Skip to content

Commit

Permalink
add NXcoordinate_system_set
Browse files Browse the repository at this point in the history
  • Loading branch information
@lukaspie
lukaspie committed Oct 17, 2024
1 parent ee792e6 commit 7f010d8
Showing 1 changed file with 240 additions and 0 deletions.
240 changes: 240 additions & 0 deletions base_classes/NXcoordinate_system_set.nxdl.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,240 @@
<?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="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
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.
</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. Apart from undefined, 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>
<!--possibility to add further coordinate systems-->
<group type="NXcoordinate_system"/>
<!--frequently used coordinate systems with frequently relevant specializations follow
convention 1 of DOI: 10.1088/0965-0393/23/8/083501 is implemented by inheriting type from NXcoordinate_system-->
<group name="processing_reference_frame" type="NXcoordinate_system">
<doc>
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.
</doc>
</group>
<group name="sample_reference_frame" type="NXcoordinate_system">
<doc>
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.
</doc>
</group>
<group name="detector_reference_frameID" type="NXcoordinate_system">
<doc>
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.
</doc>
</group>
</definition>

0 comments on commit 7f010d8

Please sign in to comment.