TIF

TIF module provides interface to read and write tif image files.

Note

This module relies on the tifffile library.

class BaseMetadataParser(source, metadata, info_categories)

Bases: object

parse()

parse_channels_excitation()

parse_date()

parse_description()

parse_order()

parse_overlap()

parse_pixel_metadata()

Parse only the pixel metadata (i.e. shape and order) from the OME metadata.

Returns

parse_resolution()

parse_shape()

parse_stitching()

parse_tile_configuration()

update_info(name, keys, mdict, astype)

property pixels_metadata

class ClearMapMetadataParser(source, metadata, info_categories)

Bases: BaseMetadataParser

Parser for ClearMap metadata.

Typically, this is tuned for the metadata of the ClearMap generated tif files which might lack some of the metadata fields but where the axes order is bound to be ‘XYZ’.

parse_order()

parse_resolution()

property pixels_metadata

class ImageJMetadataParser(source, metadata, info_categories)

Bases: BaseMetadataParser

parse_info_field()

parse_resolution()

property pixels_metadata

class OMEMetadataParser(source, metadata, info_categories)

Bases: BaseMetadataParser

Parser for OME metadata. Typically, this is tuned for the metadata of the OME-TIFF files generated by either the UltraMicroscopeII or the Blaze light-sheet microscopes from LaVision BioTec (now Miltenyi Biotec).

parse_channels_excitation()

parse_overlap()

parse_stitching(*, filename_order='YX')

parse_tile_configuration(*, filename_order='YX')

Build a tile configuration dictionary.

Constructs a nested dictionary mapping channels and tile coordinates to tile metadata including filenames and stage/relative positions.

Parameters:

filename_order (str, optional) – Order of axes in filename pattern (default: ‘YX’).

Returns

dict

Nested dict with structure: {channel: {(ix, iy): {…}}} where each tile dict contains:

• ‘filename’str

  Tile filename basename.

• ‘stage_x’, ‘stage_y’float

  Stage coordinates.

• ‘relative_x’, ‘relative_y’float

  Normalized coordinates (min per axis = 0 across all tiles).

Notes

Tile coordinates (ix, iy) are extracted from the filename ‘YY x XX’ pattern, or from FilenameAxesMap if the pattern is absent.

property img_custom_attrs

property pixels_metadata

class Source(location, series=0, multi_file=False, mode=None)

Bases: Source

Class to handle a tif file source

Note

Its assumed that the image data is stored in a series of the tif file.

Warning

It is also assumed that the last 3 dimensions are the image dimensions in the order z,y,x.

as_buffer()

as_memmap()

as_real()

as_virtual()

Return virtual source without array data to pass in parallel processing.

Returns

sourceSource class

The source class without array data.

get_raw_metadata_dictionary()

metadata(info=('shape', 'resolution', 'overlap'))

Returns metadata from this tif file.

Arguments

infolist, ‘all’ or None

Optional list of keywords, if ‘all’ return full tif metadata, if None return default set info.

Returns

metadatadict

Dictionary with the metadata.

to_clearmap_order(array)

property array

property axes_order

property dtype

The data type of the source.

Returns

dtypedtype

The data type of the source.

property element_strides

The strides of the array elements.

Returns

stridestuple

Strides of the array elements.

Note

The strides of the elements module itemsize instead of bytes.

property is_clearmap

property location

The location where the data of the source is stored.

Returns

locationstr or None

Returns the location of the data source or None if this source lives in memory only.

property pages_mode

series

Attribute whose value is computed on first access.

property series_mode

property shape

The shape of the source.

Returns

shapetuple

The shape of the source.

property tif_shape

class TileRecord(basename, channel, stage_x, stage_y, ix, iy)

Bases: NamedTuple

basename: str

Alias for field number 0

channel: int

Alias for field number 1

ix: int | None

Alias for field number 4

iy: int | None

Alias for field number 5

stage_x: float

Alias for field number 2

stage_y: float

Alias for field number 3

class VirtualSource(source=None, shape=None, dtype=None, order=None, location=None, name=None, mode=None)

Bases: VirtualSource

as_real()

Default: reopen from location with mode. Override in modules that need extra constructor args.

array_to_tif(array, source_order='ZYX')

create(location=None, shape=None, dtype=None, mode=None, as_source=True, **kwargs)

Create a memory map.

Arguments

locationstr

The filename of the memory mapped array.

shapetuple or None

The shape of the memory map to create.

dtypedtype

The data type of the memory map.

mode‘r’, ‘w’, ‘w+’, None

The mode to open the memory map.

as_sourcebool

If True, return as Source class.

Returns

memmapnp.memmap

The memory map.

Note

By default memmaps are initialized as fortran contiguous if order is None.

is_tif(source)

Checks if this is a TIF source

map_axes(source_order, dest_order, ndim=None)

Generate a mapping of axes from source order to destination order. The mapping is a tuple of integers that can be used with np.transpose to reorder the axes of an array.

Parameters:

• source_order (str) – The order of the axes in the source array (e.g., ‘ZYX’).

• dest_order (str) – The desired order of axes in the output array (e.g., ‘XYZ’).

Returns

tuple

A tuple of integers that can be used with np.transpose to reorder the axes of an array.

read(source, slicing=None, sink=None, **args)

Read data from a tif file.

Arguments

sourcestr or TIF class

The name of the tif file or a TIF class.

slicingslice, Slice or None

An optional sub-slice to consider.

Returns

dataarray

The image data in the tif file.

reorder_shape(shape, order, dest_order)

Rearrange the shape tuple to match the given order.

Parameters:

• shape (tuple) – The original shape of the array

• order (str) – The order of the axes in the array (e.g., ‘ZYX’ or ‘CZYX’)

• dest_order (str) – The desired order of axes in the output array (e.g., ‘XYZ’ or ‘XYZC’)

Returns

tuple

The shape rearranged to match the given order

shape_from_tif(shape, order='XYZ', dest_order='ZYX')

Rearrange the shape tuple to match the ‘XYZ’ (or ‘XYZC’) order based on the given axes order.

Parameters:

• shape (tuple) – The original shape of the array.

• order (str) – The order of the axes in the array (e.g., ‘ZYX’ or ‘CZYX’). Default is ‘XYZ’ (Default tiff order).

• dest_order (str) – The desired order of axes in the output array (e.g., ‘XYZ’ or ‘XYZC’). Default is ‘ZYX’ (ClearMap array order).

Returns

tuple

The shape rearranged to match the ‘XYZ’ (or ‘XYZC’) order.

shape_to_tif(shape, order='ZYX', dest_order='XYZ')

Rearrange the shape tuple to match the ‘XYZ’ (or ‘XYZC’) order based on the given axes order.

Parameters:

• shape (tuple) – The original shape of the array.

• order (str) – The order of the axes in the array (e.g., ‘ZYX’ or ‘CZYX’). Default is ‘ZYX’ (ClearMap array order).

• dest_order (str) – The desired order of axes in the output array (e.g., ‘XYZ’ or ‘XYZC’). Default is ‘XYZ’ (Default tiff order).

Returns

tuple

The shape rearranged to match the ‘XYZ’ (or ‘XYZC’) order.

tif_to_clearmap_order(array, array_order='XYZ')

Transpose the axes on array to the ClearMap order (‘ZYX’)

Parameters:

• array (np.ndarray) – The array to transpose

• array_order (str) – The order of the input array (with letters representing the axes)

Returns

The transposed array

transpose_array(array, source_order, dest_order)

Transpose the axes on array from source_order to dest_order.

Parameters:

• array (np.ndarray) – The array to transpose

• source_order (str) – The order of the axes in the array (with letters representing the axes)

• dest_order (str) – The desired order of axes in the output array (with letters representing the axes)

Returns

The transposed array

write(sink, data, **args)

Write data to a tif file

Arguments

sinkstr

The name of the tif file.

Returns

sinkstr

The name of the tif file.