Extraction of TIFF images from image data in the HDF format (with optional bit-depth reduction) and related matters¶
Introduction
It may sometimes be desirable to extract individual TIFF images from an HDF5 dataset and, optionally, reduce their bit-depth at the same time. Similarly, it may sometimes be useful to reduce the bit depth of any given set of TIFF images. The table below provides a summary of the most-frequently encountered contexts:
| Context | Dataset provenance | Brief description of dataset | Numeric data type of generic dataset | Rank (R) of generic dataset | Command to extract individual TIFF images, preserving the original numeric data type and bit depth |
Command to extract individual TIFF images, capable of modifying the original numeric data type and bit depth | Comment(s) |
|---|---|---|---|---|---|---|---|
| 1 | HDF5 dataset of reconstruction volume | Single 3d dataset containing reconstruction volume generated by Savu Tomography Reconstruction Pipeline. | 32-bit floating point | 3 (or R>3 for datasets with R-3 singleton dimensions, i.e. dimensions of unit length) | nxs2tiff | nxs2tiffux | Can be applied to extract (bit-reduced) TIFF images from any 3d-dataset generated by any plug-in in Savu. |
| 2 | HDF5 dataset of raw data | Single 3d dataset containing sample projections and, possibly, dark- and flat-field images. | 16-bit unsigned integer | 3 | nxs2tiff | nxs2tiffux | Can be applied to extract (bit-reduced) TIFF images from any 3d-dataset created by any HDF5 File Writer in GDA or EPICS. |
| 3 | Directory of reconstructed slices in the TIFF format | Sequence of reconstructed slices, stored as individual TIFF files in a single directory. | 32-bit floating point | 2 | n/a | tiff2tiffux | Can be applied to reduce the bit depth of TIFF images generated by the tomo-recon command (the predecessor of Savu). |
| 4 | Directory of raw-data files in the TIFF format | Sequence of raw images (including sample projections and, possibly, dark- and flat-field images), stored as individual TIFF files in a single directory. | 16-bit unsigned integer | 2 | n/a | tiff2tiffux | Can be applied to reduce the bit depth of TIFF images created by any TIFF File Writer in GDA or EPICS. |
All commands mentioned above become available after executing:
module add tomography
For a brief description of all available options and arguments for any of these commands, please execute:
<command-name> -h
Context 1: HDF5 dataset of reconstruction volume (3d)
nxs2tiff
Example 1: extraction of TIFFs with the original 32-bit floating-point data type being preserved
- Linux Command
>>> nxs2tiff -d /entry/final_result_tomo/data -b 0 -s 50 -i 1 --fp /dls/i13/data/2017/cm16786-1/processing/savu/vxu94780/13429/20170301171639_13429/13429_processed.nxs /dls/i13/data/2017/cm16786-1/processing/savu/vxu94780/13429/tiffs/
Note the essential --fp option being specified above. Note also that the shape of the dataset in this particular example is (2560, 2160, 2560), with the layout being (image_height, image_index, image_width).
Example 2: extraction of TIFFs with the original 32-bit floating-point data type being preserved
- Linux Command
>>> python /dls_sw/apps/tomopy/tomopy/src/nxs2tiff.py -b 0 -s 130 -d 2-AstraReconGpu-tomo/data -i 3 --fp /dls/i13/data/2019/cm22976-1/processing/test/mt21081-1/recon/20190303220500_108393/tomo_p2_astra_recon_gpu.h5 ./Tiffs
Note that the shape of the dataset in this particular example is (2560, 1, 2560, 130), with the layout being (image_height, singleton_index, image_width, image_index). Incidentally, the above example also shows how to run nxs2tiff on a local workstation rather than on the compute cluster.
nxs2tiffux
Example: extraction of TIFFs accompanied by reduction of the original 32-bit floating-point data type to 8-bit unsigned integer, using explicitly specified input values for the min (--lo) and max (--hi) intensity values
- Linux Command
>>> nxs2tiffux -d /entry/final_result_tomo/data -b 0 -s 50 -i 1 -u 8 --lo -0.0016974231 --hi 0.0016586095 /dls/i13/data/2017/cm16786-1/processing/savu/vxu94780/13429/20170301171639_13429/13429_processed.nxs /dls/i13/data/2017/cm16786-1/processing/savu/vxu94780/13429/tiffs/u8/
Note the -u 8 option being specified above.
Context 2: HDF5 dataset of raw data (3d)
nxs2tiff
Example: extraction of TIFFs with the original 16-bit unsigned-integer data type being preserved
- Linux Command
>>> nxs2tiff -d /entry1/instrument/pco1_hw_hdf/data -b 0 -s 2159 /dls/i13/data/2013/cm5937-3/raw/23912.nxs /dls/i13/data/2013/cm5937-3/processing/raw/23912/projections/
nxs2tiffux
Example: extraction of TIFFs accompanied by reduction of the original 16-bit unsigned-integer data type to 8-bit unsigned integer, using explicitly specified input values for the min (--lo) and max (--hi) intensity values
- Linux Command
>>> nxs2tiffux -d /entry1/instrument/pco1_hw_hdf/data -i 1 -u 8 --lo -0.0016974231 --hi 0.0016586095 /dls/i13/data/2013/cm5937-3/raw/23912.nxs /dls/i13/data/2013/cm5937-3/processing/raw/23912/projections/u8/
Note the -u 8 option being specified above.
Context 3: Directory of reconstructed slices in the TIFF format (2d)
tiff2tiffux
Example 1: reduction of the bit-depth of TIFFs from the original 32-bit floating-point data type to 8-bit unsigned integer, using a reference slice for implicit specification of the min and max intensity values
- Linux Command
>>> tiff2tiffux -b 0 -s 2159 -i recon_129200_%05d.tif -o recon_129200_%05d.tif -u 8 --use_ref -r 1080 -p 0.1 /dls/i13/data/2017/mt16557-1/processing/reconstruction/87637/ /dls/i13/data/2017/mt16557-1/processing/reconstruction/bit_reduced/u8/87637/
Note the -u 8 option being specified above. The input and the output filename formats do not have to be the same, but need to follow the standard Python syntax for formatting strings. In the above example, %05d is used to indicate a 5-character long string representation of integer decimal that is padded with leading zeros as required. In other words, -b 0 -s 2159 -i recon_129200_%05d.tif generates the following series of 2159 input filenames: recon_129200_00000.tif, recon_129200_00001.tif, recon_129200_00002.tif ,... recon_129200_02157.tif, recon_129200_02158.tif (and, as is the case for this particular example, an identical series of the output filenames, but one could use the -o option to add, for example, the scan number information (which, in this case, happens to be 87637) to the output filenames by specifying -o recon_87637_129200_%05d.tif). For more info on Python string formatting, see for example https://python-reference.readthedocs.io/en/latest/docs/str/formatting.html. Note also the presence of --use_ref -r 1080 for instructing tiff2tiffux to automatically determine the min (--lo) and max (--hi) intensity values from a single reference image, named recon_129200_01080.tif (the index of 1080 is used in this example to select a reasonably-representative reference image from the middle of the series of these 2159 input images).
Example 2: reduction of the bit-depth of TIFFs from the original 32-bit floating-point data type to 8-bit unsigned integer, using explicitly specified input values for the min (--lo) and max (--hi) intensity values
- Linux Command
>>> tiff2tiffux -b 0 -s 2159 -i recon_129200_%05d.tif -o recon_129200_%05d.tif -u 8 --lo -0.0016974231 --hi 0.0016586095 /dls/i13/data/2017/mt16557-1/processing/reconstruction/87637/ /dls/i13/data/2017/mt16557-1/processing/reconstruction/bit_reduced/u8/87637/
Note the -u 8 option being specified above.
Context 4: Directory of raw-data files in the TIFF format (2d)
See Context 3.