2.3.3.1.15. NXcoordinate_system

Status:

base class, extends NXobject

Description:

Base class to detail a coordinate system (CS). ...

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.

Whenever possible, all instances of 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 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 ancestor that contains one and only one NXcoordinate_system group is found. If such an ancestor exists, its coordinate system applies. If none is found or more than one instance of NXcoordinate_system is found at the same level, 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 entire tree, you can use depends_on="." to state that this transformation depends on the default NeXus coordinate system (which is the same as the one used by McStas).

    For the sake of clarity, even in this case it is better to be explicit and consistent 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:

    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"

    Note that this assumes that the direction of the beam is not defined in the NXbeam instance.

  • 1; if only one 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 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 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 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.

Symbols:

No symbol table

Groups cited:

NXtransformations

Structure:

origin: (optional) NX_CHAR

Human-readable field describing where the origin of this CS is. ...

Human-readable field describing 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.

type: (optional) NX_CHAR

Coordinate system type. ...

Coordinate system type.

Any of these values or a custom value (if you use a custom value, also set @custom=True): undefined | cartesian

x_alias: (optional) NX_CHAR

Opportunity to define an alias for the name of the x-axis.

x_direction: (optional) NX_CHAR

Human-readable field telling in which direction the x-axis points if that ...

Human-readable field telling in which direction the x-axis points if that instance of NXcoordinate_system has no reference to any parent and as such is the world reference frame.

Exemplar values could be direction of gravity.

x: (optional) NX_NUMBER (Rank: 1, Dimensions: [3]) {units=NX_LENGTH}

Basis unit vector along the first axis which spans the coordinate system. ...

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.

y_alias: (optional) NX_CHAR

Opportunity to define an alias for the name of the y-axis.

y_direction: (optional) NX_CHAR

Human-readable field telling in which direction the y-axis points if that ...

Human-readable field telling in which direction the y-axis points if that instance of 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.

y: (optional) NX_NUMBER (Rank: 1, Dimensions: [3]) {units=NX_LENGTH}

Basis unit vector along the second axis which spans the coordinate system. ...

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.

z_alias: (optional) NX_CHAR

Opportunity to define an alias for the name of the z-axis.

z_direction: (optional) NX_CHAR

Human-readable field telling in which direction the z-axis points if that ...

Human-readable field telling in which direction the z-axis points if that instance of 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.

z: (optional) NX_NUMBER (Rank: 1, Dimensions: [3]) {units=NX_LENGTH}

Basis unit vector along the third axis which spans the coordinate system. ...

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.

depends_on: (optional) NX_CHAR

This specifies the relation to another coordinate system by pointing to the la ...

This specifies the relation to another coordinate system by pointing to the last transformation in the transformation chain in the NXtransformations group.

TRANSFORMATIONS: (optional) NXtransformations

Collection of axis-based translations and rotations to describe this coordinat ...

Collection of axis-based translations and rotations to describe this coordinate system with respect to another coordinate system.

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/base_classes/NXcoordinate_system.nxdl.xml