Skip to content

Commit

Permalink
remove unmerged docs update in NXtransformations
Browse files Browse the repository at this point in the history
  • Loading branch information
@lukaspie
lukaspie committed Sep 23, 2024
1 parent c675525 commit 677b6a1
Showing 1 changed file with 29 additions and 184 deletions.
213 changes: 29 additions & 184 deletions base_classes/NXtransformations.nxdl.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,42 +55,23 @@
* ``NX_UNITLESS`` for axes for which no transformation type is specified

This class will usually contain all axes of a sample stage or goniometer or
a detector. The NeXus default :ref:`McSTAS coordinate frame<Design-CoordinateSystem>`
is assumed, but additional useful coordinate axes may be defined by using axes for which
no transformation type has been specified.
a detector. The NeXus default McSTAS coordinate frame is assumed, but additional
useful coordinate axes may be defined by using axes for which no transformation
type has been specified.

**Transformation chain**

The entry point of a chain of transformations is a field called ``depends_on``
will be outside of this class and points to a field in here. Following the chain may
also require following ``depends_on`` links to transformations outside, for example
to a common base table. If a relative path is given, it is relative to the group
enclosing the ``depends_on`` specification.
The entry point (``depends_on``) will be outside of this class and point to a
field in here. Following the chain may also require following ``depends_on``
links to transformations outside, for example to a common base table. If
a relative path is given, it is relative to the group enclosing the ``depends_on``
specification.

For a chain of three transformations, where :math:`T_1` depends on :math:`T_2`
which in turn depends on :math:`T_3`, the final *active* transformation
matrix :math:`T_f` is

.. math:: T_f = T_3 . T_2 . T_1

For example when positioning a flat detector, its pixel positions in the laboratory
reference frame (:ref:`McSTAS coordinate frame<Design-CoordinateSystem>` by default)
can be calculated by

.. math:: X_\text{lab} = T_f . X_\text{pixel} = T_3 . T_2 . T_1 . X_\text{pixel}
and that in turn depends on :math:`T_3`, the final transformation :math:`T_f` is

Note that :math:`T_1` comes first in the *depends-on* chain and is also applied first
to the pixel coordinates.
.. math:: T_f = T_3 T_2 T_1

When we say transformation :math:`A` *depends on* transformation :math:`B` we mean that
the physical motor that realizes :math:`A` is *stacked on top of* the motor that realizes :math:`B`.
So the activate coordinate transformation :math:`A` needs to be applied to a coordinate
before applying :math:`B`. In other words :math:`X' = B . A . X`.

**Transformation matrix**

In explicit terms, the transformations are a subset of affine transformations expressed as
4x4 active transformation matrices that act on homogeneous coordinates, :math:`X=[x,y,z,1]^T`.
In explicit terms, the transformations are a subset of affine transformations
expressed as 4x4 matrices that act on homogeneous coordinates, :math:`w=(x,y,z,1)^T`.

For rotation and translation,

Expand All @@ -104,16 +85,17 @@
attribute multiplied by the field value, and :math:`R` is defined as a rotation
about an axis in the direction of ``vector``, of angle of the field value.

**Usage**

NOTE
One possible use of ``NXtransformations`` is to define the motors and
transformations for a diffractometer (goniometer). Such use is mentioned
in the ``NXinstrument`` base class. Use one ``NXtransformations`` group
for each diffractometer and name the group appropriate to the device.
Collecting the motors of a sample table or xyz-stage in an NXtransformations
group is equally possible.

Following the section on the general description of axis in NXtransformations is a section which

Following the section on the general dscription of axis in NXtransformations is a section which
documents the fields commonly used within NeXus for positioning purposes and their meaning. Whenever
there is a need for positioning a beam line component please use the existing names. Use as many fields
as needed in order to position the component. Feel free to add more axis if required. In the description
Expand All @@ -126,143 +108,6 @@
* depends_on

as needed.

**Example 1: goniometer**

Position a sample mounted on a goniometer in the :ref:`McSTAS coordinate frame<Design-CoordinateSystem>`.

The sample is oriented as follows

.. math:: X_\text{lab} = R(\vec{v}_\omega, \omega) .
T(\vec{v}_z, \text{sam}_z) .
T(\vec{v}_y, \text{sam}_y) .
T(\vec{v}_x, \text{sam}_x) .
R(\vec{v}_\chi, \chi) .
R(\vec{v}_\varphi, \varphi) . X_s

where

* :math:`R(\vec{v},a)` is a rotation around vector :math:`\vec{v}` with angle :math:`a`
* :math:`T(\vec{u},t)` is a translation along vector :math:`\vec{u}` over a distance :math:`t`
* :math:`X_s` a coordinate in the sample reference frame.

.. code-block::

entry:NXentry
sample:NXsample
depends_on=transformations/phi
transformations:NXtransformations
phi=0
@depends_on=chi
@transformation_type=rotation
@vector=[-1 -0.0037 -0.002]
@units=degrees
chi=0
@depends_on=sam_x
@transformation_type=rotation
@vector=[0.0046 0.0372 0.9993]
@units=degrees
sam_x=0
@depends_on=sam_y
@transformation_type=translation
@vector=[1 0 0]
@units=mm
sam_y=0
@depends_on=sam_z
@transformation_type=translation
@vector=[0 1 0]
@units=mm
sam_z=0
@depends_on=omega
@transformation_type=translation
@vector=[0 0 1]
@units=mm
omega=174
@depends_on=.
@transformation_type=rotation
@vector=[-1 0 0]
@units=degrees

**Example 2: different coordinate system**

Define a laboratory reference frame with the X-axis along the beam and the Z-axis opposite to the direction of gravity.
Three point detectors are positioned in this reference:

* *transmission*:
* point detector in the beam
* 20 cm downstream from the sample (the origin of the reference frame)
* *vertical*:
* point detector 10 cm downstream from the sample
* making an angle of 5 degrees with the beam w.r.t. the sample
* positioned in the XZ-plane above the XY-plane
* *horizontal*:
* point detector 11 cm downstream from the sample
* making an angle of 6 degrees with the beam w.r.t. the sample
* positioned in the XY-plane above the XZ-plane

The coordinates of the point detectors in the laboratory reference frame are

* *transmission*: :math:`X_\text{lab} = T_x(20) . X_d`
* *vertical*: :math:`X_\text{lab} = R_y(-5) . T_x(10) . X_d`
* *horizontal*: :math:`X_\text{lab} = R_x(-90) . R_y(-6) . T_x(11) . X_d`

where

* :math:`T_x`, :math:`T_y`, :math:`T_z`: active transformation matrices for translation along the X, Y and Z axes
* :math:`R_x`, :math:`R_y`, :math:`R_z`: active transformation matrices for rotation around the X, Y and Z axes
* :math:`X_d` is a coordinate in the detector reference frame.

Note that as these are point detectors, we only have one coordinate :math:`X_d=[0,0,0,1]^T`.

.. code-block::

entry:NXentry
instrument:NXinstrument
vertical:NXdetector
depends_on=position/distance
position:NXtransformations
distance=10 # move downstream from the sample
@depends_on=polar
@units=cm
@vector=[1 0 0]
polar=5 # title above the horizontal plane
@depends_on=azimuth
@units=degrees
@vector=[0 -1 0]
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
@depends_on=polar
@units=cm
@vector=[1 0 0]
polar=6 # title above the horizontal plane
@depends_on=azimuth
@units=degrees
@vector=[0 -1 0]
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
@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

</doc>
<field name="AXISNAME" nameType="any" units="NX_TRANSFORMATION" type="NX_NUMBER" maxOccurs="unbounded">
<doc>
Expand Down Expand Up @@ -361,17 +206,17 @@
differences. Use of ``AXISNAME_end`` is recommended.
</doc>
</field>
<attribute name="default">
<doc>
.. index:: plotting
Declares which child group contains a path leading
to a :ref:`NXdata` group.
It is recommended (as of NIAC2014) to use this attribute
to help define the path to the default dataset to be plotted.
See https://www.nexusformat.org/2014_How_to_find_default_data.html
for a summary of the discussion.
</doc>
</attribute>
<attribute name="default">
<doc>
.. index:: plotting
Declares which child group contains a path leading
to a :ref:`NXdata` group.
It is recommended (as of NIAC2014) to use this attribute
to help define the path to the default dataset to be plotted.
See https://www.nexusformat.org/2014_How_to_find_default_data.html
for a summary of the discussion.
</doc>
</attribute>
</definition>

0 comments on commit 677b6a1

Please sign in to comment.