.. auto-generated by script ../../../../utils/nxdl2rst.py from the NXDL source NXtransformations.nxdl.xml

.. index::
    ! NXtransformations (contributed definition)
    ! transformations (contributed definition)
    see: transformations (contributed definition); NXtransformations

.. _NXtransformations:

=================
NXtransformations
=================

**Status**:

  contributed definition, extends :ref:`NXobject`, version 1.1

**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 all-caps name ``AXISUNITS`` designates the
  units appropriate to the transformation_type value, i.e. ``NX_LENGTH`` for
  ``translation``, ``NX_ANGLE`` for ``rotation``, and ``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.

  ..
  	Given an entry point :math:`\vec{p_i}`, the point :math:`\vec{p_{i+1}}` 
  	resulting from the next transformation (the field in this group named 
  	in the ``depends_on`` attribute of the entry point)
  	may be expressed:

  	.. math::

  		\vec{p_{i+1}} = \vec{o_{i}} + \vec{V_{i}} * \vec{p_{i}}

  	where :math`\vec{o_{i}}` is the vector given in the ``@offset`` attribute
  	and  :math`\vec{V_{i}}` is the vector given in the ``@vector`` attribute

  TODO: this needs an equation (issue #484)

**Symbols**:

  No symbol table

**Groups cited**:
  none

**Structure**:

  .. index:: AXISNAME (field)

  **AXISNAME**: :ref:`NX_NUMBER <NX_NUMBER>` {units=AXISUNITS}

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

    .. index:: transformation type (field attribute)

    **@transformation_type**: :ref:`NX_CHAR <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``

    .. index:: vector (field attribute)

    **@vector**: :ref:`NX_NUMBER <NX_NUMBER>` {units=\ :ref:`NX_DIMENSIONLESS <NX_DIMENSIONLESS>`}

      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.

    .. index:: offset (field attribute)

    **@offset**: :ref:`NX_NUMBER <NX_NUMBER>`

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

    .. index:: offset units (field attribute)

    **@offset_units**: :ref:`NX_CHAR <NX_CHAR>`

      Units of the offset.  Values should be consistent with NX_LENGTH.

    .. index:: depends on (field attribute)

    **@depends_on**: :ref:`NX_CHAR <NX_CHAR>`

      Points to the path to a field defining the axis on which this
      depends or the string ".".

  .. index:: AXISNAME end (field)

  **AXISNAME_end**: (optional) :ref:`NX_NUMBER <NX_NUMBER>` {units=AXISUNITS}

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

  .. index:: AXISNAME increment set (field)

  **AXISNAME_increment_set**: (optional) :ref:`NX_NUMBER <NX_NUMBER>` {units=AXISUNITS}

    ``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/contributed_definitions/NXtransformations.nxdl.xml