NXtransformations: clarify that these are active transformations + example

[woutdenolf]

Closes #1269

Rendered version of this PR:

https://hdf5.gitlab-pages.esrf.fr/nexus/nxtransformations_active/classes/base_classes/NXtransformations.html

[phyy-nx]

Update from code camp: we are saving the active transformations. @woutdenolf will update this PR to accommodate

Example given in code camp: imagine a point detector with only one transformation, call it a rail. Here's the NXtransformations field:

rail = 10
@vector = 0, 0, 1
@offset = 0, 0, 0
@transformation_type = translation

NXdetector will depend on rail. This transformation can be written in homogenous coordinates:

1   0   0   0
0   1   0   0
0   0   1   10
0   0   0   1

Call that matrix A. The equation to move from pixel space to laboratory space (where pixel space is just 0,0,0,1 as a homogenous vector since it's a point detector):

lab space = A * pixel space = [0,0,10,1]

So the final coordinates of the detector in lab space are 0,0,10

[woutdenolf]

Updated: NXtransformations are active transformations

[woutdenolf]

@PeterC-DLS We established so far that the vector+value of an NXtransformations field describe an active transformation matrix. What still needs to be established is the order in which a reader encounters the NXtransformations fields when he follows the depends_on directives.

My interpretation was this: when we say T_1 "depends on" T_2 it means T_2 needs to be applied first before you can apply T_1.

Our description says the opposite is true: when we say T_1 "depends on" T_2 it means T_1 needs to be applied first before you can apply T_2.

Maybe it becomes more clear when connecting two NXtransformation groups. The first group is called "base" and describes the overall active transformation as a result of a stack of base motors. The second group is called "positioner" and describes the overall active transformation as a result of a stack of positioning motors. Suppose the positioning motors are physically stacked on top of the base motors. This means you first need to apply the positioning transformations and then the base transformations. In this case your description makes more sense: "positioner" depends on "base" and positioning needs to be applied before base.

So the words "depends on" can be interpreted in two ways:

1. The mathematical sense (what I described): when transformation A depends an transformation B, B needs to happen before A can happen so B needs to be applied first.
2. The stack-of-motors sense (what you described): when motor A depends on motor B, motor A is stacked on top of B and A needs to be applied first.

So @PeterC-DLS if we agree that the stack-of-motors sense (what you described) is what was intended, I will adapt the PR accordingly.

[woutdenolf]

I will also add this sentence to make the intention clear.

When we say transformation A "depends on" transformation B we mean that the physical motor that realizes A is stacked on top of the motor that realizes B. So the activate coordinate transformation A needs to be applied to a coordinate before applying B. In other words X' = B . A . X

[PeterC-DLS]

Yes, stage A depends_on stage B means A is physically and rigidly mounted on B. This is why the chain must end on . so the last stage is rigidly mounted to the laboratory.

[woutdenolf]

@PeterC-DLS You can use the rendered version t help with the review:

https://hdf5.gitlab-pages.esrf.fr/nexus/nxtransformations_active/classes/base_classes/NXtransformations.html

[PeterC-DLS]

We need to add an explanation of depends_on="." and also about using any value for a direction axis.

[yayahjb]

These definitions are based on robot arm kinematics. Please just look at a kappa goniometer a notice that omega is grounded and depends on nothing (except a possible translation stage) while phi depends on everything else.

On Wed, Jun 21, 2023 at 2:57 AM woutdenolf @.***> wrote:

@PeterC-DLS https://github.com/PeterC-DLS We established so far that the vector+value of an NXtransformations field describe an active transformation matrix. What still needs to be established is the order in which a reader encounters the NXtransformations fields when he follows the depends_on directives.

My interpretation was this: when we say T_1 "depends on" T_2 it means T_2 needs to be applied first before you can apply T_1.

Our description says the opposite is true: when we say T_1 "depends on" T_2 it means T_1 needs to be applied first before you can apply T_2.

Maybe it becomes more clear when connecting two NXtransformation groups. The first group is called "base" and describes the overall active transformation as a result of a stack of base motors. The second group is called "positioner" and describes the overall active transformation as a result of a stack of positioning motors. Suppose the positioning motors are physically stacked on top of the base motors. This means you first need to apply the positioning transformations and then the base transformations. In this case your description makes more sense: "positioner" depends on "base" and positioning needs to be applied before base.

So the words "depends on" can be interpreted in two ways:

1. The mathematical sense (what I described): when transformation A depends an transformation B, B needs to happen before A can happen so B needs to be applied first.
2. The stack-of-motors sense (what you described): when motor A depends on motor B, motor A is stacked on top of B and A needs to be applied first.

So @PeterC-DLS https://github.com/PeterC-DLS if we agree that the stack-of-motors sense (what you described) is what was intended, I will adapt the PR accordingly.

— Reply to this email directly, view it on GitHub https://github.com/nexusformat/definitions/pull/1278#issuecomment-1600286106, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABB6EAOD3X623JAV4FFXGIDXMKLPBANCNFSM6AAAAAAZJGXD4I . You are receiving this because your review was requested.Message ID: @.***>

[woutdenolf]

Code camp:

• In the example, remove the relative paths with ../ and use an absolute path
• First example must use the standard reference frame, no minus signs in the vector, using a kappa goniometer for example (https://doi.org/10.5281/zenodo.3484187)
• Second example uses an alternative reference frame

[woutdenolf]

Requested changes from https://github.com/nexusformat/definitions/pull/1278#issuecomment-1600837044 applied:

• 1 standard goniometer example in the McStas frame (based on data from the gold standard paper: https://doi.org/10.5281/zenodo.3484187)
• 1 example in a custom reference frame
• remove relative links from the examples

[woutdenolf]

@PeterC-DLS Could you write out an actual example on how you would define coordinate_system? You mentioned NXbeam a few times, but I fail to see the point. I perhaps should have chosen gravity and magnetic north or something.

[woutdenolf]

Or perhaps gravity and central axis, as in the central axis of the beamline. The direction of the beam could change in space (mirror, monochromator crystals, ...) so that's probably a bad way of defining the coordinate system.

[woutdenolf]

It also seems strange to me that an NXtransformations field without transformation_type cannot be part of a chain. What is it doing under NXtransformations then?

[PeterC-DLS]

@PeterC-DLS Could you write out an actual example on how you would define coordinate_system? You mentioned NXbeam a few times, but I fail to see the point. I perhaps should have chosen gravity and magnetic north or something.

The laboratory coordinate system used is by default McStat, when you want to use another coordinate system for the lab frame, you have to make sure your components are defined consistent to override any default assumptions. The NXbeam is assumed to be along (0,0,1) then if you were to write an NXmx (or any diffraction/scattering) application definition then you must specify the beam direction to be able to work out momentum transfer, q, correctly for any spatially resolved detected event.

Giving reference directions is mainly for documentation. Your application does not need these directions.

[sanbrock]

We support this clarification and especially the distinction between active and passive transformations, device motions/displacements and base changes for coordinate system transformations which we also discussed in Feb telco. For the later, the documentation (and/or the NXtransofmrations itself) shall be further improved, because the example of describing base changes is not so clear as it only allows defining a single axis at a time, so a transformation for a proper base change of all axes seems to be possible confusingly only in multiple steps.