bffile

https://imaging-formats.github.io/bffile/
Admin
bffile is a modern Bio-Formats wrapper for Python that provides a clean Pythonic API with lazy data...
Tokens:37,305
Snippets:283
Trust Score:9.7
Update:3 days ago
Show doc for...
Tokens:
Raw
### Install bffile via pip

Source: https://imaging-formats.github.io/bffile

Standard installation command for the bffile library.

```bash
pip install bffile
```

--------------------------------

### Install bffile with optional extras

Source: https://imaging-formats.github.io/bffile

Installation command including support for zarr, xarray, and dask.

```bash
pip install bffile[zarr,xarray,dask]
```

--------------------------------

### Install dask dependencies

Source: https://imaging-formats.github.io/bffile/usage

Commands to install dask, including the bffile-specific extra for compatibility.

```bash
pip install dask

# or, to get a version that we guarantee is compatible with bffile
# install the extra:
pip install bffile[dask]
```

--------------------------------

### Quick start with bffile

Source: https://imaging-formats.github.io/bffile

Demonstrates loading data directly into memory or using lazy access to load specific slices of a file.

```python
import bffile

# load directly into memory
data = bffile.imread("path/to/file", series=0)

# or use lazy access to load only what you need
with bffile.BioFile("path/to/file") as biofile:
    # lazy series accessor
    lazy_array = biofile[0].as_array()
    # Load data into memory (T=0, C=1:4, Z=all, Y=100:200)
    data = lazy_array[0, 1:4, :, 100:200]
```

--------------------------------

### Zarr directory structure example

Source: https://imaging-formats.github.io/bffile/api

The expected directory structure for an OME-ZARR group created by to_zarr_store.

```text
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)
```

--------------------------------

### imread basic usage

Source: https://imaging-formats.github.io/bffile/api

Example of reading an image file and printing its shape and data type.

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

```

--------------------------------

### Get Bio-Formats Version

Source: https://imaging-formats.github.io/bffile/api

Returns the version of the Bio-Formats library.

```python
bioformats_version() -> str
```

--------------------------------

### imread specific series

Source: https://imaging-formats.github.io/bffile/api

Example of reading a specific series from a multi-series file.

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

```

--------------------------------

### Accessing Zarr group and arrays

Source: https://imaging-formats.github.io/bffile/api

Example of opening a BioFile as a zarr group, accessing specific arrays, and saving to disk.

```python
>>> 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")
```

--------------------------------

### BioFile

Source: https://imaging-formats.github.io/bffile/api

The BioFile class provides an interface to open and read Bio-Formats files. It includes properties for file state and metadata, and methods for reading planes, getting thumbnails, converting to dask/xarray/zarr, and managing the file lifecycle.

```APIDOC
## BioFile

### Description
The BioFile class represents an open Bio-Formats file and provides methods to read image data and metadata.

### Properties
- **closed** - Indicates whether the file is closed.
- **filename** - The path to the file.
- **ome_metadata** - OME metadata object.
- **ome_xml** - OME XML string.
- **suspended** - Indicates whether the file is suspended.

### Methods
- **__enter__** - Context manager entry.
- **__exit__** - Context manager exit.
- **__getitem__** - Get item by index.
- **__getstate__** - Get state for pickling.
- **__iter__** - Iterate over series.
- **__len__** - Number of series.
- **__setstate__** - Set state for unpickling.
- **as_array** - Return the image data as an array.
- **bioformats_maven_coordinate** - Get the Maven coordinate for Bio-Formats.
- **bioformats_version** - Get the Bio-Formats version.
- **close** - Close the file.
- **core_metadata** - Get core metadata.
- **destroy** - Destroy the file handle.
- **ensure_open** - Ensure the file is open.
- **get_thumbnail** - Get a thumbnail image.
- **global_metadata** - Get global metadata.
- **list_available_readers** - List available readers.
- **list_supported_suffixes** - List supported file suffixes.
- **lookup_table** - Get a lookup table.
- **open** - Open the file.
- **read_plane** - Read a specific plane.
- **series_count** - Get the number of series.
- **to_dask** - Convert to a dask array.
- **to_xarray** - Convert to an xarray DataArray.
- **to_zarr_store** - Convert to a zarr store.
- **used_files** - Get the list of used files.
```

--------------------------------

### Use ensure_open context manager

Source: https://imaging-formats.github.io/bffile/api

Demonstrates how to use ensure_open to temporarily access a file without disrupting its initial open or closed state.

```python
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
```

--------------------------------

### core_metadata

Source: https://imaging-formats.github.io/bffile/api

Get metadata for specified series and resolution.

```APIDOC
## core_metadata

### Description
Get metadata for specified series and resolution.

### Method
core_metadata

### Parameters
- `series` (int) - Optional - Series index, by default 0
- `resolution` (int) - Optional - Resolution level (0 = full resolution), by default 0. Negative indexing supported (e.g., -1 = lowest resolution).

### Returns
- `CoreMetadata` - Metadata for the specified series and resolution

### Raises
- `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.
```

--------------------------------

### get_thumbnail

Source: https://imaging-formats.github.io/bffile/api

Gets thumbnail image for specified series.

```APIDOC
## get_thumbnail()

### Description
Get thumbnail image for specified series.

### Returns
- **thumbnail** - The thumbnail image.
```

--------------------------------

### Open BioFile

Source: https://imaging-formats.github.io/bffile/api

Demonstrates initializing a BioFile instance and opening the file using method chaining or separate calls.

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

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

--------------------------------

### __enter__

Source: https://imaging-formats.github.io/bffile/api

Enters the context manager, ensuring the file is open.

```APIDOC
## __enter__() -> Self

### Description
Enter context manager - ensures file is open.

### Returns
- **Self** - The BioFile instance.
```

--------------------------------

### core_metadata

Source: https://imaging-formats.github.io/bffile/api

Gets metadata for specified series and resolution.

```APIDOC
## core_metadata()

### Description
Get metadata for specified series and resolution.

### Returns
- **metadata** - The core metadata.
```

--------------------------------

### __getstate__

Source: https://imaging-formats.github.io/bffile/api

Pickle support - saves constructor args, cached metadata, and state.

```APIDOC
## __getstate__()

### Description
Pickle support — save constructor args, cached metadata, and state.

### Returns
- **state** - The state to be pickled.
```

--------------------------------

### Get Maven Coordinate

Source: https://imaging-formats.github.io/bffile/api

Returns the Maven coordinate used to load Bio-Formats.

```python
bioformats_maven_coordinate() -> str
```

--------------------------------

### __getstate__

Source: https://imaging-formats.github.io/bffile/api

Pickle support - save constructor args, cached metadata, and state.

```APIDOC
## __getstate__

### Description
Pickle support - save constructor args, cached metadata, and state.

### Method
__getstate__

### Returns
- `dict` - State dictionary
```

--------------------------------

### Get File Length with __len__

Source: https://imaging-formats.github.io/bffile/api

Returns the total number of series in the file.

```python
__len__() -> int
```

--------------------------------

### Pickle Support with __getstate__

Source: https://imaging-formats.github.io/bffile/api

Saves constructor arguments, cached metadata, and state for pickling.

```python
__getstate__() -> dict
```

--------------------------------

### open()

Source: https://imaging-formats.github.io/bffile/api

Opens the file and initializes the reader. If previously closed, reopens cheaply by reacquiring the file handle. Safe to call multiple times; no-op if already open.

```APIDOC
## open()

### Description
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.

### Method
open

### Signature
open() -> Self

### Returns
- **Self** - Returns self for method chaining.

### Examples
```python
# Method chaining
bf = BioFile(path).open()

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

### See Also
- ensure_open : Context manager that restores previous state on exit
```

--------------------------------

### __getstate__

Source: https://imaging-formats.github.io/bffile/api

Pickle support — save enough to reconstruct the view.

```APIDOC
## __getstate__

### Description
Pickle support — save enough to reconstruct the view.

### Method
__getstate__

### Returns
- **dict** - State dictionary for pickling
```

--------------------------------

### Initialize LazyBioArray

Source: https://imaging-formats.github.io/bffile/usage

Demonstrates obtaining a LazyBioArray from a BioFile without loading data into memory.

```python
with BioFile("image.nd2") as bf:
    arr = bf[0].as_array()  # no data read yet!
    print(arr)
    # LazyBioArray(shape=(10, 2, 5, 512, 512), dtype=uint16, file='image.nd2')
```

--------------------------------

### Series.get_thumbnail

Source: https://imaging-formats.github.io/bffile/api

Gets a thumbnail image for the specified series, downsampled to fit within 128x128 pixels while maintaining aspect ratio. The z parameter defaults to the central slice.

```APIDOC
## Series.get_thumbnail

### Description
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.

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

### Parameters
- **t** (int) - Optional - Time index for thumbnail plane, by default 0.
- **c** (int) - Optional - Channel index for thumbnail plane, by default 0.
- **z** (int | None) - Optional - Z-slice index for thumbnail plane, by default None (take the central slice).

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

--------------------------------

### __setstate__

Source: https://imaging-formats.github.io/bffile/api

Pickle support - reconstruct with cached metadata, match state.

```APIDOC
## __setstate__

### Description
Pickle support - reconstruct with cached metadata, match state.

### Method
__setstate__

### Parameters
- `state` (dict) - Required - State dictionary
```

--------------------------------

### __setstate__

Source: https://imaging-formats.github.io/bffile/api

Pickle support - reconstructs with cached metadata and matches state.

```APIDOC
## __setstate__(state)

### Description
Pickle support — reconstruct with cached metadata, match state.

### Parameters
- **state** - Required - The state to restore.
```

--------------------------------

### open

Source: https://imaging-formats.github.io/bffile/api

Opens file and initializes reader, or re-opens if previously closed.

```APIDOC
## open()

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

--------------------------------

### get_thumbnail()

Source: https://imaging-formats.github.io/bffile/api

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.

```APIDOC
## get_thumbnail()

### Description
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.

### Method
get_thumbnail

### Signature
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

### Parameters
- **series** (int) - Optional - Series index to get thumbnail from, by default 0
- **t** (int) - Optional - Time index for thumbnail plane, by default 0
- **c** (int) - Optional - Channel index for thumbnail plane, by default 0
- **z** (int | None) - Optional - Z-slice index for thumbnail plane, by default None (take the central slice)
- **max_thumbnail_size** (int | tuple[int, int]) - Optional - Maximum thumbnail size. If int, limits both width and height to this value. If tuple, interpreted as (max_width, max_height). Default 128.
- **max_read_size** (int) - Optional - 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. Default 4096.

### Returns
- **ndarray** - Thumbnail image as numpy array with shape (H, W) for grayscale or (H, W, RGB) for RGB images.
```

--------------------------------

### Enable memoization for faster opens

Source: https://imaging-formats.github.io/bffile/usage

Use the memoize parameter to cache initialized reader state to a .bfmemo file on disk. This must be enabled on both initial and subsequent opens.

```python
# First open: full init + saves .bfmemo file to disk
with BioFile("image.nd2", memoize=True) as bf:
    ...

# Subsequent opens are faster: loads from .bfmemo instead of re-parsing
with BioFile("image.nd2", memoize=True) as bf:
    ...
```

--------------------------------

### LazyBioArray Initialization and Slicing

Source: https://imaging-formats.github.io/bffile/api

Demonstrates initializing a LazyBioArray from a BioFile and performing lazy slicing operations. Data is only read from disk when materialized via np.asarray() or similar operations.

```python
>>> 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
```

--------------------------------

### __getstate__ method

Source: https://imaging-formats.github.io/bffile/api

Pickle support - saves enough state to reconstruct the view.

```APIDOC
## __getstate__()

### Description
Pickle support - save enough to reconstruct the view.

### Returns
- **object** - State object for pickling.
```

--------------------------------

### ravel method

Source: https://imaging-formats.github.io/bffile/api

Returns a flattened array, materializing data from disk.

```APIDOC
## ravel()

### Description
Return flattened array (materializes data from disk).

### Returns
- **np.ndarray** - Flattened array.
```

--------------------------------

### open_zarr_array with rgb_as_channels

Source: https://imaging-formats.github.io/bffile/api

Opens an image as a zarr.Array with RGB samples interleaved as separate C channels, following the OME-Zarr convention.

```python
>>> 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)
```

--------------------------------

### ensure_open

Source: https://imaging-formats.github.io/bffile/api

Context manager that temporarily opens the file if closed.

```APIDOC
## ensure_open()

### Description
Context manager that temporarily opens the file if closed.
```

--------------------------------

### Open BioFile as OME-Zarr group

Source: https://imaging-formats.github.io/bffile/usage

Shows how to open a file as a virtual OME-Zarr group, providing a spec-compliant view without requiring file conversion.

```python
from bffile import open_ome_zarr_group
import zarr

ome_zarr = open_ome_zarr_group("image.nd2")
assert isinstance(ome_zarr, zarr.Group)

ome_meta = ome_zarr.attrs["ome"]
assert "bioformats2raw.layout" in ome_meta

series0 = ome_zarr["0"]  # group for series 0
assert "multiscales" in series0.attrs["ome"]  # multiscales metadata is present
level0 = series0["0"]    # array for resolution level 0
assert isinstance(level0, zarr.Array)
print(level0.shape, level0.dtype)
```

--------------------------------

### ensure_open()

Source: https://imaging-formats.github.io/bffile/api

Context manager that temporarily opens the file if closed. It restores the open/closed state on exit, allowing temporary access without disrupting the caller's file state.

```APIDOC
## ensure_open()

### Description
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.

### Method
ensure_open

### Signature
ensure_open() -> _EnsureOpenContext

### Returns
- **_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
```
```

--------------------------------

### open_zarr_array with default RGB layout

Source: https://imaging-formats.github.io/bffile/api

Opens an image as a zarr.Array with RGB data kept as the last dimension, matching standard imread behavior.

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

--------------------------------

### Using Series Proxy Objects

Source: https://imaging-formats.github.io/bffile/usage

Shows how Series objects act as proxies to call methods on the parent BioFile with the series argument pre-filled.

```python
with BioFile("image.nd2") as bf:
    s = bf[0]
    arr = s.as_array()         # same as bf.as_array(series=0)
    meta = s.core_metadata()   # same as bf.core_metadata(series=0)
```

--------------------------------

### to_zarr_store method definition

Source: https://imaging-formats.github.io/bffile/api

Defines the to_zarr_store method for creating a Zarr store, with optional tile size configuration.

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

```

--------------------------------

### used_files

Source: https://imaging-formats.github.io/bffile/api

Returns the complete list of files needed to open this dataset.

```APIDOC
## used_files()

### Description
Return complete list of files needed to open this dataset.

### Returns
- **list** - List of file paths.
```

--------------------------------

### Manage BioFile lifecycle with context manager

Source: https://imaging-formats.github.io/bffile/usage

The recommended pattern for managing the underlying Java reader and file handle is using a context manager, which ensures cleanup.

```python
with BioFile("image.nd2") as bf:
    data = bf.read_plane()
# reader fully cleaned up here
```

--------------------------------

### __setstate__ method

Source: https://imaging-formats.github.io/bffile/api

Pickle support - reconstructs the view from saved state.

```APIDOC
## __setstate__(state)

### Description
Pickle support - reconstruct from saved state.

### Parameters
- **state** - Required - State object from __getstate__.
```

--------------------------------

### BioFile constructor

Source: https://imaging-formats.github.io/bffile/api

Creates a BioFile object for a given file path. Supports metadata retrieval, memoization, reader options, and channel filler configuration.

```APIDOC
## BioFile(path, meta=True, original_meta=False, memoize=0, options=None, channel_filler=None)

### Description
Creates a BioFile object for the specified file path. Initializes the reader and optionally retrieves metadata.

### Parameters
- **path** (str or Path) - Required - Path to file.
- **meta** (bool) - Optional - Whether to get metadata as well, by default True.
- **original_meta** (bool) - Optional - Whether to also retrieve the proprietary metadata as structured annotations in the OME output, by default False.
- **memoize** (bool or int) - Optional - 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
- **options** (dict[str, bool]) - Optional - 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}.
- **channel_filler** (bool or None) - Optional - 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.
```

--------------------------------

### __setstate__

Source: https://imaging-formats.github.io/bffile/api

Pickle support — reconstruct from saved state.

```APIDOC
## __setstate__

### Description
Pickle support — reconstruct from saved state.

### Method
__setstate__

### Parameters
#### Parameters
- **state** (dict) - Required - State dictionary to restore
```

--------------------------------

### Series.used_files

Source: https://imaging-formats.github.io/bffile/api

Returns the list of files needed to open this series. This method is listed in the Series methods table.

```APIDOC
## Series.used_files

### Description
Return list of files needed to open this series.

### Method
used_files()

### Returns
list - List of file paths needed to open the series.
```

--------------------------------

### Accessing Series via Indexing and Iteration

Source: https://imaging-formats.github.io/bffile/usage

Demonstrates how to use BioFile as a sequence to access, slice, and iterate over series objects.

```python
with BioFile("multi_scene.czi") as bf:
    print(len(bf))         # number of series

    s = bf[0]              # first series
    print(s.shape)             # (10, 2, 5, 512, 512)
    print(s.dtype)             # uint16
    print(s.is_rgb)            # False
    print(s.resolution_count)  # 1

    s = bf[-1]             # last series
    first_two = bf[0:2]    # slice returns list[Series]

    for series in bf:      # iterate over all series
        print(series.shape, series.dtype)
```

--------------------------------

### list_supported_suffixes()

Source: https://imaging-formats.github.io/bffile/api

List all file suffixes supported by the available readers.

```APIDOC
## list_supported_suffixes()

### Description
List all file suffixes supported by the available readers.

### Method
list_supported_suffixes

### Signature
list_supported_suffixes() -> set[str]

### Returns
- **set[str]** - Set of supported file suffixes.
```

--------------------------------

### used_files

Source: https://imaging-formats.github.io/bffile/api

Returns the complete list of files needed to open this dataset. Optionally filters to only metadata files when metadata_only is True.

```APIDOC
## used_files

### Description
Return complete list of files needed to open this dataset.

### Method
Function call

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

### Parameters
- **metadata_only** (bool) - Optional - If True, only return files that do not contain pixel data (e.g., metadata, companion files, etc...), by default False. Default: False.

### Returns
- **list[str]** - List of file paths needed to open the dataset.

```

--------------------------------

### Perform Lazy Slicing and Materialization

Source: https://imaging-formats.github.io/bffile/usage

Shows how to create lazy views of specific dimensions or regions and materialize them using np.asarray().

```python
with BioFile("image.nd2") as bf:
    arr = bf[0].as_array()  # no reading yet!

    # create a lazy view of a single plane (t=0, c=0, z=2)
    plane_view = arr[0, 0, 2]              # LazyBioArray, shape: (512, 512)
    plane = np.asarray(plane_view)         # NOW data is read from disk

    # create lazy view of all timepoints for one channel and z-slice
    timeseries_view = arr[:, 0, 2]         # LazyBioArray, shape: (10, 512, 512)
    timeseries = np.asarray(timeseries_view)  # reads data

    # lazy view of a (100, 100) sub-region within the YX plane
    # in the third timepoint, for all channels, and the first z-slice
    roi_view = arr[2, :, 0, 100:200, 50:150]  # LazyBioArray, shape: (2, 100, 100)
    roi = np.asarray(roi_view)             # only the requested pixels are read

    # materialize the full dataset
    full = np.asarray(arr)                 # shape: (10, 2, 5, 512, 512)
```

--------------------------------

### __exit__

Source: https://imaging-formats.github.io/bffile/api

Exits the context manager, performing full resource cleanup including the Java reader.

```APIDOC
## __exit__(*_args: Any) -> None

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

### Parameters
- **_args** (Any) - Optional - Context manager exit arguments.
```

--------------------------------

### ravel

Source: https://imaging-formats.github.io/bffile/api

Return flattened array (materializes data from disk).

```APIDOC
## ravel

### Description
Return flattened array (materializes data from disk).

### Method
ravel

### Parameters
#### Parameters
- **order** (Literal["K", "A", "C", "F"]) - Optional - Flatten order, default "C"

### Returns
- **np.ndarray** - Flattened array
```

--------------------------------

### filename property

Source: https://imaging-formats.github.io/bffile/api

Returns the name of the file handle.

```APIDOC
## filename property

### Description
Return name of file handle.

### Returns
- **filename** (str) - The name of the file handle.
```

--------------------------------

### Series.to_zarr_store

Source: https://imaging-formats.github.io/bffile/api

Creates a Zarr store for the series. This method is listed in the Series methods table.

```APIDOC
## Series.to_zarr_store

### Description
Create a Zarr store for this series.

### Method
to_zarr_store()

### Returns
Zarr store - Zarr store for the series.
```

--------------------------------

### BioFile lifecycle state diagram

Source: https://imaging-formats.github.io/bffile/api

A visual representation of the state transitions for the BioFile Java reader, illustrating the relationship between open, close, and destroy operations.

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

--------------------------------

### to_zarr_store

Source: https://imaging-formats.github.io/bffile/api

Returns 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.

```APIDOC
## to_zarr_store

### Description
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.

### Method
Function call

### Signature
```
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
```

### Parameters
- **series** (int) - Optional - 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. Default: None.
- **resolution** (int) - Optional - Resolution level (0 = full resolution), by default 0. Negative indexing supported (e.g., -1 = lowest resolution). Default: 0.
- **tile_size** (tuple[int, int]) - Optional - 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). Default: None.

### Returns
- **BFOmeZarrStore** - Read-only zarr v3 Store containing the full file hierarchy.
- **BFArrayStore** - Read-only zarr v3 Store for a single series and resolution.

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

Source: https://imaging-formats.github.io/bffile/api

Return list of files needed to open this series. This method is part of the BioFile series object.

```APIDOC
## used_files

### Description
Return list of files needed to open this series.

### Method
Method

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

### Parameters
- **metadata_only** (bool) - Optional - If True, only return files that do not contain pixel data (e.g., metadata, companion files, etc...), by default False.

### Returns
- **list[str]** - List of file paths needed to open the series.
```

--------------------------------

### list_supported_suffixes

Source: https://imaging-formats.github.io/bffile/api

Lists all file suffixes supported by the available readers.

```APIDOC
## list_supported_suffixes()

### Description
List all file suffixes supported by the available readers.

### Returns
- **list** - List of supported suffixes.
```

--------------------------------

### to_zarr_store

Source: https://imaging-formats.github.io/bffile/api

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

```APIDOC
## to_zarr_store()

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

### Returns
- **zarr.Group** - The zarr store.
```

--------------------------------

### to_zarr_store method

Source: https://imaging-formats.github.io/bffile/api

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

```APIDOC
## to_zarr_store()

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

### Returns
- **zarr.storage.Store** - Read-only zarr store.
```

--------------------------------

### __repr__ method

Source: https://imaging-formats.github.io/bffile/api

Returns a string representation of the array.

```APIDOC
## __repr__()

### Description
String representation.

### Returns
- **str** - String representation.
```

--------------------------------

### Convert lookup_table to Colormap

Source: https://imaging-formats.github.io/bffile/api

Shows how to retrieve the color lookup table from an indexed-color series and convert it into a cmap.Colormap object.

```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]
```

--------------------------------

### to_zarr_store

Source: https://imaging-formats.github.io/bffile/api

Create a Zarr store for this series. This method is part of the BioFile series object.

```APIDOC
## to_zarr_store

### Description
Create a Zarr store for this series.

### Method
Method

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

### Parameters
- **resolution** (int) - Optional - Resolution level (0 = full resolution), by default 0.
- **tile_size** (tuple[int, int]) - Optional - 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).

### Returns
- **BFArrayStore** - The Zarr store for the series.
```

--------------------------------

### used_files method signature

Source: https://imaging-formats.github.io/bffile/api

Signature for the used_files method, which returns a list of files required to open the dataset.

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

--------------------------------

### __getitem__

Source: https://imaging-formats.github.io/bffile/api

Index the array with numpy-style syntax, returning a lazy view. Supports integer and slice indexing without reading data.

```APIDOC
## __getitem__

### Description
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.

### Method
__getitem__

### Parameters
#### Parameters
- **key** (int, slice, tuple, or Ellipsis) - Required - Index specification

### Returns
- **LazyBioArray** - A lazy view of the requested data

### Raises
- **NotImplementedError** - If fancy indexing, boolean indexing, or step != 1 is used
- **IndexError** - If indices are out of bounds
```

--------------------------------

### Configure dask tile-based chunking

Source: https://imaging-formats.github.io/bffile/usage

Configures dask array chunking using explicit tile sizes or by querying Bio-Formats for optimal sizes.

```python
with BioFile("image.nd2") as bf:
    darr = bf.to_dask(tile_size=(512, 512))       # explicit tile size
    darr = bf.to_dask(tile_size="auto")           # query Bio-Formats for optimal size
```

--------------------------------

### Restore State with __setstate__

Source: https://imaging-formats.github.io/bffile/api

Reconstructs the object using cached metadata and match state.

```python
__setstate__(state: dict) -> None
```

--------------------------------

### Manage BioFile lifecycle explicitly

Source: https://imaging-formats.github.io/bffile/usage

You can manually open, close, and destroy the file handle. Closing releases the handle while keeping state, while destroy performs full cleanup.

```python
bf = BioFile("image.nd2")
bf.open()
# ... use bf ...
bf.close()    # release file handle (fast reopen later)
bf.open()     # cheap — just reacquires the file handle
# ... use bf again ...
bf.destroy()  # full cleanup (or let GC handle it)
```
Tokens:
Raw