hyperspy.external.tifffile module

Read and write TIFF(r) files.

Tiffile is a package 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, NIH, SGI, ImageJ, MicroManager, FluoView, ScanImage, SEQ, GEL, SVS, SCN, SIS, 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, image trees defined via SubIFDs, 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 tiffile --help

Author

Christoph Gohlke

Organization

Laboratory for Fluorescence Dynamics, University of California, Irvine

Version

2018.9.27

Requirements

Revisions

2018.9.27

Read Olympus SIS (WIP). Allow to write non-BigTIFF files up to ~4 GB (bug fix). Fix parsing date and time fields in SEM metadata (bug fix). 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

Pass 2699 tests. Fix wrong TiffTag.valueoffset (bug fix). 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 (bug 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 (backward incompatible). Add option to specify ExtraSamples values.

2018.6.17

Pass 2680 tests. 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 (bug fix). Move EXIF tags to TIFF.TAG as per TIFF/EP standard.

2018.2.18

Pass 2293 tests. 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 (bug fix). 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 QPTIFF (no test files). Do not index out of bounds data in tifffile.c unpackbits and decodelzw.

2017.9.29 (tentative)

Many backward incompatible changes improving speed and resource usage: Pass 2268 tests. 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 (bug fix). Do not modify input array in imshow (bug fix). Fix Python implementation of unpack_ints.

2017.5.23

Pass 1961 tests. Write correct number of SampleFormat values (bug 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

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

Add option to append images to existing TIFF files. Read files without pages. Read S-FEG and Helios NanoLab tags created by FEI software. Allow saving Color Filter Array (CFA) images. Add info functions returning more information about TiffFile and TiffPage. Add option to read specific pages only. Remove maxpages argument (backward incompatible). Remove test_tifffile function.

2016.10.28

Pass 1944 tests. Improve detection of ImageJ hyperstacks. Read TVIPS metadata created by EM-MENU (by Marco Oster). Add option to disable using OME-XML metadata. Allow non-integer range attributes in modulo tags (by Stuart Berg).

2016.6.21

Do not always memmap contiguous data in page series.

2016.5.13

Add option to specify resolution unit. Write grayscale images with extra samples when planarconfig is specified. Do not write RGB color images with 2 samples. Reorder TiffWriter.save keyword arguments (backward incompatible).

2016.4.18

Pass 1932 tests. TiffWriter, imread, and imsave accept open binary file streams.

2016.04.13

Correctly handle reversed fill order in 2 and 4 bps images (bug fix). Implement reverse_bitorder in C.

2016.03.18

Fix saving additional ImageJ metadata.

2016.2.22

Pass 1920 tests. Write 8 bytes double tag values using offset if necessary (bug fix). Add option to disable writing second image description tag. Detect tags with incorrect counts. Disable color mapping for LSM.

2015.11.13

Read LSM 6 mosaics. Add option to specify directory of memory-mapped files. Add command line options to specify vmin and vmax values for colormapping.

2015.10.06

New helper function to apply colormaps. Renamed is_palette attributes to is_indexed (backward incompatible). Color-mapped samples are now contiguous (backward incompatible). Do not color-map ImageJ hyperstacks (backward incompatible). Towards reading Leica SCN.

2015.9.25

Read images with reversed bit order (FillOrder is LSB2MSB).

2015.9.21

Read RGB OME-TIFF. Warn about malformed OME-XML.

2015.9.16

Detect some corrupted ImageJ metadata. Better axes labels for ‘shaped’ files. Do not create TiffTag for default values. Chroma subsampling is not supported. Memory-map data in TiffPageSeries if possible (optional).

2015.8.17

Pass 1906 tests. Write ImageJ hyperstacks (optional). Read and write LZMA compressed data. Specify datetime when saving (optional). Save tiled and color-mapped images (optional). Ignore void bytecounts and offsets if possible. Ignore bogus image_depth tag created by ISS Vista software. Decode floating point horizontal differencing (not tiled). Save image data contiguously if possible. Only read first IFD from ImageJ files if possible. Read ImageJ ‘raw’ format (files larger than 4 GB). TiffPageSeries class for pages with compatible shape and data type. Try to read incomplete tiles. Open file dialog if no filename is passed on command line. Ignore errors when decoding OME-XML. Rename decoder functions (backward incompatible).

2014.8.24

TiffWriter class for incremental writing images. Simplify examples.

2014.8.19

Add memmap function to FileHandle. Add function to determine if image data in TiffPage is memory-mappable. Do not close files if multifile_close parameter is False.

2014.8.10

Pass 1730 tests. Return all extrasamples by default (backward incompatible). Read data from series of pages into memory-mapped array (optional). Squeeze OME dimensions (backward incompatible). Workaround missing EOI code in strips. Support image and tile depth tags (SGI extension). Better handling of STK/UIC tags (backward incompatible). Disable color mapping for STK. Julian to datetime converter. TIFF ASCII type may be NULL separated. Unwrap strip offsets for LSM files greater than 4 GB. Correct strip byte counts in compressed LSM files. Skip missing files in OME series. Read embedded TIFF files.

2014.2.05

Save rational numbers as type 5 (bug fix).

2013.12.20

Keep other files in OME multi-file series closed. FileHandle class to abstract binary file handle. Disable color mapping for bad OME-TIFF produced by bio-formats. Read bad OME-XML produced by ImageJ when cropping.

2013.11.3

Allow zlib compress data in imsave function (optional). Memory-map contiguous image data (optional).

2013.10.28

Read MicroManager metadata and little-endian ImageJ tag. Save extra tags in imsave function. Save tags in ascending order by code (bug fix).

2012.10.18

Accept file like objects (read from OIB files).

2012.8.21

Rename TIFFfile to TiffFile and TIFFpage to TiffPage. TiffSequence class for reading sequence of TIFF files. Read UltraQuant tags. Allow float numbers as resolution in imsave function.

2012.8.3

Read MD GEL tags and NIH Image header.

2012.7.25

Read ImageJ tags. …

Notes

The API is not stable yet and might change between revisions.

Tested on little-endian platforms only.

Python 2.7 and 3.4 are deprecated.

Other libraries for reading scientific TIFF files from Python:

Acknowledgements

  • Egor Zindy, University of Manchester, for lsm_scan_info specifics.

  • Wim Lewis for a bug fix and some LSM functions.

  • Hadrien Mary for help on reading MicroManager files.

  • Christian Kliche for help writing tiled and color-mapped files.

References

  1. TIFF 6.0 Specification and Supplements. Adobe Systems Incorporated. http://partners.adobe.com/public/developer/tiff/

  2. TIFF File Format FAQ. http://www.awaresystems.be/imaging/tiff/faq.html

  3. MetaMorph Stack (STK) Image File Format. http://support.meta.moleculardevices.com/docs/t10243.pdf

  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. http://www.openmicroscopy.org/site/support/file-formats/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. http://www.micro-manager.org/wiki/Micro-Manager_File_Formats

  8. Tags for TIFF and Related Specifications. Digital Preservation. http://www.digitalpreservation.gov/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

Examples

Save a 3D numpy array to a multi-page, 16-bit grayscale TIFF file:

>>> data = numpy.random.randint(0, 2**16, (4, 301, 219), 'uint16')
>>> imsave('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 (IFD) in the TIFF file:

>>> 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')
>>> imsave('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')
>>> imsave('temp.tif', data, compress=6, metadata={'axes': 'TZCYX'})

Save a volume with xyz voxel size 2.6755x2.6755x3.9474 µm^3 to ImageJ file:

>>> volume = numpy.random.randn(57*256*256).astype('float32')
>>> volume.shape = 1, 57, 1, 256, 256, 1  # dimensions in TZCYXS order
>>> imsave('temp.tif', volume, imagej=True, resolution=(0.373759, 0.373759),
...        metadata={'spacing': 3.947368, 'unit': 'um'})

Read hyperstack and metadata from 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

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 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:

>>> 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')

Read the second image series from the TIFF file:

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

Read a image stack from a sequence of TIFF files with a file name pattern:

>>> imsave('temp_C001T001.tif', numpy.random.rand(64, 64))
>>> imsave('temp_C001T002.tif', numpy.random.rand(64, 64))
>>> image_sequence = TiffSequence('temp_C001*.tif')
>>> image_sequence.shape
(1, 2)
>>> image_sequence.axes
'CT'
>>> data = image_sequence.asarray()
>>> data.shape
(1, 2, 64, 64)
hyperspy.external.tifffile.imsave(file, data=None, shape=None, dtype=None, bigsize=4261412864, **kwargs)

Write numpy array to TIFF file.

Refer to the TiffWriter class and member functions for documentation.

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, data-type of an empty array to save to the file.

  • bigsize (int) – Create a BigTIFF file if the size of data in bytes is larger than this threshold and ‘imagej’ or ‘truncate’ are not enabled. By default, the threshold is 4 GB minus 32 MB reserved for metadata. Use the ‘bigtiff’ parameter to explicitly specify the type of file created.

  • kwargs (dict) – Parameters ‘append’, ‘byteorder’, ‘bigtiff’, and ‘imagej’, are passed to TiffWriter(). Other parameters are passed to TiffWriter.save().

Returns

offset, bytecount – If the image data are written contiguously, return offset and bytecount of image data in the file.

Return type

tuple or None

hyperspy.external.tifffile.imread(files, **kwargs)

Return image data from TIFF file(s) as numpy array.

Refer to the TiffFile class and member 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 ‘multifile’ and ‘is_ome’ are passed to the TiffFile class. The ‘pattern’ parameter is passed to the TiffSequence class. Other parameters are passed to the asarray functions. The first image series is returned if no arguments are provided.

hyperspy.external.tifffile.imshow(data, title=None, vmin=0, vmax=None, cmap=None, bitspersample=None, photometric='RGB', interpolation=None, dpi=96, figure=None, subplot=111, maxdim=32768, **kwargs)

Plot n-dimensional images using matplotlib.pyplot.

Return figure, subplot and plot axis. Requires pyplot already imported C{from matplotlib import pyplot}.

Parameters

  • bitspersample (int or None) – Number of bits per channel in integer RGB images.

  • photometric ({'MINISWHITE', 'MINISBLACK', 'RGB', or 'PALETTE'}) – The color space of the image data.

  • title (str) – Window and subplot title.

  • figure (matplotlib.figure.Figure (optional)) – Matplotlib to use for plotting.

  • subplot (int) – A matplotlib.pyplot.subplot axis.

  • maxdim (int) – maximum image width and length.

  • kwargs (optional) – Arguments for matplotlib.pyplot.imshow.

hyperspy.external.tifffile.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) – Data-type 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'}, optional) – The file open mode. Default is to open existing file for reading and writing (‘r+’).

  • kwargs (dict) – Additional parameters passed to imsave() or TiffFile().

class hyperspy.external.tifffile.TiffFile(arg, name=None, offset=None, size=None, multifile=True, movie=None, **kwargs)

Bases: 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.

pages

Sequence of TIFF pages in file.

Type

TiffPages

series

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.

Type

list of TiffPageSeries

is_flag

If True, file is of a certain format. Flags are: bigtiff, movie, shaped, ome, imagej, stk, lsm, fluoview, nih, vista, micromanager, metaseries, mdgel, mediacy, tvips, fei, sem, scn, svs, scanimage, andor, epics, ndpi, pilatus, qptiff.

Type

bool

All attributes are read-only.

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.

  • movie (bool) – If True, assume that later pages differ from first page only by data offsets and byte counts. Significantly increases speed and reduces memory usage when reading movies with thousands of pages. Enabling this for non-movie files will result in data corruption or crashes. Python 3 only.

  • kwargs (bool) – ‘is_ome’: If False, disable processing of OME-XML metadata.

andor_metadata

Attribute whose value is computed on first access.

asarray(key=None, series=None, out=None, validate=True, maxworkers=None)

Return image data from multiple TIFF pages as numpy array.

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

Parameters

  • key (int, slice, or sequence of page indices) – Defines which pages to return as array.

  • series (int or TiffPageSeries) – Defines which series of pages to return as array.

  • out (numpy.ndarray, str, or file-like object; optional) – 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 pages or tiles. If None (default), mutli-threading is enabled if data are compressed. If 0, up to half the CPU cores are used. If 1, mutli-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

Image data from the specified pages. See the TiffPage.asarray function for what kind of operations are applied (or not) to the raw data stored in the file.

Return type

numpy.ndarray

property byteorder
close()

Close open file handle(s).

epics_metadata

Attribute whose value is computed on first access.

fei_metadata

Attribute whose value is computed on first access.

property filehandle

Return file handle.

property filename

Return name of file handle.

flags

Attribute whose value is computed on first access.

fluoview_metadata

Attribute whose value is computed on first access.

fstat

Attribute whose value is computed on first access.

property geotiff_metadata

Return GeoTIFF metadata from first page as dict.

imagej_metadata

Attribute whose value is computed on first access.

property is_bigtiff
is_mdgel

Attribute whose value is computed on first access.

property is_movie

Return if file is a movie.

lsm_metadata

Attribute whose value is computed on first access.

mdgel_metadata

Attribute whose value is computed on first access.

metaseries_metadata

Attribute whose value is computed on first access.

micromanager_metadata

Attribute whose value is computed on first access.

nih_metadata

Attribute whose value is computed on first access.

ome_metadata

Attribute whose value is computed on first access.

pilatus_metadata

Attribute whose value is computed on first access.

qptiff_metadata

Attribute whose value is computed on first access.

scanimage_metadata

Attribute whose value is computed on first access.

sem_metadata

Attribute whose value is computed on first access.

series

Attribute whose value is computed on first access.

shaped_metadata

Attribute whose value is computed on first access.

sis_metadata

Attribute whose value is computed on first access.

stk_metadata

Attribute whose value is computed on first access.

tvips_metadata

Attribute whose value is computed on first access.

class hyperspy.external.tifffile.TiffWriter(file, bigtiff=False, byteorder=None, append=False, imagej=False)

Bases: 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’s main purpose is saving nD numpy array’s as TIFF, not to create any possible TIFF format. Specifically, JPEG compression, SubIFDs, ExifIFD, or GPSIFD tags are not supported.

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, NIH, 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 does not support BigTIFF format or non DEFLATE compression. The ImageJ file format is undocumented.

close()

Write remaining pages and close file handle.

save(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, 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) – Data-type 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 contiguous 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. Parameters ‘photometric’ and ‘planarconfig’ are ignored. Parameters ‘description’, 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.COMPRESSION, e.g. ‘LZMA’ or ‘ZSTD’. If a tuple, first item is one of TIFF.COMPRESSION and second item is compression level. Compression cannot be used to write contiguous files.

  • rowsperstrip (int) – The number of rows per strip used for compression. Uncompressed data are written in one strip per plane.

  • predictor (bool) – If True, apply horizontal differencing or floating point predictor before compression.

  • 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) – Date and time of image creation in ‘%Y:%m:%d %H:%M:%S’ format. If None (default), 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 meta data 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 meta data 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)].

    codeint

    The TIFF tag Id.

    dtypestr

    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.

    countint

    Number of data values. Not used for string or byte string values.

    valuesequence

    ’Count’ values compatible with ‘dtype’. Byte strings must contain count values of dtype packed as binary data.

    writeoncebool

    If True, the tag is written to the first page only.

class hyperspy.external.tifffile.TiffSequence(files=None, imread=<class 'hyperspy.external.tifffile.TiffFile'>, pattern='axes', container=None, sort=None, *args, **kwargs)

Bases: object

Sequence of TIFF files.

The image data in all files must match shape, dtype, etc.

files

List of file names.

Type

list

shape

Shape of image sequence. Excludes shape of image array.

Type

tuple

axes

Labels of axes in shape.

Type

str

Initialize instance from multiple files.

Parameters

  • files (str, pathlib.Path, or sequence thereof) – Glob filename pattern or sequence of file names. Default is ‘*.tif’. Binary streams are not supported.

  • imread (function or class) – Image read function or class with asarray function returning numpy array from single file.

  • pattern (str) – Regular expression pattern that matches axes names and sequence indices in file names. By default, the pattern matches Olympus OIF and Leica TIFF series.

  • container (str, container instance, or None) – Name or open instance of ZIP file in which files are stored.

  • sort (function or None) – Sort function used to sort file names when ‘files’ is a pattern. The default (None) is natural_sorted.

exception ParseError

Bases: Exception

asarray(file=None, out=None, *args, **kwargs)

Read image data from files and return as numpy array.

The args and kwargs parameters are passed to the imread function.

Raise IndexError or ValueError if image shapes do not match.

close()
class hyperspy.external.tifffile.FileHandle(file, mode='rb', name=None, offset=None, size=None)

Bases: object

Binary file handle.

A limited, special purpose file handler 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.

name

Name of the file.

Type

str

path

Absolute path to file.

Type

str

size

Size of file in bytes.

Type

int

is_file

If True, file has a filno and can be memory-mapped.

Type

bool

All attributes are read-only.

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.

close()

Close file.

property closed
property dirname
flush()

Flush write buffers if applicable.

is_file
property lock
memmap_array(dtype, shape, offset=0, mode='r', order='C')

Return numpy.memmap of data stored in file.

property name
open()

Open or re-open file.

property path
read(size=-1)

Read ‘size’ bytes from file, or until EOF is reached.

read_array(dtype, count=-1, sep='', chunksize=33554432, out=None, native=False)

Return numpy array from file.

Work around numpy issue #2230, “numpy.fromfile does not accept StringIO object” https://github.com/numpy/numpy/issues/2230.

read_record(dtype, shape=1, byteorder=None)

Return numpy record from file.

seek(offset, whence=0)

Set file’s current position.

property size
tell()

Return file’s current position.

write(bytestring)

Write bytestring to file.

write_array(data)

Write numpy array to binary file.

write_empty(size)

Append size bytes to file. Position must be at end of file.

class hyperspy.external.tifffile.TiffPage(parent, index, keyframe=None)

Bases: object

TIFF image file directory (IFD).

index

Index of page in file.

Type

int

dtype

Data type (native byte order) of the image in IFD.

Type

numpy.dtype or None

shape

Dimensions of the image in IFD.

Type

tuple

axes

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

Type

str

tags

Dictionary of tags in IFD. {tag.name: TiffTag}

Type

dict

colormap

Color look up table, if exists.

Type

numpy.ndarray

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.

Initialize instance from file.

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

andor_tags

Attribute whose value is computed on first access.

asarray(out=None, squeeze=True, lock=None, reopen=True, maxsize=17592186044416, 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; optional) – 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, 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 syncronize 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 or None) – 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 tile data. If None (default), up to half the CPU cores are used for compressed tiles. See remarks in TiffFile.asarray.

  • validate (bool) – If True (default), validate various parameters. If None, only validate parameters and return None.

Returns

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.

Return type

numpy.ndarray

aspage()
asrgb(uint8=False, alpha=None, colormap=None, dmin=None, dmax=None, *args, **kwargs)

Return image data as RGB(A).

Work in progress.

bitspersample = 1
colormap = None
compression = 1
description = ''
description1 = ''
epics_tags

Attribute whose value is computed on first access.

extrasamples = 1
fillorder = 1
flags

Attribute whose value is computed on first access.

geotiff_tags

Attribute whose value is computed on first access.

imagedepth = 1
imagelength = 0
imagewidth = 0
property is_andor

Page contains Andor Technology tags.

property is_chroma_subsampled

Page contains chroma subsampled image.

is_contiguous

Attribute whose value is computed on first access.

property is_epics

Page contains EPICS areaDetector tags.

property is_fei

Page contains SFEG or HELIOS metadata.

is_final

Attribute whose value is computed on first access.

property is_fluoview

Page contains FluoView MM_STAMP tag.

property is_geotiff

Page contains GeoTIFF metadata.

is_imagej

Attribute whose value is computed on first access.

property is_lsm

Page contains CZ_LSMINFO tag.

property is_mask

Page is transparency mask for another image.

property is_mdgel

Page contains MDFileTag tag.

property is_mediacy

Page contains Media Cybernetics Id tag.

is_memmappable

Attribute whose value is computed on first access.

property is_metaseries

Page contains MDS MetaSeries metadata in ImageDescription tag.

property is_micromanager

Page contains Micro-Manager metadata.

property is_mrc

Page is part of Mixed Raster Content.

property is_multipage

Page is part of multi-page image.

is_ndpi

Attribute whose value is computed on first access.

property is_nih

Page contains NIH image header.

property is_ome

Page contains OME-XML in ImageDescription tag.

property is_pilatus

Page contains Pilatus tags.

property is_qptiff

Page contains PerkinElmer tissue images metadata.

property is_reduced

Page is reduced image of another image.

property is_scanimage

Page contains ScanImage metadata.

property is_scn

Page contains Leica SCN XML in ImageDescription tag.

property is_sem

Page contains Zeiss SEM metadata.

property is_sgi

Page contains SGI image and tile depth tags.

is_shaped

Attribute whose value is computed on first access.

property is_sis

Page contains Olympus SIS metadata.

property is_stk

Page contains UIC2Tag tag.

property is_svs

Page contains Aperio metadata.

property is_tiled

Page contains tiled image.

property is_tvips

Page contains TVIPS metadata.

property is_vista

Software tag is ‘ISS Vista’.

property keyframe
property ndim

Return number of array dimensions.

ndpi_tags

Attribute whose value is computed on first access.

offsets_bytecounts

Attribute whose value is computed on first access.

photometric = 0
planarconfig = 1
predictor = 1
rowsperstrip = 4294967295
sampleformat = 1
samplesperpixel = 1
property size

Return number of elements in array.

software = ''
subfiletype = 0
tiledepth = 1
tilelength = 0
tilewidth = 0
class hyperspy.external.tifffile.TiffFrame(parent, index, keyframe)

Bases: 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 data from file, not for introspection of metadata.

Not compatible with Python 2.

Read specified tags from file.

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

asarray(*args, **kwargs)

Read image data from file and return as numpy array.

aspage()

Return TiffPage from file.

asrgb(*args, **kwargs)

Read image data from file and return RGB image as numpy array.

databytecounts
dataoffsets
index
property is_contiguous

Return offset and size of contiguous data, else None.

is_mdgel = False
property is_memmappable

Return if page’s image data in file can be memory-mapped.

keyframe
offset
property offsets_bytecounts

Return simplified offsets and bytecounts.

parent
tags = {}
class hyperspy.external.tifffile.TiffTag(parent, tagheader, tagoffset)

Bases: object

TIFF tag structure.

name

Name of tag.

Type

string

code

Decimal code of tag.

Type

int

dtype

Datatype of tag data. One of TIFF DATA_FORMATS.

Type

str

count

Number of values.

Type

int

value

Tag data as Python object.

Type

various types

ImageSourceData

Location of value in file.

Type

int

All attributes are read-only.

Initialize instance from tag header.

exception Error

Bases: Exception

code
count
dtype
property name
value
valueoffset
class hyperspy.external.tifffile.lazyattr(func)

Bases: object

Attribute whose value is computed on first access.

func
hyperspy.external.tifffile.natural_sorted(iterable)

Return human sorted list of strings.

E.g. for sorting file names.

>>> natural_sorted(['f1', 'f2', 'f10'])
['f1', 'f2', 'f10']
hyperspy.external.tifffile.stripnull(string, null=b'\x00')

Return string truncated at first null character.

Clean NULL terminated C strings. For unicode strings use null=’0’.

>>> stripnull(b'string\x00')
b'string'
>>> stripnull('string\x00', null='\0')
'string'
hyperspy.external.tifffile.transpose_axes(image, axes, asaxes='CTZYX')

Return image with its axes permuted to match specified axes.

A view is returned if possible.

>>> transpose_axes(numpy.zeros((2, 3, 4, 5)), 'TYXC', asaxes='CTZYX').shape
(5, 2, 1, 3, 4)
hyperspy.external.tifffile.squeeze_axes(shape, axes, skip='XY')

Return shape and axes with single-dimensional entries removed.

Remove unused dimensions unless their axes are listed in ‘skip’.

>>> squeeze_axes((5, 1, 2, 1, 1), 'TZYXC')
((5, 2, 1), 'TYX')
hyperspy.external.tifffile.create_output(out, shape, dtype, mode='w+', suffix='.memmap')

Return numpy array where image data of shape and dtype can be copied.

The ‘out’ parameter may have the following values or types:

None

An empty array of shape and dtype is created and returned.

numpy.ndarray

An existing writable array of compatible dtype and shape. A view of the same array is returned after verification.

‘memmap’ or ‘memmap:tempdir’

A memory-map to an array stored in a temporary binary file on disk is created and returned.

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. The created memory-mapped array is returned.

hyperspy.external.tifffile.repeat_nd(a, repeats)

Return read-only view into input array with elements repeated.

Zoom nD image by integer factors using nearest neighbor interpolation (box filter).

Parameters

  • a (array_like) – Input array.

  • repeats (sequence of int) – The number of repetitions to apply along each dimension of input array.

Example

>>> repeat_nd([[1, 2], [3, 4]], (2, 2))
array([[1, 1, 2, 2],
       [1, 1, 2, 2],
       [3, 3, 4, 4],
       [3, 3, 4, 4]])
hyperspy.external.tifffile.format_size(size, threshold=1536)

Return file size as string from byte size.

>>> format_size(1234)
'1234 B'
>>> format_size(12345678901)
'11.50 GiB'
hyperspy.external.tifffile.product(iterable)

Return product of sequence of numbers.

Equivalent of functools.reduce(operator.mul, iterable, 1). Multiplying numpy integers might overflow.

>>> product([2**8, 2**30])
274877906944
>>> product([])
1
hyperspy.external.tifffile.xml2dict(xml, sanitize=True, prefix=None)

Return XML as dict.

>>> xml2dict('<?xml version="1.0" ?><root attr="name"><key>1</key></root>')
{'root': {'key': 1, 'attr': 'name'}}
hyperspy.external.tifffile.pformat(arg, width=79, height=24, compact=True)

Return pretty formatted representation of object as string.

Whitespace might be altered.

hyperspy.external.tifffile.str2bytes(s, encoding='cp1252')

Return bytes from unicode string.