2.3.3.1.53. NXtransformations¶
Status:
base class, extends NXobject
Description:
Collection of axis-based translations and rotations to describe a geometry. ...
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 attributeunits="NX_TRANSFORMATION"
designates the units will be appropriate to thetransformation_type
attribute:
NX_LENGTH
fortranslation
NX_ANGLE
forrotation
NX_UNITLESS
for axes for which no transformation type is specifiedThis 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.
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 followingdepends_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 thedepends_on
specification.For a chain of three transformations, where \(T_1\) depends on \(T_2\) which in turn depends on \(T_3\), the final active transformation matrix \(T_f\) is
\[T_f = T_3 . T_2 . T_1\]For example when positioning a flat detector, its pixel positions in the laboratory reference frame (McSTAS coordinate frame by default) can be calculated by
\[X_\text{lab} = T_f . X_\text{pixel} = T_3 . T_2 . T_1 . X_\text{pixel}\]Note that \(T_1\) comes first in the depends-on chain and is also applied first to the pixel coordinates.
When we say transformation \(A\) depends on transformation \(B\) we mean that the physical motor that realizes \(A\) is stacked on top of the motor that realizes \(B\). So the activate coordinate transformation \(A\) needs to be applied to a coordinate before applying \(B\). In other words \(X' = B . A . X\).
Transformation matrix
In explicit terms, the transformations are a subset of affine transformations expressed as 4x4 active transformation matrices that act on homogeneous coordinates, \(X=[x,y,z,1]^T\).
For rotation and translation,
\[\begin{split}T_r &= \begin{pmatrix} R & o \\ 0_3 & 1 \end{pmatrix} \\ T_t &= \begin{pmatrix} I_3 & t + o \\ 0_3 & 1 \end{pmatrix}\end{split}\]where \(R\) is the usual 3x3 rotation matrix, \(o\) is an offset vector, \(0_3\) is a row of 3 zeros, \(I_3\) is the 3x3 identity matrix and \(t\) is the translation vector.
\(o\) is given by the
offset
attribute, \(t\) is given by thevector
attribute multiplied by the field value, and \(R\) is defined as a rotation about an axis in the direction ofvector
, 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 theNXinstrument
base class. Use oneNXtransformations
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 McSTAS coordinate frame.
The sample is oriented as follows
\[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
\(R(\vec{v},a)\) is a rotation around vector \(\vec{v}\) with angle \(a\)
\(T(\vec{u},t)\) is a translation along vector \(\vec{u}\) over a distance \(t\)
\(X_s\) a coordinate in the sample reference frame.
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=degreesExample 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: \(X_\text{lab} = T_x(20) . X_d\)
vertical: \(X_\text{lab} = R_y(-5) . T_x(10) . X_d\)
horizontal: \(X_\text{lab} = R_x(-90) . R_y(-6) . T_x(11) . X_d\)
where
\(T_x\), \(T_y\), \(T_z\): active transformation matrices for translation along the X, Y and Z axes
\(R_x\), \(R_y\), \(R_z\): active transformation matrices for rotation around the X, Y and Z axes
\(X_d\) is a coordinate in the detector reference frame.
Note that as these are point detectors, we only have one coordinate \(X_d=[0,0,0,1]^T\).
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
Symbols:
No symbol table
- Groups cited:
none
Structure:
@default: (optional) NX_CHAR
Declares which child group contains a path leading ...
Declares which child group contains a path leading to a 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.
AXISNAME: (optional) NX_NUMBER {units=NX_TRANSFORMATION}
Units need to be appropriate for translation or rotation ...
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
.@transformation_type: (optional) NX_CHAR
The transformation_type may be ``translation``, in which case the ...
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.
Any of these values:
translation
|rotation
@vector: (optional) NX_NUMBER
Three values that define the axis for this transformation. ...
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. Fortranslation
axes the direction should be chosen for increasing displacement. For general axes, an appropriate direction should be chosen.@offset: (optional) NX_NUMBER
A fixed offset applied before the transformation (three vector components). ...
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.@offset_units: (optional) NX_CHAR
Units of the offset. Values should be consistent with NX_LENGTH.
@depends_on: (optional) NX_CHAR
Points to the path of a field defining the axis on which this 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.@equipment_component: (optional) NX_CHAR
An arbitrary identifier of a component of the equipment to which ...
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: (optional) NX_NUMBER {units=NX_TRANSFORMATION}
``AXISNAME_end`` is a placeholder for a name constructed from the actual ...
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: (optional) NX_NUMBER {units=NX_TRANSFORMATION}
``AXISNAME_increment_set`` is a placeholder for a name constructed from the ac ...
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 ofAXISNAME_end
, but there is a possibility of significant differences. Use ofAXISNAME_end
is recommended.
Hypertext Anchors¶
List of hypertext anchors for all groups, fields, attributes, and links defined in this class.