Skip to main content
`Ctrl`+`K`

# 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 series or pages interface built in tifffile, `series` interface (default) returns multipage series of images as a single array with single metadata and original metadata structure of first page. Using `multipage_to_list=True` will use `pages` interface and will return a list of separate arrays and metadata per page.

## 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:
    filename `python:str`, `pathlib.Path`

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

    lazy bool, 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_resolution bool, default=False

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

    multipage_as_list bool, default=False

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

    hamamatsu_streak_axis_type `python:str`, default=None

      Decide the type of the 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 of 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.

    **kwds `python:dict`, optional

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

  Returns:
    `python:list` of `python: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:
    filename `python:str`, `pathlib.Path`

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

    signal `python:dict`

      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_scale bool, default=True

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

    extratags `python:tuple`, `python:list` of `python:tuple`, `python:None`, default=None

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

    **kwds `python:dict`, 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']
      b'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')