From a44e7894fc4ee054a43ccefe6c4233328cbd8aec Mon Sep 17 00:00:00 2001 From: Florian Dobener Date: Tue, 9 Jan 2024 17:15:46 +0100 Subject: [PATCH 01/37] Updates NXtransformations docs (#114) * Updates NXtransformations docs * Manually set to lower case true * Do a forward-backward nyaml cycle for NXtransformations # Conflicts: # base_classes/nyaml/NXtransformations.yaml --- base_classes/NXtransformations.nxdl.xml | 191 +++++++++++++++++++++--- 1 file changed, 173 insertions(+), 18 deletions(-) diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index c8337ce725..667aa92e1a 100644 --- a/base_classes/NXtransformations.nxdl.xml +++ b/base_classes/NXtransformations.nxdl.xml @@ -55,23 +55,42 @@ * ``NX_UNITLESS`` for axes for which no transformation type is specified This class will usually contain all axes of a sample stage or goniometer or - a detector. The NeXus default McSTAS coordinate frame is assumed, but additional - useful coordinate axes may be defined by using axes for which no transformation - type has been specified. + a detector. The NeXus default :ref:`McSTAS coordinate frame<Design-CoordinateSystem>` + is assumed, but additional useful coordinate axes may be defined by using axes for which + no transformation type has been specified. - The entry point (``depends_on``) will be outside of this class and point to a - field in here. Following the chain may also require following ``depends_on`` - links to transformations outside, for example to a common base table. If - a relative path is given, it is relative to the group enclosing the ``depends_on`` - specification. + **Transformation chain** + + The entry point of a chain of transformations is a field called ``depends_on`` + will be outside of this class and points to a field in here. Following the chain may + also require following ``depends_on`` links to transformations outside, for example + to a common base table. If a relative path is given, it is relative to the group + enclosing the ``depends_on`` specification. For a chain of three transformations, where :math:`T_1` depends on :math:`T_2` - and that in turn depends on :math:`T_3`, the final transformation :math:`T_f` is + which in turn depends on :math:`T_3`, the final *active* transformation + matrix :math:`T_f` is + + .. math:: T_f = T_3 . T_2 . T_1 + + For example when positioning a flat detector, its pixel positions in the laboratory + reference frame (:ref:`McSTAS coordinate frame<Design-CoordinateSystem>` by default) + can be calculated by + + .. math:: X_\text{lab} = T_f . X_\text{pixel} = T_3 . T_2 . T_1 . X_\text{pixel} - .. math:: T_f = T_3 T_2 T_1 + Note that :math:`T_1` comes first in the *depends-on* chain and is also applied first + to the pixel coordinates. - In explicit terms, the transformations are a subset of affine transformations - expressed as 4x4 matrices that act on homogeneous coordinates, :math:`w=(x,y,z,1)^T`. + When we say transformation :math:`A` *depends on* transformation :math:`B` we mean that + the physical motor that realizes :math:`A` is *stacked on top of* the motor that realizes :math:`B`. + So the activate coordinate transformation :math:`A` needs to be applied to a coordinate + before applying :math:`B`. In other words :math:`X' = B . A . X`. + + **Transformation matrix** + + In explicit terms, the transformations are a subset of affine transformations expressed as + 4x4 active transformation matrices that act on homogeneous coordinates, :math:`X=[x,y,z,1]^T`. For rotation and translation, @@ -85,8 +104,8 @@ attribute multiplied by the field value, and :math:`R` is defined as a rotation about an axis in the direction of ``vector``, of angle of the field value. - NOTE - + **Usage** + One possible use of ``NXtransformations`` is to define the motors and transformations for a diffractometer (goniometer). Such use is mentioned in the ``NXinstrument`` base class. Use one ``NXtransformations`` group @@ -94,8 +113,7 @@ Collecting the motors of a sample table or xyz-stage in an NXtransformations group is equally possible. - - Following the section on the general dscription of axis in NXtransformations is a section which + Following the section on the general description of axis in NXtransformations is a section which documents the fields commonly used within NeXus for positioning purposes and their meaning. Whenever there is a need for positioning a beam line component please use the existing names. Use as many fields as needed in order to position the component. Feel free to add more axis if required. In the description @@ -108,6 +126,143 @@ * depends_on as needed. + + **Example 1: goniometer** + + Position a sample mounted on a goniometer in the :ref:`McSTAS coordinate frame<Design-CoordinateSystem>`. + + The sample is oriented as follows + + .. math:: X_\text{lab} = R(\vec{v}_\omega, \omega) . + T(\vec{v}_z, \text{sam}_z) . + T(\vec{v}_y, \text{sam}_y) . + T(\vec{v}_x, \text{sam}_x) . + R(\vec{v}_\chi, \chi) . + R(\vec{v}_\varphi, \varphi) . X_s + + where + + * :math:`R(\vec{v},a)` is a rotation around vector :math:`\vec{v}` with angle :math:`a` + * :math:`T(\vec{u},t)` is a translation along vector :math:`\vec{u}` over a distance :math:`t` + * :math:`X_s` a coordinate in the sample reference frame. + + .. code-block:: + + entry:NXentry + sample:NXsample + depends_on=transformations/phi + transformations:NXtransformations + phi=0 + @depends_on=chi + @transformation_type=rotation + @vector=[-1 -0.0037 -0.002] + @units=degrees + chi=0 + @depends_on=sam_x + @transformation_type=rotation + @vector=[0.0046 0.0372 0.9993] + @units=degrees + sam_x=0 + @depends_on=sam_y + @transformation_type=translation + @vector=[1 0 0] + @units=mm + sam_y=0 + @depends_on=sam_z + @transformation_type=translation + @vector=[0 1 0] + @units=mm + sam_z=0 + @depends_on=omega + @transformation_type=translation + @vector=[0 0 1] + @units=mm + omega=174 + @depends_on=. + @transformation_type=rotation + @vector=[-1 0 0] + @units=degrees + + **Example 2: different coordinate system** + + Define a laboratory reference frame with the X-axis along the beam and the Z-axis opposite to the direction of gravity. + Three point detectors are positioned in this reference: + + * *transmission*: + * point detector in the beam + * 20 cm downstream from the sample (the origin of the reference frame) + * *vertical*: + * point detector 10 cm downstream from the sample + * making an angle of 5 degrees with the beam w.r.t. the sample + * positioned in the XZ-plane above the XY-plane + * *horizontal*: + * point detector 11 cm downstream from the sample + * making an angle of 6 degrees with the beam w.r.t. the sample + * positioned in the XY-plane above the XZ-plane + + The coordinates of the point detectors in the laboratory reference frame are + + * *transmission*: :math:`X_\text{lab} = T_x(20) . X_d` + * *vertical*: :math:`X_\text{lab} = R_y(-5) . T_x(10) . X_d` + * *horizontal*: :math:`X_\text{lab} = R_x(-90) . R_y(-6) . T_x(11) . X_d` + + where + + * :math:`T_x`, :math:`T_y`, :math:`T_z`: active transformation matrices for translation along the X, Y and Z axes + * :math:`R_x`, :math:`R_y`, :math:`R_z`: active transformation matrices for rotation around the X, Y and Z axes + * :math:`X_d` is a coordinate in the detector reference frame. + + Note that as these are point detectors, we only have one coordinate :math:`X_d=[0,0,0,1]^T`. + + .. code-block:: + + entry:NXentry + instrument:NXinstrument + vertical:NXdetector + depends_on=position/distance + position:NXtransformations + distance=10 # move downstream from the sample + @depends_on=polar + @units=cm + @vector=[1 0 0] + polar=5 # title above the horizontal plane + @depends_on=azimuth + @units=degrees + @vector=[0 -1 0] + azimuth=0 # stay in the vertical plane + @depends_on=/entry/coordinate_system/beam + @units=degrees + @vector=[-1 0 0] + horizontal:NXdetector + depends_on=position/distance + position:NXtransformations + distance=11 # move downstream from the sample + @depends_on=polar + @units=cm + @vector=[1 0 0] + polar=6 # title above the horizontal plane + @depends_on=azimuth + @units=degrees + @vector=[0 -1 0] + azimuth=90 # rotate to the horizontal plane + @depends_on=/entry/coordinate_system/beam + @units=degrees + @vector=[-1 0 0] + transmission:NXdetector + depends_on=position/distance + position:NXtransformations + distance=20 # move downstream from the sample + @depends_on=/entry/coordinate_system/beam + @units=cm + @vector=[1 0 0] + coordinate_system:NXtransformations + beam=NaN # value is never used + @depends_on=gravity + @vector=[1 0 0] # X-axis points in the beam direction + gravity=NaN # value is never used + @depends_on=. # end of the chain + @vector=[0 0 -1] # Z-axis points up + @@ -171,7 +326,7 @@ Points to the path to a field defining the axis on which this - depends or the string ".". + depends or the string "." when at the end of the chain. @@ -218,4 +373,4 @@ for a summary of the discussion. - + \ No newline at end of file From 14276943f77c93bc549a7ceb5b6313585d9870bc Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Tue, 9 Jan 2024 16:02:44 +0100 Subject: [PATCH 02/37] change @depends_on docstring in NXtransformations # Conflicts: # base_classes/nyaml/NXtransformations.yaml --- base_classes/NXtransformations.nxdl.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index 667aa92e1a..ee4791a4cf 100644 --- a/base_classes/NXtransformations.nxdl.xml +++ b/base_classes/NXtransformations.nxdl.xml @@ -326,7 +326,8 @@ Points to the path to a field defining the axis on which this - depends or the string "." when at the end of the chain. + depends or the string ".". It can also point to an instance of + ``NX_coordinate_system`` if this transformation depends on it. From b1c770e8b15e39460eb44c35662a49bd0e084462 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Fri, 12 Jan 2024 12:21:18 +0100 Subject: [PATCH 03/37] clarify docstring in NXtransformations depends_on attribute # Conflicts: # base_classes/nyaml/NXtransformations.yaml --- base_classes/NXtransformations.nxdl.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index ee4791a4cf..93ec8ac8f4 100644 --- a/base_classes/NXtransformations.nxdl.xml +++ b/base_classes/NXtransformations.nxdl.xml @@ -325,8 +325,8 @@ - Points to the path to a field defining the axis on which this - depends or the string ".". It can also point to an instance of + Points to the path of a field defining the axis on which this instance of + NXtransformations depends or the string ".". It can also point to an instance of ``NX_coordinate_system`` if this transformation depends on it. @@ -358,7 +358,7 @@ the corresponding axis moves during the exposure of a frame. Ideally, the value of this field added to each value of ``AXISNAME`` would agree with the corresponding values of ``AXISNAME_end``, but there is a possibility of significant - differences. Use of ``AXISNAME_end`` is recommended. + differences. Use of ``AXISNAME_end`` is recommended. From 03c0ece4270ad7a66bc894f697293785129af619 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Wed, 3 Jul 2024 14:48:19 +0200 Subject: [PATCH 04/37] regenerate nxdl files # Conflicts: # base_classes/NXtransformations.nxdl.xml # base_classes/nyaml/NXtransformations.yaml --- base_classes/NXtransformations.nxdl.xml | 695 ++++++++++++------------ 1 file changed, 341 insertions(+), 354 deletions(-) diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index 93ec8ac8f4..bfbed37436 100644 --- a/base_classes/NXtransformations.nxdl.xml +++ b/base_classes/NXtransformations.nxdl.xml @@ -1,10 +1,10 @@ - - + + - - - - Collection of axis-based translations and rotations to describe a geometry. - May also contain axes that do not move and therefore do not have a transformation - type specified, but are useful in understanding coordinate frames within which - transformations are done, or in documenting important directions, such as the - direction of gravity. - - A nested sequence of transformations lists the translation and rotation steps - needed to describe the position and orientation of any movable or fixed device. - - There will be one or more transformations (axes) defined by one or more fields - for each transformation. Transformations can also be described by NXlog groups when - the values change with time. The all-caps name ``AXISNAME`` designates the - particular axis generating a transformation (e.g. a rotation axis or a translation - axis or a general axis). The attribute ``units="NX_TRANSFORMATION"`` designates the - units will be appropriate to the ``transformation_type`` attribute: - - * ``NX_LENGTH`` for ``translation`` - * ``NX_ANGLE`` for ``rotation`` - * ``NX_UNITLESS`` for axes for which no transformation type is specified - - This class will usually contain all axes of a sample stage or goniometer or - a detector. The NeXus default :ref:`McSTAS coordinate frame<Design-CoordinateSystem>` - is assumed, but additional useful coordinate axes may be defined by using axes for which - no transformation type has been specified. - - **Transformation chain** - - The entry point of a chain of transformations is a field called ``depends_on`` - will be outside of this class and points to a field in here. Following the chain may - also require following ``depends_on`` links to transformations outside, for example - to a common base table. If a relative path is given, it is relative to the group - enclosing the ``depends_on`` specification. - - For a chain of three transformations, where :math:`T_1` depends on :math:`T_2` - which in turn depends on :math:`T_3`, the final *active* transformation - matrix :math:`T_f` is - - .. math:: T_f = T_3 . T_2 . T_1 - - For example when positioning a flat detector, its pixel positions in the laboratory - reference frame (:ref:`McSTAS coordinate frame<Design-CoordinateSystem>` by default) - can be calculated by - - .. math:: X_\text{lab} = T_f . X_\text{pixel} = T_3 . T_2 . T_1 . X_\text{pixel} - - Note that :math:`T_1` comes first in the *depends-on* chain and is also applied first - to the pixel coordinates. - - When we say transformation :math:`A` *depends on* transformation :math:`B` we mean that - the physical motor that realizes :math:`A` is *stacked on top of* the motor that realizes :math:`B`. - So the activate coordinate transformation :math:`A` needs to be applied to a coordinate - before applying :math:`B`. In other words :math:`X' = B . A . X`. - - **Transformation matrix** - - In explicit terms, the transformations are a subset of affine transformations expressed as - 4x4 active transformation matrices that act on homogeneous coordinates, :math:`X=[x,y,z,1]^T`. - - For rotation and translation, - - .. math:: T_r &= \begin{pmatrix} R & o \\ 0_3 & 1 \end{pmatrix} \\ T_t &= \begin{pmatrix} I_3 & t + o \\ 0_3 & 1 \end{pmatrix} - - where :math:`R` is the usual 3x3 rotation matrix, :math:`o` is an offset vector, - :math:`0_3` is a row of 3 zeros, :math:`I_3` is the 3x3 identity matrix and - :math:`t` is the translation vector. - - :math:`o` is given by the ``offset`` attribute, :math:`t` is given by the ``vector`` - attribute multiplied by the field value, and :math:`R` is defined as a rotation - about an axis in the direction of ``vector``, of angle of the field value. - - **Usage** - - One possible use of ``NXtransformations`` is to define the motors and - transformations for a diffractometer (goniometer). Such use is mentioned - in the ``NXinstrument`` base class. Use one ``NXtransformations`` group - for each diffractometer and name the group appropriate to the device. - Collecting the motors of a sample table or xyz-stage in an NXtransformations - group is equally possible. - - Following the section on the general description of axis in NXtransformations is a section which - documents the fields commonly used within NeXus for positioning purposes and their meaning. Whenever - there is a need for positioning a beam line component please use the existing names. Use as many fields - as needed in order to position the component. Feel free to add more axis if required. In the description - given below, only those atttributes which are defined through the name are spcified. Add the other attributes - of the full set: - - * vector - * offset - * transformation_type - * depends_on - - as needed. - - **Example 1: goniometer** - - Position a sample mounted on a goniometer in the :ref:`McSTAS coordinate frame<Design-CoordinateSystem>`. - - The sample is oriented as follows - - .. math:: X_\text{lab} = R(\vec{v}_\omega, \omega) . - T(\vec{v}_z, \text{sam}_z) . - T(\vec{v}_y, \text{sam}_y) . - T(\vec{v}_x, \text{sam}_x) . - R(\vec{v}_\chi, \chi) . - R(\vec{v}_\varphi, \varphi) . X_s - - where - - * :math:`R(\vec{v},a)` is a rotation around vector :math:`\vec{v}` with angle :math:`a` - * :math:`T(\vec{u},t)` is a translation along vector :math:`\vec{u}` over a distance :math:`t` - * :math:`X_s` a coordinate in the sample reference frame. - - .. code-block:: - - entry:NXentry - sample:NXsample - depends_on=transformations/phi - transformations:NXtransformations - phi=0 - @depends_on=chi - @transformation_type=rotation - @vector=[-1 -0.0037 -0.002] - @units=degrees - chi=0 - @depends_on=sam_x - @transformation_type=rotation - @vector=[0.0046 0.0372 0.9993] - @units=degrees - sam_x=0 - @depends_on=sam_y - @transformation_type=translation - @vector=[1 0 0] - @units=mm - sam_y=0 - @depends_on=sam_z - @transformation_type=translation - @vector=[0 1 0] - @units=mm - sam_z=0 - @depends_on=omega - @transformation_type=translation - @vector=[0 0 1] - @units=mm - omega=174 - @depends_on=. - @transformation_type=rotation - @vector=[-1 0 0] - @units=degrees - - **Example 2: different coordinate system** - - Define a laboratory reference frame with the X-axis along the beam and the Z-axis opposite to the direction of gravity. - Three point detectors are positioned in this reference: - - * *transmission*: - * point detector in the beam - * 20 cm downstream from the sample (the origin of the reference frame) - * *vertical*: - * point detector 10 cm downstream from the sample - * making an angle of 5 degrees with the beam w.r.t. the sample - * positioned in the XZ-plane above the XY-plane - * *horizontal*: - * point detector 11 cm downstream from the sample - * making an angle of 6 degrees with the beam w.r.t. the sample - * positioned in the XY-plane above the XZ-plane - - The coordinates of the point detectors in the laboratory reference frame are - - * *transmission*: :math:`X_\text{lab} = T_x(20) . X_d` - * *vertical*: :math:`X_\text{lab} = R_y(-5) . T_x(10) . X_d` - * *horizontal*: :math:`X_\text{lab} = R_x(-90) . R_y(-6) . T_x(11) . X_d` - - where - - * :math:`T_x`, :math:`T_y`, :math:`T_z`: active transformation matrices for translation along the X, Y and Z axes - * :math:`R_x`, :math:`R_y`, :math:`R_z`: active transformation matrices for rotation around the X, Y and Z axes - * :math:`X_d` is a coordinate in the detector reference frame. - - Note that as these are point detectors, we only have one coordinate :math:`X_d=[0,0,0,1]^T`. - - .. code-block:: - - entry:NXentry - instrument:NXinstrument - vertical:NXdetector - depends_on=position/distance - position:NXtransformations - distance=10 # move downstream from the sample - @depends_on=polar - @units=cm - @vector=[1 0 0] - polar=5 # title above the horizontal plane - @depends_on=azimuth - @units=degrees - @vector=[0 -1 0] - azimuth=0 # stay in the vertical plane - @depends_on=/entry/coordinate_system/beam - @units=degrees - @vector=[-1 0 0] - horizontal:NXdetector - depends_on=position/distance - position:NXtransformations - distance=11 # move downstream from the sample - @depends_on=polar - @units=cm - @vector=[1 0 0] - polar=6 # title above the horizontal plane - @depends_on=azimuth - @units=degrees - @vector=[0 -1 0] - azimuth=90 # rotate to the horizontal plane - @depends_on=/entry/coordinate_system/beam - @units=degrees - @vector=[-1 0 0] - transmission:NXdetector - depends_on=position/distance - position:NXtransformations - distance=20 # move downstream from the sample - @depends_on=/entry/coordinate_system/beam - @units=cm - @vector=[1 0 0] - coordinate_system:NXtransformations - beam=NaN # value is never used - @depends_on=gravity - @vector=[1 0 0] # X-axis points in the beam direction - gravity=NaN # value is never used - @depends_on=. # end of the chain - @vector=[0 0 -1] # Z-axis points up - - - - - Units need to be appropriate for translation or rotation - - The name of this field is not forced. The user is free to use any name - that does not cause confusion. When using more than one ``AXISNAME`` field, - make sure that each field name is unique in the same group, as required - by HDF5. - - The values given should be the start points of exposures for the corresponding - frames. The end points should be given in ``AXISNAME_end``. - - - - The transformation_type may be ``translation``, in which case the - values are linear displacements along the axis, ``rotation``, - in which case the values are angular rotations around the axis. - - If this attribute is omitted, this is an axis for which there - is no motion to be specifies, such as the direction of gravity, - or the direction to the source, or a basis vector of a - coordinate frame. In this case the value of the ``AXISNAME`` field - is not used and can be set to the number ``NaN``. - - - - - - - - - - Three values that define the axis for this transformation. - The axis should be normalized to unit length, making it - dimensionless. For ``rotation`` axes, the direction should be - chosen for a right-handed rotation with increasing angle. - For ``translation`` axes the direction should be chosen for - increasing displacement. For general axes, an appropriate direction - should be chosen. - - - - - - - - A fixed offset applied before the transformation (three vector components). - This is not intended to be a substitute for a fixed ``translation`` axis but, for example, - as the mechanical offset from mounting the axis to its dependency. - - - - - - - - Units of the offset. Values should be consistent with NX_LENGTH. - - - - - Points to the path of a field defining the axis on which this instance of - NXtransformations depends or the string ".". It can also point to an instance of - ``NX_coordinate_system`` if this transformation depends on it. - - - - - An arbitrary identifier of a component of the equipment to which - the transformation belongs, such as 'detector_arm' or 'detector_module'. - NXtransformations with the same equipment_component label form a logical - grouping which can be combined together into a single change-of-basis - operation. - - - - - - ``AXISNAME_end`` is a placeholder for a name constructed from the actual - name of an axis to which ``_end`` has been appended. - - The values in this field are the end points of the motions that start - at the corresponding positions given in the ``AXISNAME`` field. - - - - - ``AXISNAME_increment_set`` is a placeholder for a name constructed from the actual - name of an axis to which ``_increment_set`` has been appended. - - The value of this optional field is the intended average range through which - the corresponding axis moves during the exposure of a frame. Ideally, the - value of this field added to each value of ``AXISNAME`` would agree with the - corresponding values of ``AXISNAME_end``, but there is a possibility of significant - differences. Use of ``AXISNAME_end`` is recommended. - - + + + Collection of axis-based translations and rotations to describe a geometry. + May also contain axes that do not move and therefore do not have a transformation + type specified, but are useful in understanding coordinate frames within which + transformations are done, or in documenting important directions, such as the + direction of gravity. + + A nested sequence of transformations lists the translation and rotation steps + needed to describe the position and orientation of any movable or fixed device. + + There will be one or more transformations (axes) defined by one or more fields + for each transformation. Transformations can also be described by NXlog groups when + the values change with time. The all-caps name ``AXISNAME`` designates the + particular axis generating a transformation (e.g. a rotation axis or a translation + axis or a general axis). The attribute ``units="NX_TRANSFORMATION"`` designates the + units will be appropriate to the ``transformation_type`` attribute: + + * ``NX_LENGTH`` for ``translation`` + * ``NX_ANGLE`` for ``rotation`` + * ``NX_UNITLESS`` for axes for which no transformation type is specified + + This class will usually contain all axes of a sample stage or goniometer or + a detector. The NeXus default :ref:`McSTAS coordinate frame<Design-CoordinateSystem>` + is assumed, but additional useful coordinate axes may be defined by using axes for which + no transformation type has been specified. + + **Transformation chain** + + The entry point of a chain of transformations is a field called ``depends_on`` + will be outside of this class and points to a field in here. Following the chain may + also require following ``depends_on`` links to transformations outside, for example + to a common base table. If a relative path is given, it is relative to the group + enclosing the ``depends_on`` specification. + + For a chain of three transformations, where :math:`T_1` depends on :math:`T_2` + which in turn depends on :math:`T_3`, the final *active* transformation + matrix :math:`T_f` is + + .. math:: T_f = T_3 . T_2 . T_1 + + For example when positioning a flat detector, its pixel positions in the laboratory + reference frame (:ref:`McSTAS coordinate frame<Design-CoordinateSystem>` by default) + can be calculated by + + .. math:: X_\text{lab} = T_f . X_\text{pixel} = T_3 . T_2 . T_1 . X_\text{pixel} + + Note that :math:`T_1` comes first in the *depends-on* chain and is also applied first + to the pixel coordinates. + + When we say transformation :math:`A` *depends on* transformation :math:`B` we mean that + the physical motor that realizes :math:`A` is *stacked on top of* the motor that realizes :math:`B`. + So the activate coordinate transformation :math:`A` needs to be applied to a coordinate + before applying :math:`B`. In other words :math:`X' = B . A . X`. + + **Transformation matrix** + + In explicit terms, the transformations are a subset of affine transformations expressed as + 4x4 active transformation matrices that act on homogeneous coordinates, :math:`X=[x,y,z,1]^T`. + + For rotation and translation, + + .. math:: T_r &= \begin{pmatrix} R & o \\ 0_3 & 1 \end{pmatrix} \\ T_t &= \begin{pmatrix} I_3 & t + o \\ 0_3 & 1 \end{pmatrix} + + where :math:`R` is the usual 3x3 rotation matrix, :math:`o` is an offset vector, + :math:`0_3` is a row of 3 zeros, :math:`I_3` is the 3x3 identity matrix and + :math:`t` is the translation vector. + + :math:`o` is given by the ``offset`` attribute, :math:`t` is given by the ``vector`` + attribute multiplied by the field value, and :math:`R` is defined as a rotation + about an axis in the direction of ``vector``, of angle of the field value. + + **Usage** + + One possible use of ``NXtransformations`` is to define the motors and + transformations for a diffractometer (goniometer). Such use is mentioned + in the ``NXinstrument`` base class. Use one ``NXtransformations`` group + for each diffractometer and name the group appropriate to the device. + Collecting the motors of a sample table or xyz-stage in an NXtransformations + group is equally possible. + + Following the section on the general description of axis in NXtransformations is a section which + documents the fields commonly used within NeXus for positioning purposes and their meaning. Whenever + there is a need for positioning a beam line component please use the existing names. Use as many fields + as needed in order to position the component. Feel free to add more axis if required. In the description + given below, only those atttributes which are defined through the name are spcified. Add the other attributes + of the full set: + + * vector + * offset + * transformation_type + * depends_on + + as needed. + + **Example 1: goniometer** + + Position a sample mounted on a goniometer in the :ref:`McSTAS coordinate frame<Design-CoordinateSystem>`. + + The sample is oriented as follows + + .. math:: X_\text{lab} = R(\vec{v}_\omega, \omega) . + T(\vec{v}_z, \text{sam}_z) . + T(\vec{v}_y, \text{sam}_y) . + T(\vec{v}_x, \text{sam}_x) . + R(\vec{v}_\chi, \chi) . + R(\vec{v}_\varphi, \varphi) . X_s + + where + + * :math:`R(\vec{v},a)` is a rotation around vector :math:`\vec{v}` with angle :math:`a` + * :math:`T(\vec{u},t)` is a translation along vector :math:`\vec{u}` over a distance :math:`t` + * :math:`X_s` a coordinate in the sample reference frame. + + .. code-block:: + + entry:NXentry + sample:NXsample + depends_on=transformations/phi + transformations:NXtransformations + phi=0 + @depends_on=chi + @transformation_type=rotation + @vector=[-1 -0.0037 -0.002] + @units=degrees + chi=0 + @depends_on=sam_x + @transformation_type=rotation + @vector=[0.0046 0.0372 0.9993] + @units=degrees + sam_x=0 + @depends_on=sam_y + @transformation_type=translation + @vector=[1 0 0] + @units=mm + sam_y=0 + @depends_on=sam_z + @transformation_type=translation + @vector=[0 1 0] + @units=mm + sam_z=0 + @depends_on=omega + @transformation_type=translation + @vector=[0 0 1] + @units=mm + omega=174 + @depends_on=. + @transformation_type=rotation + @vector=[-1 0 0] + @units=degrees + + **Example 2: different coordinate system** + + Define a laboratory reference frame with the X-axis along the beam and the Z-axis opposite to the direction of gravity. + Three point detectors are positioned in this reference: + + * *transmission*: + * point detector in the beam + * 20 cm downstream from the sample (the origin of the reference frame) + * *vertical*: + * point detector 10 cm downstream from the sample + * making an angle of 5 degrees with the beam w.r.t. the sample + * positioned in the XZ-plane above the XY-plane + * *horizontal*: + * point detector 11 cm downstream from the sample + * making an angle of 6 degrees with the beam w.r.t. the sample + * positioned in the XY-plane above the XZ-plane + + The coordinates of the point detectors in the laboratory reference frame are + + * *transmission*: :math:`X_\text{lab} = T_x(20) . X_d` + * *vertical*: :math:`X_\text{lab} = R_y(-5) . T_x(10) . X_d` + * *horizontal*: :math:`X_\text{lab} = R_x(-90) . R_y(-6) . T_x(11) . X_d` + + where + + * :math:`T_x`, :math:`T_y`, :math:`T_z`: active transformation matrices for translation along the X, Y and Z axes + * :math:`R_x`, :math:`R_y`, :math:`R_z`: active transformation matrices for rotation around the X, Y and Z axes + * :math:`X_d` is a coordinate in the detector reference frame. + + Note that as these are point detectors, we only have one coordinate :math:`X_d=[0,0,0,1]^T`. + + .. code-block:: + + entry:NXentry + instrument:NXinstrument + vertical:NXdetector + depends_on=position/distance + position:NXtransformations + distance=10 # move downstream from the sample + @depends_on=polar + @units=cm + @vector=[1 0 0] + polar=5 # title above the horizontal plane + @depends_on=azimuth + @units=degrees + @vector=[0 -1 0] + azimuth=0 # stay in the vertical plane + @depends_on=/entry/coordinate_system/beam + @units=degrees + @vector=[-1 0 0] + horizontal:NXdetector + depends_on=position/distance + position:NXtransformations + distance=11 # move downstream from the sample + @depends_on=polar + @units=cm + @vector=[1 0 0] + polar=6 # title above the horizontal plane + @depends_on=azimuth + @units=degrees + @vector=[0 -1 0] + azimuth=90 # rotate to the horizontal plane + @depends_on=/entry/coordinate_system/beam + @units=degrees + @vector=[-1 0 0] + transmission:NXdetector + depends_on=position/distance + position:NXtransformations + distance=20 # move downstream from the sample + @depends_on=/entry/coordinate_system/beam + @units=cm + @vector=[1 0 0] + coordinate_system:NXtransformations + beam=NaN # value is never used + @depends_on=gravity + @vector=[1 0 0] # X-axis points in the beam direction + gravity=NaN # value is never used + @depends_on=. # end of the chain + @vector=[0 0 -1] # Z-axis points up + + + + Units need to be appropriate for translation or rotation + + The name of this field is not forced. The user is free to use any name + that does not cause confusion. When using more than one ``AXISNAME`` field, + make sure that each field name is unique in the same group, as required + by HDF5. + + The values given should be the start points of exposures for the corresponding + frames. The end points should be given in ``AXISNAME_end``. + + + + The transformation_type may be ``translation``, in which case the + values are linear displacements along the axis, ``rotation``, + in which case the values are angular rotations around the axis. + + If this attribute is omitted, this is an axis for which there + is no motion to be specifies, such as the direction of gravity, + or the direction to the source, or a basis vector of a + coordinate frame. + + + + + + + + + + Three values that define the axis for this transformation. + The axis should be normalized to unit length, making it + dimensionless. For ``rotation`` axes, the direction should be + chosen for a right-handed rotation with increasing angle. + For ``translation`` axes the direction should be chosen for + increasing displacement. For general axes, an appropriate direction + should be chosen. + + + + + + + + A fixed offset applied before the transformation (three vector components). + This is not intended to be a substitute for a fixed ``translation`` axis but, for example, + as the mechanical offset from mounting the axis to its dependency. + + + + + + + + Units of the offset. Values should be consistent with NX_LENGTH. + + + + + Points to the path of a field defining the axis on which this instance of + NXtransformations depends or the string ".". It can also point to an instance of + ``NX_coordinate_system`` if this transformation depends on it. + + + + + An arbitrary identifier of a component of the equipment to which + the transformation belongs, such as 'detector_arm' or 'detector_module'. + NXtransformations with the same equipment_component label form a logical + grouping which can be combined together into a single change-of-basis + operation. + + + + + + ``AXISNAME_end`` is a placeholder for a name constructed from the actual + name of an axis to which ``_end`` has been appended. + + The values in this field are the end points of the motions that start + at the corresponding positions given in the ``AXISNAME`` field. + + + + + ``AXISNAME_increment_set`` is a placeholder for a name constructed from the actual + name of an axis to which ``_increment_set`` has been appended. + + The value of this optional field is the intended average range through which + the corresponding axis moves during the exposure of a frame. Ideally, the + value of this field added to each value of ``AXISNAME`` would agree with the + corresponding values of ``AXISNAME_end``, but there is a possibility of significant + differences. Use of ``AXISNAME_end`` is recommended. + + - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. - \ No newline at end of file + From dceceed65bb6b1c8e2595a1d7a28012b13e3f11c Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Wed, 3 Jul 2024 14:56:48 +0200 Subject: [PATCH 05/37] ci/cd fix # Conflicts: # base_classes/nyaml/NXtransformations.yaml --- base_classes/NXtransformations.nxdl.xml | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index bfbed37436..41d2d5d7da 100644 --- a/base_classes/NXtransformations.nxdl.xml +++ b/base_classes/NXtransformations.nxdl.xml @@ -210,47 +210,47 @@ vertical:NXdetector depends_on=position/distance position:NXtransformations - distance=10 # move downstream from the sample + distance=10 # move downstream from the sample @depends_on=polar @units=cm @vector=[1 0 0] - polar=5 # title above the horizontal plane + polar=5 # title above the horizontal plane @depends_on=azimuth @units=degrees @vector=[0 -1 0] - azimuth=0 # stay in the vertical plane + azimuth=0 # stay in the vertical plane @depends_on=/entry/coordinate_system/beam @units=degrees @vector=[-1 0 0] horizontal:NXdetector depends_on=position/distance position:NXtransformations - distance=11 # move downstream from the sample + distance=11 # move downstream from the sample @depends_on=polar @units=cm @vector=[1 0 0] - polar=6 # title above the horizontal plane + polar=6 # title above the horizontal plane @depends_on=azimuth @units=degrees @vector=[0 -1 0] - azimuth=90 # rotate to the horizontal plane + azimuth=90 # rotate to the horizontal plane @depends_on=/entry/coordinate_system/beam @units=degrees @vector=[-1 0 0] transmission:NXdetector depends_on=position/distance position:NXtransformations - distance=20 # move downstream from the sample + distance=20 # move downstream from the sample @depends_on=/entry/coordinate_system/beam @units=cm @vector=[1 0 0] coordinate_system:NXtransformations - beam=NaN # value is never used + beam=NaN # value is never used @depends_on=gravity - @vector=[1 0 0] # X-axis points in the beam direction - gravity=NaN # value is never used - @depends_on=. # end of the chain - @vector=[0 0 -1] # Z-axis points up + @vector=[1 0 0] # X-axis points in the beam direction + gravity=NaN # value is never used + @depends_on=. # end of the chain + @vector=[0 0 -1] # Z-axis points up From fe3910cb2015859b00d0ec67f75ba206de62d3a1 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Mon, 16 Sep 2024 15:48:12 +0200 Subject: [PATCH 06/37] revert unintentional changes from cherry-pick --- base_classes/NXtransformations.nxdl.xml | 703 ++++++++++++------------ 1 file changed, 358 insertions(+), 345 deletions(-) diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index 41d2d5d7da..6130240311 100644 --- a/base_classes/NXtransformations.nxdl.xml +++ b/base_classes/NXtransformations.nxdl.xml @@ -1,10 +1,10 @@ - - + + - - - Collection of axis-based translations and rotations to describe a geometry. - May also contain axes that do not move and therefore do not have a transformation - type specified, but are useful in understanding coordinate frames within which - transformations are done, or in documenting important directions, such as the - direction of gravity. - - A nested sequence of transformations lists the translation and rotation steps - needed to describe the position and orientation of any movable or fixed device. - - There will be one or more transformations (axes) defined by one or more fields - for each transformation. Transformations can also be described by NXlog groups when - the values change with time. The all-caps name ``AXISNAME`` designates the - particular axis generating a transformation (e.g. a rotation axis or a translation - axis or a general axis). The attribute ``units="NX_TRANSFORMATION"`` designates the - units will be appropriate to the ``transformation_type`` attribute: - - * ``NX_LENGTH`` for ``translation`` - * ``NX_ANGLE`` for ``rotation`` - * ``NX_UNITLESS`` for axes for which no transformation type is specified - - This class will usually contain all axes of a sample stage or goniometer or - a detector. The NeXus default :ref:`McSTAS coordinate frame<Design-CoordinateSystem>` - is assumed, but additional useful coordinate axes may be defined by using axes for which - no transformation type has been specified. - - **Transformation chain** - - The entry point of a chain of transformations is a field called ``depends_on`` - will be outside of this class and points to a field in here. Following the chain may - also require following ``depends_on`` links to transformations outside, for example - to a common base table. If a relative path is given, it is relative to the group - enclosing the ``depends_on`` specification. - - For a chain of three transformations, where :math:`T_1` depends on :math:`T_2` - which in turn depends on :math:`T_3`, the final *active* transformation - matrix :math:`T_f` is - - .. math:: T_f = T_3 . T_2 . T_1 - - For example when positioning a flat detector, its pixel positions in the laboratory - reference frame (:ref:`McSTAS coordinate frame<Design-CoordinateSystem>` by default) - can be calculated by - - .. math:: X_\text{lab} = T_f . X_\text{pixel} = T_3 . T_2 . T_1 . X_\text{pixel} - - Note that :math:`T_1` comes first in the *depends-on* chain and is also applied first - to the pixel coordinates. - - When we say transformation :math:`A` *depends on* transformation :math:`B` we mean that - the physical motor that realizes :math:`A` is *stacked on top of* the motor that realizes :math:`B`. - So the activate coordinate transformation :math:`A` needs to be applied to a coordinate - before applying :math:`B`. In other words :math:`X' = B . A . X`. - - **Transformation matrix** - - In explicit terms, the transformations are a subset of affine transformations expressed as - 4x4 active transformation matrices that act on homogeneous coordinates, :math:`X=[x,y,z,1]^T`. - - For rotation and translation, - - .. math:: T_r &= \begin{pmatrix} R & o \\ 0_3 & 1 \end{pmatrix} \\ T_t &= \begin{pmatrix} I_3 & t + o \\ 0_3 & 1 \end{pmatrix} - - where :math:`R` is the usual 3x3 rotation matrix, :math:`o` is an offset vector, - :math:`0_3` is a row of 3 zeros, :math:`I_3` is the 3x3 identity matrix and - :math:`t` is the translation vector. - - :math:`o` is given by the ``offset`` attribute, :math:`t` is given by the ``vector`` - attribute multiplied by the field value, and :math:`R` is defined as a rotation - about an axis in the direction of ``vector``, of angle of the field value. - - **Usage** - - One possible use of ``NXtransformations`` is to define the motors and - transformations for a diffractometer (goniometer). Such use is mentioned - in the ``NXinstrument`` base class. Use one ``NXtransformations`` group - for each diffractometer and name the group appropriate to the device. - Collecting the motors of a sample table or xyz-stage in an NXtransformations - group is equally possible. - - Following the section on the general description of axis in NXtransformations is a section which - documents the fields commonly used within NeXus for positioning purposes and their meaning. Whenever - there is a need for positioning a beam line component please use the existing names. Use as many fields - as needed in order to position the component. Feel free to add more axis if required. In the description - given below, only those atttributes which are defined through the name are spcified. Add the other attributes - of the full set: - - * vector - * offset - * transformation_type - * depends_on - - as needed. - - **Example 1: goniometer** - - Position a sample mounted on a goniometer in the :ref:`McSTAS coordinate frame<Design-CoordinateSystem>`. - - The sample is oriented as follows - - .. math:: X_\text{lab} = R(\vec{v}_\omega, \omega) . - T(\vec{v}_z, \text{sam}_z) . - T(\vec{v}_y, \text{sam}_y) . - T(\vec{v}_x, \text{sam}_x) . - R(\vec{v}_\chi, \chi) . - R(\vec{v}_\varphi, \varphi) . X_s - - where - - * :math:`R(\vec{v},a)` is a rotation around vector :math:`\vec{v}` with angle :math:`a` - * :math:`T(\vec{u},t)` is a translation along vector :math:`\vec{u}` over a distance :math:`t` - * :math:`X_s` a coordinate in the sample reference frame. - - .. code-block:: - - entry:NXentry - sample:NXsample - depends_on=transformations/phi - transformations:NXtransformations - phi=0 - @depends_on=chi - @transformation_type=rotation - @vector=[-1 -0.0037 -0.002] - @units=degrees - chi=0 - @depends_on=sam_x - @transformation_type=rotation - @vector=[0.0046 0.0372 0.9993] - @units=degrees - sam_x=0 - @depends_on=sam_y - @transformation_type=translation - @vector=[1 0 0] - @units=mm - sam_y=0 - @depends_on=sam_z - @transformation_type=translation - @vector=[0 1 0] - @units=mm - sam_z=0 - @depends_on=omega - @transformation_type=translation - @vector=[0 0 1] - @units=mm - omega=174 - @depends_on=. - @transformation_type=rotation - @vector=[-1 0 0] - @units=degrees - - **Example 2: different coordinate system** - - Define a laboratory reference frame with the X-axis along the beam and the Z-axis opposite to the direction of gravity. - Three point detectors are positioned in this reference: - - * *transmission*: - * point detector in the beam - * 20 cm downstream from the sample (the origin of the reference frame) - * *vertical*: - * point detector 10 cm downstream from the sample - * making an angle of 5 degrees with the beam w.r.t. the sample - * positioned in the XZ-plane above the XY-plane - * *horizontal*: - * point detector 11 cm downstream from the sample - * making an angle of 6 degrees with the beam w.r.t. the sample - * positioned in the XY-plane above the XZ-plane - - The coordinates of the point detectors in the laboratory reference frame are - - * *transmission*: :math:`X_\text{lab} = T_x(20) . X_d` - * *vertical*: :math:`X_\text{lab} = R_y(-5) . T_x(10) . X_d` - * *horizontal*: :math:`X_\text{lab} = R_x(-90) . R_y(-6) . T_x(11) . X_d` - - where - - * :math:`T_x`, :math:`T_y`, :math:`T_z`: active transformation matrices for translation along the X, Y and Z axes - * :math:`R_x`, :math:`R_y`, :math:`R_z`: active transformation matrices for rotation around the X, Y and Z axes - * :math:`X_d` is a coordinate in the detector reference frame. - - Note that as these are point detectors, we only have one coordinate :math:`X_d=[0,0,0,1]^T`. - - .. code-block:: - - entry:NXentry - instrument:NXinstrument - vertical:NXdetector - depends_on=position/distance - position:NXtransformations - distance=10 # move downstream from the sample - @depends_on=polar - @units=cm - @vector=[1 0 0] - polar=5 # title above the horizontal plane - @depends_on=azimuth - @units=degrees - @vector=[0 -1 0] - azimuth=0 # stay in the vertical plane - @depends_on=/entry/coordinate_system/beam - @units=degrees - @vector=[-1 0 0] - horizontal:NXdetector - depends_on=position/distance - position:NXtransformations - distance=11 # move downstream from the sample - @depends_on=polar - @units=cm - @vector=[1 0 0] - polar=6 # title above the horizontal plane - @depends_on=azimuth - @units=degrees - @vector=[0 -1 0] - azimuth=90 # rotate to the horizontal plane - @depends_on=/entry/coordinate_system/beam - @units=degrees - @vector=[-1 0 0] - transmission:NXdetector - depends_on=position/distance - position:NXtransformations - distance=20 # move downstream from the sample - @depends_on=/entry/coordinate_system/beam - @units=cm - @vector=[1 0 0] - coordinate_system:NXtransformations - beam=NaN # value is never used - @depends_on=gravity - @vector=[1 0 0] # X-axis points in the beam direction - gravity=NaN # value is never used - @depends_on=. # end of the chain - @vector=[0 0 -1] # Z-axis points up - - - - Units need to be appropriate for translation or rotation - - The name of this field is not forced. The user is free to use any name - that does not cause confusion. When using more than one ``AXISNAME`` field, - make sure that each field name is unique in the same group, as required - by HDF5. - - The values given should be the start points of exposures for the corresponding - frames. The end points should be given in ``AXISNAME_end``. - - - - The transformation_type may be ``translation``, in which case the - values are linear displacements along the axis, ``rotation``, - in which case the values are angular rotations around the axis. - - If this attribute is omitted, this is an axis for which there - is no motion to be specifies, such as the direction of gravity, - or the direction to the source, or a basis vector of a - coordinate frame. - - - - - - - - - - Three values that define the axis for this transformation. - The axis should be normalized to unit length, making it - dimensionless. For ``rotation`` axes, the direction should be - chosen for a right-handed rotation with increasing angle. - For ``translation`` axes the direction should be chosen for - increasing displacement. For general axes, an appropriate direction - should be chosen. - - - - - - - - A fixed offset applied before the transformation (three vector components). - This is not intended to be a substitute for a fixed ``translation`` axis but, for example, - as the mechanical offset from mounting the axis to its dependency. - - - - - - - - Units of the offset. Values should be consistent with NX_LENGTH. - - - - - Points to the path of a field defining the axis on which this instance of - NXtransformations depends or the string ".". It can also point to an instance of - ``NX_coordinate_system`` if this transformation depends on it. - - - - - An arbitrary identifier of a component of the equipment to which - the transformation belongs, such as 'detector_arm' or 'detector_module'. - NXtransformations with the same equipment_component label form a logical - grouping which can be combined together into a single change-of-basis - operation. - - - - - - ``AXISNAME_end`` is a placeholder for a name constructed from the actual - name of an axis to which ``_end`` has been appended. - - The values in this field are the end points of the motions that start - at the corresponding positions given in the ``AXISNAME`` field. - - - - - ``AXISNAME_increment_set`` is a placeholder for a name constructed from the actual - name of an axis to which ``_increment_set`` has been appended. - - The value of this optional field is the intended average range through which - the corresponding axis moves during the exposure of a frame. Ideally, the - value of this field added to each value of ``AXISNAME`` would agree with the - corresponding values of ``AXISNAME_end``, but there is a possibility of significant - differences. Use of ``AXISNAME_end`` is recommended. - - - - - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. - - - + + + + Collection of axis-based translations and rotations to describe a geometry. + May also contain axes that do not move and therefore do not have a transformation + type specified, but are useful in understanding coordinate frames within which + transformations are done, or in documenting important directions, such as the + direction of gravity. + + A nested sequence of transformations lists the translation and rotation steps + needed to describe the position and orientation of any movable or fixed device. + + There will be one or more transformations (axes) defined by one or more fields + for each transformation. Transformations can also be described by NXlog groups when + the values change with time. The all-caps name ``AXISNAME`` designates the + particular axis generating a transformation (e.g. a rotation axis or a translation + axis or a general axis). The attribute ``units="NX_TRANSFORMATION"`` designates the + units will be appropriate to the ``transformation_type`` attribute: + + * ``NX_LENGTH`` for ``translation`` + * ``NX_ANGLE`` for ``rotation`` + * ``NX_UNITLESS`` for axes for which no transformation type is specified + + This class will usually contain all axes of a sample stage or goniometer or + a detector. The NeXus default :ref:`McSTAS coordinate frame<Design-CoordinateSystem>` + is assumed, but additional useful coordinate axes may be defined by using axes for which + no transformation type has been specified. + + **Transformation chain** + + The entry point of a chain of transformations is a field called ``depends_on`` + will be outside of this class and points to a field in here. Following the chain may + also require following ``depends_on`` links to transformations outside, for example + to a common base table. If a relative path is given, it is relative to the group + enclosing the ``depends_on`` specification. + + For a chain of three transformations, where :math:`T_1` depends on :math:`T_2` + which in turn depends on :math:`T_3`, the final *active* transformation + matrix :math:`T_f` is + + .. math:: T_f = T_3 . T_2 . T_1 + + For example when positioning a flat detector, its pixel positions in the laboratory + reference frame (:ref:`McSTAS coordinate frame<Design-CoordinateSystem>` by default) + can be calculated by + + .. math:: X_\text{lab} = T_f . X_\text{pixel} = T_3 . T_2 . T_1 . X_\text{pixel} + + Note that :math:`T_1` comes first in the *depends-on* chain and is also applied first + to the pixel coordinates. + + When we say transformation :math:`A` *depends on* transformation :math:`B` we mean that + the physical motor that realizes :math:`A` is *stacked on top of* the motor that realizes :math:`B`. + So the activate coordinate transformation :math:`A` needs to be applied to a coordinate + before applying :math:`B`. In other words :math:`X' = B . A . X`. + + **Transformation matrix** + + In explicit terms, the transformations are a subset of affine transformations expressed as + 4x4 active transformation matrices that act on homogeneous coordinates, :math:`X=[x,y,z,1]^T`. + + For rotation and translation, + + .. math:: T_r &= \begin{pmatrix} R & o \\ 0_3 & 1 \end{pmatrix} \\ T_t &= \begin{pmatrix} I_3 & t + o \\ 0_3 & 1 \end{pmatrix} + + where :math:`R` is the usual 3x3 rotation matrix, :math:`o` is an offset vector, + :math:`0_3` is a row of 3 zeros, :math:`I_3` is the 3x3 identity matrix and + :math:`t` is the translation vector. + + :math:`o` is given by the ``offset`` attribute, :math:`t` is given by the ``vector`` + attribute multiplied by the field value, and :math:`R` is defined as a rotation + about an axis in the direction of ``vector``, of angle of the field value. + + **Usage** + + One possible use of ``NXtransformations`` is to define the motors and + transformations for a diffractometer (goniometer). Such use is mentioned + in the ``NXinstrument`` base class. Use one ``NXtransformations`` group + for each diffractometer and name the group appropriate to the device. + Collecting the motors of a sample table or xyz-stage in an NXtransformations + group is equally possible. + + Following the section on the general description of axis in NXtransformations is a section which + documents the fields commonly used within NeXus for positioning purposes and their meaning. Whenever + there is a need for positioning a beam line component please use the existing names. Use as many fields + as needed in order to position the component. Feel free to add more axis if required. In the description + given below, only those atttributes which are defined through the name are spcified. Add the other attributes + of the full set: + + * vector + * offset + * transformation_type + * depends_on + + as needed. + + **Example 1: goniometer** + + Position a sample mounted on a goniometer in the :ref:`McSTAS coordinate frame<Design-CoordinateSystem>`. + + The sample is oriented as follows + + .. math:: X_\text{lab} = R(\vec{v}_\omega, \omega) . + T(\vec{v}_z, \text{sam}_z) . + T(\vec{v}_y, \text{sam}_y) . + T(\vec{v}_x, \text{sam}_x) . + R(\vec{v}_\chi, \chi) . + R(\vec{v}_\varphi, \varphi) . X_s + + where + + * :math:`R(\vec{v},a)` is a rotation around vector :math:`\vec{v}` with angle :math:`a` + * :math:`T(\vec{u},t)` is a translation along vector :math:`\vec{u}` over a distance :math:`t` + * :math:`X_s` a coordinate in the sample reference frame. + + .. code-block:: + + entry:NXentry + sample:NXsample + depends_on=transformations/phi + transformations:NXtransformations + phi=0 + @depends_on=chi + @transformation_type=rotation + @vector=[-1 -0.0037 -0.002] + @units=degrees + chi=0 + @depends_on=sam_x + @transformation_type=rotation + @vector=[0.0046 0.0372 0.9993] + @units=degrees + sam_x=0 + @depends_on=sam_y + @transformation_type=translation + @vector=[1 0 0] + @units=mm + sam_y=0 + @depends_on=sam_z + @transformation_type=translation + @vector=[0 1 0] + @units=mm + sam_z=0 + @depends_on=omega + @transformation_type=translation + @vector=[0 0 1] + @units=mm + omega=174 + @depends_on=. + @transformation_type=rotation + @vector=[-1 0 0] + @units=degrees + + **Example 2: different coordinate system** + + Define a laboratory reference frame with the X-axis along the beam and the Z-axis opposite to the direction of gravity. + Three point detectors are positioned in this reference: + + * *transmission*: + * point detector in the beam + * 20 cm downstream from the sample (the origin of the reference frame) + * *vertical*: + * point detector 10 cm downstream from the sample + * making an angle of 5 degrees with the beam w.r.t. the sample + * positioned in the XZ-plane above the XY-plane + * *horizontal*: + * point detector 11 cm downstream from the sample + * making an angle of 6 degrees with the beam w.r.t. the sample + * positioned in the XY-plane above the XZ-plane + + The coordinates of the point detectors in the laboratory reference frame are + + * *transmission*: :math:`X_\text{lab} = T_x(20) . X_d` + * *vertical*: :math:`X_\text{lab} = R_y(-5) . T_x(10) . X_d` + * *horizontal*: :math:`X_\text{lab} = R_x(-90) . R_y(-6) . T_x(11) . X_d` + + where + + * :math:`T_x`, :math:`T_y`, :math:`T_z`: active transformation matrices for translation along the X, Y and Z axes + * :math:`R_x`, :math:`R_y`, :math:`R_z`: active transformation matrices for rotation around the X, Y and Z axes + * :math:`X_d` is a coordinate in the detector reference frame. + + Note that as these are point detectors, we only have one coordinate :math:`X_d=[0,0,0,1]^T`. + + .. code-block:: + + entry:NXentry + instrument:NXinstrument + vertical:NXdetector + depends_on=position/distance + position:NXtransformations + distance=10 # move downstream from the sample + @depends_on=polar + @units=cm + @vector=[1 0 0] + polar=5 # title above the horizontal plane + @depends_on=azimuth + @units=degrees + @vector=[0 -1 0] + azimuth=0 # stay in the vertical plane + @depends_on=/entry/coordinate_system/beam + @units=degrees + @vector=[-1 0 0] + horizontal:NXdetector + depends_on=position/distance + position:NXtransformations + distance=11 # move downstream from the sample + @depends_on=polar + @units=cm + @vector=[1 0 0] + polar=6 # title above the horizontal plane + @depends_on=azimuth + @units=degrees + @vector=[0 -1 0] + azimuth=90 # rotate to the horizontal plane + @depends_on=/entry/coordinate_system/beam + @units=degrees + @vector=[-1 0 0] + transmission:NXdetector + depends_on=position/distance + position:NXtransformations + distance=20 # move downstream from the sample + @depends_on=/entry/coordinate_system/beam + @units=cm + @vector=[1 0 0] + coordinate_system:NXtransformations + beam=NaN # value is never used + @depends_on=gravity + @vector=[1 0 0] # X-axis points in the beam direction + gravity=NaN # value is never used + @depends_on=. # end of the chain + @vector=[0 0 -1] # Z-axis points up + + + + + Units need to be appropriate for translation or rotation + + The name of this field is not forced. The user is free to use any name + that does not cause confusion. When using more than one ``AXISNAME`` field, + make sure that each field name is unique in the same group, as required + by HDF5. + + The values given should be the start points of exposures for the corresponding + frames. The end points should be given in ``AXISNAME_end``. + + + + The transformation_type may be ``translation``, in which case the + values are linear displacements along the axis, ``rotation``, + in which case the values are angular rotations around the axis. + + If this attribute is omitted, this is an axis for which there + is no motion to be specifies, such as the direction of gravity, + or the direction to the source, or a basis vector of a + coordinate frame. In this case the value of the ``AXISNAME`` field + is not used and can be set to the number ``NaN``. + + + + + + + + + + Three values that define the axis for this transformation. + The axis should be normalized to unit length, making it + dimensionless. For ``rotation`` axes, the direction should be + chosen for a right-handed rotation with increasing angle. + For ``translation`` axes the direction should be chosen for + increasing displacement. For general axes, an appropriate direction + should be chosen. + + + + + + + + A fixed offset applied before the transformation (three vector components). + This is not intended to be a substitute for a fixed ``translation`` axis but, for example, + as the mechanical offset from mounting the axis to its dependency. + + + + + + + + Units of the offset. Values should be consistent with NX_LENGTH. + + + + + Points to the path of a field defining the axis on which this instance of + NXtransformations depends or the string ".". It can also point to an instance of + ``NX_coordinate_system`` if this transformation depends on it. + + + + + An arbitrary identifier of a component of the equipment to which + the transformation belongs, such as 'detector_arm' or 'detector_module'. + NXtransformations with the same equipment_component label form a logical + grouping which can be combined together into a single change-of-basis + operation. + + + + + + ``AXISNAME_end`` is a placeholder for a name constructed from the actual + name of an axis to which ``_end`` has been appended. + + The values in this field are the end points of the motions that start + at the corresponding positions given in the ``AXISNAME`` field. + + + + + ``AXISNAME_increment_set`` is a placeholder for a name constructed from the actual + name of an axis to which ``_increment_set`` has been appended. + + The value of this optional field is the intended average range through which + the corresponding axis moves during the exposure of a frame. Ideally, the + value of this field added to each value of ``AXISNAME`` would agree with the + corresponding values of ``AXISNAME_end``, but there is a possibility of significant + differences. Use of ``AXISNAME_end`` is recommended. + + + + + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + + + \ No newline at end of file From f2dbbe96c22d0ba16bfcc0196070ace113d54ed7 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Mon, 23 Sep 2024 18:18:53 +0200 Subject: [PATCH 07/37] remove unmerged docs update in NXtransformations --- base_classes/NXtransformations.nxdl.xml | 213 ++++-------------------- 1 file changed, 29 insertions(+), 184 deletions(-) diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index 6130240311..fd40f89e48 100644 --- a/base_classes/NXtransformations.nxdl.xml +++ b/base_classes/NXtransformations.nxdl.xml @@ -55,42 +55,23 @@ * ``NX_UNITLESS`` for axes for which no transformation type is specified This class will usually contain all axes of a sample stage or goniometer or - a detector. The NeXus default :ref:`McSTAS coordinate frame<Design-CoordinateSystem>` - is assumed, but additional useful coordinate axes may be defined by using axes for which - no transformation type has been specified. + a detector. The NeXus default McSTAS coordinate frame is assumed, but additional + useful coordinate axes may be defined by using axes for which no transformation + type has been specified. - **Transformation chain** - - The entry point of a chain of transformations is a field called ``depends_on`` - will be outside of this class and points to a field in here. Following the chain may - also require following ``depends_on`` links to transformations outside, for example - to a common base table. If a relative path is given, it is relative to the group - enclosing the ``depends_on`` specification. + The entry point (``depends_on``) will be outside of this class and point to a + field in here. Following the chain may also require following ``depends_on`` + links to transformations outside, for example to a common base table. If + a relative path is given, it is relative to the group enclosing the ``depends_on`` + specification. For a chain of three transformations, where :math:`T_1` depends on :math:`T_2` - which in turn depends on :math:`T_3`, the final *active* transformation - matrix :math:`T_f` is - - .. math:: T_f = T_3 . T_2 . T_1 - - For example when positioning a flat detector, its pixel positions in the laboratory - reference frame (:ref:`McSTAS coordinate frame<Design-CoordinateSystem>` by default) - can be calculated by - - .. math:: X_\text{lab} = T_f . X_\text{pixel} = T_3 . T_2 . T_1 . X_\text{pixel} + and that in turn depends on :math:`T_3`, the final transformation :math:`T_f` is - Note that :math:`T_1` comes first in the *depends-on* chain and is also applied first - to the pixel coordinates. + .. math:: T_f = T_3 T_2 T_1 - When we say transformation :math:`A` *depends on* transformation :math:`B` we mean that - the physical motor that realizes :math:`A` is *stacked on top of* the motor that realizes :math:`B`. - So the activate coordinate transformation :math:`A` needs to be applied to a coordinate - before applying :math:`B`. In other words :math:`X' = B . A . X`. - - **Transformation matrix** - - In explicit terms, the transformations are a subset of affine transformations expressed as - 4x4 active transformation matrices that act on homogeneous coordinates, :math:`X=[x,y,z,1]^T`. + In explicit terms, the transformations are a subset of affine transformations + expressed as 4x4 matrices that act on homogeneous coordinates, :math:`w=(x,y,z,1)^T`. For rotation and translation, @@ -104,8 +85,8 @@ attribute multiplied by the field value, and :math:`R` is defined as a rotation about an axis in the direction of ``vector``, of angle of the field value. - **Usage** - + NOTE + One possible use of ``NXtransformations`` is to define the motors and transformations for a diffractometer (goniometer). Such use is mentioned in the ``NXinstrument`` base class. Use one ``NXtransformations`` group @@ -113,7 +94,8 @@ Collecting the motors of a sample table or xyz-stage in an NXtransformations group is equally possible. - Following the section on the general description of axis in NXtransformations is a section which + + Following the section on the general dscription of axis in NXtransformations is a section which documents the fields commonly used within NeXus for positioning purposes and their meaning. Whenever there is a need for positioning a beam line component please use the existing names. Use as many fields as needed in order to position the component. Feel free to add more axis if required. In the description @@ -126,143 +108,6 @@ * depends_on as needed. - - **Example 1: goniometer** - - Position a sample mounted on a goniometer in the :ref:`McSTAS coordinate frame<Design-CoordinateSystem>`. - - The sample is oriented as follows - - .. math:: X_\text{lab} = R(\vec{v}_\omega, \omega) . - T(\vec{v}_z, \text{sam}_z) . - T(\vec{v}_y, \text{sam}_y) . - T(\vec{v}_x, \text{sam}_x) . - R(\vec{v}_\chi, \chi) . - R(\vec{v}_\varphi, \varphi) . X_s - - where - - * :math:`R(\vec{v},a)` is a rotation around vector :math:`\vec{v}` with angle :math:`a` - * :math:`T(\vec{u},t)` is a translation along vector :math:`\vec{u}` over a distance :math:`t` - * :math:`X_s` a coordinate in the sample reference frame. - - .. code-block:: - - entry:NXentry - sample:NXsample - depends_on=transformations/phi - transformations:NXtransformations - phi=0 - @depends_on=chi - @transformation_type=rotation - @vector=[-1 -0.0037 -0.002] - @units=degrees - chi=0 - @depends_on=sam_x - @transformation_type=rotation - @vector=[0.0046 0.0372 0.9993] - @units=degrees - sam_x=0 - @depends_on=sam_y - @transformation_type=translation - @vector=[1 0 0] - @units=mm - sam_y=0 - @depends_on=sam_z - @transformation_type=translation - @vector=[0 1 0] - @units=mm - sam_z=0 - @depends_on=omega - @transformation_type=translation - @vector=[0 0 1] - @units=mm - omega=174 - @depends_on=. - @transformation_type=rotation - @vector=[-1 0 0] - @units=degrees - - **Example 2: different coordinate system** - - Define a laboratory reference frame with the X-axis along the beam and the Z-axis opposite to the direction of gravity. - Three point detectors are positioned in this reference: - - * *transmission*: - * point detector in the beam - * 20 cm downstream from the sample (the origin of the reference frame) - * *vertical*: - * point detector 10 cm downstream from the sample - * making an angle of 5 degrees with the beam w.r.t. the sample - * positioned in the XZ-plane above the XY-plane - * *horizontal*: - * point detector 11 cm downstream from the sample - * making an angle of 6 degrees with the beam w.r.t. the sample - * positioned in the XY-plane above the XZ-plane - - The coordinates of the point detectors in the laboratory reference frame are - - * *transmission*: :math:`X_\text{lab} = T_x(20) . X_d` - * *vertical*: :math:`X_\text{lab} = R_y(-5) . T_x(10) . X_d` - * *horizontal*: :math:`X_\text{lab} = R_x(-90) . R_y(-6) . T_x(11) . X_d` - - where - - * :math:`T_x`, :math:`T_y`, :math:`T_z`: active transformation matrices for translation along the X, Y and Z axes - * :math:`R_x`, :math:`R_y`, :math:`R_z`: active transformation matrices for rotation around the X, Y and Z axes - * :math:`X_d` is a coordinate in the detector reference frame. - - Note that as these are point detectors, we only have one coordinate :math:`X_d=[0,0,0,1]^T`. - - .. code-block:: - - entry:NXentry - instrument:NXinstrument - vertical:NXdetector - depends_on=position/distance - position:NXtransformations - distance=10 # move downstream from the sample - @depends_on=polar - @units=cm - @vector=[1 0 0] - polar=5 # title above the horizontal plane - @depends_on=azimuth - @units=degrees - @vector=[0 -1 0] - azimuth=0 # stay in the vertical plane - @depends_on=/entry/coordinate_system/beam - @units=degrees - @vector=[-1 0 0] - horizontal:NXdetector - depends_on=position/distance - position:NXtransformations - distance=11 # move downstream from the sample - @depends_on=polar - @units=cm - @vector=[1 0 0] - polar=6 # title above the horizontal plane - @depends_on=azimuth - @units=degrees - @vector=[0 -1 0] - azimuth=90 # rotate to the horizontal plane - @depends_on=/entry/coordinate_system/beam - @units=degrees - @vector=[-1 0 0] - transmission:NXdetector - depends_on=position/distance - position:NXtransformations - distance=20 # move downstream from the sample - @depends_on=/entry/coordinate_system/beam - @units=cm - @vector=[1 0 0] - coordinate_system:NXtransformations - beam=NaN # value is never used - @depends_on=gravity - @vector=[1 0 0] # X-axis points in the beam direction - gravity=NaN # value is never used - @depends_on=. # end of the chain - @vector=[0 0 -1] # Z-axis points up - @@ -361,17 +206,17 @@ differences. Use of ``AXISNAME_end`` is recommended. - - - .. index:: plotting - - Declares which child group contains a path leading - to a :ref:`NXdata` group. - - It is recommended (as of NIAC2014) to use this attribute - to help define the path to the default dataset to be plotted. - See https://www.nexusformat.org/2014_How_to_find_default_data.html - for a summary of the discussion. - - + + + .. index:: plotting + + Declares which child group contains a path leading + to a :ref:`NXdata` group. + + It is recommended (as of NIAC2014) to use this attribute + to help define the path to the default dataset to be plotted. + See https://www.nexusformat.org/2014_How_to_find_default_data.html + for a summary of the discussion. + + \ No newline at end of file From e95cd7cd655c8b547d6296feac2544eab3dba5ce Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Sun, 29 Sep 2024 14:52:39 +0200 Subject: [PATCH 08/37] bring in NXcoordinate_system --- base_classes/NXcoordinate_system.nxdl.xml | 159 ++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 base_classes/NXcoordinate_system.nxdl.xml diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml new file mode 100644 index 0000000000..80de81f407 --- /dev/null +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -0,0 +1,159 @@ + + + + + + Base class to detail a coordinate system (CS). + + Whenever possible, an instance of :ref:`NXcoordinate_system` should be used as + a member in an :ref:`NXcoordinate_system_set` and the name of the instance + should be this alias. This may support a process whereby jargon when talking + about coordinate systems and conventions may become cleaner for users + because it is not evident for people outside a lab that terms like e.g. + tip space or specimen space refer to the same coordinate system. + This is an example of jargon used in e.g. the field of atom + probe tomography. + + + + Human-readable field telling where the origin of this CS is. + Exemplar values could be *left corner of the lab bench*, *door-handle* + *pinhole through which the electron beam exists the pole piece*. + *barycenter of the triangle*, *center of mass of the stone*. + + + + + + An alternative name given to that coordinate system. + + + + + Coordinate system type. + + + + + + + + + Handedness of the coordinate system if it is a Cartesian. + + + + + + + + + + Possibility to define an alias for the name of the x-axis. + + + + + Human-readable field telling in which direction the x-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + Exemplar values could be direction of gravity. + + + + + + Base unit vector along the first axis which spans the coordinate system. + This axis is frequently referred to as the x-axis in real space and + the i-axis in reciprocal space. + + + + + + + + Possibility to define an alias for the name of the y-axis. + + + + + Human-readable field telling in which direction the y-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + See docstring of x_alias for further details. + + + + + Base unit vector along the second axis which spans the coordinate system. + This axis is frequently referred to as the y-axis in real space and + the j-axis in reciprocal space. + + + + + + + + Possibility to define an alias for the name of the z-axis. + + + + + Human-readable field telling in which direction the z-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + See docstring of x_alias for further details. + + + + + Base unit vector along the third axis which spans the coordinate system. + This axis is frequently referred to as the z-axis in real space and + the k-axis in reciprocal space. + + + + + + + + This specificies the relation to another coordinate system by pointing to the last + transformation in the transformation chain in the NXtransformations group. + + + + + Collection of axis-based translations and rotations to describe this coordinate system + with respect to another coordinate system. + + + From e7a818a70c4ee41318a83f2c9894d8642ba47de2 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Mon, 30 Sep 2024 16:53:13 +0200 Subject: [PATCH 09/37] add NXcoordinate_system_set --- base_classes/NXcoordinate_system_set.nxdl.xml | 240 ++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 base_classes/NXcoordinate_system_set.nxdl.xml diff --git a/base_classes/NXcoordinate_system_set.nxdl.xml b/base_classes/NXcoordinate_system_set.nxdl.xml new file mode 100644 index 0000000000..a842d257d2 --- /dev/null +++ b/base_classes/NXcoordinate_system_set.nxdl.xml @@ -0,0 +1,240 @@ + + + + + + + Base class to hold different coordinate systems and representation conversions. + + How many nodes of type :ref:`NXcoordinate_system_set` should be used in an application definition? + + * 0; if there is no instance of :ref:`NXcoordinate_system_set` and therein or elsewhere across + the application definition, an instance of NXcoordinate_system is defined, + the default NeXus `McStas <https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html>`_ + coordinate system is assumed. This makes :ref:`NXcoordinate_system_set` and + NXcoordinate_system base classes backwards compatible to older + NeXus conventions and classes. + * 1; if only one :ref:`NXcoordinate_system_set` is defined, it should be placed + as high up in the node hierarchy (ideally right below an instance of NXentry) + of the application definition tree as possible. + This :ref:`NXcoordinate_system_set` should define at least one NXcoordinate_system + instance. This shall be named such that it is clear how this coordinate system is + typically referred to in a community. For the NeXus `McStas coordinate system, it is + advised to call it mcstas for the sake of improved clarity. + Additional NXcoordinate_system instances should be specified if possible in that same + :ref:`NXcoordinate_system_set` instead of cluttering them across the tree. + + If this is the case, it is assumed that the NXcoordinate_system_members + overwrite the NeXus default McStas coordinate system, i.e. users can thereby + conveniently and explicitly specify the coordinate system(s) that + they wish to use. + + Users are encouraged to write also explicit and clean depends_on fields in + all groups that encode information about where the interpretation of coordinate + systems is relevant. If these depends_on hints are not provided, it is + automatically assumed that all children (to arbitrary depth) + of that branch and sub-branches below the one in which that + :ref:`NXcoordinate_system_set` is defined use either the only NXcoordinate_system_set + instance in that set or the application definition is considered + underconstrained which should at all costs be avoided and in which case + again McStas is assumed. + * 2 and more; as soon as more than one :ref:`NXcoordinate_system_set` is specified + somewhere in the tree, different interpretations are possible as to which + of these coordinate system sets and instances apply or take preference. + We realize that such ambiguities should at all costs be avoided. + However, the opportunity for multiple sets and their instances enables to + have branch-specific coordinate system conventions which could especially + be useful for deep classes where multiple scientific methods are combined or + cases where having a definition of global translation and conversion tables + how to convert between representations in different coordinate systems + is not desired or available for now. + We argue that having 2 or more :ref:`NXcoordinate_system_set` instances and respective + NXcoordinate_system instances makes the interpretation eventually unnecessary + complicated. Instead, developers of application definitions should always try + to work for clarity and thus use only one top-level coordinate system set. + + For these reasons we conclude that the option with one top-level + :ref:`NXcoordinate_system_set` instance is the preferred choice. + + McStas is used if neither an instance of :ref:`NXcoordinate_system_set` nor an instance + of NXcoordinate_system is specified. However, even in this case it is better + to be explicit like for every other coordinate system definition to support + users with interpreting the content and logic behind every instance of the tree. + + How to store coordinate systems inside :ref:`NXcoordinate_system_set`? + Individual coordinate systems should be specified as members of the + :ref:`NXcoordinate_system_set` instance using instances of NXcoordinate_system. + + How many individual instances of NXcoordinate_system to allow within one + instance of :ref:`NXcoordinate_system_set`? + + * 0; This case should be avoided for the sake of clarity but this case could + mean the authors of the definition meant that McStas is used. We conclude, + McStas is used in this case. + * 1; Like above-mentioned this case has the advantage that it is explicit + and faces no ambiguities. However, in reality typically multiple + coordinate systems have to be mastered especially for complex + multi-signal modality experiments. + * 2 or more; If this case is realized, the best practice is that in every + case where a coordinate system should be referred to the respective class + has a depends_on field which resolves the possible ambiguities which specific + coordinate systems is referred to. The benefit of this explicit and clear + specifying of the coordinate system used in every case is that especially + in combination with having coordinate systems inside deeper branches + makes up for a very versatile, backwards compatible, but powerful system + to express different types of coordinate systems using NeXus. In the case + of two or more instances of NXcoordinate_system in one :ref:`NXcoordinate_system_set`, + it is also advised to specify the relationship between the two coordinate systems by + using the (NXtransformations) group within NXcoordinate_system. + + In effect, 1 should be the preferred choice. However, if more than one coordinate + system is defined for practical purposes, explicit depends_on fields should + always guide the user for each group and field which of the coordinate system + one refers to. + + + + Convention how a positive rotation angle is defined when viewing + from the end of the rotation unit vector towards its origin, + i.e. in accordance with convention 2 of + DOI: 10.1088/0965-0393/23/8/083501. + Counter_clockwise is equivalent to a right-handed choice. + Clockwise is equivalent to a left-handed choice. + + + + + + + + + + How are rotations interpreted into an orientation + according to convention 3 of + DOI: 10.1088/0965-0393/23/8/083501. + + + + + + + + + + How are Euler angles interpreted given that there are several choices (e.g. zxz, xyz) + according to convention 4 of DOI: 10.1088/0965-0393/23/8/083501. + + The most frequently used convention is zxz, which is based on the work of H.-J. Bunge + but other conventions are possible. Apart from undefined, proper Euler angles + are distinguished from (improper) Tait-Bryan angles. + + + + + + + + + + + + + + + + + + + + To which angular range is the rotation angle argument of an + axis-angle pair parameterization constrained according to + convention 5 of DOI: 10.1088/0965-0393/23/8/083501. + + + + + + + + + Which sign convention is followed when converting orientations + between different parameterizations/representations according + to convention 6 of DOI: 10.1088/0965-0393/23/8/083501. + + + + + + + + + + + + + Details about eventually relevant named directions that may give reasons for anisotropies. + The classical example is mechanical processing where one has to specify which directions + (e.g. rolling, transverse, and normal direction) align how with the direction of the base + vectors of the sample_reference_frame. + + It is assumed that the configuration is inspected by looking towards the sample surface. + If a detector is involved, it is assumed that the configuration is inspected from a position + that is located behind this detector. + + If any of these assumptions is not met, the user is required to explicitly state this. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the + base vectors of this coordinate system as Xp, Yp, Zp. + + + + + Details about the sample_reference_frame that is typically overlaid onto the surface of the sample. + + It is assumed that the configuration is inspected by looking towards the sample surface. + If a detector is involved, it is assumed that the configuration is inspected from a position + that is located behind this detector. + + If any of these assumptions is not met, the user is required to explicitly state this. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the + base vectors of this coordinate system as Xs, Ys, Zs. + + + + + Details about the detector_reference_frame for a specific detector. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the + base vectors of this coordinate system as Xd, Yd, Zd. + + It is assumed that the configuration is inspected by looking towards the sample surface + from a position that is located behind the detector. + + If any of these assumptions is not met, the user is required to explicitly state this. + + + From a758081e34f5f1f02551da0d0cca94fa35867365 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Thu, 17 Oct 2024 16:28:31 +0200 Subject: [PATCH 10/37] remove NXcoordinate_system_set from contributed --- .../NXcoordinate_system_set.nxdl.xml | 137 ------------------ 1 file changed, 137 deletions(-) delete mode 100644 contributed_definitions/NXcoordinate_system_set.nxdl.xml diff --git a/contributed_definitions/NXcoordinate_system_set.nxdl.xml b/contributed_definitions/NXcoordinate_system_set.nxdl.xml deleted file mode 100644 index c2276f3a93..0000000000 --- a/contributed_definitions/NXcoordinate_system_set.nxdl.xml +++ /dev/null @@ -1,137 +0,0 @@ - - - - - - Container to hold different coordinate systems conventions. - - It is the purpose of this base class to define these conventions and - offer a place to store mappings between different coordinate systems - which are relevant for the interpretation of the data described - by the application definition and base class instances. - - For each Cartesian coordinate system users should use a set of - NXtransformations: - - * These should define the three base vectors. - * The location of the origin. - * The affine transformations which bring each axis of this coordinate system - into registration with the McStas coordinate system. - * Equally, affine transformations should be given for the inverse mapping. - - As an example one may take an experiment or computer simulation where - there is a laboratory (lab) coordinate system, a sample/specimen coordinate - system, a crystal coordinate system, and additional coordinate systems, - which are eventually attached to components of the instrument. - - If no additional transformation is specified in this group or if an - instance of an NXcoordinate_system_set is absent it should be assumed - the so-called McStas coordinate system is used. - - Many application definitions in NeXus refer to this `McStas <https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html>`_ coordinate system. - This is a Cartesian coordinate system whose z axis points along the neutron - propagation axis. The systems y axis is vertical up, while the x axis points - left when looking along the z-axis. Thus, McStas is a right-handed coordinate system. - - Within each NXtransformations a depends_on section is required. The depends_on - field specifies if the coordinate system is the root/reference - (which is indicated by writing "." in the depends_on section.) - - - - - A group of transformations which specify: - - * Three base vectors of the coordinate system. - * Origin of the coordinate system. - * A depends_on keyword. Its value can be "." or the name of an - NXtransformations instance which needs to exist in the - NXcoordinate_system_set instance. - * If the coordinate system is the reference one it has to be named - reference. - - In case of having more than one NXtransformations there has to be for - each additional coordinate system, i.e. the one not the reference: - - * A set of translations and rotations which map each base vector to the reference. - * A set of translations and rotations which map each reference base vector - to the coordinate system. - - The NXtransformations for these mappings need to be formatted - according to the descriptions in NXtransformations. - - - - - - - From 32a339cbf9e38a6fbfa422842e3fcfa85c979727 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Thu, 16 Jan 2025 14:13:53 +0100 Subject: [PATCH 11/37] separate rotation conventions and predefined coordinate systems --- base_classes/NXcoordinate_system.nxdl.xml | 2 +- base_classes/NXcoordinate_system_set.nxdl.xml | 240 ------------------ .../NXdetector_reference_frame.nxdl.xml | 52 ++++ .../NXprocessing_reference_frame.nxdl.xml | 60 +++++ base_classes/NXrotation_conventions.nxdl.xml | 114 +++++++++ .../NXsample_reference_frame.nxdl.xml | 85 +++++++ 6 files changed, 312 insertions(+), 241 deletions(-) delete mode 100644 base_classes/NXcoordinate_system_set.nxdl.xml create mode 100644 base_classes/NXdetector_reference_frame.nxdl.xml create mode 100644 base_classes/NXprocessing_reference_frame.nxdl.xml create mode 100644 base_classes/NXrotation_conventions.nxdl.xml create mode 100644 base_classes/NXsample_reference_frame.nxdl.xml diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml index 80de81f407..fd03bb061d 100644 --- a/base_classes/NXcoordinate_system.nxdl.xml +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -107,7 +107,7 @@ enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, fr instance of :ref:`NXcoordinate_system` has no reference to any parent and as such is the mighty world reference frame. - See docstring of x_alias for further details. + See docstring of ``x_direction`` for further details. diff --git a/base_classes/NXcoordinate_system_set.nxdl.xml b/base_classes/NXcoordinate_system_set.nxdl.xml deleted file mode 100644 index a842d257d2..0000000000 --- a/base_classes/NXcoordinate_system_set.nxdl.xml +++ /dev/null @@ -1,240 +0,0 @@ - - - - - - - Base class to hold different coordinate systems and representation conversions. - - How many nodes of type :ref:`NXcoordinate_system_set` should be used in an application definition? - - * 0; if there is no instance of :ref:`NXcoordinate_system_set` and therein or elsewhere across - the application definition, an instance of NXcoordinate_system is defined, - the default NeXus `McStas <https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html>`_ - coordinate system is assumed. This makes :ref:`NXcoordinate_system_set` and - NXcoordinate_system base classes backwards compatible to older - NeXus conventions and classes. - * 1; if only one :ref:`NXcoordinate_system_set` is defined, it should be placed - as high up in the node hierarchy (ideally right below an instance of NXentry) - of the application definition tree as possible. - This :ref:`NXcoordinate_system_set` should define at least one NXcoordinate_system - instance. This shall be named such that it is clear how this coordinate system is - typically referred to in a community. For the NeXus `McStas coordinate system, it is - advised to call it mcstas for the sake of improved clarity. - Additional NXcoordinate_system instances should be specified if possible in that same - :ref:`NXcoordinate_system_set` instead of cluttering them across the tree. - - If this is the case, it is assumed that the NXcoordinate_system_members - overwrite the NeXus default McStas coordinate system, i.e. users can thereby - conveniently and explicitly specify the coordinate system(s) that - they wish to use. - - Users are encouraged to write also explicit and clean depends_on fields in - all groups that encode information about where the interpretation of coordinate - systems is relevant. If these depends_on hints are not provided, it is - automatically assumed that all children (to arbitrary depth) - of that branch and sub-branches below the one in which that - :ref:`NXcoordinate_system_set` is defined use either the only NXcoordinate_system_set - instance in that set or the application definition is considered - underconstrained which should at all costs be avoided and in which case - again McStas is assumed. - * 2 and more; as soon as more than one :ref:`NXcoordinate_system_set` is specified - somewhere in the tree, different interpretations are possible as to which - of these coordinate system sets and instances apply or take preference. - We realize that such ambiguities should at all costs be avoided. - However, the opportunity for multiple sets and their instances enables to - have branch-specific coordinate system conventions which could especially - be useful for deep classes where multiple scientific methods are combined or - cases where having a definition of global translation and conversion tables - how to convert between representations in different coordinate systems - is not desired or available for now. - We argue that having 2 or more :ref:`NXcoordinate_system_set` instances and respective - NXcoordinate_system instances makes the interpretation eventually unnecessary - complicated. Instead, developers of application definitions should always try - to work for clarity and thus use only one top-level coordinate system set. - - For these reasons we conclude that the option with one top-level - :ref:`NXcoordinate_system_set` instance is the preferred choice. - - McStas is used if neither an instance of :ref:`NXcoordinate_system_set` nor an instance - of NXcoordinate_system is specified. However, even in this case it is better - to be explicit like for every other coordinate system definition to support - users with interpreting the content and logic behind every instance of the tree. - - How to store coordinate systems inside :ref:`NXcoordinate_system_set`? - Individual coordinate systems should be specified as members of the - :ref:`NXcoordinate_system_set` instance using instances of NXcoordinate_system. - - How many individual instances of NXcoordinate_system to allow within one - instance of :ref:`NXcoordinate_system_set`? - - * 0; This case should be avoided for the sake of clarity but this case could - mean the authors of the definition meant that McStas is used. We conclude, - McStas is used in this case. - * 1; Like above-mentioned this case has the advantage that it is explicit - and faces no ambiguities. However, in reality typically multiple - coordinate systems have to be mastered especially for complex - multi-signal modality experiments. - * 2 or more; If this case is realized, the best practice is that in every - case where a coordinate system should be referred to the respective class - has a depends_on field which resolves the possible ambiguities which specific - coordinate systems is referred to. The benefit of this explicit and clear - specifying of the coordinate system used in every case is that especially - in combination with having coordinate systems inside deeper branches - makes up for a very versatile, backwards compatible, but powerful system - to express different types of coordinate systems using NeXus. In the case - of two or more instances of NXcoordinate_system in one :ref:`NXcoordinate_system_set`, - it is also advised to specify the relationship between the two coordinate systems by - using the (NXtransformations) group within NXcoordinate_system. - - In effect, 1 should be the preferred choice. However, if more than one coordinate - system is defined for practical purposes, explicit depends_on fields should - always guide the user for each group and field which of the coordinate system - one refers to. - - - - Convention how a positive rotation angle is defined when viewing - from the end of the rotation unit vector towards its origin, - i.e. in accordance with convention 2 of - DOI: 10.1088/0965-0393/23/8/083501. - Counter_clockwise is equivalent to a right-handed choice. - Clockwise is equivalent to a left-handed choice. - - - - - - - - - - How are rotations interpreted into an orientation - according to convention 3 of - DOI: 10.1088/0965-0393/23/8/083501. - - - - - - - - - - How are Euler angles interpreted given that there are several choices (e.g. zxz, xyz) - according to convention 4 of DOI: 10.1088/0965-0393/23/8/083501. - - The most frequently used convention is zxz, which is based on the work of H.-J. Bunge - but other conventions are possible. Apart from undefined, proper Euler angles - are distinguished from (improper) Tait-Bryan angles. - - - - - - - - - - - - - - - - - - - - To which angular range is the rotation angle argument of an - axis-angle pair parameterization constrained according to - convention 5 of DOI: 10.1088/0965-0393/23/8/083501. - - - - - - - - - Which sign convention is followed when converting orientations - between different parameterizations/representations according - to convention 6 of DOI: 10.1088/0965-0393/23/8/083501. - - - - - - - - - - - - - Details about eventually relevant named directions that may give reasons for anisotropies. - The classical example is mechanical processing where one has to specify which directions - (e.g. rolling, transverse, and normal direction) align how with the direction of the base - vectors of the sample_reference_frame. - - It is assumed that the configuration is inspected by looking towards the sample surface. - If a detector is involved, it is assumed that the configuration is inspected from a position - that is located behind this detector. - - If any of these assumptions is not met, the user is required to explicitly state this. - - Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the - base vectors of this coordinate system as Xp, Yp, Zp. - - - - - Details about the sample_reference_frame that is typically overlaid onto the surface of the sample. - - It is assumed that the configuration is inspected by looking towards the sample surface. - If a detector is involved, it is assumed that the configuration is inspected from a position - that is located behind this detector. - - If any of these assumptions is not met, the user is required to explicitly state this. - - Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the - base vectors of this coordinate system as Xs, Ys, Zs. - - - - - Details about the detector_reference_frame for a specific detector. - - Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the - base vectors of this coordinate system as Xd, Yd, Zd. - - It is assumed that the configuration is inspected by looking towards the sample surface - from a position that is located behind the detector. - - If any of these assumptions is not met, the user is required to explicitly state this. - - - diff --git a/base_classes/NXdetector_reference_frame.nxdl.xml b/base_classes/NXdetector_reference_frame.nxdl.xml new file mode 100644 index 0000000000..365d116822 --- /dev/null +++ b/base_classes/NXdetector_reference_frame.nxdl.xml @@ -0,0 +1,52 @@ + + + + + + Details about the detector_reference_frame for a specific detector. + + It is assumed that the configuration is inspected by looking towards + the sample surface from a position that is located behind the detector. + + If any of these assumptions is not met, the user is required to + explicitly state this. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label + the base vectors of this coordinate system as Xd, Yd, Zd. + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/base_classes/NXprocessing_reference_frame.nxdl.xml b/base_classes/NXprocessing_reference_frame.nxdl.xml new file mode 100644 index 0000000000..33c8d91294 --- /dev/null +++ b/base_classes/NXprocessing_reference_frame.nxdl.xml @@ -0,0 +1,60 @@ + + + + + + Details about eventually relevant named directions that may give + reasons for anisotropies. + + The classical example is mechanical processing where one has to + specify which directions (e.g. rolling, transverse, and normal + direction) align how with the direction of the base vectors of the + :ref:`/NXsample_reference_frame </NXsample_reference_frame>`. + + It is assumed that the configuration is inspected by looking towards + the sample surface. If a detector is involved, it is assumed that the + configuration is inspected from a position that is located behind this + detector. + + If any of these assumptions is not met, the user is required to + explicitly state this. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the base + the base vectors of this coordinate system as Xp, Yp, Zp. + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/base_classes/NXrotation_conventions.nxdl.xml b/base_classes/NXrotation_conventions.nxdl.xml new file mode 100644 index 0000000000..a6db3899df --- /dev/null +++ b/base_classes/NXrotation_conventions.nxdl.xml @@ -0,0 +1,114 @@ + + + + + + + Base class to hold different rotation and angle conventions. + + This base class should be used at the top-level (i.e, directly below ``NXentry``) within + an application definition to enable the usage of consistent conventions within one NeXus entry. + + The definitions of these conventions follows those given in Rowenhorst et al 2015 Modelling Simul. Mater. Sci. Eng. 23 083501, + `DOI: 10.1088/0965-0393/23/8/083501`_. + + .. _DOI: 10.1088/0965-0393/23/8/083501: https://www.doi.org/10.1088/0965-0393/23/8/083501 + + + + Convention how a positive rotation angle is defined when viewing + from the end of the rotation unit vector towards its origin, + i.e. in accordance with convention 2 of + DOI: 10.1088/0965-0393/23/8/083501. + Counter_clockwise is equivalent to a right-handed choice. + Clockwise is equivalent to a left-handed choice. + + + + + + + + + + How are rotations interpreted into an orientation + according to convention 3 of + DOI: 10.1088/0965-0393/23/8/083501. + + + + + + + + + + How are Euler angles interpreted given that there are several choices (e.g. zxz, xyz) + according to convention 4 of DOI: 10.1088/0965-0393/23/8/083501. + + The most frequently used convention is zxz, which is based on the work of H.-J. Bunge + but other conventions are possible. Apart from undefined, proper Euler angles + are distinguished from (improper) Tait-Bryan angles. + + + + + + + + + + + + + + + + + + + + To which angular range is the rotation angle argument of an + axis-angle pair parameterization constrained according to + convention 5 of DOI: 10.1088/0965-0393/23/8/083501. + + + + + + + + + Which sign convention is followed when converting orientations + between different parameterizations/representations according + to convention 6 of DOI: 10.1088/0965-0393/23/8/083501. + + + + + + + + diff --git a/base_classes/NXsample_reference_frame.nxdl.xml b/base_classes/NXsample_reference_frame.nxdl.xml new file mode 100644 index 0000000000..a4df45d2f6 --- /dev/null +++ b/base_classes/NXsample_reference_frame.nxdl.xml @@ -0,0 +1,85 @@ + + + + + + Details about the sample reference frame that is typically overlaid + onto the surface of the sample. + + It is assumed that the configuration is inspected by looking towards + the sample surface. If a detector is involved, it is assumed that the + configuration is inspected from a position that is located behind this + detector. + + If any of these assumptions is not met, the user is required to + explicitly state this. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the base + vectors of this coordinate system as Xs, Ys, Zs. + + + + + + + + + + + + + + + + + + + + + Details about the detector_reference_frame for a specific detector. + + It is assumed that the configuration is inspected by looking towards + the sample surface from a position that is located behind the detector. + + If any of these assumptions is not met, the user is required to + explicitly state this. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label + the base vectors of this coordinate system as Xd, Yd, Zd. + + + + + + + + + + + + + + + + + \ No newline at end of file From f047610cce49f1f63b3ec6479605ba6ec4569e4d Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Thu, 16 Jan 2025 14:54:28 +0100 Subject: [PATCH 12/37] port docs of NXcoordinate_system_set to NXcoordinate_system --- base_classes/NXcoordinate_system.nxdl.xml | 112 ++++++++++++++++------ 1 file changed, 83 insertions(+), 29 deletions(-) diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml index fd03bb061d..817aae4df6 100644 --- a/base_classes/NXcoordinate_system.nxdl.xml +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -23,33 +23,88 @@ --> - Base class to detail a coordinate system (CS). - - Whenever possible, an instance of :ref:`NXcoordinate_system` should be used as - a member in an :ref:`NXcoordinate_system_set` and the name of the instance - should be this alias. This may support a process whereby jargon when talking - about coordinate systems and conventions may become cleaner for users - because it is not evident for people outside a lab that terms like e.g. - tip space or specimen space refer to the same coordinate system. - This is an example of jargon used in e.g. the field of atom - probe tomography. + Base class to detail a coordinate system (CS). + + Whenever possible, all instances of :ref:`NXcoordinate_system` + should be used at the top-level (i.e, directly below ``NXentry``) + within an application definition or within a NeXus file. + + How many nodes of type :ref:`NXcoordinate_system` should be used in + an application definition? + + * 0; if there is no instance of `NXcoordinate_system`` across + the application definition, the default NeXus + `McStas <https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html>`_ + coordinate system is assumed. + + McStas is used if no instance of NXcoordinate_system is specified. + However, for the sake of clarity, even in this case it is better + to be explicit like for every other coordinate system definition + to support users with interpreting the content and logic behind + every instance of the tree. + + * 1; if only one :ref:`NXcoordinate_system` is defined, it should be + placed as high up in the node hierarchy (ideally right below an + instance of NXentry) of the application definition tree as possible. + This coordinate system shall be named such that it is clear how this + coordinate system is typically referred to in a community. For the + NeXus McStas coordinate system, it is advised to call it ``mcstas`` + for the sake of improved clarity. + + If this is the case, it is assumed that this ``NXcoordinate_system`` + overwrites the NeXus default McStas coordinate system, i.e. users + can thereby conveniently and explicitly specify the speicific + coordinate system that they wish to use. + + This case has the advantage that it is explicit and faces no + ambiguities. However, in reality typically multiple coordinate + systems have to be mastered especially for complex multi-signal + modality experiments. + + * 2 and more; as soon as more than one :ref:`NXcoordinate_system` + is specified somewhere in the tree, different interpretations are + possible as to which of these coordinate system sets and instances + apply or take preference. + + While these ambiguities should be avoided at all costs, the + opportunity for multiple sets and their instances enables to + have branch-specific coordinate system conventions which are + especially useful for deep classes where multiple scientific + methods are combined or cases where having a definition of global + translation and conversion tables how to convert between + representations in different coordinate systems is not desired + or available for now. + + If this case is realized, the best practice is that in every + case where a coordinate system should be referred to the respective + class has a ``depends_on`` field, which resolves the possible + ambiguities which specific coordinate systems is referred to. + + In the case of two or more instances of ``NXcoordinate_system`` it + is advised to specify the relationship between the two coordinate + systems by using the :ref:`NXtransformations` group within + ``NXcoordinate_system``. + + In any case, users are encouraged to write explicit and clean + ``depends_on`` fields in all groups that encode information for which + the interpretation of coordinate systems is relevant. If these + ``depends_on`` hints are not provided, it is automatically assumed + that all branches (to arbitrary depth) use either the only + ``NXcoordinate_system`` instance in the tree or the application + definition is considered underconstrained. In the latter case, which + should be avoided at all costs, McStas is assumed again. - Human-readable field telling where the origin of this CS is. - Exemplar values could be *left corner of the lab bench*, *door-handle* - *pinhole through which the electron beam exists the pole piece*. - *barycenter of the triangle*, *center of mass of the stone*. + Human-readable field telling where the origin of this CS is. + Exemplar values could be *left corner of the lab bench*, *door handle* + *pinhole through which the electron beam exists the pole piece*. + *barycenter of the triangle*, *center of mass of the stone*. - - An alternative name given to that coordinate system. + An alternative name given to this coordinate system. @@ -66,14 +121,14 @@ enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, fr Handedness of the coordinate system if it is a Cartesian. - + - Possibility to define an alias for the name of the x-axis. + Opportunity to define an alias for the name of the x-axis. @@ -85,10 +140,9 @@ enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, fr Exemplar values could be direction of gravity. - - Base unit vector along the first axis which spans the coordinate system. + Basis unit vector along the first axis which spans the coordinate system. This axis is frequently referred to as the x-axis in real space and the i-axis in reciprocal space. @@ -98,7 +152,7 @@ enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, fr - Possibility to define an alias for the name of the y-axis. + Opportunity to define an alias for the name of the y-axis. @@ -112,7 +166,7 @@ enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, fr - Base unit vector along the second axis which spans the coordinate system. + Basis unit vector along the second axis which spans the coordinate system. This axis is frequently referred to as the y-axis in real space and the j-axis in reciprocal space. @@ -122,7 +176,7 @@ enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, fr - Possibility to define an alias for the name of the z-axis. + Opportunity to define an alias for the name of the z-axis. @@ -136,7 +190,7 @@ enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, fr - Base unit vector along the third axis which spans the coordinate system. + Basis unit vector along the third axis which spans the coordinate system. This axis is frequently referred to as the z-axis in real space and the k-axis in reciprocal space. @@ -146,7 +200,7 @@ enumeration: [undefined, front_top_left, front_top_right, front_bottom_right, fr - This specificies the relation to another coordinate system by pointing to the last + This specifies the relation to another coordinate system by pointing to the last transformation in the transformation chain in the NXtransformations group. From ed272807ce8928013f1648e8d55abb31a67a2a33 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Thu, 16 Jan 2025 14:54:44 +0100 Subject: [PATCH 13/37] clean up docs in NXrotation_conventions --- base_classes/NXrotation_conventions.nxdl.xml | 44 ++++++++++---------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/base_classes/NXrotation_conventions.nxdl.xml b/base_classes/NXrotation_conventions.nxdl.xml index a6db3899df..a658fd03a1 100644 --- a/base_classes/NXrotation_conventions.nxdl.xml +++ b/base_classes/NXrotation_conventions.nxdl.xml @@ -28,22 +28,22 @@ use depends_on field - not attribute - to point to conventions used--> Base class to hold different rotation and angle conventions. - This base class should be used at the top-level (i.e, directly below ``NXentry``) within - an application definition to enable the usage of consistent conventions within one NeXus entry. + This base class should be used at the top-level (i.e, directly below + ``NXentry``) within an application definition to enable the usage of + consistent conventions within one NeXus entry. - The definitions of these conventions follows those given in Rowenhorst et al 2015 Modelling Simul. Mater. Sci. Eng. 23 083501, - `DOI: 10.1088/0965-0393/23/8/083501`_. - - .. _DOI: 10.1088/0965-0393/23/8/083501: https://www.doi.org/10.1088/0965-0393/23/8/083501 + The definitions of these conventions follows those given in + Rowenhorst et al 2015 Modelling Simul. Mater. Sci. Eng. 23 083501, + `DOI: 10.1088/0965-0393/23/8/083501 <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. - Convention how a positive rotation angle is defined when viewing - from the end of the rotation unit vector towards its origin, - i.e. in accordance with convention 2 of - DOI: 10.1088/0965-0393/23/8/083501. - Counter_clockwise is equivalent to a right-handed choice. - Clockwise is equivalent to a left-handed choice. + Convention how a positive rotation angle is defined when viewing + from the end of the rotation unit vector towards its origin, + i.e. in accordance with convention 2 of + DOI: 10.1088/0965-0393/23/8/083501. + Counter_clockwise is equivalent to a right-handed choice. + Clockwise is equivalent to a left-handed choice. @@ -53,9 +53,9 @@ use depends_on field - not attribute - to point to conventions used--> - How are rotations interpreted into an orientation - according to convention 3 of - DOI: 10.1088/0965-0393/23/8/083501. + How are rotations interpreted into an orientation + according to convention 3 of + DOI: 10.1088/0965-0393/23/8/083501. @@ -65,12 +65,14 @@ use depends_on field - not attribute - to point to conventions used--> - How are Euler angles interpreted given that there are several choices (e.g. zxz, xyz) - according to convention 4 of DOI: 10.1088/0965-0393/23/8/083501. - - The most frequently used convention is zxz, which is based on the work of H.-J. Bunge - but other conventions are possible. Apart from undefined, proper Euler angles - are distinguished from (improper) Tait-Bryan angles. + How are Euler angles interpreted given that + there are several choices (e.g. zxz, xyz) + according to convention 4 of DOI: 10.1088/0965-0393/23/8/083501. + + The most frequently used convention is zxz, which is based on the + work of H.-J. Bunge, but other conventions are possible. If any + option other than "undefined" is, proper Euler angles are + distinguished from (improper) Tait-Bryan angles. From dbce912bc602fd719068b2be6b5a31d57559c54d Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Thu, 16 Jan 2025 14:59:21 +0100 Subject: [PATCH 14/37] rebase contributed --- .../NXcoordinate_system_set.nxdl.xml | 137 ++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 contributed_definitions/NXcoordinate_system_set.nxdl.xml diff --git a/contributed_definitions/NXcoordinate_system_set.nxdl.xml b/contributed_definitions/NXcoordinate_system_set.nxdl.xml new file mode 100644 index 0000000000..c2276f3a93 --- /dev/null +++ b/contributed_definitions/NXcoordinate_system_set.nxdl.xml @@ -0,0 +1,137 @@ + + + + + + Container to hold different coordinate systems conventions. + + It is the purpose of this base class to define these conventions and + offer a place to store mappings between different coordinate systems + which are relevant for the interpretation of the data described + by the application definition and base class instances. + + For each Cartesian coordinate system users should use a set of + NXtransformations: + + * These should define the three base vectors. + * The location of the origin. + * The affine transformations which bring each axis of this coordinate system + into registration with the McStas coordinate system. + * Equally, affine transformations should be given for the inverse mapping. + + As an example one may take an experiment or computer simulation where + there is a laboratory (lab) coordinate system, a sample/specimen coordinate + system, a crystal coordinate system, and additional coordinate systems, + which are eventually attached to components of the instrument. + + If no additional transformation is specified in this group or if an + instance of an NXcoordinate_system_set is absent it should be assumed + the so-called McStas coordinate system is used. + + Many application definitions in NeXus refer to this `McStas <https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html>`_ coordinate system. + This is a Cartesian coordinate system whose z axis points along the neutron + propagation axis. The systems y axis is vertical up, while the x axis points + left when looking along the z-axis. Thus, McStas is a right-handed coordinate system. + + Within each NXtransformations a depends_on section is required. The depends_on + field specifies if the coordinate system is the root/reference + (which is indicated by writing "." in the depends_on section.) + + + + + A group of transformations which specify: + + * Three base vectors of the coordinate system. + * Origin of the coordinate system. + * A depends_on keyword. Its value can be "." or the name of an + NXtransformations instance which needs to exist in the + NXcoordinate_system_set instance. + * If the coordinate system is the reference one it has to be named + reference. + + In case of having more than one NXtransformations there has to be for + each additional coordinate system, i.e. the one not the reference: + + * A set of translations and rotations which map each base vector to the reference. + * A set of translations and rotations which map each reference base vector + to the coordinate system. + + The NXtransformations for these mappings need to be formatted + according to the descriptions in NXtransformations. + + + + + + + From 0d1d6631b55a2e3e230df90d0c29faa146ff39b8 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Thu, 16 Jan 2025 15:01:44 +0100 Subject: [PATCH 15/37] remove duplicated definition --- .../NXsample_reference_frame.nxdl.xml | 30 ------------------- 1 file changed, 30 deletions(-) diff --git a/base_classes/NXsample_reference_frame.nxdl.xml b/base_classes/NXsample_reference_frame.nxdl.xml index a4df45d2f6..85f9aa9228 100644 --- a/base_classes/NXsample_reference_frame.nxdl.xml +++ b/base_classes/NXsample_reference_frame.nxdl.xml @@ -52,34 +52,4 @@ - - - - - Details about the detector_reference_frame for a specific detector. - - It is assumed that the configuration is inspected by looking towards - the sample surface from a position that is located behind the detector. - - If any of these assumptions is not met, the user is required to - explicitly state this. - - Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label - the base vectors of this coordinate system as Xd, Yd, Zd. - - - - - - - - - - - - - - - - \ No newline at end of file From 5b585102ce3aa266ea5c35901e22d16abdb3a83a Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Thu, 16 Jan 2025 15:10:33 +0100 Subject: [PATCH 16/37] fix issues with links in nxdl files --- base_classes/NXcoordinate_system.nxdl.xml | 43 +++++++++---------- .../NXprocessing_reference_frame.nxdl.xml | 2 +- 2 files changed, 22 insertions(+), 23 deletions(-) diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml index 817aae4df6..dd2833fbcd 100644 --- a/base_classes/NXcoordinate_system.nxdl.xml +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -34,7 +34,7 @@ * 0; if there is no instance of `NXcoordinate_system`` across the application definition, the default NeXus - `McStas <https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html>`_ + `McStas <https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html>`_ coordinate system is assumed. McStas is used if no instance of NXcoordinate_system is specified. @@ -61,29 +61,28 @@ systems have to be mastered especially for complex multi-signal modality experiments. - * 2 and more; as soon as more than one :ref:`NXcoordinate_system` - is specified somewhere in the tree, different interpretations are - possible as to which of these coordinate system sets and instances - apply or take preference. + * 2 and more; as soon as more than one :ref:`NXcoordinate_system` + is specified somewhere in the tree, different interpretations are + possible as to which of these coordinate system sets and instances + apply or take preference. + While these ambiguities should be avoided at all costs, the + opportunity for multiple sets and their instances enables to + have branch-specific coordinate system conventions which are + especially useful for deep classes where multiple scientific + methods are combined or cases where having a definition of global + translation and conversion tables how to convert between + representations in different coordinate systems is not desired + or available for now. - While these ambiguities should be avoided at all costs, the - opportunity for multiple sets and their instances enables to - have branch-specific coordinate system conventions which are - especially useful for deep classes where multiple scientific - methods are combined or cases where having a definition of global - translation and conversion tables how to convert between - representations in different coordinate systems is not desired - or available for now. + If this case is realized, the best practice is that in every + case where a coordinate system should be referred to the respective + class has a ``depends_on`` field, which resolves the possible + ambiguities which specific coordinate systems is referred to. - If this case is realized, the best practice is that in every - case where a coordinate system should be referred to the respective - class has a ``depends_on`` field, which resolves the possible - ambiguities which specific coordinate systems is referred to. - - In the case of two or more instances of ``NXcoordinate_system`` it - is advised to specify the relationship between the two coordinate - systems by using the :ref:`NXtransformations` group within - ``NXcoordinate_system``. + In the case of two or more instances of ``NXcoordinate_system`` it + is advised to specify the relationship between the two coordinate + systems by using the :ref:`NXtransformations` group within + ``NXcoordinate_system``. In any case, users are encouraged to write explicit and clean ``depends_on`` fields in all groups that encode information for which diff --git a/base_classes/NXprocessing_reference_frame.nxdl.xml b/base_classes/NXprocessing_reference_frame.nxdl.xml index 33c8d91294..a0daa15950 100644 --- a/base_classes/NXprocessing_reference_frame.nxdl.xml +++ b/base_classes/NXprocessing_reference_frame.nxdl.xml @@ -29,7 +29,7 @@ The classical example is mechanical processing where one has to specify which directions (e.g. rolling, transverse, and normal direction) align how with the direction of the base vectors of the - :ref:`/NXsample_reference_frame </NXsample_reference_frame>`. + :ref:`NXsample_reference_frame`. It is assumed that the configuration is inspected by looking towards the sample surface. If a detector is involved, it is assumed that the From 65317357bb3b08bf41a06f9bbda7a406644ce47b Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Thu, 16 Jan 2025 16:09:56 +0100 Subject: [PATCH 17/37] remove specified coordinate systems for EM/APM --- .../NXdetector_reference_frame.nxdl.xml | 52 ---------------- .../NXprocessing_reference_frame.nxdl.xml | 60 ------------------- .../NXsample_reference_frame.nxdl.xml | 55 ----------------- 3 files changed, 167 deletions(-) delete mode 100644 base_classes/NXdetector_reference_frame.nxdl.xml delete mode 100644 base_classes/NXprocessing_reference_frame.nxdl.xml delete mode 100644 base_classes/NXsample_reference_frame.nxdl.xml diff --git a/base_classes/NXdetector_reference_frame.nxdl.xml b/base_classes/NXdetector_reference_frame.nxdl.xml deleted file mode 100644 index 365d116822..0000000000 --- a/base_classes/NXdetector_reference_frame.nxdl.xml +++ /dev/null @@ -1,52 +0,0 @@ - - - - - - Details about the detector_reference_frame for a specific detector. - - It is assumed that the configuration is inspected by looking towards - the sample surface from a position that is located behind the detector. - - If any of these assumptions is not met, the user is required to - explicitly state this. - - Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label - the base vectors of this coordinate system as Xd, Yd, Zd. - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/base_classes/NXprocessing_reference_frame.nxdl.xml b/base_classes/NXprocessing_reference_frame.nxdl.xml deleted file mode 100644 index a0daa15950..0000000000 --- a/base_classes/NXprocessing_reference_frame.nxdl.xml +++ /dev/null @@ -1,60 +0,0 @@ - - - - - - Details about eventually relevant named directions that may give - reasons for anisotropies. - - The classical example is mechanical processing where one has to - specify which directions (e.g. rolling, transverse, and normal - direction) align how with the direction of the base vectors of the - :ref:`NXsample_reference_frame`. - - It is assumed that the configuration is inspected by looking towards - the sample surface. If a detector is involved, it is assumed that the - configuration is inspected from a position that is located behind this - detector. - - If any of these assumptions is not met, the user is required to - explicitly state this. - - Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the base - the base vectors of this coordinate system as Xp, Yp, Zp. - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/base_classes/NXsample_reference_frame.nxdl.xml b/base_classes/NXsample_reference_frame.nxdl.xml deleted file mode 100644 index 85f9aa9228..0000000000 --- a/base_classes/NXsample_reference_frame.nxdl.xml +++ /dev/null @@ -1,55 +0,0 @@ - - - - - - Details about the sample reference frame that is typically overlaid - onto the surface of the sample. - - It is assumed that the configuration is inspected by looking towards - the sample surface. If a detector is involved, it is assumed that the - configuration is inspected from a position that is located behind this - detector. - - If any of these assumptions is not met, the user is required to - explicitly state this. - - Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the base - vectors of this coordinate system as Xs, Ys, Zs. - - - - - - - - - - - - - - - - - \ No newline at end of file From 406caf3a68dcb72bac1fc183c8e1d97394b43a46 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Thu, 13 Feb 2025 17:28:14 +0100 Subject: [PATCH 18/37] typo fix --- base_classes/NXcoordinate_system.nxdl.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml index dd2833fbcd..eb6bd71a39 100644 --- a/base_classes/NXcoordinate_system.nxdl.xml +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -97,7 +97,7 @@ Human-readable field telling where the origin of this CS is. Exemplar values could be *left corner of the lab bench*, *door handle* - *pinhole through which the electron beam exists the pole piece*. + *pinhole through which the electron beam exits the pole piece*, *barycenter of the triangle*, *center of mass of the stone*. From ec693446b8515198f1c7a795bd561fafff5599f3 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Thu, 13 Feb 2025 17:33:52 +0100 Subject: [PATCH 19/37] remove NXcoordinate_system/alias --- base_classes/NXcoordinate_system.nxdl.xml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml index eb6bd71a39..50ab6dc26c 100644 --- a/base_classes/NXcoordinate_system.nxdl.xml +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -101,11 +101,6 @@ *barycenter of the triangle*, *center of mass of the stone*. - - - An alternative name given to this coordinate system. - - Coordinate system type. From b40467dec2615338913dd7fefe9d38913c9bd7b9 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Thu, 13 Feb 2025 17:40:14 +0100 Subject: [PATCH 20/37] use consistent underscores --- base_classes/NXcoordinate_system.nxdl.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml index 50ab6dc26c..b4a81f4818 100644 --- a/base_classes/NXcoordinate_system.nxdl.xml +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -115,7 +115,7 @@ Handedness of the coordinate system if it is a Cartesian. - + From 4465edfbae9cba51f67b7c9c43fc8b82e8e473ee Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Fri, 14 Feb 2025 10:27:04 +0100 Subject: [PATCH 21/37] use hyperreferences in NXrotation_conventions --- base_classes/NXrotation_conventions.nxdl.xml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/base_classes/NXrotation_conventions.nxdl.xml b/base_classes/NXrotation_conventions.nxdl.xml index a658fd03a1..1867415d5c 100644 --- a/base_classes/NXrotation_conventions.nxdl.xml +++ b/base_classes/NXrotation_conventions.nxdl.xml @@ -55,7 +55,7 @@ use depends_on field - not attribute - to point to conventions used--> How are rotations interpreted into an orientation according to convention 3 of - DOI: 10.1088/0965-0393/23/8/083501. + `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. @@ -67,7 +67,8 @@ use depends_on field - not attribute - to point to conventions used--> How are Euler angles interpreted given that there are several choices (e.g. zxz, xyz) - according to convention 4 of DOI: 10.1088/0965-0393/23/8/083501. + according to convention 4 of + `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. The most frequently used convention is zxz, which is based on the work of H.-J. Bunge, but other conventions are possible. If any @@ -94,7 +95,7 @@ use depends_on field - not attribute - to point to conventions used--> To which angular range is the rotation angle argument of an axis-angle pair parameterization constrained according to - convention 5 of DOI: 10.1088/0965-0393/23/8/083501. + convention 5 of `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. @@ -105,7 +106,7 @@ use depends_on field - not attribute - to point to conventions used--> Which sign convention is followed when converting orientations between different parameterizations/representations according - to convention 6 of DOI: 10.1088/0965-0393/23/8/083501. + to equation 14 of `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. From e58aca445a53f1267d2ff331600b4c8ea91bb501 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Fri, 14 Feb 2025 10:34:24 +0100 Subject: [PATCH 22/37] remove undefined as option from NXrotation_conventions --- base_classes/NXrotation_conventions.nxdl.xml | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/base_classes/NXrotation_conventions.nxdl.xml b/base_classes/NXrotation_conventions.nxdl.xml index 1867415d5c..68c59a5178 100644 --- a/base_classes/NXrotation_conventions.nxdl.xml +++ b/base_classes/NXrotation_conventions.nxdl.xml @@ -46,7 +46,6 @@ use depends_on field - not attribute - to point to conventions used--> Clockwise is equivalent to a left-handed choice. - @@ -58,7 +57,6 @@ use depends_on field - not attribute - to point to conventions used--> `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. - @@ -71,12 +69,11 @@ use depends_on field - not attribute - to point to conventions used--> `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. The most frequently used convention is zxz, which is based on the - work of H.-J. Bunge, but other conventions are possible. If any - option other than "undefined" is, proper Euler angles are - distinguished from (improper) Tait-Bryan angles. + work of H.-J. Bunge, but other conventions are possible. By definining + this convention, proper Euler angles are distinguished from (improper) + Tait-Bryan angles. - @@ -98,7 +95,6 @@ use depends_on field - not attribute - to point to conventions used--> convention 5 of `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. - @@ -109,7 +105,6 @@ use depends_on field - not attribute - to point to conventions used--> to equation 14 of `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. - From 4c7d3a89fd0ddfa8531d130048861bc18df9fddd Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Fri, 14 Feb 2025 10:36:25 +0100 Subject: [PATCH 23/37] Apply suggestions from code review Co-authored-by: Peter Chang --- base_classes/NXcoordinate_system.nxdl.xml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml index b4a81f4818..e4762fd0d7 100644 --- a/base_classes/NXcoordinate_system.nxdl.xml +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -29,7 +29,7 @@ should be used at the top-level (i.e, directly below ``NXentry``) within an application definition or within a NeXus file. - How many nodes of type :ref:`NXcoordinate_system` should be used in + How many groups of type :ref:`NXcoordinate_system` should be used in an application definition? * 0; if there is no instance of `NXcoordinate_system`` across @@ -44,7 +44,7 @@ every instance of the tree. * 1; if only one :ref:`NXcoordinate_system` is defined, it should be - placed as high up in the node hierarchy (ideally right below an + placed as high up in the tree hierarchy (ideally right below an instance of NXentry) of the application definition tree as possible. This coordinate system shall be named such that it is clear how this coordinate system is typically referred to in a community. For the @@ -53,30 +53,30 @@ If this is the case, it is assumed that this ``NXcoordinate_system`` overwrites the NeXus default McStas coordinate system, i.e. users - can thereby conveniently and explicitly specify the speicific + can thereby conveniently and explicitly specify the coordinate system that they wish to use. - This case has the advantage that it is explicit and faces no + This case has the advantage that it is explicit and offers no ambiguities. However, in reality typically multiple coordinate systems have to be mastered especially for complex multi-signal modality experiments. * 2 and more; as soon as more than one :ref:`NXcoordinate_system` is specified somewhere in the tree, different interpretations are - possible as to which of these coordinate system sets and instances + possible as to which of these coordinate systems apply or take preference. While these ambiguities should be avoided at all costs, the opportunity for multiple sets and their instances enables to have branch-specific coordinate system conventions which are - especially useful for deep classes where multiple scientific + especially useful for deep groups where multiple scientific methods are combined or cases where having a definition of global - translation and conversion tables how to convert between + conversion tables how to convert between representations in different coordinate systems is not desired or available for now. If this case is realized, the best practice is that in every case where a coordinate system should be referred to the respective - class has a ``depends_on`` field, which resolves the possible + group has a ``depends_on`` field, which resolves the possible ambiguities which specific coordinate systems is referred to. In the case of two or more instances of ``NXcoordinate_system`` it From b3333b24eb8490e6c722454a05ed6c9e79ebdff5 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Fri, 14 Feb 2025 10:48:11 +0100 Subject: [PATCH 24/37] use more precise language for coordinate system docs --- base_classes/NXcoordinate_system.nxdl.xml | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml index e4762fd0d7..f81a34af8b 100644 --- a/base_classes/NXcoordinate_system.nxdl.xml +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -65,12 +65,12 @@ is specified somewhere in the tree, different interpretations are possible as to which of these coordinate systems apply or take preference. - While these ambiguities should be avoided at all costs, the - opportunity for multiple sets and their instances enables to - have branch-specific coordinate system conventions which are - especially useful for deep groups where multiple scientific - methods are combined or cases where having a definition of global - conversion tables how to convert between + While these ambiguities should be avoided if possible, the + opportunity for multiples instances enables to have coordinate + system conventions that are specific for some part of the NeXus + tree. This is especially useful for deep groups where + multiple scientific methods are combined or cases where having a + definition of global conversion tables how to convert between representations in different coordinate systems is not desired or available for now. @@ -90,8 +90,10 @@ ``depends_on`` hints are not provided, it is automatically assumed that all branches (to arbitrary depth) use either the only ``NXcoordinate_system`` instance in the tree or the application - definition is considered underconstrained. In the latter case, which - should be avoided at all costs, McStas is assumed again. + definition is considered underconstrained. In the latter case, + which ideally should be avoided, McStas is assumed again. Note that + this is the case for all files that were created before ``NXcoordinate_system`` + was added. From f07acee42f6d6e1673628c6a095a414c2e7d6d4c Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Fri, 14 Feb 2025 12:03:56 +0100 Subject: [PATCH 25/37] add hyperreference --- base_classes/NXrotation_conventions.nxdl.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/base_classes/NXrotation_conventions.nxdl.xml b/base_classes/NXrotation_conventions.nxdl.xml index 68c59a5178..595b1cae74 100644 --- a/base_classes/NXrotation_conventions.nxdl.xml +++ b/base_classes/NXrotation_conventions.nxdl.xml @@ -69,9 +69,9 @@ use depends_on field - not attribute - to point to conventions used--> `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. The most frequently used convention is zxz, which is based on the - work of H.-J. Bunge, but other conventions are possible. By definining - this convention, proper Euler angles are distinguished from (improper) - Tait-Bryan angles. + `work of H.-J. Bunge <https://doi.org/10.1016/C2013-0-11769-2>`_, + but other conventions are possible. By definining this convention, proper Euler + angles are distinguished from (improper) Tait-Bryan angles. From 3e8ab32e7bbf9b528a2f16345615598329302445 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Mon, 14 Apr 2025 09:05:43 +0200 Subject: [PATCH 26/37] remove NXrotation_conventions for now --- base_classes/NXcoordinate_system.nxdl.xml | 64 +++++------ base_classes/NXrotation_conventions.nxdl.xml | 112 ------------------- 2 files changed, 32 insertions(+), 144 deletions(-) delete mode 100644 base_classes/NXrotation_conventions.nxdl.xml diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml index f81a34af8b..61ac6bef2e 100644 --- a/base_classes/NXcoordinate_system.nxdl.xml +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -105,7 +105,7 @@ - Coordinate system type. + Coordinate system type. @@ -114,7 +114,7 @@ - Handedness of the coordinate system if it is a Cartesian. + Handedness of the coordinate system if it is a Cartesian. @@ -124,23 +124,23 @@ - Opportunity to define an alias for the name of the x-axis. + Opportunity to define an alias for the name of the x-axis. - Human-readable field telling in which direction the x-axis points if that - instance of :ref:`NXcoordinate_system` has no reference to any parent and as such - is the mighty world reference frame. - - Exemplar values could be direction of gravity. + Human-readable field telling in which direction the x-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + Exemplar values could be direction of gravity. - Basis unit vector along the first axis which spans the coordinate system. + Basis unit vector along the first axis which spans the coordinate system. This axis is frequently referred to as the x-axis in real space and - the i-axis in reciprocal space. + the i-axis in reciprocal space. @@ -148,23 +148,23 @@ - Opportunity to define an alias for the name of the y-axis. + Opportunity to define an alias for the name of the y-axis. - Human-readable field telling in which direction the y-axis points if that - instance of :ref:`NXcoordinate_system` has no reference to any parent and as such - is the mighty world reference frame. - - See docstring of ``x_direction`` for further details. + Human-readable field telling in which direction the y-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + See docstring of ``x_direction`` for further details. - Basis unit vector along the second axis which spans the coordinate system. - This axis is frequently referred to as the y-axis in real space and - the j-axis in reciprocal space. + Basis unit vector along the second axis which spans the coordinate system. + This axis is frequently referred to as the y-axis in real space and + the j-axis in reciprocal space. @@ -172,23 +172,23 @@ - Opportunity to define an alias for the name of the z-axis. + Opportunity to define an alias for the name of the z-axis. - Human-readable field telling in which direction the z-axis points if that - instance of :ref:`NXcoordinate_system` has no reference to any parent and as such - is the mighty world reference frame. - - See docstring of x_alias for further details. + Human-readable field telling in which direction the z-axis points if that + instance of :ref:`NXcoordinate_system` has no reference to any parent and as such + is the mighty world reference frame. + + See docstring of x_alias for further details. - Basis unit vector along the third axis which spans the coordinate system. - This axis is frequently referred to as the z-axis in real space and - the k-axis in reciprocal space. + Basis unit vector along the third axis which spans the coordinate system. + This axis is frequently referred to as the z-axis in real space and + the k-axis in reciprocal space. @@ -196,14 +196,14 @@ - This specifies the relation to another coordinate system by pointing to the last - transformation in the transformation chain in the NXtransformations group. + This specifies the relation to another coordinate system by pointing to the last + transformation in the transformation chain in the NXtransformations group. - Collection of axis-based translations and rotations to describe this coordinate system - with respect to another coordinate system. + Collection of axis-based translations and rotations to describe this coordinate system + with respect to another coordinate system. diff --git a/base_classes/NXrotation_conventions.nxdl.xml b/base_classes/NXrotation_conventions.nxdl.xml deleted file mode 100644 index 595b1cae74..0000000000 --- a/base_classes/NXrotation_conventions.nxdl.xml +++ /dev/null @@ -1,112 +0,0 @@ - - - - - - - Base class to hold different rotation and angle conventions. - - This base class should be used at the top-level (i.e, directly below - ``NXentry``) within an application definition to enable the usage of - consistent conventions within one NeXus entry. - - The definitions of these conventions follows those given in - Rowenhorst et al 2015 Modelling Simul. Mater. Sci. Eng. 23 083501, - `DOI: 10.1088/0965-0393/23/8/083501 <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. - - - - Convention how a positive rotation angle is defined when viewing - from the end of the rotation unit vector towards its origin, - i.e. in accordance with convention 2 of - DOI: 10.1088/0965-0393/23/8/083501. - Counter_clockwise is equivalent to a right-handed choice. - Clockwise is equivalent to a left-handed choice. - - - - - - - - - How are rotations interpreted into an orientation - according to convention 3 of - `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. - - - - - - - - - How are Euler angles interpreted given that - there are several choices (e.g. zxz, xyz) - according to convention 4 of - `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. - - The most frequently used convention is zxz, which is based on the - `work of H.-J. Bunge <https://doi.org/10.1016/C2013-0-11769-2>`_, - but other conventions are possible. By definining this convention, proper Euler - angles are distinguished from (improper) Tait-Bryan angles. - - - - - - - - - - - - - - - - - - - To which angular range is the rotation angle argument of an - axis-angle pair parameterization constrained according to - convention 5 of `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. - - - - - - - - Which sign convention is followed when converting orientations - between different parameterizations/representations according - to equation 14 of `Rowenhorst et al. <https://www.doi.org/10.1088/0965-0393/23/8/083501>`_. - - - - - - - From 83e7b0cfdef9bb562c5dd655b6b924131cad73d3 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Mon, 14 Apr 2025 10:59:22 +0200 Subject: [PATCH 27/37] remove handedness --- base_classes/NXcoordinate_system.nxdl.xml | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml index 61ac6bef2e..5f5392390d 100644 --- a/base_classes/NXcoordinate_system.nxdl.xml +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -112,16 +112,6 @@ - - - Handedness of the coordinate system if it is a Cartesian. - - - - - - - Opportunity to define an alias for the name of the x-axis. From 58f61972a7b5c7bcca8a8085149cdb59de70ddc6 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Mon, 14 Apr 2025 11:21:46 +0200 Subject: [PATCH 28/37] add explicit between CS and transformations --- base_classes/NXcomponent.nxdl.xml | 8 ++++++-- base_classes/NXcoordinate_system.nxdl.xml | 11 ++++++++++- base_classes/NXtransformations.nxdl.xml | 17 +++++++++++++---- 3 files changed, 29 insertions(+), 7 deletions(-) diff --git a/base_classes/NXcomponent.nxdl.xml b/base_classes/NXcomponent.nxdl.xml index f9a0b7dec6..7a178cceaa 100644 --- a/base_classes/NXcomponent.nxdl.xml +++ b/base_classes/NXcomponent.nxdl.xml @@ -77,8 +77,12 @@ to apply to the component starting from 0, 0, 0. The order of these operations is critical and forms what NeXus calls a dependency chain. The depends_on field defines the path to the top most operation of the dependency chain or the - string "." if located in the origin. Usually these operations are stored in a - NXtransformations group. But NeXus allows them to be stored anywhere. + string "." if located in the origin. The depends_on can also point to an instance + of ``NX_coordinate_system`` if the transformations of the component depend on that + coordinate system. + + Usually these operations are stored in a NXtransformations group. + But NeXus allows them to be stored anywhere. diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml index 5f5392390d..c53ef31f8d 100644 --- a/base_classes/NXcoordinate_system.nxdl.xml +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -25,6 +25,12 @@ Base class to detail a coordinate system (CS). + Instances of ``NXcoordinate_system`` can be used to describe coordinate systems + other than the default `NeXus coordinate system <https://manual.nexusformat.org/design.html#the-nexus-coordinate-system>`_. + + ``NXcoordinate_system`` can be part of the transformations chain using :ref:`NXtransformations`, where it acts as a linear change-of-basis + transformation (using a 3x3 matrix with the basis vectors ``x``, ``y``, and ``z`` as columns). + Whenever possible, all instances of :ref:`NXcoordinate_system` should be used at the top-level (i.e, directly below ``NXentry``) within an application definition or within a NeXus file. @@ -129,8 +135,11 @@ Basis unit vector along the first axis which spans the coordinate system. - This axis is frequently referred to as the x-axis in real space and + This axis is frequently referred to as the x-axis in real space and the i-axis in reciprocal space. + + Note that `x``, ``y``, and ``z`` must constitute a basis, i.e., a set of linearly + independent vectors that span the vector space. diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index c173cab4e3..dcf521de14 100644 --- a/base_classes/NXtransformations.nxdl.xml +++ b/base_classes/NXtransformations.nxdl.xml @@ -60,10 +60,10 @@ type has been specified. The entry point (``depends_on``) will be outside of this class and point to a - field in here. Following the chain may also require following ``depends_on`` - links to transformations outside, for example to a common base table. If - a relative path is given, it is relative to the group enclosing the ``depends_on`` - specification. + field in here (or to an instance of ``NX_coordinate_system``). Following the + chain may also require following ``depends_on`` links to transformations outside, + for example to a common base table. If a relative path is given, it is relative + to the group enclosing the ``depends_on`` specification. For a chain of three transformations, where :math:`T_1` depends on :math:`T_2` and that in turn depends on :math:`T_3`, the final transformation :math:`T_f` is @@ -108,6 +108,15 @@ * depends_on as needed. + + NOTE + + NXtransformations follows the **active** transformation convention. This means that the transformation describes + how an object is moved or rotated within the coordinate system. In other words, the transformation + actively changes the position or orientation of the object itself, rather than altering the coordinate system in + which the object is described. This is in contrast to a **passive** transformation, which changes the frame of reference + or coordinate system, while the object remains fixed. In case it is needed to describe multiple coordinate system, + it is strongly suggested to use the :ref:`NXcoordinate_system` base class. From ee872b522a39c28ce83dcd073f60c01ef6d39437 Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Mon, 14 Apr 2025 14:15:41 +0200 Subject: [PATCH 29/37] connect transformations and coordinate systems --- base_classes/NXcoordinate_system.nxdl.xml | 49 ++++++++++++++--------- base_classes/NXtransformations.nxdl.xml | 10 +++-- 2 files changed, 37 insertions(+), 22 deletions(-) diff --git a/base_classes/NXcoordinate_system.nxdl.xml b/base_classes/NXcoordinate_system.nxdl.xml index c53ef31f8d..f6dc8b2dc7 100644 --- a/base_classes/NXcoordinate_system.nxdl.xml +++ b/base_classes/NXcoordinate_system.nxdl.xml @@ -3,7 +3,7 @@