Part 5 - volume casting

Volume casting allows users to convert any volume created by nabu to another format and or / different values scales.

For example, after reconstructing a volume as a 32 bits HDF5, you may want a stack of 16-bits tiff files, automatically re-scaled with the volume min/max values.

Volume casting can be done from command line interface (CLI) or from the python API. Complete documentation is available here

We will use volumes in /data/projects/tomo-sample-data/training/part5_volume_casting/volumes

(old EDF dataset of a pencil, courtesy ID19, 2010)

1. From command line interface

To convert a volume using the command line interface (CLI), use nabu-cast.

This is a versatile tool which

• Converts from/to HDF5, Tiff, Tiff-3D, EDF, jpeg2000
• Supports 32bits, (unsigned) 16bits, (unsigned) 8 bits...
• Automatically rescales values from volume histogram

CLI Usage

Some help and the syntax of volume identifier (url) examples are provided in the nabu-cast help:

nabu-cast --help

1.1 - Example 1: HDF5 to tiff 16 bits

Suppose you have a HDF5 reconstruction and you want to convert it to a stack of tiff images, in 16 bits (uint16), rescaling using 10%-90% percentiles.

nabu-cast \
  /data/projects/tomo-sample-data/training/part5_volume_casting/volumes/hdf5/5.06_crayon_W150_60_Al2_W0.25_xc1000__vol.hdf5 \
  --output-data-type uint16 \
  --output_volume "tiff:volume:/path/to/my/tiff_folder" \
  --rescale_min_percentile "10%" \
  --rescale_max_percentile "90%"

Note the syntax for providing output files, see details about volume identifiers (url)

1.2 - Rescaling data

Often, in a reconstruction, some values are too low or too high (hot spots, strongly absorbing parts, etc). Converting to a lower dynamic range (ex from float32 to int 16 bits) might deteriorate the overall quality.

To avoid this problem, the volume can be "clipped" to fixed min/max values during the conversion.

In most cases, nabu-cast will need the volume histogram (to extract min/max values, and/or percentiles).

• If the histogram is already available along the reconstructed volume, nabu-cast will use it.
• Otherwise, nabu-cast will re-compute it (slow!).

Therefore, when doing a reconstruction, it's good practice to set [postproc] output_histogram = 1 in the nabu configuration file - computing histogram during reconstruction is fast, while computing it after reconstruction is slow (need to reload the entire volume in memory).

Rescaling using percentiles

A good way to remove too low/high outlier values is to use percentiles: --rescale_min_percentile and rescale_max_percentile. Default values are 10% and 90%.

Rescaling using fixed min/max values

When rescaling to a very low dynamic range (8 bits) and/or from a reconstruction with two "big" histogram modes, it's usually better to use fixed rescaling values: --data_min and --data_max

1.3 - Example 2: EDF-32 bits to EDF-8 bits

in this example we will cast a float32 from edf to uint8 and redefining the rescale percentile.

nabu-cast \
  /data/projects/tomo-sample-data/training/part5_volume_casting/volumes/edf/5.06_crayon_W150_60_Al2_W0.25_xc1000__vol/ \
  --output_volume "edf:volume:/home/lesaint/tomo_training_march_2024/Part5/cast.hdf5?data_path=my_volume" \
  --rescale_min_percentile 0 \
  --rescale_max_percentile 70

Note that by default (in the CLI), the volume is cast in uint16.

2. - Volume casting from Python API

The same operation can be done using the python API.

Here is an example of a volume casting using the python API

from tomoscan.esrf.volume import HDF5Volume, TIFFVolume
from nabu.io.cast_volume import cast_volume
import numpy 

input_volume = HDF5Volume(
    file_path="5.06_crayon_W150_60_Al2_W0.25_xc1000__vol.hdf5",
    data_path="entry/reconstruction"
)
output_volume = TIFFVolume(
    folder="output_vol",
    volume_basename="5.06_crayon_W150_60_Al2_W0.25_xc1000",
)

output_volume.overwrite = True
cast_volume(
    input_volume=input_volume,
    output_volume=output_volume,
    output_data_type=numpy.uint16,
    rescale_min_percentile=0,
    rescale_max_percentile=100,
)

Note 1: in the python API, the output-data-type is a mandatory parameter (no default value is set).

Note 2 on volumes and python: if you want to "play" and or / know more about tomoscan volumes this can be a nice entry point