add depends_on with the appropriate reference location explained

* done this where possible (with reference drawings) * added some more geometry related information * deprecated old-style geometry * minor adjustments
nexusformat · Jun 14, 2022 · cc6670d · cc6670d
1 parent 96aad4c
commit cc6670d
Show file tree

Hide file tree

Showing 41 changed files with 524 additions and 22 deletions.
diff --git a/base_classes/NXaperture.nxdl.xml b/base_classes/NXaperture.nxdl.xml
@@ -30,7 +30,27 @@
     <doc>A beamline aperture.</doc>
     <!-- TODO compare with "screens" in SHADOW -->
 
-    <group type="NXgeometry">
+    <field name="depends_on" type="NX_CHAR">
+      <doc>
+        Points to the path to a field defining the last transformation in a chain of transformations
+        which defines the position and orientation of this component or the string "." if located
+        in the origin.
+
+        The reference point of the aperture is its center in the x and y axis. The reference point on the z axis is the
+        surface of the aperture pointing towards the source.
+
+        In complex (asymmetic) geometries an NXoff_geometry group can be used to provide an unambiguous reference.
+
+        .. image:: aperture/aperture.png
+            :width: 40%
+      </doc>
+    </field>
+    <group type="NXtransformations">
+      <doc>
+        Transformations used by this component to define its position and orientation.
+      </doc>
+    </group>
+    <group type="NXgeometry" deprecated="Use the field `depends_on` and :ref:`NXtransformations` instead.">
         <doc>
             location and shape of aperture
 
@@ -41,6 +61,7 @@
                 * Similar throughout base classes
                 * Some base classes do this much better
                 * Such as where is the gap written?
+
         </doc>
     </group>
     <group name="BLADE_GEOMETRY" type="NXgeometry">

diff --git a/base_classes/NXattenuator.nxdl.xml b/base_classes/NXattenuator.nxdl.xml
@@ -40,7 +40,7 @@
     </doc>
     <!-- 
         TODO compare with SHADOW definition "screen"
-        TODO  SHADOW: http://ftp.esrf.eu/pub/scisoft/shadow       or (older)   http://www.nanotech.wisc.edu/shadow  
+        TODO  SHADOW: https://github.com/oasys-kit/shadow3  
     -->
 
     <field name="distance" type="NX_FLOAT" units="NX_LENGTH">
@@ -88,4 +88,30 @@
             for a summary of the discussion.
         </doc>
     </attribute>
+    <field name="depends_on" type="NX_CHAR">
+      <doc>
+        Points to the path of a field defining the last transformation in a chain of transformations
+        which defines the position and orientation of this component or the string "." if located
+        in the origin.
+
+        The reference point of the attenuator is its center in the x and y axis. The reference point on the z axis is the
+        surface of the attenuator pointing towards the source.
+
+        In complex (asymmetic) geometries an NXoff_geometry group can be used to provide an unambiguous reference.
+
+        .. image:: attenuator/attenuator.png
+            :width: 40%
+
+      </doc>
+    </field>
+    <group type="NXtransformations">
+      <doc>
+        Transformations used by this component to define its position and orientation.
+      </doc>
+    </group>
+    <group name="shape" type="NXoff_geometry">
+      <doc>
+        Shape of this component. Particulary useful to define the origin for position and orientation in non-standard cases.
+      </doc>
+    </group>
 </definition>
diff --git a/base_classes/NXbeam_stop.nxdl.xml b/base_classes/NXbeam_stop.nxdl.xml
@@ -33,7 +33,7 @@
         Beamstops and their positions are important for SANS
         and SAXS experiments.
     </doc>
-    <group type="NXgeometry">
+    <group type="NXgeometry" deprecated="Use the field `depends_on` and :ref:`NXtransformations` instead.">
         <doc>engineering shape, orientation and position of the beam stop.</doc>
     </group>
     <field name="description">
@@ -74,4 +74,23 @@
             for a summary of the discussion.
         </doc>
     </attribute>
+    <field name="depends_on" type="NX_CHAR">
+      <doc>
+        Points to the path to a field defining the last transformation in a chain of transformations
+        which defines the position and orientation of this component or the string "." if located
+        in the origin.
+
+        The reference point of the beam stop is its center in the x and y axis. The reference point on the z axis is the
+        surface of the beam stop pointing towards the source.
+
+        .. image:: beam_stop/beam_stop.png
+          :width: 40%
+
+      </doc>
+    </field>
+    <group type="NXtransformations">
+      <doc>
+        Transformations used by this component to define its position and orientation.
+      </doc>
+    </group>
 </definition>
diff --git a/base_classes/NXbending_magnet.nxdl.xml b/base_classes/NXbending_magnet.nxdl.xml
@@ -73,7 +73,9 @@
     </doc>
   </field>
 	<group name="spectrum" type="NXdata"><doc>bending magnet spectrum</doc></group>
-  <group type="NXgeometry"><doc>"Engineering" position of bending magnet</doc></group>
+  <group type="NXgeometry" deprecated="Use the field `depends_on` and :ref:`NXtransformations` instead.">
+    <doc>"Engineering" position of bending magnet</doc>
+  </group>
   <attribute name="default">
       <doc>
           .. index:: plotting
@@ -87,5 +89,21 @@
           for a summary of the discussion.
       </doc>
   </attribute>
+  <field name="depends_on" type="NX_CHAR">
+    <doc>
+      Points to the path to a field defining the last transformation in a chain of transformations
+      which defines the position and orientation of this component or the string "." if located
+      in the origin.
+
+      .. todo::
+        Add a definition for the reference point of a bending magnet.
+
+    </doc>
+  </field>
+  <group type="NXtransformations">
+    <doc>
+      Transformations used by this component to define its position and orientation.
+    </doc>
+  </group>
 
 </definition>
diff --git a/base_classes/NXcapillary.nxdl.xml b/base_classes/NXcapillary.nxdl.xml
@@ -77,4 +77,20 @@
             for a summary of the discussion.
         </doc>
     </attribute>
+    <field name="depends_on" type="NX_CHAR">
+      <doc>
+        Points to the path to a field defining the last transformation in a chain of transformations
+        which defines the position and orientation of this component or the string "." if located
+        in the origin.
+
+        .. todo::
+            Add a definition for the reference point of a capillary lens.
+
+      </doc>
+    </field>
+    <group type="NXtransformations">
+      <doc>
+        Transformations used by this component to define its position and orientation.
+      </doc>
+    </group>
 </definition>
diff --git a/base_classes/NXcollimator.nxdl.xml b/base_classes/NXcollimator.nxdl.xml
@@ -28,7 +28,7 @@
     type="group" extends="NXobject">
 
     <doc>A beamline collimator.</doc>
-    <group type="NXgeometry">
+    <group type="NXgeometry" deprecated="Use the field `depends_on` and :ref:`NXtransformations` instead.">
         <doc>position, shape and size</doc>
     </group>
     <field name="type">
@@ -79,4 +79,24 @@
             for a summary of the discussion.
         </doc>
     </attribute>
+    <field name="depends_on" type="NX_CHAR">
+      <doc>
+        Points to the path to a field defining the last transformation in a chain of transformations
+        which defines the position and orientation of this component or the string "." if located
+        in the origin.
+
+        Assuming a collimator with a "flat" entry surface, the reference plane is the plane which contains this surface. The reference
+        point of the collimator in the x and y axis is the centre of the collimator entry surface on that plane. The reference plane is orthogonal
+        to the z axis and the location of this plane is the reference point on the z axis. The collimator faces negative z values.
+
+        .. image:: collimator/collimator.png
+          :width: 40%
+
+      </doc>
+    </field>
+    <group type="NXtransformations">
+      <doc>
+        Transformations used by this component to define its position and orientation.
+      </doc>
+    </group>
 </definition>
diff --git a/base_classes/NXcrystal.nxdl.xml b/base_classes/NXcrystal.nxdl.xml
@@ -49,7 +49,7 @@
     vertical plane.
   </doc>
 
-  <group type="NXgeometry">
+  <group type="NXgeometry" deprecated="Use the field `depends_on` and :ref:`NXtransformations` instead.">
     <doc>Position of crystal</doc>
   </group>
   <field name="usage" type="NX_CHAR">
@@ -271,6 +271,22 @@
           for a summary of the discussion.
       </doc>
   </attribute>
+  <field name="depends_on" type="NX_CHAR">
+    <doc>
+      Points to the path to a field defining the last transformation in a chain of transformations
+      which defines the position and orientation of this component or the string "." if located
+      in the origin.
+
+      .. todo::
+        Add a definition for the reference point of a crystal.
+
+    </doc>
+  </field>
+  <group type="NXtransformations">
+    <doc>
+      Transformations used by this component to define its position and orientation.
+    </doc>
+  </group>
   <!-- TODO need more parameters here, such as ...
        list from Rainer Gehrke, DESY (some items may already be present)
 

diff --git a/base_classes/NXdetector.nxdl.xml b/base_classes/NXdetector.nxdl.xml
@@ -312,7 +312,7 @@
     <doc>Local name for the detector</doc>
   </field>
 
-  <group type="NXgeometry">
+  <group type="NXgeometry" deprecated="Use the field `depends_on` and :ref:`NXtransformations` instead.">
     <doc>Position and orientation of detector</doc>
   </group>
 
@@ -899,4 +899,19 @@
           for a summary of the discussion.
       </doc>
   </attribute>
+  <field name="depends_on" type="NX_CHAR">
+    <doc>
+      Points to the path to a field defining the last transformation in a chain of transformations
+      which defines the position and orientation of this component or the string "." if located
+      in the origin.
+
+      The reference point of the detector is the center of the first pixel.
+      In complex geometries the NXoff_geometry groups can be used to provide an unambiguous reference.
+    </doc>
+  </field>
+  <group type="NXtransformations">
+    <doc>
+      Transformations used by this component to define its position and orientation.
+    </doc>
+  </group>
 </definition>
diff --git a/base_classes/NXdisk_chopper.nxdl.xml b/base_classes/NXdisk_chopper.nxdl.xml
@@ -124,7 +124,7 @@
 		<doc>Low and high values of wavelength range transmitted</doc>
 		<dimensions><dim index="1" value="2"/></dimensions>
 	</field>
-	<group type="NXgeometry" />
+	<group type="NXgeometry" deprecated="Use the field `depends_on` and :ref:`NXtransformations` instead."/>
     <attribute name="default">
         <doc>
             .. index:: plotting
@@ -138,4 +138,27 @@
             for a summary of the discussion.
         </doc>
     </attribute>
+    <field name="depends_on" type="NX_CHAR">
+      <doc>
+        Points to the path to a field defining the last transformation in a chain of transformations
+        which defines the position and orientation of this component or the string "." if located
+        in the origin.
+
+        The reference plane of the disk chopper includes the surface of the spinning disk which faces
+        the source. The reference point in the x and y axis is the point on this surface which is the
+        centre of the axle which the disk is spinning around. The reference plane is orthogonal to
+        the z axis and its position is the reference point on that axis.
+
+		Note: This reference point in almost all practical cases is not where the beam passes though.
+
+        .. image:: disk_chopper/disk_chopper.png
+            :width: 40%
+
+      </doc>
+    </field>
+    <group type="NXtransformations">
+      <doc>
+        Transformations used by this component to define its position and orientation.
+      </doc>
+    </group>
 </definition>
diff --git a/base_classes/NXfermi_chopper.nxdl.xml b/base_classes/NXfermi_chopper.nxdl.xml
@@ -61,7 +61,7 @@
   <field name="energy" type="NX_FLOAT" units="NX_ENERGY">
         <doc>energy selected</doc>
   </field> 
-	<group type="NXgeometry">
+	<group type="NXgeometry" deprecated="Use the field `depends_on` and :ref:`NXtransformations` instead.">
 		<doc>geometry of the fermi chopper</doc>
 	</group>
 	<field name="absorbing_material">
@@ -83,5 +83,21 @@
             for a summary of the discussion.
         </doc>
     </attribute>
+    <field name="depends_on" type="NX_CHAR">
+      <doc>
+        Points to the path to a field defining the last transformation in a chain of transformations
+        which defines the position and orientation of this component or the string "." if located
+        in the origin.
+
+        .. todo::
+          Add a definition for the reference point of a fermi chopper.
+
+      </doc>
+    </field>
+    <group type="NXtransformations">
+      <doc>
+        Transformations used by this component to define its position and orientation.
+      </doc>
+    </group>
 </definition>
 
diff --git a/base_classes/NXfilter.nxdl.xml b/base_classes/NXfilter.nxdl.xml
@@ -37,7 +37,7 @@
 		or :ref:`NXattenuator` (reduces beam intensity), then use 
 		:ref:`NXattenuator`.
 	</doc>
-	<group type="NXgeometry">
+	<group type="NXgeometry" deprecated="Use the field `depends_on` and :ref:`NXtransformations` instead.">
 		<doc>Geometry of the filter</doc>
 	</group>
 	<field name="description">
@@ -164,5 +164,21 @@
             for a summary of the discussion.
         </doc>
     </attribute>
+    <field name="depends_on" type="NX_CHAR">
+      <doc>
+        Points to the path to a field defining the last transformation in a chain of transformations
+        which defines the position and orientation of this component or the string "." if located
+        in the origin.
+
+        .. todo::
+          Add a definition for the reference point of a filter.
+
+      </doc>
+    </field>
+    <group type="NXtransformations">
+      <doc>
+        Transformations used by this component to define its position and orientation.
+      </doc>
+    </group>
 </definition>
 
diff --git a/base_classes/NXflipper.nxdl.xml b/base_classes/NXflipper.nxdl.xml
@@ -67,5 +67,21 @@
             for a summary of the discussion.
         </doc>
     </attribute>
+    <field name="depends_on" type="NX_CHAR">
+      <doc>
+        Points to the path to a field defining the last transformation in a chain of transformations
+        which defines the position and orientation of this component or the string "." if located
+        in the origin.
+
+        .. todo::
+          Add a definition for the reference point of a spin flipper.
+
+      </doc>
+    </field>
+    <group type="NXtransformations">
+      <doc>
+        Transformations used by this component to define its position and orientation.
+      </doc>
+    </group>
 </definition>