TiffFile

final class tifffile.TiffFile(file, /, *, mode=None, name=None, offset=None, size=None, omexml=None, _multifile=None, _useframes=None, _parent=None, **is_flags)

Read image and metadata from TIFF file.

TiffFile instances must be closed with TiffFile.close(), which is automatically called when using the ‘with’ context manager.

TiffFile instances are not thread-safe. All attributes are read-only.

Parameters:
  • file (str | os.PathLike[Any] | FileHandle | IO[bytes]) – Specifies TIFF file to read. Open file objects must be positioned at the TIFF header.

  • mode (Literal['r', 'r+'] | None) – File open mode if file is file name. The default is ‘rb’.

  • name (str | None) – Name of file if file is file handle.

  • offset (int | None) – Start position of embedded file. The default is the current file position.

  • size (int | None) – Size of embedded file. The default is the number of bytes from the offset to the end of the file.

  • omexml (str | None) – OME metadata in XML format, for example, from external companion file or sanitized XML overriding XML in file.

  • _multifile (bool | None) – Internal use.

  • _useframes (bool | None) – Internal use.

  • _parent (TiffFile | None) – Internal use.

  • **is_flags (bool | None) –

    Override TiffFile.is_ flags, for example:

    is_ome=False: disable processing of OME-XML metadata. is_lsm=False: disable special handling of LSM files. is_ndpi=True: force file to be NDPI format.

Raises:

TiffFileError – Invalid TIFF structure.

tiff: TiffFormat

Properties of TIFF file format.

pages: TiffPages

Sequence of pages in TIFF file.

property byteorder: Literal['>', '<']

Byteorder of TIFF file.

property filehandle: FileHandle

File handle.

property filename: str

Name of file handle.

property fstat: Any

Status of file handle’s descriptor, if any.

close()

Close open file handle(s).

Return type:

None

asarray(key=None, *, series=None, level=None, squeeze=None, out=None, maxworkers=None, buffersize=None)

Return images from select pages as NumPy array.

By default, the image array from the first level of the first series is returned.

Parameters:
  • key (int | slice | Iterable[int] | None) – Specifies which pages to return as array. By default, the image of the specified series and level is returned. If not None, the images from the specified pages in the whole file (if series is None) or a specified series are returned as a stacked array. Requesting an array from multiple pages that are not compatible wrt. shape, dtype, compression etc. is undefined, that is, it may crash or return incorrect values.

  • series (int | TiffPageSeries | None) – Specifies which series of pages to return as array. The default is 0.

  • level (int | None) – Specifies which level of multi-resolution series to return as array. The default is 0.

  • squeeze (bool | None) – If True, remove all length-1 dimensions (except X and Y) from array. If False, single pages are returned as 5D array of shape TiffPage.shaped. For series, the shape of the returned array also includes singlet dimensions specified in some file formats. For example, ImageJ series and most commonly also OME series, are returned in TZCYXS order. By default, all but “shaped” series are squeezed.

  • out (OutputType) – Specifies how image array is returned. By default, a new NumPy array is created. If a numpy.ndarray, a writable array to which the image is copied. If ‘memmap’, directly memory-map the image data in the file if possible; else create a memory-mapped array in a temporary file. If a string or open file, the file used to create a memory-mapped array.

  • maxworkers (int | None) – Maximum number of threads to concurrently decode data from multiple pages or compressed segments. If None or 0, use up to _TIFF.MAXWORKERS threads. Reading data from file is limited to the main thread. Using multiple threads can significantly speed up this function if the bottleneck is decoding compressed data, for example, in case of large LZW compressed LSM files or JPEG compressed tiled slides. If the bottleneck is I/O or pure Python code, using multiple threads might be detrimental.

  • buffersize (int | None) – Approximate number of bytes to read from file in one pass. The default is _TIFF.BUFFERSIZE.

Returns:

Images from specified pages. See TiffPage.asarray for operations that are applied (or not) to the image data stored in the file.

Return type:

NDArray[Any]

aszarr(key=None, *, series=None, level=None, **kwargs)

Return images from select pages as Zarr store.

By default, the images from the first series, including all levels, are wrapped as a Zarr store.

Parameters:
  • key (int | None) – Index of page in file (if series is None) or series to wrap as Zarr store. By default, a series is wrapped.

  • series (int | TiffPageSeries | None) – Index of series to wrap as Zarr store. The default is 0 (if key is None).

  • level (int | None) – Index of pyramid level in series to wrap as Zarr store. By default, all levels are included as a multi-scale group.

  • **kwargs (Any) – Additional arguments passed to TiffPage.aszarr() or TiffPageSeries.aszarr().

Return type:

ZarrTiffStore

property series: list[TiffPageSeries]

Series of pages with compatible shape and data type.

Side effect: after accessing this property, TiffFile.pages might contain TiffPage and TiffFrame instead of only TiffPage instances.

property flags: set[str]

Set of file flags (a potentially expensive operation).

property is_uniform: bool

File contains uniform series of pages.

property is_appendable: bool

Pages can be appended to file without corrupting.

property is_bigtiff: bool

File has BigTIFF format.

property is_ndtiff: bool

File has NDTiff format.

property is_mmstack: bool

File has Micro-Manager stack format.

property is_mdgel: bool

File has MD Gel format.

property is_sis: bool

File is Olympus SIS format.

property shaped_metadata: tuple[dict[str, Any], ...] | None

Tifffile metadata from JSON formatted ImageDescription tags.

property ome_metadata: str | None

OME XML metadata from ImageDescription tag.

property scn_metadata: str | None

Leica SCN XML metadata from ImageDescription tag.

property philips_metadata: str | None

Philips DP XML metadata from ImageDescription tag.

property indica_metadata: str | None

IndicaLabs XML metadata from ImageDescription tag.

property avs_metadata: str | None

Argos AVS XML metadata from tag 65000.

property lsm_metadata: dict[str, Any] | None

LSM metadata from CZ_LSMINFO tag.

property stk_metadata: dict[str, Any] | None

STK metadata from UIC tags.

property imagej_metadata: dict[str, Any] | None

ImageJ metadata from ImageDescription and IJMetadata tags.

property fluoview_metadata: dict[str, Any] | None

FluoView metadata from MM_Header and MM_Stamp tags.

property nih_metadata: dict[str, Any] | None

NIHImage metadata from NIHImageHeader tag.

property fei_metadata: dict[str, Any] | None

FEI metadata from SFEG or HELIOS tags.

property sem_metadata: dict[str, Any] | None

SEM metadata from CZ_SEM tag.

property sis_metadata: dict[str, Any] | None

Olympus SIS metadata from OlympusSIS and OlympusINI tags.

property mdgel_metadata: dict[str, Any] | None

MD-GEL metadata from MDFileTag tags.

property andor_metadata: dict[str, Any] | None

Andor metadata from Andor tags.

property epics_metadata: dict[str, Any] | None

EPICS metadata from areaDetector tags.

property tvips_metadata: dict[str, Any] | None

TVIPS metadata from tag.

property metaseries_metadata: dict[str, Any] | None

MetaSeries metadata from ImageDescription tag of first tag.

property pilatus_metadata: dict[str, Any] | None

Pilatus metadata from ImageDescription tag.

property micromanager_metadata: dict[str, Any] | None

Non-TIFF Micro-Manager metadata.

property gdal_structural_metadata: dict[str, Any] | None

Non-TIFF GDAL structural metadata.

property scanimage_metadata: dict[str, Any] | None

ScanImage non-varying frame and ROI metadata.

The returned dict may contain ‘FrameData’, ‘RoiGroups’, and ‘version’ keys.

Varying frame data can be found in the ImageDescription tags.

property geotiff_metadata: dict[str, Any] | None

GeoTIFF metadata from tags.

property gdal_metadata: dict[str, Any] | None

GDAL XML metadata from GDAL_METADATA tag.

property astrotiff_metadata: dict[str, Any] | None

AstroTIFF metadata from ImageDescription tag.

property streak_metadata: dict[str, Any] | None

Hamamatsu streak metadata from ImageDescription tag.

property eer_metadata: str | None

EER AcquisitionMetadata XML from tag 65001.