What do the origin & coordinate axes represent?

[takluyver]

The origin for physical coordinates in EXtra-geom is meant to be a meaningful centre point, e.g. for azimuthal integration. But we've been a bit vague so far on what exactly that is: detector centre, the point where the beam intersects the detector plane, or the point where a ray from the interaction point would be normal to the detector plane (PyFAI's 'PONI' or Point Of Normal Incidence).

Also, should the x, y, z directions always be in the lab coordinate system (where +z is along the beam), or based on the detector, so that x & y are in the detector plane, and z only measures deviations from that plane.

When the detector is directly downstream and perpendicular to the beam, these options are equivalent, so it's not important to distinguish between them. But if a detector can be used at an angle, it will quickly become important.

I think that the most practical option is to use the PONI and coordinates based on the detector plane, so that it's always easy to see the detector layout by ignoring the z dimension. But we might want ways to translate between detector-local geometry and lab coordinates.

Prompted by discussion with @dallanto on #6.

[kirienko]

That's a really good question.

On the one hand, the PONI coordinate system is easier to maintain, since we can forget about the third Z-axis.

But on the other hand, if we want extra-geom to be compliant with CrystFEL software, we have to either use the laboratory coordinate system from the beginning, or to call some special translation function whenever we call from_crystfel_geom.

[dallanto]

Hi both, excuse my ignorance (which did not harm for my purposes so far) but I've always - weakly - assumed the z-Direction would be in the pNaN/coffset parameter for each panel, and I could ignore it in practice.
If so, wouldn't that be a deviation from the plane rather than a z in lab coords? For me, z in lab coords would mean something like the sample - pixel distance ...
But if not (if coffset is something entirely different), where would the z appear in the panel description at all?

[dallanto]

I forgot to add, I'm talking about the CrystFEL geom file here

[takluyver]

As things stand, the z coordinate of a panel corner does get translated to coffset when we write a .geom file:

EXtra-geom/extra_geom/crystfel_fmt.py

Lines 74 to 76 in ac76cc5

	corner_x=c[0],
	corner_y=c[1],
	coffset=c[2],

CrystFEL says Z is along the beam, but treating it as perpendicular to the detector plane is convenient for assembling detector images (we can ignore the Z component). So long as the detector plane is perpendicular to the beam, these are equivalent. But detectors could be positioned differently, and then it will matter.

I suspect we'll ultimately want a way to transform between instrument coordinates (z along the beam, origin at the interaction point) and detector-local coordinates (z perpendicular to the detector plane, origin at the PONI). But working out how to make that clear (given how confusing coordinates already are) and what we work with by default, won't be easy.

[dallanto]

Thanks for your partial confirmation, it gets a bit clearer now.
But, just for interest: if z is along the beam (only perpendicular to the detecor plane in the "normal" SFX case), wouldn't that definition still be based on instrument coordinates (= lab space) and hence denote the distance between the interaction point (sample) and the detector (PONI in the simple case)?
In that simple case I would expect that coffset should be equivalent (and identical) to the clenvalue, which it isn't by orders of magnitude. The magnitude of coffset made me believe it is a deviation from the detector plane instead - a PONI-based definition ... so is CrystFEL using a "hybrid" definition?

[dallanto]

Respectively: do we use a hybrid definition when writing the .geom file?

[dallanto]

Sorry I have been myself unclear. Reading your first statement, a complementary question would be: where does the z-coordinate of a panel corner come from in the first place (before translating to coffset upon .geom write-out)?

[takluyver]

But, just for interest: if z is along the beam (only perpendicular to the detecor plane in the "normal" SFX case), wouldn't that definition still be based on instrument coordinates (= lab space) and hence denote the distance between the interaction point (sample) and the detector (PONI in the simple case)?

There's a closely related question about where z=0. In EXtra-geom at present, we're saying that's in the detector plane, and considering the sample-detector distance as a separate number.

Normally, in CrystFEL .geom files you give a single number for clen, the distance from the sample to the detector plane, and then coffset is relative to that - corresponding to our z coordinate from the detector plane. But the format also allows you to put in a separate clen for each panel, if you prefer.

(.geom files also have a rail_direction, so your camera length doesn't have to be straight along the z axis - I'm ignoring that for now for the sake of simplicity. By default, it is along the z axis).

where does the z-coordinate of a panel corner come from in the first place (before translating to coffset upon .geom write-out)?

If you read in a .geom file, it comes from coffset. Geometry objects created by other methods (like .from_quad_positions()) generally set all z coordinates to 0. You can use the geom.offset() method to shift panels in the z dimension (as well as x & y).

[kirienko]

We need to make up our minds somehow, just to be consistent.

I came across this issue when I started to implement the generic from_crystfel_geom parser for GenericGeometry. And I cannot really move on with that generic parser until we resolve this issue.

[takluyver]

I would suggest that, for now, you implement the same behaviour as when we read CrystFEL geometry for a named detector like AGIPD - skip clen (I'm working on a separate branch to store & write back other fields from CrystFEL), and use coffset as the z coordinate. I.e. we're working with coordinates based on the detector plane, and making some assumptions about how that shows up in CrystFEL.

Even if this isn't the best scheme, doing the same thing for generic geometry means we can extend it in the same way later. If we do something different for generic geometry and named detectors, it will be an extra complication as and when we get round to implementing a distinction between 'lab space' and 'detector space' geometry.

[dallanto]

Ups, did not want to close the issue, just abort a comment, sorry!

[takluyver]

No problem 😄 . If you can close issues, I guess you probably have the reopen button too.

[dallanto]

Sure 😄 The actual "problem" for me was that the comment options are comment or close with comment, or if I delete all text it's comment or close issue - that is, no cancel in either case ...