Rename axes in XY projections, or show decreasing X instead of flipping X coord

[SimonHeybrock]

Currently detector XY-projections treat x as right as seen from the sample (provided flip_x option is set correctly). This could be confusing for anyone thinking of this as the x in the instrument coord system.

Option 1:

• Rename x->right
• Rename y -> up

Option 2:

• Show x with decreasing coord - flip_x mechanism should be replaced by a simple flip of the result image instead.

[SimonHeybrock]

Thinking about this more, I believe the naming is not just confusing but actually underspecified: x and y only identify instrument-frame axes once you've also fixed z (the viewing direction / projection plane). The XY-projection isn't really "instrument x and y"; it's "the two axes orthogonal to the chosen viewing direction."

• For a detector viewed from the sample along an axis-aligned direction, the projection axes happen to coincide with instrument x/y up to a sign — but this is a special case.
• For a different viewing direction, or a non-axis-aligned detector, the projection axes are linear combinations of instrument x/y/z, and calling them x/y is simply wrong.
• Even in the aligned case, "right" depends on where the viewer is standing (sample side vs. behind the detector). That's exactly why flip_x exists — the flag is a symptom of the naming being underspecified, not a fix for it.

This pushes me toward Option 1 (right/up), and a bit further: once the projection definition picks the viewing direction, right/up follow unambiguously and flip_x should be able to disappear entirely (folded into the projection definition).

Option 2 (decreasing x) doesn't address any of this — it still pretends there's a canonical x.

[SimonHeybrock]

Related: the same kind of naming trap exists, in milder form, for the cylinder_mantle_z projection. It produces phi, arc_length, r, and z, where z is the position of the projected point on the cylinder mantle, not the voxel's own z (the projection scales position.z by radius / r_xy). Calling it z invites the reader to identify it with instrument-frame voxel z, which it isn't.

phi and arc_length are fine — they are properties of the projected point and there is no plausible alternative reading. The issue is only with z.

Suggested rename: z → beam. Reasons:

• It is a semantic label (position along the beam axis) rather than a coordinate-system label, so it doesn't smuggle in any claim about where the sample sits or what physics is happening — it stays a pure geometric coord, which is what the projection actually computes.
• It pairs naturally with phi: (beam, phi) reads as cylindrical coordinates around the beam axis, which is exactly what project_onto_cylinder_z computes.
• It dodges the voxel-vs-projected-z confusion by not invoking instrument-frame z at all.
• Unlike a physics-flavoured name such as two_theta, it doesn't bake in a sample-at-origin / scattering-angle interpretation, so it remains honest in non-diffraction contexts.

Reference point (where beam = 0) should be documented in the projection docstring.

Footnote — spherical projection: if what users actually want for diffraction is the scattering angle, the cleanest answer is not to rename z to two_theta inside cylinder-mantle (which would be a half-fix, since cylinder-mantle is then a roundabout way to compute spherical coords), but to add a separate spherical projection producing (two_theta, phi) directly. That's a feature, not a rename, and orthogonal to this issue — noting it here so we don't lose track.