ngff_zarr.lif_to_ngff_image

Convert Leica Image Format (LIF) files to OME-NGFF.

This module provides functions to convert LIF files (and related formats like LOF, XLIF, XLEF, XLCF) to NgffImage objects for further processing into OME-Zarr format.

Requires the liffile package: pip install liffile

Module Contents

Functions

_get_lif_image_data_delayed	Load LIF image data (for use with dask.delayed).
_read_lif_image_array	Re-open the LIF file and read a single image’s array.
_lif_reopen_locator	Derive a (filepath, index) that re-opens the source LIF and reselects lif_image.
_delayed_lif_data	Build a lazy dask array for lif_image that survives the source LifFile being closed by re-opening the file at compute time when possible.
_extract_scale_translation	Extract scale (pixel spacing) and translation (origin) from LIF image coordinates.
_map_lif_dims_to_ngff	Map LIF dimensions to OME-NGFF dimensions, flattening channel-like dims.
_reshape_for_flattened_channels	Reshape data array to flatten channel-like dimensions.
lif_to_ngff_image	Convert a single LifImage to an NgffImage.
lif_file_to_ngff_images	Convert a LIF file to a list of (name, NgffImage) pairs.
has_mosaic_dimension	Check if a LIF image has a mosaic dimension with size > 1.
lif_to_hcs_plate	Convert a LIF image with mosaic dimension to HCS plate structure.

Data

LIF_DIM_TO_NGFF
SPATIAL_DIMS

API

ngff_zarr.lif_to_ngff_image.LIF_DIM_TO_NGFF: dict[str, str | None]

None

ngff_zarr.lif_to_ngff_image.SPATIAL_DIMS

None

ngff_zarr.lif_to_ngff_image._get_lif_image_data_delayed(lif_image: Any) → numpy.ndarray

Load LIF image data (for use with dask.delayed).

ngff_zarr.lif_to_ngff_image._read_lif_image_array(lif_path: str, index: int) → numpy.ndarray

Re-open the LIF file and read a single image’s array.

Re-opening per read keeps the dask graph self-contained: the LifFile handle that produced the graph is typically closed (and the graph may be serialized to other worker processes) by the time chunks are computed, so holding a reference to a LifImage from that handle raises ValueError: seek of closed file.

ngff_zarr.lif_to_ngff_image._lif_reopen_locator(lif_image: Any) → tuple[str, int] | None

Derive a (filepath, index) that re-opens the source LIF and reselects lif_image.

Returns None when the source file path cannot be determined (e.g. the image is a test mock or was created without a backing file), in which case the caller falls back to referencing the LifImage directly.

ngff_zarr.lif_to_ngff_image._delayed_lif_data(

lif_image: Any,

shape: collections.abc.Sequence[int],

dtype: Any,

) → dask.array.Array

Build a lazy dask array for lif_image that survives the source LifFile being closed by re-opening the file at compute time when possible.

ngff_zarr.lif_to_ngff_image._extract_scale_translation(

lif_image: Any,

ngff_dims: collections.abc.Sequence[str],

) → tuple[dict[str, float], dict[str, float]]

Extract scale (pixel spacing) and translation (origin) from LIF image coordinates.

Parameters

lif_image : LifImage The LIF image object with coords attribute. ngff_dims : Sequence[str] The mapped NGFF dimension names.

Returns

scale : Dict[str, float] Pixel spacing for spatial dimensions. translation : Dict[str, float] Origin offset for spatial dimensions.

ngff_zarr.lif_to_ngff_image._map_lif_dims_to_ngff(

lif_dims: collections.abc.Sequence[str],

lif_shape: collections.abc.Sequence[int],

) → tuple[tuple[str, ...], tuple[int, ...]]

Map LIF dimensions to OME-NGFF dimensions, flattening channel-like dims.

Parameters

lif_dims : Sequence[str] Original LIF dimension names (e.g., (‘T’, ‘Z’, ‘C’, ‘Y’, ‘X’)). lif_shape : Sequence[int] Original shape corresponding to lif_dims.

Returns

ngff_dims : Tuple[str, …] Mapped NGFF dimension names. ngff_shape : Tuple[int, …] Shape after flattening channel-like dimensions.

ngff_zarr.lif_to_ngff_image._reshape_for_flattened_channels(

data: dask.array.Array,

lif_dims: collections.abc.Sequence[str],

lif_shape: collections.abc.Sequence[int],

ngff_dims: collections.abc.Sequence[str],

ngff_shape: collections.abc.Sequence[int],

) → dask.array.Array

Reshape data array to flatten channel-like dimensions.

This handles the case where LIF has multiple channel-like dimensions (C, λ, Λ, S) that need to be flattened into a single channel dimension.

The function ensures channel dimensions are moved to be adjacent before flattening, regardless of their original positions in the array.

ngff_zarr.lif_to_ngff_image.lif_to_ngff_image(

lif_image: Any,

name: str | None = None,

) → ngff_zarr.ngff_image.NgffImage

Convert a single LifImage to an NgffImage.

Parameters

lif_image : LifImage A LifImage object from the liffile library. name : str, optional Name for the output image. If None, uses lif_image.name.

Returns

NgffImage The converted image with metadata.

Examples

from liffile import LifFile from ngff_zarr import lif_to_ngff_image with LifFile(“sample.lif”) as lif: … ngff_image = lif_to_ngff_image(lif.images[0])

ngff_zarr.lif_to_ngff_image.lif_file_to_ngff_images(

lif_path: str | pathlib.Path,

series: int | str | list[int | str] | None = None,

) → list[tuple[str, ngff_zarr.ngff_image.NgffImage]]

Convert a LIF file to a list of (name, NgffImage) pairs.

Parameters

lif_path : str or Path Path to the LIF file. series : int, str, or list, optional Series to convert: - None or “all”: Convert all series - int: Convert series at that index - str: Convert series matching regex pattern - list: Convert multiple series by index or pattern

Returns

List[Tuple[str, NgffImage]] List of (series_name, ngff_image) tuples.

Examples

from ngff_zarr import lif_file_to_ngff_images

Convert all series

images = lif_file_to_ngff_images(“sample.lif”)

Convert specific series by index

images = lif_file_to_ngff_images(“sample.lif”, series=0)

Convert series matching pattern

images = lif_file_to_ngff_images(“sample.lif”, series=”area_1”)

ngff_zarr.lif_to_ngff_image.has_mosaic_dimension(lif_image: Any) → bool

Check if a LIF image has a mosaic dimension with size > 1.

Parameters

lif_image : LifImage The LIF image to check.

Returns

bool True if the image has M dimension with size > 1.

ngff_zarr.lif_to_ngff_image.lif_to_hcs_plate(

lif_image: Any,

plate_name: str = 'plate',

version: str = '0.4',

) → tuple[ngff_zarr.v04.zarr_metadata.Plate, list[tuple[str, str, int, ngff_zarr.ngff_image.NgffImage]]]

Convert a LIF image with mosaic dimension to HCS plate structure.

When a LIF image has M > 1 (multiple mosaic positions), this function creates an HCS plate structure where each position becomes a field of view.

Parameters

lif_image : LifImage A LIF image with mosaic dimension (M > 1). plate_name : str, optional Name for the plate. Default is “plate”. version : str, optional OME-Zarr version for the plate. Default is “0.4”.

Returns

plate : Plate Plate metadata for HCS structure. well_images : List[Tuple[str, str, int, NgffImage]] List of (row_name, column_name, field_index, ngff_image) tuples.

Raises

ValueError If the image does not have a mosaic dimension with M > 1.

Examples

from liffile import LifFile from ngff_zarr import lif_to_hcs_plate with LifFile(“mosaic.lif”) as lif: … plate, well_images = lif_to_hcs_plate(lif.images[0]) … # plate contains HCS metadata … # well_images contains individual field images