diff --git a/base_classes/NXtransformations.nxdl.xml b/base_classes/NXtransformations.nxdl.xml index 41d2d5d7da..fc537ae062 100644 --- a/base_classes/NXtransformations.nxdl.xml +++ b/base_classes/NXtransformations.nxdl.xml @@ -22,6 +22,17 @@ # For further information, see http://www.nexusformat.org --> + + + These symbols will be used below to coordinate fields with the same + shape. + + + + number of dimension in the coordinate_system (typically 3). + + + Collection of axis-based translations and rotations to describe a geometry. May also contain axes that do not move and therefore do not have a transformation @@ -210,47 +221,87 @@ vertical:NXdetector depends_on=position/distance position:NXtransformations - distance=10 # move downstream from the sample + distance=10 # move downstream from the sample @depends_on=polar @units=cm @vector=[1 0 0] - polar=5 # title above the horizontal plane + polar=5 # title above the horizontal plane @depends_on=azimuth @units=degrees @vector=[0 -1 0] - azimuth=0 # stay in the vertical plane + azimuth=0 # stay in the vertical plane @depends_on=/entry/coordinate_system/beam @units=degrees @vector=[-1 0 0] horizontal:NXdetector depends_on=position/distance position:NXtransformations - distance=11 # move downstream from the sample + distance=11 # move downstream from the sample @depends_on=polar @units=cm @vector=[1 0 0] - polar=6 # title above the horizontal plane + polar=6 # title above the horizontal plane @depends_on=azimuth @units=degrees @vector=[0 -1 0] - azimuth=90 # rotate to the horizontal plane + azimuth=90 # rotate to the horizontal plane @depends_on=/entry/coordinate_system/beam @units=degrees @vector=[-1 0 0] transmission:NXdetector depends_on=position/distance position:NXtransformations - distance=20 # move downstream from the sample + distance=20 # move downstream from the sample @depends_on=/entry/coordinate_system/beam @units=cm @vector=[1 0 0] coordinate_system:NXtransformations beam=NaN # value is never used @depends_on=gravity - @vector=[1 0 0] # X-axis points in the beam direction - gravity=NaN # value is never used - @depends_on=. # end of the chain - @vector=[0 0 -1] # Z-axis points up + @vector=[1 0 0] + @direction=X-axis points in the beam direction + gravity=NaN + @depends_on=/entry/analyser_cs/gravity # end of the chain + @vector=[1 0 0] + @transformation_type=rotation + @direction=Z-axis points up + + **Example 3: base changes between different coordinate systems** + + Define transformations to change bases from the NeXus coordinate frame (McStas) + with the Z-axis along the beam to a new laboratory reference based on X-, Y-, and Z-axes of + the sample stage. The new coordinate system is left-handed, whereas McStas is defined as + right-handed. Thus, the following transformatios need to be applied: + + - rotation about y-axis by `180-source_polar_angle`, where `source_polar_angle` is the angle between the Z-axis + of the new CS and the beam axis. + - rotation about z-axis (by the azimuthal angle of the source w.r.t the projection + of the source axis of the new CS) + - change of handedness: x = - x + + .. code-block:: + + entry:NXentry + transformations:NXtransformations + sample_stage_coordinate_system:NaN # value is never used + @depends_on=y_rotation + @direction="X-axis points in sample stage x direction, + Y-Axis points in sample stage y direction (towards the operator), + Z-axis points upwards, + forming a left-handed coordinate_system" + @matrix = [[1 0 0], [0 1 0], [0 0 1]] + y_rotation:180-source_polar_angle + @transformation_type=rotation + @depends_on=sample_stage_cs + @vector=[0, 1, 0] + z_rotation:source_azimuth_angle + @transformation_type=rotation + @depends_on=base_change + @vector=[0, 0, 1] + base_change=1 # no magnification + @transformation_type=base_change + @depends_on=. + @matrix = [[-1 0 0], [0 1 0], [0 0 1]] @@ -271,14 +322,18 @@ in which case the values are angular rotations around the axis. If this attribute is omitted, this is an axis for which there - is no motion to be specifies, such as the direction of gravity, + is no motion to be specified, such as the direction of gravity, or the direction to the source, or a basis vector of a coordinate frame. + + The transformation_type may be ``base_change``, in which case a matrix containing + n_dim column vectors of n_dim length should be supplied. + @@ -292,7 +347,27 @@ should be chosen. - + + + + + + Human-readable field telling in which direction the axis points. This is to be used + to a define a reference frame (i.e, for axes with no transformation_type). + + If `@matrix` is filled, then this field shall contain the direction of all n-dim matrix + elements. + + Exemplar values for one axis could be the direction of gravity. + + + + + For axes of transformation_type ``base_change``, this matrix contains n_dim column vectors + of n_dim length. + + + @@ -302,7 +377,7 @@ as the mechanical offset from mounting the axis to its dependency. - + @@ -312,9 +387,8 @@ - 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. + Points to the path to a field defining the axis on which this + depends or the string "." when at the end of the chain. @@ -345,7 +419,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. diff --git a/base_classes/nyaml/NXtransformations.yaml b/base_classes/nyaml/NXtransformations.yaml index 1d57a9386a..6683b6ca49 100644 --- a/base_classes/nyaml/NXtransformations.yaml +++ b/base_classes/nyaml/NXtransformations.yaml @@ -195,7 +195,7 @@ doc: | @depends_on=azimuth @units=degrees @vector=[0 -1 0] - azimuth=0 # stay in the vertical plane + azimuth=0 # stay in the vertical plane @depends_on=/entry/coordinate_system/beam @units=degrees @vector=[-1 0 0] @@ -210,7 +210,7 @@ doc: | @depends_on=azimuth @units=degrees @vector=[0 -1 0] - azimuth=90 # rotate to the horizontal plane + azimuth=90 # rotate to the horizontal plane @depends_on=/entry/coordinate_system/beam @units=degrees @vector=[-1 0 0] @@ -222,12 +222,58 @@ doc: | @units=cm @vector=[1 0 0] coordinate_system:NXtransformations - beam=NaN # value is never used + beam=NaN # value is never used @depends_on=gravity - @vector=[1 0 0] # X-axis points in the beam direction - gravity=NaN # value is never used - @depends_on=. # end of the chain - @vector=[0 0 -1] # Z-axis points up + @vector=[1 0 0] + @direction=X-axis points in the beam direction + gravity=NaN + @depends_on=/entry/analyser_cs/gravity # end of the chain + @vector=[1 0 0] + @transformation_type=rotation + @direction=Z-axis points up + + **Example 3: base changes between different coordinate systems** + + Define transformations to change bases from the NeXus coordinate frame (McStas) + with the Z-axis along the beam to a new laboratory reference based on X-, Y-, and Z-axes of + the sample stage. The new coordinate system is left-handed, whereas McStas is defined as + right-handed. Thus, the following transformatios need to be applied: + + - rotation about y-axis by `180-source_polar_angle`, where `source_polar_angle` is the angle between the Z-axis + of the new CS and the beam axis. + - rotation about z-axis (by the azimuthal angle of the source w.r.t the projection + of the source axis of the new CS) + - change of handedness: x = - x + + .. code-block:: + + entry:NXentry + transformations:NXtransformations + sample_stage_coordinate_system:NaN # value is never used + @depends_on=y_rotation + @direction="X-axis points in sample stage x direction, + Y-Axis points in sample stage y direction (towards the operator), + Z-axis points upwards, + forming a left-handed coordinate_system" + @matrix = [[1 0 0], [0 1 0], [0 0 1]] + y_rotation:180-source_polar_angle + @transformation_type=rotation + @depends_on=sample_stage_cs + @vector=[0, 1, 0] + z_rotation:source_azimuth_angle + @transformation_type=rotation + @depends_on=base_change + @vector=[0, 0, 1] + base_change=1 # no magnification + @transformation_type=base_change + @depends_on=. + @matrix = [[-1 0 0], [0 1 0], [0 0 1]] +symbols: + doc: | + These symbols will be used below to coordinate fields with the same + shape. + n_dim: | + number of dimension in the coordinate_system (typically 3). type: group ignoreExtraGroups: true ignoreExtraFields: true @@ -255,12 +301,15 @@ NXtransformations(NXobject): in which case the values are angular rotations around the axis. If this attribute is omitted, this is an axis for which there - is no motion to be specifies, such as the direction of gravity, + is no motion to be specified, such as the direction of gravity, or the direction to the source, or a basis vector of a coordinate frame. + + The transformation_type may be ``base_change``, in which case a matrix containing + n_dim column vectors of n_dim length should be supplied. # - enumeration: [translation, rotation] + enumeration: [translation, rotation, base_change] \@vector: exists: optional type: NX_NUMBER @@ -274,7 +323,25 @@ NXtransformations(NXobject): should be chosen. dimensions: rank: 1 - dim: [[1, 3]] + dim: [[1, n_dim]] + \@direction: + doc: | + Human-readable field telling in which direction the axis points. This is to be used + to a define a reference frame (i.e, for axes with no transformation_type). + + If `@matrix` is filled, then this field shall contain the direction of all n-dim matrix + elements. + + Exemplar values for one axis could be the direction of gravity. + \@matrix: + exists: optional + type: NX_NUMBER + doc: | + For axes of transformation_type ``base_change``, this matrix contains n_dim column vectors + of n_dim length. + dimensions: + rank: 2 + dim: [[n_dim, n_dim]] \@offset: type: NX_NUMBER doc: | @@ -283,7 +350,7 @@ NXtransformations(NXobject): as the mechanical offset from mounting the axis to its dependency. dimensions: rank: 1 - dim: [[1, 3]] + dim: [[1, n_dim]] \@offset_units: type: NX_CHAR doc: | @@ -291,9 +358,8 @@ NXtransformations(NXobject): \@depends_on: type: NX_CHAR doc: | - 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. + Points to the path to a field defining the axis on which this + depends or the string "." when at the end of the chain. \@equipment_component: type: NX_CHAR doc: | @@ -324,7 +390,7 @@ NXtransformations(NXobject): 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. \@default: doc: | .. index:: plotting @@ -338,7 +404,7 @@ NXtransformations(NXobject): for a summary of the discussion. # ++++++++++++++++++++++++++++++++++ SHA HASH ++++++++++++++++++++++++++++++++++ -# 9fe265099bd7f15a00e1f244948ae17ceb523ee01b164cc947ac5f14e9f68917 +# d27d2b88fa7e6bc8540257076c58577b04b0947ef9be186c7980e986f0d5b916 # # # # +# +# +# These symbols will be used below to coordinate fields with the same +# shape. +# +# +# +# number of dimension in the coordinate_system (typically 3). +# +# +# # # Collection of axis-based translations and rotations to describe a geometry. # May also contain axes that do not move and therefore do not have a transformation @@ -551,26 +628,26 @@ NXtransformations(NXobject): # vertical:NXdetector # depends_on=position/distance # position:NXtransformations -# distance=10 # move downstream from the sample +# distance=10 # move downstream from the sample # @depends_on=polar # @units=cm # @vector=[1 0 0] -# polar=5 # title above the horizontal plane +# polar=5 # title above the horizontal plane # @depends_on=azimuth # @units=degrees # @vector=[0 -1 0] -# azimuth=0 # stay in the vertical plane +# azimuth=0 # stay in the vertical plane # @depends_on=/entry/coordinate_system/beam # @units=degrees # @vector=[-1 0 0] # horizontal:NXdetector # depends_on=position/distance # position:NXtransformations -# distance=11 # move downstream from the sample +# distance=11 # move downstream from the sample # @depends_on=polar # @units=cm # @vector=[1 0 0] -# polar=6 # title above the horizontal plane +# polar=6 # title above the horizontal plane # @depends_on=azimuth # @units=degrees # @vector=[0 -1 0] @@ -581,17 +658,57 @@ NXtransformations(NXobject): # transmission:NXdetector # depends_on=position/distance # position:NXtransformations -# distance=20 # move downstream from the sample +# distance=20 # move downstream from the sample # @depends_on=/entry/coordinate_system/beam # @units=cm # @vector=[1 0 0] # coordinate_system:NXtransformations -# beam=NaN # value is never used +# beam=NaN # value is never used # @depends_on=gravity -# @vector=[1 0 0] # X-axis points in the beam direction -# gravity=NaN # value is never used -# @depends_on=. # end of the chain -# @vector=[0 0 -1] # Z-axis points up +# @vector=[1 0 0] +# @direction=X-axis points in the beam direction +# gravity=NaN +# @depends_on=/entry/analyser_cs/gravity # end of the chain +# @vector=[1 0 0] +# @transformation_type=rotation +# @direction=Z-axis points up +# +# **Example 3: base changes between different coordinate systems** +# +# Define transformations to change bases from the NeXus coordinate frame (McStas) +# with the Z-axis along the beam to a new laboratory reference based on X-, Y-, and Z-axes of +# the sample stage. The new coordinate system is left-handed, whereas McStas is defined as +# right-handed. Thus, the following transformatios need to be applied: +# +# - rotation about y-axis by `180-source_polar_angle`, where `source_polar_angle` is the angle between the Z-axis +# of the new CS and the beam axis. +# - rotation about z-axis (by the azimuthal angle of the source w.r.t the projection +# of the source axis of the new CS) +# - change of handedness: x = - x +# +# .. code-block:: +# +# entry:NXentry +# transformations:NXtransformations +# sample_stage_coordinate_system:NaN # value is never used +# @depends_on=y_rotation +# @direction="X-axis points in sample stage x direction, +# Y-Axis points in sample stage y direction (towards the operator), +# Z-axis points upwards, +# forming a left-handed coordinate_system" +# @matrix = [[1 0 0], [0 1 0], [0 0 1]] +# y_rotation:180-source_polar_angle +# @transformation_type=rotation +# @depends_on=sample_stage_cs +# @vector=[0, 1, 0] +# z_rotation:source_azimuth_angle +# @transformation_type=rotation +# @depends_on=base_change +# @vector=[0, 0, 1] +# base_change=1 # no magnification +# @transformation_type=base_change +# @depends_on=. +# @matrix = [[-1 0 0], [0 1 0], [0 0 1]] # # # @@ -612,14 +729,18 @@ NXtransformations(NXobject): # in which case the values are angular rotations around the axis. # # If this attribute is omitted, this is an axis for which there -# is no motion to be specifies, such as the direction of gravity, +# is no motion to be specified, such as the direction of gravity, # or the direction to the source, or a basis vector of a # coordinate frame. +# +# The transformation_type may be ``base_change``, in which case a matrix containing +# n_dim column vectors of n_dim length should be supplied. # # # # # +# # # # @@ -633,7 +754,27 @@ NXtransformations(NXobject): # should be chosen. # # -# +# +# +# +# +# +# Human-readable field telling in which direction the axis points. This is to be used +# to a define a reference frame (i.e, for axes with no transformation_type). +# +# If `@matrix` is filled, then this field shall contain the direction of all n-dim matrix +# elements. +# +# Exemplar values for one axis could be the direction of gravity. +# +# +# +# +# For axes of transformation_type ``base_change``, this matrix contains n_dim column vectors +# of n_dim length. +# +# +# # # # @@ -643,7 +784,7 @@ NXtransformations(NXobject): # as the mechanical offset from mounting the axis to its dependency. # # -# +# # # # @@ -653,9 +794,8 @@ NXtransformations(NXobject): # # # -# 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. +# Points to the path to a field defining the axis on which this +# depends or the string "." when at the end of the chain. # # # @@ -686,7 +826,7 @@ NXtransformations(NXobject): # 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. # # #