Volume casting allow users to convert any volume created by nabu to another format and or / different values scale
Volume casting can be done from command line interface (CLI) or from the python API. Complete documentation is available here
volumes for test are available in /scisoft/tomo_training/part5_volume_casting/volumes
!nabu-cast --help
usage: nabu-cast [-h] [--output-data-type OUTPUT_DATA_TYPE]
[--output_volume OUTPUT_VOLUME] [--output_type OUTPUT_TYPE]
[--data_min DATA_MIN] [--data_max DATA_MAX]
[--rescale_min_percentile RESCALE_MIN_PERCENTILE]
[--rescale_max_percentile RESCALE_MAX_PERCENTILE]
[--overwrite]
input_volume
positional arguments:
input_volume input volume. To define a volume you can either provide:
* an url (recommanded way) - see details lower
* a path. For hdf5 and multitiff we expect a file path. For edf, tif and jp2k we expect a folder path. In this case we will try to deduce the Volume from it.
url must be defined like:
- EDFVolume : edf:volume:/path/to/my/my_folder ; edf:volume:/path/to/my/my_folder?file_prefix=mybasename (if mybasename != folder name)
- HDF5Volume : hdf5:volume:/path/to/file_path?data_path=entry0000
- JP2KVolume : jp2k:volume:/path/to/my/my_folder ; jp2k:volume:/path/to/my/my_folder?file_prefix=mybasename (if mybasename != folder name)
- MultiTIFFVolume: tiff3d:volume:/path/to/tiff_file.tif
- TIFFVolume : tiff:volume:/path/to/my/my_folder ; tiff:volume:/path/to/my/my_folder?file_prefix=mybasename (if mybasename != folder name)
optional arguments:
-h, --help show this help message and exit
--output-data-type OUTPUT_DATA_TYPE
output data type. Valid value are numpy default types name like (uint8, uint16, int8, int16, int32, float32, float64)
--output_volume OUTPUT_VOLUME
output volume. Must be provided if 'output_type' isn't. Must looks like:
To define a volume you can either provide:
* an url (recommanded way) - see details lower
* a path. For hdf5 and multitiff we expect a file path. For edf, tif and jp2k we expect a folder path. In this case we will try to deduce the Volume from it.
url must be defined like:
- EDFVolume : edf:volume:/path/to/my/my_folder ; edf:volume:/path/to/my/my_folder?file_prefix=mybasename (if mybasename != folder name)
- HDF5Volume : hdf5:volume:/path/to/file_path?data_path=entry0000
- JP2KVolume : jp2k:volume:/path/to/my/my_folder ; jp2k:volume:/path/to/my/my_folder?file_prefix=mybasename (if mybasename != folder name)
- MultiTIFFVolume: tiff3d:volume:/path/to/tiff_file.tif
- TIFFVolume : tiff:volume:/path/to/my/my_folder ; tiff:volume:/path/to/my/my_folder?file_prefix=mybasename (if mybasename != folder name)
--output_type OUTPUT_TYPE
output type. Must be provided if 'output_volume' isn't. Valid values are ('h5', 'hdf5', 'nexus', 'nx', 'npy', 'npz', 'tif', 'tiff', 'jp2', 'jp2k', 'j2k', 'jpeg2000', 'edf', 'vol')
--data_min DATA_MIN value to clamp to volume cast new min. Any lower value will also be clamp to this value.
--data_max DATA_MAX value to clamp to volume cast new max. Any higher value will also be clamp to this value.
--rescale_min_percentile RESCALE_MIN_PERCENTILE
used to determine data_min if not provided. Expected as percentage. Default is 10%
--rescale_max_percentile RESCALE_MAX_PERCENTILE
used to determine data_max if not provided. Expected as percentage. Default is 90%
--overwrite Overwrite file or dataset if exists
For example if we want to cast the hdf5 volume to jp2k (as uint16) we can go for:
nabu-cast 5.06_crayon_W150_60_Al2_W0.25_xc1000__vol.hdf5 --output-data-type uint16 --output_type jp2k
This will cast from hdf5 current data type (float32) to uint 16. And it will use the default rescale_min_percentile and rescale_max_percentile values (10% and 90%)
But providing files / folders directly (instead of volume identifier) might fail whan you have several volumes in the same file for example. The recommanded way is to go for volume identifier like:
nabu-cast hdf5:volume:5.06_crayon_W150_60_Al2_W0.25_xc1000__vol.hdf5?data_path=entry/reconstruction --output-data-type uint16 --output_type jp2k
See details about volume identifiers (url) is recommended.
the rescale_min_percentile and rescale_max_percentile parameters will be used for "rescaling" values. Lower and higher values will be clamp to the
rescale_min_percentile and rescale_max_percentile.
instead of using rescale percentile parameters you can provide directly the data_min and data_max for values rescaling.
in this example we will cast a float32 from edf to uint8 and redefining the rescale percentile.
nabu-cast 5.06_crayon_W150_60_Al2_W0.25_xc1000__vol/ --output_volume hdf5:volume:cast.hdf5?data_path=my_volume --rescale_min_percentile 0 --rescale_max_percentile 70
during nabu reconstruction you can ask to generate the histogram of values (postproc/output_histogram option). If you intend to cast the volume it is better to ask for the histogram.
Otherwise min/max value will be computed and this will highly increase the time to cast the volume
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
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 = options.overwrite
cast_volume(
input_volume=input_volume,
output_volume=output_volume,
output_data_type=numpy.uint16,
rescale_min_percentile=0,
rescale_max_percentile=100,
)
Note on volumes and python: if you want to "play" and or / know more about tomoscan volumes this can be a nice entry point