# -*- coding: utf-8 -*-
# tifffile.py

# Copyright (c) 2008-2019, Christoph Gohlke
# Copyright (c) 2008-2019, The Regents of the University of California
# Produced at the Laboratory for Fluorescence Dynamics
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice,
#   this list of conditions and the following disclaimer.
#
# * Redistributions in binary form must reproduce the above copyright notice,
#   this list of conditions and the following disclaimer in the documentation
#   and/or other materials provided with the distribution.
#
# * Neither the name of the copyright holder nor the names of its
#   contributors may be used to endorse or promote products derived from
#   this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.

"""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, QPI, NDPI, and GeoTIFF files.

Numpy arrays can be written to TIFF, BigTIFF, and ImageJ hyperstack compatible
files in multi-page, memory-mappable, tiled, predicted, or compressed form.

Only a subset of the TIFF specification is supported, mainly uncompressed and
losslessly compressed 1, 8, 16, 32 and 64-bit integer, 16, 32 and 64-bit float,
grayscale and RGB(A) images.
Specifically, reading slices of image data, CCITT and OJPEG compression,
chroma subsampling without JPEG compression, 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 greater than 4 GB.
STK, LSM, FluoView, SGI, SEQ, GEL, and OME-TIFF, are custom extensions
defined by Molecular Devices (Universal Imaging Corporation), Carl Zeiss
MicroImaging, Olympus, Silicon Graphics International, Media Cybernetics,
Molecular Dynamics, 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: 3-clause BSD

:Version: 2019.7.26

Requirements
------------
This release has been tested with the following requirements and dependencies
(other versions may work):

* `CPython 2.7.16, 3.5.4, 3.6.8, 3.7.4, 64-bit <https://www.python.org>`_
* `Numpy 1.16.4 <https://www.numpy.org>`_
* `Imagecodecs 2019.5.22 <https://pypi.org/project/imagecodecs/>`_
  (optional; used for encoding and decoding LZW, JPEG, etc.)
* `Matplotlib 3.1 <https://www.matplotlib.org>`_ (optional; used for plotting)
* Python 2.7 requires 'futures', 'enum34', and 'pathlib'.

Revisions
---------
2019.7.26
    Pass 2869 tests.
    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 JPEG2000 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 page 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
    Rename tiffile package to tifffile.
2018.10.10
    Read ZIF, the Zoomable Image Format (WIP).
    Decode YCbCr JPEG as RGB (tentative).
    Improve restoration of incomplete tiles.
    Allow to write grayscale with extrasamples without specifying planarconfig.
    Enable decoding of PNG and JXR via imagecodecs.
    Deprecate 32-bit platforms (too many memory errors during tests).
2018.9.27
    Read Olympus SIS (WIP).
    Allow to write non-BigTIFF files up to ~4 GB (fix).
    Fix parsing date and time fields in SEM metadata.
    Detect some circular IFD references.
    Enable WebP codecs via imagecodecs.
    Add option to read TiffSequence from ZIP containers.
    Remove TiffFile.isnative.
    Move TIFF struct format constants out of TiffFile namespace.
2018.8.31
    Fix wrong TiffTag.valueoffset.
    Towards reading Hamamatsu NDPI (WIP).
    Enable PackBits compression of byte and bool arrays.
    Fix parsing NULL terminated CZ_SEM strings.
2018.8.24
    Move tifffile.py and related modules into tiffile package.
    Move usage examples to module docstring.
    Enable multi-threading for compressed tiles and pages by default.
    Add option to concurrently decode image tiles using threads.
    Do not skip empty tiles (fix).
    Read JPEG and J2K compressed strips and tiles.
    Allow floating-point predictor on write.
    Add option to specify subfiletype on write.
    Depend on imagecodecs package instead of _tifffile, lzma, etc modules.
    Remove reverse_bitorder, unpack_ints, and decode functions.
    Use pytest instead of unittest.
2018.6.20
    Save RGBA with unassociated extrasample by default (breaking).
    Add option to specify ExtraSamples values.
2018.6.17 (included with 0.15.1)
    Towards reading JPEG and other compressions via imagecodecs package (WIP).
    Read SampleFormat VOID as UINT.
    Add function to validate TIFF using 'jhove -m TIFF-hul'.
    Save bool arrays as bilevel TIFF.
    Accept pathlib.Path as filenames.
    Move 'software' argument from TiffWriter __init__ to save.
    Raise DOS limit to 16 TB.
    Lazy load LZMA and ZSTD compressors and decompressors.
    Add option to save IJMetadata tags.
    Return correct number of pages for truncated series (fix).
    Move EXIF tags to TIFF.TAG as per TIFF/EP standard.
2018.2.18
    Always save RowsPerStrip and Resolution tags as required by TIFF standard.
    Do not use badly typed ImageDescription.
    Coherce bad ASCII string tags to bytes.
    Tuning of __str__ functions.
    Fix reading 'undefined' tag values.
    Read and write ZSTD compressed data.
    Use hexdump to print byte strings.
    Determine TIFF byte order from data dtype in imsave.
    Add option to specify RowsPerStrip for compressed strips.
    Allow memory-map of arrays with non-native byte order.
    Attempt to handle ScanImage <= 5.1 files.
    Restore TiffPageSeries.pages sequence interface.
    Use numpy.frombuffer instead of fromstring to read from binary data.
    Parse GeoTIFF metadata.
    Add option to apply horizontal differencing before compression.
    Towards reading PerkinElmer QPI (QPTIFF, no test files).
    Do not index out of bounds data in tifffile.c unpackbits and decodelzw.
2017.9.29
    Many backward incompatible changes improving speed and resource usage:
    Add detail argument to __str__ function. Remove info functions.
    Fix potential issue correcting offsets of large LSM files with positions.
    Remove TiffFile sequence interface; use TiffFile.pages instead.
    Do not make tag values available as TiffPage attributes.
    Use str (not bytes) type for tag and metadata strings (WIP).
    Use documented standard tag and value names (WIP).
    Use enums for some documented TIFF tag values.
    Remove 'memmap' and 'tmpfile' options; use out='memmap' instead.
    Add option to specify output in asarray functions.
    Add option to concurrently decode pages using threads.
    Add TiffPage.asrgb function (WIP).
    Do not apply colormap in asarray.
    Remove 'colormapped', 'rgbonly', and 'scale_mdgel' options from asarray.
    Consolidate metadata in TiffFile _metadata functions.
    Remove non-tag metadata properties from TiffPage.
    Add function to convert LSM to tiled BIN files.
    Align image data in file.
    Make TiffPage.dtype a numpy.dtype.
    Add 'ndim' and 'size' properties to TiffPage and TiffPageSeries.
    Allow imsave to write non-BigTIFF files up to ~4 GB.
    Only read one page for shaped series if possible.
    Add memmap function to create memory-mapped array stored in TIFF file.
    Add option to save empty arrays to TIFF files.
    Add option to save truncated TIFF files.
    Allow single tile images to be saved contiguously.
    Add optional movie mode for files with uniform pages.
    Lazy load pages.
    Use lightweight TiffFrame for IFDs sharing properties with key TiffPage.
    Move module constants to 'TIFF' namespace (speed up module import).
    Remove 'fastij' option from TiffFile.
    Remove 'pages' parameter from TiffFile.
    Remove TIFFfile alias.
    Deprecate Python 2.
    Require enum34 and futures packages on Python 2.7.
    Remove Record class and return all metadata as dict instead.
    Add functions to parse STK, MetaSeries, ScanImage, SVS, Pilatus metadata.
    Read tags from EXIF and GPS IFDs.
    Use pformat for tag and metadata values.
    Fix reading some UIC tags.
    Do not modify input array in imshow (fix).
    Fix Python implementation of unpack_ints.
2017.5.23
    Write correct number of SampleFormat values (fix).
    Use Adobe deflate code to write ZIP compressed files.
    Add option to pass tag values as packed binary data for writing.
    Defer tag validation to attribute access.
    Use property instead of lazyattr decorator for simple expressions.
2017.3.17
    Write IFDs and tag values on word boundaries.
    Read ScanImage metadata.
    Remove is_rgb and is_indexed attributes from TiffFile.
    Create files used by doctests.
2017.1.12 (included with scikit-image 0.14.x)
    Read Zeiss SEM metadata.
    Read OME-TIFF with invalid references to external files.
    Rewrite C LZW decoder (5x faster).
    Read corrupted LSM files missing EOI code in LZW stream.
2017.1.1
    ...

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 2.7 and 32-bit versions are deprecated.

Tifffile relies on the `imagecodecs <https://pypi.org/project/imagecodecs/>`_
package for encoding and decoding LZW, JPEG, and other compressed images.
The `imagecodecs-lite <https://pypi.org/project/imagecodecs-lite/>`_ package,
which is easier to build, can be used for decoding LZW compressed images
instead.

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 is stored in a separate file.
* *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
  and might require correcting 32-bit offsets found in tags.
  JPEG compressed tiles with dimensions > 65536 are not readable with libjpeg.
  Tifffile can read NDPI files < 4 GB and decompress large JPEG tiles using
  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 on Python 3 if the image data is 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>`_

References
----------
1)  TIFF 6.0 Specification and Supplements. Adobe Systems Incorporated.
    https://www.adobe.io/open/standards/TIFF.html
2)  TIFF File Format FAQ. https://www.awaresystems.be/imaging/tiff/faq.html
3)  MetaMorph Stack (STK) Image File Format.
    http://mdc.custhelp.com/app/answers/detail/a_id/18862
4)  Image File Format Description LSM 5/7 Release 6.0 (ZEN 2010).
    Carl Zeiss MicroImaging GmbH. BioSciences. May 10, 2011
5)  The OME-TIFF format.
    https://docs.openmicroscopy.org/ome-model/5.6.4/ome-tiff/
6)  UltraQuant(r) Version 6.0 for Windows Start-Up Guide.
    http://www.ultralum.com/images%20ultralum/pdf/UQStart%20Up%20Guide.pdf
7)  Micro-Manager File Formats.
    https://micro-manager.org/wiki/Micro-Manager_File_Formats
8)  Tags for TIFF and Related Specifications. Digital Preservation.
    https://www.loc.gov/preservation/digital/formats/content/tiff_tags.shtml
9)  ScanImage BigTiff Specification - ScanImage 2016.
    http://scanimage.vidriotechnologies.com/display/SI2016/
    ScanImage+BigTiff+Specification
10) 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
11) ZIF, the Zoomable Image File format. http://zif.photo/
12) GeoTIFF File Format https://www.gdal.org/frmt_gtiff.html

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 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 ┬Ám^3 to an ImageJ 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 images 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'
>>> tag.valueoffset
360

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()
>>> memmap_image.shape, memmap_image.dtype
((256, 256), dtype('float32'))
>>> 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 images 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')

Iterate over pages and tags in the TIFF file and successively read images:

>>> with TiffFile('temp.tif') as tif:
...     image_stack = tif.asarray()
...     for page in tif.pages:
...         for tag in page.tags.values():
...             tag_name, tag_value = tag.name, tag.value
...         image = page.asarray()

Save two image series to a TIFF file:

>>> data0 = numpy.random.randint(0, 255, (301, 219, 3), 'uint8')
>>> data1 = numpy.random.randint(0, 255, (5, 301, 219), 'uint16')
>>> with TiffWriter('temp.tif') as tif:
...     tif.save(data0, compress=6, photometric='rgb')
...     tif.save(data1, compress=6, photometric='minisblack', contiguous=False)

Read the second image series from the TIFF file:

>>> series1 = imread('temp.tif', series=1)
>>> series1.shape
(5, 301, 219)

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)

"""

from __future__ import division, print_function

__version__ = '2019.7.26'
__docformat__ = 'restructuredtext en'
__all__ = (
    'imwrite',
    'imread',
    'imshow',
    'memmap',
    'lsm2bin',
    'TiffFile',
    'TiffFileError',
    'TiffSequence',
    'TiffWriter',
    'TiffPage',
    'TiffPageSeries',
    'TiffFrame',
    'TiffTag',
    'TIFF',
    # utility classes and functions used by oiffile, czifile, etc
    'FileHandle',
    'FileSequence',
    'Timer',
    'lazyattr',
    'natural_sorted',
    'stripnull',
    'transpose_axes',
    'squeeze_axes',
    'create_output',
    'repeat_nd',
    'format_size',
    'astype',
    'product',
    'xml2dict',
    'pformat',
    'str2bytes',
    'nullfunc',
    'update_kwargs',
    'parse_kwargs',
    'askopenfilename',
    '_app_show',
    # deprecated
    'imsave',
    'decode_lzw',
    'decodelzw',
)

import sys
import os
import io
import re
import glob
import math
import time
import json
import enum
import struct
import pathlib
import warnings
import binascii
import datetime
import threading
import collections

try:
    from collections.abc import Iterable
except ImportError:
    from collections import Iterable

from concurrent.futures import ThreadPoolExecutor

import numpy

try:
    import imagecodecs
except ImportError:
    import zlib

    try:
        import imagecodecs_lite as imagecodecs
    except ImportError:
        imagecodecs = None

# delay import of mmap, pprint, fractions, xml, lxml, matplotlib, tkinter,
#   logging, subprocess, multiprocessing, tempfile, zipfile, fnmatch


def imread(files, **kwargs):
    """Return image data from TIFF file(s) as numpy array.

    Refer to the TiffFile and TiffSequence classes and their asarray
    functions for documentation.

    Parameters
    ----------
    files : str, binary stream, or sequence
        File name, seekable binary stream, glob pattern, or sequence of
        file names.
    kwargs : dict
        Parameters 'name', 'offset', 'size', 'multifile', and 'is_ome'
        are passed to the TiffFile constructor.
        The 'pattern' and 'ioworkers' parameters are passed to the
        TiffSequence constructor.
        Other parameters are passed to the asarray functions.
        The first image series in the file is returned if no arguments are
        provided.

    """
    kwargs_file = parse_kwargs(
        kwargs,
        'is_ome',
        'multifile',
        '_useframes',
        'name',
        'offset',
        'size',
        # legacy
        'multifile_close',
        'fastij',
        'movie',
    )
    kwargs_seq = parse_kwargs(kwargs, 'pattern', 'ioworkers')

    if kwargs.get('pages', None) is not None:
        if kwargs.get('key', None) is not None:
            raise TypeError(
                "the 'pages' and 'key' arguments cannot be used together")
        log_warning("imread: the 'pages' argument is deprecated")
        kwargs['key'] = kwargs.pop('pages')

    if isinstance(files, basestring) and any(i in files for i in '?*'):
        files = glob.glob(files)
    if not files:
        raise ValueError('no files found')
    if not hasattr(files, 'seek') and len(files) == 1:
        files = files[0]

    if isinstance(files, basestring) or hasattr(files, 'seek'):
        with TiffFile(files, **kwargs_file) as tif:
            return tif.asarray(**kwargs)
    else:
        with TiffSequence(files, **kwargs_seq) as imseq:
            return imseq.asarray(**kwargs)


def imwrite(file, data=None, shape=None, dtype=None, **kwargs):
    """Write numpy array to TIFF file.

    Refer to the TiffWriter class and its asarray function for documentation.

    A BigTIFF file is created if the data size in bytes is larger than 4 GB
    minus 32 MB (for metadata), and 'bigtiff' is not specified, and 'imagej'
    or 'truncate' are not enabled.

    Parameters
    ----------
    file : str or binary stream
        File name or writable binary stream, such as an open file or BytesIO.
    data : array_like
        Input image. The last dimensions are assumed to be image depth,
        height, width, and samples.
        If None, an empty array of the specified shape and dtype is
        saved to file.
        Unless 'byteorder' is specified in 'kwargs', the TIFF file byte order
        is determined from the data's dtype or the dtype argument.
    shape : tuple
        If 'data' is None, shape of an empty array to save to the file.
    dtype : numpy.dtype
        If 'data' is None, datatype of an empty array to save to the file.
    kwargs : dict
        Parameters 'append', 'byteorder', 'bigtiff', and 'imagej', are passed
        to the TiffWriter constructor. Other parameters are passed to the
        TiffWriter.save function.

    Returns
    -------
    offset, bytecount : tuple or None
        If the image data are written contiguously, return offset and bytecount
        of image data in the file.

    """
    tifargs = parse_kwargs(kwargs, 'append', 'bigtiff', 'byteorder', 'imagej')
    if data is None:
        dtype = numpy.dtype(dtype)
        size = product(shape) * dtype.itemsize
        byteorder = dtype.byteorder
    else:
        try:
            size = data.nbytes
            byteorder = data.dtype.byteorder
        except Exception:
            size = 0
            byteorder = None
    bigsize = kwargs.pop('bigsize', 2**32 - 2**25)
    if (
        'bigtiff' not in tifargs
        and size > bigsize
        and not (
            tifargs.get('imagej', False) or tifargs.get('truncate', False)
        )
    ):
        tifargs['bigtiff'] = True
    if 'byteorder' not in tifargs:
        tifargs['byteorder'] = byteorder

    with TiffWriter(file, **tifargs) as tif:
        return tif.save(data, shape, dtype, **kwargs)


def memmap(filename, shape=None, dtype=None, page=None, series=0, mode='r+',
           **kwargs):
    """Return memory-mapped numpy array stored in TIFF file.

    Memory-mapping requires data stored in native byte order, without tiling,
    compression, predictors, etc.
    If 'shape' and 'dtype' are provided, existing files will be overwritten or
    appended to depending on the 'append' parameter.
    Otherwise the image data of a specified page or series in an existing
    file will be memory-mapped. By default, the image data of the first page
    series is memory-mapped.
    Call flush() to write any changes in the array to the file.
    Raise ValueError if the image data in the file is not memory-mappable.

    Parameters
    ----------
    filename : str
        Name of the TIFF file which stores the array.
    shape : tuple
        Shape of the empty array.
    dtype : numpy.dtype
        Datatype of the empty array.
    page : int
        Index of the page which image data to memory-map.
    series : int
        Index of the page series which image data to memory-map.
    mode : {'r+', 'r', 'c'}
        The file open mode. Default is to open existing file for reading and
        writing ('r+').
    kwargs : dict
        Additional parameters passed to imwrite() or TiffFile().

    """
    if shape is not None and dtype is not None:
        # create a new, empty array
        kwargs.update(
            data=None,
            shape=shape,
            dtype=dtype,
            returnoffset=True,
            align=TIFF.ALLOCATIONGRANULARITY
        )
        result = imwrite(filename, **kwargs)
        if result is None:
            # TODO: fail before creating file or writing data
            raise ValueError('image data are not memory-mappable')
        offset = result[0]
    else:
        # use existing file
        with TiffFile(filename, **kwargs) as tif:
            if page is not None:
                page = tif.pages[page]
                if not page.is_memmappable:
                    raise ValueError('image data are not memory-mappable')
                offset, _ = page.is_contiguous
                shape = page.shape
                dtype = page.dtype
            else:
                series = tif.series[series]
                if series.offset is None:
                    raise ValueError('image data are not memory-mappable')
                shape = series.shape
                dtype = series.dtype
                offset = series.offset
            dtype = tif.byteorder + dtype.char
    return numpy.memmap(filename, dtype, mode, offset, shape, 'C')


class lazyattr(object):
    """Attribute whose value is computed on first access."""

    # TODO: help() doesn't work
    __slots__ = ('func',)

    def __init__(self, func):
        self.func = func
        # self.__name__ = func.__name__
        # self.__doc__ = func.__doc__
        # self.lock = threading.RLock()

    def __get__(self, instance, owner):
        # with self.lock:
        if instance is None:
            return self
        try:
            value = self.func(instance)
        except AttributeError as exc:
            raise RuntimeError(exc)
        if value is NotImplemented:
            return getattr(super(owner, instance), self.func.__name__)
        setattr(instance, self.func.__name__, value)
        return value


class TiffFileError(Exception):
    """Exception to indicate invalid TIFF structure."""


class TiffWriter(object):
    """Write numpy arrays to TIFF file.

    TiffWriter instances must be closed using the 'close' method, which is
    automatically called when using the 'with' context manager.

    TiffWriter instances are not thread-safe.

    TiffWriter's main purpose is saving nD numpy array's as TIFF,
    not to create any possible TIFF format. Specifically, SubIFDs, ExifIFD,
    and GPSIFD tags are not supported.

    """

    def __init__(self, file, bigtiff=False, byteorder=None, append=False,
                 imagej=False):
        """Open a TIFF file for writing.

        An empty TIFF file is created if the file does not exist, else the
        file is overwritten with an empty TIFF file unless 'append'
        is true. Use 'bigtiff=True' when creating files larger than 4 GB.

        Parameters
        ----------
        file : str, binary stream, or FileHandle
            File name or writable binary stream, such as an open file
            or BytesIO.
        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.
        append : bool
            If True and 'file' is an existing standard TIFF file, image data
            and tags are appended to the file.
            Appending data may corrupt specifically formatted TIFF files
            such as LSM, STK, ImageJ, or FluoView.
        imagej : bool
            If True, write an ImageJ hyperstack compatible file.
            This format can handle data types uint8, uint16, or float32 and
            data shapes up to 6 dimensions in TZCYXS order.
            RGB images (S=3 or S=4) must be uint8.
            ImageJ's default byte order is big-endian but this implementation
            uses the system's native byte order by default.
            ImageJ hyperstacks do not support BigTIFF or compression.
            The ImageJ file format is undocumented.
            When using compression, use ImageJ's Bio-Formats import function.

        """
        if append:
            # determine if file is an existing TIFF file that can be extended
            try:
                with FileHandle(file, mode='rb', size=0) as fh:
                    pos = fh.tell()
                    try:
                        with TiffFile(fh) as tif:
                            if append != 'force' and not tif.is_appendable:
                                raise TiffFileError('cannot append to file'
                                                    ' containing metadata')
                            byteorder = tif.byteorder
                            bigtiff = tif.is_bigtiff
                            self._ifdoffset = tif.pages.next_page_offset
                    finally:
                        fh.seek(pos)
            except (IOError, FileNotFoundError):
                append = False

        if byteorder in (None, '=', '|'):
            byteorder = '<' if sys.byteorder == 'little' else '>'
        elif byteorder not in ('<', '>'):
            raise ValueError('invalid byteorder %s' % byteorder)
        if imagej and bigtiff:
            warnings.warn('writing incompatible BigTIFF ImageJ')

        self._byteorder = byteorder
        self._imagej = bool(imagej)
        self._truncate = False
        self._metadata = None
        self._colormap = None

        self._descriptionoffset = 0
        self._descriptionlen = 0
        self._descriptionlenoffset = 0
        self._tags = None
        self._shape = None  # normalized shape of data in consecutive pages
        self._datashape = None  # shape of data in consecutive pages
        self._datadtype = None  # data type
        self._dataoffset = None  # offset to data
        self._databytecounts = None  # byte counts per plane
        self._tagoffsets = None  # strip or tile offset tag code

        if bigtiff:
            self._bigtiff = True
            self._offsetsize = 8
            self._tagsize = 20
            self._tagnoformat = 'Q'
            self._offsetformat = 'Q'
            self._valueformat = '8s'
        else:
            self._bigtiff = False
            self._offsetsize = 4
            self._tagsize = 12
            self._tagnoformat = 'H'
            self._offsetformat = 'I'
            self._valueformat = '4s'

        if append:
            self._fh = FileHandle(file, mode='r+b', size=0)
            self._fh.seek(0, 2)
        else:
            self._fh = FileHandle(file, mode='wb', size=0)
            self._fh.write({'<': b'II', '>': b'MM'}[byteorder])
            if bigtiff:
                self._fh.write(struct.pack(byteorder + 'HHH', 43, 8, 0))
            else:
                self._fh.write(struct.pack(byteorder + 'H', 42))
            # first IFD
            self._ifdoffset = self._fh.tell()
            self._fh.write(struct.pack(byteorder + self._offsetformat, 0))

    def save(self, data=None, shape=None, dtype=None, returnoffset=False,
             photometric=None, planarconfig=None, extrasamples=None, tile=None,
             contiguous=True, align=16, truncate=False, compress=0,
             rowsperstrip=None, predictor=False, subsampling=None,
             colormap=None, description=None, datetime=None, resolution=None,
             subfiletype=0, software='tifffile.py', metadata={},
             ijmetadata=None, extratags=()):
        """Write numpy array and tags to TIFF file.

        The data shape's last dimensions are assumed to be image depth,
        height (length), width, and samples.
        If a colormap is provided, the data's dtype must be uint8 or uint16
        and the data values are indices into the last dimension of the
        colormap.
        If 'shape' and 'dtype' are specified, an empty array is saved.
        This option cannot be used with compression or multiple tiles.
        Image data are written uncompressed in one strip per plane by default.
        Dimensions larger than 2 to 4 (depending on photometric mode, planar
        configuration, and SGI mode) are flattened and saved as separate pages.
        The SampleFormat and BitsPerSample tags are derived from the data type.

        Parameters
        ----------
        data : numpy.ndarray or None
            Input image array.
        shape : tuple or None
            Shape of the empty array to save. Used only if 'data' is None.
        dtype : numpy.dtype or None
            Datatype of the empty array to save. Used only if 'data' is None.
        returnoffset : bool
            If True and the image data in the file is memory-mappable, return
            the offset and number of bytes of the image data in the file.
        photometric : {'MINISBLACK', 'MINISWHITE', 'RGB', 'PALETTE', 'CFA'}
            The color space of the image data.
            By default, this setting is inferred from the data shape and the
            value of colormap.
            For CFA images, DNG tags must be specified in 'extratags'.
        planarconfig : {'CONTIG', 'SEPARATE'}
            Specifies if samples are stored interleaved or in separate planes.
            By default, this setting is inferred from the data shape.
            If this parameter is set, extra samples are used to store grayscale
            images.
            'CONTIG': last dimension contains samples.
            'SEPARATE': third last dimension contains samples.
        extrasamples : tuple of {'UNSPECIFIED', 'ASSOCALPHA', 'UNASSALPHA'}
            Defines the interpretation of extra components in pixels.
            'UNSPECIFIED': no transparency information (default).
            'ASSOCALPHA': single, true transparency with pre-multiplied color.
            'UNASSALPHA': independent transparency masks.
        tile : tuple of int
            The shape ([depth,] length, width) of image tiles to write.
            If None (default), image data are written in strips.
            The tile length and width must be a multiple of 16.
            If the tile depth is provided, the SGI ImageDepth and TileDepth
            tags are used to save volume data.
            Unless a single tile is used, tiles cannot be used to write
            contiguous files.
            Few software can read the SGI format, e.g. MeVisLab.
        contiguous : bool
            If True (default) and the data and parameters are compatible with
            previous ones, if any, the image data are stored contiguously after
            the previous one. In that case, 'photometric', 'planarconfig',
            'rowsperstrip', are ignored. Metadata such as 'description',
            'metadata', 'datetime', and 'extratags' are written to the first
            page of a contiguous series only.
        align : int
            Byte boundary on which to align the image data in the file.
            Default 16. Use mmap.ALLOCATIONGRANULARITY for memory-mapped data.
            Following contiguous writes are not aligned.
        truncate : bool
            If True, only write the first page including shape metadata if
            possible (uncompressed, contiguous, not tiled).
            Other TIFF readers will only be able to read part of the data.
        compress : int or str or (str, int)
            If 0 (default), data are written uncompressed.
            If 0-9, the level of ADOBE_DEFLATE compression.
            If a str, one of TIFF.COMPESSORS, e.g. 'LZMA' or 'ZSTD'.
            If a tuple, the first item is one of TIFF.COMPESSORS and the
            second item is the compression level.
            Compression cannot be used to write contiguous files.
            Compressors may require certain data shapes, types or value ranges.
            For example, JPEG requires grayscale or RGB(A), uint8 or 12-bit
            uint16. JPEG compression is experimental. JPEG markers and TIFF
            tags may not match.
        rowsperstrip : int
            The number of rows per strip. By default, strips will be ~64 KB
            if compression is enabled, else rowsperstrip is set to the image
            length. Bilevel images are always stored in one strip per plane.
        predictor : bool
            If True, apply horizontal differencing or floating-point predictor
            before compression.
        subsampling : {(1, 1), (2, 1), (2, 2), (4, 1)}
            The horizontal and vertical subsampling factors used for the
            chrominance components of images. The default is (2, 2).
            Currently applies to JPEG compression of RGB images only.
            Images will be stored in YCbCr colorspace.
            Segment widths must be a multiple of the horizontal factor.
            Segment lengths and rowsperstrip must be a multiple of the vertical
            factor.
        colormap : numpy.ndarray
            RGB color values for the corresponding data value.
            Must be of shape (3, 2**(data.itemsize*8)) and dtype uint16.
        description : str
            The subject of the image. Must be 7-bit ASCII. Cannot be used with
            the ImageJ format. Saved with the first page only.
        datetime : datetime, str, or bool
            Date and time of image creation in '%Y:%m:%d %H:%M:%S' format or
            datetime object. Else if True, the current date and time is used.
            Saved with the first page only.
        resolution : (float, float[, str]) or ((int, int), (int, int)[, str])
            X and Y resolutions in pixels per resolution unit as float or
            rational numbers. A third, optional parameter specifies the
            resolution unit, which must be None (default for ImageJ),
            'INCH' (default), or 'CENTIMETER'.
        subfiletype : int
            Bitfield to indicate the kind of data. Set bit 0 if the image
            is a reduced-resolution version of another image. Set bit 1 if
            the image is part of a multi-page image. Set bit 2 if the image
            is transparency mask for another image (photometric must be
            MASK, SamplesPerPixel and BitsPerSample must be 1).
        software : str
            Name of the software used to create the file. Must be 7-bit ASCII.
            Saved with the first page only.
        metadata : dict
            Additional metadata to be saved along with shape information
            in JSON or ImageJ formats in an ImageDescription tag.
            If None, do not write a second ImageDescription tag.
            Strings must be 7-bit ASCII. Saved with the first page only.
        ijmetadata : dict
            Additional metadata to be saved in application specific
            IJMetadata and IJMetadataByteCounts tags. Refer to the
            imagej_metadata_tag function for valid keys and values.
            Saved with the first page only.
        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, 2i, f, d, Q, or q.
            count : int
                Number of data values. Not used for string or byte string
                values.
            value : sequence
                'Count' values compatible with 'dtype'.
                Byte strings must contain count values of dtype packed as
                binary data.
            writeonce : bool
                If True, the tag is written to the first page only.

        """
        # TODO: refactor this function
        fh = self._fh
        byteorder = self._byteorder

        if data is None:
            if compress:
                raise ValueError('cannot save compressed empty file')
            datashape = shape
            datadtype = numpy.dtype(dtype).newbyteorder(byteorder)
            datadtypechar = datadtype.char
        else:
            data = numpy.asarray(data, byteorder + data.dtype.char, 'C')
            if data.size == 0:
                raise ValueError('cannot save empty array')
            datashape = data.shape
            datadtype = data.dtype
            datadtypechar = data.dtype.char

        returnoffset = returnoffset and datadtype.isnative
        bilevel = datadtypechar == '?'
        if bilevel:
            index = -1 if datashape[-1] > 1 else -2
            datasize = product(datashape[:index])
            if datashape[index] % 8:
                datasize *= datashape[index] // 8 + 1
            else:
                datasize *= datashape[index] // 8
        else:
            datasize = product(datashape) * datadtype.itemsize

        # just append contiguous data if possible
        self._truncate = bool(truncate)
        if self._datashape:
            if (
                not contiguous
                or self._datashape[1:] != datashape
                or self._datadtype != datadtype
                or (compress and self._tags)
                or tile
                or not numpy.array_equal(colormap, self._colormap)
            ):
                # incompatible shape, dtype, compression mode, or colormap
                self._write_remaining_pages()
                self._write_image_description()
                self._truncate = False
                self._descriptionoffset = 0
                self._descriptionlenoffset = 0
                self._datashape = None
                self._colormap = None
                if self._imagej:
                    raise ValueError(
                        'ImageJ does not support non-contiguous data')
            else:
                # consecutive mode
                self._datashape = (self._datashape[0] + 1,) + datashape
                if not compress:
                    # write contiguous data, write IFDs/tags later
                    offset = fh.tell()
                    if data is None:
                        fh.write_empty(datasize)
                    else:
                        fh.write_array(data)
                    if returnoffset:
                        return offset, datasize
                    return None

        input_shape = datashape
        tagnoformat = self._tagnoformat
        valueformat = self._valueformat
        offsetformat = self._offsetformat
        offsetsize = self._offsetsize
        tagsize = self._tagsize

        MINISBLACK = TIFF.PHOTOMETRIC.MINISBLACK
        MINISWHITE = TIFF.PHOTOMETRIC.MINISWHITE
        RGB = TIFF.PHOTOMETRIC.RGB
        CFA = TIFF.PHOTOMETRIC.CFA
        PALETTE = TIFF.PHOTOMETRIC.PALETTE
        CONTIG = TIFF.PLANARCONFIG.CONTIG
        SEPARATE = TIFF.PLANARCONFIG.SEPARATE

        # parse input
        if photometric is not None:
            photometric = enumarg(TIFF.PHOTOMETRIC, photometric)
        if planarconfig:
            planarconfig = enumarg(TIFF.PLANARCONFIG, planarconfig)
        if extrasamples is None:
            extrasamples_ = None
        else:
            extrasamples_ = tuple(
                enumarg(TIFF.EXTRASAMPLE, es) for es in sequence(extrasamples)
            )
        if not compress:
            compress = False
            compresstag = 1
            # TODO: support predictors without compression
            predictor = False
            predictortag = 1
        else:
            if isinstance(compress, (tuple, list)):
                compress, compresslevel = compress
            elif isinstance(compress, int):
                compress, compresslevel = 'ADOBE_DEFLATE', int(compress)
                if not 0 <= compresslevel <= 9:
                    raise ValueError('invalid compression level %s' % compress)
            else:
                compresslevel = None
            compress = compress.upper()
            compresstag = enumarg(TIFF.COMPRESSION, compress)

        if predictor:
            if compresstag == 7:
                predictor = False  # disable predictor for lossy compression
            elif datadtype.kind in 'iu':
                predictortag = 2
                predictor = TIFF.PREDICTORS[2]
            elif datadtype.kind == 'f':
                predictortag = 3
                predictor = TIFF.PREDICTORS[3]
            else:
                raise ValueError('cannot apply predictor to %s' % datadtype)

        # prepare ImageJ format
        if self._imagej:
            # if predictor or compress:
            #     warnings.warn(
            #         'ImageJ cannot handle predictors or compression')
            if description:
                warnings.warn('not writing description to ImageJ file')
                description = None
            volume = False
            if datadtypechar not in 'BHhf':
                raise ValueError(
                    'ImageJ does not support data type %s' % datadtypechar)
            ijrgb = photometric == RGB if photometric else None
            if datadtypechar not in 'B':
                ijrgb = False
            ijshape = imagej_shape(datashape, ijrgb)
            if ijshape[-1] in (3, 4):
                photometric = RGB
                if datadtypechar not in 'B':
                    raise ValueError(
                        'ImageJ does not support data type %s for RGB'
                        % datadtypechar)
            elif photometric is None:
                photometric = MINISBLACK
                planarconfig = None
            if planarconfig == SEPARATE:
                raise ValueError('ImageJ does not support planar images')
            planarconfig = CONTIG if ijrgb else None

        # verify colormap and indices
        if colormap is not None:
            if datadtypechar not in 'BH':
                raise ValueError('invalid data dtype for palette mode')
            colormap = numpy.asarray(colormap, dtype=byteorder + 'H')
            if colormap.shape != (3, 2**(datadtype.itemsize * 8)):
                raise ValueError('invalid color map shape')
            self._colormap = colormap

        # verify tile shape
        if tile:
            tile = tuple(int(i) for i in tile[:3])
            volume = len(tile) == 3
            if (
                len(tile) < 2
                or tile[-1] % 16
                or tile[-2] % 16
                or any(i < 1 for i in tile)
            ):
                raise ValueError('invalid tile shape')
        else:
            tile = ()
            volume = False

        # normalize data shape to 5D or 6D, depending on volume:
        #   (pages, planar_samples, [depth,] height, width, contig_samples)
        datashape = reshape_nd(datashape, 3 if photometric == RGB else 2)
        shape = datashape
        ndim = len(datashape)

        samplesperpixel = 1
        extrasamples = 0
        if volume and ndim < 3:
            volume = False
        if colormap is not None:
            photometric = PALETTE
            planarconfig = None
        if photometric is None:
            photometric = MINISBLACK
            if bilevel:
                photometric = MINISWHITE
            elif planarconfig == CONTIG:
                if ndim > 2 and shape[-1] in (3, 4):
                    photometric = RGB
            elif planarconfig == SEPARATE:
                if volume and ndim > 3 and shape[-4] in (3, 4):
                    photometric = RGB
                elif ndim > 2 and shape[-3] in (3, 4):
                    photometric = RGB
            elif ndim > 2 and shape[-1] in (3, 4):
                photometric = RGB
            elif self._imagej:
                photometric = MINISBLACK
            elif volume and ndim > 3 and shape[-4] in (3, 4):
                photometric = RGB
            elif ndim > 2 and shape[-3] in (3, 4):
                photometric = RGB
        if planarconfig and len(shape) <= (3 if volume else 2):
            planarconfig = None
            if photometric not in (0, 1, 3, 4):
                photometric = MINISBLACK
        if photometric == RGB:
            if len(shape) < 3:
                raise ValueError('not a RGB(A) image')
            if len(shape) < 4:
                volume = False
            if planarconfig is None:
                if shape[-1] in (3, 4):
                    planarconfig = CONTIG
                elif shape[-4 if volume else -3] in (3, 4):
                    planarconfig = SEPARATE
                elif shape[-1] > shape[-4 if volume else -3]:
                    planarconfig = SEPARATE
                else:
                    planarconfig = CONTIG
            if planarconfig == CONTIG:
                datashape = (-1, 1) + shape[(-4 if volume else -3):]
                samplesperpixel = datashape[-1]
            else:
                datashape = (-1,) + shape[(-4 if volume else -3):] + (1,)
                samplesperpixel = datashape[1]
            if samplesperpixel > 3:
                extrasamples = samplesperpixel - 3
        elif photometric == CFA:
            if len(shape) != 2:
                raise ValueError('invalid CFA image')
            volume = False
            planarconfig = None
            datashape = (-1, 1) + shape[-2:] + (1,)
            if 50706 not in (et[0] for et in extratags):
                raise ValueError('must specify DNG tags for CFA image')
        elif planarconfig and len(shape) > (3 if volume else 2):
            if planarconfig == CONTIG:
                datashape = (-1, 1) + shape[(-4 if volume else -3):]
                samplesperpixel = datashape[-1]
            else:
                datashape = (-1,) + shape[(-4 if volume else -3):] + (1,)
                samplesperpixel = datashape[1]
            extrasamples = samplesperpixel - 1
        else:
            planarconfig = None
            while len(shape) > 2 and shape[-1] == 1:
                shape = shape[:-1]  # remove trailing 1s
            if len(shape) < 3:
                volume = False
            if extrasamples_ is None:
                datashape = (-1, 1) + shape[(-3 if volume else -2):] + (1,)
            else:
                datashape = (-1, 1) + shape[(-4 if volume else -3):]
                samplesperpixel = datashape[-1]
                extrasamples = samplesperpixel - 1

        if subfiletype & 0b100:
            # FILETYPE_MASK
            if not (
                bilevel
                and samplesperpixel == 1
                and photometric in (0, 1, 4)
            ):
                raise ValueError('invalid SubfileType MASK')
            photometric = TIFF.PHOTOMETRIC.MASK

        if bilevel:
            bitspersample = 1
        elif compresstag == 7 and datadtype == 'uint16':
            bitspersample = 12  # use 12-bit JPEG compression
        else:
            bitspersample = datadtype.itemsize * 8

        # normalize shape to 6D
        if len(datashape) not in (5, 6):
            raise RuntimeError('len(datashape) not in (5, 6)')
        if len(datashape) == 5:
            datashape = datashape[:2] + (1,) + datashape[2:]
        if datashape[0] == -1:
            s0 = product(input_shape) // product(datashape[1:])
            datashape = (s0,) + datashape[1:]
        shape = datashape
        if data is not None:
            data = data.reshape(shape)

        if photometric == PALETTE:
            if (
                samplesperpixel != 1
                or extrasamples
                or shape[1] != 1
                or shape[-1] != 1
            ):
                raise ValueError('invalid data shape for palette mode')

        if photometric == RGB and samplesperpixel == 2:
            raise ValueError('not a RGB image (samplesperpixel=2)')

        if bilevel:
            if compresstag not in (1, 32773):
                raise ValueError('cannot compress bilevel image')
            if tile:
                raise ValueError('cannot save tiled bilevel image')
            if photometric not in (0, 1, 4):
                raise ValueError('cannot save bilevel image as %s'
                                 % str(photometric))
            datashape = list(datashape)
            if datashape[-2] % 8:
                datashape[-2] = datashape[-2] // 8 + 1
            else:
                datashape[-2] = datashape[-2] // 8
            datashape = tuple(datashape)
            if datasize != product(datashape):
                raise RuntimeError('datasize != product(datashape)')
            if data is not None:
                data = numpy.packbits(data, axis=-2)
                if datashape[-2] != data.shape[-2]:
                    raise RuntimeError('datashape[-2] != data.shape[-2]')

        tags = []  # list of (code, ifdentry, ifdvalue, writeonce)

        strip_or_tile = 'Tile' if tile else 'Strip'
        tagbytecounts = TIFF.TAG_NAMES[strip_or_tile + 'ByteCounts']
        tagoffsets = TIFF.TAG_NAMES[strip_or_tile + 'Offsets']
        self._tagoffsets = tagoffsets

        def pack(fmt, *val):
            return struct.pack(byteorder + fmt, *val)

        def addtag(code, dtype, count, value, writeonce=False):
            # Compute ifdentry & ifdvalue bytes from code, dtype, count, value
            # Append (code, ifdentry, ifdvalue, writeonce) to tags list
            code = int(TIFF.TAG_NAMES.get(code, code))
            try:
                tifftype = TIFF.DATA_DTYPES[dtype]
            except KeyError:
                raise ValueError('unknown dtype %s' % dtype)
            rawcount = count

            if dtype == 's':
                # strings; enforce 7-bit ASCII on unicode strings
                value = bytestr(value, 'ascii') + b'\0'
                count = rawcount = len(value)
                rawcount = value.find(b'\0\0')
                if rawcount < 0:
                    rawcount = count
                else:
                    rawcount += 1  # length of string without buffer
                value = (value,)
            elif isinstance(value, bytes):
                # packed binary data
                dtsize = struct.calcsize(dtype)
                if len(value) % dtsize:
                    raise ValueError('invalid packed binary data')
                count = len(value) // dtsize
            if len(dtype) > 1:
                count *= int(dtype[:-1])
                dtype = dtype[-1]
            ifdentry = [pack('HH', code, tifftype),
                        pack(offsetformat, rawcount)]
            ifdvalue = None
            if struct.calcsize(dtype) * count <= offsetsize:
                # value(s) can be written directly
                if isinstance(value, bytes):
                    ifdentry.append(pack(valueformat, value))
                elif count == 1:
                    if isinstance(value, (tuple, list, numpy.ndarray)):
                        value = value[0]
                    ifdentry.append(pack(valueformat, pack(dtype, value)))
                else:
                    ifdentry.append(pack(valueformat,
                                         pack(str(count) + dtype, *value)))
            else:
                # use offset to value(s)
                ifdentry.append(pack(offsetformat, 0))
                if isinstance(value, bytes):
                    ifdvalue = value
                elif isinstance(value, numpy.ndarray):
                    if value.size != count:
                        raise RuntimeError('value.size != count')
                    if value.dtype.char != dtype:
                        raise RuntimeError('value.dtype.char != dtype')
                    ifdvalue = value.tostring()
                elif isinstance(value, (tuple, list)):
                    ifdvalue = pack(str(count) + dtype, *value)
                else:
                    ifdvalue = pack(dtype, value)
            tags.append((code, b''.join(ifdentry), ifdvalue, writeonce))

        def rational(arg, max_denominator=1000000):
            """"Return nominator and denominator from float or two integers."""
            from fractions import Fraction  # delayed import
            try:
                f = Fraction.from_float(arg)
            except TypeError:
                f = Fraction(arg[0], arg[1])
            f = f.limit_denominator(max_denominator)
            return f.numerator, f.denominator

        if description:
            # user provided description
            addtag('ImageDescription', 's', 0, description, writeonce=True)

        # write shape and metadata to ImageDescription
        self._metadata = {} if not metadata else metadata.copy()
        if self._imagej:
            description = imagej_description(
                input_shape,
                shape[-1] in (3, 4),
                self._colormap is not None,
                **self._metadata)
        elif metadata or metadata == {}:
            if self._truncate:
                self._metadata.update(truncated=True)
            description = json_description(input_shape, **self._metadata)
        # elif metadata is None and self._truncate:
        #     raise ValueError('cannot truncate without writing metadata')
        else:
            description = None
        if description:
            # add 64 bytes buffer
            # the image description might be updated later with the final shape
            description = str2bytes(description, 'ascii')
            description += b'\0' * 64
            self._descriptionlen = len(description)
            addtag('ImageDescription', 's', 0, description, writeonce=True)

        if software:
            addtag('Software', 's', 0, software, writeonce=True)
        if datetime:
            if isinstance(datetime, str):
                if len(datetime) != 19 or datetime[16] != ':':
                    raise ValueError('invalid datetime string')
            else:
                try:
                    datetime = datetime.strftime('%Y:%m:%d %H:%M:%S')
                except AttributeError:
                    datetime = self._now().strftime('%Y:%m:%d %H:%M:%S')
            addtag('DateTime', 's', 0, datetime, writeonce=True)
        addtag('Compression', 'H', 1, compresstag)
        if predictor:
            addtag('Predictor', 'H', 1, predictortag)
        addtag('ImageWidth', 'I', 1, shape[-2])
        addtag('ImageLength', 'I', 1, shape[-3])
        if tile:
            addtag('TileWidth', 'I', 1, tile[-1])
            addtag('TileLength', 'I', 1, tile[-2])
            if volume:
                addtag('ImageDepth', 'I', 1, shape[-4])
                addtag('TileDepth', 'I', 1, tile[0])
        addtag('NewSubfileType', 'I', 1, subfiletype)
        if not bilevel and not datadtype.kind == 'u':
            sampleformat = {'u': 1, 'i': 2, 'f': 3, 'c': 6}[datadtype.kind]
            addtag('SampleFormat', 'H', samplesperpixel,
                   (sampleformat,) * samplesperpixel)
        if colormap is not None:
            addtag('ColorMap', 'H', colormap.size, colormap)
        addtag('SamplesPerPixel', 'H', 1, samplesperpixel)
        if bilevel:
            pass
        elif planarconfig and samplesperpixel > 1:
            addtag('PlanarConfiguration', 'H', 1, planarconfig.value)
            addtag('BitsPerSample', 'H', samplesperpixel,
                   (bitspersample,) * samplesperpixel)
        else:
            addtag('BitsPerSample', 'H', 1, bitspersample)
        if extrasamples:
            if extrasamples_ is not None:
                if extrasamples != len(extrasamples_):
                    raise ValueError('wrong number of extrasamples specified')
                addtag('ExtraSamples', 'H', extrasamples, extrasamples_)
            elif photometric == RGB and extrasamples == 1:
                # Unassociated alpha channel
                addtag('ExtraSamples', 'H', 1, 2)
            else:
                # Unspecified alpha channel
                addtag('ExtraSamples', 'H', extrasamples, (0,) * extrasamples)

        if compresstag == 7 and photometric == RGB and planarconfig == 1:
            # JPEG compression with subsampling. Store as YCbCr
            # TODO: use JPEGTables for multiple tiles or strips
            if subsampling is None:
                subsampling = (2, 2)
            elif subsampling not in ((1, 1), (2, 1), (2, 2), (4, 1)):
                raise ValueError('invalid subsampling factors')
            maxsampling = max(subsampling) * 8
            if tile and (tile[-1] % maxsampling or tile[-2] % maxsampling):
                raise ValueError('tile shape not a multiple of %i'
                                 % maxsampling)
            if extrasamples > 1:
                raise ValueError('JPEG subsampling requires RGB(A) images')
            addtag('YCbCrSubSampling', 'H', 2, subsampling)
            addtag('PhotometricInterpretation', 'H', 1, 6)  # YCBCR
        else:
            if subsampling not in (None, (1, 1)):
                log_warning('cannot apply subsampling')
            subsampling = None
            maxsampling = 1
            addtag('PhotometricInterpretation', 'H', 1, photometric.value)
            if compresstag == 7:
                addtag('YCbCrSubSampling', 'H', 2, (1, 1))

        if resolution is not None:
            addtag('XResolution', '2I', 1, rational(resolution[0]))
            addtag('YResolution', '2I', 1, rational(resolution[1]))
            if len(resolution) > 2:
                unit = resolution[2]
                unit = 1 if unit is None else enumarg(TIFF.RESUNIT, unit)
            elif self._imagej:
                unit = 1
            else:
                unit = 2
            addtag('ResolutionUnit', 'H', 1, unit)
        elif not self._imagej:
            addtag('XResolution', '2I', 1, (1, 1))
            addtag('YResolution', '2I', 1, (1, 1))
            addtag('ResolutionUnit', 'H', 1, 1)
        if ijmetadata:
            for t in imagej_metadata_tag(ijmetadata, byteorder):
                addtag(*t)

        def bytecount_format(bytecounts, compress=compress, size=offsetsize):
            """Return bytecount format."""
            if len(bytecounts) == 1:
                return {4: 'I', 8: 'Q'}[size]
            bytecount = bytecounts[0]
            if compress:
                bytecount = bytecount * 10
            if bytecount < 2**16:
                return 'H'
            if bytecount < 2**32:
                return 'I'
            if size == 4:
                return 'I'
            return 'Q'

        contiguous = not compress
        if tile:
            # one chunk per tile per plane
            if len(tile) == 3:
                tiles = (
                    (shape[2] + tile[0] - 1) // tile[0],
                    (shape[3] + tile[1] - 1) // tile[1],
                    (shape[4] + tile[2] - 1) // tile[2],
                )
            else:
                tiles = (
                    (shape[3] + tile[0] - 1) // tile[0],
                    (shape[4] + tile[1] - 1) // tile[1],
                )
            numtiles = product(tiles) * shape[1]
            databytecounts = [
                product(tile) * shape[-1] * datadtype.itemsize] * numtiles
            bytecountformat = bytecount_format(databytecounts)
            addtag(tagbytecounts, bytecountformat, numtiles, databytecounts)
            addtag(tagoffsets, offsetformat, numtiles, [0] * numtiles)
            contiguous = contiguous and product(tiles) == 1
            if not contiguous:
                # allocate tile buffer
                chunk = numpy.empty(tile + (shape[-1],), dtype=datadtype)
            bytecountformat = bytecountformat * numtiles
        elif contiguous and (bilevel or rowsperstrip is None):
            # one strip per plane
            if bilevel:
                databytecounts = [product(datashape[2:])] * shape[1]
            else:
                databytecounts = [
                    product(datashape[2:]) * datadtype.itemsize] * shape[1]
            bytecountformat = bytecount_format(databytecounts)
            addtag(tagbytecounts, bytecountformat, shape[1], databytecounts)
            addtag(tagoffsets, offsetformat, shape[1], [0] * shape[1])
            addtag('RowsPerStrip', 'I', 1, shape[-3])
            bytecountformat = bytecountformat * shape[1]
        else:
            # use rowsperstrip
            rowsize = product(shape[-2:]) * datadtype.itemsize
            if rowsperstrip is None:
                # compress ~64 KB chunks by default
                rowsperstrip = 65536 // rowsize if compress else shape[-3]
            if rowsperstrip < 1:
                rowsperstrip = maxsampling
            elif rowsperstrip > shape[-3]:
                rowsperstrip = shape[-3]
            elif subsampling and rowsperstrip % maxsampling:
                rowsperstrip = (math.ceil(rowsperstrip / maxsampling) *
                                maxsampling)
            addtag('RowsPerStrip', 'I', 1, rowsperstrip)

            numstrips1 = (shape[-3] + rowsperstrip - 1) // rowsperstrip
            numstrips = numstrips1 * shape[1]
            # TODO: save bilevel data with rowsperstrip
            stripsize = rowsperstrip * rowsize
            databytecounts = [stripsize] * numstrips
            stripsize -= rowsize * (numstrips1 * rowsperstrip - shape[-3])
            for i in range(numstrips1 - 1, numstrips, numstrips1):
                databytecounts[i] = stripsize
            bytecountformat = bytecount_format(databytecounts)
            addtag(tagbytecounts, bytecountformat, numstrips, databytecounts)
            addtag(tagoffsets, offsetformat, numstrips, [0] * numstrips)
            bytecountformat = bytecountformat * numstrips

        if data is None and not contiguous:
            raise ValueError('cannot write non-contiguous empty file')

        # add extra tags from user
        for t in extratags:
            addtag(*t)

        # define compress function
        if compress:
            compressor = TIFF.COMPESSORS[compresstag]
            if predictor:

                def compress(data, compressor=compressor, level=compresslevel):
                    data = predictor(data, axis=-2)
                    return compressor(data, level)

            elif subsampling:
                # JPEG with subsampling. Store RGB as YCbCr
                # TODO: use JPEGTables for multiple tiles or strips
                def compress(data, compressor=compressor, level=compresslevel,
                             subsampling=subsampling):
                    return compressor(data, level, subsampling=subsampling,
                                      colorspace=2, outcolorspace=3)

            else:

                def compress(data, compressor=compressor, level=compresslevel):
                    return compressor(data, level)

        # TODO: check TIFFReadDirectoryCheckOrder warning in files containing
        #   multiple tags of same code
        # the entries in an IFD must be sorted in ascending order by tag code
        tags = sorted(tags, key=lambda x: x[0])

        fhpos = fh.tell()
        if (
            not (self._bigtiff or self._imagej)
            and fhpos + datasize > 2**32 - 1
        ):
            raise ValueError('data too large for standard TIFF file')

        # if not compressed or multi-tiled, write the first IFD and then
        # all data contiguously; else, write all IFDs and data interleaved
        for pageindex in range(1 if contiguous else shape[0]):

            ifdpos = fhpos
            if ifdpos % 2:
                # location of IFD must begin on a word boundary
                fh.write(b'\0')
                ifdpos += 1

            # update pointer at ifdoffset
            fh.seek(self._ifdoffset)
            fh.write(pack(offsetformat, ifdpos))
            fh.seek(ifdpos)

            # create IFD in memory
            if pageindex < 2:
                ifd = io.BytesIO()
                ifd.write(pack(tagnoformat, len(tags)))
                tagoffset = ifd.tell()
                ifd.write(b''.join(t[1] for t in tags))
                ifdoffset = ifd.tell()
                ifd.write(pack(offsetformat, 0))  # offset to next IFD
                # write tag values and patch offsets in ifdentries
                for tagindex, tag in enumerate(tags):
                    offset = tagoffset + tagindex * tagsize + offsetsize + 4
                    code = tag[0]
                    value = tag[2]
                    if value:
                        pos = ifd.tell()
                        if pos % 2:
                            # tag value is expected to begin on word boundary
                            ifd.write(b'\0')
                            pos += 1
                        ifd.seek(offset)
                        ifd.write(pack(offsetformat, ifdpos + pos))
                        ifd.seek(pos)
                        ifd.write(value)
                        if code == tagoffsets:
                            dataoffsetsoffset = offset, pos
                        elif code == tagbytecounts:
                            databytecountsoffset = offset, pos
                        elif code == 270 and value.endswith(b'\0\0\0\0'):
                            # image description buffer
                            self._descriptionoffset = ifdpos + pos
                            self._descriptionlenoffset = (
                                ifdpos + tagoffset + tagindex * tagsize + 4)
                    elif code == tagoffsets:
                        dataoffsetsoffset = offset, None
                    elif code == tagbytecounts:
                        databytecountsoffset = offset, None
                ifdsize = ifd.tell()
                if ifdsize % 2:
                    ifd.write(b'\0')
                    ifdsize += 1

            # write IFD later when strip/tile bytecounts and offsets are known
            fh.seek(ifdsize, 1)

            # write image data
            dataoffset = fh.tell()
            skip = align - dataoffset % align
            fh.seek(skip, 1)
            dataoffset += skip
            if contiguous:
                if data is None:
                    fh.write_empty(datasize)
                else:
                    fh.write_array(data)
            elif tile:
                # TODO: refactor this
                # TODO: use multithreading and chunk buffer?
                if data is None:
                    fh.write_empty(numtiles * databytecounts[0])
                elif len(tile) == 3:
                    stripindex = 0
                    for plane in data[pageindex]:
                        for tz in range(tiles[0]):
                            for ty in range(tiles[1]):
                                for tx in range(tiles[2]):
                                    c0 = min(tile[0], shape[2] - tz * tile[0])
                                    c1 = min(tile[1], shape[3] - ty * tile[1])
                                    c2 = min(tile[2], shape[4] - tx * tile[2])
                                    chunk[c0:, c1:, c2:] = 0
                                    chunk[:c0, :c1, :c2] = plane[
                                        tz * tile[0]: tz * tile[0] + c0,
                                        ty * tile[1]: ty * tile[1] + c1,
                                        tx * tile[2]: tx * tile[2] + c2,
                                    ]
                                    if compress:
                                        t = compress(chunk)
                                        fh.write(t)
                                        databytecounts[stripindex] = len(t)
                                        stripindex += 1
                                    else:
                                        fh.write_array(chunk)
                                        # fh.flush()
                else:
                    stripindex = 0
                    for plane in data[pageindex]:
                        for ty in range(tiles[0]):
                            for tx in range(tiles[1]):
                                c1 = min(tile[0], shape[3] - ty * tile[0])
                                c2 = min(tile[1], shape[4] - tx * tile[1])
                                chunk[c1:, c2:] = 0
                                chunk[:c1, :c2] = plane[
                                    0,
                                    ty * tile[0]: ty * tile[0] + c1,
                                    tx * tile[1]: tx * tile[1] + c2,
                                ]
                                if compress:
                                    t = compress(chunk)
                                    fh.write(t)
                                    databytecounts[stripindex] = len(t)
                                    stripindex += 1
                                else:
                                    fh.write_array(chunk)
                                    # fh.flush()
            elif compress:
                # write one strip per rowsperstrip
                if data.shape[2] != 1:
                    # not handling depth
                    raise RuntimeError('data.shape[2] != 1')
                numstrips = (shape[-3] + rowsperstrip - 1) // rowsperstrip
                stripindex = 0
                for plane in data[pageindex]:
                    for i in range(numstrips):
                        strip = plane[
                            0,
                            i * rowsperstrip: (i + 1) * rowsperstrip
                        ]
                        strip = compress(strip)
                        fh.write(strip)
                        databytecounts[stripindex] = len(strip)
                        stripindex += 1
            else:
                fh.write_array(data[pageindex])

            # update strip/tile offsets
            offset, pos = dataoffsetsoffset
            ifd.seek(offset)
            if pos:
                ifd.write(pack(offsetformat, ifdpos + pos))
                ifd.seek(pos)
                offset = dataoffset
                for size in databytecounts:
                    ifd.write(pack(offsetformat, offset))
                    offset += size
            else:
                ifd.write(pack(offsetformat, dataoffset))

            if compress:
                # update strip/tile bytecounts
                offset, pos = databytecountsoffset
                ifd.seek(offset)
                if pos:
                    ifd.write(pack(offsetformat, ifdpos + pos))
                    ifd.seek(pos)
                ifd.write(pack(bytecountformat, *databytecounts))

            fhpos = fh.tell()
            fh.seek(ifdpos)
            fh.write(iogetbuffer(ifd))
            fh.flush()
            fh.seek(fhpos)

            self._ifdoffset = ifdpos + ifdoffset

            # remove tags that should be written only once
            if pageindex == 0:
                tags = [tag for tag in tags if not tag[-1]]

        self._shape = shape
        self._datashape = (1,) + input_shape
        self._datadtype = datadtype
        self._dataoffset = dataoffset
        self._databytecounts = databytecounts

        if contiguous:
            # write remaining IFDs/tags later
            self._tags = tags
            # return offset and size of image data
            if returnoffset:
                return dataoffset, sum(databytecounts)
        return None

    def _write_remaining_pages(self):
        """Write outstanding IFDs and tags to file."""
        if not self._tags or self._truncate:
            return

        pageno = self._shape[0] * self._datashape[0] - 1
        if pageno < 1:
            self._tags = None
            self._datadtype = None
            self._dataoffset = None
            self._databytecounts = None
            return

        fh = self._fh
        fhpos = fh.tell()
        if fhpos % 2:
            fh.write(b'\0')
            fhpos += 1

        pack = struct.pack
        offsetformat = self._byteorder + self._offsetformat
        offsetsize = self._offsetsize
        tagnoformat = self._byteorder + self._tagnoformat
        tagsize = self._tagsize
        dataoffset = self._dataoffset
        pagedatasize = sum(self._databytecounts)

        # construct template IFD in memory
        # need to patch offsets to next IFD and data before writing to file
        ifd = io.BytesIO()
        ifd.write(pack(tagnoformat, len(self._tags)))
        tagoffset = ifd.tell()
        ifd.write(b''.join(t[1] for t in self._tags))
        ifdoffset = ifd.tell()
        ifd.write(pack(offsetformat, 0))  # offset to next IFD
        # tag values
        for tagindex, tag in enumerate(self._tags):
            offset = tagoffset + tagindex * tagsize + offsetsize + 4
            code = tag[0]
            value = tag[2]
            if value:
                pos = ifd.tell()
                if pos % 2:
                    # tag value is expected to begin on word boundary
                    ifd.write(b'\0')
                    pos += 1
                ifd.seek(offset)
                try:
                    ifd.write(pack(offsetformat, fhpos + pos))
                except Exception:  # struct.error
                    if self._imagej:
                        warnings.warn('truncating ImageJ file')
                        self._truncate = True
                        return
                    raise ValueError('data too large for non-BigTIFF file')
                ifd.seek(pos)
                ifd.write(value)
                if code == self._tagoffsets:
                    # save strip/tile offsets for later updates
                    dataoffsetsoffset = offset, pos
            elif code == self._tagoffsets:
                dataoffsetsoffset = offset, None

        ifdsize = ifd.tell()
        if ifdsize % 2:
            ifd.write(b'\0')
            ifdsize += 1

        # check if all IFDs fit in file
        if not self._bigtiff and fhpos + ifdsize * pageno > 2**32 - 32:
            if self._imagej:
                warnings.warn('truncating ImageJ file')
                self._truncate = True
                return
            raise ValueError('data too large for non-BigTIFF file')

        # assemble IFD chain in memory from IFD template
        ifds = io.BytesIO(bytes(ifdsize * pageno))
        ifdpos = fhpos
        for _ in range(pageno):
            # update strip/tile offsets in IFD
            dataoffset += pagedatasize  # offset to image data
            offset, pos = dataoffsetsoffset
            ifd.seek(offset)
            if pos:
                ifd.write(pack(offsetformat, ifdpos + pos))
                ifd.seek(pos)
                offset = dataoffset
                for size in self._databytecounts:
                    ifd.write(pack(offsetformat, offset))
                    offset += size
            else:
                ifd.write(pack(offsetformat, dataoffset))
            # update pointer at ifdoffset to point to next IFD in file
            ifdpos += ifdsize
            ifd.seek(ifdoffset)
            ifd.write(pack(offsetformat, ifdpos))
            # write IFD entry
            ifds.write(iogetbuffer(ifd))

        # terminate IFD chain
        ifdoffset += ifdsize * (pageno - 1)
        ifds.seek(ifdoffset)
        ifds.write(pack(offsetformat, 0))
        # write IFD chain to file
        fh.write(iogetbuffer(ifds))
        # update file to point to new IFD chain
        pos = fh.tell()
        fh.seek(self._ifdoffset)
        fh.write(pack(offsetformat, fhpos))
        fh.flush()
        fh.seek(pos)

        self._ifdoffset = fhpos + ifdoffset
        self._tags = None
        self._datadtype = None
        self._dataoffset = None
        self._databytecounts = None
        # do not reset _shape or _datashape

    def _write_image_description(self):
        """Write metadata to ImageDescription tag."""
        if (
            not self._datashape
            or self._datashape[0] == 1
            or self._descriptionoffset <= 0
        ):
            return

        colormapped = self._colormap is not None
        if self._imagej:
            isrgb = self._shape[-1] in (3, 4)
            description = imagej_description(
                self._datashape, isrgb, colormapped, **self._metadata)
        else:
            description = json_description(self._datashape, **self._metadata)

        # rewrite description and its length to file
        description = description.encode('utf-8')
        description = description[:self._descriptionlen - 1]
        pos = self._fh.tell()
        self._fh.seek(self._descriptionoffset)
        self._fh.write(description)
        self._fh.seek(self._descriptionlenoffset)
        self._fh.write(struct.pack(self._byteorder + self._offsetformat,
                                   len(description) + 1))
        self._fh.seek(pos)

        self._descriptionoffset = 0
        self._descriptionlenoffset = 0
        self._descriptionlen = 0

    def _now(self):
        """Return current date and time."""
        return datetime.datetime.now()

    def close(self):
        """Write remaining pages and close file handle."""
        if not self._truncate:
            self._write_remaining_pages()
        self._write_image_description()
        self._fh.close()

    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc_value, traceback):
        self.close()


class TiffFile(object):
    """Read image and metadata from TIFF file.

    TiffFile instances must be closed using the 'close' method, which is
    automatically called when using the 'with' context manager.

    TiffFile instances are not thread-safe.

    Attributes
    ----------
    pages : TiffPages
        Sequence of TIFF pages in file.
    series : list of TiffPageSeries
        Sequences of closely related TIFF pages. These are computed
        from OME, LSM, ImageJ, etc. metadata or based on similarity
        of page properties such as shape, dtype, and compression.
    is_flag : bool
        If True, file is of a certain format.
        Flags are: bigtiff, uniform, shaped, ome, imagej, stk, lsm, fluoview,
        nih, vista, micromanager, metaseries, mdgel, mediacy, tvips, fei,
        sem, scn, svs, scanimage, andor, epics, ndpi, pilatus, qpi.

    All attributes are read-only.

    """

    def __init__(self, arg, name=None, offset=None, size=None,
                 multifile=True, _useframes=None, **kwargs):
        """Initialize instance from file.

        Parameters
        ----------
        arg : str or open file
            Name of file or open file object.
            The file objects are closed in TiffFile.close().
        name : str
            Optional name of file in case 'arg' is a file handle.
        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.
        kwargs : bool
            'is_ome': If False, disable processing of OME-XML metadata.

        """
        if kwargs:
            for key in ('movie', 'fastij', 'multifile_close'):
                if key in kwargs:
                    del kwargs[key]
                    log_warning("TiffFile: the '%s' argument is ignored", key)
            if 'pages' in kwargs:
                raise TypeError(
                    "the TiffFile 'pages' argument is no longer supported.\n\n"
                    "Use TiffFile.asarray(key=[...]) to read image data "
                    "from specific pages.\n")

            for key, value in kwargs.items():
                if key[:3] == 'is_' and key[3:] in TIFF.FILE_FLAGS:
                    if value is not None and not value:
                        setattr(self, key, bool(value))
                else:
                    raise TypeError('unexpected keyword argument: %s' % key)

        fh = FileHandle(arg, mode='rb', name=name, offset=offset, size=size)
        self._fh = fh
        self._multifile = bool(multifile)
        self._files = {fh.name: self}  # cache of TiffFiles
        try:
            fh.seek(0)
            header = fh.read(4)
            try:
                byteorder = {b'II': '<', b'MM': '>'}[header[:2]]
            except KeyError:
                raise TiffFileError('not a TIFF file')

            version = struct.unpack(byteorder + 'H', header[2:4])[0]
            if version == 43:
                # BigTiff
                offsetsize, zero = struct.unpack(byteorder + 'HH', fh.read(4))
                if zero != 0 or offsetsize != 8:
                    raise TiffFileError('invalid BigTIFF file')
                if byteorder == '>':
                    self.tiff = TIFF.BIG_BE
                else:
                    self.tiff = TIFF.BIG_LE
            elif version == 42:
                # Classic TIFF
                if byteorder == '>':
                    self.tiff = TIFF.CLASSIC_BE
                elif kwargs.get('is_ndpi', False):
                    # NDPI uses 64 bit IFD offsets
                    # TODO: fix offsets in NDPI tags if file size > 4 GB
                    self.tiff = TIFF.NDPI_LE
                else:
                    self.tiff = TIFF.CLASSIC_LE
            else:
                raise TiffFileError('invalid TIFF file')

            # file handle is at offset to offset to first page
            self.pages = TiffPages(self)

            if self.is_lsm and (
                self.filehandle.size >= 2**32
                or self.pages[0].compression != 1
                or self.pages[1].compression != 1
            ):
                self._lsm_load_pages()
            elif self.is_scanimage and (
                not self.is_bigtiff and self.filehandle.size >= 2**31
            ):
                self.pages._load_virtual_frames()
            elif _useframes:
                self.pages.useframes = True

        except Exception:
            fh.close()
            raise

    @property
    def byteorder(self):
        return self.tiff.byteorder

    @property
    def is_bigtiff(self):
        return self.tiff.version == 43

    @property
    def filehandle(self):
        """Return file handle."""
        return self._fh

    @property
    def filename(self):
        """Return name of file handle."""
        return self._fh.name

    @lazyattr
    def fstat(self):
        """Return status of file handle as stat_result object."""
        try:
            return os.fstat(self._fh.fileno())
        except Exception:  # io.UnsupportedOperation
            return None

    def close(self):
        """Close open file handle(s)."""
        for tif in self._files.values():
            tif.filehandle.close()
        self._files = {}

    def asarray(self, key=None, series=None, out=None, validate=True,
                maxworkers=None):
        """Return image data from selected TIFF page(s) as numpy array.

        By default, the data from the first series is returned.

        Parameters
        ----------
        key : int, slice, or sequence of indices
            Defines which pages to return as array.
            If None (default), data from a series (default 0) is returned.
            If not None, data 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, i.e. may crash
            or return incorrect values.
        series : int or TiffPageSeries
            Defines which series of pages to return as array.
        out : numpy.ndarray, str, or file-like object
            Buffer where image data will be saved.
            If None (default), a new array will be created.
            If numpy.ndarray, a writable array of compatible dtype and shape.
            If 'memmap', directly memory-map the image data in the TIFF file
            if possible; else create a memory-mapped array in a temporary file.
            If str or open file, the file name or file object used to
            create a memory-map to an array stored in a binary file on disk.
        validate : bool
            If True (default), validate various tags.
            Passed to TiffPage.asarray().
        maxworkers : int or None
            Maximum number of threads to concurrently get data from multiple
            pages or compressed segments.
            If None (default), up to half the CPU cores are used.
            If 1, multi-threading is disabled.
            Reading data from file is limited to a single thread.
            Using multiple threads can significantly speed up this function
            if the bottleneck is decoding compressed data, e.g. 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.

        Returns
        -------
        numpy.ndarray
            Image data from the specified pages.
            See the TiffPage.asarray function for operations that are
            applied (or not) to the raw data stored in the file.

        """
        if not self.pages:
            return numpy.array([])
        if key is None and series is None:
            series = 0
        if series is None:
            pages = self.pages
        else:
            try:
                series = self.series[series]
            except (KeyError, TypeError):
                pass
            pages = series.pages

        if key is None:
            pass
        elif series is None:
            pages = self.pages._getlist(key)
        elif isinstance(key, inttypes):
            pages = [pages[key]]
        elif isinstance(key, slice):
            pages = pages[key]
        elif isinstance(key, Iterable):
            pages = [pages[k] for k in key]
        else:
            raise TypeError('key must be an int, slice, or sequence')

        if not pages:
            raise ValueError('no pages selected')

        if key is None and series and series.offset:
            typecode = self.byteorder + series.dtype.char
            if (
                pages[0].is_memmappable
                and isinstance(out, str)
                and out == 'memmap'
            ):
                # direct mapping
                result = self.filehandle.memmap_array(
                    typecode, series.shape, series.offset)
            else:
                # read into output
                if out is not None:
                    out = create_output(out, series.shape, series.dtype)
                self.filehandle.seek(series.offset)
                result = self.filehandle.read_array(
                    typecode, product(series.shape), out=out)
        elif len(pages) == 1:
            result = pages[0].asarray(out=out, validate=validate,
                                      maxworkers=maxworkers)
        else:
            result = stack_pages(pages, out=out, maxworkers=maxworkers)

        if result is None:
            return None

        if key is None:
            try:
                result.shape = series.shape
            except ValueError:
                try:
                    log_warning('TiffFile.asarray: failed to reshape %s to %s',
                                result.shape, series.shape)
                    # try series of expected shapes
                    result.shape = (-1,) + series.shape
                except ValueError:
                    # revert to generic shape
                    result.shape = (-1,) + pages[0].shape
        elif len(pages) == 1:
            result.shape = pages[0].shape
        else:
            result.shape = (-1,) + pages[0].shape
        return result

    @lazyattr
    def series(self):
        """Return related pages as TiffPageSeries.

        Side effect: after calling this function, TiffFile.pages might contain
        TiffPage and TiffFrame instances.

        """
        if not self.pages:
            return []

        useframes = self.pages.useframes
        keyframe = self.pages.keyframe.index
        series = []
        for name in (
            'lsm',
            'ome',
            'imagej',
            'shaped',
            'fluoview',
            'sis',
            'uniform',
            'mdgel',
        ):
            if getattr(self, 'is_' + name, False):
                series = getattr(self, '_series_' + name)()
                break
        self.pages.useframes = useframes
        self.pages.keyframe = keyframe
        if not series:
            series = self._series_generic()

        # remove empty series, e.g. in MD Gel files
        series = [s for s in series if product(s.shape) > 0]

        for i, s in enumerate(series):
            s.index = i
        return series

    def _series_generic(self):
        """Return image series in file.

        A series is a sequence of TiffPages with the same hash.

        """
        pages = self.pages
        pages._clear(False)
        pages.useframes = False
        if pages.cache:
            pages._load()

        result = []
        keys = []
        series = {}
        for page in pages:
            if not page.shape or product(page.shape) == 0:
                continue
            key = page.hash
            if key in series:
                series[key].append(page)
            else:
                keys.append(key)
                series[key] = [page]

        for key in keys:
            pages = series[key]
            page = pages[0]
            shape = page.shape
            axes = page.axes
            if len(pages) > 1:
                shape = (len(pages),) + shape
                axes = 'I' + axes
            result.append(
                TiffPageSeries(pages, shape, page.dtype, axes, kind='Generic')
            )

        self.is_uniform = len(result) == 1
        return result

    def _series_uniform(self):
        """Return all images in file as single series."""
        page = self.pages[0]
        shape = page.shape
        axes = page.axes
        dtype = page.dtype
        validate = not (page.is_scanimage or page.is_nih)
        pages = self.pages._getlist(validate=validate)
        lenpages = len(pages)
        if lenpages > 1:
            shape = (lenpages,) + shape
            axes = 'I' + axes
        if page.is_scanimage:
            kind = 'ScanImage'
        elif page.is_nih:
            kind = 'NIHImage'
        else:
            kind = 'Uniform'
        return [TiffPageSeries(pages, shape, dtype, axes, kind=kind)]

    def _series_shaped(self):
        """Return image series in "shaped" file."""
        pages = self.pages
        pages.useframes = True
        lenpages = len(pages)

        def append_series(series, pages, axes, shape, reshape, name,
                          truncated):
            page = pages[0]
            if not axes:
                shape = page.shape
                axes = page.axes
                if len(pages) > 1:
                    shape = (len(pages),) + shape
                    axes = 'Q' + axes
            size = product(shape)
            resize = product(reshape)
            if page.is_contiguous and resize > size and resize % size == 0:
                if truncated is None:
                    truncated = True
                axes = 'Q' + axes
                shape = (resize // size,) + shape
            try:
                axes = reshape_axes(axes, shape, reshape)
                shape = reshape
            except ValueError as exc:
                log_warning('Shaped series: %s: %s',
                            exc.__class__.__name__, exc)
            series.append(
                TiffPageSeries(pages, shape, page.dtype, axes,
                               name=name, kind='Shaped', truncated=truncated)
            )

        keyframe = axes = shape = reshape = name = None
        series = []
        index = 0
        while True:
            if index >= lenpages:
                break
            # new keyframe; start of new series
            pages.keyframe = index
            keyframe = pages.keyframe
            if not keyframe.is_shaped:
                log_warning(
                    'Shaped series: invalid metadata or corrupted file')
                return None
            # read metadata
            axes = None
            shape = None
            metadata = json_description_metadata(keyframe.is_shaped)
            name = metadata.get('name', '')
            reshape = metadata['shape']
            truncated = metadata.get('truncated', None)
            if 'axes' in metadata:
                axes = metadata['axes']
                if len(axes) == len(reshape):
                    shape = reshape
                else:
                    axes = ''
                    log_warning('Shaped series: axes do not match shape')
            # skip pages if possible
            spages = [keyframe]
            size = product(reshape)
            npages, mod = divmod(size, product(keyframe.shape))
            if mod:
                log_warning(
                    'Shaped series: series shape does not match page shape')
                return None
            if 1 < npages <= lenpages - index:
                size *= keyframe._dtype.itemsize
                if truncated:
                    npages = 1
                elif (
                    keyframe.is_final
                    and keyframe.offset + size < pages[index + 1].offset
                ):
                    truncated = False
                else:
                    # need to read all pages for series
                    truncated = False
                    for j in range(index + 1, index + npages):
                        page = pages[j]
                        page.keyframe = keyframe
                        spages.append(page)
            append_series(series, spages, axes, shape, reshape, name,
                          truncated)
            index += npages

        self.is_uniform = len(series) == 1

        return series

    def _series_imagej(self):
        """Return image series in ImageJ file."""
        # ImageJ's dimension order is always TZCYXS
        # TODO: fix loading of color, composite, or palette images
        pages = self.pages
        pages.useframes = True
        pages.keyframe = 0
        page = pages[0]
        ij = self.imagej_metadata

        def is_virtual():
            # ImageJ virtual hyperstacks store all image metadata in the first
            # page and image data are stored contiguously before the second
            # page, if any
            if not page.is_final:
                return False
            images = ij.get('images', 0)
            if images <= 1:
                return False
            offset, count = page.is_contiguous
            if (
                count != product(page.shape) * page.bitspersample // 8
                or offset + count * images > self.filehandle.size
            ):
                raise ValueError()
            # check that next page is stored after data
            if len(pages) > 1 and offset + count * images > pages[1].offset:
                return False
            return True

        try:
            isvirtual = is_virtual()
        except ValueError:
            log_warning('ImageJ series: invalid metadata or corrupted file')
            return None
        if isvirtual:
            # no need to read other pages
            pages = [page]
        else:
            pages = pages[:]

        images = ij.get('images', len(pages))
        frames = ij.get('frames', 1)
        slices = ij.get('slices', 1)
        channels = ij.get('channels', 1)
        mode = ij.get('mode', None)

        shape = []
        axes = []
        if frames > 1:
            shape.append(frames)
            axes.append('T')
        if slices > 1:
            shape.append(slices)
            axes.append('Z')
        if channels > 1 and (page.photometric != 2 or mode != 'composite'):
            shape.append(channels)
            axes.append('C')

        remain = images // (product(shape) if shape else 1)
        if remain > 1:
            shape.append(remain)
            axes.append('I')

        if page.axes[0] == 'S' and 'C' in axes:
            # planar storage, S == C, saved by Bio-Formats
            shape.extend(page.shape[1:])
            axes.extend(page.axes[1:])
        elif page.axes[0] == 'I':
            # contiguous multiple images
            shape.extend(page.shape[1:])
            axes.extend(page.axes[1:])
        elif page.axes[:2] == 'SI':
            # color-mapped contiguous multiple images
            shape = page.shape[0:1] + tuple(shape) + page.shape[2:]
            axes = list(page.axes[0]) + axes + list(page.axes[2:])
        else:
            shape.extend(page.shape)
            axes.extend(page.axes)

        truncated = (
            isvirtual
            and len(self.pages) == 1
            and page.is_contiguous[1] != (
                product(shape) * page.bitspersample // 8)
        )

        self.is_uniform = True

        return [
            TiffPageSeries(pages, shape, page.dtype, axes,
                           kind='ImageJ', truncated=truncated)
        ]

    def _series_fluoview(self):
        """Return image series in FluoView file."""
        pages = self.pages._getlist(validate=False)

        mm = self.fluoview_metadata
        mmhd = list(reversed(mm['Dimensions']))
        axes = ''.join(TIFF.MM_DIMENSIONS.get(i[0].upper(), 'Q')
                       for i in mmhd if i[1] > 1)
        shape = tuple(int(i[1]) for i in mmhd if i[1] > 1)
        self.is_uniform = True
        return [
            TiffPageSeries(pages, shape, pages[0].dtype, axes,
                           name=mm['ImageName'], kind='FluoView')
        ]

    def _series_mdgel(self):
        """Return image series in MD Gel file."""
        # only a single page, scaled according to metadata in second page
        self.pages.useframes = False
        self.pages.keyframe = 0
        md = self.mdgel_metadata
        if md['FileTag'] in (2, 128):
            dtype = numpy.dtype('float32')
            scale = md['ScalePixel']
            scale = scale[0] / scale[1]  # rational
            if md['FileTag'] == 2:
                # squary root data format
                def transform(a):
                    return a.astype('float32')**2 * scale
            else:
                def transform(a):
                    return a.astype('float32') * scale
        else:
            transform = None
        page = self.pages[0]
        self.is_uniform = False
        return [
            TiffPageSeries([page], page.shape, dtype, page.axes,
                           transform=transform, kind='MDGel')
        ]

    def _series_sis(self):
        """Return image series in Olympus SIS file."""
        pages = self.pages._getlist(validate=False)
        page = pages[0]
        lenpages = len(pages)
        md = self.sis_metadata
        if 'shape' in md and 'axes' in md:
            shape = md['shape'] + page.shape
            axes = md['axes'] + page.axes
        elif lenpages == 1:
            shape = page.shape
            axes = page.axes
        else:
            shape = (lenpages,) + page.shape
            axes = 'I' + page.axes
        self.is_uniform = True
        return [
            TiffPageSeries(pages, shape, page.dtype, axes, kind='SIS')
        ]

    def _series_ome(self):
        """Return image series in OME-TIFF file(s)."""
        from xml.etree import cElementTree as etree  # delayed import
        omexml = self.pages[0].description
        try:
            root = etree.fromstring(omexml)
        except etree.ParseError as exc:
            # TODO: test badly encoded OME-XML
            log_warning('OME series: %s: %s', exc.__class__.__name__, exc)
            try:
                # might work on Python 2
                omexml = omexml.decode('utf-8', 'ignore').encode('utf-8')
                root = etree.fromstring(omexml)
            except Exception:
                return None

        self.pages.cache = True
        self.pages.useframes = True
        self.pages.keyframe = 0
        self.pages._load(keyframe=None)

        root_uuid = root.attrib.get('UUID', None)
        self._files = {root_uuid: self}
        dirname = self._fh.dirname
        modulo = {}
        series = []
        for element in root:
            if element.tag.endswith('BinaryOnly'):
                # TODO: load OME-XML from master or companion file
                log_warning('OME series: not an ome-tiff master file')
                break
            if element.tag.endswith('StructuredAnnotations'):
                for annot in element:
                    if not annot.attrib.get('Namespace',
                                            '').endswith('modulo'):
                        continue
                    for value in annot:
                        for modul in value:
                            for along in modul:
                                if not along.tag[:-1].endswith('Along'):
                                    continue
                                axis = along.tag[-1]
                                newaxis = along.attrib.get('Type', 'other')
                                newaxis = TIFF.AXES_LABELS[newaxis]
                                if 'Start' in along.attrib:
                                    step = float(along.attrib.get('Step', 1))
                                    start = float(along.attrib['Start'])
                                    stop = float(along.attrib['End']) + step
                                    labels = numpy.arange(start, stop, step)
                                else:
                                    labels = [
                                        label.text
                                        for label in along
                                        if label.tag.endswith('Label')
                                    ]
                                modulo[axis] = (newaxis, labels)

            if not element.tag.endswith('Image'):
                continue

            attr = element.attrib
            name = attr.get('Name', None)

            for pixels in element:
                if not pixels.tag.endswith('Pixels'):
                    continue
                attr = pixels.attrib
                # dtype = attr.get('PixelType', None)
                axes = ''.join(reversed(attr['DimensionOrder']))
                shape = idxshape = [int(attr['Size' + ax]) for ax in axes]
                size = product(shape[:-2])
                ifds = None
                spp = 1  # samples per pixel
                for data in pixels:
                    if data.tag.endswith('Channel'):
                        attr = data.attrib
                        if ifds is None:
                            spp = int(attr.get('SamplesPerPixel', spp))
                            ifds = [None] * (size // spp)
                            if spp > 1:
                                # correct channel dimension for spp
                                idxshape = [
                                    shape[i] // spp if ax == 'C' else shape[i]
                                    for i, ax in enumerate(axes)]
                        elif int(attr.get('SamplesPerPixel', 1)) != spp:
                            raise ValueError('OME series: cannot handle '
                                             'differing SamplesPerPixel')
                        continue
                    if ifds is None:
                        ifds = [None] * (size // spp)
                    if not data.tag.endswith('TiffData'):
                        continue
                    attr = data.attrib
                    ifd = int(attr.get('IFD', 0))
                    num = int(attr.get('NumPlanes', 1 if 'IFD' in attr else 0))
                    num = int(attr.get('PlaneCount', num))
                    idx = [int(attr.get('First' + ax, 0)) for ax in axes[:-2]]
                    try:
                        idx = numpy.ravel_multi_index(idx, idxshape[:-2])
                    except ValueError:
                        # ImageJ produces invalid ome-xml when cropping
                        log_warning('OME series: invalid TiffData index')
                        continue
                    for uuid in data:
                        if not uuid.tag.endswith('UUID'):
                            continue
                        if root_uuid is None and uuid.text is not None:
                            # no global UUID, use this file
                            root_uuid = uuid.text
                            self._files[root_uuid] = self._files[None]
                        elif uuid.text not in self._files:
                            if not self._multifile:
                                # abort reading multifile OME series
                                # and fall back to generic series
                                return []
                            fname = uuid.attrib['FileName']
                            try:
                                tif = TiffFile(os.path.join(dirname, fname))
                                tif.pages.cache = True
                                tif.pages.useframes = True
                                tif.pages.keyframe = 0
                                tif.pages._load(keyframe=None)
                            except (IOError, FileNotFoundError, ValueError):
                                log_warning(
                                    "OME series: failed to read '%s'", fname)
                                break
                            self._files[uuid.text] = tif
                            tif.close()
                        pages = self._files[uuid.text].pages
                        try:
                            for i in range(num if num else len(pages)):
                                ifds[idx + i] = pages[ifd + i]
                        except IndexError:
                            log_warning('OME series: index out of range')
                        # only process first UUID
                        break
                    else:
                        pages = self.pages
                        try:
                            for i in range(num if num else
                                           min(len(pages), len(ifds))):
                                ifds[idx + i] = pages[ifd + i]
                        except IndexError:
                            log_warning('OME series: index out of range')

                if all(i is None for i in ifds):
                    # skip images without data
                    continue

                # find a keyframe
                keyframe = None
                for i in ifds:
                    # try find a TiffPage
                    if i and i == i.keyframe:
                        keyframe = i
                        break
                if keyframe is None:
                    # reload a TiffPage from file
                    for i, keyframe in enumerate(ifds):
                        if keyframe:
                            keyframe.parent.pages.keyframe = keyframe.index
                            keyframe = keyframe.parent.pages[keyframe.index]
                            ifds[i] = keyframe
                            break

                # move channel axis to match PlanarConfiguration storage
                # TODO: is this a bug or a inconsistency in the OME spec?
                if spp > 1:
                    if keyframe.planarconfig == 1 and axes[-1] != 'C':
                        i = axes.index('C')
                        axes = axes[:i] + axes[i + 1:] + axes[i: i + 1]
                        shape = shape[:i] + shape[i + 1:] + shape[i: i + 1]

                # FIXME: this implementation assumes the last dimensions are
                # stored in TIFF pages. Apparently that is not always the case.
                # For now, verify that shapes of keyframe and series match
                # If not, skip series.
                if keyframe.shape != tuple(shape[-len(keyframe.shape):]):
                    log_warning('OME series: incompatible page shape %s; '
                                'expected %s', keyframe.shape,
                                tuple(shape[-len(keyframe.shape):]))
                    del ifds
                    continue

                # set a keyframe on all IFDs
                for i in ifds:
                    if i is not None:
                        try:
                            i.keyframe = keyframe
                        except RuntimeError as exception:
                            log_warning('OME series: %s', str(exception))

                series.append(
                    TiffPageSeries(ifds, shape, keyframe.dtype, axes,
                                   parent=self, name=name, kind='OME')
                )
                del ifds

        for serie in series:
            shape = list(serie.shape)
            for axis, (newaxis, labels) in modulo.items():
                i = serie.axes.index(axis)
                size = len(labels)
                if shape[i] == size:
                    serie.axes = serie.axes.replace(axis, newaxis, 1)
                else:
                    shape[i] //= size
                    shape.insert(i + 1, size)
                    serie.axes = serie.axes.replace(axis, axis + newaxis, 1)
            serie.shape = tuple(shape)

        # squeeze dimensions
        for serie in series:
            serie.shape, serie.axes = squeeze_axes(serie.shape, serie.axes)
        self.is_uniform = len(series) == 1
        return series

    def _series_lsm(self):
        """Return main and thumbnail series in LSM file."""
        lsmi = self.lsm_metadata
        axes = TIFF.CZ_LSMINFO_SCANTYPE[lsmi['ScanType']]
        if self.pages[0].photometric == 2:  # RGB; more than one channel
            axes = axes.replace('C', '').replace('XY', 'XYC')
        if lsmi.get('DimensionP', 0) > 1:
            axes += 'P'
        if lsmi.get('DimensionM', 0) > 1:
            axes += 'M'
        axes = axes[::-1]
        shape = tuple(int(lsmi[TIFF.CZ_LSMINFO_DIMENSIONS[i]]) for i in axes)
        name = lsmi.get('Name', '')
        pages = self.pages._getlist(slice(0, None, 2), validate=False)
        dtype = pages[0].dtype
        series = [
            TiffPageSeries(pages, shape, dtype, axes, name=name, kind='LSM')
        ]

        if self.pages[1].is_reduced:
            pages = self.pages._getlist(slice(1, None, 2), validate=False)
            dtype = pages[0].dtype
            cp = 1
            i = 0
            while cp < len(pages) and i < len(shape) - 2:
                cp *= shape[i]
                i += 1
            shape = shape[:i] + pages[0].shape
            axes = axes[:i] + 'CYX'
            series.append(
                TiffPageSeries(pages, shape, dtype, axes, name=name,
                               kind='LSMreduced')
            )

        self.is_uniform = False
        return series

    def _lsm_load_pages(self):
        """Load and fix all pages from LSM file."""
        # cache all pages to preserve corrected values
        pages = self.pages
        pages.cache = True
        pages.useframes = True
        # use first and second page as keyframes
        pages.keyframe = 1
        pages.keyframe = 0
        # load remaining pages as frames
        pages._load(keyframe=None)
        # fix offsets and bytecounts first
        # TODO: fix multiple conversions between lists and tuples
        self._lsm_fix_strip_offsets()
        self._lsm_fix_strip_bytecounts()
        # assign keyframes for data and thumbnail series
        keyframe = pages[0]
        for page in pages[::2]:
            page.keyframe = keyframe
        keyframe = pages[1]
        for page in pages[1::2]:
            page.keyframe = keyframe

    def _lsm_fix_strip_offsets(self):
        """Unwrap strip offsets for LSM files greater than 4 GB.

        Each series and position require separate unwrapping (undocumented).

        """
        if self.filehandle.size < 2**32:
            return

        pages = self.pages
        npages = len(pages)
        series = self.series[0]
        axes = series.axes

        # find positions
        positions = 1
        for i in 0, 1:
            if series.axes[i] in 'PM':
                positions *= series.shape[i]

        # make time axis first
        if positions > 1:
            ntimes = 0
            for i in 1, 2:
                if axes[i] == 'T':
                    ntimes = series.shape[i]
                    break
            if ntimes:
                div, mod = divmod(npages, 2 * positions * ntimes)
                if mod != 0:
                    raise RuntimeError('mod != 0')
                shape = (positions, ntimes, div, 2)
                indices = numpy.arange(product(shape)).reshape(shape)
                indices = numpy.moveaxis(indices, 1, 0)
        else:
            indices = numpy.arange(npages).reshape(-1, 2)

        # images of reduced page might be stored first
        if pages[0]._offsetscounts[0][0] > pages[1]._offsetscounts[0][0]:
            indices = indices[..., ::-1]

        # unwrap offsets
        wrap = 0
        previousoffset = 0
        for i in indices.flat:
            page = pages[int(i)]
            dataoffsets = []
            for currentoffset in page._offsetscounts[0]:
                if currentoffset < previousoffset:
                    wrap += 2**32
                dataoffsets.append(currentoffset + wrap)
                previousoffset = currentoffset
            page._offsetscounts = tuple(dataoffsets), page._offsetscounts[1]

    def _lsm_fix_strip_bytecounts(self):
        """Set databytecounts to size of compressed data.

        The StripByteCounts tag in LSM files contains the number of bytes
        for the uncompressed data.

        """
        pages = self.pages
        if pages[0].compression == 1:
            return
        # sort pages by first strip offset
        pages = sorted(pages, key=lambda p: p._offsetscounts[0][0])
        npages = len(pages) - 1
        for i, page in enumerate(pages):
            if page.index % 2:
                continue
            offsets, bytecounts = page._offsetscounts
            if i < npages:
                lastoffset = pages[i + 1]._offsetscounts[0][0]
            else:
                # LZW compressed strips might be longer than uncompressed
                lastoffset = min(offsets[-1] + 2 * bytecounts[-1],
                                 self._fh.size)
            bytecounts = list(bytecounts)
            for j in range(len(bytecounts) - 1):
                bytecounts[j] = offsets[j + 1] - offsets[j]
            bytecounts[-1] = lastoffset - offsets[-1]
            page._offsetscounts = offsets, tuple(bytecounts)

    def __getattr__(self, name):
        """Return 'is_flag' attributes from first page."""
        if name[3:] in TIFF.FILE_FLAGS:
            if not self.pages:
                return False
            value = bool(getattr(self.pages[0], name))
            setattr(self, name, value)
            return value
        raise AttributeError("'%s' object has no attribute '%s'"
                             % (self.__class__.__name__, name))

    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc_value, traceback):
        self.close()

    def __str__(self, detail=0, width=79):
        """Return string containing information about file.

        The detail parameter specifies the level of detail returned:

        0: file only.
        1: all series, first page of series and its tags.
        2: large tag values and file metadata.
        3: all pages.

        """
        info = [
            "TiffFile '%s'",
            format_size(self._fh.size),
            ''
            if byteorder_isnative(self.tiff.byteorder)
            else {'<': 'little-endian',
                  '>': 'big-endian'}[self.tiff.byteorder]
        ]
        if self.is_bigtiff:
            info.append('BigTiff')
        info.append(' '.join(f.lower() for f in self.flags))
        if len(self.pages) > 1:
            info.append('%i Pages' % len(self.pages))
        if len(self.series) > 1:
            info.append('%i Series' % len(self.series))
        if len(self._files) > 1:
            info.append('%i Files' % (len(self._files)))
        info = '  '.join(info)
        info = info.replace('    ', '  ').replace('   ', '  ')
        info = info % snipstr(self._fh.name, max(12, width + 2 - len(info)))
        if detail <= 0:
            return info
        info = [info]
        info.append('\n'.join(str(s) for s in self.series))
        if detail >= 3:
            info.extend(
                (
                    TiffPage.__str__(p, detail=detail, width=width)
                    for p in self.pages
                    if p is not None
                )
            )
        elif self.series:
            info.extend(
                (
                    TiffPage.__str__(s.pages[0], detail=detail, width=width)
                    for s in self.series
                    if s.pages[0] is not None
                )
            )
        elif self.pages and self.pages[0]:
            info.append(
                TiffPage.__str__(self.pages[0], detail=detail, width=width)
            )
        if detail >= 2:
            for name in sorted(self.flags):
                if hasattr(self, name + '_metadata'):
                    m = getattr(self, name + '_metadata')
                    if m:
                        info.append(
                            '%s_METADATA\n%s'
                            % (name.upper(),
                               pformat(m, width=width, height=detail * 12))
                        )
        return '\n\n'.join(info).replace('\n\n\n', '\n\n')

    @lazyattr
    def flags(self):
        """Return set of file flags."""
        return set(
            name.lower()
            for name in sorted(TIFF.FILE_FLAGS)
            if getattr(self, 'is_' + name)
        )

    @lazyattr
    def is_mdgel(self):
        """File has MD Gel format."""
        # TODO: this likely reads the second page from file
        try:
            ismdgel = self.pages[0].is_mdgel or self.pages[1].is_mdgel
            if ismdgel:
                self.is_uniform = False
            return ismdgel
        except IndexError:
            return False

    @lazyattr
    def is_uniform(self):
        """Return if file contains a uniform series of pages."""
        # the hashes of IFDs 0, 7, and -1 are the same
        pages = self.pages
        page = pages[0]
        if page.is_scanimage or page.is_nih:
            return True
        try:
            useframes = pages.useframes
            pages.useframes = False
            h = page.hash
            for i in (1, 7, -1):
                if pages[i].aspage().hash != h:
                    return False
        except IndexError:
            return False
        finally:
            pages.useframes = useframes
        return True

    @property
    def is_appendable(self):
        """Return if pages can be appended to file without corrupting."""
        # TODO: check other formats
        return not (
            self.is_lsm
            or self.is_stk
            or self.is_imagej
            or self.is_fluoview
            or self.is_micromanager
        )

    @lazyattr
    def shaped_metadata(self):
        """Return tifffile metadata from JSON descriptions as dicts."""
        if not self.is_shaped:
            return None
        return tuple(
            json_description_metadata(s.pages[0].is_shaped)
            for s in self.series
            if s.kind.lower() == 'shaped'
        )

    @property
    def ome_metadata(self):
        """Return OME XML."""
        if not self.is_ome:
            return None
        # return xml2dict(self.pages[0].description)['OME']
        return self.pages[0].description

    @property
    def lsm_metadata(self):
        """Return LSM metadata from CZ_LSMINFO tag as dict."""
        if not self.is_lsm:
            return None
        return self.pages[0].tags['CZ_LSMINFO'].value

    @lazyattr
    def stk_metadata(self):
        """Return STK metadata from UIC tags as dict."""
        if not self.is_stk:
            return None
        page = self.pages[0]
        tags = page.tags
        result = {}
        result['NumberPlanes'] = tags['UIC2tag'].count
        if page.description:
            result['PlaneDescriptions'] = page.description.split('\0')
            # result['plane_descriptions'] = stk_description_metadata(
            #    page.image_description)
        if 'UIC1tag' in tags:
            result.update(tags['UIC1tag'].value)
        if 'UIC3tag' in tags:
            result.update(tags['UIC3tag'].value)  # wavelengths
        if 'UIC4tag' in tags:
            result.update(tags['UIC4tag'].value)  # override uic1 tags
        uic2tag = tags['UIC2tag'].value
        result['ZDistance'] = uic2tag['ZDistance']
        result['TimeCreated'] = uic2tag['TimeCreated']
        result['TimeModified'] = uic2tag['TimeModified']
        try:
            result['DatetimeCreated'] = numpy.array(
                [julian_datetime(*dt) for dt in
                 zip(uic2tag['DateCreated'], uic2tag['TimeCreated'])],
                dtype='datetime64[ns]')
            result['DatetimeModified'] = numpy.array(
                [julian_datetime(*dt) for dt in
                 zip(uic2tag['DateModified'], uic2tag['TimeModified'])],
                dtype='datetime64[ns]')
        except ValueError as exc:
            log_warning('STK metadata: %s: %s', exc.__class__.__name__, exc)
        return result

    @lazyattr
    def imagej_metadata(self):
        """Return consolidated ImageJ metadata as dict."""
        if not self.is_imagej:
            return None
        page = self.pages[0]
        result = imagej_description_metadata(page.is_imagej)
        if 'IJMetadata' in page.tags:
            try:
                result.update(page.tags['IJMetadata'].value)
            except Exception:
                pass
        return result

    @lazyattr
    def fluoview_metadata(self):
        """Return consolidated FluoView metadata as dict."""
        if not self.is_fluoview:
            return None
        result = {}
        page = self.pages[0]
        result.update(page.tags['MM_Header'].value)
        # TODO: read stamps from all pages
        result['Stamp'] = page.tags['MM_Stamp'].value
        # skip parsing image description; not reliable
        # try:
        #     t = fluoview_description_metadata(page.image_description)
        #     if t is not None:
        #         result['ImageDescription'] = t
        # except Exception as exc:
        #     log_warning('FluoView metadata: '
        #                 'failed to parse image description (%s)', str(exc))
        return result

    @lazyattr
    def nih_metadata(self):
        """Return NIH Image metadata from NIHImageHeader tag as dict."""
        if not self.is_nih:
            return None
        return self.pages[0].tags['NIHImageHeader'].value

    @lazyattr
    def fei_metadata(self):
        """Return FEI metadata from SFEG or HELIOS tags as dict."""
        if not self.is_fei:
            return None
        tags = self.pages[0].tags
        if 'FEI_SFEG' in tags:
            return tags['FEI_SFEG'].value
        if 'FEI_HELIOS' in tags:
            return tags['FEI_HELIOS'].value
        return None

    @property
    def sem_metadata(self):
        """Return SEM metadata from CZ_SEM tag as dict."""
        if not self.is_sem:
            return None
        return self.pages[0].tags['CZ_SEM'].value

    @lazyattr
    def sis_metadata(self):
        """Return Olympus SIS metadata from SIS and INI tags as dict."""
        if not self.is_sis:
            return None
        tags = self.pages[0].tags
        result = {}
        try:
            result.update(tags['OlympusINI'].value)
        except Exception:
            pass
        try:
            result.update(tags['OlympusSIS'].value)
        except Exception:
            pass
        return result

    @lazyattr
    def mdgel_metadata(self):
        """Return consolidated metadata from MD GEL tags as dict."""
        for page in self.pages[:2]:
            if 'MDFileTag' in page.tags:
                tags = page.tags
                break
        else:
            return None
        result = {}
        for code in range(33445, 33453):
            name = TIFF.TAGS[code]
            if name not in tags:
                continue
            result[name[2:]] = tags[name].value
        return result

    @property
    def andor_metadata(self):
        """Return Andor tags as dict."""
        return self.pages[0].andor_tags

    @property
    def epics_metadata(self):
        """Return EPICS areaDetector tags as dict."""
        return self.pages[0].epics_tags

    @property
    def tvips_metadata(self):
        """Return TVIPS tag as dict."""
        if not self.is_tvips:
            return None
        return self.pages[0].tags['TVIPS'].value

    @lazyattr
    def metaseries_metadata(self):
        """Return MetaSeries metadata from image description as dict."""
        if not self.is_metaseries:
            return None
        return metaseries_description_metadata(self.pages[0].description)

    @lazyattr
    def pilatus_metadata(self):
        """Return Pilatus metadata from image description as dict."""
        if not self.is_pilatus:
            return None
        return pilatus_description_metadata(self.pages[0].description)

    @lazyattr
    def micromanager_metadata(self):
        """Return consolidated MicroManager metadata as dict."""
        if not self.is_micromanager:
            return None
        # from file header
        result = read_micromanager_metadata(self._fh)
        # from tag
        result.update(self.pages[0].tags['MicroManagerMetadata'].value)
        return result

    @lazyattr
    def scanimage_metadata(self):
        """Return ScanImage non-varying frame and ROI metadata as dict."""
        if not self.is_scanimage:
            return None
        result = {}
        try:
            framedata, roidata = read_scanimage_metadata(self._fh)
            result['FrameData'] = framedata
            result.update(roidata)
        except ValueError:
            pass
        # TODO: scanimage_artist_metadata
        try:
            result['Description'] = scanimage_description_metadata(
                self.pages[0].description)
        except Exception as exc:
            log_warning('ScanImage metadata: %s: %s',
                        exc.__class__.__name__, exc)
        return result

    @property
    def geotiff_metadata(self):
        """Return GeoTIFF metadata from first page as dict."""
        if not self.is_geotiff:
            return None
        return self.pages[0].geotiff_tags


class TiffPages(object):
    """Sequence of TIFF image file directories (IFD chain).

    Instances of TiffPages have a state (cache, keyframe, etc.) and are not
    thread-safe.

    """

    def __init__(self, parent):
        """Initialize instance and read first TiffPage from file.

        If parent is a TiffFile, the file position must be at an offset to an
        offset to a TiffPage. If parent is a TiffPage, page offsets are read
        from the SubIFDs tag.

        """
        self.parent = None
        self.pages = []  # cache of TiffPages, TiffFrames, or their offsets
        self._indexed = False  # True if offsets to all pages were read
        self._cached = False  # True if all pages were read into cache
        self._tiffpage = TiffPage  # class used for reading pages
        self._keyframe = None  # current page that is used as keyframe
        self._cache = False  # do not cache frames or pages (if not keyframe)
        self._nextpageoffset = None

        if isinstance(parent, TiffFile):
            # read offset to first page from current file position
            self.parent = parent
            fh = parent.filehandle
            self._nextpageoffset = fh.tell()
            offset = struct.unpack(parent.tiff.ifdoffsetformat,
                                   fh.read(parent.tiff.ifdoffsetsize))[0]
        elif 'SubIFDs' not in parent.tags:
            self._indexed = True
            return
        else:
            # use offsets from SubIFDs tag
            self.parent = parent.parent
            fh = self.parent.filehandle
            offsets = parent.tags['SubIFDs'].value
            offset = offsets[0]

        if offset == 0:
            log_warning('TiffPages: file contains no pages')
            self._indexed = True
            return
        if offset >= fh.size:
            log_warning('TiffPages: invalid page offset (%i)', offset)
            self._indexed = True
            return

        # read and cache first page
        fh.seek(offset)
        page = TiffPage(self.parent, index=0)
        self.pages.append(page)
        self._keyframe = page
        if self._nextpageoffset is None:
            # offsets from SubIFDs tag
            self.pages.extend(offsets[1:])
            self._indexed = True
            self._cached = True

    @property
    def cache(self):
        """Return if pages/frames are currently being cached."""
        return self._cache

    @cache.setter
    def cache(self, value):
        """Enable or disable caching of pages/frames. Clear cache if False."""
        value = bool(value)
        if self._cache and not value:
            self._clear()
        self._cache = value

    @property
    def useframes(self):
        """Return if currently using TiffFrame (True) or TiffPage (False)."""
        return self._tiffpage == TiffFrame and TiffFrame is not TiffPage

    @useframes.setter
    def useframes(self, value):
        """Set to use TiffFrame (True) or TiffPage (False)."""
        self._tiffpage = TiffFrame if value else TiffPage

    @property
    def keyframe(self):
        """Return current keyframe."""
        return self._keyframe

    @keyframe.setter
    def keyframe(self, index):
        """Set current keyframe. Load TiffPage from file if necessary."""
        index = int(index)
        if index < 0:
            index %= len(self)
        if self._keyframe.index == index:
            return
        if index == 0:
            self._keyframe = self.pages[0]
            return
        if self._indexed or index < len(self.pages):
            page = self.pages[index]
            if isinstance(page, TiffPage):
                self._keyframe = page
                return
            if isinstance(page, TiffFrame):
                # remove existing TiffFrame
                self.pages[index] = page.offset
        # load TiffPage from file
        tiffpage = self._tiffpage
        self._tiffpage = TiffPage
        try:
            self._keyframe = self._getitem(index)
        finally:
            self._tiffpage = tiffpage
        # always cache keyframes
        self.pages[index] = self._keyframe

    @property
    def next_page_offset(self):
        """Return offset where offset to a new page can be stored."""
        if not self._indexed:
            self._seek(-1)
        return self._nextpageoffset

    def _load(self, keyframe=True):
        """Read all remaining pages from file."""
        if self._cached:
            return
        pages = self.pages
        if not pages:
            return
        if not self._indexed:
            self._seek(-1)
        if not self._cache:
            return
        fh = self.parent.filehandle
        if keyframe is not None:
            keyframe = self._keyframe
        for i, page in enumerate(pages):
            if isinstance(page, inttypes):
                fh.seek(page)
                page = self._tiffpage(self.parent, index=i, keyframe=keyframe)
                pages[i] = page
        self._cached = True

    def _load_virtual_frames(self):
        """Calculate virtual TiffFrames."""
        pages = self.pages
        try:
            if sys.version_info[0] == 2:
                raise ValueError('not supported on Python 2')
            if len(pages) > 1:
                raise ValueError('pages already loaded')
            page = pages[0]
            bytecounts = page._offsetscounts[1]
            if len(bytecounts) != 1:
                raise ValueError('data not contiguous')
            self._seek(4)
            delta = pages[2] - pages[1]
            if pages[3] - pages[2] != delta or pages[4] - pages[3] != delta:
                raise ValueError('page offsets not equidistant')
            page1 = self._getitem(1, validate=page.hash)
            offsetoffset = page1._offsetscounts[0][0] - page1.offset
            if offsetoffset < 0 or offsetoffset > delta:
                raise ValueError('page offsets not equidistant')
            pages = [page, page1]
            filesize = self.parent.filehandle.size - delta
            for index, offset in enumerate(range(page1.offset + delta,
                                                 filesize, delta)):
                offsets = [offset + offsetoffset]
                offset = offset if offset < 2**31 else None
                pages.append(
                    TiffFrame(
                        parent=page.parent,
                        index=index + 2,
                        offset=None,
                        offsets=offsets,
                        bytecounts=bytecounts,
                        keyframe=page)
                )
            self.pages = pages
            self._cache = True
            self._cached = True
            self._indexed = True
        except Exception as exc:
            log_warning(
                'TiffPages: failed to load virtual frames: %s', str(exc))

    def _clear(self, fully=True):
        """Delete all but first page from cache. Set keyframe to first page."""
        pages = self.pages
        if not pages:
            return
        self._keyframe = pages[0]
        if fully:
            # delete all but first TiffPage/TiffFrame
            for i, page in enumerate(pages[1:]):
                if not isinstance(page, inttypes) and page.offset is not None:
                    pages[i + 1] = page.offset
        elif TiffFrame is not TiffPage:
            # delete only TiffFrames
            for i, page in enumerate(pages):
                if isinstance(page, TiffFrame) and page.offset is not None:
                    pages[i] = page.offset
        self._cached = False

    def _seek(self, index, maxpages=None):
        """Seek file to offset of page specified by index."""
        pages = self.pages
        lenpages = len(pages)
        if lenpages == 0:
            raise IndexError('index out of range')

        fh = self.parent.filehandle
        if fh.closed:
            raise ValueError('seek of closed file')

        if self._indexed or 0 <= index < lenpages:
            page = pages[index]
            offset = page if isinstance(page, inttypes) else page.offset
            fh.seek(offset)
            return

        tiff = self.parent.tiff
        offsetformat = tiff.ifdoffsetformat
        offsetsize = tiff.ifdoffsetsize
        tagnoformat = tiff.tagnoformat
        tagnosize = tiff.tagnosize
        tagsize = tiff.tagsize
        unpack = struct.unpack

        page = pages[-1]
        offset = page if isinstance(page, inttypes) else page.offset

        if maxpages is None:
            maxpages = 2**22
        while lenpages < maxpages:
            # read offsets to pages from file until index is reached
            fh.seek(offset)
            # skip tags
            try:
                tagno = unpack(tagnoformat, fh.read(tagnosize))[0]
                if tagno > 4096:
                    raise TiffFileError(
                        'suspicious number of tags: %i' % tagno)
            except Exception:
                log_warning('TiffPages: corrupted tag list of page %i @ %i',
                            lenpages, offset)
                del pages[-1]
                lenpages -= 1
                self._indexed = True
                break
            self._nextpageoffset = offset + tagnosize + tagno * tagsize
            fh.seek(self._nextpageoffset)

            # read offset to next page
            offset = unpack(offsetformat, fh.read(offsetsize))[0]
            if offset == 0:
                self._indexed = True
                break
            if offset >= fh.size:
                log_warning('TiffPages: invalid page offset (%i)', offset)
                self._indexed = True
                break

            pages.append(offset)
            lenpages += 1
            if 0 <= index < lenpages:
                break

            # detect some circular references
            if lenpages == 100:
                for p in pages[:-1]:
                    if offset == (p if isinstance(p, inttypes) else p.offset):
                        raise TiffFileError('invalid circular IFD reference')

        if index >= lenpages:
            raise IndexError('index out of range')

        page = pages[index]
        fh.seek(page if isinstance(page, inttypes) else page.offset)

    def _getlist(self, key=None, useframes=True, validate=True):
        """Return specified pages as list of TiffPages or TiffFrames.

        The first item is a TiffPage, and is used as a keyframe for
        following TiffFrames.

        """
        getitem = self._getitem
        _useframes = self.useframes

        if key is None:
            key = iter(range(len(self)))
        elif isinstance(key, Iterable):
            key = iter(key)
        elif isinstance(key, slice):
            start, stop, _ = key.indices(2**31 - 1)
            if not self._indexed and max(stop, start) > len(self.pages):
                self._seek(-1)
            key = iter(range(*key.indices(len(self.pages))))
        elif isinstance(key, inttypes):
            # return single TiffPage
            self.useframes = False
            if key == 0:
                return [self.pages[key]]
            try:
                return [getitem(key)]
            finally:
                self.useframes = _useframes
        else:
            raise TypeError('key must be an integer, slice, or iterable')

        # use first page as keyframe
        keyframe = self._keyframe
        self.keyframe = next(key)
        if validate:
            validate = self._keyframe.hash
        if useframes:
            self.useframes = True
        try:
            pages = [getitem(i, validate) for i in key]
            pages.insert(0, self._keyframe)
        finally:
            # restore state
            self._keyframe = keyframe
            if useframes:
                self.useframes = _useframes

        return pages

    def _getitem(self, key, validate=False):
        """Return specified page from cache or file."""
        key = int(key)
        pages = self.pages

        if key < 0:
            key %= len(self)
        elif self._indexed and key >= len(pages):
            raise IndexError(
                'index %i out of range(%i)' % (key, len(pages)))

        if key < len(pages):
            page = pages[key]
            if self._cache:
                if not isinstance(page, inttypes):
                    if validate and validate != page.hash:
                        raise RuntimeError('page hash mismatch')
                    return page
            elif isinstance(page, (TiffPage, self._tiffpage)):
                if validate and validate != page.hash:
                    raise RuntimeError('page hash mismatch')
                return page

        self._seek(key)
        page = self._tiffpage(self.parent, index=key, keyframe=self._keyframe)
        if validate and validate != page.hash:
            raise RuntimeError('page hash mismatch')
        if self._cache:
            pages[key] = page
        return page

    def __getitem__(self, key):
        """Return specified page(s)."""
        pages = self.pages
        getitem = self._getitem

        if isinstance(key, inttypes):
            if key == 0:
                return pages[key]
            return getitem(key)

        if isinstance(key, slice):
            start, stop, _ = key.indices(2**31 - 1)
            if not self._indexed and max(stop, start) > len(pages):
                self._seek(-1)
            return [getitem(i) for i in range(*key.indices(len(pages)))]

        if isinstance(key, Iterable):
            return [getitem(k) for k in key]

        raise TypeError('key must be an integer, slice, or iterable')

    def __iter__(self):
        """Return iterator over all pages."""
        i = 0
        while True:
            try:
                yield self._getitem(i)
                i += 1
            except IndexError:
                break
        if self._cache:
            self._cached = True

    def __bool__(self):
        """Return True if file contains any pages."""
        return len(self.pages) > 0

    def __len__(self):
        """Return number of pages in file."""
        if not self._indexed:
            self._seek(-1)
        return len(self.pages)


class TiffPage(object):
    """TIFF image file directory (IFD).

    Attributes
    ----------
    index : int
        Index of page in file.
    dtype : numpy.dtype or None
        Data type (native byte order) of the image in IFD.
    shape : tuple
        Dimensions of the image in IFD.
    axes : str
        Axes label codes:
        'X' width, 'Y' height, 'S' sample, 'I' image series|page|plane,
        'Z' depth, 'C' color|em-wavelength|channel, 'E' ex-wavelength|lambda,
        'T' time, 'R' region|tile, 'A' angle, 'P' phase, 'H' lifetime,
        'L' exposure, 'V' event, 'Q' unknown, '_' missing
    tags : dict
        Dictionary of tags in IFD. {tag.name: TiffTag}
    colormap : numpy.ndarray
        Color look up table, if exists.

    All attributes are read-only.

    Notes
    -----
    The internal, normalized '_shape' attribute is 6 dimensional:

    0 : number planes/images  (stk, ij).
    1 : planar samplesperpixel.
    2 : imagedepth Z  (sgi).
    3 : imagelength Y.
    4 : imagewidth X.
    5 : contig samplesperpixel.

    """

    # default properties; will be updated from tags
    subfiletype = 0
    imagewidth = 0
    imagelength = 0
    imagedepth = 1
    tilewidth = 0
    tilelength = 0
    tiledepth = 1
    bitspersample = 1
    samplesperpixel = 1
    sampleformat = 1
    rowsperstrip = 2**32 - 1
    compression = 1
    planarconfig = 1
    fillorder = 1
    photometric = 0
    predictor = 1
    extrasamples = 1
    colormap = None
    software = ''
    description = ''
    description1 = ''
    nodata = 0

    def __init__(self, parent, index, keyframe=None):
        """Initialize instance from file.

        The file handle position must be at offset to a valid IFD.

        """
        self.parent = parent
        self.index = index
        self.shape = ()
        self._shape = ()
        self.dtype = None
        self._dtype = None
        self.axes = ''
        self.tags = tags = {}
        self.dataoffsets = ()
        self.databytecounts = ()

        tiff = parent.tiff

        # read TIFF IFD structure and its tags from file
        fh = parent.filehandle
        self.offset = fh.tell()  # offset to this IFD
        try:
            tagno = struct.unpack(
                tiff.tagnoformat, fh.read(tiff.tagnosize))[0]
            if tagno > 4096:
                raise TiffFileError('TiffPage %i: suspicious number of tags'
                                    % self.index)
        except Exception:
            raise TiffFileError(
                'TiffPage %i: corrupted tag list at offset %i'
                % (self.index, self.offset))

        tagoffset = self.offset + tiff.tagnosize  # fh.tell()
        tagsize = tiff.tagsize
        tagindex = -tagsize

        data = fh.read(tagsize * tagno)

        for _ in range(tagno):
            tagindex += tagsize
            try:
                tag = TiffTag(parent, data[tagindex: tagindex + tagsize],
                              tagoffset + tagindex)
            except TiffFileError as exc:
                log_warning('TiffPage %i: %s: %s', self.index,
                            exc.__class__.__name__, exc)
                continue
            tagname = tag.name
            if tagname not in tags:
                name = tagname
                tags[name] = tag
            else:
                # some files contain multiple tags with same code
                # e.g. MicroManager files contain two ImageDescription tags
                i = 1
                while i < 32:
                    name = '%s%i' % (tagname, i)
                    if name not in tags:
                        tags[name] = tag
                        break
                    i += 1
                else:
                    log_warning("TiffPage %i: suspicious number of '%s' tags",
                                self.index, tagname)
            name = TIFF.TAG_ATTRIBUTES.get(name, '')
            if name:
                if name[:3] in 'sof des' and not isinstance(tag.value, str):
                    pass  # wrong string type for software, description
                else:
                    setattr(self, name, tag.value)

        if not tags:
            return  # found in FIBICS

        if 'SubfileType' in tags and self.subfiletype == 0:
            sft = tags['SubfileType'].value
            if sft == 2:
                self.subfiletype = 0b1  # reduced image
            elif sft == 3:
                self.subfiletype = 0b10  # multi-page

        # consolidate private tags; remove them from self.tags
        if self.is_andor:
            self.andor_tags
        elif self.is_epics:
            self.epics_tags
        # elif self.is_ndpi:
        #     self.ndpi_tags

        if self.is_sis and 'GPSTag' in tags:
            # TODO: can't change tag.name
            tags['OlympusSIS2'] = tags['GPSTag']
            del tags['GPSTag']

        if self.is_lsm or (self.index and self.parent.is_lsm):
            # correct non standard LSM bitspersample tags
            tags['BitsPerSample']._fix_lsm_bitspersample(self)
            if self.compression == 1 and self.predictor != 1:
                # work around bug in LSM510 software
                self.predictor = 1

        if self.is_vista or (self.index and self.parent.is_vista):
            # ISS Vista writes wrong ImageDepth tag
            self.imagedepth = 1

        if self.is_stk and 'UIC1tag' in tags and not tags['UIC1tag'].value:
            # read UIC1tag now that plane count is known
            uic1tag = tags['UIC1tag']
            fh.seek(uic1tag.valueoffset)
            tags['UIC1tag'].value = read_uic1tag(
                fh, tiff.byteorder, uic1tag.dtype,
                uic1tag.count, None, tags['UIC2tag'].count)

        if 'IJMetadata' in tags:
            # decode IJMetadata tag
            try:
                tags['IJMetadata'].value = imagej_metadata(
                    tags['IJMetadata'].value,
                    tags['IJMetadataByteCounts'].value,
                    tiff.byteorder)
            except Exception as exc:
                log_warning('TiffPage %i: %s: %s', self.index,
                            exc.__class__.__name__, exc)

        if 'BitsPerSample' in tags:
            tag = tags['BitsPerSample']
            if tag.count == 1:
                self.bitspersample = tag.value
            else:
                # LSM might list more items than samplesperpixel
                value = tag.value[:self.samplesperpixel]
                if any(v - value[0] for v in value):
                    self.bitspersample = value
                else:
                    self.bitspersample = value[0]

        if 'SampleFormat' in tags:
            tag = tags['SampleFormat']
            if tag.count == 1:
                self.sampleformat = tag.value
            else:
                value = tag.value[:self.samplesperpixel]
                if any(v - value[0] for v in value):
                    self.sampleformat = value
                else:
                    self.sampleformat = value[0]

        if 'TileWidth' in tags:
            self.rowsperstrip = None
        elif 'ImageLength' in tags:
            if 'RowsPerStrip' not in tags or tags['RowsPerStrip'].count > 1:
                self.rowsperstrip = self.imagelength
            self.rowsperstrip = min(self.rowsperstrip, self.imagelength)
            # self.stripsperimage = int(math.floor(
            #    float(self.imagelength + self.rowsperstrip - 1) /
            #    self.rowsperstrip))

        # determine dtype
        dtype = self.sampleformat, self.bitspersample
        dtype = TIFF.SAMPLE_DTYPES.get(dtype, None)
        if dtype is not None:
            dtype = numpy.dtype(dtype)
        self.dtype = self._dtype = dtype

        # determine shape of data
        imagelength = self.imagelength
        imagewidth = self.imagewidth
        imagedepth = self.imagedepth
        samplesperpixel = self.samplesperpixel

        if self.is_stk:
            if imagedepth != 1:
                raise ValueError('STK imagedepth must be 1')
            uictag = tags['UIC2tag'].value
            planes = tags['UIC2tag'].count
            if self.planarconfig == 1:
                self._shape = (
                    planes,
                    1,
                    1,
                    imagelength,
                    imagewidth,
                    samplesperpixel,
                )
                if samplesperpixel == 1:
                    self.shape = (planes, imagelength, imagewidth)
                    self.axes = 'YX'
                else:
                    self.shape = (
                        planes,
                        imagelength,
                        imagewidth,
                        samplesperpixel,
                    )
                    self.axes = 'YXS'
            else:
                self._shape = (
                    planes,
                    samplesperpixel,
                    1,
                    imagelength,
                    imagewidth,
                    1,
                )
                if samplesperpixel == 1:
                    self.shape = (planes, imagelength, imagewidth)
                    self.axes = 'YX'
                else:
                    self.shape = (
                        planes,
                        samplesperpixel,
                        imagelength,
                        imagewidth,
                    )
                    self.axes = 'SYX'
            # detect type of series
            if planes == 1:
                self.shape = self.shape[1:]
            elif numpy.all(uictag['ZDistance'] != 0):
                self.axes = 'Z' + self.axes
            elif numpy.all(numpy.diff(uictag['TimeCreated']) != 0):
                self.axes = 'T' + self.axes
            else:
                self.axes = 'I' + self.axes
        elif self.photometric == 2 or samplesperpixel > 1:  # PHOTOMETRIC.RGB
            if self.planarconfig == 1:
                self._shape = (
                    1,
                    1,
                    imagedepth,
                    imagelength,
                    imagewidth,
                    samplesperpixel,
                )
                if imagedepth == 1:
                    self.shape = (imagelength, imagewidth, samplesperpixel)
                    self.axes = 'YXS'
                else:
                    self.shape = (
                        imagedepth,
                        imagelength,
                        imagewidth,
                        samplesperpixel,
                    )
                    self.axes = 'ZYXS'
            else:
                self._shape = (
                    1,
                    samplesperpixel,
                    imagedepth,
                    imagelength,
                    imagewidth,
                    1,
                )
                if imagedepth == 1:
                    self.shape = (samplesperpixel, imagelength, imagewidth)
                    self.axes = 'SYX'
                else:
                    self.shape = (
                        samplesperpixel,
                        imagedepth,
                        imagelength,
                        imagewidth,
                    )
                    self.axes = 'SZYX'
        else:
            self._shape = (1, 1, imagedepth, imagelength, imagewidth, 1)
            if imagedepth == 1:
                self.shape = (imagelength, imagewidth)
                self.axes = 'YX'
            else:
                self.shape = (imagedepth, imagelength, imagewidth)
                self.axes = 'ZYX'

        # dataoffsets and databytecounts
        if 'TileOffsets' in tags:
            self.dataoffsets = tags['TileOffsets'].value
        elif 'StripOffsets' in tags:
            self.dataoffsets = tags['StripOffsets'].value
        if 'TileByteCounts' in tags:
            self.databytecounts = tags['TileByteCounts'].value
        elif 'StripByteCounts' in tags:
            self.databytecounts = tags['StripByteCounts'].value
        else:
            self.databytecounts = (
                product(self.shape) * (self.bitspersample // 8),)
            if self.compression != 1:
                log_warning('TiffPage %i: ByteCounts tag is missing',
                            self.index)

        if 'GDAL_NODATA' in tags:
            try:
                pytype = type(dtype.type(0).item())
                self.nodata = pytype(tags['GDAL_NODATA'].value)
            except Exception:
                pass

    @lazyattr
    def decode(self):
        """Decode single tile or strip."""
        raise NotImplementedError()
        # TODO: retun function to decode single strips or tiles

    def asarray(self, out=None, squeeze=True, lock=None, reopen=True,
                maxsize=None, maxworkers=None, validate=True):
        """Read image data from file and return as numpy array.

        Raise ValueError if format is unsupported.

        Parameters
        ----------
        out : numpy.ndarray, str, or file-like object
            Buffer where image data will be saved.
            If None (default), a new array will be created.
            If numpy.ndarray, a writable array of compatible dtype and shape.
            If 'memmap', directly memory-map the image data in the TIFF file
            if possible; else create a memory-mapped array in a temporary file.
            If str or open file, the file name or file object used to
            create a memory-map to an array stored in a binary file on disk.
        squeeze : bool
            If True (default), all length-1 dimensions (except X and Y) are
            squeezed out from the array.
            If False, the shape of the returned array might be different from
            the page.shape.
        lock : {RLock, NullContext}
            A reentrant lock used to synchronize seeks and reads from file.
            If None (default), the lock of the parent's filehandle is used.
        reopen : bool
            If True (default) and the parent file handle is closed, the file
            is temporarily re-opened and closed if no exception occurs.
        maxsize: int
            Maximum size of data before a ValueError is raised.
            Can be used to catch DOS. Default: 16 TB.
        maxworkers : int or None
            Maximum number of threads to concurrently decode compressed
            segments. If None (default), up to half the CPU cores are used.
            See remarks in TiffFile.asarray.
        validate : bool
            If True (default), validate various parameters.
            If None, only validate parameters and return None.

        Returns
        -------
        numpy.ndarray
            Numpy array of decompressed, depredicted, and unpacked image data
            read from Strip/Tile Offsets/ByteCounts, formatted according to
            shape and dtype metadata found in tags and parameters.
            Photometric conversion, pre-multiplied alpha, orientation, and
            colorimetry corrections are not applied. Specifically, CMYK images
            are not converted to RGB, MinIsWhite images are not inverted,
            and color palettes are not applied. An exception are YCbCr JPEG
            compressed images, which will be converted to RGB.

        """
        # properties from TiffPage or TiffFrame
        fh = self.parent.filehandle
        byteorder = self.parent.tiff.byteorder
        offsets, bytecounts = self._offsetscounts
        self_ = self
        self = self.keyframe  # self or keyframe

        if not self._shape or product(self._shape) == 0:
            return None

        tags = self.tags

        if validate or validate is None:
            if maxsize is None:
                maxsize = 2**44
            if maxsize and product(self._shape) > maxsize:
                raise ValueError('TiffPage %i: data are too large %s'
                                 % (self.index, str(self._shape)))
            if self.dtype is None:
                raise ValueError(
                    'TiffPage %i: data type not supported: %s%i'
                    % (self.index, self.sampleformat, self.bitspersample))
            if self.compression not in TIFF.DECOMPESSORS:
                raise ValueError('TiffPage %i: cannot decompress %s'
                                 % (self.index, self.compression.name))
            if 'SampleFormat' in tags:
                tag = tags['SampleFormat']
                if (
                    tag.count != 1
                    and any(i - tag.value[0] for i in tag.value)
                ):
                    raise ValueError(
                        'TiffPage %i: sample formats do not match %s'
                        % (self.index, tag.value))
            if self.is_subsampled and (self.compression not in (6, 7)
                                       or self.planarconfig == 2):
                raise NotImplementedError(
                    'TiffPage %i: chroma subsampling not supported'
                    % self.index)
            if validate is None:
                return None

        lock = fh.lock if lock is None else lock
        with lock:
            closed = fh.closed
            if closed:
                if reopen:
                    fh.open()
                else:
                    raise IOError('TiffPage %i: file handle is closed'
                                  % self.index)

        dtype = self._dtype
        shape = self._shape
        imagewidth = self.imagewidth
        imagelength = self.imagelength
        imagedepth = self.imagedepth
        bitspersample = self.bitspersample
        typecode = byteorder + dtype.char
        lsb2msb = self.fillorder == 2
        istiled = self.is_tiled

        if istiled:
            tilewidth = self.tilewidth
            tilelength = self.tilelength
            tiledepth = self.tiledepth
            tw = (imagewidth + tilewidth - 1) // tilewidth
            tl = (imagelength + tilelength - 1) // tilelength
            td = (imagedepth + tiledepth - 1) // tiledepth
            tiledshape = (td, tl, tw)
            tileshape = (tiledepth, tilelength, tilewidth, shape[-1])
            runlen = tilewidth
        else:
            runlen = imagewidth

        if self.planarconfig == 1:
            runlen *= self.samplesperpixel

        if isinstance(out, str) and out == 'memmap' and self.is_memmappable:
            # direct memory map array in file
            with lock:
                result = fh.memmap_array(typecode, shape, offset=offsets[0])
        elif self.is_contiguous:
            # read contiguous bytes to array
            if out is not None:
                out = create_output(out, shape, dtype)
            with lock:
                fh.seek(offsets[0])
                result = fh.read_array(typecode, product(shape), out=out)
            if lsb2msb:
                bitorder_decode(result, out=result)
        else:
            # decompress, unpack,... individual strips or tiles
            result = create_output(out, shape, dtype)

            decompress = TIFF.DECOMPESSORS[self.compression]

            if self.compression in (6, 7):  # COMPRESSION.JPEG
                colorspace = None
                outcolorspace = None
                jpegtables = None
                if lsb2msb:
                    log_warning('TiffPage %i: disabling LSB2MSB for JPEG',
                                self.index)
                    lsb2msb = False
                if 'JPEGTables' in tags:
                    # load JPEGTables from TiffFrame
                    jpegtables = self_._gettags({347}, lock=lock)[0][1].value
                # TODO: obtain table from OJPEG tags
                # elif ('JPEGInterchangeFormat' in tags and
                #       'JPEGInterchangeFormatLength' in tags and
                #       tags['JPEGInterchangeFormat'].value != offsets[0]):
                #     fh.seek(tags['JPEGInterchangeFormat'].value)
                #     fh.read(tags['JPEGInterchangeFormatLength'].value)
                if 'ExtraSamples' in tags:
                    pass
                elif self.photometric == 6:
                    # YCBCR -> RGB
                    outcolorspace = 'RGB'
                elif self.photometric == 2:
                    if self.planarconfig == 1:
                        colorspace = outcolorspace = 'RGB'
                else:
                    outcolorspace = TIFF.PHOTOMETRIC(self.photometric).name
                if istiled:
                    heightwidth = tilelength, tilewidth
                else:
                    heightwidth = imagelength, imagewidth

                def decompress(data, bitspersample=bitspersample,
                               jpegtables=jpegtables, colorspace=colorspace,
                               outcolorspace=outcolorspace, shape=heightwidth,
                               out=None, _decompress=decompress):
                    return _decompress(data, bitspersample, jpegtables,
                                       colorspace, outcolorspace, shape, out)

                def unpack(data):
                    return data.reshape(-1)

            elif bitspersample in (8, 16, 32, 64, 128):
                if (bitspersample * runlen) % 8:
                    raise ValueError(
                        'TiffPage %i: data and sample size mismatch'
                        % self.index)
                if self.predictor == 3:  # PREDICTOR.FLOATINGPOINT
                    # the floating-point horizontal differencing decoder
                    # needs the raw byte order
                    typecode = dtype.char

                def unpack(data, typecode=typecode, out=None):
                    try:
                        # read only numpy array
                        return numpy.frombuffer(data, typecode)
                    except ValueError:
                        # strips may be missing EOI
                        # log_warning('TiffPage.asarray: ...')
                        bps = bitspersample // 8
                        xlen = (len(data) // bps) * bps
                        return numpy.frombuffer(data[:xlen], typecode)

            elif isinstance(bitspersample, tuple):

                def unpack(data, out=None):
                    return unpack_rgb(data, typecode, bitspersample)

            else:

                def unpack(data, out=None):
                    return packints_decode(data, typecode, bitspersample,
                                           runlen)

            # TODO: store decode function for future use
            # TODO: unify tile and strip decoding
            if istiled:
                unpredict = TIFF.UNPREDICTORS[self.predictor]

                def decode(tile, tileindex, tileshape=tileshape,
                           tiledshape=tiledshape, lsb2msb=lsb2msb,
                           decompress=decompress, unpack=unpack,
                           unpredict=unpredict, nodata=self.nodata,
                           out=result[0]):
                    return tile_decode(tile, tileindex, tileshape, tiledshape,
                                       lsb2msb, decompress, unpack, unpredict,
                                       nodata, out)

                tileiter = fh.read_segments(offsets, bytecounts, lock)

                if self.compression == 1 or len(offsets) < 3:
                    maxworkers = 1
                elif maxworkers is None or maxworkers < 1:
                    import multiprocessing
                    maxworkers = max(multiprocessing.cpu_count() // 2, 1)

                if maxworkers < 2:
                    for i, tile in enumerate(tileiter):
                        decode(tile, i)
                else:
                    # decode first tile un-threaded to catch exceptions
                    decode(next(tileiter), 0)
                    with ThreadPoolExecutor(maxworkers) as executor:
                        executor.map(decode, tileiter, range(1, len(offsets)))

            else:
                stripsize = self.rowsperstrip * self.imagewidth
                if self.planarconfig == 1:
                    stripsize *= self.samplesperpixel
                outsize = stripsize * self.dtype.itemsize
                result = result.reshape(-1)
                index = 0
                for strip in fh.read_segments(offsets, bytecounts, lock):
                    if strip is None:
                        result[index:index + stripsize] = self.nodata
                        index += stripsize
                        continue
                    if lsb2msb:
                        strip = bitorder_decode(strip, out=strip)
                    strip = decompress(strip, out=outsize)
                    strip = unpack(strip)
                    size = min(result.size, strip.size, stripsize,
                               result.size - index)
                    result[index:index + size] = strip[:size]
                    del strip
                    index += size

        result.shape = self._shape

        if self.predictor != 1 and not (istiled and not self.is_contiguous):
            unpredict = TIFF.UNPREDICTORS[self.predictor]
            result = unpredict(result, axis=-2, out=result)

        if squeeze:
            try:
                result.shape = self.shape
            except ValueError:
                log_warning('TiffPage %i: failed to reshape %s to %s',
                            self.index, result.shape, self.shape)

        if closed:
            # TODO: file should remain open if an exception occurred above
            fh.close()
        return result

    def asrgb(self, uint8=False, alpha=None, colormap=None,
              dmin=None, dmax=None, **kwargs):
        """Return image data as RGB(A).

        Work in progress.

        """
        data = self.asarray(**kwargs)
        self = self.keyframe  # self or keyframe
        photometric = self.photometric
        PHOTOMETRIC = TIFF.PHOTOMETRIC

        if photometric == PHOTOMETRIC.PALETTE:
            colormap = self.colormap
            if (
                colormap.shape[1] < 2**self.bitspersample
                or self.dtype.char not in 'BH'
            ):
                raise ValueError('TiffPage %i: cannot apply colormap'
                                 % self.index)
            if uint8:
                if colormap.max() > 255:
                    colormap >>= 8
                colormap = colormap.astype('uint8')
            if 'S' in self.axes:
                data = data[..., 0] if self.planarconfig == 1 else data[0]
            data = apply_colormap(data, colormap)

        elif photometric == PHOTOMETRIC.RGB:
            if 'ExtraSamples' in self.tags:
                if alpha is None:
                    alpha = TIFF.EXTRASAMPLE
                extrasamples = self.extrasamples
                if self.tags['ExtraSamples'].count == 1:
                    extrasamples = (extrasamples,)
                for i, exs in enumerate(extrasamples):
                    if exs in alpha:
                        if self.planarconfig == 1:
                            data = data[..., [0, 1, 2, 3 + i]]
                        else:
                            data = data[:, [0, 1, 2, 3 + i]]
                        break
            else:
                if self.planarconfig == 1:
                    data = data[..., :3]
                else:
                    data = data[:, :3]
            # TODO: convert to uint8?

        elif photometric == PHOTOMETRIC.MINISBLACK:
            raise NotImplementedError()
        elif photometric == PHOTOMETRIC.MINISWHITE:
            raise NotImplementedError()
        elif photometric == PHOTOMETRIC.SEPARATED:
            raise NotImplementedError()
        else:
            raise NotImplementedError()
        return data

    def _gettags(self, codes=None, lock=None):
        """Return list of (code, TiffTag)."""
        tags = []
        for tag in self.tags.values():
            code = tag.code
            if not codes or code in codes:
                tags.append((code, tag))
        return tags

    def aspage(self):
        """Return self."""
        return self

    @property
    def keyframe(self):
        """Return keyframe, self."""
        return self

    @keyframe.setter
    def keyframe(self, index):
        """Set keyframe, NOP."""
        return

    @lazyattr
    def pages(self):
        """Return sequence of sub-pages (SubIFDs)."""
        if 'SubIFDs' not in self.tags:
            return tuple()
        return TiffPages(self)

    @property
    def hash(self):
        """Return checksum to identify pages in same series."""
        return hash(
            self._shape
            + (
                self.tilewidth,
                self.tilelength,
                self.tiledepth,
                self.bitspersample,
                self.fillorder,
                self.predictor,
                self.extrasamples,
                self.photometric,
                self.compression,
                self.planarconfig,
            )
        )

    @lazyattr
    def _offsetscounts(self):
        """Return simplified offsets and bytecounts."""
        if self.is_contiguous:
            offset, bytecount = self.is_contiguous
            return ((offset,), (bytecount,))
        return self.dataoffsets, self.databytecounts

    @lazyattr
    def is_contiguous(self):
        """Return offset and size of contiguous data, else None.

        Excludes prediction and fill_order.

        """
        if self.compression != 1 or self.bitspersample not in (8, 16, 32, 64):
            return None
        if 'TileWidth' in self.tags:
            if (
                self.imagewidth != self.tilewidth
                or self.imagelength % self.tilelength
                or self.tilewidth % 16
                or self.tilelength % 16
            ):
                return None
            if (
                'ImageDepth' in self.tags
                and 'TileDepth' in self.tags
                and (self.imagelength != self.tilelength
                     or self.imagedepth % self.tiledepth)
            ):
                return None
        offsets = self.dataoffsets
        bytecounts = self.databytecounts
        if len(offsets) == 1:
            return offsets[0], bytecounts[0]
        if self.is_stk or self.is_lsm:
            return offsets[0], sum(bytecounts)
        if all(
            bytecounts[i] != 0 and offsets[i] + bytecounts[i] == offsets[i + 1]
            for i in range(len(offsets) - 1)
        ):
            return offsets[0], sum(bytecounts)
        return None

    @lazyattr
    def is_final(self):
        """Return if page's image data are stored in final form.

        Excludes byte-swapping.

        """
        return (
            self.is_contiguous
            and self.fillorder == 1
            and self.predictor == 1
            and not self.is_subsampled
        )

    @lazyattr
    def is_memmappable(self):
        """Return if page's image data in file can be memory-mapped."""
        return (
            self.parent.filehandle.is_file
            and self.is_final
            # and (self.bitspersample == 8 or self.parent.isnative)
            # aligned?
            and self.is_contiguous[0] % self.dtype.itemsize == 0
        )

    def __str__(self, detail=0, width=79):
        """Return string containing information about page."""
        if self.keyframe != self:
            return TiffFrame.__str__(self, detail, width)
        attr = ''
        for name in ('memmappable', 'final', 'contiguous'):
            attr = getattr(self, 'is_' + name)
            if attr:
                attr = name.upper()
                break

        def tostr(name, skip=1):
            obj = getattr(self, name)
            try:
                value = getattr(obj, 'name')
            except AttributeError:
                return ''
            if obj != skip:
                return value
            return ''

        info = '  '.join(
            s.lower()
            for s in (
                'x'.join(str(i) for i in self.shape),
                '%s%s'
                % (
                    TIFF.SAMPLEFORMAT(self.sampleformat).name,
                    self.bitspersample,
                ),
                ' '.join(
                    i
                    for i in (
                        TIFF.PHOTOMETRIC(self.photometric).name,
                        'REDUCED' if self.is_reduced else '',
                        'MASK' if self.is_mask else '',
                        'TILED' if self.is_tiled else '',
                        tostr('compression'),
                        tostr('planarconfig'),
                        tostr('predictor'),
                        tostr('fillorder'),
                    )
                    + tuple(f.upper() for f in self.flags)
                    + (attr,)
                    if i
                ),
            )
            if s
        )
        info = 'TiffPage %i @%i  %s' % (self.index, self.offset, info)
        if detail <= 0:
            return info
        info = [info]
        tags = self.tags
        tlines = []
        vlines = []
        for tag in sorted(tags.values(), key=lambda x: x.code):
            value = tag.__str__(width=width + 1)
            tlines.append(value[:width].strip())
            if detail > 1 and len(value) > width:
                name = tag.name.upper()
                if detail <= 2 and ('COUNTS' in name or 'OFFSETS' in name):
                    value = pformat(tag.value, width=width, height=detail * 4)
                else:
                    value = pformat(tag.value, width=width, height=detail * 12)
                vlines.append('%s\n%s' % (tag.name, value))
        info.append('\n'.join(tlines))
        if detail > 1:
            info.append('\n\n'.join(vlines))
            for name in ('ndpi',):
                name = name + '_tags'
                attr = getattr(self, name, False)
                if attr:
                    info.append('%s\n%s' % (name.upper(), pformat(attr)))
        if detail > 3:
            try:
                info.append(
                    'DATA\n%s'
                    % pformat(self.asarray(), width=width, height=detail * 8)
                )
            except Exception:
                pass
        return '\n\n'.join(info)

    @lazyattr
    def flags(self):
        """Return set of flags."""
        return set(
            name.lower()
            for name in sorted(TIFF.FILE_FLAGS)
            if getattr(self, 'is_' + name)
        )

    @property
    def ndim(self):
        """Return number of array dimensions."""
        return len(self.shape)

    @property
    def size(self):
        """Return number of elements in array."""
        return product(self.shape)

    @lazyattr
    def andor_tags(self):
        """Return consolidated metadata from Andor tags as dict.

        Remove Andor tags from self.tags.

        """
        if not self.is_andor:
            return None
        tags = self.tags
        result = {'Id': tags['AndorId'].value}
        for tag in list(self.tags.values()):
            code = tag.code
            if not 4864 < code < 5031:
                continue
            value = tag.value
            name = tag.name[5:] if len(tag.name) > 5 else tag.name
            result[name] = value
            del tags[tag.name]
        return result

    @lazyattr
    def epics_tags(self):
        """Return consolidated metadata from EPICS areaDetector tags as dict.

        Remove areaDetector tags from self.tags.

        """
        if not self.is_epics:
            return None
        result = {}
        tags = self.tags
        for tag in list(self.tags.values()):
            code = tag.code
            if not 65000 <= code < 65500:
                continue
            value = tag.value
            if code == 65000:
                result['timeStamp'] = datetime.datetime.fromtimestamp(
                    float(value))
            elif code == 65001:
                result['uniqueID'] = int(value)
            elif code == 65002:
                result['epicsTSSec'] = int(value)
            elif code == 65003:
                result['epicsTSNsec'] = int(value)
            else:
                key, value = value.split(':', 1)
                result[key] = astype(value)
            del tags[tag.name]
        return result

    @lazyattr
    def ndpi_tags(self):
        """Return consolidated metadata from Hamamatsu NDPI as dict."""
        if not self.is_ndpi:
            return None
        tags = self.tags
        result = {}
        for name in ('Make', 'Model', 'Software'):
            result[name] = tags[name].value
        for code, name in TIFF.NDPI_TAGS.items():
            code = str(code)
            if code in tags:
                result[name] = tags[code].value
                # del tags[code]
        return result

    @lazyattr
    def geotiff_tags(self):
        """Return consolidated metadata from GeoTIFF tags as dict."""
        if not self.is_geotiff:
            return None
        tags = self.tags

        gkd = tags['GeoKeyDirectoryTag'].value
        if gkd[0] != 1:
            log_warning('GeoTIFF tags: invalid GeoKeyDirectoryTag')
            return {}

        result = {
            'KeyDirectoryVersion': gkd[0],
            'KeyRevision': gkd[1],
            'KeyRevisionMinor': gkd[2],
            # 'NumberOfKeys': gkd[3],
        }
        # deltags = ['GeoKeyDirectoryTag']
        geokeys = TIFF.GEO_KEYS
        geocodes = TIFF.GEO_CODES
        for index in range(gkd[3]):
            try:
                keyid, tagid, count, offset = gkd[4 + index * 4: index * 4 + 8]
            except Exception as exception:
                log_warning('GeoTIFF tags: %s', str(exception))
                continue
            keyid = geokeys.get(keyid, keyid)
            if tagid == 0:
                value = offset
            else:
                tagname = TIFF.TAGS[tagid]
                # deltags.append(tagname)
                try:
                    value = tags[tagname].value[offset: offset + count]
                except KeyError:
                    log_warning('GeoTIFF tags: %s not found', tagname)
                    continue
                if tagid == 34737 and count > 1 and value[-1] == '|':
                    value = value[:-1]
                value = value if count > 1 else value[0]
            if keyid in geocodes:
                try:
                    value = geocodes[keyid](value)
                except Exception:
                    pass
            result[keyid] = value

        if 'IntergraphMatrixTag' in tags:
            value = tags['IntergraphMatrixTag'].value
            value = numpy.array(value)
            if len(value) == 16:
                value = value.reshape((4, 4)).tolist()
            result['IntergraphMatrix'] = value
        if 'ModelPixelScaleTag' in tags:
            value = numpy.array(tags['ModelPixelScaleTag'].value).tolist()
            result['ModelPixelScale'] = value
        if 'ModelTiepointTag' in tags:
            value = tags['ModelTiepointTag'].value
            value = numpy.array(value).reshape((-1, 6)).squeeze().tolist()
            result['ModelTiepoint'] = value
        if 'ModelTransformationTag' in tags:
            value = tags['ModelTransformationTag'].value
            value = numpy.array(value).reshape((4, 4)).tolist()
            result['ModelTransformation'] = value
        # if 'ModelPixelScaleTag' in tags and 'ModelTiepointTag' in tags:
        #     sx, sy, sz = tags['ModelPixelScaleTag'].value
        #     tiepoints = tags['ModelTiepointTag'].value
        #     transforms = []
        #     for tp in range(0, len(tiepoints), 6):
        #         i, j, k, x, y, z = tiepoints[tp:tp+6]
        #         transforms.append([
        #             [sx, 0.0, 0.0, x - i * sx],
        #             [0.0, -sy, 0.0, y + j * sy],
        #             [0.0, 0.0, sz, z - k * sz],
        #             [0.0, 0.0, 0.0, 1.0]])
        #     if len(tiepoints) == 6:
        #         transforms = transforms[0]
        #     result['ModelTransformation'] = transforms

        if 'RPCCoefficientTag' in tags:
            rpcc = tags['RPCCoefficientTag'].value
            result['RPCCoefficient'] = {
                'ERR_BIAS': rpcc[0],
                'ERR_RAND': rpcc[1],
                'LINE_OFF': rpcc[2],
                'SAMP_OFF': rpcc[3],
                'LAT_OFF': rpcc[4],
                'LONG_OFF': rpcc[5],
                'HEIGHT_OFF': rpcc[6],
                'LINE_SCALE': rpcc[7],
                'SAMP_SCALE': rpcc[8],
                'LAT_SCALE': rpcc[9],
                'LONG_SCALE': rpcc[10],
                'HEIGHT_SCALE': rpcc[11],
                'LINE_NUM_COEFF': rpcc[12:33],
                'LINE_DEN_COEFF ': rpcc[33:53],
                'SAMP_NUM_COEFF': rpcc[53:73],
                'SAMP_DEN_COEFF': rpcc[73:],
            }

        return result

    @property
    def is_reduced(self):
        """Page is reduced image of another image."""
        return self.subfiletype & 0b1

    @property
    def is_multipage(self):
        """Page is part of multi-page image."""
        return self.subfiletype & 0b10

    @property
    def is_mask(self):
        """Page is transparency mask for another image."""
        return self.subfiletype & 0b100

    @property
    def is_mrc(self):
        """Page is part of Mixed Raster Content."""
        return self.subfiletype & 0b1000

    @property
    def is_tiled(self):
        """Page contains tiled image."""
        return 'TileWidth' in self.tags

    @property
    def is_subsampled(self):
        """Page contains chroma subsampled image."""
        if 'YCbCrSubSampling' in self.tags:
            return self.tags['YCbCrSubSampling'].value != (1, 1)
        return (
            self.compression == 7
            and self.planarconfig == 1
            and self.photometric in (2, 6)
        )

    @lazyattr
    def is_imagej(self):
        """Return ImageJ description if exists, else None."""
        for description in (self.description, self.description1):
            if not description:
                return None
            if description[:7] == 'ImageJ=':
                return description
        return None

    @lazyattr
    def is_shaped(self):
        """Return description containing array shape if exists, else None."""
        for description in (self.description, self.description1):
            if not description:
                return None
            if description[:1] == '{' and '"shape":' in description:
                return description
            if description[:6] == 'shape=':
                return description
        return None

    @property
    def is_mdgel(self):
        """Page contains MDFileTag tag."""
        return 'MDFileTag' in self.tags

    @property
    def is_mediacy(self):
        """Page contains Media Cybernetics Id tag."""
        return (
            'MC_Id' in self.tags and self.tags['MC_Id'].value[:7] == b'MC TIFF'
        )

    @property
    def is_stk(self):
        """Page contains UIC2Tag tag."""
        return 'UIC2tag' in self.tags

    @property
    def is_lsm(self):
        """Page contains CZ_LSMINFO tag."""
        return 'CZ_LSMINFO' in self.tags

    @property
    def is_fluoview(self):
        """Page contains FluoView MM_STAMP tag."""
        return 'MM_Stamp' in self.tags

    @property
    def is_nih(self):
        """Page contains NIH image header."""
        return 'NIHImageHeader' in self.tags

    @property
    def is_sgi(self):
        """Page contains SGI image and tile depth tags."""
        return 'ImageDepth' in self.tags and 'TileDepth' in self.tags

    @property
    def is_vista(self):
        """Software tag is 'ISS Vista'."""
        return self.software == 'ISS Vista'

    @property
    def is_metaseries(self):
        """Page contains MDS MetaSeries metadata in ImageDescription tag."""
        if self.index > 1 or self.software != 'MetaSeries':
            return False
        d = self.description
        return d.startswith('<MetaData>') and d.endswith('</MetaData>')

    @property
    def is_ome(self):
        """Page contains OME-XML in ImageDescription tag."""
        if self.index > 1 or not self.description:
            return False
        d = self.description
        return d[:13] == '<?xml version' and d[-4:] == 'OME>'

    @property
    def is_scn(self):
        """Page contains Leica SCN XML in ImageDescription tag."""
        if self.index > 1 or not self.description:
            return False
        d = self.description
        return d[:14] == '<?xml version=' and d[-6:] == '</scn>'

    @property
    def is_micromanager(self):
        """Page contains Micro-Manager metadata."""
        return 'MicroManagerMetadata' in self.tags

    @property
    def is_andor(self):
        """Page contains Andor Technology tags."""
        return 'AndorId' in self.tags

    @property
    def is_pilatus(self):
        """Page contains Pilatus tags."""
        return self.software[:8] == 'TVX TIFF' and self.description[:2] == '# '

    @property
    def is_epics(self):
        """Page contains EPICS areaDetector tags."""
        return (
            self.description == 'EPICS areaDetector'
            or self.software == 'EPICS areaDetector'
        )

    @property
    def is_tvips(self):
        """Page contains TVIPS metadata."""
        return 'TVIPS' in self.tags

    @property
    def is_fei(self):
        """Page contains SFEG or HELIOS metadata."""
        return 'FEI_SFEG' in self.tags or 'FEI_HELIOS' in self.tags

    @property
    def is_sem(self):
        """Page contains Zeiss SEM metadata."""
        return 'CZ_SEM' in self.tags

    @property
    def is_svs(self):
        """Page contains Aperio metadata."""
        return self.description[:20] == 'Aperio Image Library'

    @property
    def is_scanimage(self):
        """Page contains ScanImage metadata."""
        return (
            self.description[:12] == 'state.config'
            or self.software[:22] == 'SI.LINE_FORMAT_VERSION'
            or 'scanimage.SI' in self.description[-256:]
        )

    @property
    def is_qpi(self):
        """Page contains PerkinElmer tissue images metadata."""
        # The ImageDescription tag contains XML with a top-level
        # <PerkinElmer-QPI-ImageDescription> element
        return self.software[:15] == 'PerkinElmer-QPI'

    @property
    def is_geotiff(self):
        """Page contains GeoTIFF metadata."""
        return 'GeoKeyDirectoryTag' in self.tags

    @property
    def is_sis(self):
        """Page contains Olympus SIS metadata."""
        return 'OlympusSIS' in self.tags or 'OlympusINI' in self.tags

    @lazyattr  # must not be property; tag 65420 is later removed
    def is_ndpi(self):
        """Page contains NDPI metadata."""
        return '65420' in self.tags and 'Make' in self.tags


class TiffFrame(object):
    """Lightweight TIFF image file directory (IFD).

    Only a limited number of tag values are read from file, e.g. StripOffsets,
    and StripByteCounts. Other tag values are assumed to be identical with a
    specified TiffPage instance, the keyframe.

    TiffFrame is intended to reduce resource usage and speed up reading image
    data from file, not for introspection of metadata.

    Not compatible with Python 2.

    """

    __slots__ = 'index', 'parent', 'offset', '_offsetscounts', '_keyframe'

    is_mdgel = False
    pages = None
    tags = {}

    def __init__(self, parent, index, offset=None, keyframe=None,
                 offsets=None, bytecounts=None):
        """Initialize TiffFrame from file or values.

        The file handle position must be at the offset to a valid IFD.

        """
        self._keyframe = None
        self.parent = parent
        self.index = index
        self.offset = offset

        if offsets is not None:
            # initialize "virtual frame" from offsets and bytecounts
            self._offsetscounts = offsets, bytecounts
            self._keyframe = keyframe
            return

        if offset is None:
            self.offset = parent.filehandle.tell()
        else:
            parent.filehandle.seek(offset)

        if keyframe is None:
            tags = {273, 279, 324, 325}
        elif keyframe.is_contiguous:
            tags = {256, 273, 324}
        else:
            tags = {256, 273, 279, 324, 325}

        dataoffsets = databytecounts = []

        for code, tag in self._gettags(tags):
            if code == 273 or code == 324:
                dataoffsets = tag.value
            elif code == 279 or code == 325:
                databytecounts = tag.value
            elif code == 256 and keyframe.imagewidth != tag.value:
                raise RuntimeError(
                    'TiffFrame %i: incompatible keyframe' % index)
            # elif code == 270:
            #     tagname = tag.name
            #     if tagname not in tags:
            #         tags[tagname] = bytes2str(tag.value)
            #     elif 'ImageDescription1' not in tags:
            #         tags['ImageDescription1'] = bytes2str(tag.value)
            # else:
            #     tags[tag.name] = tag.value

        if not dataoffsets:
            log_warning('TiffFrame %i: missing required tags', index)

        self._offsetscounts = dataoffsets, databytecounts

        if keyframe is not None:
            self.keyframe = keyframe

    def _gettags(self, codes=None, lock=None):
        """Return list of (code, TiffTag) from file."""
        fh = self.parent.filehandle
        tiff = self.parent.tiff
        unpack = struct.unpack
        lock = NullContext() if lock is None else lock
        tags = []

        with lock:
            fh.seek(self.offset)
            try:
                tagno = unpack(tiff.tagnoformat, fh.read(tiff.tagnosize))[0]
                if tagno > 4096:
                    raise TiffFileError(
                        'TiffFrame %i: suspicious number of tags' % self.index)
            except Exception:
                raise TiffFileError(
                    'TiffFrame %i: corrupted page list at offset %i'
                    % (self.index, self.offset))

            tagoffset = self.offset + tiff.tagnosize  # fh.tell()
            tagsize = tiff.tagsize
            tagindex = -tagsize
            codeformat = tiff.tagformat1[:2]
            tagbytes = fh.read(tagsize * tagno)

            for _ in range(tagno):
                tagindex += tagsize
                code = unpack(codeformat, tagbytes[tagindex: tagindex + 2])[0]
                if codes and code not in codes:
                    continue
                try:
                    tag = TiffTag(self.parent,
                                  tagbytes[tagindex: tagindex + tagsize],
                                  tagoffset + tagindex)
                except TiffFileError as exc:
                    log_warning('TiffFrame %i: %s: %s',
                                self.index, exc.__class__.__name__, exc)
                    continue
                tags.append((code, tag))

        return tags

    def aspage(self):
        """Return TiffPage from file."""
        if self.offset is None:
            raise ValueError(
                'TiffFrame %i: cannot return virtual frame as page'
                % self.index)
        self.parent.filehandle.seek(self.offset)
        return TiffPage(self.parent, index=self.index)

    def asarray(self, *args, **kwargs):
        """Read image data from file and return as numpy array."""
        # TODO: fix TypeError on Python 2
        #   "TypeError: unbound method asarray() must be called with TiffPage
        #   instance as first argument (got TiffFrame instance instead)"
        if self._keyframe is None:
            raise RuntimeError('TiffFrame %i: keyframe not set' % self.index)
        kwargs['validate'] = False
        return TiffPage.asarray(self, *args, **kwargs)

    def asrgb(self, *args, **kwargs):
        """Read image data from file and return RGB image as numpy array."""
        if self._keyframe is None:
            raise RuntimeError('TiffFrame %i: keyframe not set' % self.index)
        kwargs['validate'] = False
        return TiffPage.asrgb(self, *args, **kwargs)

    @property
    def keyframe(self):
        """Return keyframe."""
        return self._keyframe

    @keyframe.setter
    def keyframe(self, keyframe):
        """Set keyframe."""
        if self._keyframe == keyframe:
            return
        if self._keyframe is not None:
            raise RuntimeError(
                'TiffFrame %i: cannot reset keyframe' % self.index)
        if len(self._offsetscounts[0]) != len(keyframe.dataoffsets):
            raise RuntimeError(
                'TiffFrame %i: incompatible keyframe' % self.index)
        if keyframe.is_tiled:
            pass
        if keyframe.is_contiguous:
            self._offsetscounts = (
                (self._offsetscounts[0][0], ),
                (keyframe.is_contiguous[1], ),
            )
        self._keyframe = keyframe

    @property
    def is_contiguous(self):
        """Return offset and size of contiguous data, else None."""
        if self._keyframe is None:
            raise RuntimeError('TiffFrame %i: keyframe not set' % self.index)
        if self._keyframe.is_contiguous:
            return self._offsetscounts[0][0], self._keyframe.is_contiguous[1]
        return None

    @property
    def is_memmappable(self):
        """Return if page's image data in file can be memory-mapped."""
        if self._keyframe is None:
            raise RuntimeError('TiffFrame %i: keyframe not set' % self.index)
        return self._keyframe.is_memmappable

    @property
    def hash(self):
        """Return checksum to identify pages in same series."""
        if self._keyframe is None:
            raise RuntimeError('TiffFrame %i: keyframe not set' % self.index)
        return self._keyframe.hash

    def __getattr__(self, name):
        """Return attribute from keyframe."""
        if name in TIFF.FRAME_ATTRS:
            return getattr(self._keyframe, name)
        # this error could be raised because an AttributeError was
        # raised inside a @property function
        raise AttributeError("'%s' object has no attribute '%s'"
                             % (self.__class__.__name__, name))

    def __str__(self, detail=0, width=79):
        """Return string containing information about frame."""
        if self._keyframe is None:
            info = ''
            kf = None
        else:
            info = '  '.join(s for s in ('x'.join(str(i) for i in self.shape),
                                         str(self.dtype)))
            kf = TiffPage.__str__(self._keyframe, width=width - 11)
        if detail > 3:
            of, bc = self._offsetscounts
            of = pformat(of, width=width - 9, height=detail - 3)
            bc = pformat(bc, width=width - 13, height=detail - 3)
            info = '\n Keyframe %s\n Offsets %s\n Bytecounts %s' % (kf, of, bc)
        return 'TiffFrame %i @%s  %s' % (self.index, self.offset, info)


class TiffTag(object):
    """TIFF tag structure.

    Attributes
    ----------
    name : string
        Name of tag.
    code : int
        Decimal code of tag.
    dtype : str
        Datatype of tag data. One of TIFF DATA_FORMATS.
    count : int
        Number of values.
    value : various types
        Tag data as Python object.
    ImageSourceData : int
        Location of value in file.

    All attributes are read-only.

    """

    __slots__ = ('code', 'count', 'dtype', 'value', 'valueoffset')

    def __init__(self, parent, tagheader, tagoffset):
        """Initialize instance from tag header."""
        fh = parent.filehandle
        tiff = parent.tiff
        byteorder = tiff.byteorder
        offsetsize = tiff.offsetsize
        unpack = struct.unpack

        self.valueoffset = tagoffset + offsetsize + 4
        code, type_ = unpack(tiff.tagformat1, tagheader[:4])
        count, value = unpack(tiff.tagformat2, tagheader[4:])

        try:
            dtype = TIFF.DATA_FORMATS[type_]
        except KeyError:
            raise TiffFileError('unknown tag data type %i' % type_)

        fmt = '%s%i%s' % (byteorder, count * int(dtype[0]), dtype[1])
        size = struct.calcsize(fmt)
        if size > offsetsize or code in TIFF.TAG_READERS:
            self.valueoffset = offset = unpack(tiff.offsetformat, value)[0]
            if offset < 8 or offset > fh.size - size:
                raise TiffFileError('invalid tag value offset')
            # if offset % 2:
            #     log_warning('TiffTag: value does not begin on word boundary')
            fh.seek(offset)
            if code in TIFF.TAG_READERS:
                readfunc = TIFF.TAG_READERS[code]
                value = readfunc(fh, byteorder, dtype, count, offsetsize)
            elif type_ == 7 or (count > 1 and dtype[-1] == 'B'):
                value = read_bytes(fh, byteorder, dtype, count, offsetsize)
            elif code in TIFF.TAGS or dtype[-1] == 's':
                value = unpack(fmt, fh.read(size))
            else:
                value = read_numpy(fh, byteorder, dtype, count, offsetsize)
        elif dtype[-1] == 'B' or type_ == 7:
            value = value[:size]
        else:
            value = unpack(fmt, value[:size])

        process = (
            code not in TIFF.TAG_READERS
            and code not in TIFF.TAG_TUPLE
            and type_ != 7
        )
        if process and dtype[-1] == 's' and isinstance(value[0], bytes):
            # TIFF ASCII fields can contain multiple strings,
            #   each terminated with a NUL
            value = value[0]
            try:
                value = bytes2str(stripascii(value).strip())
            except UnicodeDecodeError:
                # TODO: this doesn't work on Python 2
                log_warning(
                    'TiffTag %i: coercing invalid ASCII to bytes', code)
                dtype = '1B'
        else:
            if code in TIFF.TAG_ENUM:
                t = TIFF.TAG_ENUM[code]
                try:
                    value = tuple(t(v) for v in value)
                except ValueError as exc:
                    log_warning('TiffTag  %i: %s', code, str(exc))
            if process:
                if len(value) == 1:
                    value = value[0]

        self.code = code
        self.dtype = dtype
        self.count = count
        self.value = value

    @property
    def name(self):
        """Return name of tag from TIFF.TAGS registry."""
        try:
            return TIFF.TAGS[self.code]
        except KeyError:
            return str(self.code)

    def _fix_lsm_bitspersample(self, parent):
        """Correct LSM bitspersample tag.

        Old LSM writers may use a separate region for two 16-bit values,
        although they fit into the tag value element of the tag.

        """
        if self.code != 258 or self.count != 2:
            return
        # TODO: test this case; need example file
        log_warning('TiffTag %i: correcting LSM bitspersample tag', self.code)
        value = struct.pack('<HH', *self.value)
        self.valueoffset = struct.unpack('<I', value)[0]
        parent.filehandle.seek(self.valueoffset)
        self.value = struct.unpack('<HH', parent.filehandle.read(4))

    def __str__(self, detail=0, width=79):
        """Return string containing information about tag."""
        height = 1 if detail <= 0 else 8 * detail
        tcode = '%i%s' % (self.count * int(self.dtype[0]), self.dtype[1])
        if self.name == str(self.code):
            codename = self.name
        else:
            codename = '%i %s' % (self.code, self.name)
        line = 'TiffTag %s %s @%i  ' % (codename, tcode, self.valueoffset)
        line = line[:width]
        try:
            if self.count == 1:
                value = TIFF.TAG_ENUM[self.code](self.value).name
            else:
                value = pformat(tuple(v.name for v in self.value))
        except Exception:
            value = pformat(self.value, width=width, height=height)
        if detail <= 0:
            line += value
            line = line[:width]
        else:
            line += '\n' + value
        return line


class TiffPageSeries(object):
    """Series of TIFF pages with compatible shape and data type.

    Attributes
    ----------
    pages : list of TiffPage
        Sequence of TiffPages in series.
    dtype : numpy.dtype
        Data type (native byte order) of the image array in series.
    shape : tuple
        Dimensions of the image array in series.
    axes : str
        Labels of axes in shape. See TiffPage.axes.
    offset : int or None
        Position of image data in file if memory-mappable, else None.

    """

    def __init__(self, pages, shape, dtype, axes, parent=None, name=None,
                 transform=None, kind=None, truncated=False):
        """Initialize instance."""
        self.index = 0
        self._pages = pages  # might contain only first of contiguous pages
        self.shape = tuple(shape)
        self.axes = ''.join(axes)
        self.dtype = numpy.dtype(dtype)
        self.kind = kind if kind else ''
        self.name = name if name else ''
        self.transform = transform
        if parent:
            self.parent = parent
        elif pages:
            self.parent = pages[0].parent
        else:
            self.parent = None
        if not truncated and len(pages) == 1:
            self._len = int(product(self.shape) // product(pages[0].shape))
        else:
            self._len = len(pages)

    def asarray(self, out=None):
        """Return image data from series of TIFF pages as numpy array."""
        if self.parent:
            result = self.parent.asarray(series=self, out=out)
            if self.transform is not None:
                result = self.transform(result)
            return result
        return None

    @lazyattr
    def offset(self):
        """Return offset to series data in file, if any."""
        if not self._pages:
            return None

        pos = 0
        for page in self._pages:
            if page is None:
                return None
            if not page.is_final:
                return None
            if not pos:
                pos = page.is_contiguous[0] + page.is_contiguous[1]
                continue
            if pos != page.is_contiguous[0]:
                return None
            pos += page.is_contiguous[1]

        page = self._pages[0]
        offset = page.is_contiguous[0]
        if (page.is_imagej or page.is_shaped) and len(self._pages) == 1:
            # truncated files
            return offset
        if pos == offset + product(self.shape) * self.dtype.itemsize:
            return offset
        return None

    @property
    def ndim(self):
        """Return number of array dimensions."""
        return len(self.shape)

    @property
    def size(self):
        """Return number of elements in array."""
        return int(product(self.shape))

    @property
    def pages(self):
        """Return sequence of all pages in series."""
        # a workaround to keep the old interface working
        return self

    def _getitem(self, key):
        """Return specified page of series from cache or file."""
        key = int(key)
        if key < 0:
            key %= self._len
        if len(self._pages) == 1 and 0 < key < self._len:
            index = self._pages[0].index
            return self.parent.pages._getitem(index + key)
        return self._pages[key]

    def __getitem__(self, key):
        """Return specified page(s)."""
        getitem = self._getitem
        if isinstance(key, inttypes):
            return getitem(key)
        if isinstance(key, slice):
            return [getitem(i) for i in range(*key.indices(self._len))]
        if isinstance(key, Iterable):
            return [getitem(k) for k in key]
        raise TypeError('key must be an integer, slice, or iterable')

    def __iter__(self):
        """Return iterator over pages in series."""
        if len(self._pages) == self._len:
            for page in self._pages:
                yield page
        else:
            pages = self.parent.pages
            index = self._pages[0].index
            for i in range(self._len):
                yield pages[index + i]

    def __len__(self):
        """Return number of pages in series."""
        return self._len

    def __str__(self):
        """Return string with information about series."""
        s = '  '.join(
            s
            for s in (
                snipstr("'%s'" % self.name, 20) if self.name else '',
                'x'.join(str(i) for i in self.shape),
                str(self.dtype),
                self.axes,
                self.kind,
                '%i Pages' % len(self.pages),
                ('Offset=%i' % self.offset) if self.offset else '')
            if s
        )
        return 'TiffPageSeries %i  %s' % (self.index, s)


class FileSequence(object):
    """Series of files containing array data of compatible shape and data type.

    Attributes
    ----------
    files : list
        List of file names.
    shape : tuple
        Shape of file series. Excludes shape of individual arrays.
    axes : str
        Labels of axes in shape.

    """

    _patterns = {
        'axes': r"""
            # matches Olympus OIF and Leica TIFF series
            _?(?:(q|l|p|a|c|t|x|y|z|ch|tp)(\d{1,4}))
            _?(?:(q|l|p|a|c|t|x|y|z|ch|tp)(\d{1,4}))?
            _?(?:(q|l|p|a|c|t|x|y|z|ch|tp)(\d{1,4}))?
            _?(?:(q|l|p|a|c|t|x|y|z|ch|tp)(\d{1,4}))?
            _?(?:(q|l|p|a|c|t|x|y|z|ch|tp)(\d{1,4}))?
            _?(?:(q|l|p|a|c|t|x|y|z|ch|tp)(\d{1,4}))?
            _?(?:(q|l|p|a|c|t|x|y|z|ch|tp)(\d{1,4}))?
            """
    }

    def __init__(self, fromfile, files, container=None, sort=None,
                 pattern=None):
        """Initialize instance from multiple files.

        Parameters
        ----------
        fromfile : function or class
            Array read function or class with asarray function returning numpy
            array from single file.
        files : str, pathlib.Path, or sequence thereof
            Glob filename pattern or sequence of file names. Default: \\*.
            Binary streams are not supported.
        container : str or container instance
            Name or open instance of ZIP file in which files are stored.
        sort : function
            Sort function used to sort file names when 'files' is a pattern.
            The default (None) is natural_sorted. Use sort=False to disable
            sorting.
        pattern : str
            Regular expression pattern that matches axes and sequence indices
            in file names. By default (None), no pattern matching is performed.
            Axes can be specified by matching groups preceding the index groups
            in the file name, be provided as group names for the index groups,
            or be omitted. The predefined 'axes' pattern matches  Olympus OIF
            and Leica TIFF series.

        """
        if files is None:
            files = '*'
        if sort is None:
            sort = natural_sorted
        self._container = container
        if container:
            import fnmatch
            if isinstance(container, basestring):
                import zipfile
                self._container = zipfile.ZipFile(container)
            elif not hasattr(self._container, 'open'):
                raise ValueError('invalid container')
            if isinstance(files, basestring):
                files = fnmatch.filter(self._container.namelist(), files)
                if sort:
                    files = sort(files)
        else:
            if isinstance(files, pathlib.Path):
                files = str(files)
            if isinstance(files, basestring):
                files = glob.glob(files)
                if sort:
                    files = sort(files)
            if not files:
                raise ValueError('no files found')

        files = list(files)
        if not files:
            raise ValueError('no files found')
        if isinstance(files[0], pathlib.Path):
            files = [str(pathlib.Path(f)) for f in files]
        elif not isinstance(files[0], basestring):
            raise ValueError('not a file name')

        if hasattr(fromfile, 'asarray'):
            # redefine fromfile to use asarray from fromfile class
            if not callable(fromfile.asarray):
                raise ValueError('invalid fromfile function')
            _fromfile0 = fromfile

            def fromfile(fname, **kwargs):
                with _fromfile0(fname) as handle:
                    return handle.asarray(**kwargs)

        elif not callable(fromfile):
            raise ValueError('invalid fromfile function')

        if container:
            # redefine fromfile to read from container
            _fromfile1 = fromfile

            def fromfile(fname, **kwargs):
                with self._container.open(fname) as handle1:
                    with io.BytesIO(handle1.read()) as handle2:
                        return _fromfile1(handle2, **kwargs)

        axes = 'I'
        shape = (len(files),)
        indices = tuple((i,) for i in range(len(files)))
        startindex = (0,)

        pattern = self._patterns.get(pattern, pattern)
        if pattern:
            try:
                axes, shape, indices, startindex = parse_filenames(files,
                                                                   pattern)
            except ValueError as exception:
                log_warning(
                    'FileSequence: failed to parse file names (%s)', exception)

        if product(shape) != len(files):
            log_warning(
                'FileSequence: files are missing. Missing data are zeroed')

        self.fromfile = fromfile
        self.files = files
        self.pattern = pattern
        self.axes = axes.upper()
        self.shape = shape
        self._indices = indices
        self._startindex = startindex

    def __str__(self):
        """Return string with information about file series."""
        return '\n'.join((
            str(self._container) if self._container else self.files[0],
            ' size: %i' % len(self.files),
            ' shape: %s' % str(self.shape),
            ' axes: %s' % self.axes,
        ))

    def __len__(self):
        return len(self.files)

    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc_value, traceback):
        self.close()

    def close(self):
        if self._container:
            self._container.close()
        self._container = None

    def asarray(self, file=None, ioworkers=1, out=None, **kwargs):
        """Read image data from files and return as numpy array.

        Raise IndexError or ValueError if array shapes do not match.

        Parameters
        ----------
        file : int or None
            Index or name of single file to read.
        ioworkers : int or None
            Maximum number of threads to execute the array read function
            asynchronously. Default: 1.
            If None, default to the number of processors multiplied by 5.
            Using threads can significantly improve runtime when
            reading many small files from a network share.
        out : numpy.ndarray, str, or file-like object
            Buffer where image data will be saved.
            If None (default), a new array will be created.
            If numpy.ndarray, a writable array of compatible dtype and shape.
            If 'memmap', create a memory-mapped array in a temporary file.
            If str or open file, the file name or file object used to
            create a memory-map to an array stored in a binary file on disk.
        kwargs : dict
            Additional parameters passed to the array read function.

        """
        if file is not None:
            if isinstance(file, int):
                return self.fromfile(self.files[file], **kwargs)
            return self.fromfile(file, **kwargs)

        im = self.fromfile(self.files[0], **kwargs)
        shape = self.shape + im.shape
        result = create_output(out, shape, dtype=im.dtype)
        result = result.reshape(-1, *im.shape)

        def func(index, fname):
            """Read single image from file into result."""
            index = [i - j for i, j in zip(index, self._startindex)]
            index = numpy.ravel_multi_index(index, self.shape)
            im = self.fromfile(fname, **kwargs)
            result[index] = im

        if len(self.files) < 3:
            ioworkers = 1
        elif ioworkers is None or ioworkers < 1:
            import multiprocessing
            ioworkers = max(multiprocessing.cpu_count() * 5, 1)

        if ioworkers < 2:
            for index, fname in zip(self._indices, self.files):
                func(index, fname)
        else:
            func(self._indices[0], self.files[0])
            with ThreadPoolExecutor(ioworkers) as executor:
                executor.map(func, self._indices[1:], self.files[1:])

        result.shape = shape
        return result


class TiffSequence(FileSequence):
    """Series of TIFF files."""

    def __init__(self, files=None, container=None, sort=None, pattern=None,
                 imread=imread):
        """Initialize instance from multiple TIFF files."""
        super(TiffSequence, self).__init__(
            imread, '*.tif' if files is None else files,
            container=container, sort=sort, pattern=pattern)


class FileHandle(object):
    """Binary file handle.

    A limited, special purpose file handle that can:

    * handle embedded files (for CZI within CZI files)
    * re-open closed files (for multi-file formats, such as OME-TIFF)
    * read and write numpy arrays and records from file like objects

    Only 'rb' and 'wb' modes are supported. Concurrently reading and writing
    of the same stream is untested.

    When initialized from another file handle, do not use it unless this
    FileHandle is closed.

    Attributes
    ----------
    name : str
        Name of the file.
    path : str
        Absolute path to file.
    size : int
        Size of file in bytes.
    is_file : bool
        If True, file has a filno and can be memory-mapped.

    All attributes are read-only.

    """

    __slots__ = ('_fh', '_file', '_mode', '_name', '_dir', '_lock',
                 '_offset', '_size', '_close', 'is_file')

    def __init__(self, file, mode='rb', name=None, offset=None, size=None):
        """Initialize file handle from file name or another file handle.

        Parameters
        ----------
        file : str, pathlib.Path, binary stream, or FileHandle
            File name or seekable binary stream, such as an open file
            or BytesIO.
        mode : str
            File open mode in case 'file' is a file name. Must be 'rb' or 'wb'.
        name : str
            Optional name of file in case 'file' is a binary stream.
        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.

        """
        self._file = file
        self._fh = None
        self._mode = mode
        self._name = name
        self._dir = ''
        self._offset = offset
        self._size = size
        self._close = True
        self.is_file = False
        self._lock = NullContext()
        self.open()

    def open(self):
        """Open or re-open file."""
        if self._fh:
            return  # file is open

        if isinstance(self._file, pathlib.Path):
            self._file = str(self._file)
        if isinstance(self._file, basestring):
            # file name
            self._file = os.path.realpath(self._file)
            self._dir, self._name = os.path.split(self._file)
            self._fh = open(self._file, self._mode)
            self._close = True
            if self._offset is None:
                self._offset = 0
        elif isinstance(self._file, FileHandle):
            # FileHandle
            self._fh = self._file._fh
            if self._offset is None:
                self._offset = 0
            self._offset += self._file._offset
            self._close = False
            if not self._name:
                if self._offset:
                    name, ext = os.path.splitext(self._file._name)
                    self._name = '%s@%i%s' % (name, self._offset, ext)
                else:
                    self._name = self._file._name
            if self._mode and self._mode != self._file._mode:
                raise ValueError('FileHandle has wrong mode')
            self._mode = self._file._mode
            self._dir = self._file._dir
        elif hasattr(self._file, 'seek'):
            # binary stream: open file, BytesIO
            try:
                self._file.tell()
            except Exception:
                raise ValueError('binary stream is not seekable')
            self._fh = self._file
            if self._offset is None:
                self._offset = self._file.tell()
            self._close = False
            if not self._name:
                try:
                    self._dir, self._name = os.path.split(self._fh.name)
                except AttributeError:
                    self._name = 'Unnamed binary stream'
            try:
                self._mode = self._fh.mode
            except AttributeError:
                pass
        else:
            raise ValueError('the first parameter must be a file name, '
                             'seekable binary stream, or FileHandle')

        if self._offset:
            self._fh.seek(self._offset)

        if self._size is None:
            pos = self._fh.tell()
            self._fh.seek(self._offset, 2)
            self._size = self._fh.tell()
            self._fh.seek(pos)

        try:
            self._fh.fileno()
            self.is_file = True
        except Exception:
            self.is_file = False

    def read(self, size=-1):
        """Read 'size' bytes from file, or until EOF is reached."""
        if size < 0 and self._offset:
            size = self._size
        return self._fh.read(size)

    def readinto(self, b):
        """Read up to len(b) bytes into b, and return number of bytes read."""
        return self._fh.readinto(b)

    def write(self, bytestring):
        """Write bytestring to file."""
        return self._fh.write(bytestring)

    def flush(self):
        """Flush write buffers if applicable."""
        return self._fh.flush()

    def memmap_array(self, dtype, shape, offset=0, mode='r', order='C'):
        """Return numpy.memmap of data stored in file."""
        if not self.is_file:
            raise ValueError('cannot memory-map file without fileno')
        return numpy.memmap(self._fh, dtype=dtype, mode=mode,
                            offset=self._offset + offset,
                            shape=shape, order=order)

    def read_array(self, dtype, count=-1, out=None):
        """Return numpy array from file in native byte order."""
        fh = self._fh
        dtype = numpy.dtype(dtype)

        if count < 0:
            size = self._size if out is None else out.nbytes
            count = size // dtype.itemsize
        else:
            size = count * dtype.itemsize

        result = numpy.empty(count, dtype) if out is None else out

        if result.nbytes != size:
            raise ValueError('size mismatch')

        n = fh.readinto(result)
        if n != size:
            raise ValueError('failed to read %i bytes' % size)

        if not result.dtype.isnative:
            if not dtype.isnative:
                result.byteswap(True)
            result = result.newbyteorder()
        elif result.dtype.isnative != dtype.isnative:
            result.byteswap(True)

        if out is not None:
            if hasattr(out, 'flush'):
                out.flush()

        return result

    def read_segments(self, offsets, bytecounts, lock=None, buffersize=None):
        """Return iterator over segments read from file.

        A reentrant lock can be used to synchronize seeks and reads up to
        buffersize bytes.

        """
        length = len(offsets)
        if length < 1:
            return
        if length == 1:
            if bytecounts[0] > 0 and offsets[0] > 0:
                if lock is None:
                    lock = self._lock
                with lock: