add NXdata transformation field

.github/workflows/ci.yaml

@@ -58,14 +58,15 @@ jobs:
         run: |
           make test
 
-      - name: Install LaTeX
+      - name: Install System Packages
         run: |
-          sudo apt-get update -y && \
+          sudo apt-get update -y
           sudo apt-get install -y \
             latexmk \
             texlive-latex-recommended \
             texlive-latex-extra \
             texlive-fonts-recommended
+          sudo apt-get install -y pandoc
 
       - name: Generate build files
         run: |

README.md

@@ -15,15 +15,48 @@ to be made before commiting the change:
 
 First install the test and build requirements with this command (only run once)
 
-    make install
+```bash
+make install
+```
+
+In addition you need to following system packages (only run once)
+
+```bash
+# Needed for jupyter notebooks
+sudo apt-get install -y pandoc
+
+# Only needed when building the PDF manual
+sudo apt-get install -y \
+    latexmk \
+    texlive-latex-recommended \
+    texlive-latex-extra \
+    texlive-fonts-recommended
+```
+
+To run the Jupyter notebooks you need to install the following packages (only run once)
+
+```bash
+pip install jupyterlab
+pip install numpy h5py scipy matplotlib
+```
 
 Then verify syntax and build the HTML manual with this command
 
-    make local
+```bash
+make local
+```
 
 Open the HTML manual in a web brower for visual verification
 
-    firefox build/manual/build/html/index.html
+```bash
+firefox build/manual/build/html/index.html
+```
+
+To build the PDF manual
+
+```bash
+make prepare pdf
+```
 
 ## Repository content
 

base_classes/NXdata.nxdl.xml

@@ -158,6 +158,11 @@
 			   to avoid string parsing in reading applications.
 		</doc>
 	</attribute>
+	<attribute name="passive_transformation" type="NX_CHAR">
+		<doc>
+			The name of the :ref:`field &lt;/NXdata/TRANSFORMATION-field&gt;` that contains the passive transformation matrix.
+		</doc>
+	</attribute>
 
 	<doc>
 		:ref:`NXdata` describes the plottable data and related dimension scales. 
@@ -390,6 +395,42 @@
 			An optional offset to apply to the values in data.
 		</doc>
 	</field>
+	<field name="TRANSFORMATION" type="NX_FLOAT" nameType="any" optional="true">
+		<doc>
+			The `passive transformation matrix &lt;../../notebooks/reference_frames.ipynb#NXdata-reference-frame&gt;`__
+			in `homogeneous coordinated &lt;../../notebooks/reference_frames.ipynb#Homogeneous-coordinates&gt;`__.
+			It describes the transformation from the *data frame* (the axis
+			values are coordinates in this frame) to the *plotting frame*.
+
+			The fields :ref:`offset &lt;/NXdata/offset-field&gt;` and :ref:`scaling_factor &lt;/NXdata/scaling_factor-field&gt;`
+			could be absorbed in this matrix as well. If they are present
+			they should be applied to the axis values before applying the
+			transformation matrix.
+		</doc>
+		<dimensions rank="2">
+			<doc>
+				If the :ref:`DATA field &lt;/NXdata/DATA-field&gt;` has dimensions
+				\ :math:`n\times n` then the :ref:`TRANSFORMATION field &lt;/NXdata/TRANSFORMATION-field&gt;`
+				should have dimensions \ :math:`(n+1)\times (n+1)`
+			</doc>
+		</dimensions>
+		<attribute name="transformation_type" optional="true">
+			<doc>
+				The `type of transformation &lt;../../notebooks/reference_frames.ipynb#NXdata-reference-frame&gt;`__
+				may be helpful for plotting utilities.
+			</doc>
+			<enumeration>
+				<item value="identity"/>
+				<item value="translation"/>
+				<item value="proper rigid"/>
+				<item value="rigid"/>
+				<item value="similarity"/>
+				<item value="affine"/>
+				<item value="projective"/>
+			  </enumeration>
+		</attribute>
+	</field>
+
 	<field name="title">
 		<doc>
 			Title for the plot.

manual/source/conf.py

@@ -47,7 +47,8 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
     'sphinx.ext.todo',
-    'sphinx_tabs.tabs'
+    'sphinx_tabs.tabs',
+    'nbsphinx'
 ]
 
 # Show `.. todo` directives in the output
@@ -59,7 +60,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ['**.ipynb_checkpoints']
 
 
 # -- Options for HTML output -------------------------------------------------

manual/source/index.rst

@@ -13,6 +13,7 @@ https://www.nexusformat.org/
 
     user_manual
     examples/index
+    notebooks/index
     ref_doc
     napi
     community

manual/source/notebooks/index.rst

@@ -0,0 +1,9 @@
+.. _Notebooks:
+
+==============================================
+Jupyter notebooks for theory and code examples
+==============================================
+.. toctree::
+   :maxdepth: 1
+
+   reference_frames