581 lines
23 KiB
Text
581 lines
23 KiB
Text
|
Metadata-Version: 2.1
|
||
|
|
Name: tifffile
|
||
|
|
Version: 2020.9.3
|
||
|
|
Summary: Read and write TIFF(r) files
|
||
|
|
Home-page: https://www.lfd.uci.edu/~gohlke/
|
||
|
|
Author: Christoph Gohlke
|
||
|
|
Author-email: cgohlke@uci.edu
|
||
|
|
License: BSD
|
||
|
|
Project-URL: Bug Tracker, https://github.com/cgohlke/tifffile/issues
|
||
|
|
Project-URL: Source Code, https://github.com/cgohlke/tifffile
|
||
|
|
Platform: any
|
||
|
|
Classifier: Development Status :: 4 - Beta
|
||
|
|
Classifier: License :: OSI Approved :: BSD License
|
||
|
|
Classifier: Intended Audience :: Science/Research
|
||
|
|
Classifier: Intended Audience :: Developers
|
||
|
|
Classifier: Operating System :: OS Independent
|
||
|
|
Classifier: Programming Language :: Python :: 3 :: Only
|
||
|
|
Classifier: Programming Language :: Python :: 3.7
|
||
|
|
Classifier: Programming Language :: Python :: 3.8
|
||
|
|
Classifier: Programming Language :: Python :: 3.9
|
||
|
|
Requires-Python: >=3.6
|
||
|
|
Requires-Dist: numpy (>=1.15.1)
|
||
|
|
Provides-Extra: all
|
||
|
|
Requires-Dist: imagecodecs (>=2020.2.18) ; extra == 'all'
|
||
|
|
Requires-Dist: matplotlib (>=3.1) ; extra == 'all'
|
||
|
|
Requires-Dist: lxml ; extra == 'all'
|
||
|
|
|
||
|
|
Read and write TIFF(r) files
|
||
|
|
============================
|
||
|
|
|
||
|
|
Tifffile is a Python library to
|
||
|
|
|
||
|
|
(1) store numpy arrays in TIFF (Tagged Image File Format) files, and
|
||
|
|
(2) read image and metadata from TIFF-like files used in bioimaging.
|
||
|
|
|
||
|
|
Image and metadata can be read from TIFF, BigTIFF, OME-TIFF, STK, LSM, SGI,
|
||
|
|
NIHImage, ImageJ, MicroManager, FluoView, ScanImage, SEQ, GEL, SVS, SCN, SIS,
|
||
|
|
ZIF (Zoomable Image File Format), QPTIFF (QPI), NDPI, and GeoTIFF files.
|
||
|
|
|
||
|
|
Numpy arrays can be written to TIFF, BigTIFF, OME-TIFF, and ImageJ hyperstack
|
||
|
|
compatible files in multi-page, memory-mappable, tiled, predicted, or
|
||
|
|
compressed form.
|
||
|
|
|
||
|
|
A subset of the TIFF specification is supported, mainly uncompressed and
|
||
|
|
losslessly compressed 8, 16, 32 and 64-bit integer, 16, 32 and 64-bit float,
|
||
|
|
grayscale and multi-sample images.
|
||
|
|
Specifically, reading slices of image data, CCITT and OJPEG compression,
|
||
|
|
chroma subsampling without JPEG compression, color space transformations,
|
||
|
|
samples with differing types, or IPTC and XMP metadata are not implemented.
|
||
|
|
|
||
|
|
TIFF(r), the Tagged Image File Format, is a trademark and under control of
|
||
|
|
Adobe Systems Incorporated. BigTIFF allows for files larger than 4 GB.
|
||
|
|
STK, LSM, FluoView, SGI, SEQ, GEL, QPTIFF, NDPI, and OME-TIFF, are custom
|
||
|
|
extensions defined by Molecular Devices (Universal Imaging Corporation),
|
||
|
|
Carl Zeiss MicroImaging, Olympus, Silicon Graphics International,
|
||
|
|
Media Cybernetics, Molecular Dynamics, PerkinElmer, Hamamatsu, and the
|
||
|
|
Open Microscopy Environment consortium, respectively.
|
||
|
|
|
||
|
|
For command line usage run ``python -m tifffile --help``
|
||
|
|
|
||
|
|
:Author:
|
||
|
|
`Christoph Gohlke <https://www.lfd.uci.edu/~gohlke/>`_
|
||
|
|
|
||
|
|
:Organization:
|
||
|
|
Laboratory for Fluorescence Dynamics, University of California, Irvine
|
||
|
|
|
||
|
|
:License: BSD 3-Clause
|
||
|
|
|
||
|
|
:Version: 2020.9.3
|
||
|
|
|
||
|
|
Requirements
|
||
|
|
------------
|
||
|
|
This release has been tested with the following requirements and dependencies
|
||
|
|
(other versions may work):
|
||
|
|
|
||
|
|
* `CPython 3.7.9, 3.8.5, 3.9.0rc1 64-bit <https://www.python.org>`_
|
||
|
|
* `Numpy 1.18.5 <https://pypi.org/project/numpy/>`_
|
||
|
|
* `Imagecodecs 2020.5.30 <https://pypi.org/project/imagecodecs/>`_
|
||
|
|
(required only for encoding or decoding LZW, JPEG, etc.)
|
||
|
|
* `Matplotlib 3.2.2 <https://pypi.org/project/matplotlib/>`_
|
||
|
|
(required only for plotting)
|
||
|
|
* `Lxml 4.5.2 <https://github.com/lxml/lxml>`_
|
||
|
|
(required only for validating and printing XML)
|
||
|
|
|
||
|
|
Revisions
|
||
|
|
---------
|
||
|
|
2020.9.3
|
||
|
|
Pass 4338 tests.
|
||
|
|
Do not write contiguous series by default (breaking).
|
||
|
|
Allow to write to SubIFDs (WIP).
|
||
|
|
Fix writing F-contiguous numpy arrays (#24).
|
||
|
|
2020.8.25
|
||
|
|
Do not convert EPICS timeStamp to datetime object.
|
||
|
|
Read incompletely written Micro-Manager image file stack header (#23).
|
||
|
|
Remove tag 51123 values from TiffFile.micromanager_metadata (breaking).
|
||
|
|
2020.8.13
|
||
|
|
Use tifffile metadata over OME and ImageJ for TiffFile.series (breaking).
|
||
|
|
Fix writing iterable of pages with compression (#20).
|
||
|
|
Expand error checking of TiffWriter data, dtype, shape, and tile arguments.
|
||
|
|
2020.7.24
|
||
|
|
Parse nested OmeXml metadata argument (WIP).
|
||
|
|
Do not lazy load TiffFrame JPEGTables.
|
||
|
|
Fix conditionally skipping some tests.
|
||
|
|
2020.7.22
|
||
|
|
Do not auto-enable OME-TIFF if description is passed to TiffWriter.save.
|
||
|
|
Raise error writing empty bilevel or tiled images.
|
||
|
|
Allow to write tiled bilevel images.
|
||
|
|
Allow to write multi-page TIFF from iterable of single page images (WIP).
|
||
|
|
Add function to validate OME-XML.
|
||
|
|
Correct Philips slide width and length.
|
||
|
|
2020.7.17
|
||
|
|
Initial support for writing OME-TIFF (WIP).
|
||
|
|
Return samples as separate dimension in OME series (breaking).
|
||
|
|
Fix modulo dimensions for multiple OME series.
|
||
|
|
Fix some test errors on big endian systems (#18).
|
||
|
|
Fix BytesWarning.
|
||
|
|
Allow to pass TIFF.PREDICTOR values to TiffWriter.save.
|
||
|
|
2020.7.4
|
||
|
|
Deprecate support for Python 3.6 (NEP 29).
|
||
|
|
Move pyramidal subresolution series to TiffPageSeries.levels (breaking).
|
||
|
|
Add parser for SVS, SCN, NDPI, and QPI pyramidal series.
|
||
|
|
Read single-file OME-TIFF pyramids.
|
||
|
|
Read NDPI files > 4 GB (#15).
|
||
|
|
Include SubIFDs in generic series.
|
||
|
|
Preliminary support for writing packed integer arrays (#11, WIP).
|
||
|
|
Read more LSM info subrecords.
|
||
|
|
Fix missing ReferenceBlackWhite tag for YCbCr photometrics.
|
||
|
|
Fix reading lossless JPEG compressed DNG files.
|
||
|
|
2020.6.3
|
||
|
|
Support os.PathLike file names (#9).
|
||
|
|
2020.5.30
|
||
|
|
Re-add pure Python PackBits decoder.
|
||
|
|
2020.5.25
|
||
|
|
Make imagecodecs an optional dependency again.
|
||
|
|
Disable multi-threaded decoding of small LZW compressed segments.
|
||
|
|
Fix caching of TiffPage.decode function.
|
||
|
|
Fix xml.etree.cElementTree ImportError on Python 3.9.
|
||
|
|
Fix tostring DeprecationWarning.
|
||
|
|
2020.5.11
|
||
|
|
Fix reading ImageJ grayscale mode RGB images (#6).
|
||
|
|
Remove napari reader plugin.
|
||
|
|
2020.5.7
|
||
|
|
Add napari reader plugin (tentative).
|
||
|
|
Fix writing single tiles larger than image data (#3).
|
||
|
|
Always store ExtraSamples values in tuple (breaking).
|
||
|
|
2020.5.5
|
||
|
|
Allow to write tiled TIFF from iterable of tiles (WIP).
|
||
|
|
Add function to iterate over decoded segments of TiffPage (WIP).
|
||
|
|
Pass chunks of segments to ThreadPoolExecutor.map to reduce memory usage.
|
||
|
|
Fix reading invalid files with too many strips.
|
||
|
|
Fix writing over-aligned image data.
|
||
|
|
Detect OME-XML without declaration (#2).
|
||
|
|
Support LERC compression (WIP).
|
||
|
|
Delay load imagecodecs functions.
|
||
|
|
Remove maxsize parameter from asarray (breaking).
|
||
|
|
Deprecate ijmetadata parameter from TiffWriter.save (use metadata).
|
||
|
|
2020.2.16
|
||
|
|
Add function to decode individual strips or tiles.
|
||
|
|
Read strips and tiles in order of their offsets.
|
||
|
|
Enable multi-threading when decompressing multiple strips.
|
||
|
|
Replace TiffPage.tags dictionary with TiffTags (breaking).
|
||
|
|
Replace TIFF.TAGS dictionary with TiffTagRegistry.
|
||
|
|
Remove TIFF.TAG_NAMES (breaking).
|
||
|
|
Improve handling of TiffSequence parameters in imread.
|
||
|
|
Match last uncommon parts of file paths to FileSequence pattern (breaking).
|
||
|
|
Allow letters in FileSequence pattern for indexing well plate rows.
|
||
|
|
Allow to reorder axes in FileSequence.
|
||
|
|
Allow to write > 4 GB arrays to plain TIFF when using compression.
|
||
|
|
Allow to write zero size numpy arrays to nonconformant TIFF (tentative).
|
||
|
|
Fix xml2dict.
|
||
|
|
Require imagecodecs >= 2020.1.31.
|
||
|
|
Remove support for imagecodecs-lite (breaking).
|
||
|
|
Remove verify parameter to asarray function (breaking).
|
||
|
|
Remove deprecated lzw_decode functions (breaking).
|
||
|
|
Remove support for Python 2.7 and 3.5 (breaking).
|
||
|
|
2019.7.26
|
||
|
|
Fix infinite loop reading more than two tags of same code in IFD.
|
||
|
|
Delay import of logging module.
|
||
|
|
2019.7.20
|
||
|
|
Fix OME-XML detection for files created by Imaris.
|
||
|
|
Remove or replace assert statements.
|
||
|
|
2019.7.2
|
||
|
|
Do not write SampleFormat tag for unsigned data types.
|
||
|
|
Write ByteCount tag values as SHORT or LONG if possible.
|
||
|
|
Allow to specify axes in FileSequence pattern via group names.
|
||
|
|
Add option to concurrently read FileSequence using threads.
|
||
|
|
Derive TiffSequence from FileSequence.
|
||
|
|
Use str(datetime.timedelta) to format Timer duration.
|
||
|
|
Use perf_counter for Timer if possible.
|
||
|
|
2019.6.18
|
||
|
|
Fix reading planar RGB ImageJ files created by Bio-Formats.
|
||
|
|
Fix reading single-file, multi-image OME-TIFF without UUID.
|
||
|
|
Presume LSM stores uncompressed images contiguously per page.
|
||
|
|
Reformat some complex expressions.
|
||
|
|
2019.5.30
|
||
|
|
Ignore invalid frames in OME-TIFF.
|
||
|
|
Set default subsampling to (2, 2) for RGB JPEG compression.
|
||
|
|
Fix reading and writing planar RGB JPEG compression.
|
||
|
|
Replace buffered_read with FileHandle.read_segments.
|
||
|
|
Include page or frame numbers in exceptions and warnings.
|
||
|
|
Add Timer class.
|
||
|
|
2019.5.22
|
||
|
|
Add optional chroma subsampling for JPEG compression.
|
||
|
|
Enable writing PNG, JPEG, JPEGXR, and JPEG2K compression (WIP).
|
||
|
|
Fix writing tiled images with WebP compression.
|
||
|
|
Improve handling GeoTIFF sparse files.
|
||
|
|
2019.3.18
|
||
|
|
Fix regression decoding JPEG with RGB photometrics.
|
||
|
|
Fix reading OME-TIFF files with corrupted but unused pages.
|
||
|
|
Allow to load TiffFrame without specifying keyframe.
|
||
|
|
Calculate virtual TiffFrames for non-BigTIFF ScanImage files > 2GB.
|
||
|
|
Rename property is_chroma_subsampled to is_subsampled (breaking).
|
||
|
|
Make more attributes and methods private (WIP).
|
||
|
|
2019.3.8
|
||
|
|
Fix MemoryError when RowsPerStrip > ImageLength.
|
||
|
|
Fix SyntaxWarning on Python 3.8.
|
||
|
|
Fail to decode JPEG to planar RGB (tentative).
|
||
|
|
Separate public from private test files (WIP).
|
||
|
|
Allow testing without data files or imagecodecs.
|
||
|
|
2019.2.22
|
||
|
|
Use imagecodecs-lite as a fallback for imagecodecs.
|
||
|
|
Simplify reading numpy arrays from file.
|
||
|
|
Use TiffFrames when reading arrays from page sequences.
|
||
|
|
Support slices and iterators in TiffPageSeries sequence interface.
|
||
|
|
Auto-detect uniform series.
|
||
|
|
Use page hash to determine generic series.
|
||
|
|
Turn off TiffPages cache (tentative).
|
||
|
|
Pass through more parameters in imread.
|
||
|
|
Discontinue movie parameter in imread and TiffFile (breaking).
|
||
|
|
Discontinue bigsize parameter in imwrite (breaking).
|
||
|
|
Raise TiffFileError in case of issues with TIFF structure.
|
||
|
|
Return TiffFile.ome_metadata as XML (breaking).
|
||
|
|
Ignore OME series when last dimensions are not stored in TIFF pages.
|
||
|
|
2019.2.10
|
||
|
|
Assemble IFDs in memory to speed-up writing on some slow media.
|
||
|
|
Handle discontinued arguments fastij, multifile_close, and pages.
|
||
|
|
2019.1.30
|
||
|
|
Use black background in imshow.
|
||
|
|
Do not write datetime tag by default (breaking).
|
||
|
|
Fix OME-TIFF with SamplesPerPixel > 1.
|
||
|
|
Allow 64-bit IFD offsets for NDPI (files > 4GB still not supported).
|
||
|
|
2019.1.4
|
||
|
|
Fix decoding deflate without imagecodecs.
|
||
|
|
2019.1.1
|
||
|
|
Update copyright year.
|
||
|
|
Require imagecodecs >= 2018.12.16.
|
||
|
|
Do not use JPEG tables from keyframe.
|
||
|
|
Enable decoding large JPEG in NDPI.
|
||
|
|
Decode some old-style JPEG.
|
||
|
|
Reorder OME channel axis to match PlanarConfiguration storage.
|
||
|
|
Return tiled images as contiguous arrays.
|
||
|
|
Add decode_lzw proxy function for compatibility with old czifile module.
|
||
|
|
Use dedicated logger.
|
||
|
|
2018.11.28
|
||
|
|
Make SubIFDs accessible as TiffPage.pages.
|
||
|
|
Make parsing of TiffSequence axes pattern optional (breaking).
|
||
|
|
Limit parsing of TiffSequence axes pattern to file names, not path names.
|
||
|
|
Do not interpolate in imshow if image dimensions <= 512, else use bilinear.
|
||
|
|
Use logging.warning instead of warnings.warn in many cases.
|
||
|
|
Fix numpy FutureWarning for out == 'memmap'.
|
||
|
|
Adjust ZSTD and WebP compression to libtiff-4.0.10 (WIP).
|
||
|
|
Decode old-style LZW with imagecodecs >= 2018.11.8.
|
||
|
|
Remove TiffFile.qptiff_metadata (QPI metadata are per page).
|
||
|
|
Do not use keyword arguments before variable positional arguments.
|
||
|
|
Make either all or none return statements in a function return expression.
|
||
|
|
Use pytest parametrize to generate tests.
|
||
|
|
Replace test classes with functions.
|
||
|
|
2018.11.6
|
||
|
|
Rename imsave function to imwrite.
|
||
|
|
Readd Python implementations of packints, delta, and bitorder codecs.
|
||
|
|
Fix TiffFrame.compression AttributeError.
|
||
|
|
2018.10.18
|
||
|
|
...
|
||
|
|
|
||
|
|
Refer to the CHANGES file for older revisions.
|
||
|
|
|
||
|
|
Notes
|
||
|
|
-----
|
||
|
|
The API is not stable yet and might change between revisions.
|
||
|
|
|
||
|
|
Tested on little-endian platforms only.
|
||
|
|
|
||
|
|
Python 32-bit versions are deprecated. Python <= 3.6 are no longer supported.
|
||
|
|
|
||
|
|
Tifffile relies on the `imagecodecs <https://pypi.org/project/imagecodecs/>`_
|
||
|
|
package for encoding and decoding LZW, JPEG, and other compressed image
|
||
|
|
segments.
|
||
|
|
|
||
|
|
Several TIFF-like formats do not strictly adhere to the TIFF6 specification,
|
||
|
|
some of which allow file or data sizes to exceed the 4 GB limit:
|
||
|
|
|
||
|
|
* *BigTIFF* is identified by version number 43 and uses different file
|
||
|
|
header, IFD, and tag structures with 64-bit offsets. It adds more data types.
|
||
|
|
Tifffile can read and write BigTIFF files.
|
||
|
|
* *ImageJ* hyperstacks store all image data, which may exceed 4 GB,
|
||
|
|
contiguously after the first IFD. Files > 4 GB contain one IFD only.
|
||
|
|
The size (shape and dtype) of the up to 6-dimensional image data can be
|
||
|
|
determined from the ImageDescription tag of the first IFD, which is Latin-1
|
||
|
|
encoded. Tifffile can read and write ImageJ hyperstacks.
|
||
|
|
* *OME-TIFF* stores up to 8-dimensional data in one or multiple TIFF of BigTIFF
|
||
|
|
files. The 8-bit UTF-8 encoded OME-XML metadata found in the ImageDescription
|
||
|
|
tag of the first IFD defines the position of TIFF IFDs in the high
|
||
|
|
dimensional data. Tifffile can read OME-TIFF files, except when the OME-XML
|
||
|
|
metadata are stored in a separate file. Tifffile can write numpy arrays
|
||
|
|
to single-file, non-pyramidal OME-TIFF.
|
||
|
|
* *LSM* stores all IFDs below 4 GB but wraps around 32-bit StripOffsets.
|
||
|
|
The StripOffsets of each series and position require separate unwrapping.
|
||
|
|
The StripByteCounts tag contains the number of bytes for the uncompressed
|
||
|
|
data. Tifffile can read large LSM files.
|
||
|
|
* *NDPI* uses some 64-bit offsets in the file header, IFD, and tag structures.
|
||
|
|
Tag values/offsets can be corrected using high bits stored after IFD
|
||
|
|
structures. JPEG compressed segments with dimensions >65536 or missing
|
||
|
|
restart markers are not readable with libjpeg. Tifffile can read NDPI
|
||
|
|
files > 4 GB. JPEG segments with restart markers and dimensions >65536 can
|
||
|
|
be decoded with the imagecodecs library on Windows.
|
||
|
|
* *ScanImage* optionally allows corrupt non-BigTIFF files > 2 GB. The values
|
||
|
|
of StripOffsets and StripByteCounts can be recovered using the constant
|
||
|
|
differences of the offsets of IFD and tag values throughout the file.
|
||
|
|
Tifffile can read such files if the image data are stored contiguously in
|
||
|
|
each page.
|
||
|
|
* *GeoTIFF* sparse files allow strip or tile offsets and byte counts to be 0.
|
||
|
|
Such segments are implicitly set to 0 or the NODATA value on reading.
|
||
|
|
Tifffile can read GeoTIFF sparse files.
|
||
|
|
|
||
|
|
Other libraries for reading scientific TIFF files from Python:
|
||
|
|
|
||
|
|
* `Python-bioformats <https://github.com/CellProfiler/python-bioformats>`_
|
||
|
|
* `Imread <https://github.com/luispedro/imread>`_
|
||
|
|
* `GDAL <https://github.com/OSGeo/gdal/tree/master/gdal/swig/python>`_
|
||
|
|
* `OpenSlide-python <https://github.com/openslide/openslide-python>`_
|
||
|
|
* `PyLibTiff <https://github.com/pearu/pylibtiff>`_
|
||
|
|
* `SimpleITK <https://github.com/SimpleITK/SimpleITK>`_
|
||
|
|
* `PyLSM <https://launchpad.net/pylsm>`_
|
||
|
|
* `PyMca.TiffIO.py <https://github.com/vasole/pymca>`_ (same as fabio.TiffIO)
|
||
|
|
* `BioImageXD.Readers <http://www.bioimagexd.net/>`_
|
||
|
|
* `CellCognition <https://cellcognition-project.org/>`_
|
||
|
|
* `pymimage <https://github.com/ardoi/pymimage>`_
|
||
|
|
* `pytiff <https://github.com/FZJ-INM1-BDA/pytiff>`_
|
||
|
|
* `ScanImageTiffReaderPython
|
||
|
|
<https://gitlab.com/vidriotech/scanimagetiffreader-python>`_
|
||
|
|
* `bigtiff <https://pypi.org/project/bigtiff>`_
|
||
|
|
|
||
|
|
Some libraries are using tifffile to write OME-TIFF files:
|
||
|
|
|
||
|
|
* `Zeiss Apeer OME-TIFF library
|
||
|
|
<https://github.com/apeer-micro/apeer-ometiff-library>`_
|
||
|
|
* `Allen Institute for Cell Science imageio
|
||
|
|
<https://pypi.org/project/aicsimageio>`_
|
||
|
|
* `xtiff <https://github.com/BodenmillerGroup/xtiff>`_
|
||
|
|
|
||
|
|
References
|
||
|
|
----------
|
||
|
|
* TIFF 6.0 Specification and Supplements. Adobe Systems Incorporated.
|
||
|
|
https://www.adobe.io/open/standards/TIFF.html
|
||
|
|
* TIFF File Format FAQ. https://www.awaresystems.be/imaging/tiff/faq.html
|
||
|
|
* The BigTIFF File Format.
|
||
|
|
https://www.awaresystems.be/imaging/tiff/bigtiff.html
|
||
|
|
* MetaMorph Stack (STK) Image File Format.
|
||
|
|
http://mdc.custhelp.com/app/answers/detail/a_id/18862
|
||
|
|
* Image File Format Description LSM 5/7 Release 6.0 (ZEN 2010).
|
||
|
|
Carl Zeiss MicroImaging GmbH. BioSciences. May 10, 2011
|
||
|
|
* The OME-TIFF format.
|
||
|
|
https://docs.openmicroscopy.org/ome-model/latest/
|
||
|
|
* UltraQuant(r) Version 6.0 for Windows Start-Up Guide.
|
||
|
|
http://www.ultralum.com/images%20ultralum/pdf/UQStart%20Up%20Guide.pdf
|
||
|
|
* Micro-Manager File Formats.
|
||
|
|
https://micro-manager.org/wiki/Micro-Manager_File_Formats
|
||
|
|
* ScanImage BigTiff Specification - ScanImage 2016.
|
||
|
|
http://scanimage.vidriotechnologies.com/display/SI2016/
|
||
|
|
ScanImage+BigTiff+Specification
|
||
|
|
* ZIF, the Zoomable Image File format. http://zif.photo/
|
||
|
|
* GeoTIFF File Format https://gdal.org/drivers/raster/gtiff.html
|
||
|
|
* Cloud optimized GeoTIFF.
|
||
|
|
https://github.com/cogeotiff/cog-spec/blob/master/spec.md
|
||
|
|
* Tags for TIFF and Related Specifications. Digital Preservation.
|
||
|
|
https://www.loc.gov/preservation/digital/formats/content/tiff_tags.shtml
|
||
|
|
* CIPA DC-008-2016: Exchangeable image file format for digital still cameras:
|
||
|
|
Exif Version 2.31.
|
||
|
|
http://www.cipa.jp/std/documents/e/DC-008-Translation-2016-E.pdf
|
||
|
|
|
||
|
|
Examples
|
||
|
|
--------
|
||
|
|
Save a 3D numpy array to a multi-page, 16-bit grayscale TIFF file:
|
||
|
|
|
||
|
|
>>> data = numpy.random.randint(0, 2**12, (4, 301, 219), 'uint16')
|
||
|
|
>>> imwrite('temp.tif', data, photometric='minisblack')
|
||
|
|
|
||
|
|
Read the whole image stack from the TIFF file as numpy array:
|
||
|
|
|
||
|
|
>>> image_stack = imread('temp.tif')
|
||
|
|
>>> image_stack.shape
|
||
|
|
(4, 301, 219)
|
||
|
|
>>> image_stack.dtype
|
||
|
|
dtype('uint16')
|
||
|
|
|
||
|
|
Read the image from the first page in the TIFF file as numpy array:
|
||
|
|
|
||
|
|
>>> image = imread('temp.tif', key=0)
|
||
|
|
>>> image.shape
|
||
|
|
(301, 219)
|
||
|
|
|
||
|
|
Read images from a sequence of TIFF files as numpy array:
|
||
|
|
|
||
|
|
>>> image_sequence = imread(['temp.tif', 'temp.tif'])
|
||
|
|
>>> image_sequence.shape
|
||
|
|
(2, 4, 301, 219)
|
||
|
|
|
||
|
|
Save a numpy array to a single-page RGB TIFF file:
|
||
|
|
|
||
|
|
>>> data = numpy.random.randint(0, 255, (256, 256, 3), 'uint8')
|
||
|
|
>>> imwrite('temp.tif', data, photometric='rgb')
|
||
|
|
|
||
|
|
Save a floating-point array and metadata, using zlib compression:
|
||
|
|
|
||
|
|
>>> data = numpy.random.rand(2, 5, 3, 301, 219).astype('float32')
|
||
|
|
>>> imwrite('temp.tif', data, compress=6, metadata={'axes': 'TZCYX'})
|
||
|
|
|
||
|
|
Save a volume with xyz voxel size 2.6755x2.6755x3.9474 micron^3 to an ImageJ
|
||
|
|
formatted TIFF file:
|
||
|
|
|
||
|
|
>>> volume = numpy.random.randn(57*256*256).astype('float32')
|
||
|
|
>>> volume.shape = 1, 57, 1, 256, 256, 1 # dimensions in TZCYXS order
|
||
|
|
>>> imwrite('temp.tif', volume, imagej=True, resolution=(1./2.6755, 1./2.6755),
|
||
|
|
... metadata={'spacing': 3.947368, 'unit': 'um'})
|
||
|
|
|
||
|
|
Get the shape and dtype of the volume stored in the TIFF file:
|
||
|
|
|
||
|
|
>>> tif = TiffFile('temp.tif')
|
||
|
|
>>> len(tif.pages) # number of pages in the file
|
||
|
|
57
|
||
|
|
>>> page = tif.pages[0] # get shape and dtype of the image in the first page
|
||
|
|
>>> page.shape
|
||
|
|
(256, 256)
|
||
|
|
>>> page.dtype
|
||
|
|
dtype('float32')
|
||
|
|
>>> page.axes
|
||
|
|
'YX'
|
||
|
|
>>> series = tif.series[0] # get shape and dtype of the first image series
|
||
|
|
>>> series.shape
|
||
|
|
(57, 256, 256)
|
||
|
|
>>> series.dtype
|
||
|
|
dtype('float32')
|
||
|
|
>>> series.axes
|
||
|
|
'ZYX'
|
||
|
|
>>> tif.close()
|
||
|
|
|
||
|
|
Read hyperstack and metadata from the ImageJ file:
|
||
|
|
|
||
|
|
>>> with TiffFile('temp.tif') as tif:
|
||
|
|
... imagej_hyperstack = tif.asarray()
|
||
|
|
... imagej_metadata = tif.imagej_metadata
|
||
|
|
>>> imagej_hyperstack.shape
|
||
|
|
(57, 256, 256)
|
||
|
|
>>> imagej_metadata['slices']
|
||
|
|
57
|
||
|
|
|
||
|
|
Read the "XResolution" tag from the first page in the TIFF file:
|
||
|
|
|
||
|
|
>>> with TiffFile('temp.tif') as tif:
|
||
|
|
... tag = tif.pages[0].tags['XResolution']
|
||
|
|
>>> tag.value
|
||
|
|
(2000, 5351)
|
||
|
|
>>> tag.name
|
||
|
|
'XResolution'
|
||
|
|
>>> tag.code
|
||
|
|
282
|
||
|
|
>>> tag.count
|
||
|
|
1
|
||
|
|
>>> tag.dtype
|
||
|
|
'2I'
|
||
|
|
|
||
|
|
Read images from a selected range of pages:
|
||
|
|
|
||
|
|
>>> image = imread('temp.tif', key=range(4, 40, 2))
|
||
|
|
>>> image.shape
|
||
|
|
(18, 256, 256)
|
||
|
|
|
||
|
|
Create an empty TIFF file and write to the memory-mapped numpy array:
|
||
|
|
|
||
|
|
>>> memmap_image = memmap('temp.tif', shape=(256, 256), dtype='float32')
|
||
|
|
>>> memmap_image[255, 255] = 1.0
|
||
|
|
>>> memmap_image.flush()
|
||
|
|
>>> del memmap_image
|
||
|
|
|
||
|
|
Memory-map image data of the first page in the TIFF file:
|
||
|
|
|
||
|
|
>>> memmap_image = memmap('temp.tif', page=0)
|
||
|
|
>>> memmap_image[255, 255]
|
||
|
|
1.0
|
||
|
|
>>> del memmap_image
|
||
|
|
|
||
|
|
Successively append image series to a BigTIFF file, which can exceed 4 GB:
|
||
|
|
|
||
|
|
>>> data = numpy.random.randint(0, 255, (5, 2, 3, 301, 219), 'uint8')
|
||
|
|
>>> with TiffWriter('temp.tif', bigtiff=True) as tif:
|
||
|
|
... for i in range(data.shape[0]):
|
||
|
|
... tif.save(data[i], compress=6, photometric='minisblack')
|
||
|
|
|
||
|
|
Append an image to the existing TIFF file:
|
||
|
|
|
||
|
|
>>> data = numpy.random.randint(0, 255, (301, 219, 3), 'uint8')
|
||
|
|
>>> imwrite('temp.tif', data, append=True)
|
||
|
|
|
||
|
|
Iterate over pages and tags in the TIFF file and successively read images:
|
||
|
|
|
||
|
|
>>> with TiffFile('temp.tif') as tif:
|
||
|
|
... for page in tif.pages:
|
||
|
|
... for tag in page.tags:
|
||
|
|
... tag_name, tag_value = tag.name, tag.value
|
||
|
|
... image = page.asarray()
|
||
|
|
|
||
|
|
Write two numpy arrays to a multi-series OME-TIFF file:
|
||
|
|
|
||
|
|
>>> data0 = numpy.random.randint(0, 255, (32, 32, 3), 'uint8')
|
||
|
|
>>> data1 = numpy.random.randint(0, 1023, (4, 256, 256), 'uint16')
|
||
|
|
>>> with TiffWriter('temp.ome.tif') as tif:
|
||
|
|
... tif.save(data0, compress=6, photometric='rgb')
|
||
|
|
... tif.save(data1, photometric='minisblack',
|
||
|
|
... metadata={'axes': 'ZYX', 'SignificantBits': 10,
|
||
|
|
... 'Plane': {'PositionZ': [0.0, 1.0, 2.0, 3.0]}})
|
||
|
|
|
||
|
|
Read the second image series from the OME-TIFF file:
|
||
|
|
|
||
|
|
>>> series1 = imread('temp.ome.tif', series=1)
|
||
|
|
>>> series1.shape
|
||
|
|
(4, 256, 256)
|
||
|
|
|
||
|
|
Read an image stack from a series of TIFF files with a file name pattern:
|
||
|
|
|
||
|
|
>>> imwrite('temp_C001T001.tif', numpy.random.rand(64, 64))
|
||
|
|
>>> imwrite('temp_C001T002.tif', numpy.random.rand(64, 64))
|
||
|
|
>>> image_sequence = TiffSequence('temp_C001*.tif', pattern='axes')
|
||
|
|
>>> image_sequence.shape
|
||
|
|
(1, 2)
|
||
|
|
>>> image_sequence.axes
|
||
|
|
'CT'
|
||
|
|
>>> data = image_sequence.asarray()
|
||
|
|
>>> data.shape
|
||
|
|
(1, 2, 64, 64)
|
||
|
|
|
||
|
|
Create a TIFF file from a generator of tiles:
|
||
|
|
|
||
|
|
>>> def tiles():
|
||
|
|
... data = numpy.arange(3*4*16*16, dtype='uint16').reshape((3*4, 16, 16))
|
||
|
|
... for i in range(data.shape[0]): yield data[i]
|
||
|
|
>>> imwrite('temp.tif', tiles(), dtype='uint16', shape=(48, 64), tile=(16, 16))
|
||
|
|
|
||
|
|
Write a tiled, multi-resolution, pyramidal OME-TIFF file using JPEG
|
||
|
|
compression. Sub-resolution images are written to SubIFDs:
|
||
|
|
|
||
|
|
>>> data = numpy.arange(1024*1024*3, dtype='uint8').reshape((1024, 1024, 3))
|
||
|
|
>>> with TiffWriter('temp.ome.tif') as tif:
|
||
|
|
... options = dict(tile=(256, 256), compress='jpeg')
|
||
|
|
... tif.save(data, subifds=2, **options)
|
||
|
|
... # save pyramid levels. In production use resampling to generate levels!
|
||
|
|
... tif.save(data[::2, ::2], subfiletype=1, **options)
|
||
|
|
... tif.save(data[::4, ::4], subfiletype=1, **options)
|
||
|
|
|
||
|
|
Access the image levels in the pyramidal OME-TIFF file:
|
||
|
|
|
||
|
|
>>> baseimage = imread('temp.ome.tif')
|
||
|
|
>>> second_level = imread('temp.ome.tif', series=0, level=1)
|
||
|
|
>>> with TiffFile('temp.ome.tif') as tif:
|
||
|
|
... baseimage = tif.series[0].asarray()
|
||
|
|
... second_level = tif.series[0].levels[1].asarray()
|
||
|
|
|
||
|
|
Iterate over and decode single JPEG compressed tiles in the TIFF file:
|
||
|
|
|
||
|
|
>>> with TiffFile('temp.ome.tif') as tif:
|
||
|
|
... fh = tif.filehandle
|
||
|
|
... for page in tif.pages:
|
||
|
|
... for index, (offset, bytecount) in enumerate(
|
||
|
|
... zip(page.dataoffsets, page.databytecounts)
|
||
|
|
... ):
|
||
|
|
... fh.seek(offset)
|
||
|
|
... data = fh.read(bytecount)
|
||
|
|
... tile, indices, shape = page.decode(data, index,
|
||
|
|
... page.jpegtables)
|
||
|
|
|
||
|
|
|