<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="nxdlformat.xsl" ?>
<!--
# NeXus - Neutron and X-ray Common Data Format
#
# Copyright (C) 2014-2016 NeXus International Advisory Committee (NIAC)
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 3 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
# For further information, see http://www.nexusformat.org
-->
<definition xmlns="http://definition.nexusformat.org/nxdl/3.1"
category="contributed"
name="NXtransformations"
version="1.1"
type="group"
extends="NXobject"
ignoreExtraGroups="true"
ignoreExtraFields="true"
ignoreExtraAttributes="true"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
>
<!--
nxdl.xsd rules do not allow us to show this as a variable name
- we'll use AXISNAME in ALL CAPS for consistency with the
use in NXDATA. We'll use ``AXISUNITS`` for the units appropriate
to the type of axis.
-->
<doc>
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)
</doc>
<!-- see: http://wiki.nexusformat.org/Main_Page/NXdetector_2012_10
This entire explanation is not clear.
-->
<field name="AXISNAME" nameType="any" units="AXISUNITS" type="NX_NUMBER" maxOccurs="unbounded">
<doc>
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``.
</doc>
<attribute name="transformation_type" minOccurs="0">
<doc>
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.
</doc>
<enumeration>
<item value="translation" />
<item value="rotation" />
<!-- <item value="general" /> -->
</enumeration>
</attribute>
<attribute name="vector" units="NX_DIMENSIONLESS" type="NX_NUMBER">
<doc>
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.
</doc>
<dimensions rank="1" value="3" />
</attribute>
<attribute name="offset" type="NX_NUMBER">
<doc>
A fixed offset applied before the transformation (three vector components).
</doc>
<dimensions rank="1" value="3" />
</attribute>
<attribute name="offset_units" type="NX_CHAR">
<doc>
Units of the offset. Values should be consistent with NX_LENGTH.
</doc>
</attribute>
<attribute name="depends_on" type="NX_CHAR">
<doc>
Points to the path to a field defining the axis on which this
depends or the string ".".
</doc>
</attribute>
</field>
<field name="AXISNAME_end" units="AXISUNITS" nameType="any" type="NX_NUMBER" minOccurs="0">
<doc>
``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.
</doc>
</field>
<!-- as per NIAC discussion, 13 Oct 2016, we have removed AXISNAME_range as duplicative.
<field name="AXISNAME_range" units="AXISUNITS" nameType="any" type="NX_NUMBER" minOccurs="0">
<doc>
AXISNAME_range is a placeholder for a name constructed from the actual
name of an axis to which ``_range`` has been appended.
The values in this optional field are differences between the values
in the field AXISNAME_end and the field AXISNAME.
</doc>
</field>
-->
<field name="AXISNAME_increment_set" units="AXISUNITS" nameType="any" type="NX_NUMBER" minOccurs="0">
<doc>
``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.
</doc>
</field>
</definition>