Part 1: basic reconstruction¶

In this part, we see how to

  • Get started with Nabu configuration files
  • Perform a basic reconstruction

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 or 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¶

At ESRF, all tomography beamlines (except ID16A and ID16B) are using the Bliss acquisition system, which produces HDF5 files.

Using HDF5 format instead of EDF was a step forward, but there are still a few drawbacks:

  • These HDF5 files are beamline-dependent (eg. fscan vs EBSTomo)
  • The structure changes over time, has missing fields/units ; which can lead to crashes
    • Format is now much more stable as of 2024

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:

/data/projects/tomo-sample-data/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 /data/projects/tomo-sample-data/training/part1_basic_reco/bambou_hercules_0001.h5 bambou_hercules_0001.nx --single-file

Note make sure that you have write access to the directory containing the target .nx file.

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

As of 2024, nano-tomography beamlines ID16A and ID16B use the SPEC acquisition system.

While the reconstruction software (nabu/tomwer) natively handles EDF datasets, the ESRF filesystem (GPFS) 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

/data/projects/tomo-sample-data/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 /data/projects/tomo-sample-data/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¶

At this stage we have a .nx file which "contains" the data, and necessary metadata to reconstruct it.

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 (WARNING : if not set, nabu will write the output file(s) to the direcory which contains the NX file.)

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 the whole volume, which can take some time.

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

To reconstruct a limited range of slices:

nabu nabu.conf --slice <first>-<end>

See also: command-line interface to modify start_xyz and end_xyz in the configuration file.

Hands-on: Basic reconstruction¶

  • 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

Hands-on: enable phase¶

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

bamboo reconstruction with phase retrieval

You can use silx compare <file1> <file2> (available in silx 2.0) to compare the two or more files.

Examples:

  • To compare two tiff files: silx compare file1.tiff file2.tiff
  • To compare two hdf5 files : silx compare "silx:bambou_hercules_0001_rec_2064.000_01080.hdf5?path=/entry0000/reconstruction/results/data&slice=0" "silx:bambou_hercules_0001_rec_2055.000_01080.hdf5?path=/entry0000/reconstruction/results/data&slice=0" (of course, path= and file names will have to be adapted to your use case).
  • To compare a list of files whose names share a pattern: silx compare "silx:bambou_hercules_0001_rec_2*_01080.hdf5?path=/entry0000/reconstruction/results/data&slice=0"

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.

Hands-on (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).

Hands-on: resuming from checkpoints¶

  • 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