readd NXtransformations to NXcoordinate_system

contributed_definitions/NXcoordinate_system.nxdl.xml

@@ -140,17 +140,16 @@ https://www.zenodo.org/record/3526738/files/lyso009a_0087.JF07T32V01_master.h5?d
             <dim index="1" value="3"/>
         </dimensions>
     </field>
-    <field name="offset" type="NX_NUMBER">
+    <field name="depends_on" type="NX_CHAR">
         <doc>
-             Translational shift during a passive transformation from the coordinate system
-             defined in the the `depends_on` attribute.
+             This specificies the relation to another coordinate system by pointing to the last 
+             transformation in the transformation chain in the NXtransformations group.
         </doc>
     </field>
-    <attribute name="depends_on" type="NX_CHAR">
+    <group type="NXtransformations">
         <doc>
-             This defines which coordinate system the base transformation defined by the 
-             `x`, `y`, and `z` fields refers to. 
-             By default, it is (.) and points to the McStas coordinate system.
+             Collection of axis-based translations and rotations to describe this coordinate system
+             with respect to another coordinate system.
         </doc>
-    </attribute>
+    </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
+           adviused 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

contributed_definitions/nyaml/NXcoordinate_system.yaml

@@ -91,19 +91,17 @@ NXcoordinate_system(NXobject):
     dimensions:
       rank: 1
       dim: [[1, 3]]
-  offset(NX_NUMBER):
+  depends_on(NX_CHAR):
     doc: |
-      Translational shift during a passive transformation from the coordinate system
-      defined in the the `depends_on` attribute.
-  \@depends_on:
-    type: NX_CHAR
+      This specificies the relation to another coordinate system by pointing to the last
+      transformation in the transformation chain in the NXtransformations group.
+  (NXtransformations):
     doc: |
-      This defines which coordinate system the base transformation defined by the
-      `x`, `y`, and `z` fields refers to.
-      By default, it is (.) and points to the McStas coordinate system.
+      Collection of axis-based translations and rotations to describe this coordinate system
+      with respect to another coordinate system.
 
 # ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++
-# 8f206af983210d7f46437cc8940974e32cc2966d997126c290089ef355f6fb59
+# 76304029bbb3a1882d9855d8b170be0cfb2a18eebd5f0b60c752ae35c441f906
 # <?xml version='1.0' encoding='UTF-8'?>
 # <?xml-stylesheet type="text/xsl" href="nxdlformat.xsl"?>
 # <!--
@@ -246,17 +244,16 @@ NXcoordinate_system(NXobject):
 #             <dim index="1" value="3"/>
 #         </dimensions>
 #     </field>
-#     <field name="offset" type="NX_NUMBER">
+#     <field name="depends_on" type="NX_CHAR">
 #         <doc>
-#              Translational shift during a passive transformation from the coordinate system
-#              defined in the the `depends_on` attribute.
+#              This specificies the relation to another coordinate system by pointing to the last 
+#              transformation in the transformation chain in the NXtransformations group.
 #         </doc>
 #     </field>
-#     <attribute name="depends_on" type="NX_CHAR">
+#     <group type="NXtransformations">
 #         <doc>
-#              This defines which coordinate system the base transformation defined by the 
-#              `x`, `y`, and `z` fields refers to. 
-#              By default, it is (.) and points to the McStas coordinate system.
+#              Collection of axis-based translations and rotations to describe this coordinate system
+#              with respect to another coordinate system.
 #         </doc>
-#     </attribute>
+#     </group>
 # </definition>

contributed_definitions/nyaml/NXcoordinate_system_set.yaml

@@ -2,24 +2,23 @@ category: base
 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 <https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html>`_
     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
+    adviused 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
@@ -79,7 +78,10 @@ doc: |
     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
@@ -88,11 +90,136 @@ doc: |
 type: group
 NXcoordinate_system_set(NXobject):
   (NXcoordinate_system):
-# How to interpret "depends_on" calls for NXtransformations instances which live
+
+  # How to interpret "depends_on" calls for NXtransformations instances which live
+  # within an instance of NXcoordinate_system(_set)?
+  # Depends on cardinality of NXcoordinate_system_set, i.e. how many NXcoordinate_system are defined?
+  # - 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
+
+# ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++
+# 19dcdaa81b00c7163aed10d5e3a9fd6393f681c1df3bf0b79af8db1e9f8e746e
+# <?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_set" extends="NXobject" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+#     <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 application definition?
+#          
+#          * 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 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
+#            adviused 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
+#            conveniently and explicitly specify the coordinate system(s) that
+#            they wish to use.
+#            
+#            Users are encouraged to write also explicit and clean depends_on fields in
+#            all groups that encode information about where the interpretation of coordinate
+#            systems is relevant. If these depends_on hints are not provided, it is
+#            automatically assumed that all children (to arbitrary depth)
+#            of that branch and sub-branches below the one in which that
+#            :ref:`NXcoordinate_system_set` is defined use either the only NXcoordinate_system_set
+#            instance in that set or the application definition is considered
+#            underconstrained which should at all costs be avoided and in which case
+#            again McStas is assumed.
+#          * 2 and more; as soon as more than one :ref:`NXcoordinate_system_set` is specified
+#            somewhere in the tree, different interpretations are possible as to which
+#            of these coordinate system sets and instances apply or take preference.
+#            We realize that such ambiguities should at all costs be avoided.
+#            However, the opportunity for multiple sets and their instances enables to
+#            have branch-specific coordinate system conventions which could especially
+#            be useful for deep classes where multiple scientific methods are combined or
+#            cases where having a definition of global translation and conversion tables
+#            how to convert between representations in different coordinate systems
+#            is not desired or available for now.
+#            We argue that having 2 or more :ref:`NXcoordinate_system_set` instances and respective
+#            NXcoordinate_system instances makes the interpretation eventually unnecessary
+#            complicated. Instead, developers of application definitions should always try
+#            to work for clarity and thus use only one top-level coordinate system set.
+#          
+#          For these reasons we conclude that the option with one top-level
+#          :ref:`NXcoordinate_system_set` instance is the preferred choice.
+#          
+#          McStas is used if neither an instance of :ref:`NXcoordinate_system_set` nor an instance
+#          of NXcoordinate_system is specified. However, even in this case it is better
+#          to be explicit like for every other coordinate system definition to support
+#          users with interpreting the content and logic behind every instance of the tree.
+#          
+#          How to store coordinate systems inside :ref:`NXcoordinate_system_set`?
+#          Individual coordinate systems should be specified as members of the
+#          :ref:`NXcoordinate_system_set` instance using instances of NXcoordinate_system.
+#          
+#          How many individual instances of NXcoordinate_system to allow within one
+#          instance of :ref:`NXcoordinate_system_set`?
+#          
+#          * 0; This case should be avoided for the sake of clarity but this case could
+#            mean the authors of the definition meant that McStas is used. We conclude,
+#            McStas is used in this case.
+#          * 1; Like above-mentioned this case has the advantage that it is explicit
+#            and faces no ambiguities. However, in reality typically multiple
+#            coordinate systems have to be mastered especially for complex
+#            multi-signal modality experiments.
+#          * 2 or more; If this case is realized, the best practice is that in every
+#            case where a coordinate system should be referred to the respective class
+#            has a depends_on field which resolves the possible ambiguities which specific
+#            coordinate systems is referred to. The benefit of this explicit and clear
+#            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. 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
+#          always guide the user for each group and field which of the coordinate system
+#          one refers to.
+#     </doc>
+#     <group type="NXcoordinate_system"/>
+#     <!--How to interpret "depends_on" calls for NXtransformations instances which live
 # within an instance of NXcoordinate_system(_set)?
 # Depends on cardinality of NXcoordinate_system_set, i.e. how many NXcoordinate_system are defined?
 # - 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>