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