--- /Users/yaya/NXtransformations.nxdl.xml 2016-10-05 20:34:15.000000000 +0200
+++ NXtransformations.nxdl.xml 2016-10-14 13:08:27.000000000 +0200
@@ -24,7 +24,7 @@
<definition xmlns="http://definition.nexusformat.org/nxdl/3.1"
category="contributed"
name="NXtransformations"
- version="1.0"
+ version="1.1"
type="group"
extends="NXobject"
ignoreExtraGroups="true"
@@ -33,19 +33,41 @@
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 translations and rotations to describe a geometry
-
- A sequence of transformations lists the
- offset and rotation steps needed to describe the position and orientation
- of any movable or fixed device.
-
- This class will usually contain all axes of a sample stage or goniometer.
+ 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.
+ 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}}`
@@ -67,41 +89,94 @@
This entire explanation is not clear.
-->
- <field name="TRANSFORMATION" nameType="any" type="NX_NUMBER" maxOccurs="unbounded">
+ <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 defined. The user is free to use any name
- that does not cause confusion. When using more than one TRANSFORMATION field,
+ 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>
- <attribute name="transformation_type">
<enumeration>
<item value="translation" />
<item value="rotation" />
+ <!-- <item value="general" /> -->
</enumeration>
</attribute>
- <attribute name="vector" type="NX_NUMBER">
+ <attribute name="vector" units="NX_DIMENSIONLESS" type="NX_NUMBER">
<doc>
- 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.
+ 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.
+ Units of the offset. Values should be consistent with NX_LENGTH.
</doc>
</attribute>
<attribute name="depends_on" type="NX_CHAR">
<doc>
- Points to the name of the next element in the geometry chain.
+ Points to the path to a field defining the axis on which this
+ depends or the string ".".
</doc>
</attribute>
</field>
-</definition>
+ <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>