From 7f010d810db4688a701f92ea3d38a88a6453649d Mon Sep 17 00:00:00 2001 From: Lukas Pielsticker <50139597+lukaspie@users.noreply.github.com> Date: Mon, 30 Sep 2024 16:53:13 +0200 Subject: [PATCH] add NXcoordinate_system_set --- base_classes/NXcoordinate_system_set.nxdl.xml | 240 ++++++++++++++++++ 1 file changed, 240 insertions(+) create mode 100644 base_classes/NXcoordinate_system_set.nxdl.xml diff --git a/base_classes/NXcoordinate_system_set.nxdl.xml b/base_classes/NXcoordinate_system_set.nxdl.xml new file mode 100644 index 0000000000..a842d257d2 --- /dev/null +++ b/base_classes/NXcoordinate_system_set.nxdl.xml @@ -0,0 +1,240 @@ + + + + + + + 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 <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 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 + 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. + + + + 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. + + + + + + + + + + How are rotations interpreted into an orientation + according to convention 3 of + DOI: 10.1088/0965-0393/23/8/083501. + + + + + + + + + + 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. Apart from undefined, proper Euler angles + are distinguished from (improper) Tait-Bryan angles. + + + + + + + + + + + + + + + + + + + + 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. + + + + + + + + + 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. + + + + + + + + + + + + + Details about eventually relevant named directions that may give reasons for anisotropies. + The classical example is mechanical processing where one has to specify which directions + (e.g. rolling, transverse, and normal direction) align how with the direction of the base + vectors of the sample_reference_frame. + + It is assumed that the configuration is inspected by looking towards the sample surface. + If a detector is involved, it is assumed that the configuration is inspected from a position + that is located behind this detector. + + If any of these assumptions is not met, the user is required to explicitly state this. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the + base vectors of this coordinate system as Xp, Yp, Zp. + + + + + Details about the sample_reference_frame that is typically overlaid onto the surface of the sample. + + It is assumed that the configuration is inspected by looking towards the sample surface. + If a detector is involved, it is assumed that the configuration is inspected from a position + that is located behind this detector. + + If any of these assumptions is not met, the user is required to explicitly state this. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the + base vectors of this coordinate system as Xs, Ys, Zs. + + + + + Details about the detector_reference_frame for a specific detector. + + Reference DOI: 10.1016/j.matchar.2016.04.008 suggest to label the + base vectors of this coordinate system as Xd, Yd, Zd. + + It is assumed that the configuration is inspected by looking towards the sample surface + from a position that is located behind the detector. + + If any of these assumptions is not met, the user is required to explicitly state this. + + +