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¶
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:
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.
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 zXRD3DAcquisition
close to a default acquisition but add two motors to he handled: rocking and base-tilt
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 applicationXRD3DHDF5ConfigHandler
: 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)