NXtransformations: clarify that these are active transformation + exa…

…mple

base_classes/NXtransformations.nxdl.xml

@@ -66,12 +66,21 @@
 		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
+		which in turn depends on :math:`T_3`, the final *active* transformation
+		matrix :math:`T_f` is
 
-		.. math:: T_f = T_3 T_2 T_1
+		.. math:: T_f = T_1 . T_2 . T_3
+
+		For example when positioning a flat detector, its pixel positions in the laboratory
+		reference frame (McSTAS coordinate frame by default) can be calculated by
+
+		.. math:: X_{\text{lab}} = T_1 . T_2 . T_3 . X_{\text{pixel}}
+
+		Note that :math:`T_1` comes first in the *depends-on* chain but is applied last
+		to the pixel coordinates.
 
 		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`.
+		expressed as 4x4 matrices that act on homogeneous coordinates, :math:`X=(x,y,z,1)^T`.
 
 		For rotation and translation,
 
@@ -94,8 +103,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 +116,92 @@
 		* depends_on
 
 		as needed.
+
+		**Example**
+
+		Define a coordinate system with the X-axis along the beam and the Z-axis opposite to the direction of gravity.
+		In that coordinate system, four different objects are positioned:
+
+		* *sample*:
+			* diffractometer angles define the orientation with respect to the coordinate system
+		* *transmission*:
+			* point detector in the beam
+			* 20 cm downstream from the sample
+		* *vertical*:
+			* point detector 10 cm downstream from the sample
+			* making an angle of 5 degrees with the beam w.r.t. the sample
+			* positioned in the XZ-plane above the XY-plane
+		* *horizontal*:
+			* point detector 11 cm downstream from the sample
+			* making an angle of 6 degrees with the beam w.r.t. the sample
+			* positioned in the XY-plane above the XZ-plane
+
+		.. code-block::
+
+		  entry:NXentry
+		    coordinate_system:NXtransformations
+		      beam=NaN  # value is never used
+		        @depends_on=gravity
+		        @vector=[1 0 0]          # X-axis points in the beam direction
+		      gravity=NaN  # value is never used
+		        @vector=[0 0 -1]         # Z-axis points up
+		    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              # stay in the vertical plane
+		            @depends_on=polar
+		            @units=degrees
+		            @vector=[-1 0 0]
+		          polar=5                # title above the horizontal plane
+		            @depends_on=distance
+		            @units=degrees
+		            @vector=[0 -1 0]
+		          distance=10            # move downstream from the sample
+		            @depends_on=../../coordinate_system/beam
+		            @units=cm
+		            @vector=[1 0 0]
+		      horizontal:NXdetector
+		        depends_on=position/azimuth
+		        position:NXtransformations
+		          azimuth=90             # rotate to the horizontal plane
+		            @depends_on=polar
+		            @units=degrees
+		            @vector=[-1 0 0]
+		          polar=6                # title above the horizontal plane
+		            @depends_on=distance
+		            @units=degrees
+		            @vector=[0 -1 0]
+		          distance=11            # move downstream from the sample
+		            @depends_on=../../coordinate_system/beam
+		            @units=cm
+		            @vector=[1 0 0]
+		      transmission:NXdetector
+		        depends_on=position/azimuth
+		        position:NXtransformations
+		          distance=20            # move downstream from the sample
+		            @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>