Coordinate system for pyFAI.geometry.core.Geometry.calc_pos_zyx

[jadball]

What is the coordinate system that is used for the return values of pyFAI.geometry.core.Geometry.calc_pos_zyx() ? The docstring says

Calculate the 3D coordinates in the sample’s referential

which is unclear to me. Is it a right-handed or left-handed system? The return description says

3-tuple of nd-array, with dim0=along the beam, dim1=along slowest dimension dim2=along fastest dimension

How does this relate to the pyFAI geometry, as defined e.g. here:

https://pyfai.readthedocs.io/en/stable/geometry.html#geometry

Thanks!

[kif]

zyx and yxz are both right-handed

[jadball]

I'm confused. In the pyFAI docs, you specify this:

• Axis 1 (i.e. y) being vertical, pointing upwards
• Axis 2 (i.e. x) being horizontal, pointing to the center of the storage ring
• Axis 3 (i.e. z) being horizontal, along the incident beam

This would imply a left-handed coordinate system which matches the image on the page.

[kif]

The direction of X is for ESRF ..., but unless I am mistaken, this makes a right-handed coordinate system.

[jadball]

I am pretty sure the configuration I mentioned is left-handed. If you pointed axis 2 away from the storage ring, it would be right-handed. Could you possibly draw the configuration used by pyFAI.geometry.core.Geometry.calc_pos_zyx() so that I can verify it?

[kif]

Small comment ... the documentation on readthedocs is for CI only. Stable documentation are available at silx.org:

http://www.silx.org/doc/pyFAI/latest/geometry.html#geometry

(d1,d2, d3) and (x1, x2, x3) as well as (x3, x1, x2) aka (z,y,x) are all right handed. But you are right (x,y,z) is left handed in this configuration.

About orientation of detectors ... @loichuder is working on something related in #2868. Can you validate the orientation he is giving ?

[jadball]

In order to validate the conversions, I think we need unambigous functions in pyFAI that can clearly tell us the lab coordinates, given image pixel indices. Unfortunately, it remains unclear to me exactly what the coordinate system is for pyFAI.geometry.core.Geometry.calc_pos_zyx(). Until we have functions with extremely clear definitions for what system they return in, I fear that we will be unable to write unit tests to tackle this problem properly.

[kif]

There is another difference between the flipping, as performed in ImageD11 (mutiplication with a matrix of 0, -1 and +1) and in pyFAI where the image remains in place, so this implies modifications of the translation, at least in the plan (PONI1, PONI2).

[kif]

If you read this thread, you can have a look at this PR which is about the same topic: #2911

[NaNIsaac]

I checked this numerically against pyFAI 2026.9.0, since the figure alone kept the question open.

What calc_pos_zyx returns: (z, y, x) in metres, in a frame centred on the sample.
z is along the incident beam (it equals dist at the PONI for zero rotations); y and x
are the detector's in-plane axes at zero rotation. (z, y, x) is right-handed (ẑ × ŷ = x̂),
so the same axes written as (x, y, z) are left-handed, which is where you and @kif ended up.

It is also the frame pyFAI's own angles are computed in. For a tilted geometry
(rot1=0.05, rot2=-0.03, rot3=0.02), arctan2(hypot(x, y), z) == g.tth(d1, d2) and
arctan2(y, x) == g.chi(d1, d2) hold exactly.

Pixel indices → axes depends on detector.orientation (default 3):

orientation	+1 row (d1)	+1 column (d2)
1	−y	−x
2	−y	+x
3 (default)	+y	+x
4	+y	−x

Lab directions: only z is tied to the lab. If the detector is mounted so that +y points
up, right-handedness gives x̂ = ẑ × ŷ, i.e. +x points to the right when looking downstream
(sample → detector). Whether that is towards or away from the ring centre depends on which
side of the ring the beamline is on, which is why the two readings of the docs disagree.

import numpy as np
from pyFAI.detectors import Detector
from pyFAI.geometry import Geometry

for o in (1, 2, 3, 4):
    det = Detector(pixel1=1e-4, pixel2=1e-4, max_shape=(100, 100), orientation=o)
    g = Geometry(dist=0.1, poni1=5e-3, poni2=5e-3, detector=det)
    z, y, x = g.calc_pos_zyx(d1=np.array([50., 51., 50.]), d2=np.array([50., 50., 51.]))
    p = np.stack([z, y, x], 1)
    print(o, "+row:", np.round((p[1] - p[0]) / 1e-4, 3), "+col:", np.round((p[2] - p[0]) / 1e-4, 3))

g = Geometry(dist=0.1, poni1=5e-3, poni2=5e-3, rot1=0.05, rot2=-0.03, rot3=0.02,
             detector=Detector(pixel1=1e-4, pixel2=1e-4, max_shape=(100, 100)))
d1, d2 = np.array([10., 80., 30.]), np.array([70., 20., 90.])
z, y, x = g.calc_pos_zyx(d1=d1, d2=d2)
print(np.allclose(np.arctan2(np.hypot(x, y), z), g.tth(d1, d2)),
      np.allclose(np.arctan2(y, x), g.chi(d1, d2)))