3.3.1.53. NXtransformations

Status:

base class, extends NXobject

Description:

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 offset 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. 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 McSTAS coordinate frame 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.

For a chain of three transformations, where \(T_1\) depends on \(T_2\) and that in turn depends on \(T_3\), the final transformation \(T_f\) is

\[T_f = T_3 T_2 T_1\]

In explicit terms, the transformations are a subset of affine transformations expressed as 4x4 matrices that act on homogeneous coordinates, \(w=(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 the offset attribute, \(t\) is given by the vector attribute multiplied by the field value, and \(R\) is defined as a rotation about an axis in the direction of vector, of angle of the field value.

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 for each diffractometer and name the group appropriate to the device. Collecting the motors of a sample table or xyz-stage in an NXtransformation group is equally possible.

Symbols:

No symbol table

Groups cited:

none

Structure:

AXISNAME: (optional) NX_NUMBER {units=NX_TRANSFORMATION}

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 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. 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.

@offset: (optional) NX_NUMBER

A fixed offset applied before the transformation (three vector components).

@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 to a field defining the axis on which this depends or the string ”.”.

AXISNAME_end: (optional) NX_NUMBER {units=NX_TRANSFORMATION}

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 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.

NXDL Source:

https://github.com/nexusformat/definitions/blob/master/base_classes/NXtransformations.nxdl.xml