The purpose of this note is to compare how pyFAI and ImageD11 treat the detector position. In particular, we derive how “PONI” detector parameters refined with pyFAI can be transformed into ImageD11 parameters.

In both packages, the transformation from pixel space to 3D laboratory coordinates is carried out in 4 steps:

• Transformation from “pixel space” to the “detector coordinate system”. The detector coordinate system is a 3D coordinate system centered on the (0,0) pixel of the detector.

• Correction for linear offsets, i.e. the position of the (0,0) pixel relative to the beam axis.

• Correction for the origin/diffractometer-to-detector distance. The sample and diffractometer center of rotation are assumed to be located at the origin.

• A series of rotations for the detector coordinate system relative to the laboratory coordinates.

Unfortunately, the conventions chosen by pyFAI and ImageD11 differ. For example, pyFAI applies the origin-to-detector distance correction before rotations, whereas ImageD11 applies it after rotations. Furthermore, they employ different coordinate systems.

Detector

We consider a pixelated 2D imaging detector. In “pixel space”, the position of a given pixel is given by the horizontal and vertical pixel numbers, \(d_H\) and \(d_V\). We assume that looking along the beam axis into the detector, \(d_H\) increases towards the right (towards the center of the synchrotron) and \(d_V\) towards the top. For clarity, we assign the unit \(\mathrm{px}\) to these coordinates.

The pixel numbers \(d_H\) and \(d_V\) are transformed into 3D “detector” coordinates by a function \(D\):

\[\begin{aligned} \vec{p} & = D\left(d_H, d_V\right).\end{aligned}\]

This function will account for the detector’s pixel size and the orientation and direction of pixel rows and columns relative to the detector coordinate system. Furthermore it may apply a distortion correction. This, however, is beyond the scope of this note.

Limiting ourselves to linear functions, \(D\) takes the form of a matrix with two columns and three rows. We will see below that the different choices of laboratory coordinate systems yield different \(D\)-matrices for pyFAI and ImageD11. We assume that the pixels have a constant horizontal and vertical size, \(\mathrm{pxsize}_H\) and \(\mathrm{pxsize}_V\). Both are given in units of length per pixel. pyFAI specifically defines the unit of length as meter, we will therefore use pixel sizes in units of \(\mathrm{m}/\mathrm{px}\) throughout this note.

The position and orientation of this detector relative to the laboratory coordinates are described below.

Geometry definition of pyFAI

Coordinates

pyFAI uses a coordinate system where the first axis (1) is vertically up (\(y\)), the second axis (2) is horizontal (\(x\)) towards the ring center (starboard), and the third axis (3) along the beam (\(z\)). Note that in this order (1, 2, 3) is a right-handed coordinate system, which makes \(xyz\) in the usual order a left-handed coordinate system!

Units

All dimensions in pyFAI are in meter and all rotation are in radians.

Parameters

pyFAI describes the position and orientation of the detector by six variables, collectively called the PONI, for point of normal incidence. In addition, a detector calibration is provided in the PONI-file to convert pixel coordinates into real-space coordinates. Here we limit our discussion to the simplest case, i.e. a pixel size as discussed above.

Rotations:

\(\theta_1\), \(\theta_2\) and \(\theta_3\) describe the detector’s orientation relative to the laboratory coordinate system.

Offsets:

\(\mathrm{poni}_1\) and \(\mathrm{poni}_2\) describe the offsets of pixel (0,0) relative to the “point of normal incidence”. In the absence of rotations the point of normal incidence is defined by the intersection of the direct beam beam axis with the detector.

Distance:

\(L\) describes the distance from the origin of the laboratory system to the point of normal incidence.

Detector

The transformation from pixel space to pyFAI detector coordinates is given by

\[\begin{split}\begin{aligned} \begin{bmatrix} p_1 \\ p_2 \\ p_3 \end{bmatrix} & = \begin{bmatrix} 0 & \mathrm{pxsize}_V \\ \mathrm{pxsize}_H & 0 \\ 0 & 0 \end{bmatrix} \cdot \begin{bmatrix} d_H \\ d_V \end{bmatrix} \\ D_{\mathtt{pyFAI}} & = \begin{bmatrix} 0 & \mathrm{pxsize}_V \\ \mathrm{pxsize}_H & 0 \\ 0 & 0 \end{bmatrix}. \label{eq-dmatrixpyFAI}\end{aligned}\end{split}\]

Offsets

The PONI parameters are: a distance \(L\), the vertical (\(y\)) and horizontal (\(x\)) coordinates of the point of normal incidence in meters, \(\mathrm{poni}_1\) and \(\mathrm{poni}_2\). The inversion of the \(x\) and \(y\) axes is due to the arrangement of the detector data, with \(x\)-rows being the “slow” axis and \(y\)-columns the “fast” axis. Extra care has to be taken with the signs of the rotations when converting form this coordinate system to another.

pyFAI applies both the offset correction and the origin-to-detector distance after the transformation from pixel space to the detector system, but before rotations,

Let \(L\) be the distance from the origin/sample/diffractometer center of rotation. In the absence of any detector rotations, \(L\) is taken along \(p_3\) (beam axis, \(z\)), \(p_1\) along the \(y\)-axis (vertical) and \(p_2\) along the \(x\)-axis (horizontal). Then the laboratory coordinates before rotation are

\[\begin{split}\begin{aligned} \begin{bmatrix} p_1 \\ p_2 \\ p_3 \end{bmatrix} & = D_{\mathtt{pyFAI}} \cdot \begin{bmatrix} d_H \\ d_V \end{bmatrix} + \begin{bmatrix} -\mathrm{poni}_1 \\ -\mathrm{poni}_2 \\ L \end{bmatrix}.\end{aligned}\end{split}\]

Rotations

The detector rotations are taken about the origin of the coordinate system (sample position). We define the following right-handed rotation matrices:

\[\begin{split}\begin{aligned} \mathrm{R}_1(\theta_1) & = \begin{bmatrix} 1 & 0 & 0 \\ 0 & \cos(\theta_1) & -\sin(\theta_1) \\ 0 & \sin(\theta_1) & \cos(\theta_1) \end{bmatrix} \label{eq-rot1} \\ \mathrm{R}_2(\theta_2) & = \begin{bmatrix} \cos(\theta_2) & 0 & \sin(\theta_2) \\ 0 & 1 & 0 \\ -\sin(\theta_2) & 0 & \cos(\theta_2) \end{bmatrix} \label{eq-rot2} \\ \mathrm{R}_3(\theta_3) & = \begin{bmatrix} \cos(\theta_3) & -\sin(\theta_3) & 0\\ \sin(\theta_3) & \cos(\theta_3) & 0\\ 0 & 0 & 1 \end{bmatrix}. \label{eq-rot3}\end{aligned}\end{split}\]

The rotations 1 and 2 in pyFAI are left handed, i.e. the sign of \(\theta_1\) and \(\theta_2\) is inverted.

The combined pyFAI rotation matrix is then

\[\begin{aligned} R_{\mathtt{pyFAI}}(\theta_1, \theta_2, \theta_3) & = R_3(\theta_3) \cdot R_2(-\theta_2) \cdot R_1(-\theta_1)\end{aligned}\]

which yields the final laboratory coordinates after rotation

\[\begin{split}\begin{aligned} \begin{bmatrix} t_1 \\ t_2 \\ t_3 \end{bmatrix} & = R_{\mathtt{pyFAI}}(\theta_1, \theta_2, \theta_3) \cdot \begin{bmatrix} p_1 \\ p_2 \\ p_3 \end{bmatrix} \label{eq-tpyFAI} \\ & = R_{\mathtt{pyFAI}}(\theta_1, \theta_2, \theta_3) \cdot \left( D_{\mathtt{pyFAI}} \cdot \begin{bmatrix} d_H \\ d_V \end{bmatrix} + \begin{bmatrix} -\mathrm{poni}_1 \\ -\mathrm{poni}_2 \\ L \end{bmatrix} \right) \\ & = R_{\mathtt{pyFAI}}(\theta_1, \theta_2, \theta_3) \cdot \left( \begin{bmatrix} 0 & \mathrm{pxsize}_V \\ \mathrm{pxsize}_H & 0 \\ 0 & 0 \end{bmatrix} \cdot \begin{bmatrix} d_H \\ d_V \end{bmatrix} + \begin{bmatrix} -\mathrm{poni}_1 \\ -\mathrm{poni}_2 \\ L \end{bmatrix} \right).\end{aligned}\end{split}\]

Inversion: Finding where a scattered beam hits the detector

For a 3DXRD-type simulation, we have to determine the pixel where a scattered ray intercepts the detector. Let \(A\) be the scattering center of a ray within a sample volume (grain, sub-grain or voxel). The Bragg condition and grain orientation pre-define the direction of the scattered beam, \(\vec{k}\). The coordinates \(A_{1,2,3}\) and \(k_{1,2,3}\) are specified in the laboratory system.

The inversion eq. [eq-tpyFAI] is straight-forward:

\[\begin{split}\begin{aligned} R_1(\theta_1)\cdot R_2(\theta_2) \cdot R_3(-\theta_3) \cdot \begin{bmatrix} t_1 \\ t_2 \\ t_3 \end{bmatrix} & = \begin{bmatrix} p_1 \\ p_2 \\ L \end{bmatrix} \label{eq-find-alpha} \\ \begin{bmatrix} t_1 \\ t_2 \\ t_3 \end{bmatrix} & = \begin{bmatrix} A_1 \\ A_2 \\ A_3 \end{bmatrix} + \alpha \begin{bmatrix} k_1 \\ k_2 \\ k_3 \end{bmatrix}.\end{aligned}\end{split}\]

The third line (\(\ldots = L\)) of eq. [eq-find-alpha] is then used to determine the free parameter \(\alpha\), which in turn is used in the first and second lines to find \(p_{1,2}\) and thus \(d_{1,2}\).

As the most trivial example we consider the case of no rotations, \(\theta_1 = \theta_2 = \theta_3 = 0\). Then

\[\begin{split}\begin{aligned} A_3 + \alpha k_3 & = L \\ \alpha & = \frac{L-A_3}{k_3} \\ p_1 & = A_1 + (L-A_3) \frac{k_1}{k_3} \\ p_2 & = A_2 + (L-A_3) \frac{k_2}{k_3}.\end{aligned}\end{split}\]

We see also that when all rotations are zero, \((\mathrm{poni}_1, \mathrm{poni_2})\) are the real space coordinates of the direct beam (\(A_{1,2,3}=k_{1,2}=0\)) .

Geometry definition of ImageD11

For maximum convenience, ImageD11 defines almost everything differently than pyFAI.

Coordinates

ImageD11 uses the ID06 coordinate system with \(x\) along the beam, \(y\) to port (away from the ring center), and \(z\) up.

Units

As the problem is somewhat scale-invariant, ImageD11 allows a free choice of the unit of length, which we will call \(X\) here. The same unit has to be used for all translations, and for the pixel size of the detector. The default used in the code appears to be \(X = 1\,\mathrm{\mu m}\), but it might as well be Planck lengths, millimeters, inches, meters, tlalcuahuitl, furlongs, nautical miles, light years, kparsec, or whatever else floats your boat. The only requirement is that you can actually measure and express the detector pixel size and COR-to-detector distance in your units of choice. Since we want to compare to pyFAI, we choose \(X=1\,\mathrm{m}\).

Rotations are given in radians.

Parameters

ImageD11 defines the detector geometry via the following parameters:

Beam center:

\(y_{\mathrm{center}}\) and \(z_{\mathrm{center}}\) define the position of the direct beam on the detector. Contrary to pyFAI, the beam center is given in pixel space, in units of \(\mathrm{px}\).

Pixel size:

The horizontal and vertical pixel size are defined by \(y_{\mathrm{size}}\) and \(z_{\mathrm{size}}\) in \({X}/{\mathrm{px}}\). With the right choice of the unit of length \(X\), these corresponds directly to the pixel sizes \(\mathrm{pxsize}_H\) and \(\mathrm{pxsize}_V\) defined above.

Detector flip matrix:

\(O = \begin{bmatrix} o_{11} & o_{12} \\ o_{21} & o_{22} \end{bmatrix}\). This matrix takes care ofcorrecting typical problems with the way pixel coordinates are arranged on the detector. If, e.g., the detector is rotated by \(90^{\circ}\), then \(O=\begin{bmatrix} 0 & 1 \\ -1 & 0\end{bmatrix}\). If left and right (or up and down) are inverted on the detector, then \(o_{22} = -1\) (\(o_{11}=-1\)).

Rotations:

Detector tilts \(t_x\), \(t_y\), and \(t_z\), in \(\mathrm{rad}\). The center of rotation is the point where the direct beam intersects the detector.

Distance:

\(\Delta\), in units \(X\), is the distance between the origin to the point where the direct beam intersects the detector. Note that this is again different from the definition of pyFAI.

It appears that these conventions where defined under the assumption that the detector is more or less centered in the direct beam, and that the detector tilts are small.

Transformation

The implementation in the code transform.py is using the following equations:

\[\begin{split}\begin{aligned} R_{\mathtt{ImageD11}}(\theta_x, \theta_y, \theta_z) & = R_1(\theta_x) \cdot R_2(\theta_y) \cdot R_3(\theta_z) \\ \begin{bmatrix} p_z \\ p_y \end{bmatrix} & = \begin{bmatrix} o_{11} & o_{12} \\ o_{21} & o_{22} \end{bmatrix} \cdot \begin{bmatrix} (d_z - z_{\mathrm{center}}) z_{\mathrm{size}} \\ (d_y - y_{\mathrm{center}}) y_{\mathrm{size}} \end{bmatrix} \label{eq-p} \\ \begin{bmatrix} t_x \\ t_y \\ t_z \end{bmatrix} & = R_{\mathtt{ImageD11}}(\theta_x, \theta_y, \theta_z) \cdot \begin{bmatrix} 0 \\ p_y \\ p_z \end{bmatrix} + \begin{bmatrix} \Delta \\ 0 \\ 0 \end{bmatrix} \label{eq-tImageD11}\end{aligned}\end{split}\]

Note that the order of \(y\) and \(z\) is not the same in eqs. [eq-p] and [eq-tImageD11].

By combining the detector flip matrix \(O\) and the pixel size into a detector \(D\) matrix, this can be written as

\[\begin{split}\begin{aligned} D_{\mathtt{ImageD11}} & = \begin{bmatrix} 0 & 0 \\ y_{\mathrm{size}} o_{22} & z_{\mathrm{size}} o_{21} \\ y_{\mathrm{size}} o_{12} & z_{\mathrm{size}} o_{11} \end{bmatrix} \label{eq-DImageD11} \\ \begin{bmatrix} p_x \\ p_y \\ p_z \end{bmatrix} & = D_{\mathtt{ImageD11}} \cdot \begin{bmatrix} d_H - y_{\mathrm{center}} \\ d_V - z_{\mathrm{center}} \end{bmatrix}\end{aligned}\end{split}\]

Conversion

Assume that the same detector geometry is described by the two notations. How can the parameters be converted from one to the other?

Detector \(D\)-matrix

The pixel size is the same in both notations, \(y_{\mathrm{size}} = \mathrm{pxsize}_H\) and \(z_{\mathrm{size}} = \mathrm{pxsize}_V\).

For a detector in its native orientation (3), \(o_{11}=1\), \(o_{22}=-1\) (because the sign of the horizontal axis is inverted between ImageD11 and pyFAI) and \(o_{12}=o_{21}=0\). For the detector setup described above, with \(d_V\) increasing to the top and \(d_H\) increasing towards the center of the synchrotron (i.e. opposite to the positive \(y\)-direction), eq. [eq-DImageD11] becomes

\[\begin{split}\begin{aligned} D_{\mathtt{ImageD11}} & = \begin{bmatrix} 0 & 0 \\ -\mathrm{pxsize}_H & 0 \\ 0 & \mathrm{pxsize}_V \end{bmatrix}. \label{eq-dmatrixImageD11}\end{aligned}\end{split}\]

Detector orientation

Since version 2023.12, pyFAI describes the position of the origin of the image with the orientation of the detector, an integer from 1 to 4 following the EXIF nomenclature, 3 being the native one. ImageD11 stores the very same information in the flip matrix \(O\), so the two are in direct correspondence: mirroring an axis changes the sign of the corresponding diagonal term, on top of the \(o_{22}=-1\) which the two axis conventions already require.

orientation	mirrored axis	\(o_{11}\)	\(o_{22}\)
1	slow and fast	\(-1\)	\(+1\)
2	slow	\(-1\)	\(-1\)
3 (native)	none	\(+1\)	\(-1\)
4	fast	\(+1\)	\(+1\)

There is however a subtlety. pyFAI mirrors the pixel index, i.e. about the center of the detector, while ImageD11 mirrors the coordinate through \(O\), i.e. about the beam center. The beam center of a mirrored axis therefore has to be re-expressed, using the number of pixels \(n_V\) and \(n_H\) of the detector:

\[\begin{split}\begin{aligned} z_{\mathrm{center}} & \rightarrow n_V - 1 - z_{\mathrm{center}} & \textrm{if the slow axis is mirrored} \\ y_{\mathrm{center}} & \rightarrow n_H - 1 - y_{\mathrm{center}} & \textrm{if the fast axis is mirrored}\end{aligned}\end{split}\]

The transposed orientations 5 to 8, which would need the off-diagonal terms of \(O\), are not supported by pyFAI.

Both formulas above are expressed in pixels, which is the natural unit of \(z_{\mathrm{center}}\) and \(y_{\mathrm{center}}\) and is also the only one ImageD11 can represent, its geometry assuming a single pixel size. The same mirroring expressed in pyFAI’s own parameters, which is what pyFAI.geometry.utils.convert_orientation() does, has to be written in meter instead, because \(\mathit{poni}_1\) and \(\mathit{poni}_2\) are distances measured from the corner of pixel (0, 0):

\[\begin{split}\begin{aligned} \mathit{poni}_1 & \rightarrow A_1 + P_1 - \mathit{poni}_1, \quad \mathit{rot}_2 \rightarrow -\mathit{rot}_2 & \textrm{if the slow axis is mirrored} \\ \mathit{poni}_2 & \rightarrow A_2 + P_2 - \mathit{poni}_2, \quad \mathit{rot}_1 \rightarrow -\mathit{rot}_1 & \textrm{if the fast axis is mirrored}\end{aligned}\end{split}\]

where \(A\) is the corner of pixel (0, 0) — the point the PONI is measured from — and \(P\) the corner the mirror maps it onto. Neither can be assumed. \(P\) is not the number of pixels times their size as soon as the pixels differ in size, since modular detectors have wider pixels along the module borders: Xpad_flat reaches 25 mm beyond the naive product along its slow axis. And \(A\) is not at the origin on a spline-corrected detector, where the corner of pixel (0, 0) is displaced like any other point of the sensor.

Both are read from the array of pixel corners by pyFAI.geometry.utils.detector_corner(). Which vertex of which pixel to read follows the mirrored axes, using the vertex numbering of get_pixel_corners — A at (i, j), B at (i+1, j), C at (i+1, j+1) and D at (i, j+1):

mirrored axis	pixel	vertex
none	(0, 0)	A
slow	(-1, 0)	B
fast	(0, -1)	D
slow and fast	(-1, -1)	C

A specific vertex has to be picked, rather than an extremum over the pixel or over the whole array: the pixels of a spline-corrected detector are distorted quadrilaterals, so nothing guarantees that the vertex which bounds the sensor is also the extreme one along a given axis. On the reference FReLoN spline the two differ by up to 6 µm.

Mirroring puts the origin of the frame exactly on the vertex used. On a spline-corrected detector — the only kind whose corner of pixel (0, 0) does not sit at the origin — converting to another orientation and back therefore does not restore the PONI exactly. That small difference is legitimate: the mirrored detector is not the same object, and only its own corner is at the origin of its own frame.

Coordinates

Both notations use the same sign for the vertical and beam axes. The sign of the horizontal transverse axis, however, is inverted.

The transformation between the different coordinate systems is then achieved by:

\[\begin{split}\begin{aligned} G & = \begin{bmatrix} 0 & 0 & 1 \\ 0 & -1 & 0 \\ 1 & 0 & 0 \end{bmatrix} \\ t_{\mathtt{ImageD11}} & = G \cdot t_{\mathtt{pyFAI}}, \label{eq-coordconv}\end{aligned}\end{split}\]

where \(t_{\mathtt{ImageD11}}\) is given by eq. [eq-tImageD11], and \(t_{\mathtt{pyFAI}}\) is given by eq. [eq-tpyFAI]. The matrix \(G\) performs the change of axes (\(x \leftrightarrow z\), \(y \leftrightarrow -y\)) and has the convenient property \(G^2 = 1\).

Substituting these equations into eq. [eq-coordconv], one can them attempt to convert pyFAI parameters into ImageD11 parameters and vice versa.

\[\begin{split}\begin{aligned} R_{\mathtt{ImageD11}} \cdot D_{\mathtt{ImageD11}} & \cdot \begin{bmatrix} d_H - y_{\mathrm{center}} \\ d_V - z_{\mathrm{center}} \end{bmatrix} + \begin{bmatrix} \Delta \\ 0 \\ 0 \end{bmatrix} \nonumber \\ = & G \cdot R_{\mathtt{pyFAI}} \cdot \left( D_{\mathtt{pyFAI}} \cdot \begin{bmatrix} d_H \\ d_V \end{bmatrix} + \begin{bmatrix} -\mathrm{poni}_1 \\ -\mathrm{poni}_2 \\ L \end{bmatrix} \right) \label{eq-transformation}\end{aligned}\end{split}\]

Rotations

Take an arbitrary vector \(d\) with \(d_{\mathtt{ImageD11}} = \begin{bmatrix} a \\ b \\ c \end{bmatrix}\). We first transform this into the pyFAI coordinate system by multiplication with \(G\), and then apply an arbitrary rotation matrix, once in before (in pyFAI coordinates, \(R_{\mathtt{pyFAI}}\)) and once after the transformation (in ImageD11 coordinates, \(R_{\mathtt{ImageD11}}\)).

\[\begin{split}\begin{aligned} d_{\mathtt{pyFAI}} & = G \cdot d_{\mathtt{ImageD11}} = \begin{bmatrix} c \\ -b \\ a \end{bmatrix} \\ R_{\mathtt{pyFAI}} \cdot d_{\mathtt{pyFAI}} & = R_{\mathtt{pyFAI}} \cdot G \cdot d_{\mathtt{ImageD11}} \\ & = G \cdot R_{\mathtt{ImageD11}} \cdot d_{\mathtt{ImageD11}}.\end{aligned}\end{split}\]

Comparing the last two lines, we find that with

\[\begin{aligned} R_{\mathtt{pyFAI}} \cdot G & = G \cdot R_{\mathtt{ImageD11}} \end{aligned}\]

the transformation is applicable for each and any vector \(d\). Because \(G^{-1} = G\) this transformation can also be applied to a series of rotations: \(G \cdot R \cdot R' = (G \cdot R \cdot G) \cdot (G \cdot R' \cdot G) \cdot G\).

Applying this to the rotations matrices defined in eqs. [eq-rot1]–[eq-rot3] shows, unsurprisingly, that this coordinate transformation is an exchange of rotation axes \(x\) and \(y\), and a change of sign for \(y\).

\[\begin{split}\begin{aligned} G \cdot R_1(\theta) \cdot G & = R_3(\theta) \\ G \cdot R_2(\theta) \cdot G & = R_2(-\theta) \\ G \cdot R_3(\theta) \cdot G & = R_1(\theta)\end{aligned}\end{split}\]

Applying this transformation to the pyFAI rotation matrix can comparing to the ImageD11 rotation matrix, we see

\[\begin{split}\begin{aligned} G \cdot R_{\mathtt{pyFAI}}(\theta_1, \theta_2, \theta_3) \cdot G & = G R_3(\theta_3) \cdot R_2(-\theta_2) \cdot R_1(-\theta_1) \cdot G \\ & = R_1(\theta_3) \cdot R_2(\theta_2) \cdot R_3(-\theta_1) \\ & = R_{\mathtt{ImageD11}}(\theta_x, \theta_y, \theta_z) \\ & = R_1(\theta_x) \cdot R_2(\theta_y) \cdot R_3(-\theta_z)\end{aligned}\end{split}\]

We find that, by divine intervention [1] and despite all the efforts to choose incompatible conventions, the effective order of rotations is actually the same between ``ImageD11`` and ``pyFAI``. Consequently, there is a direct correspondence with only a change of sign between \(\theta_z\) and \(\theta_1\):

\[\begin{split}\begin{aligned} \theta_x & = \theta_3 \label{eq-thetax} \\ \theta_y & = \theta_2 \label{eq-thetay} \\ \theta_z & = -\theta_1 \label{eq-thetaz}\end{aligned}\end{split}\]

Translations and offsets

Inserting eqs. [eq-thetax]–[eq-thetaz] into [eq-transformation], we find

\[\begin{split}\begin{aligned} \begin{bmatrix} \Delta \\ 0 \\ 0 \end{bmatrix} = & G \cdot R_{\mathtt{pyFAI}} \cdot \left( D_{\mathtt{pyFAI}} \cdot \begin{bmatrix} d_H \\ d_V \end{bmatrix} + \begin{bmatrix} -\mathrm{poni}_1 \\ -\mathrm{poni}_2 \\ L \end{bmatrix} \right) \nonumber \\ & - R_{\mathtt{ImageD11}} \cdot D_{\mathtt{ImageD11}} \cdot \begin{bmatrix} d_H - y_{\mathrm{center}} \\ d_V - z_{\mathrm{center}} \end{bmatrix} \\ = & R_{\mathtt{ImageD11}} \cdot G \cdot \left( \begin{bmatrix} \mathrm{pxsize}_V d_V \\ \mathrm{pxsize}_H d_H \\ 0 \end{bmatrix} + \begin{bmatrix} -\mathrm{poni}_1 \\ -\mathrm{poni}_2 \\ L \end{bmatrix} \right) \nonumber \\ & - R_{\mathtt{ImageD11}} \cdot \begin{bmatrix} 0 \\ -\mathrm{pxsize}_H (d_H - y_{\mathrm{center}}) \\ \mathrm{pxsize}_V (d_V - z_{\mathrm{center}}) \end{bmatrix} \\ = & R_{\mathtt{ImageD11}} \cdot \left( \begin{bmatrix} L \\ \mathrm{poni}_2 - \mathrm{pxsize}_H d_H \\ -\mathrm{poni}_1 + \mathrm{pxsize}_V d_V \end{bmatrix} - \begin{bmatrix} 0 \\ -\mathrm{pxsize}_H (d_H - y_{\mathrm{center}}) \\ \mathrm{pxsize}_V (d_V - z_{\mathrm{center}}) \end{bmatrix} \right) \\ = & R_{\mathtt{ImageD11}} \cdot \begin{bmatrix} L \\ \mathrm{poni}_2 - \mathrm{pxsize}_H y_{\mathrm{center}} \\ -\mathrm{poni}_1 + \mathrm{pxsize}_V z_{\mathrm{center}} \end{bmatrix}.\end{aligned}\end{split}\]

With a little help from our friend Mathematica, we find for the conversion from pyFAI to ImageD11

\[\begin{split}\begin{aligned} \Delta & = \frac{L}{\cos(\theta_1) \cos(\theta_2)} \\ y_{\mathrm{center}} & = \frac{1}{\mathrm{pxsize}_H} \left( \mathrm{poni}_2 - L \tan(\theta_1) \right) - \frac{1}{2} \\ z_{\mathrm{center}} & = \frac{1}{\mathrm{pxsize}_V} \left( \mathrm{poni}_1 + L \frac{\tan(\theta_2)}{\cos(\theta_1)} \right) - \frac{1}{2},\end{aligned}\end{split}\]

and for the conversion from ImageD11 to pyFAI

\[\begin{split}\begin{aligned} L & = \Delta \cos(\theta_y) \cos(\theta_z) \\ \mathrm{poni}_1 & = -\Delta \sin(\theta_y) + \mathrm{pxsize}_V \left(z_{\mathrm{center}} + \frac{1}{2}\right) \\ \mathrm{poni}_2 & = -\Delta \cos(\theta_y) \sin(\theta_z) + \mathrm{pxsize}_H \left(y_{\mathrm{center}} + \frac{1}{2}\right).\end{aligned}\end{split}\]

The half pixel in the two pairs of equations above comes from the pixel coordinate convention: in pyFAI a pixel spans \([n, n+1[\) so its center sits at \(n+1/2\), while ImageD11 counts the beam center from the center of the first pixel. On top of that, the center of a mirrored axis has to be re-expressed as described in the section on the detector orientation, the orientation being read back from the flip matrix \(O\) when converting towards pyFAI.

Azimuthal angle

The two programs do not measure the azimuth from the same axis, nor in the same direction, since the horizontal transverse axis is inverted:

\[\begin{aligned} \chi_{\mathtt{pyFAI}} & = 90^{\circ} - \eta_{\mathtt{ImageD11}}\end{aligned}\]

Both implementations, and this correspondence, are checked in pyFAI.test.test_orientation for the four orientations: the positions in the laboratory frame agree down to the numerical noise, far below the half pixel which is the meaningful scale here.

[1]

May his noodly appendages forever touch you!