zarrnii.core

Core implementation module containing the ZarrNii class and low-level helpers used by IO, metadata, and transformation workflows.

Unified ZarrNii implementation using NgffImage internally.

This module provides the core ZarrNii class that maintains chainable functionality while using NgffImage objects under the hood for better multiscale support and metadata preservation. It bridges OME-Zarr and NIfTI formats with a unified API.

The module includes: - Core ZarrNii class with transformation, cropping, and resampling capabilities - Helper functions for loading and saving OME-Zarr data - Utility functions for metadata extraction and conversion - Compatibility functions for backward compatibility

Key Classes

ZarrNii: Main class for working with OME-Zarr and NIfTI data

Key Functions

load_ngff_image: Load NgffImage from OME-Zarr store save_ngff_image: Save NgffImage to OME-Zarr store with pyramid get_multiscales: Load full multiscales object from store

Classes

zarrnii.core.MetadataInvalidError

Bases: Exception

Raised when an operation would invalidate ZarrNii metadata.

zarrnii.core.ZarrNii(darr=None, axes_order='ZYX', orientation='RAS', xyz_orientation=None, ngff_image=None, spacing=(1.0, 1.0, 1.0), origin=(0.0, 0.0, 0.0), name='image', _omero=None, affine=None, **kwargs)

Zarr-based image with NIfTI compatibility using NgffImage internally.

This class provides chainable operations on OME-Zarr data while maintaining compatibility with NIfTI workflows. It uses NgffImage objects internally for better multiscale support and metadata preservation.

Attributes:

• ngff_image (NgffImage) –

  The internal NgffImage object containing data and metadata.

• axes_order (str) –

  The order of the axes for NIfTI compatibility ('ZYX' or 'XYZ').

• xyz_orientation (str) –

  The anatomical orientation string in XYZ axes order (e.g., 'RAS', 'LPI').

Constructor with backward compatibility for old signature.

Raises:

• ValueError –

  If affine parameter is provided

Source code in zarrnii/core.py

def __init__(
    self,
    darr=None,
    axes_order="ZYX",
    orientation="RAS",
    xyz_orientation=None,
    ngff_image=None,
    spacing: Tuple[float, float, float] = (1.0, 1.0, 1.0),
    origin: Tuple[float, float, float] = (0.0, 0.0, 0.0),
    name: str = "image",
    _omero: Optional[object] = None,
    affine: Optional[AffineTransform] = None,
    **kwargs,
):
    """
    Constructor with backward compatibility for old signature.

    Raises:
        ValueError: If affine parameter is provided
    """
    # Check for deprecated affine parameter
    if affine is not None:
        raise ValueError(
            "The 'affine' parameter is no longer supported in ZarrNii(). "
            "Please use 'spacing' and 'origin' parameters instead. "
            "If you need to specify a full affine transformation, use from_nifti() "
            "or construct the NgffImage directly."
        )

    # Handle backwards compatibility: if xyz_orientation is provided, use it
    # Otherwise, use orientation for backwards compatibility
    final_orientation = (
        xyz_orientation if xyz_orientation is not None else orientation
    )

    if ngff_image is not None:
        # New signature
        object.__setattr__(self, "ngff_image", ngff_image)
        object.__setattr__(self, "axes_order", axes_order)
        object.__setattr__(self, "xyz_orientation", final_orientation)
        object.__setattr__(self, "_omero", _omero)
    elif darr is not None:
        # Legacy signature - delegate to from_darr
        instance = self.from_darr(
            darr=darr,
            axes_order=axes_order,
            orientation=final_orientation,
            spacing=spacing,
            origin=origin,
            name=name,
            omero=_omero,
            **kwargs,
        )
        object.__setattr__(self, "ngff_image", instance.ngff_image)
        object.__setattr__(self, "axes_order", instance.axes_order)
        object.__setattr__(self, "xyz_orientation", instance.xyz_orientation)
        object.__setattr__(self, "_omero", instance._omero)
    else:
        raise ValueError("Must provide either ngff_image or darr")

Attributes

zarrnii.core.ZarrNii.data property writable

Access the image data (dask array).

zarrnii.core.ZarrNii.darr property writable

Legacy property name for image data.

zarrnii.core.ZarrNii.shape property

Shape of the image data.

zarrnii.core.ZarrNii.dims property

Dimension names.

zarrnii.core.ZarrNii.scale property

Scale information from NgffImage.

zarrnii.core.ZarrNii.translation property

Translation information from NgffImage.

zarrnii.core.ZarrNii.name property

Image name from NgffImage.

zarrnii.core.ZarrNii.orientation property writable

Legacy property for backward compatibility.

Returns the xyz_orientation attribute to maintain backward compatibility with code that expects the 'orientation' property.

Returns:

• str ( str ) –

  The anatomical orientation string in XYZ axes order

zarrnii.core.ZarrNii.affine property

Affine transformation matrix derived from NgffImage scale and translation.

Returns:

• AffineTransform ( AffineTransform ) –

  4x4 affine transformation matrix in axes order of self.

zarrnii.core.ZarrNii.axes property

Axes metadata - derived from NgffImage for compatibility.

zarrnii.core.ZarrNii.coordinate_transformations property

Coordinate transformations - derived from NgffImage scale/translation.

zarrnii.core.ZarrNii.omero property

Omero metadata object.

Functions

zarrnii.core.ZarrNii.get_affine_transform(axes_order=None)

Get AffineTransform object from NgffImage metadata.

Parameters:

• axes_order (str, default: None ) –

  Spatial axes order, defaults to self.axes_order

Returns:

• AffineTransform –

  AffineTransform object

Source code in zarrnii/core.py

def get_affine_transform(self, axes_order: str = None) -> AffineTransform:
    """
    Get AffineTransform object from NgffImage metadata.

    Args:
        axes_order: Spatial axes order, defaults to self.axes_order

    Returns:
        AffineTransform object
    """
    matrix = self.get_affine_matrix(axes_order)
    return AffineTransform.from_array(matrix)

zarrnii.core.ZarrNii.get_zarr_store_info()

Extract zarr store information from the dask array if available.

Attempts to extract the underlying zarr store path and metadata from the dask array graph. This information can be used for direct zarr access without triggering dask compute() operations.

Returns:

• Optional[Dict[str, Any]] –

  Dictionary containing store information if available: - 'store_path': Path or URI to the zarr store - 'dataset_path': Path to the dataset within the zarr group - 'array_shape': Shape of the full array

• Optional[Dict[str, Any]] –

  Returns None if the data is not backed by a zarr store.

Raises:

• ValueError –

  If the dask array shape doesn't match the zarr array shape, indicating lazy operations that change shape (e.g., downsampling).

Notes

• Only works if the dask array was created from zarr using da.from_zarr()
• Returns None for in-memory arrays or arrays from other sources
• Validates that zarr array shape matches dask array shape to ensure compatibility with direct zarr access

Source code in zarrnii/core.py

def get_zarr_store_info(
    self,
) -> Optional[Dict[str, Any]]:
    """
    Extract zarr store information from the dask array if available.

    Attempts to extract the underlying zarr store path and metadata from
    the dask array graph. This information can be used for direct zarr
    access without triggering dask compute() operations.

    Returns:
        Dictionary containing store information if available:
            - 'store_path': Path or URI to the zarr store
            - 'dataset_path': Path to the dataset within the zarr group
            - 'array_shape': Shape of the full array
        Returns None if the data is not backed by a zarr store.

    Raises:
        ValueError: If the dask array shape doesn't match the zarr array shape,
            indicating lazy operations that change shape (e.g., downsampling).

    Notes:
        - Only works if the dask array was created from zarr using da.from_zarr()
        - Returns None for in-memory arrays or arrays from other sources
        - Validates that zarr array shape matches dask array shape to ensure
          compatibility with direct zarr access
    """
    try:
        # Check if the dask array has a graph
        graph = self.data.__dask_graph__()

        # Look for zarr array in the graph
        # The first key in a from_zarr graph typically contains the zarr array
        for key in graph.keys():
            task = graph[key]
            # Check if this is a zarr array
            if hasattr(task, "store") and hasattr(task, "name"):
                # Extract store information
                import zarr
                import zarr.storage

                store = task.store
                dataset_path = task.name.strip("/")

                # Determine store path based on store type
                # Handle both zarr v2 and v3 store types
                store_path = None

                # Try zarr v3 LocalStore first (has 'root' attribute)
                if hasattr(store, "root"):
                    store_path = store.root
                # Try zarr v2 DirectoryStore (has 'path' attribute)
                elif hasattr(store, "path"):
                    store_path = store.path
                # Try string representation as fallback
                elif isinstance(store, str):
                    store_path = store
                # Try str(store) which works for LocalStore
                else:
                    store_str = str(store)
                    # LocalStore repr is like "file:///path/to/store"
                    if store_str.startswith("file://"):
                        store_path = store_str.replace("file://", "")
                    else:
                        store_path = store_str

                if store_path:
                    # Validate that the zarr array shape matches the dask array shape
                    # This ensures no lazy operations have changed the shape
                    try:
                        # Convert store_path to string in case it's a Path object
                        store_path_str = str(store_path)

                        # Open the zarr store to get the actual array shape
                        if _is_ome_zarr_zip_path(store_path_str):
                            zarr_store = zarr.storage.ZipStore(
                                store_path_str, mode="r"
                            )
                            root = zarr.open_group(zarr_store, mode="r")
                            zarr_array = root[dataset_path]
                            zarr_store.close()
                        else:
                            root = zarr.open_group(store_path_str, mode="r")
                            zarr_array = root[dataset_path]

                        zarr_shape = zarr_array.shape
                        dask_shape = self.shape

                        # Check if spatial dimensions match
                        # Extract indices of spatial dimensions (x, y, z)
                        spatial_dims = ["x", "y", "z"]
                        spatial_indices = [
                            i
                            for i, dim in enumerate(self.dims)
                            if dim.lower() in spatial_dims
                        ]

                        # Compare only spatial dimensions
                        zarr_spatial_shape = tuple(
                            zarr_shape[i] for i in spatial_indices
                        )
                        dask_spatial_shape = tuple(
                            dask_shape[i] for i in spatial_indices
                        )

                        if zarr_spatial_shape != dask_spatial_shape:
                            raise ValueError(
                                f"Cannot use direct zarr access for apply_transform: "
                                f"the floating image has lazy operations that change its shape. "
                                f"Zarr array shape: {zarr_shape}, but dask array shape: {dask_shape}. "
                                f"Spatial dimensions - Zarr: {zarr_spatial_shape}, Dask: {dask_spatial_shape}. "
                                f"This typically happens when using downsample levels beyond what exists "
                                f"in the zarr store, or when using downsample_near_isotropic option. "
                                f"To fix this, save the floating image to an intermediate zarr file first:\n"
                                f"  flo_znimg.to_ome_zarr('intermediate.zarr')\n"
                                f"  flo_znimg = ZarrNii.from_ome_zarr('intermediate.zarr')\n"
                                f"  transformed = flo_znimg.apply_transform(...)"
                            )

                    except (KeyError, FileNotFoundError) as e:
                        # Dataset doesn't exist at the specified path
                        raise ValueError(
                            f"Cannot use direct zarr access for apply_transform: "
                            f"the specified dataset '{dataset_path}' does not exist in the zarr store "
                            f"at '{store_path}'. This may happen when using a downsample level that "
                            f"doesn't exist in the zarr store. "
                            f"To fix this, save the floating image to an intermediate zarr file first:\n"
                            f"  flo_znimg.to_ome_zarr('intermediate.zarr')\n"
                            f"  flo_znimg = ZarrNii.from_ome_zarr('intermediate.zarr')\n"
                            f"  transformed = flo_znimg.apply_transform(...)"
                        ) from e

                    return {
                        "store_path": store_path,
                        "dataset_path": dataset_path,
                        "array_shape": self.shape,
                    }
    except ValueError:
        # Re-raise ValueError (our validation errors)
        raise
    except Exception:
        # If we can't extract store info for other reasons, return None
        pass

    return None

zarrnii.core.ZarrNii.from_ngff_image(ngff_image, axes_order='ZYX', xyz_orientation='RAS', omero=None) classmethod

Create ZarrNii from an existing NgffImage.

Parameters:

• ngff_image (NgffImage) –

  NgffImage to wrap

• axes_order (str, default: 'ZYX' ) –

  Spatial axes order for NIfTI compatibility

• xyz_orientation (str, default: 'RAS' ) –

  Anatomical orientation string in XYZ axes order

• omero (Optional[object], default: None ) –

  Optional omero metadata object

Returns:

• 'ZarrNii' –

  ZarrNii instance

Source code in zarrnii/core.py

@classmethod
def from_ngff_image(
    cls,
    ngff_image: nz.NgffImage,
    axes_order: str = "ZYX",
    xyz_orientation: str = "RAS",
    omero: Optional[object] = None,
) -> "ZarrNii":
    """
    Create ZarrNii from an existing NgffImage.

    Args:
        ngff_image: NgffImage to wrap
        axes_order: Spatial axes order for NIfTI compatibility
        xyz_orientation: Anatomical orientation string in XYZ axes order
        omero: Optional omero metadata object

    Returns:
        ZarrNii instance
    """
    return cls(
        ngff_image=ngff_image,
        axes_order=axes_order,
        xyz_orientation=xyz_orientation,
        _omero=omero,
    )

zarrnii.core.ZarrNii.from_darr(darr, axes_order='ZYX', orientation='RAS', spacing=(1.0, 1.0, 1.0), origin=(0.0, 0.0, 0.0), name='image', omero=None, channel_labels=None, channel_colors=None, channel_windows=None, axes_units=None, affine=None, **kwargs) classmethod

Create ZarrNii from dask array (legacy compatibility constructor).

Parameters:

• darr (Array) –

  Dask array containing image data

• axes_order (str, default: 'ZYX' ) –

  Spatial axes order

• orientation (str, default: 'RAS' ) –

  Anatomical orientation string

• spacing (Tuple[float, float, float], default: (1.0, 1.0, 1.0) ) –

  Voxel spacing, in axes_order

• origin (Tuple[float, float, float], default: (0.0, 0.0, 0.0) ) –

  Origin offset, in axes_order

• name (str, default: 'image' ) –

  Image name

• omero (Optional[object], default: None ) –

  Optional full OMERO metadata object (escape hatch). Mutually exclusive with channel_labels / channel_colors / channel_windows.

• channel_labels (Optional[List[str]], default: None ) –

  Optional channel names. When provided, OMERO metadata is built automatically via :func:make_omero.

• channel_colors (Optional[List[str]], default: None ) –

  Optional per-channel colors as RRGGBB hex strings (#RRGGBB also accepted). Must have the same length as channel_labels when supplied.

• channel_windows (Optional[List[Union['nz.OmeroWindow', Dict[str, float], Tuple[float, float, float, float], List[float]]]], default: None ) –

  Optional per-channel display windows. Each entry may be an nz.OmeroWindow, a dict with keys min/max/ start/end, or a 4-item tuple/list (min, max, start, end). Must have the same length as channel_labels when supplied.

• axes_units (Optional[Dict[str, str]], default: None ) –

  Optional mapping of axis name to unit string (e.g. {"x": "micrometer", "y": "micrometer", "z": "micrometer"}). All values must be valid OME-Zarr space units (see :data:VALID_AXES_UNITS). When None, no unit metadata is stored and viewers fall back to their defaults. Non-mm units are automatically converted to millimeters on import; spacing and origin are scaled accordingly and axes_units is updated to 'millimeter'. Pipelines that already use mm are unaffected.

• affine (Optional[AffineTransform], default: None ) –

  Deprecated parameter - no longer supported

Returns:

• 'ZarrNii' –

  ZarrNii instance

Raises:

• ValueError –

  If affine parameter is provided

• ValueError –

  If both omero and any of the channel convenience arguments are provided simultaneously.

• ValueError –

  If channel_labels length does not match the number of channels in darr.

• ValueError –

  If any value in axes_units is not a valid OME-Zarr space unit.

Source code in zarrnii/core.py

@classmethod
def from_darr(
    cls,
    darr: da.Array,
    axes_order: str = "ZYX",
    orientation: str = "RAS",
    spacing: Tuple[float, float, float] = (1.0, 1.0, 1.0),
    origin: Tuple[float, float, float] = (0.0, 0.0, 0.0),
    name: str = "image",
    omero: Optional[object] = None,
    channel_labels: Optional[List[str]] = None,
    channel_colors: Optional[List[str]] = None,
    channel_windows: Optional[
        List[
            Union[
                "nz.OmeroWindow",
                Dict[str, float],
                Tuple[float, float, float, float],
                List[float],
            ]
        ]
    ] = None,
    axes_units: Optional[Dict[str, str]] = None,
    affine: Optional[AffineTransform] = None,
    **kwargs,
) -> "ZarrNii":
    """
    Create ZarrNii from dask array (legacy compatibility constructor).

    Args:
        darr: Dask array containing image data
        axes_order: Spatial axes order
        orientation: Anatomical orientation string
        spacing: Voxel spacing, in axes_order
        origin: Origin offset, in axes_order
        name: Image name
        omero: Optional full OMERO metadata object (escape hatch).  Mutually
            exclusive with *channel_labels* / *channel_colors* /
            *channel_windows*.
        channel_labels: Optional channel names.  When provided, OMERO metadata
            is built automatically via :func:`make_omero`.
        channel_colors: Optional per-channel colors as ``RRGGBB`` hex strings
            (``#RRGGBB`` also accepted).  Must have the same length as
            *channel_labels* when supplied.
        channel_windows: Optional per-channel display windows.  Each entry may
            be an ``nz.OmeroWindow``, a dict with keys ``min``/``max``/
            ``start``/``end``, or a 4-item tuple/list ``(min, max, start,
            end)``.  Must have the same length as *channel_labels* when
            supplied.
        axes_units: Optional mapping of axis name to unit string (e.g.
            ``{"x": "micrometer", "y": "micrometer", "z": "micrometer"}``).
            All values must be valid OME-Zarr space units (see
            :data:`VALID_AXES_UNITS`).  When ``None``, no unit metadata is
            stored and viewers fall back to their defaults.  **Non-mm units
            are automatically converted to millimeters on import**; spacing
            and origin are scaled accordingly and axes_units is updated to
            ``'millimeter'``.  Pipelines that already use mm are unaffected.
        affine: Deprecated parameter - no longer supported

    Returns:
        ZarrNii instance

    Raises:
        ValueError: If affine parameter is provided
        ValueError: If both *omero* and any of the channel convenience
            arguments are provided simultaneously.
        ValueError: If *channel_labels* length does not match the number of
            channels in *darr*.
        ValueError: If any value in *axes_units* is not a valid OME-Zarr
            space unit.
    """
    # Check for deprecated affine parameter
    if affine is not None:
        raise ValueError(
            "The 'affine' parameter is no longer supported in from_darr(). "
            "Please use 'spacing' and 'origin' parameters instead. "
            "If you need to specify a full affine transformation, use from_nifti() "
            "or construct the NgffImage directly."
        )

    # Validate axes_units
    _validate_axes_units(axes_units)

    # Validate channel convenience args vs explicit omero
    if omero is not None and (
        channel_labels is not None
        or channel_colors is not None
        or channel_windows is not None
    ):
        raise ValueError(
            "Provide either 'omero' or channel_labels/channel_colors/"
            "channel_windows, not both."
        )
    if (
        channel_colors is not None or channel_windows is not None
    ) and channel_labels is None:
        raise ValueError(
            "channel_labels is required when channel_colors or channel_windows are provided and omero is not set."
        )

    # Build omero from convenience args if labels were provided
    if omero is None and channel_labels is not None:
        n_channels = darr.shape[0] if darr.ndim >= 4 else 1
        if len(channel_labels) != n_channels:
            raise ValueError(
                f"channel_labels length ({len(channel_labels)}) must match "
                f"number of channels ({n_channels})."
            )
        omero = make_omero(
            channel_labels=channel_labels,
            channel_colors=channel_colors,
            channel_windows=channel_windows,
        )

    # Use spacing and origin
    if axes_order == "ZYX":
        scale = {"z": spacing[0], "y": spacing[1], "x": spacing[2]}
        translation = {"z": origin[0], "y": origin[1], "x": origin[2]}
    else:  # XYZ
        scale = {"x": spacing[0], "y": spacing[1], "z": spacing[2]}
        translation = {"x": origin[0], "y": origin[1], "z": origin[2]}

    # Create dimensions based on data shape after dimension adjustments
    final_ndim = len(darr.shape)
    if final_ndim == 4:
        # 4D: (c, z, y, x) or (c, x, y, z) - standard case
        dims = ["c"] + list(axes_order.lower())
    elif final_ndim == 5:
        # 5D: (t, c, z, y, x) or (t, c, x, y, z) - time dimension included
        dims = ["t", "c"] + list(axes_order.lower())
    else:
        # Fallback for other cases
        dims = ["c"] + list(axes_order.lower())

    # Create NgffImage and normalize spatial metadata to mm.
    ngff_image = nz.NgffImage(
        data=darr,
        dims=dims,
        scale=scale,
        translation=translation,
        name=name,
        axes_units=axes_units,
    )
    ngff_image = _normalize_ngff_image_to_mm(ngff_image)

    return cls(
        ngff_image=ngff_image,
        axes_order=axes_order,
        xyz_orientation=orientation,
        _omero=omero,
    )

zarrnii.core.ZarrNii.from_ome_zarr(store_or_path, level=0, channels=None, channel_labels=None, set_channel_labels=None, timepoints=None, storage_options=None, axes_order='ZYX', orientation=None, downsample_near_isotropic=False, chunks=None, rechunk=False) classmethod

Load ZarrNii from OME-Zarr store with flexible options.

Creates a ZarrNii instance from an OME-Zarr store, supporting multiscale pyramids, channel/timepoint selection, and various storage backends. Automatically handles metadata extraction and format conversion.

Parameters:

• store_or_path (Union[str, Any]) –

  Store or path to OME-Zarr file. Supports: - Local file paths - Remote URLs (s3://, http://, etc.) - ZIP files (.zip extension) - Zarr store objects

• level (int, default: 0 ) –

  Pyramid level to load (0 = highest resolution). If level exceeds available levels, applies lazy downsampling

• channels (Optional[List[int]], default: None ) –

  List of channel indices to load (0-based). Mutually exclusive with channel_labels

• channel_labels (Optional[List[str]], default: None ) –

  List of channel names to load by label. Requires OMERO metadata. Mutually exclusive with channels

• set_channel_labels (Optional[List[str]], default: None ) –

  Channel labels that define the channels present in the data, in channel index order. When provided, these labels are used to build output OMERO metadata and to resolve channel_labels selection.

• timepoints (Optional[List[int]], default: None ) –

  List of timepoint indices to load (0-based). If None, loads all available timepoints

• storage_options (Optional[Dict[str, Any]], default: None ) –

  Additional options for zarr storage backend (e.g., credentials for cloud storage)

• axes_order (str, default: 'ZYX' ) –

  Spatial axis order for NIfTI compatibility. Either "ZYX" or "XYZ"

• orientation (Optional[str], default: None ) –

  Default anatomical orientation if not in metadata. Standard orientations like "RAS", "LPI", etc. This is always interpreted in XYZ axes order for consistency. This setting will override any orientation defined in the OME zarr metadata

• downsample_near_isotropic (bool, default: False ) –

  If True, automatically downsample dimensions with smaller voxel sizes to achieve near-isotropic resolution

• chunks (Optional[Union[Tuple[int, ...], Literal['auto']]], default: None ) –

  Optional chunking strategy to apply after lazy loading. If provided as a tuple that omits leading singleton dimensions, singleton chunk sizes are prepended automatically when possible based on existing chunking.

• rechunk (bool, default: False ) –

  Deprecated. Rechunking behavior is now controlled by chunks directly.

Returns:

• 'ZarrNii' –

  ZarrNii instance with loaded data and metadata

Raises:

• ValueError –

  If both channels and channel_labels are specified, or if invalid level/indices are provided

• FileNotFoundError –

  If store_or_path does not exist

• KeyError –

  If specified channel labels are not found

• IOError –

  If unable to read from the storage backend

Examples:

>>> # Load full resolution data
>>> znii = ZarrNii.from_ome_zarr("/path/to/data.zarr")

>>> # Load specific channels and pyramid level
>>> znii = ZarrNii.from_ome_zarr(
...     "/path/to/data.zarr",
...     level=1,
...     channels=[0, 2],
...     orientation="LPI"
... )

>>> # Load from cloud storage
>>> znii = ZarrNii.from_ome_zarr(
...     "s3://bucket/data.zarr",
...     storage_options={"key": "access_key", "secret": "secret"}
... )

Notes

Orientation Metadata Backwards Compatibility:

This method implements backwards compatibility for orientation metadata:

1. Override: Setting the orientation here will override any orientation defined in the OME Zarr metadata.

2. Zarr Metadata: Checks for 'xyz_orientation' first (new format), then falls back to 'orientation' (legacy format)

3. Legacy Fallback: When only legacy 'orientation' is found, the orientation string is automatically reversed to convert from ZYX-based encoding (legacy) to XYZ-based encoding (current standard)

4. Default Fallback: If no orientation metadata is found, uses RAS orientation as the default.

Examples of the conversion: - Legacy 'orientation'='SAR' (ZYX) → 'xyz_orientation'='RAS' (XYZ) - Legacy 'orientation'='IPL' (ZYX) → 'xyz_orientation'='LPI' (XYZ)

This ensures consistent orientation handling while maintaining backwards compatibility with existing OME-Zarr files that use the legacy format.

Internal units invariant: Spatial scale and translation values are always stored in millimeters internally. If the OME-Zarr file contains non-mm unit metadata (e.g. micrometer), the scale and translation values are automatically converted to mm on load and axes_units is updated to 'millimeter'.

Source code in zarrnii/core.py

@classmethod
def from_ome_zarr(
    cls,
    store_or_path: Union[str, Any],
    level: int = 0,
    channels: Optional[List[int]] = None,
    channel_labels: Optional[List[str]] = None,
    set_channel_labels: Optional[List[str]] = None,
    timepoints: Optional[List[int]] = None,
    storage_options: Optional[Dict[str, Any]] = None,
    axes_order: str = "ZYX",
    orientation: Optional[str] = None,
    downsample_near_isotropic: bool = False,
    chunks: Optional[Union[Tuple[int, ...], Literal["auto"]]] = None,
    rechunk: bool = False,
) -> "ZarrNii":
    """Load ZarrNii from OME-Zarr store with flexible options.

    Creates a ZarrNii instance from an OME-Zarr store, supporting multiscale
    pyramids, channel/timepoint selection, and various storage backends.
    Automatically handles metadata extraction and format conversion.

    Args:
        store_or_path: Store or path to OME-Zarr file. Supports:
            - Local file paths
            - Remote URLs (s3://, http://, etc.)
            - ZIP files (.zip extension)
            - Zarr store objects
        level: Pyramid level to load (0 = highest resolution). If level
            exceeds available levels, applies lazy downsampling
        channels: List of channel indices to load (0-based). Mutually
            exclusive with channel_labels
        channel_labels: List of channel names to load by label. Requires
            OMERO metadata. Mutually exclusive with channels
        set_channel_labels: Channel labels that define the channels present
            in the data, in channel index order. When provided, these labels
            are used to build output OMERO metadata and to resolve
            channel_labels selection.
        timepoints: List of timepoint indices to load (0-based). If None,
            loads all available timepoints
        storage_options: Additional options for zarr storage backend
            (e.g., credentials for cloud storage)
        axes_order: Spatial axis order for NIfTI compatibility.
            Either "ZYX" or "XYZ"
        orientation: Default anatomical orientation if not in metadata.
            Standard orientations like "RAS", "LPI", etc. This is always
            interpreted in XYZ axes order for consistency. This setting will override
            any orientation defined in the OME zarr metadata
        downsample_near_isotropic: If True, automatically downsample
            dimensions with smaller voxel sizes to achieve near-isotropic
            resolution
        chunks: Optional chunking strategy to apply after lazy loading.
            If provided as a tuple that omits leading singleton dimensions,
            singleton chunk sizes are prepended automatically when possible
            based on existing chunking.
        rechunk: Deprecated. Rechunking behavior is now controlled by
            ``chunks`` directly.

    Returns:
        ZarrNii instance with loaded data and metadata

    Raises:
        ValueError: If both channels and channel_labels are specified,
            or if invalid level/indices are provided
        FileNotFoundError: If store_or_path does not exist
        KeyError: If specified channel labels are not found
        IOError: If unable to read from the storage backend

    Examples:
        >>> # Load full resolution data
        >>> znii = ZarrNii.from_ome_zarr("/path/to/data.zarr")

        >>> # Load specific channels and pyramid level
        >>> znii = ZarrNii.from_ome_zarr(
        ...     "/path/to/data.zarr",
        ...     level=1,
        ...     channels=[0, 2],
        ...     orientation="LPI"
        ... )

        >>> # Load from cloud storage
        >>> znii = ZarrNii.from_ome_zarr(
        ...     "s3://bucket/data.zarr",
        ...     storage_options={"key": "access_key", "secret": "secret"}
        ... )

    Notes:
        **Orientation Metadata Backwards Compatibility:**

        This method implements backwards compatibility for orientation metadata:

        1. **Override**: Setting the orientation here will override
           any orientation defined in the OME Zarr metadata.

        2. **Zarr Metadata**: Checks for 'xyz_orientation' first (new format),
           then falls back to 'orientation' (legacy format)

        3. **Legacy Fallback**: When only legacy 'orientation' is found, the
           orientation string is automatically reversed to convert from ZYX-based
           encoding (legacy) to XYZ-based encoding (current standard)

        4. **Default Fallback**: If no orientation metadata is found, uses RAS
           orientation as the default.

        Examples of the conversion:
        - Legacy 'orientation'='SAR' (ZYX) → 'xyz_orientation'='RAS' (XYZ)
        - Legacy 'orientation'='IPL' (ZYX) → 'xyz_orientation'='LPI' (XYZ)

        This ensures consistent orientation handling while maintaining backwards
        compatibility with existing OME-Zarr files that use the legacy format.

        **Internal units invariant:**
        Spatial scale and translation values are always stored in millimeters
        internally.  If the OME-Zarr file contains non-mm unit metadata (e.g.
        ``micrometer``), the scale and translation values are automatically
        converted to mm on load and ``axes_units`` is updated to
        ``'millimeter'``.
    """
    # Validate channel and timepoint selection arguments
    if channels is not None and channel_labels is not None:
        raise ValueError("Cannot specify both 'channels' and 'channel_labels'")

    # Load the multiscales object
    try:
        if isinstance(store_or_path, str):
            # Handle OME-Zarr zip files by creating a ZipStore
            if _is_ome_zarr_zip_path(store_or_path):
                import zarr

                store = zarr.storage.ZipStore(store_or_path, mode="r")
                multiscales = nz.from_ngff_zarr(
                    store, storage_options=storage_options or {}
                )
                # Note: We'll close the store after extracting metadata
            else:
                multiscales = nz.from_ngff_zarr(
                    store_or_path, storage_options=storage_options or {}
                )
        else:
            multiscales = nz.from_ngff_zarr(store_or_path)
    except Exception as e:
        # Fallback for older zarr/ngff_zarr versions
        if isinstance(store_or_path, str):
            if _is_ome_zarr_zip_path(store_or_path):
                import zarr

                store = zarr.storage.ZipStore(store_or_path, mode="r")
                multiscales = nz.from_ngff_zarr(store)
            else:
                store = fsspec.get_mapper(store_or_path, **storage_options or {})
                multiscales = nz.from_ngff_zarr(store)
        else:
            store = store_or_path
            multiscales = nz.from_ngff_zarr(store)

    # Extract omero metadata from the already-parsed multiscales metadata.
    # ngff_zarr's from_ngff_zarr() correctly handles both v0.4 (omero at root
    # group level) and v0.5 (omero nested under the 'ome' key), so we rely on
    # it rather than hard-coding a group.attrs lookup.
    omero_metadata = getattr(multiscales.metadata, "omero", None)

    # Read orientation metadata with backwards compatibility support
    # Priority: xyz_orientation (new) > orientation (legacy, with reversal)
    try:
        import zarr

        if orientation is None:

            if isinstance(store_or_path, str):
                if _is_ome_zarr_zip_path(store_or_path):
                    zip_store = zarr.storage.ZipStore(store_or_path, mode="r")
                    group = zarr.open_group(zip_store, mode="r")
                    # Check for new xyz_orientation first, then fallback to legacy orientation
                    if "xyz_orientation" in group.attrs:
                        orientation = group.attrs["xyz_orientation"]
                    elif "orientation" in group.attrs:
                        # Legacy orientation is ZYX-based, reverse it to get XYZ-based orientation
                        legacy_orientation = group.attrs["orientation"]
                        orientation = reverse_orientation_string(legacy_orientation)
                    # If neither found, use the provided default orientation
                    zip_store.close()
                else:
                    group = zarr.open_group(store_or_path, mode="r")
                    # Check for new xyz_orientation first, then fallback to legacy orientation
                    if "xyz_orientation" in group.attrs:
                        orientation = group.attrs["xyz_orientation"]
                    elif "orientation" in group.attrs:
                        # Legacy orientation is ZYX-based, reverse it to get XYZ-based orientation
                        legacy_orientation = group.attrs["orientation"]
                        orientation = reverse_orientation_string(legacy_orientation)
                    # If neither found, use the provided default orientation
            else:
                group = zarr.open_group(store_or_path, mode="r")
                # Check for new xyz_orientation first, then fallback to legacy orientation
                if "xyz_orientation" in group.attrs:
                    orientation = group.attrs["xyz_orientation"]
                elif "orientation" in group.attrs:
                    # Legacy orientation is ZYX-based, reverse it to get XYZ-based orientation
                    legacy_orientation = group.attrs["orientation"]
                    orientation = reverse_orientation_string(legacy_orientation)
                # If neither found, use the provided default orientation

    except Exception:
        # If we can't read orientation metadata, use the provided default
        pass

    # If orientation is still None, use the fallback default
    if orientation is None:
        orientation = "RAS"
    # Determine the available pyramid levels and handle lazy downsampling
    max_level = len(multiscales.images) - 1
    actual_level = min(level, max_level)
    do_downsample = level > max_level

    # Get the highest available level
    ngff_image = multiscales.images[actual_level]
    dims = list(ngff_image.dims)

    if set_channel_labels is not None:
        if "c" in dims:
            n_channels = ngff_image.data.shape[dims.index("c")]
        else:
            n_channels = 1
        if len(set_channel_labels) != n_channels:
            raise ValueError(
                f"set_channel_labels length ({len(set_channel_labels)}) must match "
                f"number of channels in source data ({n_channels})."
            )
        omero_metadata = make_omero(set_channel_labels)

    # Handle channel and timepoint selection and filter omero metadata accordingly
    filtered_omero = omero_metadata
    if channels is not None or channel_labels is not None or timepoints is not None:
        ngff_image, filtered_omero = _select_dimensions_from_image_with_omero(
            ngff_image,
            multiscales,
            channels,
            channel_labels,
            timepoints,
            omero_metadata,
        )

    # Normalize spatial metadata to mm before building the ZarrNii instance.
    ngff_image = _normalize_ngff_image_to_mm(ngff_image)

    # Create ZarrNii instance with xyz_orientation
    znimg = cls(
        ngff_image=ngff_image,
        axes_order=axes_order,
        xyz_orientation=orientation,
        _omero=filtered_omero,
    )

    # Apply lazy downsampling if needed
    if do_downsample:
        level_ds = level - max_level
        downsample_factor = 2**level_ds

        # Get spatial dims based on axes order
        spatial_dims = ["z", "y", "x"] if axes_order == "ZYX" else ["x", "y", "z"]

        # Apply downsampling using the existing method
        znimg = znimg.downsample(
            factors=downsample_factor, spatial_dims=spatial_dims
        )

    # Apply near-isotropic downsampling if requested
    if downsample_near_isotropic:
        znimg = _apply_near_isotropic_downsampling(znimg, axes_order)

    if rechunk:
        warnings.warn(
            "The 'rechunk' argument is deprecated and no longer needed. "
            "Set 'chunks' to trigger rechunking when chunk sizes differ.",
            DeprecationWarning,
            stacklevel=2,
        )

    if chunks is not None:
        normalized_chunks = _normalize_chunks_with_leading_singletons(
            chunks, znimg.data.chunksize
        )
        if isinstance(normalized_chunks, tuple):
            should_rechunk = normalized_chunks != znimg.data.chunksize
        else:
            should_rechunk = True
        if should_rechunk:
            znimg.data = znimg.data.rechunk(normalized_chunks)

    return znimg

zarrnii.core.ZarrNii.from_nifti(path, chunks='auto', axes_order='XYZ', name=None, as_ref=False, zooms=None) classmethod

Load ZarrNii from NIfTI file with flexible loading options.

Creates a ZarrNii instance from a NIfTI file, automatically converting the data to dask arrays and extracting spatial transformation information. Supports both full data loading and reference-only loading for memory efficiency. For 4D NIfTI files, the 4th dimension is treated as channels (XYZC ordering, analogous to CZYX in OME-Zarr).

Parameters:

• path (Union[str, bytes]) –

  File path to NIfTI file (.nii, .nii.gz, .img/.hdr)

• chunks (Union[str, Tuple[int, ...]], default: 'auto' ) –

  Dask array chunking strategy. Can be: - "auto": Automatic chunking based on file size - Tuple of ints: Manual chunk sizes for each dimension - Dict mapping axis to chunk size

• axes_order (str, default: 'XYZ' ) –

  Spatial axis ordering convention. Either: - "XYZ": X=left-right, Y=anterior-posterior, Z=inferior-superior - "ZYX": Z=inferior-superior, Y=anterior-posterior, X=left-right

• name (Optional[str], default: None ) –

  Optional name for the resulting NgffImage. If None, uses filename without extension

• as_ref (bool, default: False ) –

  If True, creates empty dask array with correct shape/metadata without loading actual image data (memory efficient for templates)

• zooms (Optional[Tuple[float, float, float]], default: None ) –

  Target voxel spacing as (x, y, z) in mm. Only valid when as_ref=True. Adjusts shape and affine accordingly

Returns:

• 'ZarrNii' –

  ZarrNii instance containing NIfTI data and spatial metadata. If the

• 'ZarrNii' –

  NIfTI file contains channel labels in header extensions, they will be

• 'ZarrNii' –

  preserved in OMERO metadata.

Raises:

• ValueError –

  If zooms specified with as_ref=False, or invalid axes_order

• FileNotFoundError –

  If NIfTI file does not exist

• OSError –

  If unable to read NIfTI file

• ImageFileError –

  If file is not valid NIfTI

Examples:

>>> # Load full NIfTI data
>>> znii = ZarrNii.from_nifti("/path/to/brain.nii.gz")

>>> # Load with custom chunking and axis order
>>> znii = ZarrNii.from_nifti(
...     "/path/to/data.nii",
...     chunks=(64, 64, 64),
...     axes_order="ZYX"
... )

>>> # Load 4D NIfTI with multiple channels
>>> znii = ZarrNii.from_nifti("/path/to/multichannel.nii.gz")
>>> print(znii.list_channels())  # Shows channel labels if stored

>>> # Create reference with target resolution
>>> znii_ref = ZarrNii.from_nifti(
...     "/path/to/template.nii.gz",
...     as_ref=True,
...     zooms=(2.0, 2.0, 2.0)
... )

Notes

• The method automatically handles NIfTI orientation codes and converts them to the specified axes_order for consistency with OME-Zarr workflows
• For 4D NIfTI files, the 4th dimension is interpreted as channels (XYZC)
• Channel labels stored in NIfTI header extensions are automatically loaded
• Internal units invariant: spatial scale and translation values are always stored in millimeters. NIfTI files that declare mm units are stored as-is; files with other spatial units (e.g. micron, meter) are automatically converted to mm on import.

Source code in zarrnii/core.py

@classmethod
def from_nifti(
    cls,
    path: Union[str, bytes],
    chunks: Union[str, Tuple[int, ...]] = "auto",
    axes_order: str = "XYZ",
    name: Optional[str] = None,
    as_ref: bool = False,
    zooms: Optional[Tuple[float, float, float]] = None,
) -> "ZarrNii":
    """Load ZarrNii from NIfTI file with flexible loading options.

    Creates a ZarrNii instance from a NIfTI file, automatically converting
    the data to dask arrays and extracting spatial transformation information.
    Supports both full data loading and reference-only loading for memory
    efficiency. For 4D NIfTI files, the 4th dimension is treated as channels
    (XYZC ordering, analogous to CZYX in OME-Zarr).

    Args:
        path: File path to NIfTI file (.nii, .nii.gz, .img/.hdr)
        chunks: Dask array chunking strategy. Can be:
            - "auto": Automatic chunking based on file size
            - Tuple of ints: Manual chunk sizes for each dimension
            - Dict mapping axis to chunk size
        axes_order: Spatial axis ordering convention. Either:
            - "XYZ": X=left-right, Y=anterior-posterior, Z=inferior-superior
            - "ZYX": Z=inferior-superior, Y=anterior-posterior, X=left-right
        name: Optional name for the resulting NgffImage. If None,
            uses filename without extension
        as_ref: If True, creates empty dask array with correct shape/metadata
            without loading actual image data (memory efficient for templates)
        zooms: Target voxel spacing as (x, y, z) in mm. Only valid when
            as_ref=True. Adjusts shape and affine accordingly

    Returns:
        ZarrNii instance containing NIfTI data and spatial metadata. If the
        NIfTI file contains channel labels in header extensions, they will be
        preserved in OMERO metadata.

    Raises:
        ValueError: If zooms specified with as_ref=False, or invalid axes_order
        FileNotFoundError: If NIfTI file does not exist
        OSError: If unable to read NIfTI file
        nibabel.filebasedimages.ImageFileError: If file is not valid NIfTI

    Examples:
        >>> # Load full NIfTI data
        >>> znii = ZarrNii.from_nifti("/path/to/brain.nii.gz")

        >>> # Load with custom chunking and axis order
        >>> znii = ZarrNii.from_nifti(
        ...     "/path/to/data.nii",
        ...     chunks=(64, 64, 64),
        ...     axes_order="ZYX"
        ... )

        >>> # Load 4D NIfTI with multiple channels
        >>> znii = ZarrNii.from_nifti("/path/to/multichannel.nii.gz")
        >>> print(znii.list_channels())  # Shows channel labels if stored

        >>> # Create reference with target resolution
        >>> znii_ref = ZarrNii.from_nifti(
        ...     "/path/to/template.nii.gz",
        ...     as_ref=True,
        ...     zooms=(2.0, 2.0, 2.0)
        ... )

    Notes:
        - The method automatically handles NIfTI orientation codes and converts
          them to the specified axes_order for consistency with OME-Zarr workflows
        - For 4D NIfTI files, the 4th dimension is interpreted as channels (XYZC)
        - Channel labels stored in NIfTI header extensions are automatically loaded
        - **Internal units invariant**: spatial scale and translation values are
          always stored in millimeters.  NIfTI files that declare mm units are
          stored as-is; files with other spatial units (e.g. micron, meter) are
          automatically converted to mm on import.
    """
    if not as_ref and zooms is not None:
        raise ValueError("`zooms` can only be used when `as_ref=True`.")

    # Load NIfTI file
    nifti_img = nib.load(path)
    shape = nifti_img.header.get_data_shape()
    affine_matrix = nifti_img.affine.copy()

    # infer orientation from the affine
    orientation = _affine_to_orientation(affine_matrix)

    in_zooms = np.array(nifti_img.header.get_zooms())

    # Adjust shape and affine if zooms are provided
    if zooms is not None:
        scaling_factor = in_zooms / zooms
        new_shape = [
            int(np.floor(shape[0] * scaling_factor[2])),  # Z
            int(np.floor(shape[1] * scaling_factor[1])),  # Y
            int(np.floor(shape[2] * scaling_factor[0])),  # X
        ]
        # create affine by specifying orientation, scale and translation
        affine_matrix = _axcodes2aff(orientation, zooms, affine_matrix[:3, 3])
        in_zooms = zooms
    else:
        new_shape = shape

    if as_ref:
        # Create an empty dask array with the adjusted shape
        # Already add channel dimension here
        darr = da.zeros((1, *new_shape), chunks=chunks, dtype="float32")

        # Mark that we already added channel dimension
        has_channel_dim = True

    else:
        # Load the NIfTI data and convert to a dask array
        array = nifti_img.get_fdata()
        darr = da.from_array(array, chunks=chunks)
        has_channel_dim = False

    # NIfTI uses XYZ ordering, but we need to handle channels
    # For 4D NIfTI: XYZC (4th dim is channels, analogous to CZYX in OME-Zarr)
    original_ndim = len(darr.shape)

    if has_channel_dim:
        # Already has channel dimension from as_ref, don't modify
        pass
    elif original_ndim == 3:
        # 3D data: add channel dimension -> (c, z, y, x) or (c, x, y, z)
        darr = darr[np.newaxis, ...]
        # If axes_order is to ultimately be ZYX, transpose spatial XYZ to ZYX
        if axes_order == "ZYX":
            darr = darr.transpose(0, 3, 2, 1)  # CXYZ -> CZYX
    elif original_ndim == 4:
        # 4D data: NIfTI stores as XYZC, we need CZYX or CXYZ
        if axes_order == "ZYX":
            # Transpose from XYZC to CZYX
            darr = darr.transpose(3, 2, 1, 0)  # XYZC -> CZYX
        else:
            # Transpose from XYZC to CXYZ
            darr = darr.transpose(3, 0, 1, 2)  # XYZC -> CXYZ
    elif original_ndim == 5:
        # 5D data: assume (t, z, y, x, c) and handle appropriately
        pass  # Keep as is - 5D is already the target format
    else:
        # For 1D, 2D, or >5D data, add channel dimension and let user handle
        darr = darr[np.newaxis, ...]

    # Create dimensions based on data shape after dimension adjustments
    final_ndim = len(darr.shape)
    if final_ndim == 4:
        # 4D: (c, z, y, x) or (c, x, y, z) - standard case
        dims = ["c"] + list(axes_order.lower())
    elif final_ndim == 5:
        # 5D: (t, c, z, y, x) or (t, c, x, y, z) - time dimension included
        dims = ["t", "c"] + list(axes_order.lower())
    else:
        # Fallback for other cases
        dims = ["c"] + list(axes_order.lower())

    # Extract translation from affine, scale from the zooms
    scale = {}
    translation = {}
    axes_units = {}
    spatial_dims = ["z", "y", "x"] if axes_order == "ZYX" else ["x", "y", "z"]

    # Get spatial units from NIfTI header
    try:
        spatial_unit_code, time_unit_code = nifti_img.header.get_xyzt_units()
    except Exception:
        spatial_unit_code = "unknown"

    # Map NIfTI spatial unit codes to OME-Zarr unit names
    # NIfTI codes: 'unknown', 'meter', 'mm', 'micron'
    nifti_to_omezarr_units = {
        "mm": "millimeter",
        "micron": "micrometer",
        "meter": "meter",
        "unknown": "millimeter",  # Default to millimeter for unknown (NIfTI standard assumption)
    }
    omezarr_unit = nifti_to_omezarr_units.get(spatial_unit_code, "millimeter")

    for i, dim in enumerate(spatial_dims):
        scale[dim] = float(in_zooms[i])
        translation[dim] = affine_matrix[i, 3]
        axes_units[dim] = omezarr_unit

    # Create NgffImage and normalize spatial metadata to mm.
    if name is None:
        name = f"nifti_image_{path}"

    ngff_image = nz.NgffImage(
        data=darr,
        dims=dims,
        scale=scale,
        translation=translation,
        axes_units=axes_units,
        name=name,
    )
    ngff_image = _normalize_ngff_image_to_mm(ngff_image)

    # Extract channel labels from NIfTI header extensions if present
    channel_labels = None
    if (
        hasattr(nifti_img.header, "extensions")
        and len(nifti_img.header.extensions) > 0
    ):
        import json

        for ext in nifti_img.header.extensions:
            try:
                if ext.get_code() == 1:
                    # Try to decode the extension content as JSON
                    content = ext.get_content().decode("utf-8")
                    metadata = json.loads(content)

                    # Look for channel_labels in the metadata
                    if "channel_labels" in metadata:
                        channel_labels = metadata["channel_labels"]
                        break
            except (json.JSONDecodeError, UnicodeDecodeError, AttributeError):
                # Skip extensions that aren't JSON or can't be decoded
                continue

    # Create ZarrNii instance
    # Extract OMERO metadata for channel labels if present
    omero_metadata = None
    if channel_labels is not None and len(channel_labels) > 0:
        # Get the number of channels from the data
        num_channels = darr.shape[0] if "c" in dims else 1

        # Only use channel labels if count matches
        if len(channel_labels) == num_channels:
            omero_metadata = make_omero(channel_labels)

    zarrnii_instance = cls(
        ngff_image=ngff_image,
        axes_order=axes_order,
        xyz_orientation=orientation,
        _omero=omero_metadata,
    )

    return zarrnii_instance

zarrnii.core.ZarrNii.crop(bbox_min, bbox_max=None, spatial_dims=None, physical_coords=False, coords_units=None)

Extract a spatial region or multiple regions from the image.

Crops the image to the specified bounding box coordinates, preserving all metadata and non-spatial dimensions (channels, time). The cropping is performed in voxel coordinates by default, or physical coordinates if specified. Can crop a single region or multiple regions at once.

Parameters:

• bbox_min (Union[Tuple[float, ...], List[Tuple[Tuple[float, ...], Tuple[float, ...]]]]) –

  Either: - Minimum corner coordinates of bounding box as tuple (when bbox_max is provided). Length should match number of spatial dimensions (x, y, z order) - List of (bbox_min, bbox_max) tuples for batch cropping (when bbox_max is None)

• bbox_max (Optional[Tuple[float, ...]], default: None ) –

  Maximum corner coordinates of bounding box as tuple. Length should match number of spatial dimensions (x, y, z order). Should be None when bbox_min is a list of bounding boxes.

• spatial_dims (Optional[List[str]], default: None ) –

  Names of spatial dimensions to crop. If None, automatically derived from axes_order ("z","y","x" for ZYX or "x","y","z" for XYZ)

• physical_coords (bool, default: False ) –

  If True, bbox_min and bbox_max are in physical/world coordinates. If False, they are in voxel coordinates. Default is False.

• coords_units (Optional[Dict[str, str]], default: None ) –

  Spatial units of bbox_min / bbox_max when physical_coords is True. Expressed as a mapping of axis name to OME-Zarr unit string, e.g. {'x': 'millimeter', 'y': 'millimeter', 'z': 'millimeter'}. Absent axes default to 'millimeter'. If None, all axes default to 'millimeter'. When the supplied units differ from the units stored in the image, the coordinates are automatically converted before the crop. Ignored when physical_coords is False.

Returns:

• Union['ZarrNii', List['ZarrNii']] –

  New ZarrNii instance with cropped data (single crop) or list of

• Union['ZarrNii', List['ZarrNii']] –

  ZarrNii instances (batch crop) with updated spatial metadata

Raises:

• ValueError –

  If bbox coordinates are invalid or out of bounds, or if both list and bbox_max are provided, or if coords_units contains an unrecognised unit string

• IndexError –

  If bbox dimensions don't match spatial dimensions

Examples:

>>> # Crop 3D region (voxel coordinates)
>>> cropped = znii.crop((10, 20, 30), (110, 120, 130))

>>> # Crop with physical coordinates (default millimeter units)
>>> cropped = znii.crop((10.5, 20.5, 30.5), (110.5, 120.5, 130.5),
...                      physical_coords=True)

>>> # Crop with physical coordinates supplied in micrometers
>>> cropped = znii.crop(
...     (10500.0, 20500.0, 30500.0), (110500.0, 120500.0, 130500.0),
...     physical_coords=True,
...     coords_units={'x': 'micrometer', 'y': 'micrometer', 'z': 'micrometer'},
... )

>>> # Crop with explicit spatial dimensions
>>> cropped = znii.crop(
...     (50, 60, 70), (150, 160, 170),
...     spatial_dims=["x", "y", "z"]
... )

>>> # Batch crop multiple regions
>>> bboxes = [
...     ((10, 20, 30), (60, 70, 80)),
...     ((100, 110, 120), (150, 160, 170))
... ]
>>> cropped_list = znii.crop(bboxes, physical_coords=True)

Notes

• Coordinates are in voxel space (0-based indexing) by default
• Physical coordinates are in RAS orientation (Right-Anterior-Superior)
• The cropped region includes bbox_min but excludes bbox_max
• All non-spatial dimensions (channels, time) are preserved
• Spatial transformations are automatically updated
• When batch cropping, all patches share the same spatial_dims, physical_coords, and coords_units settings

Source code in zarrnii/core.py

def crop(
    self,
    bbox_min: Union[
        Tuple[float, ...], List[Tuple[Tuple[float, ...], Tuple[float, ...]]]
    ],
    bbox_max: Optional[Tuple[float, ...]] = None,
    spatial_dims: Optional[List[str]] = None,
    physical_coords: bool = False,
    coords_units: Optional[Dict[str, str]] = None,
) -> Union["ZarrNii", List["ZarrNii"]]:
    """Extract a spatial region or multiple regions from the image.

    Crops the image to the specified bounding box coordinates, preserving
    all metadata and non-spatial dimensions (channels, time). The cropping
    is performed in voxel coordinates by default, or physical coordinates
    if specified. Can crop a single region or multiple regions at once.

    Args:
        bbox_min: Either:
            - Minimum corner coordinates of bounding box as tuple
              (when bbox_max is provided). Length should match number of
              spatial dimensions (x, y, z order)
            - List of (bbox_min, bbox_max) tuples for batch cropping
              (when bbox_max is None)
        bbox_max: Maximum corner coordinates of bounding box as tuple.
            Length should match number of spatial dimensions (x, y, z order).
            Should be None when bbox_min is a list of bounding boxes.
        spatial_dims: Names of spatial dimensions to crop. If None,
            automatically derived from axes_order ("z","y","x" for ZYX
            or "x","y","z" for XYZ)
        physical_coords: If True, bbox_min and bbox_max are in physical/world
            coordinates. If False, they are in voxel coordinates.
            Default is False.
        coords_units: Spatial units of *bbox_min* / *bbox_max* when
            *physical_coords* is ``True``.  Expressed as a mapping of axis
            name to OME-Zarr unit string, e.g.
            ``{'x': 'millimeter', 'y': 'millimeter', 'z': 'millimeter'}``.
            Absent axes default to ``'millimeter'``.  If ``None``, all axes
            default to ``'millimeter'``.  When the supplied units differ from
            the units stored in the image, the coordinates are automatically
            converted before the crop.  Ignored when *physical_coords* is
            ``False``.

    Returns:
        New ZarrNii instance with cropped data (single crop) or list of
        ZarrNii instances (batch crop) with updated spatial metadata

    Raises:
        ValueError: If bbox coordinates are invalid or out of bounds, or
            if both list and bbox_max are provided, or if *coords_units*
            contains an unrecognised unit string
        IndexError: If bbox dimensions don't match spatial dimensions

    Examples:
        >>> # Crop 3D region (voxel coordinates)
        >>> cropped = znii.crop((10, 20, 30), (110, 120, 130))

        >>> # Crop with physical coordinates (default millimeter units)
        >>> cropped = znii.crop((10.5, 20.5, 30.5), (110.5, 120.5, 130.5),
        ...                      physical_coords=True)

        >>> # Crop with physical coordinates supplied in micrometers
        >>> cropped = znii.crop(
        ...     (10500.0, 20500.0, 30500.0), (110500.0, 120500.0, 130500.0),
        ...     physical_coords=True,
        ...     coords_units={'x': 'micrometer', 'y': 'micrometer', 'z': 'micrometer'},
        ... )

        >>> # Crop with explicit spatial dimensions
        >>> cropped = znii.crop(
        ...     (50, 60, 70), (150, 160, 170),
        ...     spatial_dims=["x", "y", "z"]
        ... )

        >>> # Batch crop multiple regions
        >>> bboxes = [
        ...     ((10, 20, 30), (60, 70, 80)),
        ...     ((100, 110, 120), (150, 160, 170))
        ... ]
        >>> cropped_list = znii.crop(bboxes, physical_coords=True)

    Notes:
        - Coordinates are in voxel space (0-based indexing) by default
        - Physical coordinates are in RAS orientation (Right-Anterior-Superior)
        - The cropped region includes bbox_min but excludes bbox_max
        - All non-spatial dimensions (channels, time) are preserved
        - Spatial transformations are automatically updated
        - When batch cropping, all patches share the same spatial_dims,
          physical_coords, and coords_units settings
    """
    _validate_axes_units(coords_units)

    # Check if this is batch cropping (list of bounding boxes)
    # A batch crop is a list of (bbox_min, bbox_max) tuples
    # Each element should be a tuple/list of two elements
    is_batch_crop = (
        isinstance(bbox_min, list)
        and len(bbox_min) > 0
        and isinstance(bbox_min[0], (tuple, list))
        and len(bbox_min[0]) == 2
    )

    if is_batch_crop:
        if bbox_max is not None:
            raise ValueError(
                "bbox_max should be None when bbox_min is a list of bounding boxes"
            )
        # Batch crop: recursively call crop for each bounding box
        return [
            self.crop(bmin, bmax, spatial_dims, physical_coords, coords_units)
            for bmin, bmax in bbox_min
        ]

    # Single crop: original implementation
    if bbox_max is None:
        raise ValueError("bbox_max is required when bbox_min is not a list")

    if spatial_dims is None:
        spatial_dims = (
            ["z", "y", "x"] if self.axes_order == "ZYX" else ["x", "y", "z"]
        )

    # Convert physical coordinates to voxel coordinates if needed
    if physical_coords:
        # Convert bbox coords from coords_units to image native units
        image_axes_units = self.ngff_image.axes_units
        bbox_min = _convert_physical_coords_units(
            bbox_min, coords_units, image_axes_units
        )
        bbox_max = _convert_physical_coords_units(
            bbox_max, coords_units, image_axes_units
        )

        # Physical coords are always in (x, y, z) order
        # Convert to homogeneous coordinates
        phys_min = np.array(list(bbox_min) + [1.0])
        phys_max = np.array(list(bbox_max) + [1.0])

        # Get inverse affine to convert from physical to voxel
        affine_inv = np.linalg.inv(
            self.get_affine_matrix(axes_order="XYZ")
        )  # TODO: should this always be xyz affine??

        # Transform to voxel coordinates
        voxel_min = affine_inv @ phys_min
        voxel_max = affine_inv @ phys_max

        # Extract voxel coordinates (x, y, z)
        voxel_min_xyz = voxel_min[:3]
        voxel_max_xyz = voxel_max[:3]

        # Round to nearest integer voxel indices
        voxel_min_xyz = np.round(voxel_min_xyz).astype(int)
        voxel_max_xyz = np.round(voxel_max_xyz).astype(int)

        # Ensure max >= min
        voxel_min_xyz = np.minimum(voxel_min_xyz, voxel_max_xyz)
        voxel_max_xyz = np.maximum(
            np.round(affine_inv @ phys_min).astype(int)[:3],
            np.round(affine_inv @ phys_max).astype(int)[:3],
        )

        # Create mapping from x,y,z to voxel coordinates
        bbox_min = voxel_min_xyz
        bbox_max = voxel_max_xyz

    # Create mapping from x,y,z to voxel coordinates
    bbox_vox_min = {
        "x": bbox_min[0],
        "y": bbox_min[1],
        "z": bbox_min[2],
    }
    bbox_vox_max = {
        "x": bbox_max[0],
        "y": bbox_max[1],
        "z": bbox_max[2],
    }

    dim_flips = _axcodes2flips(self.orientation)
    cropped_image = crop_ngff_image(
        self.ngff_image, bbox_vox_min, bbox_vox_max, dim_flips
    )
    return ZarrNii(
        ngff_image=cropped_image,
        axes_order=self.axes_order,
        xyz_orientation=self.xyz_orientation,
        _omero=self._omero,
    )

zarrnii.core.ZarrNii.crop_with_bounding_box(bbox_min, bbox_max, ras_coords=False)

Legacy method name for crop.

Parameters:

• bbox_min –

  Minimum corner coordinates

• bbox_max –

  Maximum corner coordinates

• ras_coords –

  If True, coordinates are in RAS physical space (deprecated, use physical_coords parameter of crop() instead)

Source code in zarrnii/core.py

def crop_with_bounding_box(self, bbox_min, bbox_max, ras_coords=False):
    """Legacy method name for crop.

    Args:
        bbox_min: Minimum corner coordinates
        bbox_max: Maximum corner coordinates
        ras_coords: If True, coordinates are in RAS physical space (deprecated,
            use physical_coords parameter of crop() instead)
    """
    return self.crop(bbox_min, bbox_max, physical_coords=ras_coords)

zarrnii.core.ZarrNii.crop_centered(centers, patch_size, spatial_dims=None, fill_value=0.0, centers_units=None)

Extract fixed-size patches centered at specified coordinates.

Crops the image to extract patches of a fixed size (in voxels) centered at the given physical coordinates. This is particularly useful for machine learning workflows where training patches must have consistent dimensions. The method can process a single center or multiple centers at once.

Patches that extend beyond image boundaries are padded with the fill_value to ensure all patches have exactly the requested size.

Parameters:

• centers (Union[Tuple[float, float, float], List[Tuple[float, float, float]]]) –

  Either: - Single center coordinate as (x, y, z) tuple in physical space - List of center coordinates for batch processing

• patch_size (Tuple[int, int, int]) –

  Size of the patch in voxels as (x, y, z) tuple. This defines the dimensions of each cropped region in voxel space. All returned patches will have exactly this size.

• spatial_dims (Optional[List[str]], default: None ) –

  Names of spatial dimensions to crop. If None, automatically derived from axes_order ("z","y","x" for ZYX or "x","y","z" for XYZ). Default is None.

• fill_value (float, default: 0.0 ) –

  Value to use for padding when patches extend beyond image boundaries. Default is 0.0.

• centers_units (Optional[Dict[str, str]], default: None ) –

  Spatial units of the center coordinates, expressed as a mapping of axis name to OME-Zarr unit string, e.g. {'x': 'millimeter', 'y': 'millimeter', 'z': 'millimeter'}. Absent axes default to 'millimeter'. If None, all axes default to 'millimeter'. When the supplied units differ from the units stored in the image, the coordinates are automatically converted before locating the patch center.

Returns:

• Union['ZarrNii', List['ZarrNii']] –

  Single ZarrNii instance (when centers is a single tuple) or list of

• Union['ZarrNii', List['ZarrNii']] –

  ZarrNii instances (when centers is a list) with cropped data and

• Union['ZarrNii', List['ZarrNii']] –

  updated spatial metadata. All patches will have exactly the shape

• Union['ZarrNii', List['ZarrNii']] –

  specified by patch_size (plus any non-spatial dimensions).

Raises:

• ValueError –

  If coordinates/dimensions are invalid, or if centers_units contains an unrecognised unit string

• IndexError –

  If patch_size dimensions don't match spatial dimensions

Examples:

>>> # Extract single 256x256x256 voxel patch at a coordinate (mm)
>>> center = (50.0, 60.0, 70.0)  # physical coordinates in mm
>>> patch = znii.crop_centered(center, patch_size=(256, 256, 256))
>>>
>>> # Extract patch with centers supplied in micrometers
>>> center_um = (50000.0, 60000.0, 70000.0)
>>> patch = znii.crop_centered(
...     center_um,
...     patch_size=(256, 256, 256),
...     centers_units={'x': 'micrometer', 'y': 'micrometer', 'z': 'micrometer'},
... )
>>>
>>> # Extract multiple patches for ML training
>>> centers = [
...     (50.0, 60.0, 70.0),
...     (100.0, 110.0, 120.0),
...     (150.0, 160.0, 170.0)
... ]
>>> patches = znii.crop_centered(centers, patch_size=(128, 128, 128))
>>> # Returns list of 3 ZarrNii instances, all with shape (1, 128, 128, 128)
>>>
>>> # Use with atlas sampling for ML training workflow
>>> centers = atlas.sample_region_patches(
...     n_patches=100,
...     region_ids="cortex",
...     seed=42
... )
>>> patches = image.crop_centered(centers, patch_size=(256, 256, 256))
>>>
>>> # Use custom fill value for padding
>>> patch = znii.crop_centered(center, patch_size=(256, 256, 256), fill_value=-1.0)

Notes

• Centers are in physical/world coordinates, always in (x, y, z) order
• By default centers are assumed to be in millimeters; use centers_units to supply coordinates in a different unit
• patch_size is in voxels, in (x, y, z) order
• The patch is centered at the given coordinate, extending ±patch_size/2
• If patch_size is odd, the center voxel is included
• Patches near boundaries are padded with fill_value to maintain size
• All patches are guaranteed to have exactly the requested size
• Useful for ML training where fixed patch sizes are required
• Coordinates from atlas.sample_region_patches() can be used directly

Source code in zarrnii/core.py

def crop_centered(
    self,
    centers: Union[Tuple[float, float, float], List[Tuple[float, float, float]]],
    patch_size: Tuple[int, int, int],
    spatial_dims: Optional[List[str]] = None,
    fill_value: float = 0.0,
    centers_units: Optional[Dict[str, str]] = None,
) -> Union["ZarrNii", List["ZarrNii"]]:
    """Extract fixed-size patches centered at specified coordinates.

    Crops the image to extract patches of a fixed size (in voxels) centered
    at the given physical coordinates. This is particularly useful for machine
    learning workflows where training patches must have consistent dimensions.
    The method can process a single center or multiple centers at once.

    Patches that extend beyond image boundaries are padded with the fill_value
    to ensure all patches have exactly the requested size.

    Args:
        centers: Either:
            - Single center coordinate as (x, y, z) tuple in physical space
            - List of center coordinates for batch processing
        patch_size: Size of the patch in voxels as (x, y, z) tuple.
            This defines the dimensions of each cropped region in voxel space.
            All returned patches will have exactly this size.
        spatial_dims: Names of spatial dimensions to crop. If None,
            automatically derived from axes_order ("z","y","x" for ZYX
            or "x","y","z" for XYZ). Default is None.
        fill_value: Value to use for padding when patches extend beyond
            image boundaries. Default is 0.0.
        centers_units: Spatial units of the center coordinates, expressed as
            a mapping of axis name to OME-Zarr unit string, e.g.
            ``{'x': 'millimeter', 'y': 'millimeter', 'z': 'millimeter'}``.
            Absent axes default to ``'millimeter'``.  If ``None``, all axes
            default to ``'millimeter'``.  When the supplied units differ from
            the units stored in the image, the coordinates are automatically
            converted before locating the patch center.

    Returns:
        Single ZarrNii instance (when centers is a single tuple) or list of
        ZarrNii instances (when centers is a list) with cropped data and
        updated spatial metadata. All patches will have exactly the shape
        specified by patch_size (plus any non-spatial dimensions).

    Raises:
        ValueError: If coordinates/dimensions are invalid, or if
            *centers_units* contains an unrecognised unit string
        IndexError: If patch_size dimensions don't match spatial dimensions

    Examples:
        >>> # Extract single 256x256x256 voxel patch at a coordinate (mm)
        >>> center = (50.0, 60.0, 70.0)  # physical coordinates in mm
        >>> patch = znii.crop_centered(center, patch_size=(256, 256, 256))
        >>>
        >>> # Extract patch with centers supplied in micrometers
        >>> center_um = (50000.0, 60000.0, 70000.0)
        >>> patch = znii.crop_centered(
        ...     center_um,
        ...     patch_size=(256, 256, 256),
        ...     centers_units={'x': 'micrometer', 'y': 'micrometer', 'z': 'micrometer'},
        ... )
        >>>
        >>> # Extract multiple patches for ML training
        >>> centers = [
        ...     (50.0, 60.0, 70.0),
        ...     (100.0, 110.0, 120.0),
        ...     (150.0, 160.0, 170.0)
        ... ]
        >>> patches = znii.crop_centered(centers, patch_size=(128, 128, 128))
        >>> # Returns list of 3 ZarrNii instances, all with shape (1, 128, 128, 128)
        >>>
        >>> # Use with atlas sampling for ML training workflow
        >>> centers = atlas.sample_region_patches(
        ...     n_patches=100,
        ...     region_ids="cortex",
        ...     seed=42
        ... )
        >>> patches = image.crop_centered(centers, patch_size=(256, 256, 256))
        >>>
        >>> # Use custom fill value for padding
        >>> patch = znii.crop_centered(center, patch_size=(256, 256, 256), fill_value=-1.0)

    Notes:
        - Centers are in physical/world coordinates, always in (x, y, z) order
        - By default centers are assumed to be in millimeters; use
          *centers_units* to supply coordinates in a different unit
        - patch_size is in voxels, in (x, y, z) order
        - The patch is centered at the given coordinate, extending ±patch_size/2
        - If patch_size is odd, the center voxel is included
        - Patches near boundaries are padded with fill_value to maintain size
        - All patches are guaranteed to have exactly the requested size
        - Useful for ML training where fixed patch sizes are required
        - Coordinates from atlas.sample_region_patches() can be used directly
    """
    _validate_axes_units(centers_units)

    # Check if this is batch processing (list of centers)
    is_batch = isinstance(centers, list)

    if is_batch:
        # Batch processing: recursively call crop_centered for each center
        return [
            self.crop_centered(
                center, patch_size, spatial_dims, fill_value, centers_units
            )
            for center in centers
        ]

    # Single center processing
    if spatial_dims is None:
        spatial_dims = (
            ["z", "y", "x"] if self.axes_order == "ZYX" else ["x", "y", "z"]
        )

    # Convert center from physical to voxel coordinates
    # Centers are always in (x, y, z) order
    # First convert from centers_units to the image's native units
    centers_converted = _convert_physical_coords_units(
        centers, centers_units, self.ngff_image.axes_units
    )
    center_phys = np.array(list(centers_converted) + [1.0])

    # Get inverse affine to convert from physical to voxel
    affine_inv = np.linalg.inv(self.get_affine_matrix(axes_order="XYZ"))

    # Transform to voxel coordinates
    center_voxel = affine_inv @ center_phys
    center_voxel_xyz = center_voxel[:3]

    # patch_size is in voxels, in (x, y, z) order
    patch_size_np = np.array(patch_size)
    half_patch = patch_size_np / 2.0

    # Calculate desired bounding box in voxel coordinates (may extend beyond image)
    voxel_min_xyz = center_voxel_xyz - half_patch
    voxel_max_xyz = center_voxel_xyz + half_patch

    # Round to nearest integer voxel indices
    voxel_min_xyz = np.round(voxel_min_xyz).astype(int)
    voxel_max_xyz = np.round(voxel_max_xyz).astype(int)

    # Ensure we get exactly the requested patch size
    # Adjust max to ensure patch_size is respected
    voxel_max_xyz = voxel_min_xyz + patch_size_np

    # Get image dimensions in voxel space
    # Map spatial dims to their indices
    spatial_dim_indices = {}
    for i, dim in enumerate(self.ngff_image.dims):
        if dim.lower() in [d.lower() for d in spatial_dims]:
            spatial_dim_indices[dim.lower()] = i

    image_shape_xyz = np.array(
        [
            self.ngff_image.data.shape[spatial_dim_indices["x"]],
            self.ngff_image.data.shape[spatial_dim_indices["y"]],
            self.ngff_image.data.shape[spatial_dim_indices["z"]],
        ]
    )

    # Calculate the actual crop region (clipped to image bounds)
    crop_min_xyz = np.maximum(voxel_min_xyz, 0)
    crop_max_xyz = np.minimum(voxel_max_xyz, image_shape_xyz)

    # Ensure crop_max >= crop_min to avoid empty arrays
    crop_max_xyz = np.maximum(crop_min_xyz, crop_max_xyz)

    # Calculate padding needed on each side
    pad_before_xyz = crop_min_xyz - voxel_min_xyz  # How much we're clipped at start
    pad_after_xyz = voxel_max_xyz - crop_max_xyz  # How much we're clipped at end

    # Check if the entire patch is outside the image bounds
    # This happens when crop_min >= crop_max in any dimension after clipping
    is_completely_outside = np.any(crop_min_xyz >= crop_max_xyz)

    if is_completely_outside:
        # The entire patch is outside the image bounds
        # Create a completely padded array with the fill value
        import dask.array as da

        # Build the full patch shape
        full_shape = []
        spatial_idx = 0
        for dim in self.ngff_image.dims:
            if dim.lower() in [d.lower() for d in spatial_dims]:
                full_shape.append(patch_size_np[spatial_idx])
                spatial_idx += 1
            else:
                # Non-spatial dimension - keep original size
                dim_idx = self.ngff_image.dims.index(dim)
                full_shape.append(self.ngff_image.data.shape[dim_idx])

        # Create array filled with fill_value
        padded_data = da.full(
            tuple(full_shape),
            fill_value,
            dtype=self.ngff_image.data.dtype,
            chunks=self.ngff_image.data.chunksize,
        )

        # Calculate translation for the patch center
        # The translation should be at voxel_min_xyz (the desired start of patch)
        new_translation = {}
        for dim in self.ngff_image.dims:
            if dim.lower() in [d.lower() for d in spatial_dims]:
                dim_lower = dim.lower()
                if dim_lower == "x":
                    voxel_start = voxel_min_xyz[0]
                elif dim_lower == "y":
                    voxel_start = voxel_min_xyz[1]
                elif dim_lower == "z":
                    voxel_start = voxel_min_xyz[2]
                else:
                    voxel_start = 0

                # Translation is voxel_start * scale + original translation
                new_translation[dim] = voxel_start * self.ngff_image.scale.get(
                    dim, 1.0
                ) + self.ngff_image.translation.get(dim, 0.0)
            elif dim in self.ngff_image.translation:
                new_translation[dim] = self.ngff_image.translation[dim]

        # Create NgffImage with the padded data
        padded_image = _derive_ngff_image(
            self.ngff_image,
            data=padded_data,
            scale=self.ngff_image.scale.copy(),
            translation=new_translation,
        )

        return ZarrNii(
            ngff_image=padded_image,
            axes_order=self.axes_order,
            xyz_orientation=self.xyz_orientation,
            _omero=self._omero,
        )

    # Create mapping from x,y,z to voxel coordinates for cropping
    bbox_vox_min = {
        "x": crop_min_xyz[0],
        "y": crop_min_xyz[1],
        "z": crop_min_xyz[2],
    }
    bbox_vox_max = {
        "x": crop_max_xyz[0],
        "y": crop_max_xyz[1],
        "z": crop_max_xyz[2],
    }

    dim_flips = _axcodes2flips(self.orientation)
    # Crop the actual image data that exists
    cropped_image = crop_ngff_image(
        self.ngff_image, bbox_vox_min, bbox_vox_max, dim_flips
    )

    # Check if padding is needed
    needs_padding = np.any(pad_before_xyz > 0) or np.any(pad_after_xyz > 0)

    if needs_padding:
        # Build padding specification for all dimensions
        pad_width = []
        spatial_idx = 0

        for dim in cropped_image.dims:
            if dim.lower() in [d.lower() for d in spatial_dims]:
                # Spatial dimension - may need padding
                dim_lower = dim.lower()
                if dim_lower == "x":
                    pad_width.append((pad_before_xyz[0], pad_after_xyz[0]))
                elif dim_lower == "y":
                    pad_width.append((pad_before_xyz[1], pad_after_xyz[1]))
                elif dim_lower == "z":
                    pad_width.append((pad_before_xyz[2], pad_after_xyz[2]))
                spatial_idx += 1
            else:
                # Non-spatial dimension - no padding
                pad_width.append((0, 0))

        # Apply padding
        import dask.array as da

        padded_data = da.pad(
            cropped_image.data,
            pad_width=pad_width,
            mode="constant",
            constant_values=fill_value,
        )

        # Adjust translation for the padding
        new_translation = cropped_image.translation.copy()

        for i, dim in enumerate(bbox_vox_min.keys()):
            new_translation[dim] = new_translation[dim] + dim_flips[
                dim
            ] * pad_before_xyz[i] * cropped_image.scale.get(dim, 1.0)

        # Create padded NgffImage
        cropped_image = _derive_ngff_image(
            cropped_image,
            data=padded_data,
            translation=new_translation,
        )

    return ZarrNii(
        ngff_image=cropped_image,
        axes_order=self.axes_order,
        xyz_orientation=self.xyz_orientation,
        _omero=self._omero,
    )

zarrnii.core.ZarrNii.downsample(factors=None, along_x=1, along_y=1, along_z=1, level=None, spatial_dims=None)

Reduce image resolution by downsampling.

Performs spatial downsampling by averaging blocks of voxels, effectively reducing image resolution and size. Multiple parameter options provide flexibility for different downsampling strategies.

Parameters:

• factors (Optional[Union[int, List[int]]], default: None ) –

  Downsampling factors for spatial dimensions. Can be: - int: Same factor applied to all spatial dimensions - List[int]: Per-dimension factors matching spatial_dims order - None: Use other parameters to determine factors

• along_x (int, default: 1 ) –

  Downsampling factor for X dimension (legacy parameter)

• along_y (int, default: 1 ) –

  Downsampling factor for Y dimension (legacy parameter)

• along_z (int, default: 1 ) –

  Downsampling factor for Z dimension (legacy parameter)

• level (Optional[int], default: None ) –

  Power-of-2 downsampling level (factors = 2^level). Takes precedence over along_* parameters

• spatial_dims (Optional[List[str]], default: None ) –

  Names of spatial dimensions. If None, derived from axes_order

Returns:

• 'ZarrNii' –

  New ZarrNii instance with downsampled data and updated metadata

Raises:

• ValueError –

  If conflicting parameters provided or invalid factors

Examples:

>>> # Isotropic downsampling by factor of 2
>>> downsampled = znii.downsample(factors=2)

>>> # Anisotropic downsampling
>>> downsampled = znii.downsample(factors=[1, 2, 2])

>>> # Using legacy parameters
>>> downsampled = znii.downsample(along_x=2, along_y=2, along_z=1)

>>> # Power-of-2 downsampling
>>> downsampled = znii.downsample(level=2)  # factors = 4

Notes

• Downsampling uses block averaging for anti-aliasing
• Spatial transformations are automatically scaled
• Non-spatial dimensions (channels, time) are preserved
• Original data remains unchanged (creates new instance)

Source code in zarrnii/core.py

def downsample(
    self,
    factors: Optional[Union[int, List[int]]] = None,
    along_x: int = 1,
    along_y: int = 1,
    along_z: int = 1,
    level: Optional[int] = None,
    spatial_dims: Optional[List[str]] = None,
) -> "ZarrNii":
    """Reduce image resolution by downsampling.

    Performs spatial downsampling by averaging blocks of voxels, effectively
    reducing image resolution and size. Multiple parameter options provide
    flexibility for different downsampling strategies.

    Args:
        factors: Downsampling factors for spatial dimensions. Can be:
            - int: Same factor applied to all spatial dimensions
            - List[int]: Per-dimension factors matching spatial_dims order
            - None: Use other parameters to determine factors
        along_x: Downsampling factor for X dimension (legacy parameter)
        along_y: Downsampling factor for Y dimension (legacy parameter)
        along_z: Downsampling factor for Z dimension (legacy parameter)
        level: Power-of-2 downsampling level (factors = 2^level).
            Takes precedence over along_* parameters
        spatial_dims: Names of spatial dimensions. If None, derived
            from axes_order

    Returns:
        New ZarrNii instance with downsampled data and updated metadata

    Raises:
        ValueError: If conflicting parameters provided or invalid factors

    Examples:
        >>> # Isotropic downsampling by factor of 2
        >>> downsampled = znii.downsample(factors=2)

        >>> # Anisotropic downsampling
        >>> downsampled = znii.downsample(factors=[1, 2, 2])

        >>> # Using legacy parameters
        >>> downsampled = znii.downsample(along_x=2, along_y=2, along_z=1)

        >>> # Power-of-2 downsampling
        >>> downsampled = znii.downsample(level=2)  # factors = 4

    Notes:
        - Downsampling uses block averaging for anti-aliasing
        - Spatial transformations are automatically scaled
        - Non-spatial dimensions (channels, time) are preserved
        - Original data remains unchanged (creates new instance)
    """
    # Handle legacy parameters
    if factors is None:
        if level is not None:
            factors = 2**level
        else:
            factors = (
                [along_z, along_y, along_x]
                if self.axes_order == "ZYX"
                else [along_x, along_y, along_z]
            )

    if spatial_dims is None:
        spatial_dims = (
            ["z", "y", "x"] if self.axes_order == "ZYX" else ["x", "y", "z"]
        )

    downsampled_image = downsample_ngff_image(
        self.ngff_image, factors, spatial_dims
    )
    return ZarrNii(
        ngff_image=downsampled_image,
        axes_order=self.axes_order,
        xyz_orientation=self.xyz_orientation,
        _omero=self._omero,
    )

zarrnii.core.ZarrNii.upsample(along_x=1, along_y=1, along_z=1, to_shape=None)

Upsamples the ZarrNii instance using scipy.ndimage.zoom.

Parameters:

• along_x (int, default: 1 ) –

  Upsampling factor along the X-axis (default: 1).

• along_y (int, default: 1 ) –

  Upsampling factor along the Y-axis (default: 1).

• along_z (int, default: 1 ) –

  Upsampling factor along the Z-axis (default: 1).

• to_shape (tuple, default: None ) –

  Target shape for upsampling. Should include all dimensions (e.g., (c, z, y, x) for ZYX or (c, x, y, z) for XYZ). If provided, along_x, along_y, and along_z are ignored.

Returns:

• ZarrNii –

  A new ZarrNii instance with the upsampled data and updated affine.

Notes

• This method supports both direct scaling via along_* factors or target shape via to_shape.
• If to_shape is provided, chunk sizes and scaling factors are dynamically calculated.
• The affine matrix is updated to reflect the new voxel size after upsampling.

Example

Upsample with scaling factors

upsampled_znimg = znimg.upsample(along_x=2, along_y=2, along_z=2)

Upsample to a specific shape

upsampled_znimg = znimg.upsample(to_shape=(1, 256, 256, 256))

Source code in zarrnii/core.py

def upsample(self, along_x=1, along_y=1, along_z=1, to_shape=None):
    """
    Upsamples the ZarrNii instance using `scipy.ndimage.zoom`.

    Parameters:
        along_x (int, optional): Upsampling factor along the X-axis (default: 1).
        along_y (int, optional): Upsampling factor along the Y-axis (default: 1).
        along_z (int, optional): Upsampling factor along the Z-axis (default: 1).
        to_shape (tuple, optional): Target shape for upsampling. Should include all dimensions
                                     (e.g., `(c, z, y, x)` for ZYX or `(c, x, y, z)` for XYZ).
                                     If provided, `along_x`, `along_y`, and `along_z` are ignored.

    Returns:
        ZarrNii: A new ZarrNii instance with the upsampled data and updated affine.

    Notes:
        - This method supports both direct scaling via `along_*` factors or target shape via `to_shape`.
        - If `to_shape` is provided, chunk sizes and scaling factors are dynamically calculated.
        - The affine matrix is updated to reflect the new voxel size after upsampling.

    Example:
        # Upsample with scaling factors
        upsampled_znimg = znimg.upsample(along_x=2, along_y=2, along_z=2)

        # Upsample to a specific shape
        upsampled_znimg = znimg.upsample(to_shape=(1, 256, 256, 256))
    """
    # Determine scaling and chunks based on input parameters
    if to_shape is None:
        if self.axes_order == "XYZ":
            scaling = (1, along_x, along_y, along_z)
        else:
            scaling = (1, along_z, along_y, along_x)

        chunks_out = tuple(
            tuple(c * scale for c in chunks_i)
            for chunks_i, scale in zip(self.data.chunks, scaling)
        )
    else:
        chunks_out, scaling = self.__get_upsampled_chunks(to_shape)

    # Define block-wise upsampling function
    def zoom_blocks(x, block_info=None):
        """
        Scales blocks to the desired size using `scipy.ndimage.zoom`.

        Parameters:
            x (np.ndarray): Input block data.
            block_info (dict, optional): Metadata about the current block.

        Returns:
            np.ndarray: The upscaled block.
        """
        # Calculate scaling factors based on input and output chunk shapes
        scaling = tuple(
            out_n / in_n
            for out_n, in_n in zip(block_info[None]["chunk-shape"], x.shape)
        )
        return zoom(x, scaling, order=1, prefilter=False)

    # Perform block-wise upsampling
    darr_scaled = da.map_blocks(
        zoom_blocks, self.data, dtype=self.data.dtype, chunks=chunks_out
    )

    # Update the affine matrix to reflect the new voxel size
    if self.axes_order == "XYZ":
        scaling_matrix = np.diag(
            (1 / scaling[1], 1 / scaling[2], 1 / scaling[3], 1)
        )
    else:
        scaling_matrix = np.diag(
            (1 / scaling[-1], 1 / scaling[-2], 1 / scaling[-3], 1)
        )

    # Create new NgffImage with upsampled data
    dims = self.dims

    # Build new_scale by updating only the spatial dimensions
    new_scale = self.scale.copy()

    # Find spatial dimension indices and update their scales
    for i, dim in enumerate(dims):
        if dim.lower() in ["x", "y", "z"]:
            if dim in self.scale:
                new_scale[dim] = self.scale[dim] / scaling[i]

    upsampled_ngff = nz.to_ngff_image(
        darr_scaled,
        dims=dims,
        scale=new_scale,
        translation=self.translation.copy(),
        name=self.name,
        axes_units=self.ngff_image.axes_units,
    )

    # Return a new ZarrNii instance with the upsampled data
    return ZarrNii.from_ngff_image(
        upsampled_ngff,
        axes_order=self.axes_order,
        xyz_orientation=self.xyz_orientation,
        omero=self.omero,
    )

zarrnii.core.ZarrNii.get_bounded_subregion(points)

Extracts a bounded subregion of the dask array containing the specified points, along with the grid points for interpolation.

If the points extend beyond the domain of the dask array, the extent is capped at the boundaries. If all points are outside the domain, the function returns (None, None).

Parameters:

• points (ndarray) –

  Nx3 or Nx4 array of coordinates in the array's space. If Nx4, the last column is assumed to be the homogeneous coordinate and is ignored.

Returns:

• tuple –

  grid_points (tuple): A tuple of three 1D arrays representing the grid points along each axis (X, Y, Z) in the subregion. subvol (np.ndarray or None): The extracted subregion as a NumPy array. Returns None if all points are outside the array domain.

Notes

• The function uses compute() on the dask array to immediately load the subregion, as Dask doesn't support the type of indexing required for interpolation.
• A padding of 1 voxel is applied around the extent of the points.

Example

grid_points, subvol = znimg.get_bounded_subregion(points) if subvol is not None: print("Subvolume shape:", subvol.shape)

Source code in zarrnii/core.py

def get_bounded_subregion(self, points: np.ndarray):
    """
    Extracts a bounded subregion of the dask array containing the specified points,
    along with the grid points for interpolation.

    If the points extend beyond the domain of the dask array, the extent is capped
    at the boundaries. If all points are outside the domain, the function returns
    `(None, None)`.

    Parameters:
        points (np.ndarray): Nx3 or Nx4 array of coordinates in the array's space.
                             If Nx4, the last column is assumed to be the homogeneous
                             coordinate and is ignored.

    Returns:
        tuple:
            grid_points (tuple): A tuple of three 1D arrays representing the grid
                                 points along each axis (X, Y, Z) in the subregion.
            subvol (np.ndarray or None): The extracted subregion as a NumPy array.
                                         Returns `None` if all points are outside
                                         the array domain.

    Notes:
        - The function uses `compute()` on the dask array to immediately load the
          subregion, as Dask doesn't support the type of indexing required for
          interpolation.
        - A padding of 1 voxel is applied around the extent of the points.

    Example:
        grid_points, subvol = znimg.get_bounded_subregion(points)
        if subvol is not None:
            print("Subvolume shape:", subvol.shape)
    """
    pad = 1  # Padding around the extent of the points

    # Compute the extent of the points in the array's coordinate space
    min_extent = np.floor(points.min(axis=1)[:3] - pad).astype("int")
    max_extent = np.ceil(points.max(axis=1)[:3] + pad).astype("int")

    # Clip the extents to ensure they stay within the bounds of the array
    clip_min = np.zeros_like(min_extent)
    clip_max = np.array(self.darr.shape[-3:])  # Z, Y, X dimensions

    min_extent = np.clip(min_extent, clip_min, clip_max)
    max_extent = np.clip(max_extent, clip_min, clip_max)

    # Check if all points are outside the domain
    if np.any(max_extent <= min_extent):
        return None, None

    # Extract the subvolume using the computed extents
    subvol = self.darr[
        :,
        min_extent[0] : max_extent[0],
        min_extent[1] : max_extent[1],
        min_extent[2] : max_extent[2],
    ].compute()

    # Generate grid points for interpolation
    grid_points = (
        np.arange(min_extent[0], max_extent[0]),  # Z
        np.arange(min_extent[1], max_extent[1]),  # Y
        np.arange(min_extent[2], max_extent[2]),  # X
    )

    return grid_points, subvol

zarrnii.core.ZarrNii.sample_at_points(xyz_points, method='linear', fill_value=0.0, points_units=None)

Block-aware interpolation of image values at physical-space query points.

Interpolates image values at the specified physical coordinates without loading the entire image into memory. For zarr-backed images the data is loaded chunk-by-chunk based on where the query points fall, making the function suitable for very large datasets.

Parameters:

• xyz_points (ndarray) –

  Query coordinates in physical space (x, y, z order). Shape can be (N, 3) or (3, N). A single point may also be passed as a length-3 1-D array.

• method (str, default: 'linear' ) –

  Interpolation method passed to scipy.interpolate.interpn. Supported values: 'linear' (default) and 'nearest'.

• fill_value (float, default: 0.0 ) –

  Value returned for query points that fall outside the image domain. Default 0.0.

• points_units (Optional[Dict[str, str]], default: None ) –

  Spatial units of the query points, expressed as a mapping of axis name to OME-Zarr unit string, e.g. {'x': 'millimeter', 'y': 'millimeter', 'z': 'millimeter'}. Absent axes default to 'millimeter'. If None, all axes default to 'millimeter'. When the supplied units differ from the units stored in the image, the query points are automatically converted before interpolation.

Returns:

• ndarray –

  np.ndarray: Interpolated values with shape (C, N) where C is

• ndarray –

  the number of image channels and N is the number of query points.

Raises:

• ValueError –

  If points_units contains an unrecognised unit string, or if the input array has an incompatible shape.

Notes

• By default query coordinates are assumed to be in millimeters; use points_units to supply coordinates in a different unit.
• When the image has no unit metadata (axes_units is None), its units are assumed to be millimeters for the purpose of conversion.
• For zarr-backed images only the minimal set of data blocks that cover the query points is loaded; the full array is never read into memory.
• For non-zarr-backed (in-memory / pure-dask) images the bounding box of all query points is computed and only that subregion is materialised via dask.compute().
• Points outside the image domain receive fill_value.

Examples:

>>> import numpy as np
>>> from zarrnii import ZarrNii
>>> znii = ZarrNii.from_ome_zarr("image.zarr")
>>> # Sample at three physical locations (mm, the default)
>>> pts = np.array([[0.0, 0.0, 0.0],
...                 [1.0, 1.0, 1.0],
...                 [2.0, 2.0, 2.0]])   # shape (3, 3)
>>> values = znii.sample_at_points(pts)   # shape (C, 3)
>>>
>>> # Same points supplied in micrometers
>>> pts_um = pts * 1000.0
>>> values = znii.sample_at_points(
...     pts_um,
...     points_units={'x': 'micrometer', 'y': 'micrometer', 'z': 'micrometer'},
... )

Source code in zarrnii/core.py

def sample_at_points(
    self,
    xyz_points: np.ndarray,
    method: str = "linear",
    fill_value: float = 0.0,
    points_units: Optional[Dict[str, str]] = None,
) -> np.ndarray:
    """Block-aware interpolation of image values at physical-space query points.

    Interpolates image values at the specified physical coordinates without
    loading the entire image into memory.  For zarr-backed images the data is
    loaded chunk-by-chunk based on where the query points fall, making the
    function suitable for very large datasets.

    Args:
        xyz_points: Query coordinates in physical space (x, y, z order).
            Shape can be ``(N, 3)`` or ``(3, N)``.  A single point may also
            be passed as a length-3 1-D array.
        method: Interpolation method passed to ``scipy.interpolate.interpn``.
            Supported values: ``'linear'`` (default) and ``'nearest'``.
        fill_value: Value returned for query points that fall outside the
            image domain.  Default ``0.0``.
        points_units: Spatial units of the query points, expressed as a
            mapping of axis name to OME-Zarr unit string, e.g.
            ``{'x': 'millimeter', 'y': 'millimeter', 'z': 'millimeter'}``.
            Absent axes default to ``'millimeter'``.  If ``None``, all axes
            default to ``'millimeter'``.  When the supplied units differ from
            the units stored in the image, the query points are automatically
            converted before interpolation.

    Returns:
        np.ndarray: Interpolated values with shape ``(C, N)`` where *C* is
        the number of image channels and *N* is the number of query points.

    Raises:
        ValueError: If *points_units* contains an unrecognised unit string,
            or if the input array has an incompatible shape.

    Notes:
        - By default query coordinates are assumed to be in millimeters; use
          *points_units* to supply coordinates in a different unit.
        - When the image has no unit metadata (``axes_units`` is ``None``),
          its units are assumed to be millimeters for the purpose of
          conversion.
        - For zarr-backed images only the minimal set of data blocks that
          cover the query points is loaded; the full array is never read into
          memory.
        - For non-zarr-backed (in-memory / pure-dask) images the bounding
          box of all query points is computed and only that subregion is
          materialised via ``dask.compute()``.
        - Points outside the image domain receive ``fill_value``.

    Examples:
        >>> import numpy as np
        >>> from zarrnii import ZarrNii
        >>> znii = ZarrNii.from_ome_zarr("image.zarr")
        >>> # Sample at three physical locations (mm, the default)
        >>> pts = np.array([[0.0, 0.0, 0.0],
        ...                 [1.0, 1.0, 1.0],
        ...                 [2.0, 2.0, 2.0]])   # shape (3, 3)
        >>> values = znii.sample_at_points(pts)   # shape (C, 3)
        >>>
        >>> # Same points supplied in micrometers
        >>> pts_um = pts * 1000.0
        >>> values = znii.sample_at_points(
        ...     pts_um,
        ...     points_units={'x': 'micrometer', 'y': 'micrometer', 'z': 'micrometer'},
        ... )
    """
    _validate_axes_units(points_units)

    # ---------------------------------------------------------------
    # 1. Normalize input to shape (N, 3), xyz order
    # ---------------------------------------------------------------
    xyz = np.asarray(xyz_points, dtype=np.float64)
    if xyz.ndim == 1:
        if xyz.shape[0] != 3:
            raise ValueError(
                f"1-D input must have exactly 3 elements (x, y, z), "
                f"got {xyz.shape[0]}"
            )
        xyz = xyz.reshape(1, 3)
    elif xyz.ndim == 2:
        if xyz.shape[1] == 3:
            pass  # already (N, 3)
        elif xyz.shape[0] == 3 and xyz.shape[1] != 3:
            xyz = xyz.T  # (3, N) → (N, 3)
        else:
            raise ValueError(
                f"2-D input must be (N, 3) or (3, N), got shape {xyz.shape}"
            )
    else:
        raise ValueError(f"Input must be a 1-D or 2-D array, got {xyz.ndim}-D")

    n_points = xyz.shape[0]
    n_channels = self.shape[0]

    # Allocate output (C, N) filled with fill_value
    results = np.full((n_channels, n_points), fill_value, dtype=np.float64)

    if n_points == 0:
        return results

    # ---------------------------------------------------------------
    # 1b. Convert points from points_units to image native units
    # ---------------------------------------------------------------
    xyz = _convert_physical_coords_units(
        xyz, points_units, self.ngff_image.axes_units
    )

    # ---------------------------------------------------------------
    # 2. Convert physical (x, y, z) → voxel coordinates in data order
    # ---------------------------------------------------------------
    # The XYZ affine maps (x, y, z) voxel indices → (x, y, z) physical.
    # Its inverse converts physical → XYZ voxel indices.
    affine_xyz = self.get_affine_matrix(axes_order="XYZ")
    affine_xyz_inv = np.linalg.inv(affine_xyz)

    xyz_homog = np.column_stack([xyz, np.ones(n_points)])  # (N, 4)
    vox_xyz = (xyz_homog @ affine_xyz_inv.T)[:, :3]  # (N, 3) XYZ

    # Convert to the data storage order (ZYX or XYZ)
    if self.axes_order == "ZYX":
        # Data array dims: (C, Z, Y, X) → query coords must be [z, y, x]
        vox_data = vox_xyz[:, ::-1].copy()  # (N, 3): [z, y, x]
    else:
        # Data array dims: (C, X, Y, Z) → query coords stay as [x, y, z]
        vox_data = vox_xyz.copy()

    spatial_shape = np.array(self.shape[1:], dtype=int)  # (Z, Y, X) or (X, Y, Z)

    # ---------------------------------------------------------------
    # 3. Block-aware loading: group points by zarr chunk
    # ---------------------------------------------------------------
    store_info = self.get_zarr_store_info()

    if store_info is not None:
        import zarr

        store_path = str(store_info["store_path"])
        dataset_path = store_info["dataset_path"]

        # Open the zarr store once and keep it open for all chunk reads
        if _is_ome_zarr_zip_path(store_path):
            _store = zarr.storage.ZipStore(store_path, mode="r")
            root = zarr.open_group(_store, mode="r")
        else:
            _store = None
            root = zarr.open_group(store_path, mode="r")

        try:
            arr = root[dataset_path]
            # chunk_shape for spatial dims only (skip the channel dim)
            chunk_shape = np.array(arr.chunks[1:], dtype=int)

            # Assign each point to the chunk it falls in
            chunk_indices = np.floor(vox_data / chunk_shape).astype(int)
            unique_chunks = np.unique(chunk_indices, axis=0)

            for chunk_idx in unique_chunks:
                mask = np.all(chunk_indices == chunk_idx, axis=1)
                chunk_points = vox_data[mask]  # (M, 3) in data order

                # Bounding box of this chunk's points + 1-voxel padding
                pad = 1
                min_ext = np.clip(
                    np.floor(chunk_points.min(axis=0) - pad).astype(int),
                    0,
                    spatial_shape,
                )
                max_ext = np.clip(
                    np.ceil(chunk_points.max(axis=0) + pad).astype(int),
                    0,
                    spatial_shape,
                )

                if np.any(max_ext <= min_ext):
                    # All points in this group are outside the image bounds
                    continue

                subvol = np.asarray(
                    arr[
                        :,
                        min_ext[0] : max_ext[0],
                        min_ext[1] : max_ext[1],
                        min_ext[2] : max_ext[2],
                    ]
                )

                grid = tuple(np.arange(min_ext[i], max_ext[i]) for i in range(3))

                for c in range(n_channels):
                    results[c, mask] = interpn(
                        grid,
                        subvol[c],
                        chunk_points,
                        method=method,
                        bounds_error=False,
                        fill_value=fill_value,
                    )

        finally:
            if _store is not None:
                _store.close()

    else:
        # ---------------------------------------------------------------
        # 4. Fallback: load only the bounding box of all query points
        # ---------------------------------------------------------------
        pad = 1
        min_ext = np.clip(
            np.floor(vox_data.min(axis=0) - pad).astype(int),
            0,
            spatial_shape,
        )
        max_ext = np.clip(
            np.ceil(vox_data.max(axis=0) + pad).astype(int),
            0,
            spatial_shape,
        )

        if np.any(max_ext <= min_ext):
            return results  # All points outside the image domain

        subvol = self.darr[
            :,
            min_ext[0] : max_ext[0],
            min_ext[1] : max_ext[1],
            min_ext[2] : max_ext[2],
        ].compute()

        grid = tuple(np.arange(min_ext[i], max_ext[i]) for i in range(3))

        for c in range(n_channels):
            results[c] = interpn(
                grid,
                subvol[c],
                vox_data,
                method=method,
                bounds_error=False,
                fill_value=fill_value,
            )

    return results

zarrnii.core.ZarrNii.apply_transform(*transforms, ref_znimg, spatial_dims=None)

Apply spatial transformations to image data.

Transforms the image data to align with a reference image space using the provided transformation(s). This enables registration, resampling, and coordinate system conversions.

Parameters:

• *transforms (Transform, default: () ) –

  Variable number of Transform objects to apply sequentially. Supported transform types: - AffineTransform: Linear transformations (rotation, scaling, translation) - DisplacementTransform: Non-linear deformation fields

• ref_znimg ('ZarrNii') –

  Reference ZarrNii image defining the target coordinate system, grid spacing, and field of view for the output

• spatial_dims (Optional[List[str]], default: None ) –

  Names of spatial dimensions for transformation. If None, automatically derived from axes_order

Returns:

• 'ZarrNii' –

  New ZarrNii instance with transformed data in reference space

Raises:

• ValueError –

  If no transforms provided or reference image incompatible

• TypeError –

  If transforms are not valid Transform objects

Examples:

>>> # Apply affine transformation
>>> affine = AffineTransform.from_txt("transform.txt")
>>> transformed = moving.apply_transform(affine, ref_znimg=reference)

>>> # Apply multiple transforms sequentially
>>> affine = AffineTransform.identity()
>>> warp = DisplacementTransform.from_nifti("warp.nii.gz")
>>> result = moving.apply_transform(affine, warp, ref_znimg=reference)

Notes

• Transformations are applied in the order specified
• Output data inherits spatial properties from ref_znimg
• Uses interpolation for non-integer coordinate mappings
• Non-spatial dimensions (channels, time) are preserved

Source code in zarrnii/core.py

def apply_transform(
    self,
    *transforms: Transform,
    ref_znimg: "ZarrNii",
    spatial_dims: Optional[List[str]] = None,
) -> "ZarrNii":
    """Apply spatial transformations to image data.

    Transforms the image data to align with a reference image space using
    the provided transformation(s). This enables registration, resampling,
    and coordinate system conversions.

    Args:
        *transforms: Variable number of Transform objects to apply sequentially.
            Supported transform types:
            - AffineTransform: Linear transformations (rotation, scaling, translation)
            - DisplacementTransform: Non-linear deformation fields
        ref_znimg: Reference ZarrNii image defining the target coordinate system,
            grid spacing, and field of view for the output
        spatial_dims: Names of spatial dimensions for transformation. If None,
            automatically derived from axes_order

    Returns:
        New ZarrNii instance with transformed data in reference space

    Raises:
        ValueError: If no transforms provided or reference image incompatible
        TypeError: If transforms are not valid Transform objects

    Examples:
        >>> # Apply affine transformation
        >>> affine = AffineTransform.from_txt("transform.txt")
        >>> transformed = moving.apply_transform(affine, ref_znimg=reference)

        >>> # Apply multiple transforms sequentially
        >>> affine = AffineTransform.identity()
        >>> warp = DisplacementTransform.from_nifti("warp.nii.gz")
        >>> result = moving.apply_transform(affine, warp, ref_znimg=reference)

    Notes:
        - Transformations are applied in the order specified
        - Output data inherits spatial properties from ref_znimg
        - Uses interpolation for non-integer coordinate mappings
        - Non-spatial dimensions (channels, time) are preserved
    """
    if spatial_dims is None:
        spatial_dims = (
            ["z", "y", "x"] if self.axes_order == "ZYX" else ["x", "y", "z"]
        )

    # Initialize the list of transformations to apply
    tfms_to_apply = [ref_znimg.affine]  # Start with the reference image affine

    # Append all transformations passed as arguments
    tfms_to_apply.extend(transforms)

    # Append the inverse of the current image's affine
    tfms_to_apply.append(self.affine.invert())

    interp_znimg = ref_znimg.copy(
        name=f"{self.name}_transformed_to_{ref_znimg.name}"
    )

    # Try to get zarr store information for direct access (avoids nested compute)
    store_info = self.get_zarr_store_info()

    # Lazily apply the transformations using dask
    if store_info is not None:
        # Use direct zarr access to avoid nested compute() calls
        interp_znimg.data = da.map_blocks(
            interp_by_block,  # Function to interpolate each block
            ref_znimg.data,  # Reference image data
            dtype=np.float32,  # Output data type
            transforms=tfms_to_apply,  # Transformations to apply
            flo_store_path=store_info["store_path"],
            flo_array_shape=store_info["array_shape"],
            flo_dataset_path=store_info["dataset_path"],
            flo_storage_options=None,  # TODO: Extract from dask array if available
        )
    else:
        # Fall back to passing ZarrNii instance (legacy behavior with nested compute)
        interp_znimg.data = da.map_blocks(
            interp_by_block,  # Function to interpolate each block
            ref_znimg.data,  # Reference image data
            dtype=np.float32,  # Output data type
            transforms=tfms_to_apply,  # Transformations to apply
            flo_znimg=self,  # Floating image to align (legacy)
        )

    return interp_znimg

zarrnii.core.ZarrNii.to_ome_zarr(store_or_path, max_layer=4, scale_factors=None, match_scale_factors_from=None, backend='ome-zarr-py', zarr_format=3, storage_options=None, **kwargs)

Save to OME-Zarr store with multiscale pyramid.

Creates an OME-Zarr dataset with automatic multiscale pyramid generation for efficient visualization and processing at multiple resolutions. Preserves spatial metadata and supports various storage backends.

Parameters:

• store_or_path (Union[str, Any]) –

  Target location for OME-Zarr store. Supports: - Local directory path - Remote URLs (s3://, gs://, etc.) - ZIP files (.zip extension for compressed storage) - Zarr store objects

• max_layer (int, default: 4 ) –

  Maximum number of pyramid levels to create (including level 0). Higher values create more downsampled levels

• scale_factors (Optional[Union[List[int], List[Dict[str, int]]]], default: None ) –

  Custom downsampling factors for each pyramid level. If None (default), automatically computes anisotropy-aware cumulative scale factors for the 'ome-zarr-py' backend: the first pyramid level corrects any voxel-size anisotropy by downsampling only the fine-resolution dimensions (using per-axis factors of 1 or a power of 2) so that all spatial dimensions reach the same coarsest resolution; subsequent levels then apply uniform 2× downsampling. For already-isotropic data, uniform 2× per level is used. For the 'ngff-zarr' backend the default remains powers of 2 [2, 4, 8, ...]. Pass a list of integers to downsample in xy only, or a list of dicts for explicit per-axis cumulative factors, e.g. [{"z": 1, "y": 2, "x": 2}, {"z": 2, "y": 4, "x": 4}].

• match_scale_factors_from (Optional[Union[str, Any]], default: None ) –

  Optional source file path (OME-Zarr or Imaris .ims) whose pyramid scale factors should be reused exactly. When set, scale_factors must be None and max_layer is set to match the source pyramid depth.

• backend (str, default: 'ome-zarr-py' ) –

  Backend library to use for writing. Options: - 'ngff-zarr': Use ngff-zarr library - 'ome-zarr-py': Use ome-zarr-py library for better dask integration (default)

• zarr_format (int, default: 3 ) –

  Zarr format version to use (2 or 3). Defaults to 3. Use 2 for backwards compatibility with tools that do not yet support Zarr v3 (e.g. older versions of napari). Only applies to the 'ome-zarr-py' backend.

• storage_options (Optional[Union[Dict[str, Any], List[Dict[str, Any]]]], default: None ) –

  Storage options passed to the zarr backend ('ome-zarr-py' backend only). A single dict applies to all pyramid levels; a list of dicts must match the number of pyramid levels. Common uses include sharding (zarr v3) and custom chunk sizes, e.g.::

  storage_options={"shards": (1, 64, 64, 64)}
  

• **kwargs (Any, default: {} ) –

  Additional arguments passed to the save function. For 'ngff-zarr': passed to to_ngff_zarr function For 'ome-zarr-py': passed to write_image (e.g., scaling_method, compute)

Returns:

• 'ZarrNii' –

  Self for method chaining

Raises:

• OSError –

  If unable to write to target location

• ValueError –

  If invalid scale_factors or backend provided

Examples:

>>> # Save with default pyramid levels (z+xy downsampled)
>>> znii.to_ome_zarr("/path/to/output.zarr")

>>> # Save with shards for cloud-optimised storage
>>> znii.to_ome_zarr(
...     "/path/to/output.zarr",
...     storage_options={"shards": (1, 64, 64, 64)},
... )

>>> # Save to compressed ZIP with custom pyramid
>>> znii.to_ome_zarr(
...     "/path/to/output.zarr.zip",
...     max_layer=3,
...     scale_factors=[2, 4]
... )

>>> # Use a specific downsampling method
>>> znii.to_ome_zarr(
...     "/path/to/output.zarr",
...     scaling_method="nearest"
... )

>>> # Chain with other operations
>>> result = (znii.downsample(2)
...               .crop((0,0,0), (100,100,100))
...               .to_ome_zarr("processed.zarr"))

Notes

• OME-Zarr files are always saved in ZYX axis order
• Automatic axis reordering if current order is XYZ
• Spatial transformations and metadata are preserved
• Orientation information is stored using the new 'xyz_orientation' metadata key for consistency and future compatibility
• The 'ome-zarr-py' backend provides better performance with dask and dask distributed workflows

Source code in zarrnii/core.py

def to_ome_zarr(
    self,
    store_or_path: Union[str, Any],
    max_layer: int = 4,
    scale_factors: Optional[Union[List[int], List[Dict[str, int]]]] = None,
    match_scale_factors_from: Optional[Union[str, Any]] = None,
    backend: str = "ome-zarr-py",
    zarr_format: int = 3,
    storage_options: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = None,
    **kwargs: Any,
) -> "ZarrNii":
    """Save to OME-Zarr store with multiscale pyramid.

    Creates an OME-Zarr dataset with automatic multiscale pyramid generation
    for efficient visualization and processing at multiple resolutions.
    Preserves spatial metadata and supports various storage backends.

    Args:
        store_or_path: Target location for OME-Zarr store. Supports:
            - Local directory path
            - Remote URLs (s3://, gs://, etc.)
            - ZIP files (.zip extension for compressed storage)
            - Zarr store objects
        max_layer: Maximum number of pyramid levels to create (including level 0).
            Higher values create more downsampled levels
        scale_factors: Custom downsampling factors for each pyramid level.
            If None (default), automatically computes anisotropy-aware
            cumulative scale factors for the ``'ome-zarr-py'`` backend:
            the first pyramid level corrects any voxel-size anisotropy by
            downsampling only the fine-resolution dimensions (using per-axis
            factors of 1 or a power of 2) so that all spatial dimensions
            reach the same coarsest resolution; subsequent levels then apply
            uniform 2× downsampling.  For already-isotropic data, uniform
            2× per level is used.  For the ``'ngff-zarr'`` backend the
            default remains powers of 2 ``[2, 4, 8, ...]``.
            Pass a list of integers to downsample in xy only, or a list of
            dicts for explicit per-axis cumulative factors, e.g.
            ``[{"z": 1, "y": 2, "x": 2}, {"z": 2, "y": 4, "x": 4}]``.
        match_scale_factors_from: Optional source file path (OME-Zarr or
            Imaris ``.ims``) whose pyramid scale factors should be reused
            exactly. When set, ``scale_factors`` must be ``None`` and
            ``max_layer`` is set to match the source pyramid depth.
        backend: Backend library to use for writing. Options:
            - 'ngff-zarr': Use ngff-zarr library
            - 'ome-zarr-py': Use ome-zarr-py library for better dask
              integration (default)
        zarr_format: Zarr format version to use (2 or 3). Defaults to 3.
            Use 2 for backwards compatibility with tools that do not yet
            support Zarr v3 (e.g. older versions of napari).
            Only applies to the 'ome-zarr-py' backend.
        storage_options: Storage options passed to the zarr backend
            (``'ome-zarr-py'`` backend only).  A single dict applies to all
            pyramid levels; a list of dicts must match the number of pyramid
            levels.  Common uses include sharding (zarr v3) and custom chunk
            sizes, e.g.::

                storage_options={"shards": (1, 64, 64, 64)}

        **kwargs: Additional arguments passed to the save function.
            For 'ngff-zarr': passed to to_ngff_zarr function
            For 'ome-zarr-py': passed to write_image (e.g., scaling_method,
            compute)

    Returns:
        Self for method chaining

    Raises:
        OSError: If unable to write to target location
        ValueError: If invalid scale_factors or backend provided

    Examples:
        >>> # Save with default pyramid levels (z+xy downsampled)
        >>> znii.to_ome_zarr("/path/to/output.zarr")

        >>> # Save with shards for cloud-optimised storage
        >>> znii.to_ome_zarr(
        ...     "/path/to/output.zarr",
        ...     storage_options={"shards": (1, 64, 64, 64)},
        ... )

        >>> # Save to compressed ZIP with custom pyramid
        >>> znii.to_ome_zarr(
        ...     "/path/to/output.zarr.zip",
        ...     max_layer=3,
        ...     scale_factors=[2, 4]
        ... )

        >>> # Use a specific downsampling method
        >>> znii.to_ome_zarr(
        ...     "/path/to/output.zarr",
        ...     scaling_method="nearest"
        ... )

        >>> # Chain with other operations
        >>> result = (znii.downsample(2)
        ...               .crop((0,0,0), (100,100,100))
        ...               .to_ome_zarr("processed.zarr"))

    Notes:
        - OME-Zarr files are always saved in ZYX axis order
        - Automatic axis reordering if current order is XYZ
        - Spatial transformations and metadata are preserved
        - Orientation information is stored using the new 'xyz_orientation'
          metadata key for consistency and future compatibility
        - The 'ome-zarr-py' backend provides better performance with dask
          and dask distributed workflows
    """
    # Validate backend parameter
    if backend not in ["ngff-zarr", "ome-zarr-py"]:
        raise ValueError(
            f"Invalid backend '{backend}'. Must be 'ngff-zarr' or 'ome-zarr-py'"
        )

    if match_scale_factors_from is not None:
        if scale_factors is not None:
            raise ValueError(
                "Cannot specify both 'scale_factors' and "
                "'match_scale_factors_from'."
            )

        # Derive scale factors from source level shapes
        level_shapes = _get_level_zyx_shapes_from_file(match_scale_factors_from)
        scale_factors = _compute_scale_factors_from_shapes(level_shapes)
        max_layer = len(scale_factors) + 1

    # Determine the image to save
    if self.axes_order == "XYZ":
        # Need to reorder data from XYZ to ZYX for OME-Zarr
        ngff_image_to_save = self._create_zyx_ngff_image()
    else:
        # Already in ZYX order
        ngff_image_to_save = self.ngff_image

    # Use the appropriate save function based on backend
    if backend == "ngff-zarr":
        save_ngff_image(
            ngff_image_to_save,
            store_or_path,
            max_layer,
            scale_factors,
            xyz_orientation=(
                self.xyz_orientation if hasattr(self, "xyz_orientation") else None
            ),
            **kwargs,
        )
    elif backend == "ome-zarr-py":
        save_ngff_image_with_ome_zarr(
            ngff_image_to_save,
            store_or_path,
            max_layer,
            scale_factors,
            omero=self._omero,
            xyz_orientation=(
                self.xyz_orientation if hasattr(self, "xyz_orientation") else None
            ),
            zarr_format=zarr_format,
            storage_options=storage_options,
            **kwargs,
        )

    # Add orientation metadata to the zarr store (only for non-ZIP files)
    # For OME-Zarr zip files, orientation is handled inside save_ngff_image
    if not (
        isinstance(store_or_path, str) and _is_ome_zarr_zip_path(store_or_path)
    ):
        try:
            import zarr

            if isinstance(store_or_path, str):
                group = zarr.open_group(store_or_path, mode="r+")
            else:
                group = zarr.open_group(store_or_path, mode="r+")

            # Add metadata for xyz_orientation (new format)
            if hasattr(self, "xyz_orientation") and self.xyz_orientation:
                group.attrs["xyz_orientation"] = self.xyz_orientation
        except Exception:
            # If we can't write orientation metadata, that's not critical
            pass

    return self

zarrnii.core.ZarrNii.to_nifti(filename=None, convert_units_to_mm=True)

Convert to NIfTI format with automatic dimension handling.

Converts the ZarrNii image to NIfTI-1 format, handling dimension reordering, singleton dimension removal, and spatial transformation conversion. NIfTI files are always written in XYZ axis order.

For multi-channel data, the 4th dimension is used for channels (XYZC), and channel labels are preserved in NIfTI header extensions.

Parameters:

• filename (Optional[Union[str, bytes]], default: None ) –

  Output file path for saving. Supported extensions: - .nii: Uncompressed NIfTI - .nii.gz: Compressed NIfTI (recommended) If None, returns nibabel image object without saving

• convert_units_to_mm (bool, default: True ) –

  If True (default), converts spatial units to millimeters. If False, preserves the original units from the OME-Zarr metadata. Supported source units: meter, micrometer, millimeter, nanometer.

Returns:

• Union[Nifti1Image, str] –

  If filename is None: nibabel.Nifti1Image object

• Union[Nifti1Image, str] –

  If filename provided: path to saved file

Raises:

• ValueError –

  If data has non-singleton time dimension (time is not supported in NIfTI output, but multiple channels are supported)

• OSError –

  If unable to write to specified filename

Notes

• Automatically reorders data from ZYX to XYZ if necessary
• Removes singleton time dimensions automatically
• Supports multi-channel data via 4th dimension (XYZC ordering)
• Channel labels are saved in NIfTI header extensions as JSON
• Spatial transformations are converted to NIfTI affine format
• By default, converts spatial units to millimeters (NIfTI standard)
• Sets NIfTI header xyzt_units appropriately

Examples:

>>> # Save to compressed NIfTI file with units in mm (default)
>>> znii.to_nifti("output.nii.gz")

>>> # Get nibabel object without saving
>>> nifti_img = znii.to_nifti()
>>> print(nifti_img.shape)

>>> # Preserve original units (e.g., micrometers)
>>> znii.to_nifti("output.nii.gz", convert_units_to_mm=False)

>>> # Save multi-channel data with channel labels preserved
>>> znii.to_nifti("multichannel.nii.gz")
>>> # Channel labels are automatically saved in header extensions

>>> # Select specific channels before saving
>>> znii.select_channels([0, 2]).to_nifti("selected.nii.gz")

Source code in zarrnii/core.py

def to_nifti(
    self,
    filename: Optional[Union[str, bytes]] = None,
    convert_units_to_mm: bool = True,
) -> Union[nib.Nifti1Image, str]:
    """Convert to NIfTI format with automatic dimension handling.

    Converts the ZarrNii image to NIfTI-1 format, handling dimension
    reordering, singleton dimension removal, and spatial transformation
    conversion. NIfTI files are always written in XYZ axis order.

    For multi-channel data, the 4th dimension is used for channels (XYZC),
    and channel labels are preserved in NIfTI header extensions.

    Args:
        filename: Output file path for saving. Supported extensions:
            - .nii: Uncompressed NIfTI
            - .nii.gz: Compressed NIfTI (recommended)
            If None, returns nibabel image object without saving
        convert_units_to_mm: If True (default), converts spatial units to
            millimeters. If False, preserves the original units from the
            OME-Zarr metadata. Supported source units: meter, micrometer,
            millimeter, nanometer.

    Returns:
        If filename is None: nibabel.Nifti1Image object
        If filename provided: path to saved file

    Raises:
        ValueError: If data has non-singleton time dimension (time is not
            supported in NIfTI output, but multiple channels are supported)
        OSError: If unable to write to specified filename

    Notes:
        - Automatically reorders data from ZYX to XYZ if necessary
        - Removes singleton time dimensions automatically
        - Supports multi-channel data via 4th dimension (XYZC ordering)
        - Channel labels are saved in NIfTI header extensions as JSON
        - Spatial transformations are converted to NIfTI affine format
        - By default, converts spatial units to millimeters (NIfTI standard)
        - Sets NIfTI header xyzt_units appropriately

    Examples:
        >>> # Save to compressed NIfTI file with units in mm (default)
        >>> znii.to_nifti("output.nii.gz")

        >>> # Get nibabel object without saving
        >>> nifti_img = znii.to_nifti()
        >>> print(nifti_img.shape)

        >>> # Preserve original units (e.g., micrometers)
        >>> znii.to_nifti("output.nii.gz", convert_units_to_mm=False)

        >>> # Save multi-channel data with channel labels preserved
        >>> znii.to_nifti("multichannel.nii.gz")
        >>> # Channel labels are automatically saved in header extensions

        >>> # Select specific channels before saving
        >>> znii.select_channels([0, 2]).to_nifti("selected.nii.gz")

    Warnings:
        Large images will be computed in memory during conversion.
        Consider downsampling or cropping first for very large datasets.
    """
    # Get data and dimensions
    data = self.data.compute()

    dims = self.dims

    # Handle dimensional reduction for NIfTI compatibility
    # NIfTI supports up to 4D, and we use 4th dimension for channels (XYZC)
    squeeze_axes = []
    new_dims = []

    for i, dim in enumerate(dims):
        if dim == "t" and data.shape[i] == 1:
            # Remove singleton time dimension
            squeeze_axes.append(i)
        elif dim == "t" and data.shape[i] > 1:
            # Non-singleton time dimension - not supported
            raise ValueError(
                f"NIfTI format doesn't support non-singleton time dimension. "
                f"Dimension 't' has size {data.shape[i]}. "
                f"Consider selecting a specific timepoint first."
            )
        elif dim == "c" and data.shape[i] == 1:
            # Singleton channel - can be squeezed
            squeeze_axes.append(i)
            # Don't add to new_dims
        else:
            # Keep this dimension (spatial or multi-channel)
            new_dims.append(dim)

    # Squeeze out singleton dimensions
    if squeeze_axes:
        data = np.squeeze(data, axis=tuple(squeeze_axes))

    # Check final dimensionality
    if data.ndim > 4:
        raise ValueError(
            f"Resulting data has {data.ndim} dimensions, but NIfTI supports maximum 4D"
        )

    # Now handle spatial reordering based on axes_order
    # We need to reorder to XYZC for NIfTI (or XYZ for 3D)
    if self.axes_order == "ZYX":
        # Data spatial dimensions are in ZYX order, need to transpose to XYZ
        if data.ndim == 3:
            # Pure spatial data: ZYX -> XYZ
            data = data.transpose(2, 1, 0)
        elif data.ndim == 4:
            # Check what the dimension order is
            if new_dims == ["c", "z", "y", "x"]:
                # CZYX -> XYZC
                data = data.transpose(3, 2, 1, 0)
            elif new_dims == ["z", "y", "x", "c"]:
                # ZYXC -> XYZC
                data = data.transpose(2, 1, 0, 3)
            else:
                # Fallback: assume CZYX
                data = data.transpose(3, 2, 1, 0)

        # Get affine matrix in XYZ order
        affine_matrix = self.get_affine_matrix(axes_order="XYZ")
    else:
        # Data is in XYZ order
        if data.ndim == 3:
            # Pure spatial data: XYZ (no change needed)
            pass
        elif data.ndim == 4:
            # Check what the dimension order is
            if new_dims == ["c", "x", "y", "z"]:
                # CXYZ -> XYZC
                data = data.transpose(1, 2, 3, 0)
            elif new_dims == ["x", "y", "z", "c"]:
                # XYZC -> XYZC (already correct!)
                pass
            else:
                # Fallback: assume CXYZ
                data = data.transpose(1, 2, 3, 0)

        affine_matrix = self.get_affine_matrix(axes_order="XYZ")

    # Handle unit conversion if requested
    # Get the spatial units from axes metadata (common for both branches)
    axes = self.axes
    spatial_axes = [ax for ax in axes if ax.get("type") == "space"]
    source_unit = "micrometer"  # Default

    if spatial_axes:
        source_unit = spatial_axes[0].get("unit", "micrometer")
        # Handle None case (default to micrometer)
        if source_unit is None:
            source_unit = "micrometer"

    output_spatial_unit = "mm"  # Default output unit for NIfTI

    if convert_units_to_mm:
        # Only convert if the source unit is not already millimeters
        if source_unit.lower() not in ["millimeter", "mm"]:
            # Convert spatial scale in affine matrix
            conversion_factor = _convert_spatial_unit_to_mm(1.0, source_unit)

            # Scale the spatial components of the affine matrix
            # The first 3 columns of the first 3 rows contain the spatial scaling/rotation
            affine_matrix[:3, :3] *= conversion_factor
            # The translation component (last column, first 3 rows) also needs conversion
            affine_matrix[:3, 3] *= conversion_factor
    else:
        # Preserve original units
        output_spatial_unit = _get_nifti_spatial_unit_code(source_unit)

    # Create NIfTI image
    nifti_img = nib.Nifti1Image(data, affine_matrix)

    # Set the spatial units in the NIfTI header
    try:
        # Set spatial units; time unit defaults to 'unknown'
        nifti_img.header.set_xyzt_units(output_spatial_unit, "unknown")
    except Exception:
        # If setting units fails, it's not critical
        pass

    # Add channel labels to NIfTI header extensions if available
    channel_labels = self.list_channels()
    if channel_labels and len(channel_labels) > 0 and data.ndim == 4:
        # Only add channel labels if we have multi-channel 4D data
        import json

        channel_metadata = {"channel_labels": channel_labels}
        ext = nib.nifti1.Nifti1Extension(
            1,
            json.dumps(channel_metadata).encode(
                "utf-8"
            ),  # code 1 is reserved/unspecified in NIfTI standard, suitable for custom metadata
        )
        nifti_img.header.extensions.append(ext)

    if filename is not None:
        nib.save(nifti_img, filename)
        return filename
    else:
        return nifti_img

zarrnii.core.ZarrNii.to_tiff_stack(filename_pattern, channel=None, timepoint=None, compress=True, dtype='uint16', rescale=True)

Save data as a stack of 2D TIFF images.

Saves the image data as a series of 2D TIFF files, with each Z-slice saved as a separate file. This format is useful for compatibility with tools that don't support OME-Zarr or napari plugins that require individual TIFF files.

Parameters:

• filename_pattern (str) –

  Output filename pattern. Should contain '{z:04d}' or similar format specifier for the Z-slice number. Examples: - "output_z{z:04d}.tif" - "data/slice_{z:03d}.tiff" If pattern doesn't contain format specifier, '_{z:04d}' is appended before the extension.

• channel (Optional[int], default: None ) –

  Channel index to save (0-based). If None and data has multiple channels, all channels will be saved as separate channel dimensions in each TIFF file (multi-channel TIFFs).

• timepoint (Optional[int], default: None ) –

  Timepoint index to save (0-based). If None and data has multiple timepoints, raises ValueError (must select single timepoint).

• compress (bool, default: True ) –

  Whether to use LZW compression (default: True)

• dtype (Optional[str], default: 'uint16' ) –

  Output data type for TIFF files. Options: - 'uint8': 8-bit unsigned integer (0-255) - 'uint16': 16-bit unsigned integer (0-65535) [default] - 'int16': 16-bit signed integer (-32768 to 32767) - 'float32': 32-bit float (preserves original data) Default 'uint16' provides good range and compatibility.

• rescale (bool, default: True ) –

  Whether to rescale data to fit the output dtype range. If True, data is linearly scaled from [min, max] to the full range of the output dtype. If False, data is clipped to the output dtype range. Default: True

Returns:

• str –

  Base directory path where files were saved

Raises:

• ValueError –

  If data has multiple timepoints but none selected, or if selected channel/timepoint is out of range, or if dtype is not supported

• OSError –

  If unable to write to specified directory

Examples:

>>> # Save as 16-bit with auto-rescaling (default, recommended)
>>> znii.to_tiff_stack("output_z{z:04d}.tif")

>>> # Save as 8-bit for smaller file sizes
>>> znii.to_tiff_stack("output_z{z:04d}.tif", dtype='uint8')

>>> # Save specific channel without rescaling
>>> znii.to_tiff_stack("channel0_z{z:04d}.tif", channel=0, rescale=False)

>>> # Save as float32 to preserve original precision
>>> znii.to_tiff_stack("precise_z{z:04d}.tif", dtype='float32')

Notes

• Z-dimension becomes the stack (file) dimension
• Time and channel dimensions are handled as specified
• Spatial transformations are not preserved in TIFF format
• For 5D data (T,C,Z,Y,X), you must select a single timepoint
• Multi-channel data can be saved as multi-channel TIFFs or selected
• Data type conversion helps ensure compatibility with analysis tools
• uint16 is recommended for most scientific applications (good range + compatibility)

Source code in zarrnii/core.py

def to_tiff_stack(
    self,
    filename_pattern: str,
    channel: Optional[int] = None,
    timepoint: Optional[int] = None,
    compress: bool = True,
    dtype: Optional[str] = "uint16",
    rescale: bool = True,
) -> str:
    """Save data as a stack of 2D TIFF images.

    Saves the image data as a series of 2D TIFF files, with each Z-slice
    saved as a separate file. This format is useful for compatibility with
    tools that don't support OME-Zarr or napari plugins that require
    individual TIFF files.

    Args:
        filename_pattern: Output filename pattern. Should contain '{z:04d}' or similar
            format specifier for the Z-slice number. Examples:
            - "output_z{z:04d}.tif"
            - "data/slice_{z:03d}.tiff"
            If pattern doesn't contain format specifier, '_{z:04d}' is appended
            before the extension.
        channel: Channel index to save (0-based). If None and data has multiple
            channels, all channels will be saved as separate channel dimensions
            in each TIFF file (multi-channel TIFFs).
        timepoint: Timepoint index to save (0-based). If None and data has multiple
            timepoints, raises ValueError (must select single timepoint).
        compress: Whether to use LZW compression (default: True)
        dtype: Output data type for TIFF files. Options:
            - 'uint8': 8-bit unsigned integer (0-255)
            - 'uint16': 16-bit unsigned integer (0-65535) [default]
            - 'int16': 16-bit signed integer (-32768 to 32767)
            - 'float32': 32-bit float (preserves original data)
            Default 'uint16' provides good range and compatibility.
        rescale: Whether to rescale data to fit the output dtype range.
            If True, data is linearly scaled from [min, max] to the full
            range of the output dtype. If False, data is clipped to the
            output dtype range. Default: True

    Returns:
        Base directory path where files were saved

    Raises:
        ValueError: If data has multiple timepoints but none selected,
            or if selected channel/timepoint is out of range,
            or if dtype is not supported
        OSError: If unable to write to specified directory

    Examples:
        >>> # Save as 16-bit with auto-rescaling (default, recommended)
        >>> znii.to_tiff_stack("output_z{z:04d}.tif")

        >>> # Save as 8-bit for smaller file sizes
        >>> znii.to_tiff_stack("output_z{z:04d}.tif", dtype='uint8')

        >>> # Save specific channel without rescaling
        >>> znii.to_tiff_stack("channel0_z{z:04d}.tif", channel=0, rescale=False)

        >>> # Save as float32 to preserve original precision
        >>> znii.to_tiff_stack("precise_z{z:04d}.tif", dtype='float32')

    Warnings:
        This method loads all data into memory. For large datasets,
        consider cropping or downsampling first to reduce memory usage.
        The cellseg3d napari plugin and similar tools work best with
        cropped regions rather than full-resolution whole-brain images.

    Notes:
        - Z-dimension becomes the stack (file) dimension
        - Time and channel dimensions are handled as specified
        - Spatial transformations are not preserved in TIFF format
        - For 5D data (T,C,Z,Y,X), you must select a single timepoint
        - Multi-channel data can be saved as multi-channel TIFFs or selected
        - Data type conversion helps ensure compatibility with analysis tools
        - uint16 is recommended for most scientific applications (good range + compatibility)
    """
    try:
        import tifffile
    except ImportError:
        raise ImportError(
            "tifffile is required for TIFF stack support. "
            "Install with: pip install tifffile"
        )

    # Get data and dimensions
    data = self.data.compute()
    dims = self.dims

    # Create output directory if needed
    import os

    output_dir = os.path.dirname(filename_pattern)
    if output_dir and not os.path.exists(output_dir):
        os.makedirs(output_dir)

    # Handle dimensional selection and validation
    # Remove singleton dimensions first, similar to to_nifti
    squeeze_axes = []
    remaining_dims = []
    time_dim_size = 1
    channel_dim_size = 1

    for i, dim in enumerate(dims):
        if dim == "t":
            time_dim_size = data.shape[i]
            if data.shape[i] == 1:
                squeeze_axes.append(i)
            elif timepoint is None:
                raise ValueError(
                    f"Data has {data.shape[i]} timepoints. "
                    f"Must specify 'timepoint' parameter to select a single timepoint."
                )
            elif timepoint >= data.shape[i]:
                raise ValueError(
                    f"Timepoint {timepoint} is out of range (data has {data.shape[i]} timepoints)"
                )
            else:
                remaining_dims.append(dim)
        elif dim == "c":
            channel_dim_size = data.shape[i]
            if data.shape[i] == 1:
                squeeze_axes.append(i)
            elif channel is None:
                raise ValueError(
                    f"Data has {data.shape[i]} channels. "
                    f"Must specify 'channel' parameter to select a single channel."
                )
            elif channel >= data.shape[i]:
                raise ValueError(
                    f"Channel {channel} is out of range (data has {data.shape[i]} channels)"
                )
            else:
                remaining_dims.append(dim)
        else:
            remaining_dims.append(dim)

    # Select specific timepoint if needed
    if time_dim_size > 1 and timepoint is not None:
        time_axis = dims.index("t")
        data = np.take(data, timepoint, axis=time_axis)
        # Update dims list
        dims = [d for i, d in enumerate(dims) if i != time_axis]

    # Select specific channel if needed
    if channel_dim_size > 1 and channel is not None:
        channel_axis = dims.index("c")
        data = np.take(data, channel, axis=channel_axis)
        # Update dims list
        dims = [d for i, d in enumerate(dims) if i != channel_axis]

    # Squeeze singleton dimensions
    if squeeze_axes:
        # Recalculate squeeze axes after potential dimension removal
        current_squeeze_axes = []
        for axis in squeeze_axes:
            # Count how many axes were removed before this one
            removed_before = sum(
                1
                for removed_axis in [
                    (
                        dims.index("t")
                        if time_dim_size > 1 and timepoint is not None
                        else -1
                    ),
                    (
                        dims.index("c")
                        if channel_dim_size > 1 and channel is not None
                        else -1
                    ),
                ]
                if removed_axis != -1 and removed_axis < axis
            )
            current_squeeze_axes.append(axis - removed_before)

        data = np.squeeze(data, axis=tuple(current_squeeze_axes))
        dims = [dim for i, dim in enumerate(dims) if i not in current_squeeze_axes]

    # Find Z dimension for stacking
    if "z" not in dims:
        raise ValueError("Data must have a Z dimension for TIFF stack export")

    z_axis = dims.index("z")
    z_size = data.shape[z_axis]

    # Check filename pattern contains format specifier
    if "{z" not in filename_pattern:
        # Add default z format before extension
        name, ext = os.path.splitext(filename_pattern)
        filename_pattern = f"{name}_{{z:04d}}{ext}"

    # Move Z axis to first position for easy iteration
    axes_order = list(range(data.ndim))
    axes_order[0], axes_order[z_axis] = axes_order[z_axis], axes_order[0]
    data = data.transpose(axes_order)

    # Handle data type conversion and rescaling
    supported_dtypes = {
        "uint8": np.uint8,
        "uint16": np.uint16,
        "int16": np.int16,
        "float32": np.float32,
    }

    if dtype not in supported_dtypes:
        raise ValueError(
            f"Unsupported dtype '{dtype}'. Supported types: {list(supported_dtypes.keys())}"
        )

    target_dtype = supported_dtypes[dtype]

    if rescale and dtype != "float32":
        # Get the data range
        data_min = np.min(data)
        data_max = np.max(data)

        if data_min == data_max:
            # Handle constant data case
            data_scaled = np.zeros_like(data, dtype=target_dtype)
        else:
            # Get target range for the dtype
            if dtype == "uint8":
                target_min, target_max = 0, 255
            elif dtype == "uint16":
                target_min, target_max = 0, 65535
            elif dtype == "int16":
                target_min, target_max = -32768, 32767

            # Convert data to float to avoid overflow during rescaling
            # Linear rescaling formula:
            # new_value = (value - data_min) * (target_max - target_min)
            #             / (data_max - data_min) + target_min
            data_float = data.astype(np.float64)
            data_scaled = (
                (data_float - data_min)
                * (target_max - target_min)
                / (data_max - data_min)
                + target_min
            ).astype(target_dtype)

        print(
            f"Rescaled data from [{data_min:.3f}, {data_max:.3f}] to {dtype} range"
        )
    else:
        # No rescaling - just clip and convert
        if dtype == "uint8":
            data_scaled = np.clip(data, 0, 255).astype(target_dtype)
        elif dtype == "uint16":
            data_scaled = np.clip(data, 0, 65535).astype(target_dtype)
        elif dtype == "int16":
            data_scaled = np.clip(data, -32768, 32767).astype(target_dtype)
        else:  # float32
            data_scaled = data.astype(target_dtype)

        if dtype != "float32":
            print(f"Converted data to {dtype} with clipping (no rescaling)")

    data = data_scaled

    # Save each Z-slice as a separate TIFF file
    compression = "lzw" if compress else None
    saved_files = []

    for z_idx in range(z_size):
        slice_data = data[z_idx]

        # Generate filename for this slice
        filename = filename_pattern.format(z=z_idx)

        # Save the 2D slice
        tifffile.imwrite(filename, slice_data, compression=compression)
        saved_files.append(filename)

    print(f"Saved {len(saved_files)} TIFF files to {output_dir or '.'}")
    print(
        f"Files: {os.path.basename(saved_files[0])} ... {os.path.basename(saved_files[-1])}"
    )

    return output_dir or "."

zarrnii.core.ZarrNii.from_imaris(path, level=0, timepoint=0, channels=None, channel_labels=None, set_channel_labels=None, chunks=None, axes_order='ZYX', orientation='RAS', axes_units=None, downsample_near_isotropic=False) classmethod

Load from Imaris (.ims) file format.

This method uses imaris_ims_zarr to expose the IMS file as a Zarr store, loads it with Dask, then delegates construction to :meth:from_darr.

Parameters:

• path (str) –

  Path to Imaris (.ims) file

• level (int, default: 0 ) –

  Resolution level to load (0 = full resolution). If level exceeds available levels, applies lazy downsampling

• timepoint (int, default: 0 ) –

  Time point to load (default: 0)

• channels (Optional[List[int]], default: None ) –

  List of channel indices to load (0-based). Mutually exclusive with channel_labels. If None, loads all channels.

• channel_labels (Optional[List[str]], default: None ) –

  List of channel names to load by label. Mutually exclusive with channels. Requires set_channel_labels.

• set_channel_labels (Optional[List[str]], default: None ) –

  Channel labels that define the channels present in the Imaris data, in channel index order. Required when channel_labels is used.

• chunks (Any, default: None ) –

  Chunking strategy for dask array (default: use Imaris chunking). If provided as a tuple that omits leading singleton dimensions, singleton chunk sizes are prepended automatically when possible based on existing chunking.

• axes_order (str, default: 'ZYX' ) –

  Spatial axes order for compatibility (default: "ZYX")

• orientation (str, default: 'RAS' ) –

  Default orientation (default: "RAS")

• axes_units (Optional[Dict[str, str]], default: None ) –

  Optional mapping of axis name to unit string (e.g. {"x": "micrometer", "y": "micrometer", "z": "micrometer"}). All values must be valid OME-Zarr space units (see :data:VALID_AXES_UNITS). When None, micrometer is assumed. Non-mm units are automatically converted to millimeters on import; spacing is scaled accordingly and axes_units is updated to 'millimeter'.

• downsample_near_isotropic (bool, default: False ) –

  If True, automatically downsample dimensions with smaller voxel sizes to achieve near-isotropic resolution. Deprecated and will be removed in a future version.

Returns:

• 'ZarrNii' –

  ZarrNii instance

Raises:

• ImportError –

  If imaris_ims_zarr is not available

• FileNotFoundError –

  If path does not exist.

• ValueError –

  If the file cannot be read, has unexpected dimensions, if level/timepoint/channels are out of range, or if selection arguments are invalid.

• ValueError –

  If any value in axes_units is not a valid OME-Zarr space unit.

Source code in zarrnii/core.py

@classmethod
def from_imaris(
    cls,
    path: str,
    level: int = 0,
    timepoint: int = 0,
    channels: Optional[List[int]] = None,
    channel_labels: Optional[List[str]] = None,
    set_channel_labels: Optional[List[str]] = None,
    chunks: Any = None,
    axes_order: str = "ZYX",
    orientation: str = "RAS",
    axes_units: Optional[Dict[str, str]] = None,
    downsample_near_isotropic: bool = False,
) -> "ZarrNii":
    """
    Load from Imaris (.ims) file format.

    This method uses ``imaris_ims_zarr`` to expose the IMS file as a
    Zarr store, loads it with Dask, then delegates construction to
    :meth:`from_darr`.

    Args:
        path: Path to Imaris (.ims) file
        level: Resolution level to load (0 = full resolution). If level
            exceeds available levels, applies lazy downsampling
        timepoint: Time point to load (default: 0)
        channels: List of channel indices to load (0-based). Mutually
            exclusive with channel_labels. If None, loads all channels.
        channel_labels: List of channel names to load by label. Mutually
            exclusive with channels. Requires set_channel_labels.
        set_channel_labels: Channel labels that define the channels present
            in the Imaris data, in channel index order. Required when
            channel_labels is used.
        chunks: Chunking strategy for dask array (default: use Imaris
            chunking). If provided as a tuple that omits leading singleton
            dimensions, singleton chunk sizes are prepended automatically
            when possible based on existing chunking.
        axes_order: Spatial axes order for compatibility (default: "ZYX")
        orientation: Default orientation (default: "RAS")
        axes_units: Optional mapping of axis name to unit string (e.g.
            ``{"x": "micrometer", "y": "micrometer", "z": "micrometer"}``).
            All values must be valid OME-Zarr space units (see
            :data:`VALID_AXES_UNITS`).  When ``None``, micrometer is assumed.
            **Non-mm units are automatically converted to millimeters on
            import**; spacing is scaled accordingly and axes_units is updated
            to ``'millimeter'``.
        downsample_near_isotropic: If True, automatically downsample
            dimensions with smaller voxel sizes to achieve near-isotropic
            resolution. Deprecated and will be removed in a future version.

    Returns:
        ZarrNii instance

    Raises:
        ImportError: If ``imaris_ims_zarr`` is not available
        FileNotFoundError: If *path* does not exist.
        ValueError: If the file cannot be read, has unexpected dimensions,
            if *level*/*timepoint*/*channels* are out of range, or if
            selection arguments are invalid.
        ValueError: If any value in *axes_units* is not a valid OME-Zarr
            space unit.
    """

    if axes_units is None:
        axes_units = {"x": "micrometer", "y": "micrometer", "z": "micrometer"}
    _validate_axes_units(axes_units)
    if downsample_near_isotropic:
        warnings.warn(
            "downsample_near_isotropic is deprecated and will be removed in a "
            "future version of ZarrNii.",
            DeprecationWarning,
            stacklevel=2,
        )
    if channels is not None and channel_labels is not None:
        raise ValueError("Cannot specify both 'channels' and 'channel_labels'")
    if channel_labels is not None and set_channel_labels is None:
        raise ValueError(
            "'set_channel_labels' is required when 'channel_labels' is provided"
        )

    try:
        from imaris_ims_zarr import ImsProcessSafeStore
    except ImportError:
        raise ImportError(
            "imaris_ims_zarr is required for Imaris support. "
            "Install with: pip install imaris-ims-zarr or uv add imaris-ims-zarr"
        )
    if not os.path.exists(path):
        raise FileNotFoundError(
            f"Unable to read Imaris file '{path}': file does not exist"
        )

    # The reader may surface multiple low-level exceptions (h5py/zarr/reader),
    # all of which should map to a consistent user-facing read error.
    imaris_read_errors = (OSError, KeyError, ValueError, RuntimeError, TypeError)
    try:
        level0_store = ImsProcessSafeStore(path, ResolutionLevelLock=0)
    except imaris_read_errors as exc:
        raise ValueError(f"Unable to read Imaris file '{path}': {exc}") from exc

    available_levels = 1
    if hasattr(level0_store, "ResolutionLevels"):
        available_levels = level0_store.ResolutionLevels
    if level < 0:
        raise ValueError(f"Level {level} not available. Level must be >= 0.")
    max_level = available_levels - 1
    actual_level = min(level, max_level)
    do_downsample = level > max_level

    imaris_store = level0_store
    if actual_level != 0:
        try:
            imaris_store = ImsProcessSafeStore(
                path, ResolutionLevelLock=actual_level
            )
        except imaris_read_errors as exc:
            raise ValueError(f"Unable to read Imaris file '{path}': {exc}") from exc

    native_data_array = da.from_zarr(imaris_store)
    normalized_chunks = _normalize_chunks_with_leading_singletons(
        chunks, native_data_array.chunksize
    )
    if chunks is None or normalized_chunks == native_data_array.chunksize:
        data_array = native_data_array
    else:
        data_array = native_data_array.rechunk(normalized_chunks)
    selected_channel_labels = None

    if data_array.ndim == 5:
        if not 0 <= timepoint < data_array.shape[0]:
            raise ValueError(
                f"Timepoint {timepoint} not available. Available timepoints: "
                f"0-{data_array.shape[0] - 1}"
            )
        n_channels = data_array.shape[1]
        available_channels = list(range(n_channels))
        selected_channels = available_channels if channels is None else channels

        if set_channel_labels is not None and len(set_channel_labels) != n_channels:
            raise ValueError(
                f"set_channel_labels length ({len(set_channel_labels)}) must match "
                f"number of channels in source data ({n_channels})."
            )

        if channel_labels is not None:
            label_to_index = {
                label: idx for idx, label in enumerate(set_channel_labels)
            }
            selected_channels = []
            for label in channel_labels:
                if label not in label_to_index:
                    raise KeyError(
                        f"Channel label '{label}' not found. "
                        f"Available labels: {list(label_to_index.keys())}"
                    )
                selected_channels.append(label_to_index[label])

        for channel_idx in selected_channels:
            if not 0 <= channel_idx < n_channels:
                raise ValueError(
                    f"Channel index {channel_idx} not available. "
                    f"Available channels: 0-{n_channels - 1}"
                )

        data_array = data_array[timepoint, selected_channels, ...]
        selected_channel_name = "-".join(str(idx) for idx in selected_channels)
        if set_channel_labels is not None:
            selected_channel_labels = [
                set_channel_labels[idx] for idx in selected_channels
            ]
    elif data_array.ndim == 3:
        if timepoint != 0:
            raise ValueError(
                "Timepoint selection is not supported for 3D Imaris data"
            )
        if channels is not None:
            if len(channels) != 1 or channels[0] != 0:
                raise ValueError(
                    "Channel selection is not supported for 3D Imaris data "
                    "(single channel only)"
                )
        if set_channel_labels is not None and len(set_channel_labels) != 1:
            raise ValueError(
                f"set_channel_labels length ({len(set_channel_labels)}) must match "
                "number of channels in source data (1)."
            )
        if channel_labels is not None:
            if len(channel_labels) != 1:
                raise ValueError(
                    "3D Imaris data only supports selecting one channel label"
                )
            if channel_labels[0] != set_channel_labels[0]:
                raise KeyError(
                    f"Channel label '{channel_labels[0]}' not found. "
                    f"Available labels: {set_channel_labels}"
                )
        if set_channel_labels is not None:
            selected_channel_labels = [set_channel_labels[0]]
        selected_channel_name = "0"
    else:
        raise ValueError(
            f"Unexpected Imaris data dimensions: {data_array.ndim}. "
            "Expected 3D or 5D data."
        )

    if data_array.ndim == 3:
        data_array = data_array[np.newaxis, ...]

    spacing = (1.0, 1.0, 1.0)
    if hasattr(imaris_store, "resolution") and len(imaris_store.resolution) == 3:
        if axes_order == "ZYX":
            spacing = imaris_store.resolution
        else:
            spacing = (
                imaris_store.resolution[2],
                imaris_store.resolution[1],
                imaris_store.resolution[0],
            )

    znimg = cls.from_darr(
        data_array,
        axes_order=axes_order,
        orientation=orientation,
        spacing=spacing,
        name=(
            f"imaris_image_{os.path.basename(path)}_{level}_{timepoint}_"
            f"{selected_channel_name}"
        ),
        channel_labels=selected_channel_labels,
        axes_units=axes_units,
    )

    # Apply lazy downsampling if the requested level exceeds available levels
    # (factor = 2^(level - max_level))
    if do_downsample:
        level_ds = level - max_level
        znimg = znimg.downsample(level=level_ds)

    # Apply near-isotropic downsampling if requested (deprecated)
    if downsample_near_isotropic:
        znimg = _apply_near_isotropic_downsampling(znimg, axes_order)

    return znimg

zarrnii.core.ZarrNii.from_tif_stack(paths, stack_mode='auto', axes_order='ZYX', orientation='RAS', spacing=(1.0, 1.0, 1.0), origin=(0.0, 0.0, 0.0), chunks='auto', name='image', level=0, set_channel_labels=None, channel_colors=None, channel_windows=None, omero=None, axes_units=None, downsample_near_isotropic=False) classmethod

Load TIFF files into a single multi-dimensional ZarrNii image.

Supports flat lists (single stack) and nested lists (per-channel stacks): - Flat list of 2D slices: ["z0.tif", "z1.tif", ...] - Flat list of 3D volumes: ["ch0.tif", "ch1.tif", ...] - Nested per-channel stacks: [["ch0_z0.tif", ...], ["ch1_z0.tif", ...]]

Parameters:

• paths (Union[List[Union[str, bytes]], Tuple[Union[str, bytes], ...], List[List[Union[str, bytes]]], Tuple[Tuple[Union[str, bytes], ...], ...]]) –

  Flat or nested TIFF path list.

• stack_mode (str, default: 'auto' ) –

  One of: - "auto": infer from input layout - "z": flat list of 2D files (stack) or 3D volumes (concatenate) -> stack/concatenate along Z - "c": flat list of 3D volumes (or 2D per-channel single slices) -> stack along channel - "channel_z": nested list of per-channel 2D stacks

• axes_order (str, default: 'ZYX' ) –

  Spatial axes order for output metadata ("ZYX" or "XYZ").

• orientation (str, default: 'RAS' ) –

  Anatomical orientation string in XYZ order.

• spacing (Tuple[float, float, float], default: (1.0, 1.0, 1.0) ) –

  Spatial voxel spacing for the three spatial axes.

• origin (Tuple[float, float, float], default: (0.0, 0.0, 0.0) ) –

  Spatial origin for the three spatial axes.

• chunks (Union[str, Tuple[int, ...]], default: 'auto' ) –

  Dask chunking strategy for final stacked array.

• name (str, default: 'image' ) –

  Name for resulting image.

• level (int, default: 0 ) –

  Downsampling level to apply after loading (0 = full resolution). Since TIFF stacks have no pyramid, any level > 0 applies lazy downsampling by a factor of 2^level.

• set_channel_labels (Optional[List[str]], default: None ) –

  Optional channel names. When provided, OMERO metadata is built automatically via :func:make_omero.

• channel_colors (Optional[List[str]], default: None ) –

  Optional per-channel colors as RRGGBB hex strings (#RRGGBB also accepted). Must have the same length as set_channel_labels when supplied.

• channel_windows (Optional[List[Union['nz.OmeroWindow', Dict[str, float], Tuple[float, float, float, float], List[float]]]], default: None ) –

  Optional per-channel display windows. Each entry may be an nz.OmeroWindow, a dict with keys min/max/ start/end, or a 4-item tuple/list (min, max, start, end). Must have the same length as set_channel_labels when supplied.

• omero (Optional[object], default: None ) –

  Optional full OMERO metadata object (escape hatch). Mutually exclusive with set_channel_labels / channel_colors / channel_windows.

• axes_units (Optional[Dict[str, str]], default: None ) –

  Optional mapping of axis name to unit string (e.g. {"x": "micrometer", "y": "micrometer", "z": "micrometer"}). All values must be valid OME-Zarr space units (see :data:VALID_AXES_UNITS). When None, no unit metadata is stored.

• downsample_near_isotropic (bool, default: False ) –

  If True, automatically downsample dimensions with smaller voxel sizes to achieve near-isotropic resolution. Deprecated and will be removed in a future version.

Returns:

• 'ZarrNii' –

  ZarrNii instance containing TIFF data as lazy dask array.

Raises:

• ValueError –

  If input layout and stack_mode are incompatible.

• ValueError –

  If both omero and any of the channel convenience arguments are provided simultaneously.

• ValueError –

  If set_channel_labels length does not match the number of channels in the stacked data.

• ValueError –

  If any value in axes_units is not a valid OME-Zarr space unit.

Source code in zarrnii/core.py

@classmethod
def from_tif_stack(
    cls,
    paths: Union[
        List[Union[str, bytes]],
        Tuple[Union[str, bytes], ...],
        List[List[Union[str, bytes]]],
        Tuple[Tuple[Union[str, bytes], ...], ...],
    ],
    stack_mode: str = "auto",
    axes_order: str = "ZYX",
    orientation: str = "RAS",
    spacing: Tuple[float, float, float] = (1.0, 1.0, 1.0),
    origin: Tuple[float, float, float] = (0.0, 0.0, 0.0),
    chunks: Union[str, Tuple[int, ...]] = "auto",
    name: str = "image",
    level: int = 0,
    set_channel_labels: Optional[List[str]] = None,
    channel_colors: Optional[List[str]] = None,
    channel_windows: Optional[
        List[
            Union[
                "nz.OmeroWindow",
                Dict[str, float],
                Tuple[float, float, float, float],
                List[float],
            ]
        ]
    ] = None,
    omero: Optional[object] = None,
    axes_units: Optional[Dict[str, str]] = None,
    downsample_near_isotropic: bool = False,
) -> "ZarrNii":
    """Load TIFF files into a single multi-dimensional ZarrNii image.

    Supports flat lists (single stack) and nested lists (per-channel stacks):
    - Flat list of 2D slices: ``["z0.tif", "z1.tif", ...]``
    - Flat list of 3D volumes: ``["ch0.tif", "ch1.tif", ...]``
    - Nested per-channel stacks: ``[["ch0_z0.tif", ...], ["ch1_z0.tif", ...]]``

    Args:
        paths: Flat or nested TIFF path list.
        stack_mode: One of:
            - ``"auto"``: infer from input layout
            - ``"z"``: flat list of 2D files (stack) or 3D volumes (concatenate)
              -> stack/concatenate along Z
            - ``"c"``: flat list of 3D volumes (or 2D per-channel single slices)
              -> stack along channel
            - ``"channel_z"``: nested list of per-channel 2D stacks
        axes_order: Spatial axes order for output metadata (``"ZYX"`` or ``"XYZ"``).
        orientation: Anatomical orientation string in XYZ order.
        spacing: Spatial voxel spacing for the three spatial axes.
        origin: Spatial origin for the three spatial axes.
        chunks: Dask chunking strategy for final stacked array.
        name: Name for resulting image.
        level: Downsampling level to apply after loading (0 = full resolution).
            Since TIFF stacks have no pyramid, any level > 0 applies lazy
            downsampling by a factor of 2^level.
        set_channel_labels: Optional channel names.  When provided, OMERO metadata
            is built automatically via :func:`make_omero`.
        channel_colors: Optional per-channel colors as ``RRGGBB`` hex strings
            (``#RRGGBB`` also accepted).  Must have the same length as
            *set_channel_labels* when supplied.
        channel_windows: Optional per-channel display windows.  Each entry may
            be an ``nz.OmeroWindow``, a dict with keys ``min``/``max``/
            ``start``/``end``, or a 4-item tuple/list ``(min, max, start,
            end)``.  Must have the same length as *set_channel_labels* when
            supplied.
        omero: Optional full OMERO metadata object (escape hatch).  Mutually
            exclusive with *set_channel_labels* / *channel_colors* /
            *channel_windows*.
        axes_units: Optional mapping of axis name to unit string (e.g.
            ``{"x": "micrometer", "y": "micrometer", "z": "micrometer"}``).
            All values must be valid OME-Zarr space units (see
            :data:`VALID_AXES_UNITS`).  When ``None``, no unit metadata is
            stored.
        downsample_near_isotropic: If True, automatically downsample
            dimensions with smaller voxel sizes to achieve near-isotropic
            resolution. Deprecated and will be removed in a future version.

    Returns:
        ZarrNii instance containing TIFF data as lazy dask array.

    Raises:
        ValueError: If input layout and stack_mode are incompatible.
        ValueError: If both *omero* and any of the channel convenience
            arguments are provided simultaneously.
        ValueError: If *set_channel_labels* length does not match the number of
            channels in the stacked data.
        ValueError: If any value in *axes_units* is not a valid OME-Zarr
            space unit.
    """
    import os

    from dask.array.image import imread

    if downsample_near_isotropic:
        warnings.warn(
            "downsample_near_isotropic is deprecated and will be removed in a "
            "future version of ZarrNii.",
            DeprecationWarning,
            stacklevel=2,
        )
    if stack_mode not in {"auto", "z", "c", "channel_z"}:
        raise ValueError(
            "stack_mode must be one of {'auto', 'z', 'c', 'channel_z'}."
        )
    if axes_order not in {"ZYX", "XYZ"}:
        raise ValueError("axes_order must be 'ZYX' or 'XYZ'.")
    if len(spacing) != 3:
        raise ValueError("spacing must have 3 values for spatial axes.")
    if len(origin) != 3:
        raise ValueError("origin must have 3 values for spatial axes.")
    if not paths:
        raise ValueError("paths must contain at least one TIFF path.")
    if omero is not None and (
        set_channel_labels is not None
        or channel_colors is not None
        or channel_windows is not None
    ):
        raise ValueError(
            "Provide either 'omero' or set_channel_labels/channel_colors/"
            "channel_windows, not both."
        )
    if (
        (channel_colors is not None or channel_windows is not None)
        and set_channel_labels is None
        and omero is None
    ):
        raise ValueError(
            "set_channel_labels is required when channel_colors or channel_windows are provided and omero is not set."
        )

    def _read_tif(path_like: Union[str, bytes]) -> da.Array:
        p = os.fspath(path_like)
        try:
            arr = imread(p)
        except Exception as e:
            raise ValueError(
                f"Failed to read TIFF file '{p}' with dask imread."
            ) from e

        while arr.ndim > 3 and arr.shape[0] == 1:
            arr = arr[0]
        if arr.ndim == 3 and arr.shape[0] == 1:
            arr = arr[0]
        if arr.ndim == 3:
            tif_axes = ""
            tif_shape: Tuple[int, ...] = ()
            try:
                import tifffile

                with tifffile.TiffFile(p) as tif:
                    tif_axes = tif.series[0].axes.upper()
                    tif_shape = tuple(tif.series[0].shape)
            except Exception:
                pass

            normalized_axes = []
            for ax in tif_axes:
                if ax in {"I", "Q", "S"}:
                    normalized_axes.append("Z")
                else:
                    normalized_axes.append(ax)

            if (
                len(normalized_axes) == 3
                and len(set(normalized_axes)) == 3
                and set(normalized_axes) == {"Z", "Y", "X"}
            ):
                arr_shape = tuple(int(v) for v in arr.shape)
                size_to_index = {}
                for idx, size in enumerate(arr_shape):
                    size_to_index.setdefault(size, []).append(idx)

                axis_sizes = {
                    axis: int(tif_shape[i])
                    for i, axis in enumerate(normalized_axes)
                    if i < len(tif_shape)
                }

                permutation = []
                used_indices = set()
                for axis in ("Z", "Y", "X"):
                    target_size = axis_sizes.get(axis)
                    candidates = [
                        i
                        for i in size_to_index.get(target_size, [])
                        if i not in used_indices
                    ]
                    if len(candidates) == 1:
                        permutation.append(candidates[0])
                        used_indices.add(candidates[0])
                    else:
                        permutation = []
                        break

                if len(permutation) == 3:
                    arr = arr.transpose(tuple(permutation))
                else:
                    arr = arr.transpose(
                        (
                            normalized_axes.index("Z"),
                            normalized_axes.index("Y"),
                            normalized_axes.index("X"),
                        )
                    )
        if arr.ndim not in (2, 3):
            raise ValueError(
                f"TIFF file '{p}' produced shape {arr.shape}; only 2D or 3D TIFF inputs are supported."
            )
        return arr

    first_item = paths[0]
    is_nested = isinstance(first_item, (list, tuple))

    if is_nested:
        if stack_mode not in {"auto", "channel_z"}:
            raise ValueError(
                "Nested paths require stack_mode='channel_z' (or 'auto')."
            )

        channel_volumes = []
        for i, channel_paths in enumerate(paths):
            if (
                not isinstance(channel_paths, (list, tuple))
                or len(channel_paths) == 0
            ):
                raise ValueError(
                    f"Nested channel entry at index {i} must be a non-empty list of TIFF paths."
                )
            channel_arrays = [_read_tif(p) for p in channel_paths]
            ndims = {arr.ndim for arr in channel_arrays}
            if len(ndims) != 1:
                raise ValueError(
                    f"All TIFF files within channel index {i} must be consistently 2D or 3D."
                )
            if channel_arrays[0].ndim == 2:
                channel_volumes.append(da.stack(channel_arrays, axis=0))
            elif len(channel_arrays) == 1:
                channel_volumes.append(channel_arrays[0])
            else:
                raise ValueError(
                    "Nested 3D TIFF channels are ambiguous; provide one 3D volume per channel."
                )
        data = da.stack(channel_volumes, axis=0)
    else:
        flat_arrays = [_read_tif(p) for p in paths]
        ndims = {arr.ndim for arr in flat_arrays}

        inferred_mode = stack_mode
        if inferred_mode == "auto":
            if len(ndims) != 1:
                raise ValueError(
                    "Cannot infer stack_mode from mixed 2D and 3D flat TIFF inputs."
                )
            inferred_mode = "z" if flat_arrays[0].ndim == 2 else "c"

        if inferred_mode == "channel_z":
            raise ValueError("stack_mode='channel_z' requires nested path input.")
        if inferred_mode == "z":
            if ndims == {2}:
                data = da.expand_dims(da.stack(flat_arrays, axis=0), axis=0)
            elif ndims == {3}:
                data = da.expand_dims(da.concatenate(flat_arrays, axis=0), axis=0)
            else:
                raise ValueError(
                    "stack_mode='z' requires a flat list of only 2D TIFF files or only 3D TIFF volumes."
                )
        elif inferred_mode == "c":
            if ndims == {2}:
                channel_volumes = [
                    da.expand_dims(arr, axis=0) for arr in flat_arrays
                ]
                data = da.stack(channel_volumes, axis=0)
            elif ndims == {3}:
                data = da.stack(flat_arrays, axis=0)
            else:
                raise ValueError(
                    "stack_mode='c' requires either all 2D or all 3D TIFF files."
                )
        else:
            raise ValueError(
                "stack_mode must be one of {'auto', 'z', 'c', 'channel_z'}."
            )

    if chunks != "auto":
        data = data.rechunk(chunks)

    if axes_order == "XYZ":
        data = data.transpose((0, 3, 2, 1))

    if omero is None and set_channel_labels is not None:
        if len(set_channel_labels) != data.shape[0]:
            raise ValueError(
                f"set_channel_labels length ({len(set_channel_labels)}) must match number of channels ({data.shape[0]})."
            )
        omero = make_omero(
            channel_labels=set_channel_labels,
            channel_colors=channel_colors,
            channel_windows=channel_windows,
        )

    znimg = cls.from_darr(
        data,
        axes_order=axes_order,
        orientation=orientation,
        spacing=spacing,
        origin=origin,
        name=name,
        omero=omero,
        axes_units=axes_units,
    )

    # Apply lazy downsampling if level > 0 (TIFF stacks have no pyramid;
    # factor = 2^level)
    if level > 0:
        znimg = znimg.downsample(level=level)

    # Apply near-isotropic downsampling if requested (deprecated)
    if downsample_near_isotropic:
        znimg = _apply_near_isotropic_downsampling(znimg, axes_order)

    return znimg

zarrnii.core.ZarrNii.from_ome_tif(path, axes_order='ZYX', orientation='RAS', level=0, series=0, chunks='auto', name=None, set_channel_labels=None, axes_units=None, downsample_near_isotropic=False) classmethod

Load ZarrNii from an OME-TIFF file (e.g. a z-stack).

Lazily reads the image data using tifffile and wraps it as a ZarrNii object with spatial metadata extracted from the embedded OME-XML or ImageJ metadata. The method mirrors the signature and behaviour of other constructors such as :meth:from_darr and :meth:from_imaris.

Parameters:

• path (str) –

  Path to the OME-TIFF file (.tif or .tiff).

• axes_order (str, default: 'ZYX' ) –

  Target spatial axes order for ZarrNii. Either "ZYX" (default, most common for microscopy z-stacks) or "XYZ". The loaded array is transposed to this order regardless of how the TIFF was written.

• orientation (str, default: 'RAS' ) –

  Anatomical orientation string in XYZ axes order (e.g. "RAS", "LPI"). Passed through to the ZarrNii instance unchanged.

• level (int, default: 0 ) –

  Pyramid level to load (0 = full resolution). If level exceeds available levels, applies lazy downsampling. Most OME-TIFF z-stacks are single-level, so this defaults to 0.

• series (int, default: 0 ) –

  OME-TIFF series index to load (default: 0). Multi- series files (e.g. from plate acquisitions) may contain more than one series.

• chunks (Union[str, Tuple], default: 'auto' ) –

  Dask chunking strategy. "auto" lets Dask choose chunk sizes automatically; a tuple of ints sets explicit chunk sizes matching the array dimensions.

• name (Optional[str], default: None ) –

  Optional name for the resulting NgffImage. Defaults to the basename of path.

• set_channel_labels (Optional[List[str]], default: None ) –

  Optional channel names in channel index order. When provided, OMERO metadata is built from these labels.

• axes_units (Optional[Dict[str, str]], default: None ) –

  Optional mapping of axis name to unit string that overrides the unit read from the file metadata (e.g. {"x": "micrometer", "y": "micrometer", "z": "micrometer"}). All values must be valid OME-Zarr space units (see :data:VALID_AXES_UNITS). When None, the unit is inferred from PhysicalSizeXUnit in the OME-XML (or ImageJ metadata), defaulting to "micrometer" when no unit is present.

• downsample_near_isotropic (bool, default: False ) –

  If True, automatically downsample dimensions with smaller voxel sizes to achieve near-isotropic resolution. Deprecated and will be removed in a future version.

Returns:

• 'ZarrNii' –

  ZarrNii instance with lazily-loaded data and spatial metadata.

Raises:

• ImportError –

  If tifffile is not installed.

• ValueError –

  If series or level is out of range.

• ValueError –

  If axes_order is not "ZYX" or "XYZ".

• ValueError –

  If set_channel_labels length does not match the number of channels in the loaded data.

• ValueError –

  If any value in axes_units is not a valid OME-Zarr space unit.

Examples:

>>> # Load a single-channel z-stack
>>> znii = ZarrNii.from_ome_tif("/path/to/zstack.ome.tif")

>>> # Load with explicit axes order and orientation
>>> znii = ZarrNii.from_ome_tif(
...     "/path/to/zstack.ome.tif",
...     axes_order="ZYX",
...     orientation="RAS",
... )

>>> # Load a specific series at a lower resolution level
>>> znii = ZarrNii.from_ome_tif(
...     "/path/to/multiresolution.ome.tif",
...     level=1,
...     series=0,
... )

Notes

• Spacing is read from PhysicalSizeX/Y/Z in the OME-XML, or from the equivalent ImageJ metadata fields when the file is in ImageJ format. Falls back to 1.0 if no physical size is found.
• The spatial unit (PhysicalSizeXUnit) is mapped to the corresponding OME-Zarr unit name (e.g. "um" → "micrometer").
• Data are kept as a lazy Dask array backed by the TIFF file; they are not read into memory until explicitly computed.
• Internal units invariant: spatial scale and translation values are always stored in millimeters. Non-mm units read from the OME-TIFF metadata (e.g. "micrometer") are automatically converted to mm on import and axes_units is set to 'millimeter'.

Source code in zarrnii/core.py

@classmethod
def from_ome_tif(
    cls,
    path: str,
    axes_order: str = "ZYX",
    orientation: str = "RAS",
    level: int = 0,
    series: int = 0,
    chunks: Union[str, Tuple] = "auto",
    name: Optional[str] = None,
    set_channel_labels: Optional[List[str]] = None,
    axes_units: Optional[Dict[str, str]] = None,
    downsample_near_isotropic: bool = False,
) -> "ZarrNii":
    """Load ZarrNii from an OME-TIFF file (e.g. a z-stack).

    Lazily reads the image data using tifffile and wraps it as a ZarrNii
    object with spatial metadata extracted from the embedded OME-XML or
    ImageJ metadata.  The method mirrors the signature and behaviour of
    other constructors such as :meth:`from_darr` and :meth:`from_imaris`.

    Args:
        path: Path to the OME-TIFF file (.tif or .tiff).
        axes_order: Target spatial axes order for ZarrNii.  Either
            ``"ZYX"`` (default, most common for microscopy z-stacks) or
            ``"XYZ"``.  The loaded array is transposed to this order
            regardless of how the TIFF was written.
        orientation: Anatomical orientation string in XYZ axes order
            (e.g. ``"RAS"``, ``"LPI"``).  Passed through to the
            ZarrNii instance unchanged.
        level: Pyramid level to load (0 = full resolution).  If level
            exceeds available levels, applies lazy downsampling.  Most
            OME-TIFF z-stacks are single-level, so this defaults to 0.
        series: OME-TIFF series index to load (default: 0).  Multi-
            series files (e.g. from plate acquisitions) may contain
            more than one series.
        chunks: Dask chunking strategy.  ``"auto"`` lets Dask choose
            chunk sizes automatically; a tuple of ints sets explicit
            chunk sizes matching the array dimensions.
        name: Optional name for the resulting NgffImage.  Defaults to
            the basename of *path*.
        set_channel_labels: Optional channel names in channel index order.
            When provided, OMERO metadata is built from these labels.
        axes_units: Optional mapping of axis name to unit string that
            overrides the unit read from the file metadata (e.g.
            ``{"x": "micrometer", "y": "micrometer", "z": "micrometer"}``).
            All values must be valid OME-Zarr space units (see
            :data:`VALID_AXES_UNITS`).  When ``None``, the unit is inferred
            from ``PhysicalSizeXUnit`` in the OME-XML (or ImageJ metadata),
            defaulting to ``"micrometer"`` when no unit is present.
        downsample_near_isotropic: If True, automatically downsample
            dimensions with smaller voxel sizes to achieve near-isotropic
            resolution. Deprecated and will be removed in a future version.

    Returns:
        ZarrNii instance with lazily-loaded data and spatial metadata.

    Raises:
        ImportError: If *tifffile* is not installed.
        ValueError: If *series* or *level* is out of range.
        ValueError: If *axes_order* is not ``"ZYX"`` or ``"XYZ"``.
        ValueError: If *set_channel_labels* length does not match the
            number of channels in the loaded data.
        ValueError: If any value in *axes_units* is not a valid OME-Zarr
            space unit.

    Examples:
        >>> # Load a single-channel z-stack
        >>> znii = ZarrNii.from_ome_tif("/path/to/zstack.ome.tif")

        >>> # Load with explicit axes order and orientation
        >>> znii = ZarrNii.from_ome_tif(
        ...     "/path/to/zstack.ome.tif",
        ...     axes_order="ZYX",
        ...     orientation="RAS",
        ... )

        >>> # Load a specific series at a lower resolution level
        >>> znii = ZarrNii.from_ome_tif(
        ...     "/path/to/multiresolution.ome.tif",
        ...     level=1,
        ...     series=0,
        ... )

    Notes:
        - Spacing is read from ``PhysicalSizeX/Y/Z`` in the OME-XML, or
          from the equivalent ImageJ metadata fields when the file is in
          ImageJ format.  Falls back to 1.0 if no physical size is found.
        - The spatial unit (``PhysicalSizeXUnit``) is mapped to the
          corresponding OME-Zarr unit name (e.g. ``"um"`` →
          ``"micrometer"``).
        - Data are kept as a lazy Dask array backed by the TIFF file;
          they are not read into memory until explicitly computed.
        - **Internal units invariant**: spatial scale and translation values
          are always stored in millimeters.  Non-mm units read from the
          OME-TIFF metadata (e.g. ``"micrometer"``) are automatically
          converted to mm on import and ``axes_units`` is set to
          ``'millimeter'``.
    """
    _validate_axes_units(axes_units)
    if downsample_near_isotropic:
        warnings.warn(
            "downsample_near_isotropic is deprecated and will be removed in a "
            "future version of ZarrNii.",
            DeprecationWarning,
            stacklevel=2,
        )
    try:
        import tifffile
    except ImportError:
        raise ImportError(
            "tifffile is required for OME-TIFF support. "
            "Install with: pip install tifffile"
        )

    import os
    from xml.etree import ElementTree as ET

    import zarr

    if axes_order not in ("ZYX", "XYZ"):
        raise ValueError(f"axes_order must be 'ZYX' or 'XYZ', got '{axes_order}'")

    # --- Step 1: collect metadata from within the context manager ----------
    with tifffile.TiffFile(path) as tif:
        if series >= len(tif.series):
            raise ValueError(
                f"Series {series} not available. "
                f"File has {len(tif.series)} series (0-{len(tif.series)-1})."
            )

        tif_series = tif.series[series]
        # tifffile reports axes in Python array order, e.g. 'ZYX', 'CZYX'
        tif_axes = tif_series.axes.upper()

        # Validate the requested level
        n_levels = len(tif_series.levels)
        if level < 0:
            raise ValueError(f"Level {level} not available. Level must be >= 0.")
        max_level = n_levels - 1
        actual_level = min(level, max_level)
        do_downsample = level > max_level

        # --- Parse physical spacing -----------------------------------------
        spacing_x, spacing_y, spacing_z = 1.0, 1.0, 1.0
        axes_unit = "micrometer"

        _ome_to_zarr_units = {
            "um": "micrometer",
            "µm": "micrometer",
            "nm": "nanometer",
            "mm": "millimeter",
            "m": "meter",
            "cm": "centimeter",
        }

        if tif.is_ome and tif.ome_metadata:
            root = ET.fromstring(tif.ome_metadata)
            ns_uri = root.tag.split("}")[0][1:] if "{" in root.tag else ""
            ns_prefix = f"{{{ns_uri}}}" if ns_uri else ""
            pixels_elem = root.find(f"{ns_prefix}Image/{ns_prefix}Pixels")
            if pixels_elem is not None:
                spacing_x = float(pixels_elem.get("PhysicalSizeX", 1.0))
                spacing_y = float(pixels_elem.get("PhysicalSizeY", 1.0))
                spacing_z = float(pixels_elem.get("PhysicalSizeZ", 1.0))
                unit = pixels_elem.get("PhysicalSizeXUnit", "um")
                axes_unit = _ome_to_zarr_units.get(unit, "micrometer")

        elif tif.is_imagej and tif.imagej_metadata:
            ij = tif.imagej_metadata
            spacing_x = float(ij.get("physicalsizex", 1.0))
            spacing_y = float(ij.get("physicalsizey", 1.0))
            spacing_z = float(ij.get("physicalsizez", 1.0))
            unit = ij.get("unit", "um")
            axes_unit = _ome_to_zarr_units.get(unit, "micrometer")

    # --- Step 2: open the zarr store outside the context manager so that
    #     the dask array can be lazily evaluated later ---------------------
    zarr_store = tifffile.imread(
        path, aszarr=True, series=series, level=actual_level
    )
    z_arr = zarr.open(zarr_store, mode="r")

    dask_chunks = None if chunks == "auto" else chunks
    darr = da.from_zarr(z_arr, chunks=dask_chunks)

    # --- Step 3: normalize axes to (C, Z, Y, X) or (C, X, Y, Z) ----------
    current_axes = list(tif_axes)

    # Map any unrecognised axes labels to known ones.  tifffile uses 'Q'
    # for pages whose dimension is not identified from metadata.  Treat the
    # first unknown axis as Z (z-stack), any further unknown axes as T.
    # Iterate in reverse so that index-based removal stays valid.
    _known = {"T", "C", "Z", "Y", "X"}
    for i in range(len(current_axes) - 1, -1, -1):
        ax = current_axes[i]
        if ax not in _known:
            if "Z" not in current_axes:
                current_axes[i] = "Z"
            elif "T" not in current_axes:
                current_axes[i] = "T"
            else:
                # Drop unrecognised surplus dimension by squeezing
                darr = darr.squeeze(axis=i)
                current_axes.pop(i)

    # Add channel dimension if absent
    if "C" not in current_axes:
        darr = darr[np.newaxis, ...]
        current_axes = ["C"] + current_axes

    # Build target axes list
    if axes_order == "ZYX":
        spatial = ["Z", "Y", "X"]
    else:
        spatial = ["X", "Y", "Z"]

    has_time = "T" in current_axes
    target_axes = (["T"] if has_time else []) + ["C"] + spatial

    # Add any axes that are still missing as size-1 dimensions, inserting
    # each one at the correct position relative to axes already present so
    # that the subsequent transpose is straightforward.
    for ax in target_axes:
        if ax not in current_axes:
            ax_pos = target_axes.index(ax)
            # Insert just before the first following target axis present in
            # current_axes, defaulting to the end.
            insert_idx = len(current_axes)
            for following_ax in target_axes[ax_pos + 1 :]:
                if following_ax in current_axes:
                    insert_idx = current_axes.index(following_ax)
                    break
            darr = da.expand_dims(darr, axis=insert_idx)
            current_axes.insert(insert_idx, ax)

    # Transpose to target order
    transpose_order = [current_axes.index(ax) for ax in target_axes]
    darr = darr.transpose(transpose_order)

    final_dims = [ax.lower() for ax in target_axes]

    # --- Step 4: build scale / translation dicts --------------------------
    n_channels = darr.shape[target_axes.index("C")] if "C" in target_axes else 1
    omero_metadata = None
    if set_channel_labels is not None:
        if len(set_channel_labels) != n_channels:
            raise ValueError(
                f"set_channel_labels length ({len(set_channel_labels)}) must match "
                f"number of channels in source data ({n_channels})."
            )
        omero_metadata = make_omero(set_channel_labels)

    if axes_order == "ZYX":
        scale = {"z": spacing_z, "y": spacing_y, "x": spacing_x}
        translation = {"z": 0.0, "y": 0.0, "x": 0.0}
        axes_units_dict = {
            "z": axes_unit,
            "y": axes_unit,
            "x": axes_unit,
        }
    else:  # XYZ
        scale = {"x": spacing_x, "y": spacing_y, "z": spacing_z}
        translation = {"x": 0.0, "y": 0.0, "z": 0.0}
        axes_units_dict = {
            "x": axes_unit,
            "y": axes_unit,
            "z": axes_unit,
        }

    # Use the caller-supplied override when provided (already validated above),
    # otherwise fall back to the unit derived from the file metadata.
    final_axes_units = axes_units if axes_units is not None else axes_units_dict

    if name is None:
        name = os.path.basename(path)

    ngff_image = nz.NgffImage(
        data=darr,
        dims=final_dims,
        scale=scale,
        translation=translation,
        axes_units=final_axes_units,
        name=name,
    )
    # Normalize spatial metadata to mm.
    ngff_image = _normalize_ngff_image_to_mm(ngff_image)

    znimg = cls(
        ngff_image=ngff_image,
        axes_order=axes_order,
        xyz_orientation=orientation,
        _omero=omero_metadata,
    )

    # Apply lazy downsampling if the requested level exceeds available levels
    # (factor = 2^(level - max_level))
    if do_downsample:
        level_ds = level - max_level
        znimg = znimg.downsample(level=level_ds)

    # Apply near-isotropic downsampling if requested (deprecated)
    if downsample_near_isotropic:
        znimg = _apply_near_isotropic_downsampling(znimg, axes_order)

    return znimg

zarrnii.core.ZarrNii.to_imaris(path, compression='gzip', compression_opts=6)

Save to Imaris (.ims) file format using HDF5.

This method creates Imaris files compatible with Imaris software by following the exact HDF5 structure from correctly-formed reference files. All attributes use byte-array encoding as required by Imaris.

Parameters:

• path (str) –

  Output path for Imaris (.ims) file

• compression (str, default: 'gzip' ) –

  HDF5 compression method (default: "gzip")

• compression_opts (int, default: 6 ) –

  Compression level (default: 6)

Returns:

• str ( str ) –

  Path to the saved file

Raises:

• ImportError –

  If h5py is not available

Notes

• Imaris files are always saved in ZYX axis order
• Automatic axis reordering from XYZ to ZYX if needed
• Spatial transformations and metadata are preserved

Source code in zarrnii/core.py

def to_imaris(
    self, path: str, compression: str = "gzip", compression_opts: int = 6
) -> str:
    """
    Save to Imaris (.ims) file format using HDF5.

    This method creates Imaris files compatible with Imaris software by
    following the exact HDF5 structure from correctly-formed reference files.
    All attributes use byte-array encoding as required by Imaris.

    Args:
        path: Output path for Imaris (.ims) file
        compression: HDF5 compression method (default: "gzip")
        compression_opts: Compression level (default: 6)

    Returns:
        str: Path to the saved file

    Raises:
        ImportError: If h5py is not available

    Notes:
        - Imaris files are always saved in ZYX axis order
        - Automatic axis reordering from XYZ to ZYX if needed
        - Spatial transformations and metadata are preserved
    """
    try:
        import h5py
    except ImportError:
        raise ImportError(
            "h5py is required for Imaris support. "
            "Install with: pip install zarrnii[imaris] or pip install h5py"
        )

    # Determine the image to save
    if self.axes_order == "XYZ":
        # Need to reorder data from XYZ to ZYX for Imaris
        ngff_image_to_save = self._create_zyx_ngff_image()
    else:
        # Already in ZYX order
        ngff_image_to_save = self.ngff_image

    # Ensure path has .ims extension
    if not path.endswith(".ims"):
        path = path + ".ims"

    def _string_to_byte_array(s: str) -> np.ndarray:
        """Convert string to byte array as required by Imaris."""
        return np.array([c.encode() for c in s])

    # Get data and metadata
    if hasattr(ngff_image_to_save.data, "compute"):
        data = (
            ngff_image_to_save.data.compute()
        )  # Convert Dask array to numpy array
    else:
        data = np.asarray(ngff_image_to_save.data)  # Handle numpy arrays directly

    # Handle dimensions: expect ZYX or CZYX
    if len(data.shape) == 4:
        # CZYX format
        n_channels = data.shape[0]
        z, y, x = data.shape[1:]
    elif len(data.shape) == 3:
        # ZYX format - single channel
        n_channels = 1
        z, y, x = data.shape
        data = data[np.newaxis, ...]  # Add channel dimension
    else:
        raise ValueError(
            f"Unsupported data shape: {data.shape}. Expected 3D (ZYX) or 4D (CZYX)"
        )

    # Create Imaris file structure exactly matching reference file
    with h5py.File(path, "w") as f:
        # Root attributes - use exact byte array format from reference
        f.attrs["DataSetDirectoryName"] = _string_to_byte_array("DataSet")
        f.attrs["DataSetInfoDirectoryName"] = _string_to_byte_array("DataSetInfo")
        f.attrs["ImarisDataSet"] = _string_to_byte_array("ImarisDataSet")
        f.attrs["ImarisVersion"] = _string_to_byte_array("5.5.0")
        f.attrs["NumberOfDataSets"] = np.array([1], dtype=np.uint32)
        f.attrs["ThumbnailDirectoryName"] = _string_to_byte_array("Thumbnail")

        # Create main DataSet group structure
        dataset_group = f.create_group("DataSet")
        res_group = dataset_group.create_group("ResolutionLevel 0")
        time_group = res_group.create_group("TimePoint 0")

        # Create channels with proper attributes
        for c in range(n_channels):
            channel_group = time_group.create_group(f"Channel {c}")
            channel_data = data[c]  # (Z, Y, X)

            # Channel attributes - use byte array format exactly like reference
            channel_group.attrs["ImageSizeX"] = _string_to_byte_array(str(x))
            channel_group.attrs["ImageSizeY"] = _string_to_byte_array(str(y))
            channel_group.attrs["ImageSizeZ"] = _string_to_byte_array(str(z))
            channel_group.attrs["ImageBlockSizeX"] = _string_to_byte_array(str(x))
            channel_group.attrs["ImageBlockSizeY"] = _string_to_byte_array(str(y))
            channel_group.attrs["ImageBlockSizeZ"] = _string_to_byte_array(
                str(min(z, 16))
            )

            # Histogram range attributes
            data_min, data_max = float(channel_data.min()), float(
                channel_data.max()
            )
            channel_group.attrs["HistogramMin"] = _string_to_byte_array(
                f"{data_min:.3f}"
            )
            channel_group.attrs["HistogramMax"] = _string_to_byte_array(
                f"{data_max:.3f}"
            )

            # Create data dataset with proper compression
            # Preserve original data type but ensure it's compatible with Imaris
            if channel_data.dtype == np.float32 or channel_data.dtype == np.float64:
                # Keep float data as is for round-trip compatibility
                data_for_storage = channel_data.astype(np.float32)
            elif channel_data.dtype in [np.uint16, np.int16]:
                # Keep 16-bit data as is
                data_for_storage = channel_data
            else:
                # Convert other types to uint8
                data_for_storage = channel_data.astype(np.uint8)

            channel_group.create_dataset(
                "Data",
                data=data_for_storage,
                compression=compression,
                compression_opts=compression_opts,
                chunks=True,
            )

            # Create histogram
            hist_data, _ = np.histogram(
                channel_data.flatten(), bins=256, range=(data_min, data_max)
            )
            channel_group.create_dataset(
                "Histogram", data=hist_data.astype(np.uint64)
            )

        # Get spacing directly from scale dictionary with proper XYZ order
        try:
            # Extract voxel sizes directly from ngff_image scale dictionary
            # This ensures we get X, Y, Z in the correct order regardless of axes_order
            sx = ngff_image_to_save.scale.get("x", 1.0)
            sy = ngff_image_to_save.scale.get("y", 1.0)
            sz = ngff_image_to_save.scale.get("z", 1.0)
        except:
            sx = sy = sz = 1.0

        # Calculate extents (physical coordinates)
        ext_x = sx * x
        ext_y = sy * y
        ext_z = sz * z

        # Create comprehensive DataSetInfo structure matching reference
        info_group = f.create_group("DataSetInfo")

        # Create channel info groups
        for c in range(n_channels):
            channel_info = info_group.create_group(f"Channel {c}")

            # Essential channel attributes in byte array format
            channel_info.attrs["Color"] = _string_to_byte_array(
                "1.000 0.000 0.000"
                if c == 0
                else f"0.000 {1.0 if c == 1 else 0.0:.3f} {1.0 if c == 2 else 0.0:.3f}"
            )
            channel_info.attrs["Name"] = _string_to_byte_array(f"Channel {c}")
            channel_info.attrs["ColorMode"] = _string_to_byte_array("BaseColor")
            channel_info.attrs["ColorOpacity"] = _string_to_byte_array("1.000")
            channel_info.attrs["ColorRange"] = _string_to_byte_array("0 255")
            channel_info.attrs["GammaCorrection"] = _string_to_byte_array("1.000")
            channel_info.attrs["LSMEmissionWavelength"] = _string_to_byte_array(
                "500"
            )
            channel_info.attrs["LSMExcitationWavelength"] = _string_to_byte_array(
                "500"
            )
            channel_info.attrs["LSMPhotons"] = _string_to_byte_array("1")
            channel_info.attrs["LSMPinhole"] = _string_to_byte_array("0")

            # Add description
            description = f"Channel {c} created by ZarrNii"
            channel_info.attrs["Description"] = _string_to_byte_array(description)

        # Create CRITICAL Image group with voxel size information (this was missing!)
        image_info = info_group.create_group("Image")

        # Add essential image metadata with proper voxel size information
        image_info.attrs["X"] = _string_to_byte_array(str(x))
        image_info.attrs["Y"] = _string_to_byte_array(str(y))
        image_info.attrs["Z"] = _string_to_byte_array(str(z))
        image_info.attrs["Unit"] = _string_to_byte_array("um")
        image_info.attrs["Noc"] = _string_to_byte_array(str(n_channels))

        # CRITICAL: Set proper physical extents that define voxel size
        # Imaris reads voxel size from these extent values
        image_info.attrs["ExtMin0"] = _string_to_byte_array(f"{-ext_x/2:.3f}")
        image_info.attrs["ExtMax0"] = _string_to_byte_array(f"{ext_x/2:.3f}")
        image_info.attrs["ExtMin1"] = _string_to_byte_array(f"{-ext_y/2:.3f}")
        image_info.attrs["ExtMax1"] = _string_to_byte_array(f"{ext_y/2:.3f}")
        image_info.attrs["ExtMin2"] = _string_to_byte_array(f"{-ext_z/2:.3f}")
        image_info.attrs["ExtMax2"] = _string_to_byte_array(f"{ext_z/2:.3f}")

        # Add device/acquisition metadata
        image_info.attrs["ManufactorString"] = _string_to_byte_array("ZarrNii")
        image_info.attrs["ManufactorType"] = _string_to_byte_array("Generic")
        image_info.attrs["LensPower"] = _string_to_byte_array("")
        image_info.attrs["NumericalAperture"] = _string_to_byte_array("")
        image_info.attrs["RecordingDate"] = _string_to_byte_array(
            "2024-01-01 00:00:00.000"
        )
        image_info.attrs["Filename"] = _string_to_byte_array(path.split("/")[-1])
        image_info.attrs["Name"] = _string_to_byte_array("ZarrNii Export")
        image_info.attrs["Compression"] = _string_to_byte_array("5794")

        # Add description
        description = (
            f"Imaris file created by ZarrNii from {self.axes_order} format data. "
            f"Original shape: {self.darr.shape}. Converted to Imaris format "
            f"with {n_channels} channel(s) and dimensions {z}x{y}x{x}. "
            f"Voxel size: {sx:.3f} x {sy:.3f} x {sz:.3f} um."
        )
        image_info.attrs["Description"] = _string_to_byte_array(description)

        # Create Imaris metadata group
        imaris_info = info_group.create_group("Imaris")
        imaris_info.attrs["Version"] = _string_to_byte_array("7.0")
        imaris_info.attrs["ThumbnailMode"] = _string_to_byte_array("thumbnailMIP")
        imaris_info.attrs["ThumbnailSize"] = _string_to_byte_array("256")

        # Create ImarisDataSet metadata
        dataset_info = info_group.create_group("ImarisDataSet")
        dataset_info.attrs["Creator"] = _string_to_byte_array("Imaris")
        dataset_info.attrs["Version"] = _string_to_byte_array("7.0")
        dataset_info.attrs["NumberOfImages"] = _string_to_byte_array("1")

        # Add version-specific groups as seen in reference
        dataset_info_ver = info_group.create_group("ImarisDataSet       0.0.0")
        dataset_info_ver.attrs["NumberOfImages"] = _string_to_byte_array("1")
        dataset_info_ver2 = info_group.create_group("ImarisDataSet      0.0.0")
        dataset_info_ver2.attrs["NumberOfImages"] = _string_to_byte_array("1")

        # Create TimeInfo group
        time_info = info_group.create_group("TimeInfo")
        time_info.attrs["DatasetTimePoints"] = _string_to_byte_array("1")
        time_info.attrs["FileTimePoints"] = _string_to_byte_array("1")
        time_info.attrs["TimePoint1"] = _string_to_byte_array(
            "2024-01-01 00:00:00.000"
        )

        # Create Log group (basic processing log)
        log_group = info_group.create_group("Log")
        log_group.attrs["Entries"] = _string_to_byte_array("1")
        log_group.attrs["Entry0"] = _string_to_byte_array(
            f"<ZarrNiiExport channels=\"{' '.join(['on'] * n_channels)}\"/>"
        )

        # Create thumbnail group with proper multi-channel thumbnail
        thumbnail_group = f.create_group("Thumbnail")

        # Create a combined thumbnail (256x1024 for multi-channel as in reference)
        if n_channels > 1:
            # Multi-channel thumbnail: concatenate channels horizontally
            thumb_width = 256 * n_channels
            thumbnail_data = np.zeros((256, thumb_width), dtype=np.uint8)

            for c in range(n_channels):
                # Downsample each channel to 256x256
                channel_data = data[c]
                # Take MIP (Maximum Intensity Projection) along Z
                mip = np.max(channel_data, axis=0)
                # Resize to 256x256 (simple decimation)
                step_y = max(1, mip.shape[0] // 256)
                step_x = max(1, mip.shape[1] // 256)
                thumb_channel = mip[::step_y, ::step_x]

                # Pad or crop to exactly 256x256
                if thumb_channel.shape[0] < 256 or thumb_channel.shape[1] < 256:
                    padded = np.zeros((256, 256), dtype=thumb_channel.dtype)
                    h, w = thumb_channel.shape
                    padded[:h, :w] = thumb_channel
                    thumb_channel = padded
                else:
                    thumb_channel = thumb_channel[:256, :256]

                # Place in thumbnail
                thumbnail_data[:, c * 256 : (c + 1) * 256] = thumb_channel
        else:
            # Single channel: 256x256 thumbnail
            channel_data = data[0]
            mip = np.max(channel_data, axis=0)
            step_y = max(1, mip.shape[0] // 256)
            step_x = max(1, mip.shape[1] // 256)
            thumbnail_data = mip[::step_y, ::step_x]

            if thumbnail_data.shape[0] < 256 or thumbnail_data.shape[1] < 256:
                padded = np.zeros((256, 256), dtype=thumbnail_data.dtype)
                h, w = thumbnail_data.shape
                padded[:h, :w] = thumbnail_data
                thumbnail_data = padded
            else:
                thumbnail_data = thumbnail_data[:256, :256]

        thumbnail_group.create_dataset("Data", data=thumbnail_data.astype(np.uint8))

    return path

zarrnii.core.ZarrNii.copy(name=None)

Create a copy of this ZarrNii.

Returns:

• 'ZarrNii' –

  New ZarrNii with copied data

Source code in zarrnii/core.py

def copy(self, name=None) -> "ZarrNii":
    """
    Create a copy of this ZarrNii.

    Returns:
        New ZarrNii with copied data
    """
    # Copy dims - tuples are immutable so can be used directly,
    # lists need to be copied
    dims = self.ngff_image.dims
    copied_dims = dims if isinstance(dims, tuple) else list(dims)

    # Create a new NgffImage with the same properties
    copied_image = _derive_ngff_image(
        self.ngff_image,
        data=self.ngff_image.data,  # Reuse lazy Dask array; no extra copy needed
        dims=copied_dims,
        scale=self.ngff_image.scale.copy(),
        translation=self.ngff_image.translation.copy(),
        name=self.ngff_image.name if name is None else name,
    )
    return ZarrNii(
        ngff_image=copied_image,
        axes_order=self.axes_order,
        xyz_orientation=self.xyz_orientation,
        _omero=self._omero,
    )

zarrnii.core.ZarrNii.compute()

Compute the dask array and return the underlying NgffImage.

This triggers computation of any lazy operations and returns the NgffImage with computed data.

Returns:

• NgffImage –

  NgffImage with computed data

Source code in zarrnii/core.py

def compute(self) -> nz.NgffImage:
    """
    Compute the dask array and return the underlying NgffImage.

    This triggers computation of any lazy operations and returns
    the NgffImage with computed data.

    Returns:
        NgffImage with computed data
    """
    computed_data = self.ngff_image.data.compute()

    # Create new NgffImage with computed data
    computed_image = _derive_ngff_image(self.ngff_image, data=computed_data)
    return computed_image

zarrnii.core.ZarrNii.get_orientation()

Get the anatomical orientation of the dataset.

This function returns the orientation string (e.g., 'RAS', 'LPI') of the dataset.

Returns:

• str ( str ) –

  The orientation string corresponding to the dataset's anatomical orientation.

Source code in zarrnii/core.py

def get_orientation(self) -> str:
    """
    Get the anatomical orientation of the dataset.

    This function returns the orientation string (e.g., 'RAS', 'LPI') of the dataset.

    Returns:
        str: The orientation string corresponding to the dataset's anatomical orientation.
    """
    return self.orientation

zarrnii.core.ZarrNii.get_zooms(axes_order=None)

Get voxel spacing (zooms) from NgffImage scale.

Parameters:

• axes_order (str, default: None ) –

  Spatial axes order, defaults to self.axes_order

Returns:

• ndarray –

  Array of voxel spacings

Source code in zarrnii/core.py

def get_zooms(self, axes_order: str = None) -> np.ndarray:
    """
    Get voxel spacing (zooms) from NgffImage scale.

    Args:
        axes_order: Spatial axes order, defaults to self.axes_order

    Returns:
        Array of voxel spacings
    """
    if axes_order is None:
        axes_order = self.axes_order

    spatial_dims = ["z", "y", "x"] if axes_order == "ZYX" else ["x", "y", "z"]
    zooms = []

    for dim in spatial_dims:
        if dim in self.ngff_image.scale:
            zooms.append(self.ngff_image.scale[dim])
        else:
            zooms.append(1.0)

    return np.array(zooms)

zarrnii.core.ZarrNii.get_origin(axes_order=None)

Get origin (translation) from NgffImage.

Parameters:

• axes_order (str, default: None ) –

  Spatial axes order, defaults to self.axes_order

Returns:

• ndarray –

  Array of origin coordinates

Source code in zarrnii/core.py

def get_origin(self, axes_order: str = None) -> np.ndarray:
    """
    Get origin (translation) from NgffImage.

    Args:
        axes_order: Spatial axes order, defaults to self.axes_order

    Returns:
        Array of origin coordinates
    """
    if axes_order is None:
        axes_order = self.axes_order

    spatial_dims = ["z", "y", "x"] if axes_order == "ZYX" else ["x", "y", "z"]
    origin = []

    for dim in spatial_dims:
        if dim in self.ngff_image.translation:
            origin.append(self.ngff_image.translation[dim])
        else:
            origin.append(0.0)

    return np.array(origin)

zarrnii.core.ZarrNii.get_affine_matrix(axes_order=None)

Construct a 4x4 affine matrix from NGFF metadata (scale/translation), and align it to self.orientation (if provided) using nibabel.orientations.

Parameters:

• axes_order (str, default: None ) –

  Spatial axes order, e.g. 'ZYX' or 'XYZ'. Defaults to 'XYZ'.

Returns:

• ndarray –

  np.ndarray: 4x4 affine matrix.

Source code in zarrnii/core.py

def get_affine_matrix(self, axes_order: str = None) -> np.ndarray:
    """
    Construct a 4x4 affine matrix from NGFF metadata (scale/translation),
    and align it to self.orientation (if provided) using nibabel.orientations.

    Args:
        axes_order: Spatial axes order, e.g. 'ZYX' or 'XYZ'. Defaults to 'XYZ'.

    Returns:
        np.ndarray: 4x4 affine matrix.
    """
    if axes_order is None:
        axes_order = self.axes_order

    if axes_order == "ZYX":
        orientation = reverse_orientation_string(self.orientation)
    else:
        orientation = self.orientation

    # Safely pull scale/translation from metadata (dict-like expected)
    scale_meta = getattr(self.ngff_image, "scale", {}) or {}
    trans_meta = getattr(self.ngff_image, "translation", {}) or {}

    scale = np.ones(
        3,
    )
    trans = np.zeros(
        3,
    )

    for i, dim in enumerate(axes_order):
        s = scale_meta.get(dim.lower())
        if s is not None:
            scale[i] = float(s)

    for i, dim in enumerate(axes_order):
        s = trans_meta.get(dim.lower())
        if s is not None:
            trans[i] = float(s)

    affine = _axcodes2aff(orientation, scale=scale, translate=trans)

    return affine

zarrnii.core.ZarrNii.apply_transform_ref_to_flo_indices(*transforms, ref_znimg, indices)

Transform indices from reference to floating space.

Source code in zarrnii/core.py

def apply_transform_ref_to_flo_indices(self, *transforms, ref_znimg, indices):
    """Transform indices from reference to floating space."""
    # Placeholder implementation - would need full transform logic
    return indices

zarrnii.core.ZarrNii.apply_transform_flo_to_ref_indices(*transforms, ref_znimg, indices)

Transform indices from floating to reference space.

Source code in zarrnii/core.py

def apply_transform_flo_to_ref_indices(self, *transforms, ref_znimg, indices):
    """Transform indices from floating to reference space."""
    # Placeholder implementation - would need full transform logic
    return indices

zarrnii.core.ZarrNii.list_channels()

Get list of available channel labels from OMERO metadata.

Extracts channel labels from OMERO metadata if available, providing human-readable names for multi-channel datasets.

Returns:

• List[str] –

  List of channel label strings. Empty list if no OMERO metadata

• List[str] –

  is available or no channels are defined.

Examples:

>>> # Check available channels
>>> labels = znii.list_channels()
>>> print(f"Available channels: {labels}")
>>> # ['DAPI', 'GFP', 'RFP', 'Cy5']

>>> # Select specific channels by label
>>> selected = znii.select_channels(channel_labels=['DAPI', 'GFP'])

Notes

• Requires OMERO metadata to be present in the dataset
• Returns empty list for datasets without channel metadata
• Labels are extracted from the 'label' field of each channel

Source code in zarrnii/core.py

def list_channels(self) -> List[str]:
    """Get list of available channel labels from OMERO metadata.

    Extracts channel labels from OMERO metadata if available, providing
    human-readable names for multi-channel datasets.

    Returns:
        List of channel label strings. Empty list if no OMERO metadata
        is available or no channels are defined.

    Examples:
        >>> # Check available channels
        >>> labels = znii.list_channels()
        >>> print(f"Available channels: {labels}")
        >>> # ['DAPI', 'GFP', 'RFP', 'Cy5']

        >>> # Select specific channels by label
        >>> selected = znii.select_channels(channel_labels=['DAPI', 'GFP'])

    Notes:
        - Requires OMERO metadata to be present in the dataset
        - Returns empty list for datasets without channel metadata
        - Labels are extracted from the 'label' field of each channel
    """
    if self.omero is None or not hasattr(self.omero, "channels"):
        return []

    return [
        ch.label if hasattr(ch, "label") else ch.get("label", "")
        for ch in self.omero.channels
    ]

zarrnii.core.ZarrNii.select_channels(channels=None, channel_labels=None)

Select specific channels from multi-channel image data.

Creates a new ZarrNii instance containing only the specified channels, reducing memory usage and focusing analysis on channels of interest. Supports selection by both numeric indices and human-readable labels.

Parameters:

• channels (Optional[List[int]], default: None ) –

  List of 0-based channel indices to select. Mutually exclusive with channel_labels

• channel_labels (Optional[List[str]], default: None ) –

  List of channel names to select by label. Requires OMERO metadata. Mutually exclusive with channels

Returns:

• 'ZarrNii' –

  New ZarrNii instance with selected channels and updated metadata

Raises:

• ValueError –

  If both channels and channel_labels specified, or if channel_labels used without OMERO metadata, or if labels not found

• IndexError –

  If channel indices are out of range

Examples:

>>> # Select channels by index
>>> selected = znii.select_channels(channels=[0, 2])

>>> # Select channels by label (requires OMERO metadata)
>>> selected = znii.select_channels(channel_labels=['DAPI', 'GFP'])

>>> # Check available labels first
>>> available = znii.list_channels()
>>> print(f"Available: {available}")
>>> selected = znii.select_channels(channel_labels=available[:2])

Notes

• Preserves all spatial dimensions and timepoints
• Updates OMERO metadata to reflect selected channels
• Maintains spatial transformations and other metadata
• Channel order in output matches selection order

Source code in zarrnii/core.py

def select_channels(
    self,
    channels: Optional[List[int]] = None,
    channel_labels: Optional[List[str]] = None,
) -> "ZarrNii":
    """Select specific channels from multi-channel image data.

    Creates a new ZarrNii instance containing only the specified channels,
    reducing memory usage and focusing analysis on channels of interest.
    Supports selection by both numeric indices and human-readable labels.

    Args:
        channels: List of 0-based channel indices to select.
            Mutually exclusive with channel_labels
        channel_labels: List of channel names to select by label.
            Requires OMERO metadata. Mutually exclusive with channels

    Returns:
        New ZarrNii instance with selected channels and updated metadata

    Raises:
        ValueError: If both channels and channel_labels specified, or if
            channel_labels used without OMERO metadata, or if labels not found
        IndexError: If channel indices are out of range

    Examples:
        >>> # Select channels by index
        >>> selected = znii.select_channels(channels=[0, 2])

        >>> # Select channels by label (requires OMERO metadata)
        >>> selected = znii.select_channels(channel_labels=['DAPI', 'GFP'])

        >>> # Check available labels first
        >>> available = znii.list_channels()
        >>> print(f"Available: {available}")
        >>> selected = znii.select_channels(channel_labels=available[:2])

    Notes:
        - Preserves all spatial dimensions and timepoints
        - Updates OMERO metadata to reflect selected channels
        - Maintains spatial transformations and other metadata
        - Channel order in output matches selection order
    """
    if channels is not None and channel_labels is not None:
        raise ValueError("Cannot specify both 'channels' and 'channel_labels'")

    if channel_labels is not None:
        if self.omero is None:
            raise ValueError(
                "Channel labels were specified but no omero metadata found"
            )

        available_labels = self.list_channels()
        channel_indices = []
        for label in channel_labels:
            if label not in available_labels:
                raise ValueError(f"Channel label '{label}' not found")
            channel_indices.append(available_labels.index(label))
        channels = channel_indices

    if channels is None:
        # Return a copy with all channels
        return self.copy()

    # Check if channel dimension exists
    if "c" not in self.dims:
        raise ValueError("No channel dimension found in the data")

    # Get channel dimension index
    c_idx = self.dims.index("c")

    # Create slice objects for proper dimension indexing
    slices = [slice(None)] * len(self.data.shape)
    slices[c_idx] = channels

    # Select channels from data using proper dimension indexing
    selected_data = self.data[tuple(slices)]

    # Create new NgffImage with selected data
    new_ngff_image = _derive_ngff_image(self.ngff_image, data=selected_data)
    filtered_omero = None
    if self.omero is not None and hasattr(self.omero, "channels"):

        class FilteredOmero:
            def __init__(self, channels):
                self.channels = channels

        filtered_channels = [self.omero.channels[i] for i in channels]
        filtered_omero = FilteredOmero(filtered_channels)

    return ZarrNii(
        ngff_image=new_ngff_image,
        axes_order=self.axes_order,
        xyz_orientation=self.xyz_orientation,
        _omero=filtered_omero,
    )

zarrnii.core.ZarrNii.select_timepoints(timepoints=None)

Select timepoints from the image data and return a new ZarrNii instance.

Parameters:

• timepoints (Optional[List[int]], default: None ) –

  Timepoint indices to select

Returns:

• 'ZarrNii' –

  New ZarrNii instance with selected timepoints

Source code in zarrnii/core.py

def select_timepoints(self, timepoints: Optional[List[int]] = None) -> "ZarrNii":
    """
    Select timepoints from the image data and return a new ZarrNii instance.

    Args:
        timepoints: Timepoint indices to select

    Returns:
        New ZarrNii instance with selected timepoints
    """
    if timepoints is None:
        # Return a copy with all timepoints
        return self.copy()

    # Check if time dimension exists
    if "t" not in self.dims:
        raise ValueError("No time dimension found in the data")

    # Get time dimension index
    t_idx = self.dims.index("t")

    # Create slice objects
    slices = [slice(None)] * len(self.data.shape)
    slices[t_idx] = timepoints

    # Select timepoints from data
    selected_data = self.data[tuple(slices)]

    # Create new NgffImage with selected data
    new_ngff_image = _derive_ngff_image(self.ngff_image, data=selected_data)

    return ZarrNii(
        ngff_image=new_ngff_image,
        axes_order=self.axes_order,
        xyz_orientation=self.xyz_orientation,
        _omero=self._omero,  # Timepoint selection doesn't affect omero metadata
    )

zarrnii.core.ZarrNii.to_ngff_image(name=None)

Convert to NgffImage object.

Parameters:

• name (str, default: None ) –

  Optional name for the image

Returns:

• NgffImage –

  NgffImage representation

Source code in zarrnii/core.py

def to_ngff_image(self, name: str = None) -> nz.NgffImage:
    """
    Convert to NgffImage object.

    Args:
        name: Optional name for the image

    Returns:
        NgffImage representation
    """
    if name is None:
        name = self.name

    return _derive_ngff_image(self.ngff_image, data=self.data, name=name)

zarrnii.core.ZarrNii.segment(plugin, chunk_size=None, **kwargs)

Apply segmentation plugin to the image using blockwise processing.

This method applies a segmentation plugin to the image data using dask's blockwise processing for efficient computation on large datasets.

Parameters:

• plugin –

  Segmentation plugin instance or class to apply. The plugin must have a segment(image, metadata=None) method decorated with @hookimpl from :mod:zarrnii.plugins.

• chunk_size (Optional[Tuple[int, ...]], default: None ) –

  Optional chunk size for dask processing. If None, uses current chunks.

• **kwargs –

  Additional arguments passed to the plugin when plugin is a class.

Returns:

• 'ZarrNii' –

  New ZarrNii instance with segmented data as labels

Source code in zarrnii/core.py

def segment(
    self, plugin, chunk_size: Optional[Tuple[int, ...]] = None, **kwargs
) -> "ZarrNii":
    """
    Apply segmentation plugin to the image using blockwise processing.

    This method applies a segmentation plugin to the image data using dask's
    blockwise processing for efficient computation on large datasets.

    Args:
        plugin: Segmentation plugin instance or class to apply.  The plugin
            must have a ``segment(image, metadata=None)`` method decorated
            with ``@hookimpl`` from :mod:`zarrnii.plugins`.
        chunk_size: Optional chunk size for dask processing. If None, uses current chunks.
        **kwargs: Additional arguments passed to the plugin when *plugin* is a class.

    Returns:
        New ZarrNii instance with segmented data as labels
    """
    # Handle plugin instance or class
    if isinstance(plugin, type):
        plugin = plugin(**kwargs)

    if not callable(getattr(plugin, "segment", None)):
        raise TypeError(
            "Plugin must have a callable 'segment' method decorated with @hookimpl"
        )

    # Prepare chunk size
    if chunk_size is not None:
        # Rechunk the data if different chunk size requested
        data = self.data.rechunk(chunk_size)
    else:
        data = self.data

    # Create metadata dict to pass to plugin
    metadata = {
        "axes_order": self.axes_order,
        "orientation": self.xyz_orientation,
        "shape": self.shape,
        "dims": self.dims,
        "scale": self.scale,
        "translation": self.translation,
    }

    # Create a wrapper function for map_blocks
    def segment_block(block):
        """Wrapper function to apply segmentation to a single block."""
        # Handle single blocks
        return plugin.segment(block, metadata)

    # Apply segmentation using dask map_blocks
    segmented_data = da.map_blocks(
        segment_block,
        data,
        dtype=np.uint8,  # Segmentation results are typically uint8
        meta=np.array([], dtype=np.uint8),  # Provide meta information
    )

    # Derive a name from the plugin's name hook if available, else use class name
    plugin_name_func = getattr(plugin, "segmentation_plugin_name", None)
    plugin_label = (
        plugin_name_func().lower().replace(" ", "_")
        if callable(plugin_name_func)
        else type(plugin).__name__.lower()
    )

    # Create copy with segmented data
    segmented_znimg = self.copy(name=f"{self.name}_segmented_{plugin_label}")
    segmented_znimg.data = segmented_data

    # Return new ZarrNii instance
    return segmented_znimg

zarrnii.core.ZarrNii.segment_otsu(nbins=256, chunk_size=None)

Apply local Otsu thresholding segmentation to the image.

Convenience method for local Otsu thresholding segmentation. This computes the threshold locally for each processing block.

Parameters:

• nbins (int, default: 256 ) –

  Number of bins for histogram computation (default: 256)

• chunk_size (Optional[Tuple[int, ...]], default: None ) –

  Optional chunk size for dask processing

Returns:

• 'ZarrNii' –

  New ZarrNii instance with binary segmentation

Source code in zarrnii/core.py

def segment_otsu(
    self, nbins: int = 256, chunk_size: Optional[Tuple[int, ...]] = None
) -> "ZarrNii":
    """
    Apply local Otsu thresholding segmentation to the image.

    Convenience method for local Otsu thresholding segmentation.
    This computes the threshold locally for each processing block.

    Args:
        nbins: Number of bins for histogram computation (default: 256)
        chunk_size: Optional chunk size for dask processing

    Returns:
        New ZarrNii instance with binary segmentation
    """
    from .plugins.segmentation import LocalOtsuSegmentation

    plugin = LocalOtsuSegmentation(nbins=nbins)
    return self.segment(plugin, chunk_size=chunk_size)

zarrnii.core.ZarrNii.segment_threshold(thresholds, inclusive=True, chunk_size=None)

Apply threshold-based segmentation to the image.

Convenience method for threshold-based segmentation using either manual threshold values or computed thresholds.

Parameters:

• thresholds (Union[float, List[float]]) –

  Single threshold value or list of threshold values. For single threshold, creates binary segmentation (0/1). For multiple thresholds, creates multi-class segmentation (0/1/2/...).

• inclusive (bool, default: True ) –

  Whether thresholds are inclusive (default: True). If True, pixels >= threshold are labeled as foreground. If False, pixels > threshold are labeled as foreground.

• chunk_size (Optional[Tuple[int, ...]], default: None ) –

  Optional chunk size for dask processing

Returns:

• 'ZarrNii' –

  New ZarrNii instance with labeled segmentation

Examples:

>>> # Binary threshold segmentation
>>> segmented = znimg.segment_threshold(0.5)
>>>
>>> # Multi-level threshold segmentation
>>> thresholds = znimg.compute_otsu_thresholds(classes=3)
>>> segmented = znimg.segment_threshold(thresholds[1:-1])  # Exclude min/max values

Source code in zarrnii/core.py

def segment_threshold(
    self,
    thresholds: Union[float, List[float]],
    inclusive: bool = True,
    chunk_size: Optional[Tuple[int, ...]] = None,
) -> "ZarrNii":
    """
    Apply threshold-based segmentation to the image.

    Convenience method for threshold-based segmentation using either
    manual threshold values or computed thresholds.

    Args:
        thresholds: Single threshold value or list of threshold values.
            For single threshold, creates binary segmentation (0/1).
            For multiple thresholds, creates multi-class segmentation (0/1/2/...).
        inclusive: Whether thresholds are inclusive (default: True).
            If True, pixels >= threshold are labeled as foreground.
            If False, pixels > threshold are labeled as foreground.
        chunk_size: Optional chunk size for dask processing

    Returns:
        New ZarrNii instance with labeled segmentation

    Examples:
        >>> # Binary threshold segmentation
        >>> segmented = znimg.segment_threshold(0.5)
        >>>
        >>> # Multi-level threshold segmentation
        >>> thresholds = znimg.compute_otsu_thresholds(classes=3)
        >>> segmented = znimg.segment_threshold(thresholds[1:-1])  # Exclude min/max values
    """
    from .plugins.segmentation import ThresholdSegmentation

    plugin = ThresholdSegmentation(thresholds=thresholds, inclusive=inclusive)
    return self.segment(plugin, chunk_size=chunk_size)

zarrnii.core.ZarrNii.compute_histogram(bins=None, range=None, mask=None, **kwargs)

Compute histogram of the image.

This method computes the histogram of image intensities, optionally using a mask to weight the computation. The histogram is computed using dask for efficient processing of large datasets.

Parameters:

• bins (Optional[int], default: None ) –

  Number of histogram bins (default: bin width 1, bins=max - min + 1)

• range (Optional[Tuple[float, float]], default: None ) –

  Optional tuple (min, max) defining histogram range. If None, uses the full range of the data

• mask (Optional['ZarrNii'], default: None ) –

  Optional ZarrNii mask of same shape as image. Only pixels where mask > 0 are included in histogram computation

• **kwargs (Any, default: {} ) –

  Additional arguments passed to dask.array.histogram

Returns:

• Array –

  Tuple of (histogram_counts, bin_edges) where:

• Array –
  • histogram_counts: dask array of histogram bin counts
• Tuple[Array, Array] –
  • bin_edges: dask array of bin edge values (length = bins + 1)

Examples:

>>> # Compute histogram
>>> hist, bin_edges = znimg.compute_histogram(bins=128)
>>>
>>> # Compute histogram with mask
>>> mask = znimg > 0.5
>>> hist_masked, _ = znimg.compute_histogram(mask=mask)

Source code in zarrnii/core.py

def compute_histogram(
    self,
    bins: Optional[int] = None,
    range: Optional[Tuple[float, float]] = None,
    mask: Optional["ZarrNii"] = None,
    **kwargs: Any,
) -> Tuple[da.Array, da.Array]:
    """
    Compute histogram of the image.

    This method computes the histogram of image intensities, optionally using
    a mask to weight the computation. The histogram is computed using dask for
    efficient processing of large datasets.

    Args:
        bins: Number of histogram bins (default: bin width 1, bins=max - min + 1)
        range: Optional tuple (min, max) defining histogram range. If None,
            uses the full range of the data
        mask: Optional ZarrNii mask of same shape as image. Only pixels
            where mask > 0 are included in histogram computation
        **kwargs: Additional arguments passed to dask.array.histogram

    Returns:
        Tuple of (histogram_counts, bin_edges) where:
        - histogram_counts: dask array of histogram bin counts
        - bin_edges: dask array of bin edge values (length = bins + 1)

    Examples:
        >>> # Compute histogram
        >>> hist, bin_edges = znimg.compute_histogram(bins=128)
        >>>
        >>> # Compute histogram with mask
        >>> mask = znimg > 0.5
        >>> hist_masked, _ = znimg.compute_histogram(mask=mask)
    """
    from .analysis import compute_histogram

    mask_data = mask.darr if mask is not None else None
    return compute_histogram(
        self.darr, bins=bins, range=range, mask=mask_data, **kwargs
    )

zarrnii.core.ZarrNii.compute_otsu_thresholds(classes=2, bins=None, range=None, mask=None, return_figure=False)

Compute Otsu multi-level thresholds for the image.

This method first computes the histogram of the image, then uses scikit-image's threshold_multiotsu to compute optimal threshold values.

Parameters:

• classes (int, default: 2 ) –

  Number of classes to separate data into (default: 2). Must be >= 2. For classes=2, returns 1 threshold. For classes=k, returns k-1 thresholds.

• bins (Optional[int], default: None ) –

  Number of histogram bins (default: bin width 1, bins=max - min + 1)

• range (Optional[Tuple[float, float]], default: None ) –

  Optional tuple (min, max) defining histogram range. If None, uses the full range of the data

• mask (Optional['ZarrNii'], default: None ) –

  Optional ZarrNii mask of same shape as image. Only pixels where mask > 0 are included in histogram computation

• return_figure (bool, default: False ) –

  If True, returns a tuple containing thresholds and a matplotlib figure with the histogram and annotated threshold lines (default: False).

Returns:

• Union[List[float], Tuple[List[float], Any]] –

  If return_figure is False (default): List of threshold values. For classes=k, returns k+1 values: [0, threshold1, threshold2, ..., threshold_k-1, max_intensity] where 0 represents the minimum and max_intensity represents the maximum.

• Union[List[float], Tuple[List[float], Any]] –

  If return_figure is True: Tuple of (thresholds, figure) where figure is a matplotlib Figure object showing the histogram with annotated threshold lines.

Examples:

>>> # Compute binary threshold (2 classes)
>>> thresholds = znimg.compute_otsu_thresholds(classes=2)
>>> print(f"Binary thresholds: {thresholds}")
>>>
>>> # Compute multi-level thresholds (3 classes)
>>> thresholds = znimg.compute_otsu_thresholds(classes=3)
>>> print(f"Multi-level thresholds: {thresholds}")
>>>
>>> # Get histogram data along with thresholds
>>> thresholds, (hist, bin_edges) = znimg.compute_otsu_thresholds(
...     classes=2, return_histogram=True
... )
>>>
>>> # Generate a figure with annotated thresholds
>>> thresholds, fig = znimg.compute_otsu_thresholds(
...     classes=2, return_figure=True
... )
>>> fig.savefig('otsu_thresholds.png')

Source code in zarrnii/core.py

def compute_otsu_thresholds(
    self,
    classes: int = 2,
    bins: Optional[int] = None,
    range: Optional[Tuple[float, float]] = None,
    mask: Optional["ZarrNii"] = None,
    return_figure: bool = False,
) -> Union[
    List[float],
    Tuple[List[float], Any],
]:
    """
    Compute Otsu multi-level thresholds for the image.

    This method first computes the histogram of the image, then uses
    scikit-image's threshold_multiotsu to compute optimal threshold values.

    Args:
        classes: Number of classes to separate data into (default: 2).
            Must be >= 2. For classes=2, returns 1 threshold. For classes=k,
            returns k-1 thresholds.
        bins: Number of histogram bins (default: bin width 1, bins=max - min + 1)
        range: Optional tuple (min, max) defining histogram range. If None,
            uses the full range of the data
        mask: Optional ZarrNii mask of same shape as image. Only pixels
            where mask > 0 are included in histogram computation
        return_figure: If True, returns a tuple containing thresholds and a
            matplotlib figure with the histogram and annotated threshold lines
            (default: False).

    Returns:
        If return_figure is False (default):
            List of threshold values. For classes=k, returns k+1 values:
            [0, threshold1, threshold2, ..., threshold_k-1, max_intensity]
            where 0 represents the minimum and max_intensity represents the maximum.

        If return_figure is True:
            Tuple of (thresholds, figure) where figure is a matplotlib Figure
            object showing the histogram with annotated threshold lines.

    Examples:
        >>> # Compute binary threshold (2 classes)
        >>> thresholds = znimg.compute_otsu_thresholds(classes=2)
        >>> print(f"Binary thresholds: {thresholds}")
        >>>
        >>> # Compute multi-level thresholds (3 classes)
        >>> thresholds = znimg.compute_otsu_thresholds(classes=3)
        >>> print(f"Multi-level thresholds: {thresholds}")
        >>>
        >>> # Get histogram data along with thresholds
        >>> thresholds, (hist, bin_edges) = znimg.compute_otsu_thresholds(
        ...     classes=2, return_histogram=True
        ... )
        >>>
        >>> # Generate a figure with annotated thresholds
        >>> thresholds, fig = znimg.compute_otsu_thresholds(
        ...     classes=2, return_figure=True
        ... )
        >>> fig.savefig('otsu_thresholds.png')
    """
    from .analysis import compute_otsu_thresholds

    # First compute histogram
    hist, bin_edges = self.compute_histogram(bins=bins, range=range, mask=mask)

    # Then compute thresholds with optional returns
    return compute_otsu_thresholds(
        hist,
        classes=classes,
        bin_edges=bin_edges,
        return_figure=return_figure,
    )

zarrnii.core.ZarrNii.create_mip(plane='axial', slab_thickness_um=100.0, slab_spacing_um=100.0, channel_colors=None, channel_ranges=None, channel_labels=None, return_slabs=False, scale_units='mm')

Create Maximum Intensity Projection (MIP) visualizations across slabs.

This method generates MIP visualizations by dividing the volume into slabs along the specified plane, computing the maximum intensity projection within each slab, then rendering with channel-specific colors. Returns lazy dask arrays that are computed only when explicitly requested.

Parameters:

• plane (str, default: 'axial' ) –

  Projection plane - one of 'axial', 'coronal', 'sagittal'. - 'axial': projects along z-axis (creates xy slices) - 'coronal': projects along y-axis (creates xz slices) - 'sagittal': projects along x-axis (creates yz slices)

• slab_thickness_um (float, default: 100.0 ) –

  Thickness of each slab in microns (default: 100.0)

• slab_spacing_um (float, default: 100.0 ) –

  Spacing between slab centers in microns (default: 100.0)

• channel_colors (Optional[List[Union[str, Tuple[float, float, float], Tuple[float, float, float, float]]]], default: None ) –

  Optional list of colors for each channel. Each color can be: - Color name string (e.g., 'red', 'green', 'blue') - RGB tuple with values 0-1 (e.g., (1.0, 0.0, 0.0) for red) - RGBA tuple with values 0-1 (e.g., (1.0, 0.0, 0.0, 0.5) for semi-transparent red) If None and OMERO metadata is available, uses OMERO channel colors. Otherwise uses default colors: ['red', 'green', 'blue', 'cyan', 'magenta', 'yellow']

• channel_ranges (Optional[List[Tuple[float, float]]], default: None ) –

  Optional list of (min, max) tuples specifying intensity range for each channel. If None and OMERO metadata is available, uses OMERO window settings. Otherwise uses auto-scaling based on data min/max.

• channel_labels (Optional[List[str]], default: None ) –

  Optional list of channel label names to use for selecting channels from OMERO metadata. If provided, channels are filtered and reordered to match these labels. Requires OMERO metadata to be available.

• return_slabs (bool, default: False ) –

  If True, returns tuple of (mip_list, slab_info_list) where slab_info_list contains metadata about each slab. If False (default), returns only the mip_list.

• scale_units (str, default: 'mm' ) –

  Units for scale values. Either "mm" (millimeters, default) or "um" (microns). The ZarrNii scale values from NGFF/NIfTI are in millimeters by default, so this should typically be left as "mm".

Returns:

• Union[List[Array], Tuple[List[Array], List[dict]]] –

  If return_slabs is False (default): List of 2D dask arrays, each containing an RGB MIP visualization for one slab. Each array has shape (height, width, 3) with RGB values in range [0, 1]. Arrays are lazy and will only be computed when explicitly requested.

• Union[List[Array], Tuple[List[Array], List[dict]]] –

  If return_slabs is True: Tuple of (mip_list, slab_info_list) where: - mip_list: List of 2D RGB dask arrays as described above - slab_info_list: List of dictionaries with slab metadata including: - 'start_um': Start position of slab in microns - 'end_um': End position of slab in microns - 'center_um': Center position of slab in microns - 'start_idx': Start index in array coordinates - 'end_idx': End index in array coordinates

Examples:

>>> # Create axial MIPs with custom intensity ranges
>>> mips = znimg.create_mip(
...     plane='axial',
...     slab_thickness_um=100.0,
...     slab_spacing_um=100.0,
...     channel_colors=['red', 'green'],
...     channel_ranges=[(0.0, 1000.0), (0.0, 5000.0)]
... )
>>>
>>> # Use OMERO metadata for colors and ranges
>>> mips = znimg.create_mip(
...     plane='axial',
...     channel_labels=['DAPI', 'GFP']
... )
>>>
>>> # Use alpha transparency
>>> mips = znimg.create_mip(
...     plane='axial',
...     channel_colors=[(1.0, 0.0, 0.0, 0.7), (0.0, 1.0, 0.0, 0.5)]
... )

Source code in zarrnii/core.py

def create_mip(
    self,
    plane: str = "axial",
    slab_thickness_um: float = 100.0,
    slab_spacing_um: float = 100.0,
    channel_colors: Optional[
        List[
            Union[
                str, Tuple[float, float, float], Tuple[float, float, float, float]
            ]
        ]
    ] = None,
    channel_ranges: Optional[List[Tuple[float, float]]] = None,
    channel_labels: Optional[List[str]] = None,
    return_slabs: bool = False,
    scale_units: str = "mm",
) -> Union[List[da.Array], Tuple[List[da.Array], List[dict]]]:
    """
    Create Maximum Intensity Projection (MIP) visualizations across slabs.

    This method generates MIP visualizations by dividing the volume into slabs
    along the specified plane, computing the maximum intensity projection within
    each slab, then rendering with channel-specific colors. Returns lazy dask
    arrays that are computed only when explicitly requested.

    Args:
        plane: Projection plane - one of 'axial', 'coronal', 'sagittal'.
            - 'axial': projects along z-axis (creates xy slices)
            - 'coronal': projects along y-axis (creates xz slices)
            - 'sagittal': projects along x-axis (creates yz slices)
        slab_thickness_um: Thickness of each slab in microns (default: 100.0)
        slab_spacing_um: Spacing between slab centers in microns (default: 100.0)
        channel_colors: Optional list of colors for each channel. Each color can be:
            - Color name string (e.g., 'red', 'green', 'blue')
            - RGB tuple with values 0-1 (e.g., (1.0, 0.0, 0.0) for red)
            - RGBA tuple with values 0-1 (e.g., (1.0, 0.0, 0.0, 0.5) for semi-transparent red)
            If None and OMERO metadata is available, uses OMERO channel colors.
            Otherwise uses default colors: ['red', 'green', 'blue', 'cyan', 'magenta', 'yellow']
        channel_ranges: Optional list of (min, max) tuples specifying intensity range
            for each channel. If None and OMERO metadata is available, uses OMERO window
            settings. Otherwise uses auto-scaling based on data min/max.
        channel_labels: Optional list of channel label names to use for selecting
            channels from OMERO metadata. If provided, channels are filtered and
            reordered to match these labels. Requires OMERO metadata to be available.
        return_slabs: If True, returns tuple of (mip_list, slab_info_list) where
            slab_info_list contains metadata about each slab. If False (default),
            returns only the mip_list.
        scale_units: Units for scale values. Either "mm" (millimeters, default) or
            "um" (microns). The ZarrNii scale values from NGFF/NIfTI are in millimeters
            by default, so this should typically be left as "mm".

    Returns:
        If return_slabs is False (default):
            List of 2D dask arrays, each containing an RGB MIP visualization for one slab.
            Each array has shape (height, width, 3) with RGB values in range [0, 1].
            Arrays are lazy and will only be computed when explicitly requested.

        If return_slabs is True:
            Tuple of (mip_list, slab_info_list) where:
            - mip_list: List of 2D RGB dask arrays as described above
            - slab_info_list: List of dictionaries with slab metadata including:
                - 'start_um': Start position of slab in microns
                - 'end_um': End position of slab in microns
                - 'center_um': Center position of slab in microns
                - 'start_idx': Start index in array coordinates
                - 'end_idx': End index in array coordinates

    Examples:
        >>> # Create axial MIPs with custom intensity ranges
        >>> mips = znimg.create_mip(
        ...     plane='axial',
        ...     slab_thickness_um=100.0,
        ...     slab_spacing_um=100.0,
        ...     channel_colors=['red', 'green'],
        ...     channel_ranges=[(0.0, 1000.0), (0.0, 5000.0)]
        ... )
        >>>
        >>> # Use OMERO metadata for colors and ranges
        >>> mips = znimg.create_mip(
        ...     plane='axial',
        ...     channel_labels=['DAPI', 'GFP']
        ... )
        >>>
        >>> # Use alpha transparency
        >>> mips = znimg.create_mip(
        ...     plane='axial',
        ...     channel_colors=[(1.0, 0.0, 0.0, 0.7), (0.0, 1.0, 0.0, 0.5)]
        ... )
    """
    from .analysis import create_mip_visualization

    return create_mip_visualization(
        image=self.darr,
        dims=self.dims,
        scale=self.scale,
        plane=plane,
        slab_thickness_um=slab_thickness_um,
        slab_spacing_um=slab_spacing_um,
        channel_colors=channel_colors,
        channel_ranges=channel_ranges,
        omero_metadata=self.omero,
        channel_labels=channel_labels,
        return_slabs=return_slabs,
        scale_units=scale_units,
    )

zarrnii.core.ZarrNii.compute_region_properties(output_properties=None, depth=10, boundary='none', rechunk=None, output_path=None, region_filters=None)

Compute properties of binary segmentation objects with coordinate transformation.

This method processes the binary image (typically output from a segmentation plugin) to identify connected components and compute their properties using scikit-image's regionprops. Coordinate-based properties (like centroid) are automatically transformed to physical coordinates. The method processes the image chunk-by-chunk with overlap to handle objects that span chunk boundaries.

This is a generalized method that allows extraction of any combination of regionprops properties, enabling downstream quantification and filtering.

For large datasets, use the output_path parameter to write properties directly to a Parquet file on disk instead of returning them in memory.

Parameters:

• output_properties (Optional[Union[List[str], Dict[str, str]]], default: None ) –

  Properties to extract. Can be either: - List of regionprops property names to extract. Property names are used as output keys. - Dict mapping regionprops property names to custom output names. Example: {'area': 'nvoxels', 'equivalent_diameter_area': 'equivdiam'} Coordinate properties ('centroid', 'centroid_weighted') are automatically transformed to physical coordinates and split into separate x, y, z columns. When using a dict, coordinate property output names are suffixed with '_x', '_y', '_z' (e.g., {'centroid': 'loc'} gives 'loc_x', 'loc_y', 'loc_z'). Default is ['centroid']. Example list: ['centroid', 'area', 'equivalent_diameter_area'] Example dict: {'area': 'nvoxels', 'centroid': 'position'}

• depth (Union[int, Tuple[int, ...], Dict[int, int]], default: 10 ) –

  Number of elements of overlap between chunks. Can be: - int: same depth for all dimensions (default: 10) - tuple: different depth per dimension - dict: mapping dimension index to depth

• boundary (str, default: 'none' ) –

  How to handle boundaries when adding overlap. Options include 'none', 'reflect', 'periodic', 'nearest', or constant values. Default is 'none' (no padding at array boundaries).

• rechunk (Optional[Union[int, Tuple[int, ...]]], default: None ) –

  Optional rechunking specification before processing. Can be: - int: target chunk size for all dimensions - tuple: target chunk size per dimension - None: use existing chunks (default)

• output_path (Optional[str], default: None ) –

  Optional path to write properties to Parquet file instead of returning them in memory. If provided, properties are written to this file path and None is returned. Use this for large datasets. If None (default), properties are returned as a dict.

• region_filters (Optional[Dict[str, Tuple[str, Any]]], default: None ) –

  Optional dictionary specifying filters to apply to detected regions based on scikit-image regionprops properties. Each key is a property name (e.g., 'area', 'perimeter', 'eccentricity'), and the value is a tuple of (operator, threshold) where operator is one of: '>', '>=', '<', '<=', '==', '!='. Regions that don't satisfy ALL filters are excluded. Example: {'area': ('>=', 30), 'eccentricity': ('<', 0.9)} If None (default), no filtering is applied.

Returns:

• Optional[Dict[str, ndarray]] –

  Optional[Dict[str, numpy.ndarray]]: If output_path is None, returns a dictionary mapping property names (or custom names if dict was used) to numpy arrays. For coordinate properties like 'centroid', the keys are suffixed with _x, _y, _z (e.g., 'centroid_x' or 'custom_name_x') containing physical coordinates. Scalar properties have their name (or custom name) as the key. If output_path is provided, writes to Parquet file and returns None.

Notes

• This method expects a binary image (e.g., from segment_threshold).
• Objects with centroids in overlap regions are filtered to avoid duplicates.
• Uses 26-connectivity (connectivity=3) for 3D connected component labeling.
• Coordinate properties ('centroid', 'centroid_weighted') are transformed to physical coordinates and split into suffixed columns (e.g., 'centroid_x', 'centroid_y', 'centroid_z' or when renamed via dict, 'custom_name_x', 'custom_name_y', 'custom_name_z').
• Scalar properties are included directly without transformation.
• Available regionprops properties include: 'area', 'area_bbox', 'centroid', 'eccentricity', 'equivalent_diameter_area', 'euler_number', 'extent', 'feret_diameter_max', 'axis_major_length', 'axis_minor_length', 'moments', 'perimeter', 'solidity', and more.

Examples:

>>> # Extract centroid and area
>>> props = binary.compute_region_properties(
...     output_properties=['centroid', 'area'],
...     depth=5
... )
>>> print(f"Found {len(props['centroid_x'])} objects")
>>> print(f"Areas: {props['area']}")
>>>
>>> # Extract multiple properties with filtering
>>> props = binary.compute_region_properties(
...     output_properties=['centroid', 'area', 'equivalent_diameter_area'],
...     depth=5,
...     region_filters={'area': ('>=', 30)}
... )
>>>
>>> # Use dict to rename output columns
>>> props = binary.compute_region_properties(
...     output_properties={'area': 'nvoxels', 'centroid': 'position'},
...     depth=5
... )
>>> print(f"Number of voxels: {props['nvoxels']}")
>>> print(f"Position X: {props['position_x']}")
>>>
>>> # Write to Parquet for large datasets
>>> binary.compute_region_properties(
...     output_properties=['centroid', 'area', 'eccentricity'],
...     depth=5,
...     output_path='region_props.parquet'
... )

Source code in zarrnii/core.py

def compute_region_properties(
    self,
    output_properties: Optional[Union[List[str], Dict[str, str]]] = None,
    depth: Union[int, Tuple[int, ...], Dict[int, int]] = 10,
    boundary: str = "none",
    rechunk: Optional[Union[int, Tuple[int, ...]]] = None,
    output_path: Optional[str] = None,
    region_filters: Optional[Dict[str, Tuple[str, Any]]] = None,
) -> Optional[Dict[str, np.ndarray]]:
    """
    Compute properties of binary segmentation objects with coordinate transformation.

    This method processes the binary image (typically output from a segmentation
    plugin) to identify connected components and compute their properties using
    scikit-image's regionprops. Coordinate-based properties (like centroid) are
    automatically transformed to physical coordinates. The method processes the
    image chunk-by-chunk with overlap to handle objects that span chunk boundaries.

    This is a generalized method that allows extraction of any combination of
    regionprops properties, enabling downstream quantification and filtering.

    For large datasets, use the output_path parameter to write properties directly
    to a Parquet file on disk instead of returning them in memory.

    Args:
        output_properties: Properties to extract. Can be either:
            - List of regionprops property names to extract. Property names are
              used as output keys.
            - Dict mapping regionprops property names to custom output names.
              Example: {'area': 'nvoxels', 'equivalent_diameter_area': 'equivdiam'}
            Coordinate properties ('centroid', 'centroid_weighted') are automatically
            transformed to physical coordinates and split into separate x, y, z
            columns. When using a dict, coordinate property output names are suffixed
            with '_x', '_y', '_z' (e.g., {'centroid': 'loc'} gives 'loc_x', 'loc_y',
            'loc_z').
            Default is ['centroid'].
            Example list: ['centroid', 'area', 'equivalent_diameter_area']
            Example dict: {'area': 'nvoxels', 'centroid': 'position'}
        depth: Number of elements of overlap between chunks. Can be:
            - int: same depth for all dimensions (default: 10)
            - tuple: different depth per dimension
            - dict: mapping dimension index to depth
        boundary: How to handle boundaries when adding overlap. Options include
            'none', 'reflect', 'periodic', 'nearest', or constant values.
            Default is 'none' (no padding at array boundaries).
        rechunk: Optional rechunking specification before processing. Can be:
            - int: target chunk size for all dimensions
            - tuple: target chunk size per dimension
            - None: use existing chunks (default)
        output_path: Optional path to write properties to Parquet file instead of
            returning them in memory. If provided, properties are written to this
            file path and None is returned. Use this for large datasets.
            If None (default), properties are returned as a dict.
        region_filters: Optional dictionary specifying filters to apply to detected
            regions based on scikit-image regionprops properties. Each key is a
            property name (e.g., 'area', 'perimeter', 'eccentricity'), and the value
            is a tuple of (operator, threshold) where operator is one of:
            '>', '>=', '<', '<=', '==', '!='.
            Regions that don't satisfy ALL filters are excluded.
            Example: {'area': ('>=', 30), 'eccentricity': ('<', 0.9)}
            If None (default), no filtering is applied.

    Returns:
        Optional[Dict[str, numpy.ndarray]]: If output_path is None, returns a
            dictionary mapping property names (or custom names if dict was used)
            to numpy arrays. For coordinate properties like 'centroid', the keys
            are suffixed with _x, _y, _z (e.g., 'centroid_x' or 'custom_name_x')
            containing physical coordinates.
            Scalar properties have their name (or custom name) as the key.
            If output_path is provided, writes to Parquet file and returns None.

    Notes:
        - This method expects a binary image (e.g., from segment_threshold).
        - Objects with centroids in overlap regions are filtered to avoid duplicates.
        - Uses 26-connectivity (connectivity=3) for 3D connected component labeling.
        - Coordinate properties ('centroid', 'centroid_weighted') are transformed
          to physical coordinates and split into suffixed columns (e.g.,
          'centroid_x', 'centroid_y', 'centroid_z' or when renamed via dict,
          'custom_name_x', 'custom_name_y', 'custom_name_z').
        - Scalar properties are included directly without transformation.
        - Available regionprops properties include: 'area', 'area_bbox', 'centroid',
          'eccentricity', 'equivalent_diameter_area', 'euler_number', 'extent',
          'feret_diameter_max', 'axis_major_length', 'axis_minor_length',
          'moments', 'perimeter', 'solidity', and more.

    Examples:
        >>> # Extract centroid and area
        >>> props = binary.compute_region_properties(
        ...     output_properties=['centroid', 'area'],
        ...     depth=5
        ... )
        >>> print(f"Found {len(props['centroid_x'])} objects")
        >>> print(f"Areas: {props['area']}")
        >>>
        >>> # Extract multiple properties with filtering
        >>> props = binary.compute_region_properties(
        ...     output_properties=['centroid', 'area', 'equivalent_diameter_area'],
        ...     depth=5,
        ...     region_filters={'area': ('>=', 30)}
        ... )
        >>>
        >>> # Use dict to rename output columns
        >>> props = binary.compute_region_properties(
        ...     output_properties={'area': 'nvoxels', 'centroid': 'position'},
        ...     depth=5
        ... )
        >>> print(f"Number of voxels: {props['nvoxels']}")
        >>> print(f"Position X: {props['position_x']}")
        >>>
        >>> # Write to Parquet for large datasets
        >>> binary.compute_region_properties(
        ...     output_properties=['centroid', 'area', 'eccentricity'],
        ...     depth=5,
        ...     output_path='region_props.parquet'
        ... )
    """
    from .analysis import compute_region_properties

    return compute_region_properties(
        self.darr,
        affine=self.affine.matrix,
        output_properties=output_properties,
        depth=depth,
        boundary=boundary,
        rechunk=rechunk,
        output_path=output_path,
        region_filters=region_filters,
    )

zarrnii.core.ZarrNii.apply_scaled_processing(plugin, downsample_factor=4, chunk_size=None, upsampled_ome_zarr_path=None, method='default', lowres_znimg=None, **kwargs)

Apply scaled processing plugin using multi-resolution approach.

This method implements a multi-resolution processing pipeline where: 1. The image is downsampled for efficient computation (or a pre-computed downsampled image is provided via lowres_znimg) 2. The plugin's lowres_func is applied to the downsampled data 3. The result is upsampled and highres_func is applied to full-resolution data, using one of two back-end strategies selected by method.

Two back-end methods are available:

"default" (rechunk/OME-Zarr upsample) The low-resolution result is upsampled by rechunking, materialised to a temporary OME-Zarr file, and then highres_func is called with two full-resolution dask arrays (the original data and the upsampled correction field). This is the original approach.

"map_blocks" (fused map_blocks upsample) The low-resolution result is kept in memory (small, already computed). Upsampling and highres_func are fused into a single :func:dask.array.map_blocks pass over the full-resolution data. Inside each block, scipy.ndimage.map_coordinates interpolates the correction field at the block's coordinates, and highres_func is called with two NumPy arrays (the block and the interpolated correction). This avoids writing intermediate zarr files and is robust to datasets (e.g., Imaris) where chunk boundaries do not align nicely with the upsampling grid.

Plugin interface Both methods share the same plugin API. highres_func is called with arrays that support NumPy arithmetic (either dask arrays for "default" or plain NumPy arrays for "map_blocks"), so implementations that use np.maximum, np.where, and standard arithmetic operators work correctly with both methods.

Parameters:

• plugin –

  Plugin instance or class to apply. The plugin must have lowres_func(lowres_array: np.ndarray) -> np.ndarray and highres_func(fullres_array, upsampled_output) methods decorated with @hookimpl from :mod:zarrnii.plugins.

• downsample_factor (int, default: 4 ) –

  Factor for downsampling (default: 4). Ignored when lowres_znimg is provided.

• chunk_size (Optional[Tuple[int, ...]], default: None ) –

  Optional chunk size for spatial dimensions in order [Z, Y, X] (or [X, Y, Z] if axes_order is 'XYZ'). If None, defaults to (10, 10, 10). Non-spatial dimensions (time, channel) are automatically assigned singleton chunks. Only used by the "default" method.

• upsampled_ome_zarr_path (Optional[str], default: None ) –

  Path to save the intermediate upsampled OME-Zarr. If None, a system temp directory is used. Only used by the "default" method.

• method (Literal['default', 'map_blocks'], default: 'default' ) –

  Back-end strategy to use. One of "default" (rechunk + OME-Zarr upsample) or "map_blocks" (fused map_blocks interpolation). Default is "default".

• lowres_znimg (Optional['ZarrNii'], default: None ) –

  Pre-computed downsampled :class:ZarrNii image. When provided, the downsampling step is skipped and this image is used as the low-resolution input instead. Useful for reusing a previously computed pyramid level or for applying the same correction to multiple channels. Only used by the "map_blocks" method (ignored for "default").

• **kwargs –

  Additional arguments passed to the plugin constructor when plugin is a class.

Returns:

• 'ZarrNii' –

  New ZarrNii instance with processed data

Raises:

• TypeError –

  If plugin is an instance but keyword arguments are also supplied, or if the plugin is missing the required hooks.

• ValueError –

  If an unsupported method value is given.

Source code in zarrnii/core.py

def apply_scaled_processing(
    self,
    plugin,
    downsample_factor: int = 4,
    chunk_size: Optional[Tuple[int, ...]] = None,
    upsampled_ome_zarr_path: Optional[str] = None,
    method: Literal["default", "map_blocks"] = "default",
    lowres_znimg: Optional["ZarrNii"] = None,
    **kwargs,
) -> "ZarrNii":
    """
    Apply scaled processing plugin using multi-resolution approach.

    This method implements a multi-resolution processing pipeline where:
    1. The image is downsampled for efficient computation (or a pre-computed
       downsampled image is provided via *lowres_znimg*)
    2. The plugin's ``lowres_func`` is applied to the downsampled data
    3. The result is upsampled and ``highres_func`` is applied to full-resolution
       data, using one of two back-end strategies selected by *method*.

    Two back-end methods are available:

    ``"default"`` (rechunk/OME-Zarr upsample)
        The low-resolution result is upsampled by rechunking, materialised to a
        temporary OME-Zarr file, and then ``highres_func`` is called with two
        full-resolution **dask arrays** (the original data and the upsampled
        correction field).  This is the original approach.

    ``"map_blocks"`` (fused map_blocks upsample)
        The low-resolution result is kept in memory (small, already computed).
        Upsampling and ``highres_func`` are fused into a single
        :func:`dask.array.map_blocks` pass over the full-resolution data.
        Inside each block, ``scipy.ndimage.map_coordinates`` interpolates the
        correction field at the block's coordinates, and ``highres_func`` is
        called with two **NumPy arrays** (the block and the interpolated
        correction).  This avoids writing intermediate zarr files and is robust
        to datasets (e.g., Imaris) where chunk boundaries do not align nicely
        with the upsampling grid.

    Plugin interface
        Both methods share the same plugin API.  ``highres_func`` is called
        with arrays that support NumPy arithmetic (either dask arrays for
        ``"default"`` or plain NumPy arrays for ``"map_blocks"``), so
        implementations that use ``np.maximum``, ``np.where``, and standard
        arithmetic operators work correctly with both methods.

    Args:
        plugin: Plugin instance or class to apply.  The plugin must have
            ``lowres_func(lowres_array: np.ndarray) -> np.ndarray`` and
            ``highres_func(fullres_array, upsampled_output)`` methods
            decorated with ``@hookimpl`` from :mod:`zarrnii.plugins`.
        downsample_factor: Factor for downsampling (default: 4).  Ignored
            when *lowres_znimg* is provided.
        chunk_size: Optional chunk size for spatial dimensions in order
            [Z, Y, X] (or [X, Y, Z] if axes_order is 'XYZ').  If ``None``,
            defaults to ``(10, 10, 10)``.  Non-spatial dimensions (time,
            channel) are automatically assigned singleton chunks.  Only
            used by the ``"default"`` method.
        upsampled_ome_zarr_path: Path to save the intermediate upsampled
            OME-Zarr.  If ``None``, a system temp directory is used.  Only
            used by the ``"default"`` method.
        method: Back-end strategy to use.  One of ``"default"`` (rechunk
            + OME-Zarr upsample) or ``"map_blocks"`` (fused
            map_blocks interpolation).  Default is ``"default"``.
        lowres_znimg: Pre-computed downsampled :class:`ZarrNii` image.
            When provided, the downsampling step is skipped and this image
            is used as the low-resolution input instead.  Useful for
            reusing a previously computed pyramid level or for applying the
            same correction to multiple channels.  Only used by the
            ``"map_blocks"`` method (ignored for ``"default"``).
        **kwargs: Additional arguments passed to the plugin constructor when
            *plugin* is a class.

    Returns:
        New ZarrNii instance with processed data

    Raises:
        TypeError: If *plugin* is an instance but keyword arguments are
            also supplied, or if the plugin is missing the required hooks.
        ValueError: If an unsupported *method* value is given.
    """
    if method not in ("default", "map_blocks"):
        raise ValueError(
            f"Unsupported method {method!r}. " "Choose 'default' or 'map_blocks'."
        )

    # Handle plugin instance or class
    if isinstance(plugin, type):
        plugin = plugin(**kwargs)
    elif kwargs:
        raise TypeError(
            f"apply_scaled_processing() received unexpected keyword arguments "
            f"for a plugin instance: {list(kwargs.keys())}. "
            f"Keyword arguments are only accepted when 'plugin' is a class."
        )

    if not callable(getattr(plugin, "lowres_func", None)) or not callable(
        getattr(plugin, "highres_func", None)
    ):
        raise TypeError(
            "Plugin must have callable 'lowres_func' and 'highres_func' methods "
            "decorated with @hookimpl"
        )

    if method == "map_blocks":
        return self._apply_scaled_processing_map_blocks(
            plugin, downsample_factor=downsample_factor, lowres_znimg=lowres_znimg
        )

    # ------------------------------------------------------------------
    # "default" method: rechunk + OME-Zarr upsample
    # ------------------------------------------------------------------

    # Step 1: Downsample the data for low-resolution processing
    _lowres_znimg = self.downsample(level=int(np.log2(downsample_factor)))

    # Convert to numpy array for lowres processing
    lowres_array = _lowres_znimg.data.compute()

    # Step 2: Apply low-resolution function and prepare for upsampling
    # Construct chunk size: map spatial dimensions to their positions
    spatial_chunk_size = chunk_size if chunk_size is not None else (10, 10, 10)

    # Determine spatial dimension order based on axes_order
    if _lowres_znimg.axes_order == "XYZ":
        spatial_dim_order = ["x", "y", "z"]
    else:  # ZYX
        spatial_dim_order = ["z", "y", "x"]

    # Create a mapping from spatial dimension name to chunk size
    spatial_chunk_map = {
        dim: size for dim, size in zip(spatial_dim_order, spatial_chunk_size)
    }

    # Build lowres_chunks by iterating through dims and assigning chunk sizes
    lowres_chunks = []
    for dim in _lowres_znimg.dims:
        dim_lower = dim.lower()
        if dim_lower in spatial_chunk_map:
            lowres_chunks.append(spatial_chunk_map[dim_lower])
        else:
            # Non-spatial dimension (time, channel): singleton chunk
            lowres_chunks.append(1)

    lowres_chunks = tuple(lowres_chunks)

    _lowres_znimg.data = da.from_array(
        plugin.lowres_func(lowres_array), chunks=lowres_chunks
    )

    # Use temporary OME-Zarr to break up dask graph for performance
    import tempfile

    if upsampled_ome_zarr_path is None:
        upsampled_ome_zarr_path = tempfile.mkdtemp(suffix="_SPIM.ome.zarr")

    # Step 3: Upsample using dask-based upsampling, save to ome zarr
    _lowres_znimg.upsample(to_shape=self.shape).to_ome_zarr(
        upsampled_ome_zarr_path, max_layer=1
    )

    upsampled_znimg = ZarrNii.from_ome_zarr(upsampled_ome_zarr_path)

    corrected_znimg = self.copy()

    # Step 4: Apply high-resolution function
    # rechunk original data to use same chunksize as upsampled_data, before multiplying
    corrected_znimg.data = plugin.highres_func(
        self.data.rechunk(upsampled_znimg.data.chunks), upsampled_znimg.data
    )

    return corrected_znimg

zarrnii.core.ZarrNii.destripe(channel=0, **kwargs)

Apply destriping.

Parameters:

• **kwargs –

  Additional arguments passed to destripe()

Returns:

• 'ZarrNii' –

  New ZarrNii instance with destriped data

Source code in zarrnii/core.py

def destripe(
    self,
    channel=0,
    **kwargs,
) -> "ZarrNii":
    """
    Apply destriping.

    Args:
        **kwargs: Additional arguments passed to destripe()

    Returns:
        New ZarrNii instance with destriped data
    """

    from .destripe import destripe

    destriped_znimg = self.copy()

    # Extract the selected channel as a 3D array
    img_3d = self.data[channel, :, :, :].squeeze()

    # Compute destriped channel data and ensure it is a Dask array
    destriped_channel = da.asarray(destripe(img_3d, **kwargs))

    # Ensure the destriped channel has the same shape as the original channel
    original_channel = self.data[channel, :, :, :]
    if destriped_channel.shape != original_channel.shape:
        destriped_channel = destriped_channel.reshape(original_channel.shape)

    # Rebuild the data array with the updated channel, avoiding in-place mutation
    data = self.data
    num_channels = data.shape[0]
    channels = []
    for c in range(num_channels):
        if c == channel:
            channels.append(destriped_channel)
        else:
            channels.append(data[c, :, :, :])

    destriped_znimg.data = da.stack(channels, axis=0)

    return destriped_znimg

Functions

zarrnii.core.load_ngff_image(store_or_path, level=0, channels=None, channel_labels=None, timepoints=None, storage_options=None)

Load an NgffImage from an OME-Zarr store.

This function provides flexible loading of OME-Zarr data with support for ZIP stores, channel selection, and timepoint selection. It handles various storage backends through fsspec.

Parameters:

• store_or_path (Union[str, Any]) –

  Store or path to the OME-Zarr file. Supports local paths, remote URLs, and .zip extensions for ZipStore access

• level (int, default: 0 ) –

  Pyramid level to load (0 = highest resolution, higher = lower resolution)

• channels (Optional[List[int]], default: None ) –

  List of channel indices to load (0-based). If None, loads all channels

• channel_labels (Optional[List[str]], default: None ) –

  List of channel names to load by label. Requires OMERO metadata

• timepoints (Optional[List[int]], default: None ) –

  List of timepoint indices to load (0-based). If None, loads all timepoints

• storage_options (Optional[Dict[str, Any]], default: None ) –

  Additional options passed to zarr storage backend

Returns:

• NgffImage –

  NgffImage object containing the loaded image data and metadata at the specified level

Raises:

• FileNotFoundError –

  If the store or path does not exist

• ValueError –

  If level is out of range or invalid channel/timepoint indices

• KeyError –

  If channel_labels are specified but not found in metadata

Examples:

>>> # Load highest resolution level
>>> img = load_ngff_image("/path/to/data.zarr")

>>> # Load specific channels by index
>>> img = load_ngff_image("/path/to/data.zarr", channels=[0, 2])

>>> # Load from ZIP store
>>> img = load_ngff_image("/path/to/data.zarr.zip", level=1)

Source code in zarrnii/core.py

def load_ngff_image(
    store_or_path: Union[str, Any],
    level: int = 0,
    channels: Optional[List[int]] = None,
    channel_labels: Optional[List[str]] = None,
    timepoints: Optional[List[int]] = None,
    storage_options: Optional[Dict[str, Any]] = None,
) -> nz.NgffImage:
    """Load an NgffImage from an OME-Zarr store.

    This function provides flexible loading of OME-Zarr data with support for
    ZIP stores, channel selection, and timepoint selection. It handles various
    storage backends through fsspec.

    Args:
        store_or_path: Store or path to the OME-Zarr file. Supports local paths,
            remote URLs, and .zip extensions for ZipStore access
        level: Pyramid level to load (0 = highest resolution, higher = lower resolution)
        channels: List of channel indices to load (0-based). If None, loads all channels
        channel_labels: List of channel names to load by label. Requires OMERO metadata
        timepoints: List of timepoint indices to load (0-based). If None, loads all timepoints
        storage_options: Additional options passed to zarr storage backend

    Returns:
        NgffImage object containing the loaded image data and metadata at the specified level

    Raises:
        FileNotFoundError: If the store or path does not exist
        ValueError: If level is out of range or invalid channel/timepoint indices
        KeyError: If channel_labels are specified but not found in metadata

    Examples:
        >>> # Load highest resolution level
        >>> img = load_ngff_image("/path/to/data.zarr")

        >>> # Load specific channels by index
        >>> img = load_ngff_image("/path/to/data.zarr", channels=[0, 2])

        >>> # Load from ZIP store
        >>> img = load_ngff_image("/path/to/data.zarr.zip", level=1)
    """
    import zarr

    # Handle OME-Zarr zip files by creating a ZipStore
    if isinstance(store_or_path, str) and _is_ome_zarr_zip_path(store_or_path):
        store = zarr.storage.ZipStore(store_or_path, mode="r")
        multiscales = nz.from_ngff_zarr(store, storage_options=storage_options)
        store.close()
    else:
        # Load the multiscales object normally
        multiscales = nz.from_ngff_zarr(store_or_path, storage_options=storage_options)

    # Get the specified level
    ngff_image = multiscales.images[level]

    # Handle channel and timepoint selection if specified
    if channels is not None or channel_labels is not None or timepoints is not None:
        ngff_image = _select_dimensions_from_image(
            ngff_image, multiscales, channels, channel_labels, timepoints
        )

    return ngff_image

zarrnii.core.save_ngff_image(ngff_image, store_or_path, max_layer=4, scale_factors=None, xyz_orientation=None, **kwargs)

Save an NgffImage to an OME-Zarr store with multiscale pyramid.

Creates a multiscale OME-Zarr dataset from the input NgffImage, with automatic generation of pyramid levels for efficient viewing and processing at different scales.

Parameters:

• ngff_image (NgffImage) –

  NgffImage object to save containing data and metadata

• store_or_path (Union[str, Any]) –

  Target store or path. Supports local paths, remote URLs, and .zip extensions for ZipStore creation

• max_layer (int, default: 4 ) –

  Maximum number of pyramid levels to create (including level 0)

• scale_factors (Optional[List[int]], default: None ) –

  Custom scale factors for each pyramid level. If None, uses powers of 2: [2, 4, 8, ...]

• orientation –

  Anatomical orientation string (e.g., 'RAS', 'LPI') to store as metadata

• **kwargs (Any, default: {} ) –

  Additional arguments passed to to_ngff_zarr function

Raises:

• ValueError –

  If scale_factors length doesn't match max_layer-1

• OSError –

  If unable to write to the specified location

• TypeError –

  If ngff_image is not a valid NgffImage object

Examples:

>>> # Save with default pyramid levels
>>> save_ngff_image(img, "/path/to/output.zarr")

>>> # Save to OME-Zarr zip with custom pyramid (new .ozx extension)
>>> save_ngff_image(img, "/path/to/output.ozx",
...                 scale_factors=[2, 4], xyz_orientation="RAS")

>>> # Save to ZIP with legacy extension (backward compatible)
>>> save_ngff_image(img, "/path/to/output.zarr.zip",
...                 scale_factors=[2, 4], xyz_orientation="RAS")

Source code in zarrnii/core.py

def save_ngff_image(
    ngff_image: nz.NgffImage,
    store_or_path: Union[str, Any],
    max_layer: int = 4,
    scale_factors: Optional[List[int]] = None,
    xyz_orientation: Optional[str] = None,
    **kwargs: Any,
) -> None:
    """Save an NgffImage to an OME-Zarr store with multiscale pyramid.

    Creates a multiscale OME-Zarr dataset from the input NgffImage, with automatic
    generation of pyramid levels for efficient viewing and processing at different
    scales.

    Args:
        ngff_image: NgffImage object to save containing data and metadata
        store_or_path: Target store or path. Supports local paths, remote URLs,
            and .zip extensions for ZipStore creation
        max_layer: Maximum number of pyramid levels to create (including level 0)
        scale_factors: Custom scale factors for each pyramid level. If None,
            uses powers of 2: [2, 4, 8, ...]
        orientation: Anatomical orientation string (e.g., 'RAS', 'LPI') to store
            as metadata
        **kwargs: Additional arguments passed to to_ngff_zarr function

    Raises:
        ValueError: If scale_factors length doesn't match max_layer-1
        OSError: If unable to write to the specified location
        TypeError: If ngff_image is not a valid NgffImage object

    Examples:
        >>> # Save with default pyramid levels
        >>> save_ngff_image(img, "/path/to/output.zarr")

        >>> # Save to OME-Zarr zip with custom pyramid (new .ozx extension)
        >>> save_ngff_image(img, "/path/to/output.ozx",
        ...                 scale_factors=[2, 4], xyz_orientation="RAS")

        >>> # Save to ZIP with legacy extension (backward compatible)
        >>> save_ngff_image(img, "/path/to/output.zarr.zip",
        ...                 scale_factors=[2, 4], xyz_orientation="RAS")
    """
    import os
    import tempfile

    import zarr

    if scale_factors is None:
        scale_factors = [2**i for i in range(1, max_layer)]

    # Extract chunks from the input data if available
    # This preserves the original chunk size from dask arrays
    # ngff_zarr.to_multiscales expects an integer chunk size for spatial dimensions
    chunks = None
    if hasattr(ngff_image, "data") and hasattr(ngff_image.data, "chunksize"):
        chunksize = ngff_image.data.chunksize
        # Extract spatial chunk sizes (skip the first dimension which is typically channel/time)
        # and use the first spatial dimension's chunk size as representative
        if len(chunksize) > 1:
            # Take the chunk size from the first spatial dimension (index 1)
            chunks = chunksize[1]

    # Create multiscales from the image, passing chunks to preserve original chunking
    multiscales = nz.to_multiscales(
        ngff_image, scale_factors=scale_factors, chunks=chunks
    )

    # Check if the target is an OME-Zarr zip file (based on extension)
    if isinstance(store_or_path, str) and _is_ome_zarr_zip_path(store_or_path):
        # For OME-Zarr zip files, use temp directory approach
        # then create spec-compliant ZIP archive
        with tempfile.TemporaryDirectory() as tmpdir:
            # Save to temporary directory first
            temp_zarr_path = os.path.join(tmpdir, "temp.zarr")
            nz.to_ngff_zarr(temp_zarr_path, multiscales, **kwargs)

            # Add xyz_orientation metadata to the temporary zarr store if provided
            if xyz_orientation:
                try:
                    group = zarr.open_group(temp_zarr_path, mode="r+")
                    group.attrs["xyz_orientation"] = xyz_orientation
                except Exception:
                    # If we can't write orientation metadata, that's not critical
                    pass

            # Create OME-Zarr zip file according to spec
            _create_ome_zarr_zip(temp_zarr_path, store_or_path)
    else:
        # Write to zarr store directly
        nz.to_ngff_zarr(store_or_path, multiscales, **kwargs)

        # Add xyz_orientation metadata if provided
        if xyz_orientation:
            try:
                if isinstance(store_or_path, str):
                    group = zarr.open_group(store_or_path, mode="r+")
                else:
                    group = zarr.open_group(store_or_path, mode="r+")
                group.attrs["xyz_orientation"] = xyz_orientation
            except Exception:
                # If we can't write orientation metadata, that's not critical
                pass

zarrnii.core.save_ngff_image_with_ome_zarr(ngff_image, store_or_path, max_layer=4, scale_factors=None, scaling_method='local_mean', xyz_orientation=None, omero=None, compute=True, zarr_format=3, storage_options=None, **kwargs)

Save an NgffImage to an OME-Zarr store using ome-zarr-py library.

This function uses the ome-zarr-py library for writing, which can provide performance enhancements when using dask and dask distributed. It was the default writer before v2.0 and is now offered as an alternative.

Parameters:

• ngff_image (NgffImage) –

  NgffImage object to save containing data and metadata

• store_or_path (Union[str, Any]) –

  Target store or path. Supports local paths, remote URLs, and .ozx or .zip extensions for OME-Zarr zip creation

• max_layer (int, default: 4 ) –

  Maximum number of pyramid levels to create (including level 0)

• scale_factors (Optional[Union[List[int], List[Dict[str, int]], List[Dict[str, float]]]], default: None ) –

  Custom scale factors for each pyramid level. If None, automatically computes anisotropy-aware cumulative factors so that the first pyramid level brings all spatial dimensions to approximately the same (coarsest) resolution, and subsequent levels apply uniform 2× downsampling. Falls back to uniform 2× per level when the data are already isotropic. Can also be an explicit list of integers (xy-only downsampling) or a list of dicts with per-axis cumulative factors from level 0, e.g. [{"z": 1, "y": 2, "x": 2}, {"z": 2, "y": 4, "x": 4}].

• scaling_method (str, default: 'local_mean' ) –

  Downsampling method to use. One of 'nearest', 'resize', 'local_mean', or 'zoom'. Defaults to 'local_mean'.

• xyz_orientation (Optional[str], default: None ) –

  Anatomical orientation string (e.g., 'RAS', 'LPI') to store as metadata

• omero (Omero, default: None ) –

  Optional OMERO channel metadata (nz.Omero instance).

• compute (bool, default: True ) –

  Whether to compute the write operations immediately (True) or return delayed operations (False)

• zarr_format (int, default: 3 ) –

  Zarr format version to use (2 or 3). Defaults to 3. Use 2 for backwards compatibility with tools that do not yet support Zarr v3 (e.g. older versions of napari).

• storage_options (Optional[Union[Dict[str, Any], List[Dict[str, Any]]]], default: None ) –

  Storage options passed directly to the zarr backend via ome_zarr.writer.write_image. A single dict applies to all pyramid levels; a list of dicts must match the number of pyramid levels and allows different options per level. Typical uses include selecting shards (zarr v3) or custom chunk sizes, e.g.::

  storage_options={"shards": (1, 64, 64, 64)}
  

• **kwargs (Any, default: {} ) –

  Additional arguments passed to ome_zarr.writer.write_image

Raises:

• ValueError –

  If scale_factors length doesn't match max_layer-1

• OSError –

  If unable to write to the specified location

• TypeError –

  If ngff_image is not a valid NgffImage object

Examples:

>>> # Save with default pyramid levels (all spatial dims downsampled)
>>> save_ngff_image_with_ome_zarr(img, "/path/to/output.zarr")

>>> # Save with shards for efficient cloud storage
>>> save_ngff_image_with_ome_zarr(
...     img, "/path/to/output.zarr",
...     storage_options={"shards": (1, 64, 64, 64)},
... )

>>> # Save to OME-Zarr zip with custom pyramid (new .ozx extension)
>>> save_ngff_image_with_ome_zarr(img, "/path/to/output.ozx",
...                                scale_factors=[2, 4], xyz_orientation="RAS")

>>> # Save to ZIP with legacy extension (backward compatible)
>>> save_ngff_image_with_ome_zarr(img, "/path/to/output.zarr.zip",
...                                scale_factors=[2, 4], xyz_orientation="RAS")

>>> # Use with dask distributed for better performance
>>> from dask.distributed import Client
>>> client = Client()
>>> save_ngff_image_with_ome_zarr(img, "/path/to/output.zarr", compute=True)

Source code in zarrnii/core.py

def save_ngff_image_with_ome_zarr(
    ngff_image: nz.NgffImage,
    store_or_path: Union[str, Any],
    max_layer: int = 4,
    scale_factors: Optional[
        Union[List[int], List[Dict[str, int]], List[Dict[str, float]]]
    ] = None,
    scaling_method: str = "local_mean",
    xyz_orientation: Optional[str] = None,
    omero: nz.Omero = None,
    compute: bool = True,
    zarr_format: int = 3,
    storage_options: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = None,
    **kwargs: Any,
) -> None:
    """Save an NgffImage to an OME-Zarr store using ome-zarr-py library.

    This function uses the ome-zarr-py library for writing, which can provide
    performance enhancements when using dask and dask distributed. It was the
    default writer before v2.0 and is now offered as an alternative.

    Args:
        ngff_image: NgffImage object to save containing data and metadata
        store_or_path: Target store or path. Supports local paths, remote URLs,
            and .ozx or .zip extensions for OME-Zarr zip creation
        max_layer: Maximum number of pyramid levels to create (including level 0)
        scale_factors: Custom scale factors for each pyramid level. If None,
            automatically computes anisotropy-aware cumulative factors so that
            the first pyramid level brings all spatial dimensions to
            approximately the same (coarsest) resolution, and subsequent levels
            apply uniform 2× downsampling.  Falls back to uniform 2× per level
            when the data are already isotropic.  Can also be an explicit list
            of integers (xy-only downsampling) or a list of dicts with
            per-axis cumulative factors from level 0, e.g.
            ``[{"z": 1, "y": 2, "x": 2}, {"z": 2, "y": 4, "x": 4}]``.
        scaling_method: Downsampling method to use. One of ``'nearest'``,
            ``'resize'``, ``'local_mean'``, or ``'zoom'``. Defaults to
            ``'local_mean'``.
        xyz_orientation: Anatomical orientation string (e.g., 'RAS', 'LPI') to store
            as metadata
        omero: Optional OMERO channel metadata (``nz.Omero`` instance).
        compute: Whether to compute the write operations immediately (True) or
            return delayed operations (False)
        zarr_format: Zarr format version to use (2 or 3). Defaults to 3.
            Use 2 for backwards compatibility with tools that do not yet
            support Zarr v3 (e.g. older versions of napari).
        storage_options: Storage options passed directly to the zarr backend via
            ``ome_zarr.writer.write_image``.  A single dict applies to all
            pyramid levels; a list of dicts must match the number of pyramid
            levels and allows different options per level.  Typical uses include
            selecting shards (zarr v3) or custom chunk sizes, e.g.::

                storage_options={"shards": (1, 64, 64, 64)}

        **kwargs: Additional arguments passed to ome_zarr.writer.write_image

    Raises:
        ValueError: If scale_factors length doesn't match max_layer-1
        OSError: If unable to write to the specified location
        TypeError: If ngff_image is not a valid NgffImage object

    Examples:
        >>> # Save with default pyramid levels (all spatial dims downsampled)
        >>> save_ngff_image_with_ome_zarr(img, "/path/to/output.zarr")

        >>> # Save with shards for efficient cloud storage
        >>> save_ngff_image_with_ome_zarr(
        ...     img, "/path/to/output.zarr",
        ...     storage_options={"shards": (1, 64, 64, 64)},
        ... )

        >>> # Save to OME-Zarr zip with custom pyramid (new .ozx extension)
        >>> save_ngff_image_with_ome_zarr(img, "/path/to/output.ozx",
        ...                                scale_factors=[2, 4], xyz_orientation="RAS")

        >>> # Save to ZIP with legacy extension (backward compatible)
        >>> save_ngff_image_with_ome_zarr(img, "/path/to/output.zarr.zip",
        ...                                scale_factors=[2, 4], xyz_orientation="RAS")

        >>> # Use with dask distributed for better performance
        >>> from dask.distributed import Client
        >>> client = Client()
        >>> save_ngff_image_with_ome_zarr(img, "/path/to/output.zarr", compute=True)
    """
    import os
    import tempfile

    import zarr
    from ome_zarr.scale import Methods
    from ome_zarr.writer import write_image

    if scale_factors is None:
        # Generate anisotropy-aware scale factors so that the first pyramid
        # level corrects any voxel-size anisotropy before subsequent levels
        # apply uniform 2× downsampling.  Falls back to uniform 2× per level
        # when the data are already isotropic.
        scale_factors = _compute_isotropic_scale_factors(ngff_image, max_layer)

    # Convert scaling_method string to Methods enum for proper type safety
    method = Methods(scaling_method)

    # Convert NgffImage metadata to ome-zarr format
    axes = _ngff_image_to_ome_zarr_axes(ngff_image)
    coordinate_transformations = _ngff_image_to_ome_zarr_transforms(
        ngff_image, scale_factors
    )

    # Check if the target is an OME-Zarr zip file (based on extension)
    if isinstance(store_or_path, str) and _is_ome_zarr_zip_path(store_or_path):
        # For OME-Zarr zip files, use temp directory approach
        # then create spec-compliant ZIP archive
        with tempfile.TemporaryDirectory() as tmpdir:
            # Save to temporary directory first
            temp_zarr_path = os.path.join(tmpdir, "temp.zarr")
            store = zarr.open_group(temp_zarr_path, mode="w", zarr_format=zarr_format)

            # Write the data to OME-Zarr using the new scale_factors API
            write_image(
                image=ngff_image.data,
                group=store,
                scale_factors=scale_factors,
                method=method,
                coordinate_transformations=coordinate_transformations,
                axes=axes,
                metadata={} if omero is None else {"omero": _to_primitive(omero)},
                storage_options=storage_options,
                compute=compute,
                **kwargs,
            )

            # Add xyz_orientation metadata if provided
            if xyz_orientation:
                try:
                    store.attrs["xyz_orientation"] = xyz_orientation
                except Exception:
                    # If we can't write orientation metadata, that's not critical
                    pass

            # Create OME-Zarr zip file according to spec
            _create_ome_zarr_zip(temp_zarr_path, store_or_path)
    else:
        # Write to zarr store directly
        if isinstance(store_or_path, str):
            store = zarr.open_group(store_or_path, mode="w", zarr_format=zarr_format)
        else:
            store = store_or_path

        # Write the data to OME-Zarr using the new scale_factors API
        write_image(
            image=ngff_image.data,
            group=store,
            scale_factors=scale_factors,
            method=method,
            coordinate_transformations=coordinate_transformations,
            axes=axes,
            metadata={} if omero is None else {"omero": _to_primitive(omero)},
            storage_options=storage_options,
            compute=compute,
            **kwargs,
        )

        # Add xyz_orientation metadata if provided
        if xyz_orientation:
            try:
                if isinstance(store_or_path, str):
                    group = zarr.open_group(store_or_path, mode="r+")
                else:
                    group = store_or_path
                group.attrs["xyz_orientation"] = xyz_orientation
            except Exception:
                # If we can't write orientation metadata, that's not critical
                pass

zarrnii.core.get_multiscales(store_or_path, storage_options=None)

Load the full multiscales object from an OME-Zarr store.

This provides access to all pyramid levels and metadata.

Parameters:

• store_or_path –

  Store or path to the OME-Zarr file

• storage_options (Optional[Dict], default: None ) –

  Storage options for Zarr

Returns:

• Multiscales ( Multiscales ) –

  The full multiscales object with all pyramid levels

Source code in zarrnii/core.py

def get_multiscales(
    store_or_path,
    storage_options: Optional[Dict] = None,
) -> nz.Multiscales:
    """
    Load the full multiscales object from an OME-Zarr store.

    This provides access to all pyramid levels and metadata.

    Args:
        store_or_path: Store or path to the OME-Zarr file
        storage_options: Storage options for Zarr

    Returns:
        Multiscales: The full multiscales object with all pyramid levels
    """
    return nz.from_ngff_zarr(store_or_path, storage_options=storage_options)

zarrnii.core.get_scale_factors_from_file(path, storage_options=None)

Return per-level scale factors.

Dispatches to the appropriate format-specific helper based on the file extension. Supports OME-Zarr (.zarr, .ozx, .zarr.zip) and Imaris (.ims) formats.

Parameters:

• path (Any) –

  Path or store to the source file.

• storage_options (Optional[Dict], default: None ) –

  Optional storage options (only used for OME-Zarr paths).

Returns:

• List[Dict[str, int]] –

  List of cumulative scale-factor dicts ({"z": ..., "y": ..., "x": ...}) one per pyramid level above level 0. Returns an

• List[Dict[str, int]] –

  empty list when level_shapes has only one entry.

Source code in zarrnii/core.py

def get_scale_factors_from_file(
    path: Any,
    storage_options: Optional[Dict] = None,
) -> List[Dict[str, int]]:
    """Return per-level scale factors.

    Dispatches to the appropriate format-specific helper based on the file
    extension. Supports OME-Zarr (``.zarr``, ``.ozx``, ``.zarr.zip``) and
    Imaris (``.ims``) formats.

    Args:
        path: Path or store to the source file.
        storage_options: Optional storage options (only used for OME-Zarr paths).

    Returns:
        List of cumulative scale-factor dicts (``{"z": ..., "y": ..., "x": ...}``)
         one per pyramid level above level 0.  Returns an
        empty list when *level_shapes* has only one entry.
    """

    level_shapes = _get_level_zyx_shapes_from_file(path)
    scale_factors = _compute_scale_factors_from_shapes(level_shapes)
    return scale_factors

zarrnii.core.crop_ngff_image(ngff_image, bbox_min, bbox_max, dim_flips)

Crop an NgffImage using a bounding box.

Parameters:

• ngff_image (NgffImage) –

  Input NgffImage to crop

• bbox_min (dict[float]) –

  Minimum corner of bounding box, dict with spatial dim keys

• bbox_max (dict[float]) –

  Maximum corner of bounding box, dict with spatial dim keys

• orientation_flips –

  orientation flips by dimensions, dict with spatial dim keys, vals as -1 or +1

Returns:

• NgffImage –

  New cropped NgffImage

Source code in zarrnii/core.py

def crop_ngff_image(
    ngff_image: nz.NgffImage,
    bbox_min: dict[float],
    bbox_max: dict[float],
    dim_flips: dict[float],
) -> nz.NgffImage:
    """
    Crop an NgffImage using a bounding box.

    Args:
        ngff_image: Input NgffImage to crop
        bbox_min: Minimum corner of bounding box, dict with spatial dim keys
        bbox_max: Maximum corner of bounding box, dict with spatial dim keys
        orientation_flips: orientation flips by dimensions, dict with spatial dim keys, vals as -1 or +1

    Returns:
        New cropped NgffImage
    """
    # Build slices for cropping
    slices = []

    for dim in ngff_image.dims:
        if dim in bbox_min:
            # This is a spatial dimension
            slices.append(slice(bbox_min[dim], bbox_max[dim]))
        else:
            # Non-spatial dimension, keep all
            slices.append(slice(None))

    # Apply crop
    cropped_data = ngff_image.data[tuple(slices)]

    # Update translation to account for cropping
    new_translation = ngff_image.translation.copy()

    for dim in bbox_min.keys():
        new_translation[dim] = (
            new_translation[dim]
            + dim_flips[dim] * bbox_min[dim] * ngff_image.scale[dim]
        )

    # Create new NgffImage
    return _derive_ngff_image(
        ngff_image, data=cropped_data, translation=new_translation
    )

zarrnii.core.downsample_ngff_image(ngff_image, factors, spatial_dims=['z', 'y', 'x'])

Downsample an NgffImage by the specified factors.

Parameters:

• ngff_image (NgffImage) –

  Input NgffImage to downsample

• factors (Union[int, List[int]]) –

  Downsampling factors (int for isotropic, list for per-dimension)

• spatial_dims (List[str], default: ['z', 'y', 'x'] ) –

  Names of spatial dimensions

Returns:

• NgffImage –

  New downsampled NgffImage

Source code in zarrnii/core.py

def downsample_ngff_image(
    ngff_image: nz.NgffImage,
    factors: Union[int, List[int]],
    spatial_dims: List[str] = ["z", "y", "x"],
) -> nz.NgffImage:
    """
    Downsample an NgffImage by the specified factors.

    Args:
        ngff_image: Input NgffImage to downsample
        factors: Downsampling factors (int for isotropic, list for per-dimension)
        spatial_dims: Names of spatial dimensions

    Returns:
        New downsampled NgffImage
    """
    if isinstance(factors, int):
        factors = [factors] * len(spatial_dims)

    # Build downsampling slices
    slices = []
    spatial_idx = 0

    for dim in ngff_image.dims:
        if dim.lower() in [d.lower() for d in spatial_dims]:
            if spatial_idx < len(factors):
                factor = factors[spatial_idx]
                slices.append(slice(None, None, factor))
                spatial_idx += 1
            else:
                slices.append(slice(None))
        else:
            # Non-spatial dimension, keep all
            slices.append(slice(None))

    # Apply downsampling
    downsampled_data = ngff_image.data[tuple(slices)]

    # Update scale to account for downsampling
    new_scale = ngff_image.scale.copy()
    spatial_idx = 0

    for dim in ngff_image.dims:
        if dim.lower() in [d.lower() for d in spatial_dims]:
            if spatial_idx < len(factors) and dim in new_scale:
                new_scale[dim] *= factors[spatial_idx]
                spatial_idx += 1

    # Create new NgffImage
    return _derive_ngff_image(ngff_image, data=downsampled_data, scale=new_scale)

zarrnii.core.apply_transform_to_ngff_image(ngff_image, transform, reference_image, spatial_dims=['z', 'y', 'x'])

Apply a spatial transformation to an NgffImage.

Parameters:

• ngff_image (NgffImage) –

  Input NgffImage to transform

• transform (Transform) –

  Transformation to apply

• reference_image (NgffImage) –

  Reference image defining output space

• spatial_dims (List[str], default: ['z', 'y', 'x'] ) –

  Names of spatial dimensions

Returns:

• NgffImage –

  New transformed NgffImage

Source code in zarrnii/core.py

def apply_transform_to_ngff_image(
    ngff_image: nz.NgffImage,
    transform: Transform,
    reference_image: nz.NgffImage,
    spatial_dims: List[str] = ["z", "y", "x"],
) -> nz.NgffImage:
    """
    Apply a spatial transformation to an NgffImage.

    Args:
        ngff_image: Input NgffImage to transform
        transform: Transformation to apply
        reference_image: Reference image defining output space
        spatial_dims: Names of spatial dimensions

    Returns:
        New transformed NgffImage
    """
    # For now, return a placeholder implementation
    # This would need full implementation of interpolation logic
    print("Warning: apply_transform_to_ngff_image is not fully implemented yet")

    return reference_image

zarrnii.core.make_omero(channel_labels, channel_colors=None, channel_windows=None)

Build OMERO metadata from plain channel labels/colors/windows.

Parameters:

• channel_labels (List[str]) –

  Channel names in order.

• channel_colors (Optional[List[str]], default: None ) –

  Optional per-channel colors as RRGGBB (#RRGGBB also accepted).

• channel_windows (Optional[List[Union[OmeroWindow, Dict[str, float], Tuple[float, float, float, float], List[float]]]], default: None ) –

  Optional per-channel display windows. Each item can be: - nz.OmeroWindow (or object with min/max/start/end attributes) - dict with keys min, max, start, end - 4-item tuple/list (min, max, start, end)

Returns:

• Omero –

  nz.Omero metadata object with one channel entry per label.

Source code in zarrnii/core.py

def make_omero(
    channel_labels: List[str],
    channel_colors: Optional[List[str]] = None,
    channel_windows: Optional[
        List[
            Union[
                nz.OmeroWindow,
                Dict[str, float],
                Tuple[float, float, float, float],
                List[float],
            ]
        ]
    ] = None,
) -> nz.Omero:
    """Build OMERO metadata from plain channel labels/colors/windows.

    Args:
        channel_labels: Channel names in order.
        channel_colors: Optional per-channel colors as ``RRGGBB`` (``#RRGGBB`` also accepted).
        channel_windows: Optional per-channel display windows. Each item can be:
            - ``nz.OmeroWindow`` (or object with min/max/start/end attributes)
            - dict with keys ``min``, ``max``, ``start``, ``end``
            - 4-item tuple/list ``(min, max, start, end)``

    Returns:
        ``nz.Omero`` metadata object with one channel entry per label.
    """
    if not channel_labels:
        raise ValueError("channel_labels must contain at least one label.")

    labels = list(channel_labels)
    if any(not isinstance(label, str) or label == "" for label in labels):
        raise ValueError("Each channel label must be a non-empty string.")

    n_channels = len(labels)
    if channel_colors is not None and len(channel_colors) != n_channels:
        raise ValueError("channel_colors must have the same length as channel_labels.")
    if channel_windows is not None and len(channel_windows) != n_channels:
        raise ValueError("channel_windows must have the same length as channel_labels.")

    colors = (
        [_normalize_omero_color(c) for c in channel_colors]
        if channel_colors is not None
        else [
            _DEFAULT_OMERO_COLORS[i % len(_DEFAULT_OMERO_COLORS)]
            for i in range(n_channels)
        ]
    )
    windows = (
        list(channel_windows) if channel_windows is not None else [None] * n_channels
    )

    channels = []
    for label, color, window in zip(labels, colors, windows):
        channels.append(
            nz.OmeroChannel(
                color=color,
                window=_make_omero_window(window),
                label=label,
            )
        )

    return nz.Omero(channels=channels)

zarrnii.core.make_omero_channels(channel_labels, channel_colors=None, channel_windows=None)

Alias for make_omero with identical parameters and behavior.

Use this alias if you prefer a channel-centric name.

Source code in zarrnii/core.py

def make_omero_channels(
    channel_labels: List[str],
    channel_colors: Optional[List[str]] = None,
    channel_windows: Optional[
        List[
            Union[
                nz.OmeroWindow,
                Dict[str, float],
                Tuple[float, float, float, float],
                List[float],
            ]
        ]
    ] = None,
) -> nz.Omero:
    """Alias for ``make_omero`` with identical parameters and behavior.

    Use this alias if you prefer a channel-centric name.
    """
    return make_omero(
        channel_labels=channel_labels,
        channel_colors=channel_colors,
        channel_windows=channel_windows,
    )

zarrnii.core.get_bounded_subregion_from_zarr(points, store_path, array_shape, dataset_path='0', storage_options=None)

Extract a bounded subregion from a zarr array using direct zarr access.

This function reads data directly from a zarr store without using dask's compute(), avoiding nested compute() calls when used within dask.map_blocks.

Parameters:

• points (ndarray) –

  Nx3 or Nx4 array of coordinates in the array's space. If Nx4, the last column is assumed to be the homogeneous coordinate and is ignored.

• store_path (str) –

  Path or URI to the zarr store

• array_shape (tuple) –

  Shape of the full array (C, Z, Y, X)

• dataset_path (str, default: '0' ) –

  Path to the dataset within the zarr group (default: "0")

• storage_options (dict, default: None ) –

  Additional options for the storage backend

Returns:

• tuple –

  grid_points (tuple): A tuple of three 1D arrays representing the grid points along each axis (Z, Y, X) in the subregion. subvol (np.ndarray or None): The extracted subregion as a NumPy array. Returns None if all points are outside the array domain.

Notes

• Uses zarr library directly to load the subregion
• A padding of 1 voxel is applied around the extent of the points
• Handles ZIP stores automatically if store_path ends with .zip

Source code in zarrnii/core.py

def get_bounded_subregion_from_zarr(
    points: np.ndarray,
    store_path: str,
    array_shape: Tuple[int, ...],
    dataset_path: str = "0",
    storage_options: Optional[Dict[str, Any]] = None,
):
    """
    Extract a bounded subregion from a zarr array using direct zarr access.

    This function reads data directly from a zarr store without using dask's compute(),
    avoiding nested compute() calls when used within dask.map_blocks.

    Parameters:
        points (np.ndarray): Nx3 or Nx4 array of coordinates in the array's space.
                            If Nx4, the last column is assumed to be the homogeneous
                            coordinate and is ignored.
        store_path (str): Path or URI to the zarr store
        array_shape (tuple): Shape of the full array (C, Z, Y, X)
        dataset_path (str): Path to the dataset within the zarr group (default: "0")
        storage_options (dict, optional): Additional options for the storage backend

    Returns:
        tuple:
            grid_points (tuple): A tuple of three 1D arrays representing the grid
                                points along each axis (Z, Y, X) in the subregion.
            subvol (np.ndarray or None): The extracted subregion as a NumPy array.
                                        Returns `None` if all points are outside
                                        the array domain.

    Notes:
        - Uses zarr library directly to load the subregion
        - A padding of 1 voxel is applied around the extent of the points
        - Handles ZIP stores automatically if store_path ends with .zip
    """
    import zarr

    # Ensure store_path is a string (could be Path object)
    store_path = str(store_path)

    pad = 1  # Padding around the extent of the points

    # Compute the extent of the points in the array's coordinate space
    min_extent = np.floor(points.min(axis=1)[:3] - pad).astype("int")
    max_extent = np.ceil(points.max(axis=1)[:3] + pad).astype("int")

    # Clip the extents to ensure they stay within the bounds of the array
    clip_min = np.zeros_like(min_extent)
    clip_max = np.array(array_shape[-3:])  # Z, Y, X dimensions

    min_extent = np.clip(min_extent, clip_min, clip_max)
    max_extent = np.clip(max_extent, clip_min, clip_max)

    # Check if all points are outside the domain
    if np.any(max_extent <= min_extent):
        return None, None

    # Open the zarr store and read the subregion directly
    try:
        if _is_ome_zarr_zip_path(store_path):
            store = zarr.storage.ZipStore(store_path, mode="r")
            root = zarr.open_group(store, mode="r")
        else:
            if storage_options:
                # Use fsspec for remote stores with storage options
                mapper = fsspec.get_mapper(store_path, **storage_options)
                root = zarr.open_group(mapper, mode="r")
            else:
                root = zarr.open_group(store_path, mode="r")

        # Access the dataset
        arr = root[dataset_path]

        # Extract the subvolume using direct zarr array access
        subvol = arr[
            :,
            min_extent[0] : max_extent[0],
            min_extent[1] : max_extent[1],
            min_extent[2] : max_extent[2],
        ]

        # Ensure we have a numpy array (zarr v3 may return zarr Array)
        if not isinstance(subvol, np.ndarray):
            subvol = np.asarray(subvol)

    finally:
        # Close ZIP store if used
        if _is_ome_zarr_zip_path(store_path):
            store.close()

    # Generate grid points for interpolation
    grid_points = (
        np.arange(min_extent[0], max_extent[0]),  # Z
        np.arange(min_extent[1], max_extent[1]),  # Y
        np.arange(min_extent[2], max_extent[2]),  # X
    )

    return grid_points, subvol

zarrnii.core.interp_by_block(x, transforms, flo_store_path=None, flo_array_shape=None, flo_dataset_path='0', flo_storage_options=None, flo_znimg=None, block_info=None, interp_method='linear')

Interpolates the floating image onto the reference image block (x) using the provided transformations.

This function extracts the necessary subset of the floating image for each block of the reference image, applies the transformations, and interpolates the floating image intensities onto the reference image grid.

Parameters:

• x (ndarray) –

  The reference image block to interpolate onto.

• transforms (list[Transform]) –

  A list of Transform objects to apply to the reference image coordinates.

• flo_store_path (str, default: None ) –

  Path/URI to the zarr store containing the floating image. If provided, uses direct zarr access instead of dask compute().

• flo_array_shape (tuple, default: None ) –

  Shape of the floating array (C, Z, Y, X). Required if flo_store_path is provided.

• flo_dataset_path (str, default: '0' ) –

  Path to dataset within zarr group. Defaults to "0".

• flo_storage_options (dict, default: None ) –

  Storage options for accessing the store.

• flo_znimg (ZarrNii, default: None ) –

  The floating ZarrNii instance. Used as fallback if store path not provided (legacy behavior).

• block_info (dict, default: None ) –

  Metadata about the current block being processed.

• interp_method (str, default: 'linear' ) –

  Interpolation method. Defaults to "linear".

Returns:

• –

  np.ndarray: The interpolated block of the reference image.

Notes

• When flo_store_path is provided, uses direct zarr access to avoid nested compute() calls.
• Falls back to using flo_znimg.get_bounded_subregion() for backwards compatibility.
• If the transformed coordinates are completely outside the bounds of the floating image, a zero-filled array is returned.

Example

New approach with store path

interpolated_block = interp_by_block( x=ref_block, transforms=[transform1, transform2], flo_store_path="/path/to/data.zarr", flo_array_shape=(3, 100, 100, 100), block_info=block_metadata, )

Legacy approach with ZarrNii instance

interpolated_block = interp_by_block( x=ref_block, transforms=[transform1, transform2], flo_znimg=floating_image, block_info=block_metadata, )

Source code in zarrnii/core.py

def interp_by_block(
    x,
    transforms: list[Transform],
    flo_store_path: Optional[str] = None,
    flo_array_shape: Optional[Tuple[int, ...]] = None,
    flo_dataset_path: str = "0",
    flo_storage_options: Optional[Dict[str, Any]] = None,
    flo_znimg: Optional["ZarrNii"] = None,
    block_info=None,
    interp_method="linear",
):
    """
    Interpolates the floating image onto the reference image block (`x`)
    using the provided transformations.

    This function extracts the necessary subset of the floating image for each block
    of the reference image, applies the transformations, and interpolates the floating
    image intensities onto the reference image grid.

    Parameters:
        x (np.ndarray): The reference image block to interpolate onto.
        transforms (list[Transform]): A list of `Transform` objects to apply to the
                                       reference image coordinates.
        flo_store_path (str, optional): Path/URI to the zarr store containing the
                                       floating image. If provided, uses direct zarr
                                       access instead of dask compute().
        flo_array_shape (tuple, optional): Shape of the floating array (C, Z, Y, X).
                                          Required if flo_store_path is provided.
        flo_dataset_path (str, optional): Path to dataset within zarr group.
                                         Defaults to "0".
        flo_storage_options (dict, optional): Storage options for accessing the store.
        flo_znimg (ZarrNii, optional): The floating ZarrNii instance. Used as fallback
                                      if store path not provided (legacy behavior).
        block_info (dict, optional): Metadata about the current block being processed.
        interp_method (str, optional): Interpolation method. Defaults to "linear".

    Returns:
        np.ndarray: The interpolated block of the reference image.

    Notes:
        - When flo_store_path is provided, uses direct zarr access to avoid nested
          compute() calls.
        - Falls back to using flo_znimg.get_bounded_subregion() for backwards
          compatibility.
        - If the transformed coordinates are completely outside the bounds of the
          floating image, a zero-filled array is returned.

    Example:
        # New approach with store path
        interpolated_block = interp_by_block(
            x=ref_block,
            transforms=[transform1, transform2],
            flo_store_path="/path/to/data.zarr",
            flo_array_shape=(3, 100, 100, 100),
            block_info=block_metadata,
        )

        # Legacy approach with ZarrNii instance
        interpolated_block = interp_by_block(
            x=ref_block,
            transforms=[transform1, transform2],
            flo_znimg=floating_image,
            block_info=block_metadata,
        )
    """
    # Extract the array location (block bounds) from block_info
    arr_location = block_info[0]["array-location"]

    # Generate coordinate grids for the reference image block
    xv, yv, zv = np.meshgrid(
        np.arange(arr_location[-3][0], arr_location[-3][1]),
        np.arange(arr_location[-2][0], arr_location[-2][1]),
        np.arange(arr_location[-1][0], arr_location[-1][1]),
        indexing="ij",
    )

    # Reshape grids into vectors for matrix multiplication
    xvf = xv.reshape((1, np.prod(xv.shape)))
    yvf = yv.reshape((1, np.prod(yv.shape)))
    zvf = zv.reshape((1, np.prod(zv.shape)))
    homog = np.ones(xvf.shape)

    xfm_vecs = np.vstack((xvf, yvf, zvf, homog))

    # Apply transformations sequentially
    for tfm in transforms:
        xfm_vecs = tfm.apply_transform(xfm_vecs)

    # Initialize the output array for interpolated values
    interpolated = np.zeros(x.shape)

    # Determine the required subregion of the floating image
    # Use direct zarr access if store path is provided, otherwise use legacy method
    if flo_store_path is not None and flo_array_shape is not None:
        grid_points, flo_vol = get_bounded_subregion_from_zarr(
            xfm_vecs,
            flo_store_path,
            flo_array_shape,
            flo_dataset_path,
            flo_storage_options,
        )
    elif flo_znimg is not None:
        # Legacy fallback
        grid_points, flo_vol = flo_znimg.get_bounded_subregion(xfm_vecs)
    else:
        raise ValueError(
            "Either (flo_store_path and flo_array_shape) or flo_znimg must be provided"
        )

    if grid_points is None and flo_vol is None:
        # Points are fully outside the floating image; return zeros
        return interpolated

    # Interpolate each channel of the floating image
    for c in range(flo_vol.shape[0]):
        interpolated[c, :, :, :] = (
            interpn(
                grid_points,
                flo_vol[c, :, :, :],
                xfm_vecs[:3, :].T,  # Transformed coordinates
                method=interp_method,
                bounds_error=False,
                fill_value=0,
            )
            .reshape((x.shape[-3], x.shape[-2], x.shape[-1]))
            .astype(block_info[None]["dtype"])
        )

    return interpolated

zarrnii.core.reverse_orientation_string(orientation_str)

Reverse an orientation string to convert between ZYX and XYZ axis orders.

This function reverses the character order of an orientation string to convert between ZYX-based and XYZ-based orientation encoding. For example: 'RAS' (ZYX order) becomes 'SAR' (XYZ order).

Parameters:

• orientation_str (str) –

  Three-character orientation string (e.g., 'RAS', 'LPI')

Returns:

• str –

  Reversed orientation string

Examples:

>>> reverse_orientation_string('RAS')
'SAR'
>>> reverse_orientation_string('LPI')
'IPL'

Source code in zarrnii/core.py

def reverse_orientation_string(orientation_str):
    """
    Reverse an orientation string to convert between ZYX and XYZ axis orders.

    This function reverses the character order of an orientation string to convert
    between ZYX-based and XYZ-based orientation encoding. For example:
    'RAS' (ZYX order) becomes 'SAR' (XYZ order).

    Args:
        orientation_str (str): Three-character orientation string (e.g., 'RAS', 'LPI')

    Returns:
        str: Reversed orientation string

    Examples:
        >>> reverse_orientation_string('RAS')
        'SAR'
        >>> reverse_orientation_string('LPI')
        'IPL'
    """

    if len(orientation_str) != 3:
        raise ValueError(
            f"Orientation string must be exactly 3 characters, got: {orientation_str}"
        )

    return orientation_str[::-1]