Tomo-tools training - Part 1: basic reconstruction¶

In this part, we see how to

  • Connect to ESRF compute infrastructure and activate the tomo-tools software
  • Get started with Nabu configuration files
  • Perform a basic reconstruction

0. Introduction¶

The tomo-tools denote a collection of tomography software developed at ESRF:

  • Nabu - reconstruction
  • NXTomomill - data conversion (eg. edf to NX)
  • Tomwer - graphical user interface

0.1 - Nabu¶

Nabu is a versatile tool for tomography processing.

It consists in a collection of command-line tools:

  • nabu: full-field tomography processing pipeline
  • nabu-helical: helical tomography processing pipeline
  • nabu-histogram
  • nabu-cast
  • ... and more

and a Python API of invidivual processing steps.

The documentation can be found at https://www.silx.org/pub/nabu/doc/

0.2 - Tomwer¶

tomwer offers tools to automate acquisition and define processing workflows for Tomography.

Main interface to define processing workflows can be access from the tomwer canvas.

Most of the processing step can be access as standalone from CLI like:

  • tomwer axis
  • tomwer nxtomo-editor
  • ...
  • tomwer --help

note: use the help to get more information about CLI

All processing can also be accesses through a python API (using ewoks tasks).

1. Reconstruction using nabu¶

In this part, we use the command line (nabu + nxtomomill) to perform a basic reconstruction.

There are roughly three steps:

  • Convert data (Bliss-HDF5 Spec-EDF) to Nexus : nxtomomill
  • Create and edit a nabu confiration file : nabu-config
  • Run the reconstruction : nabu

1.1 - Converting a Bliss HDF5 acquisition scan to NX¶

ESRF is deploying the Bliss acquisition system on all beamlines.
This new acquisition system is producing HDF5 files.

There are a few drawbacks:

  • These HDF5 files are beamline-dependent (eg. fscan vs EBSTomo)
  • The structure itself changes over time, which can lead to crashes

On the other hand, nabu/tomwer need a stable and standard file format.

  • The Nexus format was chosen
  • Need a tool to convert HDF5 from Bliss layout to Nexus layout
  • This conversion does not duplicate data - only re-arange the internal layout

For this first part, we will be using the dataset: /scisoft/tomo_training/part1_basic_reco/bambou_hercules_0001.h5 (scan of a Bamboo stick, courtesy Ludovic Broche, ID19)

Hands-on: convert Bliss-H5 to Nexus¶

Use the command line nxtomomill to convert between (Bliss) HDF5 and NX layout.

nxtomomill h52nx /scisoft/tomo_training/part1_basic_reco/bambou_hercules_0001.h5 bambou_hercules_0001.nx

1.1- (alt.) Converting a Spec acquisition to NX¶

Some beamlines do not use Bliss yet.

The reconstruction software (nabu/tomwer) natively handles EDF datasets, but the ESRF GPFS configuration makes it very slow.

It is therefore advised to first convert the EDF dataset to NX. By default this duplicates the data.

We will use the dataset /scisoft/tomo_training/part1_basic_reco/gut_ctrl_7_mid_ovw1_150nm_1_/ (courtesy Alexandra Pacureanu, ID16A)

Hands-on: convert Spec-EDF to Nexus¶

Use the command nxtomomill to convert thre EDF dataset to Nexus:

nxtomomill edf2nx /scisoft/tomo_training/part1_basic_reco/gut_ctrl_7_mid_ovw1_150nm_1_ gut_ctrl_7_mid_ovw1_150nm_1_.nx

1.2 - Generating a configuration file¶

To create a configuration file from scratch, the command-line tool nabu-config can be used:

nabu-config

this creates a file (nabu.conf by default) with pre-filled parameters.

To choose the file name:

nabu-config --output my_config.conf

By default, only a subset of the options are visible in the configuration file.

To see all the parameters:

nabu-config --level advanced

to retain only a handful of parameters:

nabu-config --level required

Hands-on¶

  • Create a directory which will contain the nabu configuration file, and possibly the reconstructions.
  • Create a nabu configuration file from scratch: nabu-config --dataset <path to the NX file>
  • Open the generated file and inspect the default parameters
  • Specify the output file/directory in the [output] section

1.3 - Basic reconstruction¶

Let's run our first reconstruction, using the NX file produced by nxtomomill.

The syntax is nabu nabu.conf [parameters].

By default, nabu nabu.conf will reconstruct all the volume (unless start_xyz and end_xyz are modified in the configuration file).

Reconstructing one slice¶

Usually, to quickly assess the reconstruction parameters, only one or several slices are reconstructed.

To reconstruct only the middle slice:

nabu nabu.conf --slice middle

To reconstruct the first and last slices:

nabu nabu.conf --slice first
nabu nabu.conf --slice last

See also: command-line interface

Exercise¶

  • Reconstruct one or several slices of your choice
  • Examine the result

bamboo reconstruction

In this case:

  • No phase retrieval means a rather noisy reconstruction
  • Half acquisition yields a 4120x4100 slice
  • The (default) CoR estimation method sliding-window works well

Exercise¶

  • Enable phase retrieval (paganin) and re-run the reconstruction

bamboo reconstruction with phase retrieval

1.4 - Using checkpoints¶

Sometimes it's useful to save partially-processed data in the middle of the process, for debugging/visualization.

Nabu enables to

  • Dump data from arbitrary point in the processing pipeline ("checkpoint")
  • Resume the processing from this data

Creating checkpoints¶

The relevant section in configuration file is [pipeline]:

[pipeline]
# Example: dump data after phase retrieval and sinogram construction
save_steps = phase, sinogram

Note checkpoints can be saved in a custom file with the steps_file parameter.

Exercise (optional)¶

  • Save the data after phase retrieval and sinogram build

Resuming from a checkpoint¶

The parameter name is resume_from_step.
You can save any number of step (flatfield, phase, sinogram, ...), but the processing can be resumed from only one checkpoint.

[pipeline]
save_steps = sinogram
resume_from_step = sinogram

This particular configuration is useful for manually finding the center of rotation (many trial-and-error reconstructions needed).

Exercise¶

  • Configure nabu to dump the sinograms, and to resume the processing from already-saved sinograms
    • save_steps = sinogram and resume_from_step = sinogram
  • Reconstruct the middle slice: nabu nabu.conf --slice middle
  • Reconstruct the last slice: nabu nabu.conf --slice last
  • What do you observe ?
  • Reconstruct again the last slice: nabu nabu.conf --slice last