Welcome to nxtomomill’s documentation!

nxtomomill provide a set of applications to convert tomography acquisition made by BLISS from their original file format (.edf, .h5) to a Nexus compliant file format (using NXtomo)

Installation

The simplest way to install nxtomomill is to use the pypi wheel provided ()

pip install nxtomomill

You can also install it from source:

git clone https://gitlab.esrf.fr/tomotools/nxtomomill.git
cd nxtomomill
pip install .

Building doc

In order to build documentation you should insure sphinx is install. You can for example install it from pip:

pip install sphinx

Then you can build the documentation using sphinx:

python setup.py build build_sphinx

Tutorials

• tutorials
  • edf2nx tutorial
  • h52nx tutorial
  • patch-nx tutorial
  • dxfile2nx tutorial

API

• nxtomomill API

Plugins

In some cases you might want to modify information contained on an NXtomo. For example if you want to do some operations between raw dataset or append some information that does not appears on the raw file.

This is the goal of the ‘plugin mecanism’.

All the plugins will be discover during the bliss-hdf5 to nexus_hdf5 conversion and will be apply just before saving NXtomo(s) to disk.

In order to create a plugin you must:

• create a directory that will contain the plugins.

• define the environment variable ‘NXTOMOMILL_PLUGINS_DIR’ which register the plugin directory

• inside the plugin directory create one or several python file which will implement the ‘HDF5Plugin’ class.

You can retrieve data from bliss-hdf5 acquisition contained either in instrument or in positioner groups.

For performance issues, as we collect this information in the NXtomo creation preprocessing you must declare dataset name you want to retrieve from those groups.

The HDF5Plugin provide an API to modify the NXtomo before they will be saved on disk. This way you can modify them as you like using the NXtomo API by implementing the update_nx_tomo funciton.

from nxtomomill.plugins import HDF5Plugin
import numpy


class MyPlugin1(HDF5Plugin):
    """

    :warning: the constructor should not take any parameter because
    instantiate by nxtomomill
    """
    def __init__(self):
        positioners_names = 'diffty', 'd1ty'
        super().__init__(name='My plugin 1', positioner_keys=positioners_names)

    def update_nx_tomo(self, nx_tomo) -> nx_tomo:
        diffty = numpy.array(self.get_positioner_info('diffty'))
        d1ty = numpy.array(self.get_positioner_info('d1ty'))

        nx_tomo.sample.x_translation = diffty - d1ty - 14
        nx_tomo.sample.x_translation.unit = "mm"

Settings

nxtomomill needs to get several information in order to complete translation from EDF or (bliss) HDF5 to nexus-compliant HDF5 file.

This information

• is a set of key values for EDF

• is a set of dataset location and name for (bliss) HDF5

All are stored in nxtomomill.settings.py file. For tomoh52nx you can generally overwrite from calling the appropriate command option (see h52nx tutorial).

But for scripting are when used from a dependency (like tomwer) it can be convenient to modify some of them. For example if you cannot retrieve rotation angle because this information is stored at a different location than the ‘default’ one knows by nxtomomill you can change H5_Y_ROT_KEY parameter.

If one of the requested information is a combination of dataset value then you light probably want to add a plugin for it Plugins

Design

HDF5Converter

The more it goes the more use cases the hdf5 converter has to handle. Today it handles “classical” tomography acquisition, zseries and pcotomo. In the future it is expected to handle XRD-CT, XFD-CT and dual energy - CT.

Behavior of the HDF5Converter

The HDF5 is applying sequentially the following taks:

1. preprocess raw data (During converter creation)

   browse raw data and collect information on Bliss scan sequence.

   During this step it will determine for each entry if the frame type are dark, flats, projections or alignment.

   Create an instance of Acquistion for each ‘init’ Bliss scan.

2. HDF5Converter.convert function

   2.1 create for Acquisition instance one or several instances of NXtomo.

   2.2 Optional split of NXtomo (use case of pcotomo) in order to obtain the final NXtomo.

   2.3 apply plugin (allows user to modify NXtomo instances).

   2.4 save data to disk.

Acquistion classes

To manage all the use cases it has evolved. Each acquisition has now it’s own acquisition class. All based on the nxtomomill.converter.hdf5.acquisition.baseacquisition.BaseAcquisition

• StandardAcquisition default acquisition.

• ZSeriesBaseAcquisition a serie of default acquisition with a set of z values. Create one NXTomo per different z

• XRD3DAcquisition close to a default acquisition but add two motors to he handled: rocking and base-tilt

• XRDCTAcquisition

The regular conversion sequence is:

Actually we also have two configuration handler classes. Both inherit from nxtomomill.io.confighandler.BaseHDF5ConfigHandler.

The configuration handler is used to make the connection between applications options and configuration (nxtomomill.io.config.TomoHDF5Config)

• TomoHDF5ConfigHandler: used by h52nx application

• XRD3DHDF5ConfigHandler: used by h5-3dxrd-2x application

The configuration is used to make the conversion (defines input file, output file, entry titles, urls to be converted, source format…)

Actually there is also two configuration classes.

• TomoHDF5Config: define the configuration to generate a usual “NXTomo”

• XRD3DHDF5Config: define the configuration for 3D-XRD acquisition (close to a standard acquisition including two motors: rocking and base-tilt)

Indices and tables

• Index

• Search Page