Suggestions for NeXus following the study of imageCIF ---------------------------------------------------- In the recent workshop HDF-5 for hyperspectral dataformats a mapping from imageCIF to NeXus was discussed. While many aspects of the mapping were straightforward or just need the addition of fields to base classes, some areas were markedly different. One confusing (to me) aspect of imageCIf is that the relationship between components of the instrument and descriptions in the file is maintained through ID's. Which can come in text and binary forms. In NeXus this cohesion is achieved through storing data componentwise. In other areas, most notably data and axis descriptions, imageCIF has superior concepts. Here NeXus can learn. Data Storage ------------- NeXus strongly advises to store detector or other data in a form which is directly readable and in C storage order. If for some hopefully good reason this is not possible, the data transformation necessary has to be specified by annotating the dataset with appropriate attributes. In the formulas below Vtrue denotes the true value of the data item, Vraw the one which is stored in the data. The attributes are: - linearity: This is the indicator that a transformation of the Vraw data is necessary. Linearity can have one the following values: * offset: Vtrue = Vraw + offset * scaling: Vtrue = Vraw * scaling * scaling_offset: both an offset and scaling is applied. Vtrue = Vraw*scaling + offset * sqrt_scaled: Vtrue = (Vraw/scaling)*(Vraw/scaling) * logarithmic_scaled: Vtrue = (Vraw/scaling)**10 - offset: The offset to apply - scaling The scale factor to apply - direction: a komma separated list of length ndim which specifies for each dimension if it is increasing or decreasing. If this attribute is missing, increasing is implied. - precedence: a komma separated list of length ndim which gives the rank order in which array indexes change with respect to other indexes. A precedence of 1 denotes the fastest changing index. If this attribute is missing, C storage order is implied. Axis ---- The CIF way of specifying axis is far more accurate then what we do with NeXus. Thus the suggestion is to align NeXus with the well thought out CIF scheme. This section consists first of a discussion of the CIF axis system and then of suggestions how to use this within NeXus. CIF uses a coordinate system which is similar to the McStas coordinate system which NeXus uses at its bottom. Just the orientation of the Z-axis differs. The description of any given axis in CIF consists of three elements: - The type of the axis. This can be translation or rotation - The axis vector. This is the direction of a translation or the vector around which the axis rotates. - The axis offset. The offset to the base of the rotation or translation. If this is not given 0,0,0 is assumed. CIF also describes in which order transformations have to be applied to get a component into its final position from its zero position. In CIF this is done by chaining axis through the depends attribute. Axis Suggestions for NeXus --------------------------- 1) NeXus stays with the McStas coordinate system. 2) NeXus uses the vector and offset scheme to describe NeXus axis. The base of all operations is always the component, if not specified by an offset vector. Rotations are in degree, translations in milimetre. 2a) The first use of the vector/offset scheme would be the documentation of the existing NeXus axis. This would look like: - rotation_angle has a vector 0 1 0, rotation around Y - azimuthal_angle is a rotation around Z, vector = 0 0 1 - polar_angle is also a rotation around Y, vector 0 1 0, but as the rotation axis is with the previous component upstream, we have an offset of 0 0 -distance - chi is a rotation around Z, vector 0 0 1 - phi is a rotation around Y, vector 0 1 0 2b) With the vector/offset scheme arbitrary axis can be stored in NeXus. The rule then is that type, vector and offset have to be specified as attributes. Type is NX_CHAR, vector and offset are of dim 3 and type NX_FLOAT. We need these attributes anyway as there are angles such as kappa, which differ in their rotation axis between instruments. 3) Each NeXus component receives an additional field with the name transform. This contains a komma separated list of the operations required to place the component at its position in the instrument. The formula is: Xcurrent = op1*op2....*opn * X0 with transform becoming: op1,op2,....,opn Names of operations are the names of the axis to apply. Unqualified names relate to axis in the same group. In order to refer axis outside the current group, full path names must be given. Storing this separatly in a transform field gives direct access whereas the CIF depends system requires a lot of searches to reconstruct the sequence of transforms. This is why I like transform better. In this description, our NeXus polar coordinate system has the transform: azimuthal_angle, polar_angle 4) NeXus is missing a rotation around the X axis. As we already bought into quite lyrical names for rotation axis I suggest aequatorial_angle as a name for this. 5) Consequently, as NeXus does not have fields for describing translations, except in Nxgeometry, I suggest to add x_translation, y_translation and z_translation fields to each component. This makes NXtranslation in NXgeometry obsolete. I choose to suggest separate fields for the translations as they frequently map to dedicated motors. Please note that all angles have to be 0 if you were to determine the operation of any given translation motor. 6) The orientation field in NXgeometry receives the same meaning as vector in axis descriptions. With vector being aligned with the main axis of the component.