ngio 0.3.4__py3-none-any.whl → 0.4.0__py3-none-any.whl

ngio/__init__.py

@@ -9,7 +9,7 @@ except PackageNotFoundError:  # pragma: no cover
 __author__ = "Lorenzo Cerrone"
 __email__ = "lorenzo.cerrone@uzh.ch"
 
-from ngio.common import ArrayLike, Dimensions, Roi, RoiPixels
+from ngio.common import Dimensions, Roi, RoiPixels
 from ngio.hcs import (
     OmeZarrPlate,
     OmeZarrWell,
@@ -19,12 +19,15 @@ from ngio.hcs import (
     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 (
@@ -36,8 +39,8 @@ from ngio.ome_zarr_meta.ngio_specs import (
 )
 
 __all__ = [
-    "ArrayLike",
     "AxesSetup",
+    "ChannelSelectionModel",
     "DefaultNgffVersion",
     "Dimensions",
     "Image",
@@ -54,7 +57,9 @@ __all__ = [
     "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

@@ -1,70 +1,23 @@
 """Common classes and functions that are used across the package."""
 
-from ngio.common._array_pipe import (
-    get_masked_pipe,
-    get_pipe,
-    set_masked_pipe,
-    set_pipe,
-)
-from ngio.common._axes_transforms import (
-    transform_dask_array,
-    transform_list,
-    transform_numpy_array,
-)
-from ngio.common._common_types import ArrayLike
 from ngio.common._dimensions import Dimensions
 from ngio.common._masking_roi import compute_masking_roi
 from ngio.common._pyramid import consolidate_pyramid, init_empty_pyramid, on_disk_zoom
-from ngio.common._roi import Roi, RoiPixels, roi_to_slice_kwargs
-from ngio.common._slicer import (
-    SliceTransform,
-    compute_and_slices,
-    dask_get_slice,
-    dask_set_slice,
-    numpy_get_slice,
-    numpy_set_slice,
-)
-from ngio.common._table_ops import (
-    concatenate_image_tables,
-    concatenate_image_tables_as,
-    concatenate_image_tables_as_async,
-    concatenate_image_tables_async,
-    conctatenate_tables,
-    list_image_tables,
-    list_image_tables_async,
+from ngio.common._roi import (
+    Roi,
+    RoiPixels,
 )
-from ngio.common._zoom import dask_zoom, numpy_zoom
+from ngio.common._zoom import InterpolationOrder, dask_zoom, numpy_zoom
 
 __all__ = [
-    "ArrayLike",
     "Dimensions",
+    "InterpolationOrder",
     "Roi",
     "RoiPixels",
-    "SliceTransform",
-    "compute_and_slices",
     "compute_masking_roi",
-    "concatenate_image_tables",
-    "concatenate_image_tables_as",
-    "concatenate_image_tables_as_async",
-    "concatenate_image_tables_async",
-    "conctatenate_tables",
     "consolidate_pyramid",
-    "dask_get_slice",
-    "dask_set_slice",
     "dask_zoom",
-    "get_masked_pipe",
-    "get_pipe",
     "init_empty_pyramid",
-    "list_image_tables",
-    "list_image_tables_async",
-    "numpy_get_slice",
-    "numpy_set_slice",
     "numpy_zoom",
     "on_disk_zoom",
-    "roi_to_slice_kwargs",
-    "set_masked_pipe",
-    "set_pipe",
-    "transform_dask_array",
-    "transform_list",
-    "transform_numpy_array",
 ]

ngio/common/_dimensions.py

@@ -4,117 +4,332 @@ This is not related to the NGFF metadata,
 but it is based on the actual metadata of the image data.
 """
 
-from collections.abc import Collection
+import math
+from typing import overload
 
-from ngio.common._axes_transforms import transform_list
-from ngio.ome_zarr_meta import AxesMapper
-from ngio.utils import NgioValidationError, NgioValueError
+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."""
+    """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, ...],
-        axes_mapper: AxesMapper,
+        chunks: tuple[int, ...],
+        dataset: Dataset,
     ) -> None:
         """Create a Dimension object from a Zarr array.
 
         Args:
             shape: The shape of the Zarr array.
-            axes_mapper: The axes mapper object.
+            chunks: The chunks of the Zarr array.
+            dataset: The dataset object.
         """
         self._shape = shape
-        self._axes_mapper = axes_mapper
+        self._chunks = chunks
+        self._axes_handler = dataset.axes_handler
+        self._pixel_size = dataset.pixel_size
 
-        if len(self._shape) != len(self._axes_mapper.on_disk_axes):
-            raise NgioValidationError(
+        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_mapper.on_disk_axes_names} but got shape "
+                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.on_disk_name}: {s}"
-            for ax, s in zip(self._axes_mapper.on_disk_axes, self._shape, strict=True)
+            f"{ax.name}: {s}"
+            for ax, s in zip(self._axes_handler.axes, self._shape, strict=True)
         )
         return f"Dimensions({dims})"
 
-    def get(self, axis_name: str, strict: bool = True) -> int:
-        """Return the dimension of the given axis name.
-
-        Args:
-            axis_name: The name of the axis (either canonical or non-canonical).
-            strict: If True, raise an error if the axis does not exist.
-        """
-        index = self._axes_mapper.get_index(axis_name)
-        if index is None and strict:
-            raise NgioValueError(f"Axis {axis_name} does not exist.")
-        elif index is None:
-            return 1
-        return self._shape[index]
-
-    def has_axis(self, axis_name: str) -> bool:
-        """Return whether the axis exists."""
-        index = self._axes_mapper.get_axis(axis_name)
-        if index is None:
-            return False
-        return True
-
-    def get_shape(self, axes_order: Collection[str]) -> tuple[int, ...]:
-        """Return the shape in the given axes order."""
-        transforms = self._axes_mapper.to_order(axes_order)
-        return tuple(transform_list(list(self._shape), 1, transforms))
-
-    def get_canonical_shape(self) -> tuple[int, ...]:
-        """Return the shape in the canonical order."""
-        transforms = self._axes_mapper.to_canonical()
-        return tuple(transform_list(list(self._shape), 1, transforms))
-
     def __repr__(self) -> str:
         """Return the string representation of the object."""
         return str(self)
 
     @property
-    def on_disk_shape(self) -> tuple[int, ...]:
+    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 tuple(self._shape)
+        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 data is a time series."""
-        if self.get("t", strict=False) == 1:
+        """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 data is 2D."""
-        if self.get("z", strict=False) != 1:
+        """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 data is a 2D time series."""
+        """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 data is 3D."""
+        """Return whether the image is 3D."""
         return not self.is_2d
 
     @property
     def is_3d_time_series(self) -> bool:
-        """Return whether the data is a 3D time series."""
+        """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 data has multiple channels."""
-        if self.get("c", strict=False) == 1:
+        """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

@@ -2,11 +2,10 @@
 
 import itertools
 
-import dask
 import dask.array as da
-import dask.delayed
 import numpy as np
 import scipy.ndimage as ndi
+from dask.delayed import delayed
 
 from ngio.common._roi import Roi, RoiPixels
 from ngio.ome_zarr_meta import PixelSize
@@ -39,7 +38,7 @@ def _adjust_slices(slices, offset):
     return adjusted_slices
 
 
-@dask.delayed
+@delayed
 def _process_chunk(chunk, offset):
     """Process a single chunk.
 
@@ -63,7 +62,7 @@ def _merge_slices(
     return tuple(merged)
 
 
-@dask.delayed
+@delayed
 def _collect_slices(
     local_slices: list[dict[int, tuple[slice, ...]]],
 ) -> dict[int, tuple[slice]]:
@@ -101,7 +100,7 @@ def compute_slices(segmentation: np.ndarray) -> dict[int, tuple[slice, ...]]:
 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()
+    delayed_chunks = segmentation.to_delayed()  # type: ignore
 
     grid_shape = tuple(len(c) for c in segmentation.chunks)
 
@@ -125,8 +124,8 @@ def compute_masking_roi(
     Other axes orders are not supported.
 
     """
-    if segmentation.ndim not in [2, 3]:
-        raise NgioValueError("Only 2D and 3D segmentations are supported.")
+    if segmentation.ndim not in [2, 3, 4]:
+        raise NgioValueError("Only 2D, 3D, and 4D segmentations are supported.")
 
     if isinstance(segmentation, da.Array):
         slices = lazy_compute_slices(segmentation)
@@ -136,21 +135,50 @@ def compute_masking_roi(
     rois = []
     for label, slice_ in slices.items():
         if len(slice_) == 2:
-            min_z, min_y, min_x = 0, slice_[0].start, slice_[1].start
-            max_z, max_y, max_x = 1, slice_[0].stop, slice_[1].stop
+            min_t, max_t = None, None
+            min_z, max_z = None, None
+            min_y, min_x = slice_[0].start, slice_[1].start
+            max_y, max_x = slice_[0].stop, slice_[1].stop
         elif len(slice_) == 3:
+            min_t, max_t = None, None
             min_z, min_y, min_x = slice_[0].start, slice_[1].start, slice_[2].start
             max_z, max_y, max_x = slice_[0].stop, slice_[1].stop, slice_[2].stop
+        elif len(slice_) == 4:
+            min_t, min_z, min_y, min_x = (
+                slice_[0].start,
+                slice_[1].start,
+                slice_[2].start,
+                slice_[3].start,
+            )
+            max_t, max_z, max_y, max_x = (
+                slice_[0].stop,
+                slice_[1].stop,
+                slice_[2].stop,
+                slice_[3].stop,
+            )
         else:
             raise ValueError("Invalid slice length.")
+
+        if max_t is None:
+            t_length = None
+        else:
+            t_length = max_t - min_t
+
+        if max_z is None:
+            z_length = None
+        else:
+            z_length = max_z - min_z
+
         roi = RoiPixels(
             name=str(label),
             x_length=max_x - min_x,
             y_length=max_y - min_y,
-            z_length=max_z - min_z,
+            z_length=z_length,
+            t_length=t_length,
             x=min_x,
             y=min_y,
             z=min_z,
+            label=label,
         )
 
         roi = roi.to_roi(pixel_size)