WIP: add transformation field to NXdata

[woutdenolf]

Closes nexusformat/NIAC#102

Proposal

Add the attribute passive_transformation and field TRANSFORMATION to NXdata.

myplot:NXdata
  @passive_transformation = 'reciprocal_space'
  reciprocal_space NX_FLOAT (n+1, n+1)
    @transformation_type = 'affine'

To be decided:

• do save the active or passive transformation matrix?
  -> currently I chose passive because transforming an image is often done by defining a grid in the plotting frame, transforming the grid coordinates to the data frame and interpolate the image.
• should be matrix be for [x,y,1]^T coordinates (natural for 2D) or [y,x,1]^T (natural for n-D)?
  -> currently I chose [y,x,1]^T as it keeps the coordinate order defined by AXISNAME_indices.

Example

An example for a 3D signal

myplot:NXdata
  @axes = ['Ql', 'Qk', 'Qh']
  @passive_transformation = "reciprocal_space"
  Qh = float64(1601)
    @long_name = 'H (rlu)'
  Qk = float64(801)
    @long_name = 'K (rlu)'
  Ql = float64(1201)
    @long_name = 'L (rlu)'
  reciprocal_space = float64(4, 4)
    @transformation_type = 'affine'

Preview of PR changes

NXdata rendering:

https://hdf5.gitlab-pages.esrf.fr/nexus/nxdata_transformation/classes/base_classes/NXdata.html#nxdata-transformation-field

Additional documentation and code examples for reference frames:

https://hdf5.gitlab-pages.esrf.fr/nexus/nxdata_transformation/notebooks/index.html

Extra dependencies

nbsphinx and ipython are needed to include jupyter notebooks in the documentation.

These can be pip installed but nbsphinx also needs pandoc, which is a system package.

Edit: to be decided whether this is acceptable. Perhaps add pandoc system installation to make install for linux, windows and mac?

[prjemian]

Right. Before sphinx is run, the nxdl.xml files are parsed, creating .rst files for the documentation.

…

On Sat, Mar 26, 2022, 11:06 AM woutdenolf ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In .gitignore <#1033 (comment)> : > @@ -10,6 +11,11 @@ manual/source/*.table manual/source/classes/*/NX*.rst manual/source/classes/*/*.nxdl.xml manual/source/classes/contributed_definitions/canSAS +manual/source/classes/applications/canSAS I'm actually surprised files are added to the source directory. That's not normal sphinx behaviour. I guess this is done by some custom code somewhere? — Reply to this email directly, view it on GitHub <#1033 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AARMUMDQDMWA4FOMXMIZNN3VB4YYHANCNFSM5QTF25SA> . You are receiving this because you commented.Message ID: ***@***.***>

[prjemian]

I like the way this looks. Makes it so easy to add documentation which becomes part of the manual_ from a Jupyter notebook.

Noticing that a single notebook creates 4 subsections. Was expecting a single subsection per notebook, with sub-subsections. Was that intentional? Is it designed (by the notebook author)? Looks like it. Each of the sections there use #. Thinking that a notebook should only have a single level-1 heading, then level-2 (##) or more below that heading. The idea is that all this content belongs to this one document.

[prjemian]

@woutdenolf Should we consider this PR at the 2022-06 Code Camp?

[woutdenolf]

I made this to discuss nexusformat/NIAC#102

Maybe after some cleanup this can be actually part of the documentation.

Not for 2022-06 Code Camp I would say.

[vincefn]

Looks good to me. This will also be useful for 3D reciprocal space plots.
I would suggest to add a link in the doc to https://en.wikipedia.org/wiki/Active_and_passive_transformation to explain the notion of passive/active transformations, which can be a bit obscure otherwise.

[woutdenolf]

NXdata has a link to this (If you don't see the link, make sure to refresh the page or clear cache). The passive/active transformation is defined there. Perhaps not clear enough? I'd like to avoid links to wikipedia.