--- NXmx_1_4.nxdl.xml 2016-10-05 16:35:39.000000000 +0200
+++ definitions/applications/NXmx.nxdl.xml 2016-10-14 07:18:37.000000000 +0200
@@ -22,27 +22,36 @@
# For further information, see http://www.nexusformat.org
-->
<definition name="NXmx" extends="NXobject" type="group"
- version="1.4" category="application"
+ version="1.5" category="application"
xmlns="http://definition.nexusformat.org/nxdl/3.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
>
<symbols>
- <!-- TODO define options for most fields to allow them to be either scaler
- np i,j np,i,j So indices can be aligned sensibly in an automated way. -->
+ <!-- TODO define options for most fields to allow them to be either scalar
+ or arrays indexed by np, i, j, k, ...,
+ -->
<doc>
These symbols will be used below to coordinate datasets
- with the same shape.
+ with the same shape. Most MX x-ray detectors will produce
+ two-dimensional images. Some will produce three-dimensional
+ images, using one of the indices to select a detector element.
</doc>
+ <symbol name="dataRank">
+ <doc>rank of the ``data`` field</doc>
+ </symbol>
<symbol name="np">
<doc>number of scan points</doc>
</symbol>
<symbol name="i">
- <doc>number of detector pixels in the slow direction</doc>
+ <doc>number of detector pixels in the slowest direction</doc>
</symbol>
<symbol name="j">
- <doc>number of detector pixels in the fast direction</doc>
+ <doc>number of detector pixels in the second slowest direction</doc>
+ </symbol>
+ <symbol name="k">
+ <doc>number of detector pixels in the third slowest direction</doc>
</symbol>
</symbols>
@@ -70,8 +79,73 @@
minOccurs="0" />
</group>
+ <group type="NXdetector_group" minOccurs="0">
+ <doc>
+ Optional logical grouping of detector elements.
+
+ Each detector element is represented as an NXdetector group
+ with its own detector data array. Each detector data array
+ may be further decomposed into array sections by use of
+ NXdetector_module groups. The names are given in the
+ group names field.
+
+ The groups are defined hierarchically, with names given
+ in the group_names field, unique identifiing indices given
+ in the field group_index, and the level in the hierarchy
+ given in the group_parent field. For example if an x-ray
+ detector, DET, consists of four elements in a rectangular array::
+
+ DTL DTR
+ DLL DLR
+
+ We could have::
+
+ group_names: ["DET", "DTL", "DTR", "DLL", "DLR"]
+ group_index: [1, 2, 3, 4, 5]
+ group_parent: [-1, 1, 1, 1, 1]
+
+ </doc>
+
+ <field name="group_names" type="NX_CHAR">
+ <doc>
+ An array of the names of the detector elements or hierarchical
+ groupings of detector elements.
+
+ Specified in the base classes as comma separated list of names,
+ but new code should use an array of names as quoted strings.
+ </doc>
+ <dimensions><dim index="1" ref="group_index"/></dimensions>
+ </field>
+
+ <field name="group_index" type="NX_INT">
+ <doc>
+ An array of unique indices for detector elements or groupings
+ of detector elements.
+
+ Each element is a unique ID for the corresponding group named
+ in the field group_names. The IDs are positive integers starting
+ with 1.
+ </doc>
+ <dimensions><dim index="1" value="i"/></dimensions>
+ </field>
+
+ <field name="group_parent" type="NX_INT">
+ <doc>
+ An array of the hierarchical levels of the parents of detector
+ elements or groupings of detector elements.
+
+ A top-level element or grouping has parent level -1
+ </doc>
+ <dimensions><dim index="1" ref="group_index"/></dimensions>
+ </field>
+ </group>
<group type="NXdetector">
- <field name="depends_on" type="NX_CHAR" /> <!-- better type for paths the need to resolve -->
+ <doc>
+ Normally the detector group will have the name ``detector``.
+ However, in the case of multiple detector elements, each element
+ needs a uniquely named NXdetector group.
+ </doc>
+ <field name="depends_on" type="NX_CHAR" /> <!-- better type for paths needed -->
<group type="NXtransformations" minOccurs="0">
<doc>
@@ -89,10 +163,17 @@
</group>
<field name="data" type="NX_NUMBER">
- <dimensions rank="3">
+ <doc>
+ For a dimension-2 detector, the rank of the data array will be 3.
+ For a dimension-3 detector, the rank of the data array will be 4.
+ This allows for the introduction of the frame number as the
+ first index.
+ </doc>
+ <dimensions rank="dataRank">
<dim index="1" value="np" />
<dim index="2" value="i" />
<dim index="3" value="j" />
+ <dim index="4" value="k" minOccurs="0"/>
</dimensions>
</field>
@@ -113,17 +194,38 @@
To allow consistent parsing of the experimental geometry,
this application definiton requires all detectors to
define a detector module, even if there is only one.
+
+ This group specifies the hyperslab of data in the data
+ array associated with the detector that contains the
+ data for this module. If the module is associated with
+ a full data array, rather than with a hyperslab within
+ a larger array, then a single module should be defined,
+ spanning the entire array.
</doc>
<field name="data_origin" type="NX_INT">
<doc>
- A two value field which gives the index of the start of the
- modules data in the
- main area detector image in the underlying NXdetector module.
+ A dimension-2 or dimension-3 field which gives the indices
+ of the origin of the hyperslab of data for this module in the
+ main area detector image in the parent NXdetector module.
+
+ The data_origin is 0-based.
+
+ The frame number dimension (np) is omitted. The order
+ of indices is i, j or i, j, k, i.e. slow to fast.
</doc>
</field>
<field name="data_size" type="NX_INT">
<doc>
- Two values for the size of the module in pixels in each direction.
+ Two or three values for the size of the module in pixels in
+ each direction.
+ </doc>
+ </field>
+ <field name="data_stride" type="NX_INT" minOccurs="0">
+ <doc>
+ Two or three values for the stride of the module in pixels in
+ each direction. By default the stride is [1,1] or [1,1,1],
+ and this is the most likely case. This optional field is
+ included for completeness.
</doc>
</field>
@@ -230,9 +332,10 @@
<field name="angular_calibration" type="NX_FLOAT" minOccurs="0">
<doc>Angular calibration data.</doc>
- <dimensions rank="2">
+ <dimensions rank="dataRank">
<dim index="1" value="i" />
<dim index="2" value="j" />
+ <dim index="3" value="k" minOccurs="0"/>
</dimensions>
</field>
@@ -245,17 +348,19 @@
<field name="flatfield" type="NX_FLOAT" minOccurs="0">
<doc>Flat field correction data.</doc>
- <dimensions rank="2">
+ <dimensions rank="dataRank">
<dim index="1" value="i" />
<dim index="2" value="j" />
+ <dim index="3" value="k" minOccurs="0"/>
</dimensions>
</field>
<field name="flatfield_error" type="NX_FLOAT" minOccurs="0">
<doc>Errors of the flat field correction data.</doc>
- <dimensions rank="2">
+ <dimensions rank="dataRank">
<dim index="1" value="i" />
<dim index="2" value="j" />
+ <dim index="3" value="k" minOccurs="0"/>
</dimensions>
</field>
@@ -300,9 +405,10 @@
If the full bit depths is not required, providing a
mask with fewer bits is permissible.
</doc>
- <dimensions rank="2">
+ <dimensions rank="dataRank">
<dim index="1" value="i" />
<dim index="2" value="j" />
+ <dim index="3" value="k" minOccurs="0"/>
</dimensions>
</field>
@@ -399,26 +505,105 @@
<field name="depends_on" type="NX_CHAR" minOccurs="0">
<!-- better type for paths the need to resolve -->
<doc>
- This should be an absolute requirement to have for any scan
- experiment.
+ This is a requirement to describe for any scan experiment.
The reason it is optional is mainly to accommodate XFEL
single shot exposures.
+
+ The axis on which the sample position depends may be stored
+ anywhere, but is normally stored in the NXtransformations
+ NXtransformations group within the NXsample group.
</doc>
</field>
+ <group type="NXtransformations" minOccurs="0">
+ <doc>
+ This is the recommended location for sample goniometer
+ and other related axes.
+
+ This is a requirement to describe for any scan experiment.
+ The reason it is optional is mainly to accommodate XFEL
+ single shot exposures.
+
+ Use of the depends_on field and the NXtransformations group is
+ strongly recommended. As noted above this should be an absolute
+ requirement to have for any scan experiment.
+
+ The reason it is optional is mainly to accommodate XFEL
+ single shot exposures.
+ </doc>
+ </group>
+
<field name="temperature" units="NX_TEMPERATURE" minOccurs="0" />
<group type="NXbeam">
- <field name="incident_wavelength" type="NX_NUMBER" units="NX_WAVELENGTH"
- minOccurs="0" /> <!-- we write wavelength! -->
+ <field name="incident_wavelength" type="NX_FLOAT" units="NX_WAVELENGTH"
+ minOccurs="0" >
+ <doc>
+ In the case of a monchromatic beam this is the scalar
+ wavelength.
+
+ In the case of a polychromatic beam this is an array of
+ the wavelengths with the relative weights in
+ incident_wavelength_weight.
+ </doc>
+ </field>
+
+ <field name="incident_wavelength_weight" type="NX_FLOAT" minOccurs="0" >
+ <doc>
+ In the case of a polychromatic beam this is an array of the
+ relative weights of the corresponding wavelengths in
+ incident_wavelength.
+ </doc>
+ </field>
+
+ <field name="incident_wavelength_spread" type="NX_FLOAT" units="NX_WAVELENGTH"
+ minOccurs="0" >
+ <doc>
+ The wavelength spread FWHM for the corresponding
+ wavelength(s) in incident_wavelength.
+ </doc>
+ </field>
<group name="incident_wavelength_spectrum" type="NXdata"
minOccurs="0" />
<field name="flux" type="NX_FLOAT" units="NX_FLUX" minOccurs="0">
- <doc>flux incident on beam plane area</doc>
+ <doc>
+ flux incident on beam plane area in photons
+ per second per unit area
+ </doc>
+ </field>
+
+ <field name="total_flux" type="NX_FLOAT" units="NX_FREQUENCY" minOccurs="0">
+ <doc>
+ flux incident on beam plane in photons per second
+ </doc>
</field>
+ <field name="incident_beam_size" type="NX_FLOAT" units="NX_LENGTH" minOccurs="0">
+ <doc>
+ Two-element array of FWHM (if Gaussian or Airy function) or
+ diameters (if top hat) or widths (if rectangular) of beam
+ in the order x, y
+ </doc>
+ <dimensions rank="1" value="2" />
+ </field>
+
+ <field name="profile" type="NX_CHAR" minOccurs="0">
+ <doc>
+ The beam profile, Gaussian, Airy function, top-hat or
+ rectangular. The profile is given in the plane of
+ incidence of the beam on the sample.
+ </doc>
+ <enumeration>
+ <item value="Gaussian"/>
+ <item value="Airy"/>
+ <item value="top-hat"/>
+ <item value="rectangular"/>
+ </enumeration>
+ </field>
+
+
<field name="incident_polarisation_stokes" minOccurs="0">
<dimensions rank="2">
<dim index="1" value="np" />
@@ -426,12 +611,6 @@
</dimensions>
</field>
</group>
-
- <group type="NXtransformations" minOccurs="0">
- <doc>
- Suggested location for sample goniometer or other axes (transformations)
- </doc>
- </group>
</group>
<group type="NXdata" />
</pre>