[NeXus-tech] Proposal for dealing with start and end positions per scan point

[Herbert J. Bernstein]

This is a proposal in response to Dectris requests.  I would suggest
we discuss it at the next Telco.  I have added preliminary support
code to CBFlib_bleeding_edge in the cbflib soureforge project.

This is a proposed revision to the base class NXtransformations adding
certain optional items that would be useful in MX data processing.
The currently posted NXtransformations has caused some confusion
because of the variable axis names.  For clarity, let is use "(axis)"
as a place holder for an axis name, e.g. for
"GONIOMETER_PHI"

Then the current form of NXtransformations is the class of a group
containing some number of fields (HDF5 datasets), each of the form

(axis)[np]:NX_NUMBER
  @transformation_type: NX_CHAR
  @vector[3]: NX_NUMBER
  @offset[3]: NX_NUMBER
  @offset_units: NX_CHAR
  @depends_on: NX_CHAR

we propose to permit the optional addition of three new fields:

(axis)_end[np]:NX_NUMBER
(axis)_range_average:NX_NUMBER
(axis)_range_total[2]:NX_NUMBER

and the optional addition of two new attributes for clarity

  @end_point:NX_CHAR
  @start_point:NX_CHAR

(axis) is an array of the dimension of the number of frames containing
the starting set points of this axis when collecting data for the
corresponding frame.

(axis)_end is an array of the dimension of the number of frames
containing the ending set points of this axis when collecting data for
the corresponding frame.

(axis)_range_average is the average to the magnitudes of the ranges of
set point values (i.e. the average of the magnitudes of the
differences between corresponding values in (axis) and (axis)_end),
appropriately corrected for the periodicity of rotational settings,
e.g.  if (axis)=[359,0,1] and (axis)_end=[358,359,0] then
(axis)_range_average = 1, exactly.

(axis)_range_total is an array of two values, the minimum and the
maximum of the values in (axis) and (axis)_end, with values
appropriately corrected for the periodicity of rotation settings to
minimize the excursion e.g. if (axis)=[359,0,1] and
(axis)_end=[358,359,0] , then (axis)_range_total =[-2,1] consistent
with the data values.

@end_point is an optional attribute to (axis) giving the path to (axis)_end
@start_point is an optional attribute to (axis)_end giving the path to (axis)

Note 1:  When np>1 and the scan is known to be a continuous
open-shutter scan, then none of the optional fields are necessary,
inasmuch as they can be computed from the values in (axis).  However,
when np=1 or if the scan is discontinuous, the values in (axis)_end
will not be computable from the values in (axis).

Note 2:  The values in (axis)_range_average and (axis)_range_total are
normally computable from the values in (axis) and (axis)_end, but for
many processing programs one, the other or both will need to be
computes, and these field names provide a convenient, documented place
in which to store the information in the file for processing, avoiding
conflicts in naming from different experimenters making idiosyncratic
name choices.

Note 3:  The two optional attributes @end_point and @start_point are
also redundant but again are scratch information people are likely to
generate for processing support and providing these specific names
helps to avoid conflicts in naming.

--- HJB