API Reference

Yet another Bio-Formats wrapper for Python.

Classes:

Name	Description
`BioFile`	Read image and metadata from file supported by Bioformats.
`CoreMetadata`	Core metadata for a single series.
`LazyBioArray`	Pythonic lazy array interface for a single Bio-Formats Series/Resolution.
`OMEShape`	NamedTuple with OME metadata shape.
`Series`	Proxy for a single series within a `BioFile`.

Functions:

Name	Description
`imread`	Read image data from a Bio-Formats-supported file into a numpy array.
`open_ome_zarr_group`	Read image data from a Bio-Formats-supported file as a zarr array or group.
`open_zarr_array`	Read image data from a Bio-Formats-supported file as a zarr array.

BioFile

BioFile(
    path: str | PathLike,
    *,
    meta: bool = True,
    original_meta: bool = False,
    memoize: int | bool = 0,
    options: dict[str, bool] | None = None,
    channel_filler: bool | None = None,
)

Read image and metadata from file supported by Bioformats.

BioFile instances must be explicitly opened before use, either by:

Using a context manager: with BioFile(path) as bf: ...
Explicitly calling open(): bf = BioFile(path).open()

The recommended pattern is to use the context manager, which automatically handles opening and closing the file and cleanup of Java resources; but many usage patterns will also require explicit open/close.

BioFile instances are not thread-safe. Create separate instances per thread.

Lifecycle

BioFile manages the underlying Java reader through three states:

UNINITIALIZED ── open() ──> OPEN ── close() ──> SUSPENDED
     ↑    ↑                  │ ↑                     │
     │    └── destroy() ─────┘ └──── open() ─────────┘
     └─────── destroy() ─────────────────────────────┘

open() first call: full initialization via Java:setId() (slow).
close(): releases file handles but preserves all parsed metadata and reader state in memory (Java:close(fileOnly=true)).
open() after close(): fast: simply reacquires the file handle — no re-parsing.
destroy() / __exit__(): full teardown — releases the Java reader and all cached state, returning to UNINITIALIZED. open() can be called again but will require full re-initialization.
__del__ GC finalizer: equivalent to destroy().

SUSPENDED preserves the Java reader's parsed state (format-specific headers, CoreMetadata, OME-XML DOM, metadata hashtable) in JVM heap, as well as Python-side core_metadata(). Only file handles are released. This is what enables the fast open() path.

destroy() releases all of these, making the Java objects eligible for JVM garbage collection. The BioFile reverts to its initial state.

Parameters:

Name	Type	Description	Default
`path`	`str or Path`	Path to file	required
`meta`	`bool`	Whether to get metadata as well, by default True	`True`
`original_meta`	`bool`	Whether to also retrieve the proprietary metadata as structured annotations in the OME output, by default False	`False`
`memoize`	`bool or int`	Threshold (in milliseconds) for memoizing the reader. If the time required to call `reader.setId()` is larger than this number, the initialized reader (including all reader wrappers) will be cached in a memo file, reducing time to load the file on future reads. By default, this results in a hidden `.bfmemo` file in the same directory as the file. The `BIOFORMATS_MEMO_DIR` environment can be used to change the memo file directory. Set `memoize` to greater than 0 to turn on memoization, by default it's off. https://downloads.openmicroscopy.org/bio-formats/latest/api/loci/formats/Memoizer.html	`0`
`options`	`dict[str, bool]`	A mapping of option-name -> bool specifying additional reader-specific options. See: https://docs.openmicroscopy.org/bio-formats/latest/formats/options.html For example: to turn off chunkmap table reading for ND2 files, use `options={"nativend2.chunkmap": False}`	`None`
`channel_filler`	`bool or None`	Whether to wrap the reader with Bio-Formats' ChannelFiller, which expands indexed-color data (e.g. GIF palettes) into RGB. If `True`, always use ChannelFiller. If `False`, never use it. If `None` (default), automatically apply it when the file contains true indexed-color data.	`None`

Methods:

Name	Description
`__enter__`	Enter context manager - ensures file is open.
`__exit__`	Exit context manager — full resource cleanup, including the Java reader.
`__getitem__`	Return a `Series` proxy for the given index.
`__iter__`	Iterate over all series in the file.
`__len__`	Return the number of series in the file.
`as_array`	Return a lazy numpy-compatible array that reads data on-demand.
`bioformats_maven_coordinate`	Return the Maven coordinate used to load Bio-Formats.
`bioformats_version`	Get the version of Bio-Formats.
`close`	Close file handles while preserving reader state for fast reopen.
`core_metadata`	Get metadata for specified series and resolution.
`destroy`	Full cleanup — release all Java resources and cached state.
`ensure_open`	Context manager that temporarily opens the file if closed.
`get_thumbnail`	Get thumbnail image for specified series.
`global_metadata`	Return the global metadata as a dictionary.
`list_available_readers`	List all available Bio-Formats readers.
`list_supported_suffixes`	List all file suffixes supported by the available readers.
`lookup_table`	Return the color lookup table for an indexed-color series.
`open`	Open file and initialize reader, or re-open if previously closed.
`read_plane`	Read a single plane or sub-region directly from Bio-Formats.
`series_count`	Return the number of series in the file (same as `__len__`).
`to_dask`	Create dask array for lazy computation on Bio-Formats data.
`to_xarray`	Return xarray.DataArray for specified series and resolution.
`to_zarr_store`	Return a zarr v3 group store containing all series and resolutions.
`used_files`	Return complete list of files needed to open this dataset.

closed `property`

closed: bool

Return True if the file is currently closed (uninitialized or suspended).

filename `property`

filename: str

Return name of file handle.

ome_metadata `property`

ome_metadata: OME

Return ome_types.OME object parsed from OME XML.

ome_xml `property`

ome_xml: str

Return plain OME XML string.

suspended `property`

suspended: bool

Return True if the file is currently suspended (closed but not destroyed).

"Suspended" means: - we have previously opened the file and parsed the metadata - we retain the initialized Java reader and its state in the JVM - but we have released the file handles to free up system resources

enter

__enter__() -> Self

Enter context manager - ensures file is open.

exit

__exit__(*_args: Any) -> None

Exit context manager — full resource cleanup, including the Java reader.

getitem

__getitem__(index: int) -> Series

__getitem__(index: slice) -> list[Series]

__getitem__(index: int | slice) -> Series | list[Series]

Return a Series proxy for the given index.

Parameters:

Name	Type	Description	Default
`index`	`int \| slice`	Series index or slice of series indices to retrieve	required

iter

__iter__() -> Iterator[Series]

Iterate over all series in the file.

len

__len__() -> int

Return the number of series in the file.

as_array

as_array(
    series: int = 0, resolution: int = 0
) -> LazyBioArray

Return a lazy numpy-compatible array that reads data on-demand.

The returned array behaves like a numpy array but reads data from disk only when indexed. Use it just like a numpy array - any indexing operation will read only the requested planes or sub-regions, not the entire dataset.

Supports integer and slice indexing on all dimensions. The array also implements the __array__() protocol for seamless numpy integration.

Parameters:

Name	Type	Description	Default
`series`	`int`	Series index, by default 0	`0`
`resolution`	`int`	Resolution level (0 = full resolution), by default 0. Negative indexing supported (e.g., -1 = lowest resolution).	`0`

Returns:

Type	Description
`LazyBioArray`	Lazy array in (T, C, Z, Y, X) or (T, C, Z, Y, X, rgb) format

Examples:

Index like a numpy array - only reads what you request:

>>> with BioFile("image.nd2") as bf:
...     arr = bf.as_array()  # No data read yet
...
...     # Read single plane (t=0, c=0, z=2)
...     plane = arr[0, 0, 2]  # Only this plane read from disk
...
...     # Read all timepoints for one channel/z
...     timeseries = arr[:, 0, 2]  # Reads T planes
...
...     # Read sub-region across entire volume
...     roi = arr[:, :, :, 100:200, 50:150]  # Reads 100x50 sub-regions
...
...     # Materialize entire dataset (two equivalent ways)
...     full_data = arr[:]  # Using slice notation
...     full_data = np.array(arr)  # Using numpy conversion

Notes

BioFile must remain open while using the array. Multiple arrays can coexist, each reading from their own series independently.

Planes >2GB automatically use tiled reading (transparent, ~20% slower).

bioformats_maven_coordinate `staticmethod`

bioformats_maven_coordinate() -> str

Return the Maven coordinate used to load Bio-Formats.

This was either provided via the BIOFORMATS_VERSION environment variable, or is the default value, in format "groupId:artifactId:version", See https://mvnrepository.com/artifact/ome for available versions.

bioformats_version `staticmethod`

bioformats_version() -> str

Get the version of Bio-Formats.

close

close() -> None

Close file handles while preserving reader state for fast reopen.

Releases the underlying file handle via Java close(fileOnly=true) but keeps all parsed metadata and reader state in memory. A subsequent open() call will cheaply reacquire the file handle.

Metadata remains accessible via core_metadata() and len() while the file is closed.

Safe to call multiple times — no-op if already closed.

core_metadata

core_metadata(
    series: int = 0, resolution: int = 0
) -> CoreMetadata

Get metadata for specified series and resolution.

Parameters:

Name	Type	Description	Default
`series`	`int`	Series index, by default 0	`0`
`resolution`	`int`	Resolution level (0 = full resolution), by default 0. Negative indexing supported (e.g., -1 = lowest resolution).	`0`

Returns:

Type	Description
`CoreMetadata`	Metadata for the specified series and resolution

Raises:

Type	Description
`RuntimeError`	If file is not open
`IndexError`	If series or resolution index is out of bounds

Notes

Resolution support is included for future compatibility, but currently only resolution 0 (full resolution) is exposed in the public API.

destroy

destroy() -> None

Full cleanup — release all Java resources and cached state.

Releases the Java reader and all parsed metadata, returning to UNINITIALIZED. open() can be called again but will require full re-initialization (slow path). The GC finalizer calls this automatically if not called explicitly.

Safe to call multiple times or from any state.

ensure_open

ensure_open() -> _EnsureOpenContext

Context manager that temporarily opens the file if closed.

Opens the file if needed, then on exit: suspends if it started closed (uninitialized or suspended), or leaves open if it started open. This allows temporary access without disrupting the caller's file state.

Note: "closed" encompasses both uninitialized and suspended states. Files starting uninitialized will end suspended (not destroyed).

Returns:

Type	Description
`_EnsureOpenContext`	Context manager that restores open/closed state on exit.

Examples:

bf = BioFile(path)

# Started uninitialized -> ends suspended
with bf.ensure_open():
    data = bf.read_plane()
assert bf.suspended  # not destroyed

# Started open -> stays open
bf.open()
with bf.ensure_open():
    data = bf.read_plane()
assert not bf.closed

get_thumbnail

get_thumbnail(
    series: int = 0,
    *,
    t: int = 0,
    c: int = 0,
    z: int | None = None,
    max_thumbnail_size: int | tuple[int, int] = 128,
    max_read_size: int = 4096,
) -> np.ndarray

Get thumbnail image for specified series.

Returns a downsampled version of the specified plane from the specified series, channel, timepoint, and z-slice (default: central slice). The thumbnail is scaled to fit within max_thumbnail_size pixels while maintaining aspect ratio.

This method reads the lowest resolution level available for the series, and then downsamples it to create the thumbnail. If the lowest resolution is still larger than max_read_size, it will read a centered sub-region of the lowest resolution, no greater than max_read_size in either dimension.

Note

For stability and performance, this does not use the java openThumbBytes API.

Parameters:

Name	Type	Description	Default
`series`	`int`	Series index to get thumbnail from, by default 0	`0`
`t`	`int`	Time index for thumbnail plane, by default 0	`0`
`c`	`int`	Channel index for thumbnail plane, by default 0	`0`
`z`	`int \| None`	Z-slice index for thumbnail plane, by default None (take the central slice)	`None`
`max_thumbnail_size`	`int \| tuple[int, int]`	Maximum thumbnail size. If int, limits both width and height to this value. If tuple, interpreted as `(max_width, max_height)`.	`128`
`max_read_size`	`int`	Maximum dimension size to read directly from Bio-Formats before switching. If this is lower than the size of the full plane, the image will be cropped. Decrease for speed, increase for field of view.	`4096`

Returns:

Type	Description
`ndarray`	Thumbnail image as numpy array with shape (H, W) for grayscale or (H, W, RGB) for RGB images.

global_metadata

global_metadata() -> Mapping[str, Any]

Return the global metadata as a dictionary.

This includes all metadata that is not specific to a particular series or resolution. The exact contents will depend on the file and reader, but may include things like instrument information, acquisition settings, and other annotations.

Returns:

Type	Description
`Mapping[str, Any]`	Global metadata key-value pairs

Raises:

Type	Description
`RuntimeError`	If file is not open

list_available_readers `cached` `staticmethod`

list_available_readers() -> list[ReaderInfo]

List all available Bio-Formats readers.

Returns:

Type	Description
`list[ReaderInfo]`	Information about each available reader, including: format: human-readable format name (e.g., "Nikon ND2") suffixes: supported file extensions (e.g., ("nd2", "jp2")) class_name: full Java class name (e.g., "ND2Reader") is_gpl: whether this reader requires GPL license (True) or is BSD (False)

list_supported_suffixes `cached` `staticmethod`

list_supported_suffixes() -> set[str]

List all file suffixes supported by the available readers.

lookup_table

lookup_table(series: int = 0) -> np.ndarray | None

Return the color lookup table for an indexed-color series.

Parameters:

Name	Type	Description	Default
`series`	`int`	Series index, by default 0.	`0`

Returns:

Type	Description
`ndarray \| None`	Array of shape `(N, 3)` with RGB values for each pixel index, or None if the series is not indexed.

Examples:

To convert this object to a [cmap.Colormap][]:

``python import cmap from bffile import BioFile

with BioFile("indexed_image.ome.tiff") as bf: lut = bf.lookup_table() if lut is not None: colormap = cmap.Colormap(lut / lut.max()) # Normalize to [0, 1] ``

open

open() -> Self

Open file and initialize reader, or re-open if previously closed.

On first call, performs full initialization (setId). If the file was previously closed via close(), reopens cheaply by reacquiring only the file handle without re-parsing.

Safe to call multiple times — no-op if already open.

Returns:

Type	Description
`Self`	Returns `self` for method chaining.

Examples:

# Method chaining
bf = BioFile(path).open()

# Or two lines
bf = BioFile(path)
bf.open()

read_plane

read_plane(
    t: int = 0,
    c: int = 0,
    z: int = 0,
    y: slice | None = None,
    x: slice | None = None,
    series: int = 0,
    resolution: int = 0,
    buffer: ndarray | None = None,
) -> np.ndarray

Read a single plane or sub-region directly from Bio-Formats.

Low-level method wrapping Bio-Formats' openBytes() API. Provides fine-grained control for reading specific planes or rectangular sub-regions. Most users should use as_array() or to_dask() instead.

Not thread-safe. Create separate BioFile instances per thread.

Parameters:

Name	Type	Description	Default
`t`	`int`	Time index, by default 0	`0`
`c`	`int`	Channel index, by default 0	`0`
`z`	`int`	Z-slice index, by default 0	`0`
`y`	`slice`	Y-axis slice (default: full height). Example: `slice(100, 200)`	`None`
`x`	`slice`	X-axis slice (default: full width). Example: `slice(50, 150)`	`None`
`series`	`int`	Series index, by default 0	`0`
`resolution`	`int`	Resolution level (0 = full resolution), by default 0. Negative indexing supported (e.g., -1 = lowest resolution).	`0`
`buffer`	`ndarray`	Pre-allocated buffer for efficient reuse in loops	`None`

Returns:

Type	Description
`ndarray`	Shape (height, width) for grayscale or (height, width, rgb) for RGB

Examples:

>>> with BioFile("image.nd2") as bf:
...     plane = bf.read_plane(t=0, c=1, z=5)
...     roi = bf.read_plane(y=slice(200, 300), x=slice(200, 300))

series_count

series_count() -> int

Return the number of series in the file (same as __len__).

to_dask

to_dask(
    series: int = 0,
    resolution: int = 0,
    *,
    chunks: str | tuple = "auto",
    tile_size: tuple[int, int] | str | None = None,
) -> dask.array.Array

Create dask array for lazy computation on Bio-Formats data.

Returns a dask array in TCZYX[r] order that wraps a LazyBioArray. Uses single-threaded scheduler for Bio-Formats thread safety.

Parameters:

Name	Type	Description	Default
`series`	`int`	Series index to read from, by default 0	`0`
`resolution`	`int`	Resolution level (0 = full resolution), by default 0. Negative indexing supported (e.g., -1 = lowest resolution).	`0`
`chunks`	`str or tuple`	Chunk specification. Examples: - "auto": Let dask decide (default) - (1, 1, 1, -1, -1): Full Y,X planes per T,C,Z - (1, 1, 1, 512, 512): 512x512 tiles Mutually exclusive with tile_size.	`"auto"`
`tile_size`	`tuple[int, int] or 'auto'`	Tile-based chunking for Y,X dimensions (T,C,Z get chunks of 1). - (512, 512): Use 512x512 tiles - "auto": Query Bio-Formats optimal tile size Mutually exclusive with chunks.	`None`

Returns:

Type	Description
`Array`	Dask array that reads data on-demand. Shape is (T, C, Z, Y, X) or (T, C, Z, Y, X, rgb) for RGB images.

Raises:

Type	Description
`ValueError`	If both chunks and tile_size are specified

Examples:

>>> with BioFile("image.nd2") as bf:
...     darr = bf.to_dask(chunks=(1, 1, 1, -1, -1))
...     result = darr.mean(axis=2).compute()  # Z-projection

Notes

BioFile must remain open during computation
Uses synchronous scheduler by default (required for thread safety)

to_xarray

to_xarray(
    series: int = 0, resolution: int = 0
) -> xr.DataArray

Return xarray.DataArray for specified series and resolution.

The returned DataArray has .dims and .coords attributes populated according to the metadata. Dimension and coord names will be one of: TCZYXS, where S represents the RGB/RGBA channels if present. The parsed ome_types.OME object is also available in the .attrs['ome_metadata'] attribute of the DataArray.

Parameters:

Name	Type	Description	Default
`series`	`int`	Series index to read from, by default 0	`0`
`resolution`	`int`	Resolution level (0 = full resolution), by default 0. Negative indexing supported (e.g., -1 = lowest resolution).	`0`

to_zarr_store

to_zarr_store(
    series: Literal[None] = ...,
    *,
    tile_size: tuple[int, int] | None = ...,
) -> BFOmeZarrStore

to_zarr_store(
    series: int,
    resolution: int = ...,
    *,
    tile_size: tuple[int, int] | None = ...,
) -> BFArrayStore

to_zarr_store(
    series: int | None = None,
    resolution: int = 0,
    *,
    tile_size: tuple[int, int] | None = None,
) -> BFOmeZarrStore | BFArrayStore

Return a zarr v3 group store containing all series and resolutions.

Creates an OME-ZARR group structure following NGFF v0.5 specification, with full hierarchy including all series and resolution levels. Useful for tools like napari that expect complete OME-ZARR groups.

Directory structure::

root/
├── zarr.json (group metadata)
├── OME/
│   ├── zarr.json (series list)
│   └── METADATA.ome.xml (raw OME-XML)
├── 0/ (series 0 - multiscales group)
│   ├── zarr.json (multiscales metadata with axes/datasets)
│   ├── 0/ (full resolution)
│   │   ├── zarr.json (array metadata)
│   │   └── c/... (chunk data)
│   └── 1/ (downsampled, if exists)
└── 1/ (series 1, if exists)

Parameters:

Name	Type	Description	Default
`series`	`int`	If provided, only return the specified series and resolution as a single array store. By default, returns the full group store with all series and resolutions.	`None`
`resolution`	`int`	Resolution level (0 = full resolution), by default 0. Negative indexing supported (e.g., -1 = lowest resolution).	`0`
`tile_size`	`tuple[int, int]`	If provided, Y and X are chunked into tiles of this size instead of full planes. Chunk shape becomes `(1, 1, 1, tile_y, tile_x)`.	`None`

Returns:

Type	Description
`BFOmeZarrStore`	Read-only zarr v3 Store containing the full file hierarchy.

Examples:

Open as zarr group and access arrays:

>>> import zarr
>>> with BioFile("image.nd2") as bf:
...     group = zarr.open_group(bf.to_zarr_store(), mode="r")
...     # Access first series, full resolution
...     arr = group["0/0"]
...     data = arr[0, 0, 0]
...
...     # Check multiscales metadata
...     print(group["0"].attrs["ome"]["multiscales"])
...
...     # Save to disk
...     bf.to_zarr_store().save("output.ome.zarr")

Notes

For single array access, prefer as_array().to_zarr_store() (simpler)
This creates the full hierarchy needed for multi-series/multi-resolution visualization tools
Conforms to NGFF v0.5 specification

used_files

used_files(*, metadata_only: bool = False) -> list[str]

Return complete list of files needed to open this dataset.

Parameters:

Name	Type	Description	Default
`metadata_only`	`bool`	If True, only return files that do not contain pixel data (e.g., metadata, companion files, etc...), by default `False`.	`False`

CoreMetadata `dataclass`

CoreMetadata(
    dtype: dtype,
    shape: OMEShape,
    rgb_count: int = 0,
    thumb_size_x: int = 0,
    thumb_size_y: int = 0,
    bits_per_pixel: int = 0,
    image_count: int = 0,
    modulo_z: Any = None,
    modulo_c: Any = None,
    modulo_t: Any = None,
    dimension_order: str = "",
    is_order_certain: bool = False,
    is_rgb: bool = False,
    is_little_endian: bool = False,
    is_interleaved: bool = False,
    is_indexed: bool = False,
    is_false_color: bool = True,
    is_metadata_complete: bool = False,
    is_thumbnail_series: bool = False,
    series_metadata: dict[str, Any] = dict(),
    resolution_count: int = 1,
)

Core metadata for a single series.

Parameters:

Name	Type	Description	Default
`dtype`	`dtype`		required
`shape`	`OMEShape`		required
`rgb_count`	`int`		`0`
`thumb_size_x`	`int`		`0`
`thumb_size_y`	`int`		`0`
`bits_per_pixel`	`int`		`0`
`image_count`	`int`		`0`
`modulo_z`	`Any`		`None`
`modulo_c`	`Any`		`None`
`modulo_t`	`Any`		`None`
`dimension_order`	`str`		`''`
`is_order_certain`	`bool`		`False`
`is_rgb`	`bool`		`False`
`is_little_endian`	`bool`		`False`
`is_interleaved`	`bool`		`False`
`is_indexed`	`bool`		`False`
`is_false_color`	`bool`		`True`
`is_metadata_complete`	`bool`		`False`
`is_thumbnail_series`	`bool`		`False`
`series_metadata`	`dict[str, Any]`	dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)	`<class 'dict'>`
`resolution_count`	`int`		`1`

LazyBioArray

LazyBioArray(
    biofile: BioFile, series: int, resolution: int = 0
)

Pythonic lazy array interface for a single Bio-Formats Series/Resolution.

This object provides a numpy-compatible API for on-demand access to a specific series and resolution level in a Bio-Formats file. In the Bio-Formats Java API, each file can contain multiple series (e.g., wells in a plate, fields of view, or tiled regions), and each series can have multiple resolution levels (pyramid layers). LazyBioArray represents one of these series/resolution combinations as a numpy-style array.

The array is always 5-dimensional with shape (T, C, Z, Y, X), though some dimensions may be singletons (size 1) depending on the image acquisition. For RGB/RGBA images, a 6th dimension is added: (T, C, Z, Y, X, rgb).

Lazy slicing behavior: Indexing operations (arr[...]) return lazy views without reading data. Use np.asarray() or numpy operations to materialize. This enables composition: arr[0][1][2] creates nested views, only reading data when explicitly requested.

Supports integer and slice indexing along with the __array__() protocol for seamless numpy integration.

Examples:

>>> with BioFile("image.nd2") as bf:
...     arr = bf.as_array()  # No data read yet
...     view = arr[0, 0, 2]  # Returns LazyBioArray view (no I/O)
...     plane = np.asarray(view)  # Now reads single plane from disk
...     roi = arr[:, :, :, 100:200, 50:150]  # Lazy view of sub-region
...     full_data = np.array(arr)  # Materialize all data
...     max_z = np.max(arr, axis=2)  # Works with numpy functions

Composition example:

>>> with BioFile("image.nd2") as bf:
...     arr = bf.as_array()
...     view1 = arr[0:10]  # LazyBioArray (no I/O)
...     view2 = view1[2:5]  # LazyBioArray (still no I/O)
...     data = np.asarray(view2)  # Read frames 2-4 from disk

Notes

BioFile must remain open while using this array
Step indexing (arr[::2]), fancy indexing, and boolean masks not supported
Not thread-safe: create separate BioFile instances per thread

Initialize lazy array wrapper.

Parameters:

Name	Type	Description	Default
`biofile`	`BioFile`	Open BioFile instance to read from	required
`series`	`int`	Series index this array represents	required
`resolution`	`int`	Resolution level (0 = full resolution), by default 0	`0`

Methods:

Name	Description
`__array__`	numpy array protocol - materializes data from disk.
`__getitem__`	Index the array with numpy-style syntax, returning a lazy view.
`__repr__`	String representation.
`to_dask`	Create dask array for lazy computation on Bio-Formats data.
`to_xarray`	Return xarray.DataArray for specified series and resolution.
`to_zarr_store`	Create a read-only zarr v3 store backed by this array.

coords `property`

coords: Mapping[str, Any]

Mapping of dimension names to coordinate values for this view.

Squeezed dimensions are returned as scalars, non-squeezed dimensions are returned as ranges or sequences of values.

This mimics the .coords attribute of xarray.DataArray for compatibility with xarray's indexing

dims `property`

dims: tuple[str, ...]

Return used dimension names (matches shape).

dtype `property`

dtype: dtype

Data type of array elements.

is_rgb `property`

is_rgb: bool

True if image has RGB/RGBA components (ndim == 6).

nbytes `property`

nbytes: int

Total bytes consumed by the array elements.

ndim `property`

ndim: int

Number of dimensions.

shape `property`

shape: tuple[int, ...]

Array shape in (T, C, Z, Y, X) or (T, C, Z, Y, X, rgb) format.

size `property`

size: int

Number of elements in the array

array

__array__(
    dtype: dtype | None = None, copy: bool | None = None
) -> np.ndarray

numpy array protocol - materializes data from disk.

This enables np.array(lazy_arr) and other numpy operations.

Parameters:

Name	Type	Description	Default
`dtype`	`dtype`	Desired data type	`None`
`copy`	`bool`	Whether to force a copy (NumPy 2.0+ compatibility)	`None`

getitem

__getitem__(key: Any) -> LazyBioArray

Index the array with numpy-style syntax, returning a lazy view.

Supports integer and slice indexing. Returns a view without reading data - use np.asarray() or array() to materialize.

Parameters:

Name	Type	Description	Default
`key`	`int, slice, tuple, or Ellipsis`	Index specification	required

Returns:

Type	Description
`LazyBioArray`	A lazy view of the requested data

Raises:

Type	Description
`NotImplementedError`	If fancy indexing, boolean indexing, or step != 1 is used
`IndexError`	If indices are out of bounds

repr

__repr__() -> str

String representation.

to_dask

to_dask(
    *,
    chunks: str | tuple = "auto",
    tile_size: tuple[int, int] | str | None = None,
) -> dask.array.Array

Create dask array for lazy computation on Bio-Formats data.

Returns a dask array in TCZYX[r] order that wraps this lazy array. Uses single-threaded scheduler for Bio-Formats thread safety.

Parameters:

Name	Type	Description	Default
`chunks`	`str or tuple`	Chunk specification. Examples: - "auto": Let dask decide (default) - (1, 1, 1, -1, -1): Full Y,X planes per T,C,Z - (1, 1, 1, 512, 512): 512x512 tiles Mutually exclusive with tile_size.	`"auto"`
`tile_size`	`tuple[int, int] or 'auto'`	Tile-based chunking for Y,X dimensions (T,C,Z get chunks of 1). - (512, 512): Use 512x512 tiles - "auto": Query Bio-Formats optimal tile size Mutually exclusive with chunks.	`None`

to_xarray

to_xarray() -> xarray.DataArray

Return xarray.DataArray for specified series and resolution.

The returned DataArray has .dims and .coords attributes populated according to the metadata. Dimension and coord names will be one of: TCZYXS, where S represents the RGB/RGBA channels if present. The parsed ome_types.OME object is also available in the .attrs['ome_metadata'] attribute of the DataArray.

to_zarr_store

to_zarr_store(
    *,
    tile_size: tuple[int, int] | None = None,
    rgb_as_channels: bool = False,
    squeeze_singletons: bool = False,
) -> BFArrayStore

Create a read-only zarr v3 store backed by this array.

Each zarr chunk maps to a single read_plane() call. Requires the zarr extra (pip install bffile[zarr]).

Parameters:

Name	Type	Description	Default
`tile_size`	`tuple[int, int]`	If provided, Y and X are chunked into tiles of this size. Default is full-plane chunks `(1, 1, 1, Y, X)`.	`None`
`rgb_as_channels`	`bool`	If True, interleave RGB samples as separate C channels (OME-Zarr convention). If False, keep RGB as the last dimension (numpy/imread convention). Default is False.	`False`
`squeeze_singletons`	`bool`	If True, omit dimensions with size 1 from metadata (except Y/X). Default is False (always reports 5D or 6D arrays).	`False`

Returns:

Type	Description
`BFArrayStore`	A zarr v3 Store suitable for `zarr.open_array(store, mode="r")`.

OMEShape

NamedTuple with OME metadata shape.

Parameters:

Name	Type	Default
`t`	`ForwardRef('int')`	`None`
`c`	`ForwardRef('int')`	`None`
`z`	`ForwardRef('int')`	`None`
`y`	`ForwardRef('int')`	`None`
`x`	`ForwardRef('int')`	`None`
`rgb`	`ForwardRef('int')`	`None`

as_array_shape `property`

as_array_shape: tuple[int, ...]

Return 5-tuple (T,C,Z,Y,X) if rgb==1, else 6-tuple (T,C,Z,Y,X,RGB).

Series

Series(biofile: BioFile, index: int)

Proxy for a single series within a BioFile.

Provides convenient access to metadata and data for one series without needing to pass series= to every method call.

Parameters:

Name	Type	Description	Default
`biofile`	`BioFile`	Open BioFile instance this series belongs to.	required
`index`	`int`	Zero-based series index.	required

Methods:

Name	Description
`as_array`	Return a lazy array for this series.
`core_metadata`	Return :class:`CoreMetadata` for this series.
`get_thumbnail`	Get thumbnail image for specified series.
`read_plane`	Read a single plane from this series.
`to_dask`	Create a dask array for this series.
`to_xarray`	Create an xarray DataArray for this series.
`to_zarr_store`	Create a Zarr store for this series.
`used_files`	Return list of files needed to open this series.

dtype `property`

dtype: dtype

Pixel data type at resolution 0.

index `property`

index: int

Zero-based series index.

is_rgb `property`

is_rgb: bool

Whether this series has multiple RGB components.

is_thumbnail `property`

is_thumbnail: bool

Whether this series is a thumbnail.

resolution_count `property`

resolution_count: int

Number of resolution levels in this series.

shape `property`

shape: tuple[int, ...]

Shape as (T, C, Z, Y, X) or (T, C, Z, Y, X, rgb).

as_array

as_array(resolution: int = 0) -> LazyBioArray

Return a lazy array for this series.

Parameters:

Name	Type	Description	Default
`resolution`	`int`	Resolution level (0 = full resolution), by default 0.	`0`

core_metadata

core_metadata(resolution: int = 0)

Return :class:CoreMetadata for this series.

Parameters:

Name	Type	Description	Default
`resolution`	`int`	Resolution level (0 = full resolution), by default 0.	`0`

get_thumbnail

get_thumbnail(
    *, t: int = 0, c: int = 0, z: int | None = None
) -> np.ndarray

Get thumbnail image for specified series.

Returns a downsampled version of the specified plane from this series, scaled to fit within 128x128 pixels while maintaining aspect ratio.

Parameters:

Name	Type	Description	Default
`t`	`int`	Time index for thumbnail plane, by default 0	`0`
`c`	`int`	Channel index for thumbnail plane, by default 0	`0`
`z`	`int \| None`	Z-slice index for thumbnail plane, by default None (take the central slice)	`None`

Returns:

Type	Description
`ndarray`	Thumbnail image as numpy array with shape (H, W) for grayscale or (H, W, RGB) for RGB images. Maximum dimension is 128 pixels.

read_plane

read_plane(
    *,
    t: int = 0,
    c: int = 0,
    z: int = 0,
    y: slice | None = None,
    x: slice | None = None,
    resolution: int = 0,
    buffer: ndarray | None = None,
) -> np.ndarray

Read a single plane from this series.

Parameters:

Name	Type	Description	Default
`t`	`int`	Time index, by default 0.	`0`
`c`	`int`	Channel index, by default 0.	`0`
`z`	`int`	Z-slice index, by default 0.	`0`
`y`	`slice`	Y-axis sub-region.	`None`
`x`	`slice`	X-axis sub-region.	`None`
`resolution`	`int`	Resolution level (0 = full resolution), by default 0.	`0`
`buffer`	`ndarray`	Pre-allocated buffer for reuse.	`None`

to_dask

to_dask(
    resolution: int = 0,
    *,
    chunks: str | tuple = "auto",
    tile_size: tuple[int, int] | str | None = None,
) -> dask.array.Array

Create a dask array for this series.

Parameters:

Name	Type	Description	Default
`resolution`	`int`	Resolution level (0 = full resolution), by default 0.	`0`
`chunks`	`str or tuple`	Chunk specification, by default "auto".	`'auto'`
`tile_size`	`tuple[int, int] or 'auto'`	Tile-based chunking for Y,X dimensions.	`None`

to_xarray

to_xarray(resolution: int = 0) -> xarray.DataArray

Create an xarray DataArray for this series.

Parameters:

Name	Type	Description	Default
`resolution`	`int`	Resolution level (0 = full resolution), by default 0.	`0`

to_zarr_store

to_zarr_store(
    resolution: int = 0,
    *,
    tile_size: tuple[int, int] | None = None,
) -> BFArrayStore

Create a Zarr store for this series.

Parameters:

Name	Type	Description	Default
`resolution`	`int`	Resolution level (0 = full resolution), by default 0.	`0`
`tile_size`	`tuple[int, int]`	If provided, Y and X are chunked into tiles of this size instead of full planes. Chunk shape becomes `(1, 1, 1, tile_y, tile_x)`.	`None`

used_files

used_files(*, metadata_only: bool = False) -> list[str]

Return list of files needed to open this series.

Parameters:

Name	Type	Description	Default
`metadata_only`	`bool`	If True, only return files that do not contain pixel data (e.g., metadata, companion files, etc...), by default `False`.	`False`

imread

imread(
    path: str | Path,
    *,
    series: int = 0,
    resolution: int = 0,
) -> np.ndarray

Read image data from a Bio-Formats-supported file into a numpy array.

Convenience function that opens a file, reads the specified series into memory, and returns it as a numpy array. For more control over reading (lazy loading, sub-regions, etc.), use BioFile directly.

Parameters:

Name	Type	Description	Default
`path`	`str or Path`	Path to the image file	required
`series`	`int`	Series index to read, by default 0	`0`
`resolution`	`int`	Resolution level (0 = full resolution), by default 0	`0`

Returns:

Type	Description
`ndarray`	Image data with shape (T, C, Z, Y, X) or (T, C, Z, Y, X, rgb)

Examples:

>>> from bffile import imread
>>> data = imread("image.nd2")
>>> print(data.shape, data.dtype)
(10, 2, 5, 512, 512) uint16

Read a specific series:

>>> data = imread("multi_series.czi", series=1)

open_ome_zarr_group

open_ome_zarr_group(
    path: str | Path, *, version: Literal["0.5"] = "0.5"
) -> zarr.Group

Read image data from a Bio-Formats-supported file as a zarr array or group.

Returns an OME zarr.Group following the bf2raw transitional layout with all series.

Parameters:

Name	Type	Description	Default
`path`	`str or Path`	Path to the image file	required
`version`	`str`	OME-ZARR version to use, by default "0.5". Only "0.5" is currently supported. This keyword is included for future compatibility when newer OME-ZARR versions are supported; pass it explicitly to avoid unexpected future changes.	`'0.5'`

Examples:

>>> zarr_group = open_ome_zarr_group("image.nd2")
>>> # Access first series, full resolution
>>> arr = zarr_group["0/0"]
>>> data = arr[0, 0, 0]

open_zarr_array

open_zarr_array(
    path: str | Path,
    *,
    series: int = 0,
    resolution: int = 0,
    rgb_as_channels: bool = False,
) -> zarr.Array

Read image data from a Bio-Formats-supported file as a zarr array.

By default, returns arrays with the same shape as imread(): - RGB images: (T, C, Z, Y, X, rgb) - Non-RGB images: (T, C, Z, Y, X)

Set rgb_as_channels=True to interleave RGB samples as separate C channels (OME-Zarr convention), giving shape (T, C*rgb, Z, Y, X).

Parameters:

Name	Type	Description	Default
`path`	`str or Path`	Path to the image file	required
`series`	`int`	Series index to read, by default 0.	`0`
`resolution`	`int`	Resolution level (0 = full resolution), by default 0.	`0`
`rgb_as_channels`	`bool`	If True, interleave RGB samples as separate C channels (OME-Zarr convention). If False, keep RGB as the last dimension (numpy/imread convention). Default is False.	`False`

Returns:

Type	Description
`Array`	Zarr array view of the image data

Examples:

>>> import bffile
>>> arr = bffile.open_zarr_array("image.jpg")
>>> arr.shape  # RGB as last dimension (like imread)
(1, 1, 1, 512, 512, 3)

>>> arr = bffile.open_zarr_array("image.jpg", rgb_as_channels=True)
>>> arr.shape  # RGB interleaved as channels (OME-Zarr style)
(1, 3, 1, 512, 512)

API Reference

BioFile

closed property

filename property

ome_metadata property

ome_xml property

suspended property

__enter__

__exit__

__getitem__

__iter__

__len__

as_array

bioformats_maven_coordinate staticmethod

bioformats_version staticmethod

close

core_metadata

destroy

ensure_open

get_thumbnail

global_metadata

list_available_readers cached staticmethod

list_supported_suffixes cached staticmethod

lookup_table

open

read_plane

series_count

to_dask

to_xarray

to_zarr_store

used_files

CoreMetadata dataclass

LazyBioArray

coords property

dims property

dtype property

is_rgb property

nbytes property

ndim property

shape property

size property

__array__

__getitem__

__repr__

to_dask

to_xarray

to_zarr_store

OMEShape

as_array_shape property

Series

dtype property

index property

is_rgb property

is_thumbnail property

resolution_count property

shape property

as_array

core_metadata

get_thumbnail

read_plane

to_dask

to_xarray

to_zarr_store

used_files

imread

open_ome_zarr_group

open_zarr_array

closed `property`

filename `property`

ome_metadata `property`

ome_xml `property`

suspended `property`

enter

exit

getitem

iter

len

bioformats_maven_coordinate `staticmethod`

bioformats_version `staticmethod`

list_available_readers `cached` `staticmethod`

list_supported_suffixes `cached` `staticmethod`

CoreMetadata `dataclass`

coords `property`

dims `property`

dtype `property`

is_rgb `property`

nbytes `property`

ndim `property`

shape `property`

size `property`

array

getitem

repr

as_array_shape `property`

dtype `property`

index `property`

is_rgb `property`

is_thumbnail `property`

resolution_count `property`

shape `property`