z-stitching

z-stitching can be done over:

• projections (in this case we will speak of pre-processing stitching)

• reconstructed volumes (in this case we will speak about post-processing stitching)

At nabu level most of the code is shared for those two use-case. Diversity comes mostly from getting and interpretting metadata of the scans or of the volumes.

overlaping

To process successfully a stitching frames must have an overlaping area

pre processing z-stitching (projections)

You can stitch together a z-serie in pre processing by using the PreProcessZStitcher. It requires as input a set of Nxtomo.

real life example of z-stitching projections

reference used for projection stitching

post processing z-stitching (reconstructed volumes)

You can stitch together a z-serie in pre processing by using the PostProcessZStitcher. It requires as input a set of (reconstructed) volumes.

real life example of z-stitching volumes

reference used for volume stitching

stitching using the GUI

A GUI exists to stitch volumes with a graphical user interface. It is embed with tomwer. See TODO: add link

stitching from the command line interface

You can apply stitching from CLI by:

• creating a configuration file

• editing the configuration

• calling nabu-stitching with the configuration file

creating a configuration file

this can be done from:

nabu-stitching-config [-h] [--stitching-type STITCHING_TYPE] [--level LEVEL] [--output OUTPUT]

usage: nabu-stitching-config [-h] [--stitching-type STITCHING_TYPE] [--level LEVEL] [--output OUTPUT]

Initialize a nabu configuration file

optional arguments:
  -h, --help            show this help message and exit
  --stitching-type STITCHING_TYPE
                        User can provide stitching type to filter some parameters. Must be in ('z-preproc', 'z-postproc').
  --level LEVEL         Level of options to embed in the configuration file. Can be 'required', 'optional', 'advanced'.
  --output OUTPUT       output file to store the configuration

editing a configuration file

The different field of the configuration are explained within the file. But maybe some precision can be added regarding:

• input section

  • slices: You can apply the stitching on a sub-section only (for debug or distribution for example). This sub-section can be specify using the slices value from the configuration file:

  [inputs]
  slices=
  

  slices can be provided as a slice like slices=start:stop[:step] or as a list of value like slices=start or slices=1,20,55. Giving them as slices (with step equal 1) is recommanded because it will allow to load contiguous data faster.

calling nabu-stitching with the configuration file

Once you finished editing the stitching configuration file you can execute the stitching from:

nabu-stitching [my_stitching_file]

This will trigger the processing. If this is a pre-processing stitching then this will generate a NXtomo that you will be able to reconstruct using the nabu command line and a nabu reconstruction file. If this is a post-processing stitching then you will obtain a volume.

from python and notebook

to ease processing stitching and get a better view of the behavior there is two notebooks that could be used:

• preprocess_stitching: to ease full preprocessing stitching, display some raw data and some basic stiching

• postprocess_stitching: to ease full postprocessing stitching, display some raw data and some basic stiching

• overlap_stitcher: to display and ease definition of overlap areas and result on a single slice. Here is an example on how the overlap areas will be displayed (colored rectangle of alpha==0.5 are the one that can be used for overlap):

note on calling nabu with the stitched NXtomo

Pre processing z-stitching will create a NXtomo containing projection already flat fielded. This is why you should turn of flatfield field from the nabu configuration file. as it does not contain any dark or flat it would raise an error otherwise.

note on ordering

Algorithm expects to have the scan z decreasing ordered (first scan provided should be the upper one). Only the ZStitcher and the nabu-stiching can invert only scan z ordering automatically.

It expect to have something like:

note on frame flips

The NXtomo can be aware of some frame flipping in x or in y. Those flips will be handled by the stitching algorithm. But be aware that stitching algorithm will generate unflipped data. This might be a bit disturbing when comparing stitched data with raw data.

note on management of rotation angle

some acquisition can have inverted rotation angle. To speed up acquition over several z then user might want to avoid to reset to original position motors. This case is hanled by hckecing the order as long as rotation angle are coherent.

real overlaps vs stitching overlap.

Between to overlaping scan or volumes exists a ‘real overlap’. Which can be obtain from the real positions of the two objects + object shapes. Positions are deduced from metada of the object. They can also be redefined by either axis_X_pos_px (one per object) or by axis_X_pos_mm + pixel size or voxel size.

Then the algorithm will do the stitching using a overlap size ( <= real overlap). Of course this height must be smaller or equal to the real overlap otherwise it cannot process. This size height be defined by the overlap_size key from axis_0_params parameter.

On this example we ask the z-stitching to be 40 px height

axis_0_params = overlap_size=40

warning / bottlenecks

pre-processing stitching works for NXtomo format. If your entry is an EDF please convert it to NXtomo first. A tutorial can be find here

post-processing stitching is meant to work any file format handled by nabu. Nevertheless it first target HDF5. For other file format it is expected to be unoptimised. For now for example it will duplicate all slice files to do the concatenation.