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.
- 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()
orTiffPageSeries.aszarr()
.
- Return type:
- 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.