Tagged image file format (TIFF)#

Note

To read this format, the optional dependency tifffile is required.

RosettaSciIO can read and write 2D and 3D .tiff files using using Christoph Gohlke’s tifffile library. In particular, it supports reading and writing of TIFF, BigTIFF, OME-TIFF, STK, LSM, NIH, and FluoView files. Most of these are uncompressed or losslessly compressed 2**(0 to 6) bit integer, 16, 32 and 64-bit float, grayscale and RGB(A) images, which are commonly used in bio-scientific imaging. See the library webpage for more details.

Currently, RosettaSciIO has limited support for reading and saving the TIFF tags. However, the way that RosettaSciIO reads and saves the scale and the units of .tiff files is compatible with ImageJ/Fiji and Gatan Digital Micrograph software. RosettaSciIO can also import the scale and the units from .tiff files saved using FEI, Zeiss SEM, Olympus SIS, Jeol SightX and Hamamatsu HPD-TA (streak camera) software.

Multipage tiff files are read using either the series or pages interface built in tifffile, the series interface (default) returns multipage series of images as a single array with only the metadata and original metadata structure of the first page. Using multipage_to_list=True will use the pages interface and will return a list of separate arrays and metadata per page.

When a tiff file containing a Hamamatsu streak image is read and LumiSpy is installed, TransientSpectrum will be used as the signal_type. Note that also the Hamamatsu itex (.img) format can be read, for which the metadata is parsed.

API functions#

rsciio.tiff.file_reader(filename, lazy=False, force_read_resolution=False, multipage_as_list=False, hamamatsu_streak_axis_type=None, **kwds)#

Read data from tif files using Christoph Gohlke’s tifffile library.

The units and the scale of images saved with ImageJ or Digital Micrograph is read. There is limited support for reading the scale of files created with Zeiss and FEI SEMs.

Parameters:
filenamestr, pathlib.Path

Filename of the file to read or corresponding pathlib.Path.

lazybool, default=False

Whether to open the file lazily or not. The file will stay open until closed in compute() or closed manually. get_file_handle() can be used to access the file handler and close it manually.

force_read_resolutionbool, default=False

Force read image resolution using the x_resolution, y_resolution and resolution_unit tiff tags. Beware: most software does not (properly) use these tags when saving .tiff files. See https://www.loc.gov/preservation/digital/formats/content/tiff_tags.shtml.

multipage_as_listbool, default=False

Read multipage tiff images and return list with full content of every page. This utilises pages from tifffile instead of series for data access, which in contrast to series is able to return metadata per page. series (default) is only able to access metadata from the first page. This is recommended to be used when data is from dynamic experiments (where some parameters of the instrument are changing during acquisition).

hamamatsu_streak_axis_typestr, default=None

Select the type of time axis for hamamatsu streak files:

  • "uniform": the best-fit linear axis is used, inducing a (small) linearisation error. Initialise a UniformDataAxis.

  • "data": the raw time axis parsed from the metadata is used. Initialise a DataAxis.

  • "functional": the best-fit 3rd-order polynomial axis is used, avoiding linearisation error. Initialise a FunctionalDataAxis.

By default (None), uniform is used but a warning about the linearisation error is issued. Explicitly passing hamamatsu_streak_axis_type='uniform' suppresses the warning. In all cases, the original axis values are stored in the original_metadata of the signal object. Alternatively, a DataAxis can be subsequently converted to a UniformDataAxis by interpolation using the function interpolate_on_axis('uniform', axis=1).

**kwdsdict, optional

Additional arguments to be passed to the TiffFile class of the tifffile library.

Returns:
list of dict

List of dictionaries containing the following fields:

  • ‘data’ – multidimensional numpy.ndarray or dask.array.Array

  • ‘axes’ – list of dictionaries describing the axes containing the fields ‘name’, ‘units’, ‘index_in_array’, and either ‘size’, ‘offset’, and ‘scale’ or a numpy array ‘axis’ containing the full axes vector

  • ‘metadata’ – dictionary containing the parsed metadata

  • ‘original_metadata’ – dictionary containing the full metadata tree from the input file

When the file contains several datasets, each dataset will be loaded as separate dictionary.

Examples

>>> # Force read image resolution using the x_resolution, y_resolution and
>>> # the resolution_unit of the TIFF tags.
>>> s = file_reader('file.tif', force_read_resolution=True)
>>> # Load a non-uniform axis from a hamamatsu streak file:
>>> s = file_reader('file.tif', hamamatsu_streak_axis_type='data')
rsciio.tiff.file_writer(filename, signal, export_scale=True, extratags=None, **kwds)#

Write data to tif using Christoph Gohlke’s tifffile library.

Parameters:
filenamestr, pathlib.Path

Filename of the file to write to or corresponding pathlib.Path.

signaldict

Dictionary containing the signal object. Should contain the following fields:

  • ‘data’ – multidimensional numpy array

  • ‘axes’ – list of dictionaries describing the axes containing the fields ‘name’, ‘units’, ‘index_in_array’, and either ‘size’, ‘offset’, and ‘scale’ or a numpy array ‘axis’ containing the full axes vector

  • ‘metadata’ – dictionary containing the metadata tree

export_scalebool, default=True

Export the scale and the units (compatible with DM and ImageJ) to appropriate tags.

extratagstuple, list of tuple, None, default=None

Save custom tags through the tifffile library. Must conform to a specific convention (see tifffile documentation and example below).

**kwdsdict, optional

Additional arguments to be passed to the imwrite function of the tifffile library.

Examples

>>> # Saving the string 'Random metadata' in a custom tag (ID 65000)
>>> extratag = [(65000, 's', 1, "Random metadata", False)]
>>> file_writer('file.tif', signal, extratags=extratag)

>>> # Reading the string 'Random metadata' from a custom tag (ID 65000)
>>> s2 = file_reader('file.tif')
>>> s2.original_metadata['Number_65000']
'Random metadata'

Warning

The file will be saved with the same bit depth as the signal. Since most processing operations in HyperSpy and numpy will result in 64-bit floats, this can result in 64-bit .tiff files, which are not always compatible with other imaging software.

You can first change the dtype of the signal before saving (example using HyperSpy):

>>> s.data.dtype
dtype('float64')
>>> s.change_dtype('float32')
>>> s.data.dtype
dtype('float32')
>>> s.save('file.tif')