pysnt.io.images module#

Image format utilities for pysnt.

This module provides functions for loading various image formats for use with SNT. Supports both bioformats2raw and OME-NGFF layouts.

detect_zarr_layout(path: str | Path) → str[source]#

Detect the OME-ZARR layout type.

Parameters:

path (str or Path) – Path or URL to the OME-ZARR directory

Returns:

Layout type: ‘bioformats2raw’, ‘ome-ngff’, or ‘unknown’

Return type:

str

Examples

>>> from pysnt.io import detect_zarr_layout
>>> layout = detect_zarr_layout('/path/to/image.ome.zarr')
>>> print(layout)  # 'bioformats2raw' or 'ome-ngff'
get_dataset_path(layout: str, level: int, series: int = 0) → str[source]#

Get the N5/Zarr dataset path for a given layout and level (standard layouts only).

For non-standard layouts, use get_dataset_path_from_metadata() instead.

Parameters:

  • layout (str) – Layout type (‘bioformats2raw’ or ‘ome-ngff’)

  • level (int) – Resolution level (0 = full resolution)

  • series (int, optional) – Series index for multi-series datasets. Default: 0

Returns:

Dataset path string (e.g., ‘/0/0’ for bioformats2raw or ‘/0’ for ome-ngff)

Return type:

str

get_dataset_path_from_metadata(path: str | Path, level: int = 0, series: int = 0) → Tuple[str, dict][source]#

Get the actual dataset path by reading OME-ZARR metadata.

This handles non-standard layouts where dataset paths are not simply ‘0’, ‘1’, etc.

Parameters:

  • path (str or Path) – Path or URL to the OME-ZARR directory

  • level (int, optional) – Resolution level (0 = full resolution). Default: 0

  • series (int, optional) – Series index for multi-series datasets. Default: 0

Returns:

(dataset_path, scale_info) where: - dataset_path: the actual path to the dataset (e.g., ‘/scale0/marmoset_neurons’) - scale_info: dict with ‘scale’ and ‘translation’ arrays, or None

Return type:

tuple

Raises:

ValueError – If metadata cannot be read or level is out of range

get_zattrs_path(layout: str, zarr_path: str, series: int = 0) → str[source]#

Get the path to .zattrs containing multiscales metadata.

Parameters:

  • layout (str) – Layout type (‘bioformats2raw’ or ‘ome-ngff’)

  • zarr_path (str) – Root zarr path

  • series (int, optional) – Series index for multi-series datasets. Default: 0

Returns:

Path to .zattrs file

Return type:

str

get_available_levels(path: str | Path, series: int = 0) → list[source]#

Get available resolution levels in an OME-ZARR dataset.

Parameters:

  • path (str or Path) – Path or URL to the OME-ZARR directory

  • series (int, optional) – Series index for multi-series datasets. Default: 0

Returns:

List of available level indices with their dimensions

Return type:

list

Examples

>>> from pysnt.io import get_available_levels
>>> levels = get_available_levels('/path/to/image.ome.zarr')
>>> for level in levels:
...     print(f"Level {level['level']}: {level['shape']}")
imgplus_from_zarr(path: str | Path, level: int = 0, series: int = 0)[source]#

Load an OME-ZARR image as a calibrated ImgPlus from local or remote sources. Supports both bioformats2raw and OME-NGFF layouts.

Parameters:

  • path (str or Path) – Path or URL to the OME-ZARR directory. Supports: - Local paths: ‘/path/to/image.ome.zarr’ - HTTP/HTTPS URLs: ‘https://example.com/data/image.ome.zarr’ - S3 URLs: ‘s3://bucket-name/path/to/image.ome.zarr’

  • level (int, optional) – Resolution level to load (0 = full resolution). Default: 0

  • series (int, optional) – Series index for multi-series datasets (bioformats2raw). Default: 0

Returns:

Calibrated ImgPlus with axis metadata from OME-ZARR

Return type:

ImgPlus

Raises:

  • FileNotFoundError – If the zarr path does not exist (local paths only)

  • ValueError – If the zarr lacks valid OME metadata or requested level

  • ImportError – If required dependencies are not available

Examples

>>> from pysnt.io import imgplus_from_zarr
>>>
>>> # Local file (full resolution)
>>> img = imgplus_from_zarr('/path/to/image.ome.zarr')
>>>
>>> # Load downsampled level
>>> img = imgplus_from_zarr('/path/to/image.ome.zarr', level=2)
>>>
>>> # Multi-series dataset (bioformats2raw)
>>> img = imgplus_from_zarr('/path/to/image.ome.zarr', series=1)
>>>
>>> # HTTP URL
>>> img = imgplus_from_zarr('https://example.com/data/image.ome.zarr')
>>>
>>> # S3 URL (requires s3fs)
>>> img = imgplus_from_zarr('s3://my-bucket/data/image.ome.zarr')

Notes

For S3 access, you may need to configure AWS credentials.

The function automatically detects the layout type (bioformats2raw vs OME-NGFF) and reads calibration metadata from the appropriate location.

inspect_zarr(path: str | Path, max_depth: int = 3) → dict[source]#

Inspect the structure and contents of an OME-ZARR file.

This function provides detailed information about the zarr structure, including groups, datasets, dimensions, data types, and OME metadata.

Parameters:

  • path (str or Path) – Path or URL to the OME-ZARR directory

  • max_depth (int, optional) – Maximum depth for recursive exploration. Default: 3

Returns:

Dictionary containing zarr structure information including: - ‘layout’: detected layout type - ‘resolution_levels’: list of available levels with dimensions - ‘axes’: axis information from metadata - ‘structure’: hierarchical structure of the zarr

Return type:

dict

Examples

>>> from pysnt.io import inspect_zarr
>>>
>>> info = inspect_zarr('/path/to/image.ome.zarr')
>>> print(f"Layout: {info['layout']}")
>>> print(f"Levels: {len(info['resolution_levels'])}")
>>> for level in info['resolution_levels']:
...     print(f"  Level {level['level']}: {level['shape']}")