nxtomomill - introduction / overview¶

nxtomomill icon

nxtomomill provides a Command Line Interface (CLI) and a python API to convert raw tomography datasets to NXtomo format.

NXtomo is the choosen file format for tomography software.

It also provides a set of tools to edit a NXtomo.

context¶

EBS icon

The European Synchrotron Radiation Facility (ESRF) decided to adopt "HDF5" file format as several other institute. (see HDF5 file format in confluence).

And with HDF5 comes the nexus format which intend to be a common data format for neutron, x-ray, and muon science (see details on following slides).

The goal is to ease sharing data and applications through users.

A sub section of nexus dedicated to tomography aplpication exists which is named NXtomo. We decided to use it as the default entry of our tools for tomography.

use case at esrf for tomography¶

data flow

NXtomo¶

Nexus¶

nexus icons

NeXus is a common data format for neutron, x-ray, and muon science.
It is being developed as an international standard by scientists and programmers 
representing major scientific facilities in order to facilitate greater cooperation 
in the analysis and visualization of neutron, x-ray, and muon data.

More information here: https://www.nexusformat.org/

NXTomo¶

This is the application definition for x-ray or neutron tomography raw data.

You can find the definition here

The idea is to have the minimalist information to run a reconstruction from it.

An NXTomo entry looks like:

NXTomo entry

Fields¶

NXtomo contains the following fields:

  • entry

    • title

    • start_time

    • end_time

    • instrument

      • source:

        • type

        • name

    • detector

      • data[nFrames, xSize, ySize]

      • image_key[nFrames]

         projection = 0

 flat field = 1

 dark field = 2

 invalid = 3

      • image_key_control[nFrames] close to image_key. But add the alignment field for alignment frame, also aka return frames

        alignment = -1

      • x_pixel_size

      • y_pixel_size

      • distance

        Distance between detector and sample

    • sample

      • name

        Descriptive name of sample

      • rotation_angle[nFrames]

        In practice this axis is always aligned along one pixel direction on the detector and usually vertical. There are experiments with horizontal rotation axes, so this would need to be indicated somehow. For now the best way for that is an open question.

      • x_translation[nFrames]

      • y_translation[nFrames]

      • z_translation[nFrames]

  • data:

    • data: link to instrument/detector/data

    • rotation_angle: link sample/detector/data

    • image_key: link to instrument/detector/image_key

Nexus is also using HDF5 attributes. This is used for example to define the "unit" of a dataset. You can view the unit for example which is a field of high interest. This is the job of the different woftware to interpret it correctly.

Getting ready for the hand-on¶

For this tutorial you will only need a terminal and you will only launch nxtomomill commands and silx view command to browse data.

Accessing it from ESRF machines¶

It is available from the tomography environments. Using one of the following command:

module load tomotools/{version}

or

source /scisoft/tomotools_env/activate.sh {version}

Raw data for the training¶

For this training we will use the "bamboo dataset".

raw data

You can have a view of the raw data from silx view

cd [...] 
silx view bamboo/bamboo_hercules{...}bamboo_hercules_0001.h5

bamboo raw data

In [ ]:
%%bash
# TODO: Move to the folder containing bamboo_hercules_0001.h5
# cd ...
In [ ]:
%%bash
# TODO: browse raw data using silx view
# silx view ...

training overview¶

  • conversion

    • h52nx (bliss HDF5 to nxtomo)

      • simple conversion from CLI
      • conversion from CLI using a configuration file
      • conversion from the python API
      • define titles names
      • provide some parameters that can be missing (energy...)
      • define dataset path / name
      • advance usage: define your own sequence from the configuration file
      • provide a configuration file to tomwer
      • converting from dxfile to NXtomo

    • edf2nx

It can useful to know the version of the application you are using. For nxtomomill you can access it :

  • from the command line interface:
nxtomomill --version
  • from python
import nxtomomill
nxtomomill.__version__
In [ ]: