giatools.io

Copyright 2017-2025 Leonid Kostrykin, Biomedical Computer Vision Group, Heidelberg University.

Distributed under the MIT license. See file LICENSE for detail or copy at https://opensource.org/licenses/MIT

exception giatools.io.CorruptFileError(filepath: str, *args: Any, **kwargs: Any)

Bases: Exception

Raised when a file is corrupted (or follows an unexpected internal format flavor) and cannot be read.

filepath: str

The path to the file that could not be read.

exception giatools.io.IncompatibleDataError(filepath: str, *args: Any, **kwargs: Any)

Bases: Exception

Raised when a file cannot be written because the data or metadata is incompatible with the file format.

filepath: str

The path to the file that could not be written.

exception giatools.io.UnsupportedFileError(filepath: str, *args: Any, **kwargs: Any)

Bases: Exception

Raised when a file cannot be read or written.

filepath: str

The path to the file that could not be read or written.

giatools.io.backends = [<tifffile Backend>, <omezarr Backend>, <skimage Backend>]

List of the supported backends for reading and writing image files.

For reading, the backends are tried in succession until one is successful.

The tifffile backend is likely to fail if the file is not a TIFF file. The ome_zarr backend is likely to fail if the file is not an OME-Zarr file. The skimage.io.imread backend is able to read a wide variety of image formats, but for some formats it may not be able to extract all metadata, which is why it is less preferred.

For writing, the appropriate backend is selected based on the file extension.

Note

The omezarr backend is only available on Python 3.11 or later.

giatools.io.imreadraw(filepath: str | Path, *args: Any, position: int = 0, **kwargs: Any) → Tuple[ndarray | DaskArray, str, Metadata]

Wrapper for reading images, muting non-fatal errors.

The backends defined in backends are tried in succession until one is successful.

Some image files can store multiple images (e.g., multi-series TIFF files or multi-image OME-Zarr files). In these cases, the desired image can be selected by specifying the position parameter (default: 0, the first image). An IndexError is raised if position is invalid. The peek_num_images_in_file() function can be used to determine the number of images in a file.

Returns a tuple (data, axes, metadata) where data is the image data as a NumPy or Dask array, axes are the axes of the image, and metadata is any additional metadata. Minimal normalization is performed by treating sample axis S as an alias for the channel axis C. For images which are read by the skimage.io.imread backend, single-channel and multi-channel 2-D images are supported, assuming YX axes layout for arrays with two axes and YXC for arrays with three axes, respectively.

Raises:

  • CorruptFileError – If the image cannot be read by the designated backend due to corruption or an unsupported format flavor.

  • FileNotFoundError – If the specified file does not exist.

  • UnsupportedFileError – If no backend could read the image.

giatools.io.imwrite(data: ndarray | DaskArray, filepath: str | Path, axes: str, metadata: Metadata, backend: str = 'auto', **kwargs: Any)

Save an image to a file.

Raises:

  • IncompatibleDataError – If the image data or metadata is incompatible with the file format (inferred from the suffix of the file).

  • UnsupportedFileError – If no backend is available to write the file format (inferred from the suffix of the file).

  • ValueError – If backend is not "auto" and the specified backend is not available, or if the image data or metadata are invalid (e.g., None, invalid axes or dimensions).

giatools.io.peek_num_images_in_file(filepath: str | Path, *args: Any, **kwargs: Any) → int

Peeks the number of images that can be loaded from a file.

Example

>>> from giatools.io import peek_num_images_in_file
>>> print(
...     'Images in multi-series TIFF:',
...     peek_num_images_in_file('data/input11.ome.tiff'),
... )
Images in multi-series TIFF: 6
>>> print(
...     'Images in single-series TIFF:',
...     peek_num_images_in_file('data/input1_uint8_yx.tiff'),
... )
Images in single-series TIFF: 1
>>> print(
...     'Images in PNG file:',
...     peek_num_images_in_file('data/input4_uint8.png'),
... )
Images in PNG file: 1
Raises:

  • FileNotFoundError – If the specified file does not exist.

  • UnsupportedFileError – If no backend could read the image.