2.3.3.3.83. NXcoordinate_system_set

Status:

base class, extends NXobject

Description:

Base class to hold different coordinate systems and representation conversions. ...

Base class to hold different coordinate systems and representation conversions.

How many nodes of type NXcoordinate_system_set should be used in an application definition?

  • 0; if there is no instance of NXcoordinate_system_set and therein or elsewhere across the application definition, an instance of NXcoordinate_system is defined, the default NeXus McStas coordinate system is assumed. This makes NXcoordinate_system_set and NXcoordinate_system base classes backwards compatible to older NeXus conventions and classes.

  • 1; if only one 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 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 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 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 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 NXcoordinate_system_set instance is the preferred choice.

McStas is used if neither an instance of 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 NXcoordinate_system_set? Individual coordinate systems should be specified as members of the NXcoordinate_system_set instance using instances of NXcoordinate_system.

How many individual instances of NXcoordinate_system to allow within one instance of 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 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.

Symbols:

No symbol table

Groups cited:

NXcoordinate_system

Structure:

rotation_handedness: (optional) NX_CHAR

Convention how a positive rotation angle is defined when viewing ...

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.

Any of these values: undefined | counter_clockwise | clockwise

rotation_convention: (optional) NX_CHAR

How are rotations interpreted into an orientation ...

How are rotations interpreted into an orientation according to convention 3 of DOI: 10.1088/0965-0393/23/8/083501.

Any of these values: undefined | passive | active

euler_angle_convention: (optional) NX_CHAR

How are Euler angles interpreted given that there are several choices (e.g. zx ...

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.

Any of these values:

  • undefined

  • zxz

  • xyx

  • yzy

  • zyz

  • xzx

  • yxy

  • xyz

  • yzx

  • zxy

  • xzy

  • zyx

  • yxz

axis_angle_convention: (optional) NX_CHAR

To which angular range is the rotation angle argument of an ...

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.

Any of these values: undefined | rotation_angle_on_interval_zero_to_pi

sign_convention: (optional) NX_CHAR

Which sign convention is followed when converting orientations ...

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.

Any of these values: undefined | p_plus_one | p_minus_one

COORDINATE_SYSTEM: (optional) NXcoordinate_system

processing_reference_frame: (optional) NXcoordinate_system

Details about eventually relevant named directions that may give reasons for a ...

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.

sample_reference_frame: (optional) NXcoordinate_system

Details about the sample_reference_frame that is typically overlaid onto the s ...

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.

detector_reference_frameID: (optional) NXcoordinate_system

Details about the detector_reference_frame for a specific detector. ...

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.

Hypertext Anchors

List of hypertext anchors for all groups, fields, attributes, and links defined in this class.

NXDL Source:

https://github.com/FAIRmat-NFDI/nexus_definitions/tree/fairmat/contributed_definitions/NXcoordinate_system_set.nxdl.xml