BrukerTiffImagingExtractors

ImagingExtractors for the TIFF image format produced by Bruker.

Classes

BrukerTiffImagingExtractor

Unified extractor for Bruker OME-TIFF files. Inherits from OMETiffImagingExtractor.

BrukerTiffSinglePlaneImagingExtractor

Deprecated. Use BrukerTiffImagingExtractor instead.

BrukerTiffMultiPlaneImagingExtractor

Deprecated. Use BrukerTiffImagingExtractor instead.

filter_read_uic_tag_warnings(record)

Filter out the warnings from tifffile.read_uic_tag() that are not relevant to the user.

class BrukerTiffImagingExtractor(folder_path: str | Path, channel_name: str | None = None)

Bases: OMETiffImagingExtractor

An extractor for Bruker Prairie View OME-TIFF files.

Inherits from OMETiffImagingExtractor and adds automatic sampling frequency computation from the Bruker configuration XML. Supports single-plane, volumetric, and multi-channel data.

The user provides a folder path containing .ome.tif files and a Bruker configuration XML. The extractor reads structural metadata (dimensions, channels, planes, file layout) from the OME-XML embedded in the first TIFF file, and computes sampling frequency from the relativeTime attributes in the Bruker XML.

Parameters:

• folder_path (str or Path) – Path to the folder containing Bruker .ome.tif files and the configuration XML.

• channel_name (str or None, optional) – Name of the channel to extract. Required when the data has more than one channel. Channel names are zero-indexed strings (e.g., “0”, “1”).

Initialize the extractor with file paths and dimension information.

Parameters:

• file_paths (list[PathType]) – List of paths to TIFF files.

• sampling_frequency (float) – The sampling frequency in Hz. Note that if your data is volumetric the sampling rate is the sampling rate of the volume, not the individual frames.

• dimension_order (str, optional) – The order of dimensions in the data. Must be one of: ZCT, ZTC, CTZ, TCZ, CZT, TZC. This follows the OME-TIFF specification for dimension order, but excludes the XY dimensions which are assumed to be the first two dimensions. Default is “TZC” (time-first, suitable for planar single-channel data). See Notes section for detailed explanations of each dimension order.

• num_channels (int, optional) – Number of channels in the data. Default is 1 (single channel).

• channel_name (str, optional) – Name of the channel to extract (e.g., “0”, “1”). Only required when num_channels > 1. For single-channel data, this parameter is ignored. Default is None.

• num_planes (int, optional) – Number of depth planes (Z-slices) per volume. Default is 1 (planar data).

Notes

Dimension Order Notes

This class follows a subset of the OME-TIFF dimension order specification, focusing on the Z (depth), C (channel), and T dimensions. The XY spatial dimensions are assumed to be the first two dimensions of each frame and are not included in the dimension_order parameter.

While we use ‘T’ for compatibility with the OME-TIFF standard, we emphasize that its meaning varies significantly based on position: - When T is first (TCZ, TZC): Represents oversampling - multiple samples acquired at

each depth or channel: - TCZ: T samples per channel at each depth position - TZC: T samples per depth position for each channel

• When T is middle (ZTC, CTZ): Represents repetitions - repeated acquisitions of

  sub-structures before varying the outer dimension - ZTC: T repetitions of each Z-stack before switching channels - CTZ: T repetitions of the full channel set at each depth

• When T is last (ZCT, CZT): Represents acquisition cycles - complete acquisitions

  of the entire multi-channel, multi-plane dataset - ZCT: T complete multi-channel volumes where the depth is varied first - CZT: T complete multi-channel volumes where the channel is varied first

For more information on OME-TIFF dimension order, see: https://docs.openmicroscopy.org/ome-model/5.6.3/ome-tiff/specification.html

Acquisition Patterns

ZCT (Depth → Channel → Acquisition Cycles)

Acquire a complete Z-stack for the first channel, then switch to the next channel and acquire its full Z-stack. After all channels are acquired, this constitutes one acquisition cycle. Repeat for T acquisition cycles.

ZTC (Depth → Repetitions → Channel)

Acquire full Z-stacks repeated T times for a single channel, then switch to the next channel and acquired another T repetitions of the full Z-stack for that channel. Repeat the same process for all channels.

CZT (Channel → Depth → Acquisition Cycles)

At the first depth position, acquire all channels sequentially. Move to the next depth and acquire all channels again. After completing all depths, one acquisition cycle is complete. Repeat for T acquisition cycles.

CTZ (Channel → Repetitions → Depth)

At a fixed depth position, acquire all channels, then repeat this channel acquisition T times. Then move to the next depth position and repeat the pattern of T repetitions of all channels.

TCZ (Oversampling → Channel → Depth)

At a fixed depth position, acquire T samples for the first channel, then acquire T samples for the next channel. After oversampling all channels at this depth, move to the next depth position and repeat.

TZC (Oversampling → Depth → Channel)

For a fixed channel, acquire T samples at the first depth, then T samples at the second depth, continuing through all depths. Switch to the next channel and repeat the entire oversampling pattern across depths.

Special Cases

When data has only a single channel (num_channels=1):

ZCT, ZTC, CZT → ZT: Volumetric time series (complete volumes acquired sequentially)

CTZ, TCZ, TZC → TZ: Plane-by-plane time series (T samples at each depth before moving to next)

When data is planar (num_planes=1):

ZCT, CZT, CTZ → CT: Channel-first acquisition patterns (one full channel sweep after another)

ZTC, TCZ, TZC → TC: Time-first acquisition patterns (full data for one channel and then the next)

When data is both single-channel AND planar:

All dimension orders → T: Simple planar time series (all orderings equivalent)

get_native_timestamps(start_sample: int | None = None, end_sample: int | None = None) → ndarray

Extract per-sample timestamps from Frame relativeTime attributes in the Bruker XML.

For volumetric data, frames alternate between planes; every num_planes-th timestamp corresponds to one volume (sample).

class BrukerTiffMultiPlaneImagingExtractor(folder_path: str | Path, stream_name: str | None = None)

Bases: MultiImagingExtractor

A MultiImagingExtractor for TIFF files produced by Bruke with multiple planes.

This format consists of multiple TIF image files (.ome.tif) and configuration files (.xml, .env).

Create a BrukerTiffMultiPlaneImagingExtractor instance from a folder path that contains the image files.

Deprecated since version Use: BrukerTiffImagingExtractor instead.

Parameters:

• folder_path (PathType) – The path to the folder that contains the Bruker TIF image files (.ome.tif) and configuration files (.xml, .env).

• stream_name (str, optional) – The name of the recording channel (e.g. “Ch2”).

Raises:

• ValueError – If more than one recording stream is detected.

• ValueError – If the selected stream is not in the available plane_streams.

• AssertionError – If the TIF image files are missing from the folder.

• AssertionError – If the imaging is not volumetric.

classmethod get_streams(folder_path: str | Path) → dict

Get the available streams from the Bruker TIF image files (.ome.tif) and configuration files (.xml, .env).

Parameters:

folder_path (PathType) – The path to the folder that contains the Bruker TIF image files (.ome.tif) and configuration files (.xml, .env).

Returns:

streams – The dictionary of available streams.

Return type:

dict

get_image_shape() → tuple[int, int]

Get the shape of the video frame (num_rows, num_columns).

Returns:

image_shape – Shape of the video frame (num_rows, num_columns).

Return type:

tuple

get_num_samples() → int

Get the number of samples in the video.

Returns:

num_samples – Number of samples in the video.

Return type:

int

get_sampling_frequency() → float

Get the sampling frequency in Hz.

Returns:

sampling_frequency – Sampling frequency in Hz.

Return type:

float

get_series(start_sample: int | None = None, end_sample: int | None = None) → ndarray

Get the video frames.

Parameters:

• start_sample (int, optional) – Start sample index (inclusive).

• end_sample (int, optional) – End sample index (exclusive).

Returns:

series – The video frames.

Return type:

numpy.ndarray

get_num_planes() → int

Get the number of depth planes.

Returns:

num_planes – The number of depth planes.

Return type:

int

get_volume_shape() → tuple[int, int, int]

Get the shape of the volumetric video (num_rows, num_columns, num_planes).

Returns:

video_shape – Shape of the volumetric video (num_rows, num_columns, num_planes).

Return type:

tuple

class BrukerTiffSinglePlaneImagingExtractor(folder_path: str | Path, stream_name: str | None = None)

Bases: MultiImagingExtractor

A MultiImagingExtractor for TIFF files produced by Bruker with only 1 plane.

Create a BrukerTiffSinglePlaneImagingExtractor instance from a folder path that contains the image files.

Deprecated since version Use: BrukerTiffImagingExtractor instead.

Parameters:

• folder_path (PathType) – The path to the folder that contains the Bruker TIF image files (.ome.tif) and configuration files (.xml, .env).

• stream_name (str, optional) – The name of the recording channel (e.g. “Ch2” or “Green”).

classmethod get_streams(folder_path: str | Path) → dict

Get the available streams from the Bruker TIF image files (.ome.tif) and configuration files (.xml, .env).

Parameters:

folder_path (PathType) – The path to the folder that contains the Bruker TIF image files (.ome.tif) and configuration files (.xml, .env).

Returns:

streams – The dictionary of available streams.

Return type:

dict

static get_available_channels(folder_path: str | Path) → set[str]

Extract set of available channel names from the XML configuration file in the specified folder.

Parameters:

folder_path (PathType) – The path to the folder containing the XML configuration file. It can be either a string or a Path object.

Returns:

A set of channel names available in the first ‘Frame’ element found in the XML configuration file.

Return type:

Set[str]

get_image_shape() → tuple[int, int]

Get the shape of the video frame (num_rows, num_columns).

Returns:

image_shape – Shape of the video frame (num_rows, num_columns).

Return type:

tuple

get_sampling_frequency() → float

Get the sampling frequency in Hz.

Returns:

sampling_frequency – Sampling frequency in Hz.

Return type:

float

get_dtype() → dtype

Get the data type of the video.

Returns:

dtype – Data type of the video.

Return type:

dtype