Fairmat 2024: use NXcoordinate_system together with NXtransformations

base_classes/NXcoordinate_system.nxdl.xml

@@ -0,0 +1,212 @@
+<?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, 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.
+
+        How many nodes of type :ref:`NXcoordinate_system` should be used in
+        an application definition?
+
+        * 0; if there is no instance of `NXcoordinate_system`` across
+          the application definition, the default NeXus
+          `McStas &lt;https://mailman2.mcstas.org/pipermail/mcstas-users/2021q2/001431.html&gt;`_
+          coordinate system is assumed.
+
+          McStas is used if no instance of NXcoordinate_system is specified.
+          However, 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.
+
+        * 1; if only one :ref:`NXcoordinate_system` 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 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 speicific
+          coordinate system that they wish to use.
+
+          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 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 system sets and instances
+          apply or take preference.
+          While these ambiguities should be avoided at all costs, the
+          opportunity for multiple sets and their instances enables to
+          have branch-specific coordinate system conventions which are
+          especially 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.
+
+          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.
+
+          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 is relevant. If these
+        ``depends_on`` hints are not provided, it is automatically assumed
+        that all branches (to arbitrary depth) use either the only
+        ``NXcoordinate_system`` instance in the tree or the application
+        definition is considered underconstrained. In the latter case, which
+        should be avoided at all costs, McStas is assumed again.
+    </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>
+    <field name="alias" type="NX_CHAR">
+        <doc>
+             An alternative name given to this coordinate system.
+        </doc>
+    </field>
+    <field name="type" type="NX_CHAR">
+        <doc>
+             Coordinate system type.
+        </doc>
+        <enumeration>
+            <item value="undefined"/>
+            <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="not applicable"/>
+            <item value="right_handed"/>
+            <item value="left_handed"/>
+        </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 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>
+             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 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>
+             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 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 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/NXrotation_conventions.nxdl.xml

@@ -0,0 +1,116 @@
+<?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
+-->
+<!--
+express conventions explicitly and understandable
+use depends_on field - not attribute - to point to conventions used-->
+<definition xmlns="http://definition.nexusformat.org/nxdl/3.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" category="base" type="group" name="NXrotation_conventions" extends="NXobject" xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd">
+    <doc>
+        Base class to hold different rotation and angle conventions.
+
+        This base class should be used at the top-level (i.e, directly below
+        ``NXentry``) within an application definition to enable the usage of
+        consistent conventions within one NeXus entry.
+
+        The definitions of these conventions follows those given in
+        Rowenhorst et al 2015 Modelling Simul. Mater. Sci. Eng. 23 083501,
+        `DOI: 10.1088/0965-0393/23/8/083501 &lt;https://www.doi.org/10.1088/0965-0393/23/8/083501&gt;`_.
+    </doc>
+    <field name="rotation_handedness" type="NX_CHAR">
+        <doc>
+            Convention how a positive rotation angle is defined when viewing
+            from the end of the rotation unit vector towards its origin,
+            i.e. in accordance with convention 2 of
+            DOI: 10.1088/0965-0393/23/8/083501.
+            Counter_clockwise is equivalent to a right-handed choice.
+            Clockwise is equivalent to a left-handed choice.
+        </doc>
+        <enumeration>
+            <item value="undefined"/>
+            <item value="counter_clockwise"/>
+            <item value="clockwise"/>
+        </enumeration>
+    </field>
+    <field name="rotation_convention" type="NX_CHAR">
+        <doc>
+            How are rotations interpreted into an orientation
+            according to convention 3 of
+            DOI: 10.1088/0965-0393/23/8/083501.
+        </doc>
+        <enumeration>
+            <item value="undefined"/>
+            <item value="passive"/>
+            <item value="active"/>
+        </enumeration>
+    </field>
+    <field name="euler_angle_convention" type="NX_CHAR">
+        <doc>
+            How are Euler angles interpreted given that
+            there are several choices (e.g. zxz, xyz)
+            according to convention 4 of DOI: 10.1088/0965-0393/23/8/083501.
+
+            The most frequently used convention is zxz, which is based on the
+            work of H.-J. Bunge, but other conventions are possible. If any
+            option other than "undefined" is, proper Euler angles are
+            distinguished from (improper) Tait-Bryan angles.
+        </doc>
+        <enumeration>
+            <item value="undefined"/>
+            <item value="zxz"/>
+            <item value="xyx"/>
+            <item value="yzy"/>
+            <item value="zyz"/>
+            <item value="xzx"/>
+            <item value="yxy"/>
+            <item value="xyz"/>
+            <item value="yzx"/>
+            <item value="zxy"/>
+            <item value="xzy"/>
+            <item value="zyx"/>
+            <item value="yxz"/>
+        </enumeration>
+    </field>
+    <field name="axis_angle_convention" type="NX_CHAR">
+        <doc>
+             To which angular range is the rotation angle argument of an
+             axis-angle pair parameterization constrained according to
+             convention 5 of DOI: 10.1088/0965-0393/23/8/083501.
+        </doc>
+        <enumeration>
+            <item value="undefined"/>
+            <item value="rotation_angle_on_interval_zero_to_pi"/>
+        </enumeration>
+    </field>
+    <field name="sign_convention" type="NX_CHAR">
+        <doc>
+             Which sign convention is followed when converting orientations
+             between different parameterizations/representations according
+             to convention 6 of DOI: 10.1088/0965-0393/23/8/083501.
+        </doc>
+        <enumeration>
+            <item value="undefined"/>
+            <item value="p_plus_one"/>
+            <item value="p_minus_one"/>
+        </enumeration>
+    </field>
+</definition>

base_classes/NXtransformations.nxdl.xml

@@ -170,8 +170,9 @@
 		</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.
 			</doc>
 		</attribute>
 		<attribute name="equipment_component" type="NX_CHAR">
@@ -202,7 +203,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>
     <attribute name="default">
@@ -218,4 +219,4 @@
             for a summary of the discussion.
         </doc>
     </attribute>
-</definition>
+</definition>