Define usage of NXtransformations and NXcoordinate_system(_set)

contributed_definitions/NXcoordinate_system.nxdl.xml

@@ -132,12 +132,24 @@ https://www.zenodo.org/record/3526738/files/lyso009a_0087.JF07T32V01_master.h5?d
     </field>
     <field name="z" type="NX_NUMBER" units="NX_LENGTH">
         <doc>
-             Base unit vector along the second axis which spans the coordinate system.
+             Base unit vector along the third axis which spans the coordinate system.
              This axis is frequently referred to as the z-axis in real space and
              the k-axis in reciprocal space.
         </doc>
         <dimensions rank="1">
             <dim index="1" value="3"/>
         </dimensions>
     </field>
+    <field name="depends_on" type="NX_CHAR">
+        <doc>
+             This specificies the relation to another coordinate system by pointing to the last
+             transformation in the transformation chain in the NXtransformations group.
+        </doc>
+    </field>
+    <group type="NXtransformations">
+        <doc>
+             Collection of axis-based translations and rotations to describe this coordinate system
+             with respect to another coordinate system.
+        </doc>
+    </group>
 </definition>

contributed_definitions/NXcoordinate_system_set.nxdl.xml

@@ -25,24 +25,23 @@
     <doc>
          Base class to hold different coordinate systems and representation conversions.
 
-         How many nodes of type :ref:`NXcoordinate_system_set` should be used in an appdef?
+         How many nodes of type :ref:`NXcoordinate_system_set` should be used in an application definition?
 
-         * 0; if no instance of :ref:`NXcoordinate_system_set` and therein or elsewhere across
-           the appdef an instance of NXcoordinate_system is defined,
+         * 0; if there is no instance of :ref:`NXcoordinate_system_set` and therein or elsewhere across
+           the application definition, an instance of NXcoordinate_system is defined,
            the default NeXus `McStas &lt;https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html&gt;`_
            coordinate system is assumed. This makes :ref:`NXcoordinate_system_set` and
            NXcoordinate_system base classes backwards compatible to older
            NeXus conventions and classes.
          * 1; if only one :ref:`NXcoordinate_system_set` is defined, it should be placed
            as high up in the node hierarchy (ideally right below an instance of NXentry)
            of the application definition tree as possible.
-           This :ref:`NXcoordinate_system_set` should at least define one NXcoordinate_system
-           instance which should be called mcstas for the sake of improved clarity.
-           Alternatively, at least one NXcoordinate_system member of the set should be
-           defined and named such that it is clear how this coordinate system is
-           typically referred to in a community. Additional NXcoordinate_system instances
-           should be specified if possible in that same :ref:`NXcoordinate_system_set` instead
-           of cluttering them across the tree.
+           This :ref:`NXcoordinate_system_set` should define at least one NXcoordinate_system
+           instance. This shall be named such that it is clear how this coordinate system is
+           typically referred to in a community. For the NeXus `McStas coordinate system, it is
+           advised to call it mcstas for the sake of improved clarity.
+           Additional NXcoordinate_system instances should be specified if possible in that same
+           :ref:`NXcoordinate_system_set` instead of cluttering them across the tree.
 
            If this is the case, it is assumed that the NXcoordinate_system_members
            overwrite the NeXus default McStas coordinate system, i.e. users can thereby
@@ -102,7 +101,10 @@
            specifying of the coordinate system used in every case is that especially
            in combination with having coordinate systems inside deeper branches
            makes up for a very versatile, backwards compatible, but powerful system
-           to express different types of coordinate systems using NeXus.
+           to express different types of coordinate systems using NeXus. In the case
+           of two or more instances of NXcoordinate_system in one :ref:`NXcoordinate_system_set`,
+           it is also advised to specify the relationship between the two coordinate systems by
+           using the (NXtransformations) group within NXcoordinate_system.
 
          In effect, 1 should be the preferred choice. However, if more than one coordinate
          system is defined for practical purposes, explicit depends_on fields should
@@ -116,5 +118,5 @@ Depends on cardinality of NXcoordinate_system_set, i.e. how many NXcoordinate_sy
 - 0, the root of an NXtransformation chain i.e. "." means McStas
 - 1, the root of an NXtransformation chain i.e. "." means "that specific CS" i.e. the one defined by the single instance of NXcoordinate_system in the set
 - > 1, "." becomes ambiguous. My suggestion, spell out the name of the specific NXcoordinate_system instance to be used, using "."
-  despite all these, a warning should be raised, like a logic warning (and McStas kick in) or an error (i.e. be forbidden) be raised-->
+despite all these, a warning should be raised, like a logic warning (and McStas kick in) or an error (i.e. be forbidden) be raised-->
 </definition>

contributed_definitions/NXem_conventions.nxdl.xml

@@ -398,7 +398,7 @@ assumed reference frame and rotation conventions-->
         <doc>
              Details about the detector reference frame for a specific detector.
         </doc>
-        <attribute name="depends_on" type="NX_CHAR">
+        <attribute name="detector" type="NX_CHAR">
             <doc>
                  Reference to the specifically named :ref:`NXdetector` instance
                  for which these conventions in this :ref:`NXprocess` group apply

contributed_definitions/nyaml/NXcoordinate_system.yaml

@@ -18,6 +18,7 @@ NXcoordinate_system(NXobject):
       Exemplar values could be *left corner of the lab bench*, *door-handle*
       *pinhole through which the electron beam exists the pole piece*.
       *barycenter of the triangle*, *center of mass of the stone*.
+
   # implementing a proposal for "a common base table" along thoughts like:
   # https://manual.nexusformat.org/classes/base_classes/NXtransformations.html#nxtransformations
   # similar to a place where all transformations are stored
@@ -44,12 +45,14 @@ NXcoordinate_system(NXobject):
 
       Exemplar values could be direction of gravity.
   x(NX_NUMBER):
+    unit: NX_LENGTH
     doc: |
       Base unit vector along the first axis which spans the coordinate system.
       This axis is frequently referred to as the x-axis in real space and
       the i-axis in reciprocal space.
-    unit: NX_LENGTH
-    dim: (3,)
+    dimensions:
+      rank: 1
+      dim: [[1, 3]]
   y_alias(NX_CHAR):
     doc: |
       Possibility to define an alias for the name of the y-axis.
@@ -61,12 +64,14 @@ NXcoordinate_system(NXobject):
 
       See docstring of x_alias for further details.
   y(NX_NUMBER):
+    unit: NX_LENGTH
     doc: |
       Base unit vector along the second axis which spans the coordinate system.
       This axis is frequently referred to as the y-axis in real space and
       the j-axis in reciprocal space.
-    unit: NX_LENGTH
-    dim: (3,)
+    dimensions:
+      rank: 1
+      dim: [[1, 3]]
   z_alias(NX_CHAR):
     doc: |
       Possibility to define an alias for the name of the z-axis.
@@ -78,9 +83,177 @@ NXcoordinate_system(NXobject):
 
       See docstring of x_alias for further details.
   z(NX_NUMBER):
+    unit: NX_LENGTH
     doc: |
-      Base unit vector along the second axis which spans the coordinate system.
+      Base unit vector along the third axis which spans the coordinate system.
       This axis is frequently referred to as the z-axis in real space and
       the k-axis in reciprocal space.
-    unit: NX_LENGTH
-    dim: (3,)
+    dimensions:
+      rank: 1
+      dim: [[1, 3]]
+  depends_on(NX_CHAR):
+    doc: |
+      This specificies the relation to another coordinate system by pointing to the last
+      transformation in the transformation chain in the NXtransformations group.
+  (NXtransformations):
+    doc: |
+      Collection of axis-based translations and rotations to describe this coordinate system
+      with respect to another coordinate system.
+
+# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++
+# 76304029bbb3a1882d9855d8b170be0cfb2a18eebd5f0b60c752ae35c441f906
+# <?xml version='1.0' encoding='UTF-8'?>
+# <?xml-stylesheet type="text/xsl" href="nxdlformat.xsl"?>
+# <!--
+# # NeXus - Neutron and X-ray Common Data Format
+# #
+# # Copyright (C) 2014-2024 NeXus International Advisory Committee (NIAC)
+# #
+# # This library is free software; you can redistribute it and/or
+# # modify it under the terms of the GNU Lesser General Public
+# # License as published by the Free Software Foundation; either
+# # version 3 of the License, or (at your option) any later version.
+# #
+# # This library is distributed in the hope that it will be useful,
+# # but WITHOUT ANY WARRANTY; without even the implied warranty of
+# # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# # Lesser General Public License for more details.
+# #
+# # You should have received a copy of the GNU Lesser General Public
+# # License along with this library; if not, write to the Free Software
+# # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+# #
+# # For further information, see http://www.nexusformat.org
+# -->
+# <definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXcoordinate_system" extends="NXobject" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+#     <doc>
+#          Base class to detail a coordinate system (CS).
+#          
+#          Whenever possible, an instance of :ref:`NXcoordinate_system` should be used as
+#          a member in an :ref:`NXcoordinate_system_set` and the name of the instance
+#          should be this alias. This may support a process whereby jargon when talking
+#          about coordinate systems and conventions may become cleaner for users
+#          because it is not evident for people outside a lab that terms like e.g.
+#          tip space or specimen space refer to the same coordinate system.
+#          This is an example of jargon used in e.g. the field of atom
+#          probe tomography.
+#     </doc>
+#     <field name="origin" type="NX_CHAR">
+#         <doc>
+#              Human-readable field telling where the origin of this CS is.
+#              Exemplar values could be *left corner of the lab bench*, *door-handle*
+#              *pinhole through which the electron beam exists the pole piece*.
+#              *barycenter of the triangle*, *center of mass of the stone*.
+#         </doc>
+#     </field>
+#     <!--implementing a proposal for "a common base table" along thoughts like:
+# https://manual.nexusformat.org/classes/base_classes/NXtransformations.html#nxtransformations
+# similar to a place where all transformations are stored
+# https://www.zenodo.org/record/3526738/files/lyso009a_0087.JF07T32V01_master.h5?download=1-->
+#     <field name="alias" type="NX_CHAR">
+#         <doc>
+#              An alternative name given to that coordinate system.
+#         </doc>
+#     </field>
+#     <field name="type" type="NX_CHAR">
+#         <doc>
+#              Coordinate system type.
+#         </doc>
+#         <enumeration>
+#             <item value="cartesian"/>
+#         </enumeration>
+#     </field>
+#     <field name="handedness" type="NX_CHAR">
+#         <doc>
+#              Handedness of the coordinate system if it is a Cartesian.
+#         </doc>
+#         <enumeration>
+#             <item value="right_handed"/>
+#             <item value="left_handed"/>
+#         </enumeration>
+#     </field>
+#     <field name="x_alias" type="NX_CHAR">
+#         <doc>
+#              Possibility to define an alias for the name of the x-axis.
+#         </doc>
+#     </field>
+#     <field name="x_direction" type="NX_CHAR">
+#         <doc>
+#              Human-readable field telling in which direction the x-axis points if that
+#              instance of :ref:`NXcoordinate_system` has no reference to any parent and as such
+#              is the mighty world reference frame.
+#              
+#              Exemplar values could be direction of gravity.
+#         </doc>
+#     </field>
+#     <field name="x" type="NX_NUMBER" units="NX_LENGTH">
+#         <doc>
+#              Base unit vector along the first axis which spans the coordinate system.
+#              This axis is frequently referred to as the x-axis in real space and
+#              the i-axis in reciprocal space.
+#         </doc>
+#         <dimensions rank="1">
+#             <dim index="1" value="3"/>
+#         </dimensions>
+#     </field>
+#     <field name="y_alias" type="NX_CHAR">
+#         <doc>
+#              Possibility to define an alias for the name of the y-axis.
+#         </doc>
+#     </field>
+#     <field name="y_direction" type="NX_CHAR">
+#         <doc>
+#              Human-readable field telling in which direction the y-axis points if that
+#              instance of :ref:`NXcoordinate_system` has no reference to any parent and as such
+#              is the mighty world reference frame.
+#              
+#              See docstring of x_alias for further details.
+#         </doc>
+#     </field>
+#     <field name="y" type="NX_NUMBER" units="NX_LENGTH">
+#         <doc>
+#              Base unit vector along the second axis which spans the coordinate system.
+#              This axis is frequently referred to as the y-axis in real space and
+#              the j-axis in reciprocal space.
+#         </doc>
+#         <dimensions rank="1">
+#             <dim index="1" value="3"/>
+#         </dimensions>
+#     </field>
+#     <field name="z_alias" type="NX_CHAR">
+#         <doc>
+#              Possibility to define an alias for the name of the z-axis.
+#         </doc>
+#     </field>
+#     <field name="z_direction" type="NX_CHAR">
+#         <doc>
+#              Human-readable field telling in which direction the z-axis points if that
+#              instance of :ref:`NXcoordinate_system` has no reference to any parent and as such
+#              is the mighty world reference frame.
+#              
+#              See docstring of x_alias for further details.
+#         </doc>
+#     </field>
+#     <field name="z" type="NX_NUMBER" units="NX_LENGTH">
+#         <doc>
+#              Base unit vector along the third axis which spans the coordinate system.
+#              This axis is frequently referred to as the z-axis in real space and
+#              the k-axis in reciprocal space.
+#         </doc>
+#         <dimensions rank="1">
+#             <dim index="1" value="3"/>
+#         </dimensions>
+#     </field>
+#     <field name="depends_on" type="NX_CHAR">
+#         <doc>
+#              This specificies the relation to another coordinate system by pointing to the last
+#              transformation in the transformation chain in the NXtransformations group.
+#         </doc>
+#     </field>
+#     <group type="NXtransformations">
+#         <doc>
+#              Collection of axis-based translations and rotations to describe this coordinate system
+#              with respect to another coordinate system.
+#         </doc>
+#     </group>
+# </definition>