ngio 0.5.0b6__py3-none-any.whl

ngio/__init__.py

@@ -0,0 +1,69 @@
+"""Next Generation file format IO."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("ngio")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "uninstalled"
+__author__ = "Lorenzo Cerrone"
+__email__ = "lorenzo.cerrone@uzh.ch"
+
+from ngio.common import Dimensions, Roi, RoiSlice
+from ngio.hcs import (
+    OmeZarrPlate,
+    OmeZarrWell,
+    create_empty_plate,
+    create_empty_well,
+    open_ome_zarr_plate,
+    open_ome_zarr_well,
+)
+from ngio.images import (
+    ChannelSelectionModel,
+    Image,
+    Label,
+    OmeZarrContainer,
+    create_empty_ome_zarr,
+    create_ome_zarr_from_array,
+    create_synthetic_ome_zarr,
+    open_image,
+    open_label,
+    open_ome_zarr_container,
+)
+from ngio.ome_zarr_meta.ngio_specs import (
+    AxesSetup,
+    DefaultNgffVersion,
+    ImageInWellPath,
+    NgffVersions,
+    PixelSize,
+)
+from ngio.utils import NgioSupportedStore, StoreOrGroup
+
+__all__ = [
+    "AxesSetup",
+    "ChannelSelectionModel",
+    "DefaultNgffVersion",
+    "Dimensions",
+    "Image",
+    "ImageInWellPath",
+    "Label",
+    "NgffVersions",
+    "NgioSupportedStore",
+    "OmeZarrContainer",
+    "OmeZarrPlate",
+    "OmeZarrWell",
+    "PixelSize",
+    "Roi",
+    "RoiSlice",
+    "StoreOrGroup",
+    "create_empty_ome_zarr",
+    "create_empty_plate",
+    "create_empty_well",
+    "create_ome_zarr_from_array",
+    "create_synthetic_ome_zarr",
+    "open_image",
+    "open_label",
+    "open_ome_zarr_container",
+    "open_ome_zarr_plate",
+    "open_ome_zarr_well",
+]

ngio/common/__init__.py

@@ -0,0 +1,28 @@
+"""Common classes and functions that are used across the package."""
+
+from ngio.common._dimensions import Dimensions
+from ngio.common._masking_roi import compute_masking_roi
+from ngio.common._pyramid import (
+    ChunksLike,
+    ImagePyramidBuilder,
+    ShardsLike,
+    consolidate_pyramid,
+    on_disk_zoom,
+)
+from ngio.common._roi import Roi, RoiSlice
+from ngio.common._zoom import InterpolationOrder, dask_zoom, numpy_zoom
+
+__all__ = [
+    "ChunksLike",
+    "Dimensions",
+    "ImagePyramidBuilder",
+    "InterpolationOrder",
+    "Roi",
+    "RoiSlice",
+    "ShardsLike",
+    "compute_masking_roi",
+    "consolidate_pyramid",
+    "dask_zoom",
+    "numpy_zoom",
+    "on_disk_zoom",
+]

ngio/common/_dimensions.py

@@ -0,0 +1,335 @@
+"""Dimension metadata.
+
+This is not related to the NGFF metadata,
+but it is based on the actual metadata of the image data.
+"""
+
+import math
+from typing import overload
+
+from ngio.ome_zarr_meta import (
+    AxesHandler,
+)
+from ngio.ome_zarr_meta.ngio_specs._dataset import Dataset
+from ngio.ome_zarr_meta.ngio_specs._pixel_size import PixelSize
+from ngio.utils import NgioValueError
+
+
+def _are_compatible(shape1: int, shape2: int, scaling: float) -> bool:
+    """Check if shape2 is consistent with shape1 given pixel sizes.
+
+    Since we only deal with shape discrepancies due to rounding, we
+    shape1, needs to be larger than shape2.
+    """
+    if shape1 < shape2:
+        return _are_compatible(shape2, shape1, 1 / scaling)
+    expected_shape2 = shape1 * scaling
+    expected_shape2_floor = math.floor(expected_shape2)
+    expected_shape2_ceil = math.ceil(expected_shape2)
+    return shape2 in {expected_shape2_floor, expected_shape2_ceil}
+
+
+def require_axes_match(reference: "Dimensions", other: "Dimensions") -> None:
+    """Check if two Dimensions objects have the same axes.
+
+    Besides the channel axis (which is a special case), all axes must be
+    present in both Dimensions objects.
+
+    Args:
+        reference (Dimensions): The reference dimensions object to compare against.
+        other (Dimensions): The other dimensions object to compare against.
+
+    Raises:
+        NgioValueError: If the axes do not match.
+    """
+    for s_axis in reference.axes_handler.axes:
+        if s_axis.axis_type == "channel":
+            continue
+        o_axis = other.axes_handler.get_axis(s_axis.name)
+        if o_axis is None:
+            raise NgioValueError(
+                f"Axes do not match. The axis {s_axis.name} "
+                f"is not present in either dimensions."
+            )
+    # Check for axes present in the other dimensions but not in this one
+    for o_axis in other.axes_handler.axes:
+        if o_axis.axis_type == "channel":
+            continue
+        s_axis = reference.axes_handler.get_axis(o_axis.name)
+        if s_axis is None:
+            raise NgioValueError(
+                f"Axes do not match. The axis {o_axis.name} "
+                f"is not present in either dimensions."
+            )
+
+
+def check_if_axes_match(reference: "Dimensions", other: "Dimensions") -> bool:
+    """Check if two Dimensions objects have the same axes.
+
+    Besides the channel axis (which is a special case), all axes must be
+    present in both Dimensions objects.
+
+    Args:
+        reference (Dimensions): The reference dimensions object to compare against.
+        other (Dimensions): The other dimensions object to compare against.
+
+    Returns:
+        bool: True if the axes match, False otherwise.
+    """
+    try:
+        require_axes_match(reference, other)
+        return True
+    except NgioValueError:
+        return False
+
+
+def require_dimensions_match(
+    reference: "Dimensions", other: "Dimensions", allow_singleton: bool = False
+) -> None:
+    """Check if two Dimensions objects have the same axes and dimensions.
+
+    Besides the channel axis, all axes must have the same dimension in
+    both images.
+
+    Args:
+        reference (Dimensions): The reference dimensions object to compare against.
+        other (Dimensions): The other dimensions object to compare against.
+        allow_singleton (bool): Whether to allow singleton dimensions to be
+            different. For example, if the input image has shape
+            (5, 100, 100) and the label has shape (1, 100, 100).
+
+    Raises:
+        NgioValueError: If the dimensions do not match.
+    """
+    require_axes_match(reference, other)
+    for r_axis in reference.axes_handler.axes:
+        if r_axis.axis_type == "channel":
+            continue
+        o_axis = other.axes_handler.get_axis(r_axis.name)
+        assert o_axis is not None  # already checked in assert_axes_match
+
+        r_dim = reference.get(r_axis.name, default=1)
+        o_dim = other.get(o_axis.name, default=1)
+
+        if r_dim != o_dim:
+            if allow_singleton and (r_dim == 1 or o_dim == 1):
+                continue
+            raise NgioValueError(
+                f"Dimensions do not match for axis "
+                f"{r_axis.name}. Got {r_dim} and {o_dim}."
+            )
+
+
+def check_if_dimensions_match(
+    reference: "Dimensions", other: "Dimensions", allow_singleton: bool = False
+) -> bool:
+    """Check if two Dimensions objects have the same axes and dimensions.
+
+    Besides the channel axis, all axes must have the same dimension in
+    both images.
+
+    Args:
+        reference (Dimensions): The reference dimensions object to compare against.
+        other (Dimensions): The other dimensions object to compare against.
+        allow_singleton (bool): Whether to allow singleton dimensions to be
+            different. For example, if the input image has shape
+            (5, 100, 100) and the label has shape (1, 100, 100).
+
+    Returns:
+        bool: True if the dimensions match, False otherwise.
+    """
+    try:
+        require_dimensions_match(reference, other, allow_singleton)
+        return True
+    except NgioValueError:
+        return False
+
+
+def require_rescalable(reference: "Dimensions", other: "Dimensions") -> None:
+    """Assert that two images can be rescaled.
+
+    For this to be true, the images must have the same axes, and
+    the pixel sizes must be compatible (i.e. one can be scaled to the other).
+
+    Args:
+        reference (Dimensions): The reference dimensions object to compare against.
+        other (Dimensions): The other dimensions object to compare against.
+
+    """
+    require_axes_match(reference, other)
+    for ax_r in reference.axes_handler.axes:
+        if ax_r.axis_type == "channel":
+            continue
+        ax_o = other.axes_handler.get_axis(ax_r.name)
+        assert ax_o is not None, "Axes do not match."
+        px_r = reference.pixel_size.get(ax_r.name, default=1.0)
+        px_o = other.pixel_size.get(ax_o.name, default=1.0)
+        shape_r = reference.get(ax_r.name, default=1)
+        shape_o = other.get(ax_o.name, default=1)
+        scale = px_r / px_o
+        if not _are_compatible(
+            shape1=shape_r,
+            shape2=shape_o,
+            scaling=scale,
+        ):
+            raise NgioValueError(
+                f"Reference image with shape {reference.shape}, "
+                f"and pixel size {reference.pixel_size}, "
+                f"cannot be rescaled to "
+                f"image with shape {other.shape} "
+                f"and pixel size {other.pixel_size}. "
+            )
+
+
+def check_if_rescalable(reference: "Dimensions", other: "Dimensions") -> bool:
+    """Check if two images can be rescaled.
+
+    For this to be true, the images must have the same axes, and
+    the pixel sizes must be compatible (i.e. one can be scaled to the other).
+
+    Args:
+        reference (Dimensions): The reference dimensions object to compare against.
+        other (Dimensions): The other dimensions object to compare against.
+
+    Returns:
+        bool: True if the images can be rescaled, False otherwise.
+    """
+    try:
+        require_rescalable(reference, other)
+        return True
+    except NgioValueError:
+        return False
+
+
+class Dimensions:
+    """Dimension metadata Handling Class.
+
+    This class is used to handle and manipulate dimension metadata.
+    It provides methods to access and validate dimension information,
+    such as shape, axes, and properties like is_2d, is_3d, is_time_series, etc.
+    """
+
+    require_axes_match = require_axes_match
+    check_if_axes_match = check_if_axes_match
+    require_dimensions_match = require_dimensions_match
+    check_if_dimensions_match = check_if_dimensions_match
+    require_rescalable = require_rescalable
+    check_if_rescalable = check_if_rescalable
+
+    def __init__(
+        self,
+        shape: tuple[int, ...],
+        chunks: tuple[int, ...],
+        dataset: Dataset,
+    ) -> None:
+        """Create a Dimension object from a Zarr array.
+
+        Args:
+            shape: The shape of the Zarr array.
+            chunks: The chunks of the Zarr array.
+            dataset: The dataset object.
+        """
+        self._shape = shape
+        self._chunks = chunks
+        self._axes_handler = dataset.axes_handler
+        self._pixel_size = dataset.pixel_size
+
+        if len(self._shape) != len(self._axes_handler.axes):
+            raise NgioValueError(
+                "The number of dimensions must match the number of axes. "
+                f"Expected Axis {self._axes_handler.axes_names} but got shape "
+                f"{self._shape}."
+            )
+
+    def __str__(self) -> str:
+        """Return the string representation of the object."""
+        dims = ", ".join(
+            f"{ax.name}: {s}"
+            for ax, s in zip(self._axes_handler.axes, self._shape, strict=True)
+        )
+        return f"Dimensions({dims})"
+
+    def __repr__(self) -> str:
+        """Return the string representation of the object."""
+        return str(self)
+
+    @property
+    def axes_handler(self) -> AxesHandler:
+        """Return the axes handler object."""
+        return self._axes_handler
+
+    @property
+    def pixel_size(self) -> PixelSize:
+        """Return the pixel size object."""
+        return self._pixel_size
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        """Return the shape as a tuple."""
+        return self._shape
+
+    @property
+    def chunks(self) -> tuple[int, ...]:
+        """Return the chunks as a tuple."""
+        return self._chunks
+
+    @property
+    def axes(self) -> tuple[str, ...]:
+        """Return the axes as a tuple of strings."""
+        return self.axes_handler.axes_names
+
+    @property
+    def is_time_series(self) -> bool:
+        """Return whether the image is a time series."""
+        if self.get("t", default=1) == 1:
+            return False
+        return True
+
+    @property
+    def is_2d(self) -> bool:
+        """Return whether the image is 2D."""
+        if self.get("z", default=1) != 1:
+            return False
+        return True
+
+    @property
+    def is_2d_time_series(self) -> bool:
+        """Return whether the image is a 2D time series."""
+        return self.is_2d and self.is_time_series
+
+    @property
+    def is_3d(self) -> bool:
+        """Return whether the image is 3D."""
+        return not self.is_2d
+
+    @property
+    def is_3d_time_series(self) -> bool:
+        """Return whether the image is a 3D time series."""
+        return self.is_3d and self.is_time_series
+
+    @property
+    def is_multi_channels(self) -> bool:
+        """Return whether the image has multiple channels."""
+        if self.get("c", default=1) == 1:
+            return False
+        return True
+
+    @overload
+    def get(self, axis_name: str, default: None = None) -> int | None:
+        pass
+
+    @overload
+    def get(self, axis_name: str, default: int) -> int:
+        pass
+
+    def get(self, axis_name: str, default: int | None = None) -> int | None:
+        """Return the dimension/shape of the given axis name.
+
+        Args:
+            axis_name: The name of the axis (either canonical or non-canonical).
+            default: The default value to return if the axis does not exist.
+        """
+        index = self.axes_handler.get_index(axis_name)
+        if index is None:
+            return default
+        return self._shape[index]

ngio/common/_masking_roi.py

@@ -0,0 +1,153 @@
+"""Utilities to build masking regions of interest (ROIs)."""
+
+import itertools
+from collections.abc import Sequence
+
+import dask.array as da
+import numpy as np
+import scipy.ndimage as ndi
+from dask.delayed import delayed
+
+from ngio.common._roi import Roi
+from ngio.ome_zarr_meta import PixelSize
+from ngio.utils import NgioValueError
+
+
+def _compute_offsets(chunks):
+    """Given a chunks tuple, compute cumulative offsets for each axis.
+
+    Returns a list where each element is a list of offsets for that dimension.
+    """
+    offsets = []
+    for dim_chunks in chunks:
+        dim_offsets = [0]
+        for size in dim_chunks:
+            dim_offsets.append(dim_offsets[-1] + size)
+        offsets.append(dim_offsets)
+    return offsets
+
+
+def _adjust_slices(slices, offset):
+    """Adjust slices to global coordinates using the provided offset."""
+    adjusted_slices = {}
+    for label, s in slices.items():
+        adjusted = tuple(
+            slice(s_dim.start + off, s_dim.stop + off)
+            for s_dim, off in zip(s, offset, strict=True)
+        )
+        adjusted_slices[label] = adjusted
+    return adjusted_slices
+
+
+@delayed
+def _process_chunk(chunk, offset):
+    """Process a single chunk.
+
+    run ndi.find_objects and adjust the slices
+    to global coordinates using the provided offset.
+    """
+    local_slices = compute_slices(chunk)
+    local_slices = _adjust_slices(local_slices, offset)
+    return local_slices
+
+
+def _merge_slices(
+    slice1: tuple[slice, ...], slice2: tuple[slice, ...]
+) -> tuple[slice, ...]:
+    """Merge two slices."""
+    merged = []
+    for s1, s2 in zip(slice1, slice2, strict=True):
+        start = min(s1.start, s2.start)
+        stop = max(s1.stop, s2.stop)
+        merged.append(slice(start, stop))
+    return tuple(merged)
+
+
+@delayed
+def _collect_slices(
+    local_slices: list[dict[int, tuple[slice, ...]]],
+) -> dict[int, tuple[slice]]:
+    """Collect the slices from the delayed results."""
+    global_slices = {}
+    for result in local_slices:
+        for label, s in result.items():
+            if label in global_slices:
+                global_slices[label] = _merge_slices(global_slices[label], s)
+            else:
+                global_slices[label] = s
+    return global_slices
+
+
+def compute_slices(segmentation: np.ndarray) -> dict[int, tuple[slice, ...]]:
+    """Compute slices for each label in a segmentation.
+
+    Args:
+        segmentation (ndarray): The segmentation array.
+
+    Returns:
+        dict[int, tuple[slice]]: A dictionary with the label as key
+            and the slice as value.
+    """
+    slices = ndi.find_objects(segmentation)
+    slices_dict = {}
+    for label, s in enumerate(slices, start=1):
+        if s is None:
+            continue
+        else:
+            slices_dict[label] = s
+    return slices_dict
+
+
+def lazy_compute_slices(segmentation: da.Array) -> dict[int, tuple[slice, ...]]:
+    """Compute slices for each label in a segmentation."""
+    global_offsets = _compute_offsets(segmentation.chunks)
+    delayed_chunks = segmentation.to_delayed()  # type: ignore
+
+    grid_shape = tuple(len(c) for c in segmentation.chunks)
+
+    grid_indices = list(itertools.product(*[range(n) for n in grid_shape]))
+    delayed_results = []
+    for idx, chunk in zip(grid_indices, np.ravel(delayed_chunks), strict=True):
+        offset = tuple(global_offsets[dim][idx[dim]] for dim in range(len(idx)))
+        delayed_result = _process_chunk(chunk, offset)
+        delayed_results.append(delayed_result)
+
+    return _collect_slices(delayed_results).compute()
+
+
+def compute_masking_roi(
+    segmentation: np.ndarray | da.Array,
+    pixel_size: PixelSize,
+    axes_order: Sequence[str],
+) -> list[Roi]:
+    """Compute a ROIs for each label in a segmentation.
+
+    This function expects a 2D or 3D segmentation array.
+    And this function expects the axes order to be 'zyx' or 'yx'.
+    Other axes orders are not supported.
+
+    """
+    if segmentation.ndim not in [2, 3, 4]:
+        raise NgioValueError("Only 2D, 3D, and 4D segmentations are supported.")
+
+    if len(axes_order) != segmentation.ndim:
+        raise NgioValueError(
+            "The length of axes_order must match the number of dimensions "
+            "of the segmentation."
+        )
+
+    if isinstance(segmentation, da.Array):
+        slices = lazy_compute_slices(segmentation)
+    else:
+        slices = compute_slices(segmentation)
+
+    rois = []
+    for label, slice_ in slices.items():
+        assert len(slice_) == len(axes_order)
+        slices = dict(zip(axes_order, slice_, strict=True))
+        roi = Roi.from_values(
+            name=str(label), slices=slices, label=label, space="pixel"
+        )
+        roi = roi.to_world(pixel_size=pixel_size)
+        rois.append(roi)
+    return rois