562 lines
20 KiB
Python
562 lines
20 KiB
Python
# -*- coding: utf-8 -*-
|
|
# imageio is distributed under the terms of the (new) BSD License.
|
|
|
|
""" Read/Write TIFF files.
|
|
|
|
Backend: internal
|
|
|
|
Provides support for a wide range of Tiff images using the tifffile
|
|
backend.
|
|
|
|
Parameters for reading
|
|
----------------------
|
|
offset : int
|
|
Optional start position of embedded file. By default this is
|
|
the current file position.
|
|
size : int
|
|
Optional size of embedded file. By default this is the number
|
|
of bytes from the 'offset' to the end of the file.
|
|
multifile : bool
|
|
If True (default), series may include pages from multiple files.
|
|
Currently applies to OME-TIFF only.
|
|
multifile_close : bool
|
|
If True (default), keep the handles of other files in multifile
|
|
series closed. This is inefficient when few files refer to
|
|
many pages. If False, the C runtime may run out of resources.
|
|
|
|
Parameters for saving
|
|
---------------------
|
|
bigtiff : bool
|
|
If True, the BigTIFF format is used.
|
|
byteorder : {'<', '>'}
|
|
The endianness of the data in the file.
|
|
By default this is the system's native byte order.
|
|
software : str
|
|
Name of the software used to create the image.
|
|
Saved with the first page only.
|
|
|
|
Metadata for reading
|
|
--------------------
|
|
planar_configuration : {'contig', 'planar'}
|
|
Specifies if samples are stored contiguous or in separate planes.
|
|
By default this setting is inferred from the data shape.
|
|
'contig': last dimension contains samples.
|
|
'planar': third last dimension contains samples.
|
|
resolution_unit : int
|
|
The resolution unit stored in the TIFF tag. Usually 1 means no/unknown unit,
|
|
2 means dpi (inch), 3 means dpc (centimeter).
|
|
resolution : (float, float, str)
|
|
A tuple formatted as (X_resolution, Y_resolution, unit). The unit is a
|
|
string representing one of the following units::
|
|
|
|
NONE # No unit or unit unknown
|
|
INCH # dpi
|
|
CENTIMETER # cpi
|
|
MILLIMETER
|
|
MICROMETER
|
|
|
|
compression : int
|
|
Value indicating the compression algorithm used, e.g. 5 is LZW,
|
|
7 is JPEG, 8 is deflate.
|
|
If 1, data are uncompressed.
|
|
predictor : int
|
|
Value 2 indicates horizontal differencing was used before compression,
|
|
while 3 indicates floating point horizontal differencing.
|
|
If 1, no prediction scheme was used before compression.
|
|
orientation : {'top_left', 'bottom_right', ...}
|
|
Oriented of image array.
|
|
is_rgb : bool
|
|
True if page contains a RGB image.
|
|
is_contig : bool
|
|
True if page contains a contiguous image.
|
|
is_tiled : bool
|
|
True if page contains tiled image.
|
|
is_palette : bool
|
|
True if page contains a palette-colored image and not OME or STK.
|
|
is_reduced : bool
|
|
True if page is a reduced image of another image.
|
|
is_shaped : bool
|
|
True if page contains shape in image_description tag.
|
|
is_fluoview : bool
|
|
True if page contains FluoView MM_STAMP tag.
|
|
is_nih : bool
|
|
True if page contains NIH image header.
|
|
is_micromanager : bool
|
|
True if page contains Micro-Manager metadata.
|
|
is_ome : bool
|
|
True if page contains OME-XML in image_description tag.
|
|
is_sgi : bool
|
|
True if page contains SGI image and tile depth tags.
|
|
is_mdgel : bool
|
|
True if page contains md_file_tag tag.
|
|
is_mediacy : bool
|
|
True if page contains Media Cybernetics Id tag.
|
|
is_stk : bool
|
|
True if page contains UIC2Tag tag.
|
|
is_lsm : bool
|
|
True if page contains LSM CZ_LSM_INFO tag.
|
|
description : str
|
|
Image description
|
|
description1 : str
|
|
Additional description
|
|
is_imagej : None or str
|
|
ImageJ metadata
|
|
software : str
|
|
Software used to create the TIFF file
|
|
datetime : datetime.datetime
|
|
Creation date and time
|
|
|
|
Metadata for writing
|
|
--------------------
|
|
photometric : {'minisblack', 'miniswhite', 'rgb'}
|
|
The color space of the image data.
|
|
By default this setting is inferred from the data shape.
|
|
planarconfig : {'contig', 'planar'}
|
|
Specifies if samples are stored contiguous or in separate planes.
|
|
By default this setting is inferred from the data shape.
|
|
'contig': last dimension contains samples.
|
|
'planar': third last dimension contains samples.
|
|
resolution : (float, float) or ((int, int), (int, int))
|
|
X and Y resolution in dots per inch as float or rational numbers.
|
|
description : str
|
|
The subject of the image. Saved with the first page only.
|
|
compress : int
|
|
Values from 0 to 9 controlling the level of zlib (deflate) compression.
|
|
If 0, data are written uncompressed (default).
|
|
compression : str, (int, int)
|
|
Compression scheme used while writing the image. If omitted (default) the
|
|
image is not uncompressed. Compression cannot be used to write contiguous
|
|
series. Compressors may require certain data shapes, types or value ranges.
|
|
For example, JPEG compression requires grayscale or RGB(A), uint8 or 12-bit
|
|
uint16. JPEG compression is experimental. JPEG markers and TIFF tags may not
|
|
match. Only a limited set of compression schemes are implemented. 'ZLIB' is
|
|
short for ADOBE_DEFLATE. The value is written to the Compression tag.
|
|
compressionargs:
|
|
Extra arguments passed to compression codec, e.g., compression level. Refer
|
|
to the Imagecodecs implementation for supported arguments.
|
|
predictor : bool
|
|
If True, horizontal differencing is applied before compression.
|
|
Note that using an int literal 1 actually means no prediction scheme
|
|
will be used.
|
|
volume : bool
|
|
If True, volume data are stored in one tile (if applicable) using
|
|
the SGI image_depth and tile_depth tags.
|
|
Image width and depth must be multiple of 16.
|
|
Few software can read this format, e.g. MeVisLab.
|
|
writeshape : bool
|
|
If True, write the data shape to the image_description tag
|
|
if necessary and no other description is given.
|
|
extratags: sequence of tuples
|
|
Additional tags as [(code, dtype, count, value, writeonce)].
|
|
|
|
code : int
|
|
The TIFF tag Id.
|
|
dtype : str
|
|
Data type of items in 'value' in Python struct format.
|
|
One of B, s, H, I, 2I, b, h, i, f, d, Q, or q.
|
|
count : int
|
|
Number of data values. Not used for string values.
|
|
value : sequence
|
|
'Count' values compatible with 'dtype'.
|
|
writeonce : bool
|
|
If True, the tag is written to the first page only.
|
|
|
|
Notes
|
|
-----
|
|
Global metadata is stored with the first frame in a TIFF file.
|
|
Thus calling :py:meth:`Format.Writer.set_meta_data` after the first frame
|
|
was written has no effect. Also, global metadata is ignored if metadata is
|
|
provided via the `meta` argument of :py:meth:`Format.Writer.append_data`.
|
|
|
|
If you have installed tifffile as a Python package, imageio will attempt
|
|
to use that as backend instead of the bundled backend. Doing so can
|
|
provide access to new performance improvements and bug fixes.
|
|
|
|
"""
|
|
|
|
import datetime
|
|
|
|
from ..core import Format
|
|
from ..core.request import URI_BYTES, URI_FILE
|
|
|
|
import numpy as np
|
|
import warnings
|
|
|
|
|
|
try:
|
|
import tifffile as _tifffile
|
|
except ImportError:
|
|
warnings.warn(
|
|
"ImageIO's vendored tifffile backend is deprecated and will be"
|
|
" removed in ImageIO v3. Install the tifffile directly:"
|
|
" `pip install imageio[tifffile]`",
|
|
DeprecationWarning,
|
|
)
|
|
from . import _tifffile
|
|
|
|
|
|
TIFF_FORMATS = (".tif", ".tiff", ".stk", ".lsm")
|
|
WRITE_METADATA_KEYS = (
|
|
"photometric",
|
|
"planarconfig",
|
|
"resolution",
|
|
"description",
|
|
"compress",
|
|
"compression",
|
|
"compressionargs",
|
|
"predictor",
|
|
"volume",
|
|
"writeshape",
|
|
"extratags",
|
|
"datetime",
|
|
)
|
|
READ_METADATA_KEYS = (
|
|
"planar_configuration",
|
|
"is_fluoview",
|
|
"is_nih",
|
|
"is_contig",
|
|
"is_micromanager",
|
|
"is_ome",
|
|
"is_lsm",
|
|
"is_palette",
|
|
"is_reduced",
|
|
"is_rgb",
|
|
"is_sgi",
|
|
"is_shaped",
|
|
"is_stk",
|
|
"is_tiled",
|
|
"is_mdgel",
|
|
"resolution_unit",
|
|
"compression",
|
|
"predictor",
|
|
"is_mediacy",
|
|
"orientation",
|
|
"description",
|
|
"description1",
|
|
"is_imagej",
|
|
"software",
|
|
)
|
|
|
|
|
|
class TiffFormat(Format):
|
|
"""Provides support for a wide range of Tiff images using the tifffile
|
|
backend.
|
|
|
|
Images that contain multiple pages can be read using ``imageio.mimread()``
|
|
to read the individual pages, or ``imageio.volread()`` to obtain a
|
|
single (higher dimensional) array.
|
|
|
|
Note that global metadata is stored with the first frame in a TIFF file.
|
|
Thus calling :py:meth:`Format.Writer.set_meta_data` after the first frame
|
|
was written has no effect. Also, global metadata is ignored if metadata is
|
|
provided via the `meta` argument of :py:meth:`Format.Writer.append_data`.
|
|
|
|
If you have installed tifffile as a Python package, imageio will attempt
|
|
to use that as backend instead of the bundled backend. Doing so can
|
|
provide access to new performance improvements and bug fixes.
|
|
|
|
Parameters for reading
|
|
----------------------
|
|
offset : int
|
|
Optional start position of embedded file. By default this is
|
|
the current file position.
|
|
size : int
|
|
Optional size of embedded file. By default this is the number
|
|
of bytes from the 'offset' to the end of the file.
|
|
multifile : bool
|
|
If True (default), series may include pages from multiple files.
|
|
Currently applies to OME-TIFF only.
|
|
multifile_close : bool
|
|
If True (default), keep the handles of other files in multifile
|
|
series closed. This is inefficient when few files refer to
|
|
many pages. If False, the C runtime may run out of resources.
|
|
|
|
Parameters for saving
|
|
---------------------
|
|
bigtiff : bool
|
|
If True, the BigTIFF format is used.
|
|
byteorder : {'<', '>'}
|
|
The endianness of the data in the file.
|
|
By default this is the system's native byte order.
|
|
software : str
|
|
Name of the software used to create the image.
|
|
Saved with the first page only.
|
|
|
|
Metadata for reading
|
|
--------------------
|
|
planar_configuration : {'contig', 'planar'}
|
|
Specifies if samples are stored contiguous or in separate planes.
|
|
By default this setting is inferred from the data shape.
|
|
'contig': last dimension contains samples.
|
|
'planar': third last dimension contains samples.
|
|
resolution_unit : (float, float) or ((int, int), (int, int))
|
|
X and Y resolution in dots per inch as float or rational numbers.
|
|
compression : int
|
|
Value indicating the compression algorithm used, e.g. 5 is LZW,
|
|
7 is JPEG, 8 is deflate.
|
|
If 1, data are uncompressed.
|
|
predictor : int
|
|
Value 2 indicates horizontal differencing was used before compression,
|
|
while 3 indicates floating point horizontal differencing.
|
|
If 1, no prediction scheme was used before compression.
|
|
orientation : {'top_left', 'bottom_right', ...}
|
|
Oriented of image array.
|
|
is_rgb : bool
|
|
True if page contains a RGB image.
|
|
is_contig : bool
|
|
True if page contains a contiguous image.
|
|
is_tiled : bool
|
|
True if page contains tiled image.
|
|
is_palette : bool
|
|
True if page contains a palette-colored image and not OME or STK.
|
|
is_reduced : bool
|
|
True if page is a reduced image of another image.
|
|
is_shaped : bool
|
|
True if page contains shape in image_description tag.
|
|
is_fluoview : bool
|
|
True if page contains FluoView MM_STAMP tag.
|
|
is_nih : bool
|
|
True if page contains NIH image header.
|
|
is_micromanager : bool
|
|
True if page contains Micro-Manager metadata.
|
|
is_ome : bool
|
|
True if page contains OME-XML in image_description tag.
|
|
is_sgi : bool
|
|
True if page contains SGI image and tile depth tags.
|
|
is_stk : bool
|
|
True if page contains UIC2Tag tag.
|
|
is_mdgel : bool
|
|
True if page contains md_file_tag tag.
|
|
is_mediacy : bool
|
|
True if page contains Media Cybernetics Id tag.
|
|
is_stk : bool
|
|
True if page contains UIC2Tag tag.
|
|
is_lsm : bool
|
|
True if page contains LSM CZ_LSM_INFO tag.
|
|
description : str
|
|
Image description
|
|
description1 : str
|
|
Additional description
|
|
is_imagej : None or str
|
|
ImageJ metadata
|
|
software : str
|
|
Software used to create the TIFF file
|
|
datetime : datetime.datetime
|
|
Creation date and time
|
|
|
|
Metadata for writing
|
|
--------------------
|
|
photometric : {'minisblack', 'miniswhite', 'rgb'}
|
|
The color space of the image data.
|
|
By default this setting is inferred from the data shape.
|
|
planarconfig : {'contig', 'planar'}
|
|
Specifies if samples are stored contiguous or in separate planes.
|
|
By default this setting is inferred from the data shape.
|
|
'contig': last dimension contains samples.
|
|
'planar': third last dimension contains samples.
|
|
resolution : (float, float) or ((int, int), (int, int))
|
|
X and Y resolution in dots per inch as float or rational numbers.
|
|
description : str
|
|
The subject of the image. Saved with the first page only.
|
|
compress : int
|
|
Values from 0 to 9 controlling the level of zlib (deflate) compression.
|
|
If 0, data are written uncompressed (default).
|
|
predictor : bool
|
|
If True, horizontal differencing is applied before compression.
|
|
Note that using an int literal 1 actually means no prediction scheme
|
|
will be used.
|
|
volume : bool
|
|
If True, volume data are stored in one tile (if applicable) using
|
|
the SGI image_depth and tile_depth tags.
|
|
Image width and depth must be multiple of 16.
|
|
Few software can read this format, e.g. MeVisLab.
|
|
writeshape : bool
|
|
If True, write the data shape to the image_description tag
|
|
if necessary and no other description is given.
|
|
extratags: sequence of tuples
|
|
Additional tags as [(code, dtype, count, value, writeonce)].
|
|
|
|
code : int
|
|
The TIFF tag Id.
|
|
dtype : str
|
|
Data type of items in 'value' in Python struct format.
|
|
One of B, s, H, I, 2I, b, h, i, f, d, Q, or q.
|
|
count : int
|
|
Number of data values. Not used for string values.
|
|
value : sequence
|
|
'Count' values compatible with 'dtype'.
|
|
writeonce : bool
|
|
If True, the tag is written to the first page only.
|
|
"""
|
|
|
|
def _can_read(self, request):
|
|
try:
|
|
_tifffile.TiffFile(request.get_file(), **request.kwargs)
|
|
except ValueError:
|
|
# vendored backend raises value exception
|
|
return False
|
|
except _tifffile.TiffFileError: # pragma: no-cover
|
|
# current version raises custom exception
|
|
return False
|
|
finally:
|
|
request.get_file().seek(0)
|
|
|
|
return True
|
|
|
|
def _can_write(self, request):
|
|
if request._uri_type in [URI_FILE, URI_BYTES]:
|
|
pass # special URI
|
|
elif request.extension not in self.extensions:
|
|
return False
|
|
|
|
try:
|
|
_tifffile.TiffWriter(request.get_file(), **request.kwargs)
|
|
except ValueError:
|
|
# vendored backend raises value exception
|
|
return False
|
|
except _tifffile.TiffFileError: # pragma: no-cover
|
|
# current version raises custom exception
|
|
return False
|
|
finally:
|
|
request.get_file().seek(0)
|
|
return True
|
|
|
|
# -- reader
|
|
|
|
class Reader(Format.Reader):
|
|
def _open(self, **kwargs):
|
|
# Allow loading from http; tifffile uses seek, so download first
|
|
if self.request.filename.startswith(("http://", "https://")):
|
|
self._f = f = open(self.request.get_local_filename(), "rb")
|
|
else:
|
|
self._f = None
|
|
f = self.request.get_file()
|
|
self._tf = _tifffile.TiffFile(f, **kwargs)
|
|
|
|
def _close(self):
|
|
self._tf.close()
|
|
if self._f is not None:
|
|
self._f.close()
|
|
|
|
def _get_length(self):
|
|
return len(self._tf.series)
|
|
|
|
def _get_data(self, index):
|
|
if index < 0 or index >= self._get_length():
|
|
raise IndexError("Index out of range while reading from tiff file")
|
|
|
|
im = self._tf.asarray(series=index)
|
|
meta = self._get_meta_data(index)
|
|
|
|
return im, meta
|
|
|
|
def _get_meta_data(self, index):
|
|
meta = {}
|
|
page = self._tf.pages[index or 0]
|
|
for key in READ_METADATA_KEYS:
|
|
try:
|
|
meta[key] = getattr(page, key)
|
|
except Exception:
|
|
pass
|
|
|
|
# tifffile <= 0.12.1 use datetime, newer use DateTime
|
|
for key in ("datetime", "DateTime"):
|
|
try:
|
|
meta["datetime"] = datetime.datetime.strptime(
|
|
page.tags[key].value, "%Y:%m:%d %H:%M:%S"
|
|
)
|
|
break
|
|
except Exception:
|
|
pass
|
|
|
|
if 296 in page.tags:
|
|
meta["resolution_unit"] = page.tags[296].value.value
|
|
|
|
if 282 in page.tags and 283 in page.tags and 296 in page.tags:
|
|
resolution_x = page.tags[282].value
|
|
resolution_y = page.tags[283].value
|
|
if resolution_x[1] == 0 or resolution_y[1] == 0:
|
|
warnings.warn(
|
|
"Ignoring resolution metadata, "
|
|
"because at least one direction has a 0 denominator.",
|
|
RuntimeWarning,
|
|
)
|
|
else:
|
|
meta["resolution"] = (
|
|
resolution_x[0] / resolution_x[1],
|
|
resolution_y[0] / resolution_y[1],
|
|
page.tags[296].value.name,
|
|
)
|
|
|
|
return meta
|
|
|
|
# -- writer
|
|
class Writer(Format.Writer):
|
|
def _open(self, bigtiff=None, byteorder=None, software=None):
|
|
try:
|
|
self._tf = _tifffile.TiffWriter(
|
|
self.request.get_file(),
|
|
bigtiff=bigtiff,
|
|
byteorder=byteorder,
|
|
software=software,
|
|
)
|
|
self._software = None
|
|
except TypeError:
|
|
# In tifffile >= 0.15, the `software` arg is passed to
|
|
# TiffWriter.save
|
|
self._tf = _tifffile.TiffWriter(
|
|
self.request.get_file(), bigtiff=bigtiff, byteorder=byteorder
|
|
)
|
|
self._software = software
|
|
|
|
self._meta = {}
|
|
self._frames_written = 0
|
|
|
|
def _close(self):
|
|
self._tf.close()
|
|
|
|
def _append_data(self, im, meta):
|
|
if meta is not None:
|
|
meta = self._sanitize_meta(meta)
|
|
else:
|
|
# Use global metadata for first frame
|
|
meta = self._meta if self._frames_written == 0 else {}
|
|
if self._software is not None and self._frames_written == 0:
|
|
meta["software"] = self._software
|
|
# No need to check self.request.mode; tifffile figures out whether
|
|
# this is a single page, or all page data at once.
|
|
try:
|
|
# TiffWriter.save has been deprecated in version 2020.9.30
|
|
write_meth = self._tf.write
|
|
except AttributeError:
|
|
write_meth = self._tf.save
|
|
write_meth(np.asanyarray(im), contiguous=False, **meta)
|
|
self._frames_written += 1
|
|
|
|
@staticmethod
|
|
def _sanitize_meta(meta):
|
|
ret = {}
|
|
for key, value in meta.items():
|
|
if key in WRITE_METADATA_KEYS:
|
|
# Special case of previously read `predictor` int value
|
|
# 1(=NONE) translation to False expected by TiffWriter.save
|
|
if key == "predictor" and not isinstance(value, bool):
|
|
ret[key] = value > 1
|
|
elif key == "compress" and value != 0:
|
|
warnings.warn(
|
|
"The use of `compress` is deprecated. Use `compression` and `compressionargs` instead.",
|
|
DeprecationWarning,
|
|
)
|
|
|
|
if _tifffile.__version__ < "2022":
|
|
ret["compression"] = (8, value)
|
|
else:
|
|
ret["compression"] = "zlib"
|
|
ret["compressionargs"] = {"level": value}
|
|
else:
|
|
ret[key] = value
|
|
return ret
|
|
|
|
def set_meta_data(self, meta):
|
|
self._meta = self._sanitize_meta(meta)
|