NXtransformations: clarify that these are passive transformation + ex…

…ample

base_classes/NXtransformations.nxdl.xml

@@ -65,10 +65,13 @@
 		a relative path is given, it is relative to the group enclosing the ``depends_on``
 		specification.
 
-		For a chain of three transformations, where :math:`T_1` depends on :math:`T_2`
-		and that in turn depends on :math:`T_3`, the final transformation :math:`T_f` is
+		For a chain of three transformations, where :math:`T_3` depends on :math:`T_2`
+		and that in turn depends on :math:`T_1`, the final transformation :math:`T_f` is
 
-		.. math:: T_f = T_3 T_2 T_1
+		.. math:: T_f = T_1 T_2 T_3
+
+		Transformations are defines as *passive* transformations so :math:`T_1` is the first
+		transformation to be applied while it comes last in the *depends-on* chain.
 
 		In explicit terms, the transformations are a subset of affine transformations
 		expressed as 4x4 matrices that act on homogeneous coordinates, :math:`w=(x,y,z,1)^T`.
@@ -94,8 +97,7 @@
 		Collecting the motors of a sample table or xyz-stage in an NXtransformations
 		group is equally possible.
 
-
-		Following the section on the general dscription of axis in NXtransformations is a section which
+		Following the section on the general description of axis in NXtransformations is a section which
 		documents the fields commonly used within NeXus for positioning purposes and their meaning. Whenever
 		there is a need for positioning a beam line component please use the existing names. Use as many fields
 		as needed in order to position the component. Feel free to add more axis if required. In the description
@@ -108,6 +110,85 @@
 		* depends_on
 
 		as needed.
+
+		**Example**
+
+		We define a coordinate system with the X-axis along the beam and the Z-axis opposite to the direction of gravity.
+		Four different objects are positions:
+
+		* *sample*: diffractometer angles define the orientation with respect to the coordinate system
+		* *transmission*: detector in the beam, 20 cm downstream from the sample
+		* *vertical*: 10 cm downstream from the sample, 5 degrees with the beam, positioned in the XZ-plane above the XY-plane
+		* *horizontal*: 10 cm downstream from the sample, 5 degrees with the beam, positioned in the XY-plane above the XZ-plane
+
+		Be careful: when positioning an object, the first transformation in the *depends-on* chain is actually the last
+		transformation. In addition the transformation is the *passive* transformation, which is the inverse of
+		the coordinate transformation. For example the translation of *transmission* to position it 20 cm downstream from
+		the sample is `-20` with `vector=[1 0 0]` or equivalently `20` with `vector=[-1 0 0]`.
+
+		  entry:NXentry
+		    coordinate_system:NXtransformations
+		      beam=NaN  # value is never used
+		        @depends_on=gravity
+		        @vector=[1 0 0]
+		      gravity=NaN  # value is never used
+		        @vector=[0 0 -1]
+		    sample:NXsample
+		      depends_on=diffr/phi
+		      diffr:NXtransformations
+		        phi=45
+		          @depends_on=chi
+		          @transformation_type=rotation
+		          @vector=[0 1 0]
+		          @units=degrees
+		        chi=90
+		          @depends_on=rotation_angle
+		          @transformation_type=rotation
+		          @vector=[0 0 1]
+		          @units=degrees
+		        rotation_angle=30
+		         @depends_on=../../coordinate_system/beam
+		          @transformation_type=rotation
+		          @vector=[0 1 0]
+		          @units=degrees
+		    instrument:NXinstrument
+		      vertical:NXdetector
+		        depends_on=position/azimuth
+		        position:NXtransformations
+		          azimuth=0
+		            @depends_on=polar
+		            @units=degrees
+		            @vector=[1 0 0]
+		          polar=5
+		            @depends_on=distance
+		            @units=degrees
+		            @vector=[0 1 0]
+		          distance=-10
+		            @depends_on=../../coordinate_system/beam
+		            @units=cm
+		            @vector=[1 0 0]
+		      horizontal:NXdetector
+		        position:NXtransformations
+		          azimuth=0
+		            @depends_on=polar
+		            @units=degrees
+		            @vector=[1 0 0]
+		          polar=5
+		            @depends_on=distance
+		            @units=degrees
+		            @vector=[0 1 0]
+		          distance=-10
+		            @depends_on=../../coordinate_system/beam
+		            @units=cm
+		            @vector=[1 0 0]
+		      transmission:NXdetector
+		        depends_on=position/azimuth
+		        position:NXtransformations
+		          distance=-20
+		            @depends_on=../../coordinate_system/beam
+		            @units=cm
+		            @vector=[1 0 0]
+
 	</doc>
 	<field name="AXISNAME" nameType="any" units="NX_TRANSFORMATION" type="NX_NUMBER" maxOccurs="unbounded">
 		<doc>
@@ -176,7 +257,7 @@
 		<attribute name="equipment_component" type="NX_CHAR">
 			<doc>
 				An arbitrary identifier of a component of the equipment to which
-				the transformation belongs, such as 'detector_arm' or 'detector_module'.
+				the transformation belongs, such as 'arm' or 'module'.
 				NXtransformations with the same equipment_component label form a logical
 				grouping which can be combined together into a single change-of-basis
 				operation.