From 7bcfb8a33618fd16234730cd5849db01770303b6 Mon Sep 17 00:00:00 2001
From: "Herbert J. Bernstein" <yayahjb@gmail.com>
Date: Wed, 5 Oct 2016 10:57:51 -0400
Subject: [PATCH] Clarify rank and units issues for NXmx and NXtransformations

For Nxmx, clarify the possibility of 2- or 3-dimensional images by
adding a dataRank variable.

For NXtransformations, as suggested by Andreas Foerster clarify the
handling of units for different transformation types.
---
 .DS_Store                               | Bin 0 -> 8196 bytes
 applications/NXmx.nxdl.xml              |  38 +++++++++++++++---------
 base_classes/NXtransformations.nxdl.xml |  37 +++++++++++++++--------
 3 files changed, 48 insertions(+), 27 deletions(-)
 create mode 100644 .DS_Store

diff --git a/.DS_Store b/.DS_Store
new file mode 100644
index 0000000000000000000000000000000000000000..d156873a8f60d64ec4546f9714ddfa4c77e68891
GIT binary patch
literal 8196
zcmeHMTWl0n7(U;&v@<XZr<6h|m#j9LiV#*>tRTYn0xcp^-O>wGm)V^GMy4}$XLgG=
z)f(SWqEVtI8Vz31Akh~Qd@_oOCitTE1){#FuWBL*>Wlto&TNI2_K6t8InA8!T>k%@
zJ>P!koc*VaF|-zp+Zd~5j4AX8<Z~#yLK6MrnUZ2*O9dgwpD~N&n9h7ccZzk?5HS!j
z5HS!j5HS!ja4j%EceY5%H21#jjq-?rh=Knl1LAy0&?7Jv;+VwX=%6eJ0SL>fIY?Bd
zI3VyzgqR9(Ok&_lW6J0Op)0}=1Ja%P6T+M@72=pg>CPbC8N!(nMkokoC%;5s&XAHA
z<q-oB15+6gvAaew`w;!vm&NZ6^RmO<P}X*{WOFe)WLut}OrArmtbA5QrJ~NJG<P<y
zn)^U{zdM}vb-&=X>iOM4%`(hvSnksO{iSlZ>)I1#J=<fM!x_Gy&2@a;a?JcCt^>W6
zW4ObuZox6UfwUa2*E0P58D7(sH;d%jr8{Pi<yl$Fw){s_N{X7{3r9whD-(^4&7&(5
zBhAfJZfZ)7j`F7zWyvjTTekNPjUIaajW^#q_VzoUoRN$mJXKirB!)hliJrZNm&?+E
zgwM1b+Fr3sau_>N;_&=G9L~|=b2o44Sk$Ry_<XUZ9Yen5I$n>N_Xsn5o=4<v&ACpv
z<_xdO>2|JQ>%Q4y+iB}j)9cN-c45%*gmo_O+IE-gSz?&}KHog(3!5ojeY-q2@3#ex
zeHM)`t$4vR?>A|1t7x{<6ds4F9G_Ra?1r0fO|D(HahzApuhwd`MZHBqylw6r7T-y~
z?&VC!u$+Cn=$mqUYp-SI)heu1yB&SdlwNi5r7AzE3>Y--cGnO#M$i+lizgIiw`gz6
zo0Q9Dtv-H}%5|mNqXozz8nhKE_tfqKBo67iN?WaPL)~fXS<{wHYqTbXZ&Q1Vl0(^8
zqursXeK~h<kUpL#+wP3trSLD52gStq=$^l0$aHA#>P@MZ*1C9n^3qC6?icnghG80t
zQlBbF$<(JB!h!_G>QhNsROxP8#@4WQ*2ng+JR4z$*-Pvw`+$AOPO;PM4EvIev-9jn
z_6z%!{l+e^KM+G1W}yPrSc+v>jumJ`6K+Q{HefThpc7khFM833UDypB58(g?;h>1e
zF@`5_2+!jPUcieuhWBw2ALDa;g|G1qzQs@Y85iY8i<N|bcj;40#P5VNX*xU?Vn?RY
z^p=j!g<G#>O`n@5l)Rv3;iB3=+Uqy9O{im%ATAYVphYRRK!hcc1v0-}*^BFzER8SM
z5+&J8meWqsuz64sn}k=62i7EbAxN&sYD0X5LK}w1f~vMEzFKStUM713nHwsfC3~B-
zbz*Dqa@o5<+bA{xuaLdVwN_Q-Oja7=bJVM%+_R+HA4s(q*q`h#R6@gI+(=qYVm(r5
zK|5)+16{ZeX>_9p8SFt8IhdqW7Y`#3AES6IQ0$X<8i(-=p2c%`8L!|~yoRGVj(2ea
z@8J|q<0E{Evlz#BleD{Sl6JqJNxQ{#-mzV0AK3`)Yb;B*pT|s=p?BAIP!=_>bhwu`
z$mMff7qv3Eidqr>Z=U}B|8=p}Xb}+u5d&9d0OjrJ_Ezef?yM8Bc7mQg^oS(v#v}$V
xlm+29VGxcJPW;1=$_X+RKB*ALBvK2dfBi*3_?tGm|F6O?*XaHaH2h!8{szRYY{viq

literal 0
HcmV?d00001

diff --git a/applications/NXmx.nxdl.xml b/applications/NXmx.nxdl.xml
index aa7302f2fc..869a5a77e2 100644
--- a/applications/NXmx.nxdl.xml
+++ b/applications/NXmx.nxdl.xml
@@ -38,6 +38,9 @@
 				two-dimensional images.  Some will produce three-dimensional
 				images, using one of the indices to select a detector element. 
 			</doc>
+			<symbol name="dataRank">
+				<doc>rank of the ``data`` field</doc>
+			</symbol>
 			<symbol name="np">
 				<doc>number of scan points</doc>
 			</symbol>
@@ -91,10 +94,10 @@
 					in the field group_index, and the level in the hierarchy
 					given in the group_parent field.  For example if an x-ray
 					detector, DET, consists of four elements in a rectangular array::
-						     
-						     DTL    DTR
-						     DLL    DLR
-						     
+							 
+							 DTL	DTR
+							 DLL	DLR
+							 
 					We could have::
 						
 						 group_names: ["DET", "DTL", "DTR", "DLL", "DLR"]
@@ -138,7 +141,7 @@
 				</group>
 				<group type="NXdetector">
 					<doc>
-						Normally the detector group will usually have the name detector
+						Normally the detector group will have the name ``detector``.
 						However, in the case of multiple detector elements, each element
 						needs a uniquely named NXdetector group. 
 					</doc>
@@ -161,13 +164,16 @@
 
 					<field name="data" type="NX_NUMBER">
 						<doc>
-							This is the example for a dimension-2 detector.  For a
-							a dimension-3 detector, a rank-4 data field is needed.
+							For a dimension-2 detector, the rank of the data array will be 3.
+							For a dimension-3 detector, the rank of the data array will be 4.
+							This allows for the introduction of the frame number as the
+							first index.
 						</doc>
-						<dimensions rank="3">
+						<dimensions rank="dataRank">
 							<dim index="1" value="np" />
 							<dim index="2" value="i" />
 							<dim index="3" value="j" />
+							<dim index="4" value="k" minOccurs="0"/>
 						</dimensions>
 					</field>
 
@@ -326,9 +332,10 @@
 
 					<field name="angular_calibration" type="NX_FLOAT" minOccurs="0">
 						<doc>Angular calibration data.</doc>
-						<dimensions rank="2">
+						<dimensions rank="dataRank">
 							<dim index="1" value="i" />
 							<dim index="2" value="j" />
+							<dim index="3" value="k" minOccurs="0"/>
 						</dimensions>
 					</field>
 
@@ -341,17 +348,19 @@
 
 					<field name="flatfield" type="NX_FLOAT" minOccurs="0">
 						<doc>Flat field correction data.</doc>
-						<dimensions rank="2">
+						<dimensions rank="dataRank">
 							<dim index="1" value="i" />
 							<dim index="2" value="j" />
+							<dim index="3" value="k" minOccurs="0"/>
 						</dimensions>
 					</field>
 
 					<field name="flatfield_error" type="NX_FLOAT" minOccurs="0">
 						<doc>Errors of the flat field correction data.</doc>
-						<dimensions rank="2">
+						<dimensions rank="dataRank">
 							<dim index="1" value="i" />
 							<dim index="2" value="j" />
+							<dim index="3" value="k" minOccurs="0"/>
 						</dimensions>
 					</field>
 
@@ -396,9 +405,10 @@
 							If the full bit depths is not required, providing a
 							mask with fewer bits is permissible.
 						</doc>
-						<dimensions rank="2">
+						<dimensions rank="dataRank">
 							<dim index="1" value="i" />
 							<dim index="2" value="j" />
+							<dim index="3" value="k" minOccurs="0"/>
 						</dimensions>
 					</field>
 
@@ -551,10 +561,10 @@
 
 					<field name="incident_beam_size" type="NX_FLOAT" units="NX_LENGTH"  minOccurs="0">
 						<doc>
-							Two-dimensional array of FWHM (if Gaussian or Airy function) or
+							Two-element array of FWHM (if Gaussian or Airy function) or
 							diameters (if top hat) of beam in the order x, y
 						</doc>
-						<dimensions rank="1" />
+						<dimensions rank="1" value="2" />
 					</field>
 
 					<field name="profile" type="NX_CHAR" minOccurs="0">
diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml
index a17a7d9558..7ed5a3b1ad 100644
--- a/base_classes/NXtransformations.nxdl.xml
+++ b/base_classes/NXtransformations.nxdl.xml
@@ -33,11 +33,12 @@
 	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.
-                -->
+				<!--	
+						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.
@@ -49,7 +50,10 @@
 		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).  
+		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
+		``general``.
 
 		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
@@ -93,7 +97,7 @@
 		This entire explanation is not clear.
 		-->
 
-	<field name="AXISNAME" 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
 			
@@ -116,19 +120,26 @@
 				<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">
@@ -138,7 +149,7 @@
 			</doc>
 		</attribute>
 	</field>
-	<field name="AXISNAME_end" nameType="any" type="NX_NUMBER" minOccurs="0">
+	<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.
@@ -147,7 +158,7 @@
 			at the corresponding positions given in the AXISNAME field.
 		</doc>
 	</field>
-	<field name="AXISNAME_range" nameType="any" type="NX_NUMBER" minOccurs="0">
+	<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.
@@ -156,7 +167,7 @@
 			in the field AXISNAME_end and the field AXISNAME.
 		</doc>
 	</field>
-	<field name="AXISNAME_average_range" nameType="any" type="NX_NUMBER" minOccurs="0">
+	<field name="AXISNAME_average_range" units="AXISUNITS"  nameType="any" type="NX_NUMBER" minOccurs="0">
 		<doc>
 			AXISNAME_average_range is a placeholder for a name constructed from the actual
 			name of an axis to which ``_average_range`` has been appended.