Fairmat 2024: use NXcoordinate_system together with NXtransformations

base_classes/NXcomponent.nxdl.xml

@@ -74,11 +74,15 @@
             via the NXtransformations group.
 
             NeXus positions components by applying a set of translations and rotations
-            to apply to the component starting from 0, 0, 0. The order of these operations
+            to the component starting from 0, 0, 0. The order of these operations
             is critical and forms what NeXus calls a dependency chain. The depends_on
             field defines the path to the top most operation of the dependency chain or the
-            string "." if located in the origin. Usually these operations are stored in a
-            NXtransformations group. But NeXus allows them to be stored anywhere.
+            string "." if located in the origin. The depends_on can also point to an instance
+            of ``NX_coordinate_system`` if the transformations of the component depend on that
+            coordinate system.
+
+            Usually these operations are stored in a NXtransformations group.
+            But NeXus allows them to be stored anywhere.
         </doc>
     </field>
     <group type="NXtransformations">

base_classes/NXcoordinate_system.nxdl.xml

@@ -0,0 +1,238 @@
+<?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) 2023-2025 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).
+
+        Instances of ``NXcoordinate_system`` can be used to describe coordinate systems
+        other than the default `NeXus coordinate system &lt;https://manual.nexusformat.org/design.html#the-nexus-coordinate-system&gt;`_.
+
+        Whenever possible, all instances of :ref:`NXcoordinate_system`
+        should be used at the top-level (i.e, directly below ``NXentry``)
+        within an application definition or within a NeXus file.
+
+        ``NXcoordinate_system`` can be part of the transformations chain
+        using :ref:`NXtransformations`, where it acts as a linear
+        change-of-basis transformation (using a 3x3 matrix with the basis
+        vectors ``x``, `y``, and ``z`` as columns).
+
+        Any group that has an optional ``depends_on`` field or any field
+        that has an optional ``depends_on`` attribute has a fallback when
+        ``depends_on`` is not provided. The fallback behavior involves
+        traversing up the hierarchy until the first parent that contains one
+        and only one ``NXcoordinate_system`` group is found. If such a parent
+        exists, its coordinate system applies. If none is found, then the
+        current coordinate system is not defined with respect to anything
+        else. As an example, if there is only one NXcoordinate_system called
+        "my_coordinate_system" defined directly under ``NXentry``, each
+        optional ``depends_on`` field/attribute that is not defined
+        automatically defaults to ``depends_on=my_coordinate_system``.
+
+        How many groups of type ``NXcoordinate_system`` should be used in
+        an application definition?
+
+        * 0; if there is no instance of ``NXcoordinate_system`` across the
+          application definition or the data tree, you can use ``depends_on="."``
+          to state that this transformation depends on the default
+          `NeXus coordinate system &lt;https://manual.nexusformat.org/design.html#the-nexus-coordinate-system&gt;`_
+          (which is the same as the one used by `McStas &lt;https://mcstas.org/&gt;`_).
+
+          For the sake of clarity, 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.
+
+          The default NeXus coordinate system (i.e., the McStas coordinate
+          system) can be expressed as follows:
+
+          .. code-block::
+
+            mcstas@NXcoordinate_system
+                x = [1, 0, 0]
+                y = [0, 1, 0]
+                z = [0, 0, 1]
+                @y_direction = "opposite to gravity"
+                @z_direction = "direction of the primary beam"
+
+        * 1; if only one :ref:`NXcoordinate_system` is defined, it should be
+          placed as high up in the tree hierarchy (ideally right below an
+          instance of NXentry) of the application definition tree as possible.
+          This coordinate system 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.
+
+          If this is the case, it is assumed that this ``NXcoordinate_system``
+          overwrites the NeXus default McStas coordinate system, i.e. users
+          can thereby conveniently and explicitly specify the
+          coordinate system that they wish to use.
+
+          This case has the advantage that it is explicit and offers no
+          ambiguities. However, in reality typically multiple coordinate
+          systems have to be mastered especially for complex multi-signal
+          modality experiments.
+
+          If this case is realized, the best practice is that in every
+          case where this coordinate system should be referred to the respective
+          group has a ``depends_on`` field, to clearly indicate which 
+          specific coordinate systems is referred to.
+
+        * 2 and more; as soon as more than one :ref:`NXcoordinate_system`
+          is specified somewhere in the tree, different interpretations are
+          possible as to which of these coordinate systems
+          apply or take preference.
+          While these ambiguities should be avoided if possible, the
+          opportunity for multiples instances enables to have coordinate
+          system conventions that are specific for some part of the NeXus
+          tree. This is especially useful for deep groups where
+          multiple scientific methods are combined or cases where having a
+          definition of global conversion tables how to convert between
+          representations in different coordinate systems is not desired
+          or available for now.
+
+          To resolve the possible ambiguities which specific coordinate systems 
+          in an :ref:`NXtransformations` train is referred to, it is even more
+          important to use the ``depends_on`` field in groups and the ``depends_on``
+          attribute in NXtransformations to refer to one of the ``NXcoordinate_system``
+          instances. 
+
+          In the case of two or more instances of ``NXcoordinate_system`` it
+          is advised to specify the relationship between the two coordinate
+          systems by using the :ref:`NXtransformations` group within
+          ``NXcoordinate_system``.
+
+        In any case, users are encouraged to write explicit and clean
+        ``depends_on`` fields in all groups that encode information for which
+        the interpretation of coordinate systems and transformations is relevant.
+        If these ``depends_on`` instances are not provided or no instance of
+        ``NX_coordinate_system`` exists in the upper part of the hierarchy,
+        the application definition is considered underconstrained. Note that this
+        is the case for all files that were created before ``NXcoordinate_system``
+        was added.
+    </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 exits the pole piece*,
+            *barycenter of the triangle*, *center of mass of the stone*.
+        </doc>
+    </field>
+    <field name="type" type="NX_CHAR">
+        <doc>
+            Coordinate system type.
+        </doc>
+        <enumeration open="true">
+            <item value="undefined"/>
+            <item value="cartesian"/>
+        </enumeration>
+    </field>
+    <field name="x_alias" type="NX_CHAR">
+        <doc>
+            Opportunity 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>
+            Basis unit vector along the first axis which spans the coordinate system.
+            This axis is frequently referred to as the x-axis in Euclidean space and
+            the i-axis in reciprocal space.
+
+            Note that `x``, ``y``, and ``z`` must constitute a basis, i.e., a set of linearly
+            independent vectors that span the vector space.
+        </doc>
+        <dimensions rank="1">
+            <dim index="1" value="3"/>
+        </dimensions>
+    </field>
+    <field name="y_alias" type="NX_CHAR">
+        <doc>
+            Opportunity 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_direction`` for further details.
+        </doc>
+    </field>
+    <field name="y" type="NX_NUMBER" units="NX_LENGTH">
+        <doc>
+            Basis unit vector along the second axis which spans the coordinate system.
+            This axis is frequently referred to as the y-axis in Euclidean 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>
+            Opportunity 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>
+            Basis unit vector along the third axis which spans the coordinate system.
+            This axis is frequently referred to as the z-axis in Euclidean 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 specifies 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>

base_classes/NXtransformations.nxdl.xml

@@ -60,10 +60,10 @@
 		type has been specified.
 
 		The entry point (``depends_on``) will be outside of this class and point to a
-		field in here. Following the chain may also require following ``depends_on``
-		links to transformations outside, for example to a common base table.  If
-		a relative path is given, it is relative to the group enclosing the ``depends_on``
-		specification.
+		field in here (or to an instance of ``NX_coordinate_system``). Following the
+		chain may also require following ``depends_on``	links to transformations outside,
+		for example to a common base table.  If a relative path is given, it is relative
+		to the group enclosing the ``depends_on`` 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
@@ -108,6 +108,14 @@
 		* depends_on
 
 		as needed.
+
+		NOTE
+
+		NXtransformations follows the **active** transformation convention. This means that the transformation describes
+		how an object is moved or rotated within the coordinate system. In other words, the transformation
+		actively changes the position or orientation of the object itself. This is in contrast to a **passive** transformation,
+		which changes the frame of reference or coordinate system, while the object remains fixed. In case it is needed 
+		to describe multiple coordinate systems, it is strongly suggested to use the :ref:`NXcoordinate_system` base class.
 	</doc>
 	<field name="AXISNAME" nameType="any" units="NX_TRANSFORMATION" type="NX_NUMBER" maxOccurs="unbounded">
 		<doc>
@@ -148,6 +156,11 @@
 				For ``translation`` axes the direction should be chosen for
 				increasing displacement. For general axes, an appropriate direction
 				should be chosen.
+
+				Note that if the ``NXtransformation`` depends on a coordinate system
+				(i.e., its ``depends_on`` attribute points to an instance :ref:`NXcoordinate_system`),
+				the rotation is right handed in that coordinate system, even if the the coordinate system
+				itself is left-handed (as defined by the determinant of its base vectors).
 			</doc>
 			<dimensions rank="1">
 				<dim index="1" value="3" />
@@ -170,8 +183,12 @@
 		</attribute>
 		<attribute name="depends_on" type="NX_CHAR">
 			<doc>
-				Points to the path to a field defining the axis on which this
-				depends or the string ".".
+				Points to the path of a field defining the axis on which this instance of
+				NXtransformations depends or the string ".". It can also point to an instance of
+				``NX_coordinate_system`` if this transformation depends on it.
+
+				If it is the string ".", it is explicitly pointing towards the default 
+				`NeXus coordinate system &lt;https://manual.nexusformat.org/design.html#the-nexus-coordinate-system&gt;`_.
 			</doc>
 		</attribute>
 		<attribute name="equipment_component" type="NX_CHAR">
@@ -202,7 +219,7 @@
 			the corresponding axis moves during the exposure of a frame.  Ideally, the
 			value of this field added to each value of ``AXISNAME`` would agree with the
 			corresponding values of ``AXISNAME_end``, but there is a possibility of significant
-			differences.  Use of ``AXISNAME_end`` is recommended.
+			differences. Use of ``AXISNAME_end`` is recommended.
 		</doc>
 	</field>
 </definition>