ngio 0.4.0a2__py3-none-any.whl → 0.4.0a4__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,
@@ -39,7 +39,6 @@ from ngio.ome_zarr_meta.ngio_specs import (
 )
 
 __all__ = [
-    "ArrayLike",
     "AxesSetup",
     "ChannelSelectionModel",
     "DefaultNgffVersion",

ngio/common/__init__.py

@@ -1,72 +1,23 @@
 """Common classes and functions that are used across the package."""
 
-from ngio.common._array_io_pipes import (
-    build_dask_getter,
-    build_dask_setter,
-    build_masked_dask_getter,
-    build_masked_dask_setter,
-    build_masked_numpy_getter,
-    build_masked_numpy_setter,
-    build_numpy_getter,
-    build_numpy_setter,
-)
-from ngio.common._array_io_utils import (
-    ArrayLike,
-    SlicingInputType,
-    TransformProtocol,
-    apply_dask_axes_ops,
-    apply_numpy_axes_ops,
-    apply_sequence_axes_ops,
-)
 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,
-    build_roi_dask_getter,
-    build_roi_dask_setter,
-    build_roi_masked_dask_getter,
-    build_roi_masked_dask_setter,
-    build_roi_masked_numpy_getter,
-    build_roi_masked_numpy_setter,
-    build_roi_numpy_getter,
-    build_roi_numpy_setter,
-    roi_to_slicing_dict,
 )
-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",
-    "SlicingInputType",
-    "TransformProtocol",
-    "apply_dask_axes_ops",
-    "apply_numpy_axes_ops",
-    "apply_sequence_axes_ops",
-    "build_dask_getter",
-    "build_dask_setter",
-    "build_masked_dask_getter",
-    "build_masked_dask_setter",
-    "build_masked_numpy_getter",
-    "build_masked_numpy_setter",
-    "build_numpy_getter",
-    "build_numpy_setter",
-    "build_roi_dask_getter",
-    "build_roi_dask_setter",
-    "build_roi_masked_dask_getter",
-    "build_roi_masked_dask_setter",
-    "build_roi_masked_numpy_getter",
-    "build_roi_masked_numpy_setter",
-    "build_roi_numpy_getter",
-    "build_roi_numpy_setter",
     "compute_masking_roi",
     "consolidate_pyramid",
     "dask_zoom",
     "init_empty_pyramid",
     "numpy_zoom",
     "on_disk_zoom",
-    "roi_to_slicing_dict",
 ]

ngio/common/_dimensions.py

@@ -4,88 +4,68 @@ 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 AxesMapper
-from ngio.ome_zarr_meta.ngio_specs import AxisType
+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
 
 
 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.
+    """
 
     def __init__(
         self,
         shape: tuple[int, ...],
-        axes_mapper: AxesMapper,
+        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.
+            dataset: The dataset object.
         """
         self._shape = shape
-        self._axes_mapper = axes_mapper
+        self._axes_handler = dataset.axes_handler
+        self._pixel_size = dataset.pixel_size
 
-        if len(self._shape) != len(self._axes_mapper.axes):
+        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.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.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})"
 
-    @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 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_mapper.get_index(axis_name)
-        if index is None:
-            return default
-        return self._shape[index]
-
-    def get_index(self, axis_name: str) -> int | None:
-        """Return the index of the given axis name.
-
-        Args:
-            axis_name: The name of the axis (either canonical or non-canonical).
-        """
-        return self._axes_mapper.get_index(axis_name)
-
-    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 __repr__(self) -> str:
         """Return the string representation of the object."""
         return str(self)
 
     @property
-    def axes_mapper(self) -> AxesMapper:
-        """Return the axes mapper object."""
-        return self._axes_mapper
+    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, ...]:
@@ -95,7 +75,7 @@ class Dimensions:
     @property
     def axes(self) -> tuple[str, ...]:
         """Return the axes as a tuple of strings."""
-        return self._axes_mapper.axes_names
+        return self.axes_handler.axes_names
 
     @property
     def is_time_series(self) -> bool:
@@ -133,24 +113,203 @@ class Dimensions:
             return False
         return True
 
-    def is_compatible_with(self, other: "Dimensions") -> bool:
-        """Check if the dimensions are compatible with another Dimensions object.
+    @overload
+    def get(self, axis_name: str, default: None = None) -> int | None:
+        pass
+
+    @overload
+    def get(self, axis_name: str, default: int) -> int:
+        pass
 
-        Two dimensions are compatible if:
-            - they have the same number of axes (excluding channels)
-            - the shape of each axis is the same
+    def get(self, axis_name: str, default: int | None = None) -> int | None:
+        """Return the dimension 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.
         """
-        if abs(len(self.shape) - len(other.shape)) > 1:
-            # Since channels are not considered in compatibility
-            # we allow a difference of 0, 1 n-dimension in the shapes.
+        index = self.axes_handler.get_index(axis_name)
+        if index is None:
+            return default
+        return self._shape[index]
+
+    def get_index(self, axis_name: str) -> int | None:
+        """Return the index of the given axis name.
+
+        Args:
+            axis_name: The name of the axis (either canonical or non-canonical).
+        """
+        return self.axes_handler.get_index(axis_name)
+
+    def has_axis(self, axis_name: str) -> bool:
+        """Return whether the axis exists."""
+        index = self.axes_handler.get_index(axis_name)
+        if index is None:
             return False
+        return True
+
+    def require_axes_match(self, 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:
+            other (Dimensions): The other dimensions object to compare against.
+
+        Raises:
+            NgioValueError: If the axes do not match.
+        """
+        require_axes_match(self, other)
+
+    def require_dimensions_match(
+        self, 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:
+            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_dimensions_match(self, other, allow_singleton)
+
+    def require_can_be_rescaled(self, 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:
+            other (Dimensions): The other dimensions object to compare against.
+
+        """
+        require_rescalable(self, other)
 
-        for ax in self._axes_mapper.axes:
-            if ax.axis_type == AxisType.channel:
+
+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(dimensions1: Dimensions, dimensions2: 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:
+        dimensions1 (Dimensions): The first dimensions object to compare against.
+        dimensions2 (Dimensions): The second dimensions object to compare against.
+
+    Raises:
+        NgioValueError: If the axes do not match.
+    """
+    for s_axis in dimensions1.axes_handler.axes:
+        if s_axis.axis_type == "channel":
+            continue
+        o_axis = dimensions2.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 dimensions2.axes_handler.axes:
+        if o_axis.axis_type == "channel":
+            continue
+        s_axis = dimensions1.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 require_dimensions_match(
+    dimensions1: Dimensions, dimensions2: 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:
+        dimensions1 (Dimensions): The first dimensions object to compare against.
+        dimensions2 (Dimensions): The second 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(dimensions1, dimensions2)
+    for s_axis in dimensions1.axes_handler.axes:
+        if s_axis.axis_type == "channel":
+            continue
+        o_axis = dimensions2.axes_handler.get_axis(s_axis.name)
+        assert o_axis is not None  # already checked in assert_axes_match
+
+        i_dim = dimensions1.get(s_axis.name, default=1)
+        o_dim = dimensions2.get(o_axis.name, default=1)
+
+        if i_dim != o_dim:
+            if allow_singleton and (i_dim == 1 or o_dim == 1):
                 continue
+            raise NgioValueError(
+                f"Dimensions do not match for axis "
+                f"{s_axis.name}. Got {i_dim} and {o_dim}."
+            )
 
-            self_shape = self.get(ax.on_disk_name, default=None)
-            other_shape = other.get(ax.on_disk_name, default=None)
-            if self_shape != other_shape:
-                return False
-        return True
+
+def require_rescalable(dimensions1: Dimensions, dimensions2: 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:
+        dimensions1 (Dimensions): The first dimensions object to compare against.
+        dimensions2 (Dimensions): The second dimensions object to compare against.
+
+    """
+    require_axes_match(dimensions1, dimensions2)
+    for ax1 in dimensions1.axes_handler.axes:
+        if ax1.axis_type == "channel":
+            continue
+        ax2 = dimensions2.axes_handler.get_axis(ax1.name)
+        assert ax2 is not None, "Axes do not match."
+        px1 = dimensions1.pixel_size.get(ax1.name, default=1.0)
+        px2 = dimensions2.pixel_size.get(ax2.name, default=1.0)
+        shape1 = dimensions1.get(ax1.name, default=1)
+        shape2 = dimensions2.get(ax2.name, default=1)
+        scale = px1 / px2
+        if not _are_compatible(
+            shape1=shape1,
+            shape2=shape2,
+            scaling=scale,
+        ):
+            raise NgioValueError(
+                f"Image1 with shape {dimensions1.shape}, "
+                f"and pixel size {dimensions1.pixel_size}, "
+                f"cannot be rescaled to "
+                f"Image2 with shape {dimensions2.shape}, "
+                f"and pixel size {dimensions2.pixel_size}. "
+            )

ngio/common/_pyramid.py

@@ -5,8 +5,14 @@ from typing import Literal
 import dask.array as da
 import numpy as np
 import zarr
+from zarr.types import DIMENSION_SEPARATOR
 
-from ngio.common._zoom import _zoom_inputs_check, dask_zoom, numpy_zoom
+from ngio.common._zoom import (
+    InterpolationOrder,
+    _zoom_inputs_check,
+    dask_zoom,
+    numpy_zoom,
+)
 from ngio.utils import (
     AccessModeLiteral,
     NgioValueError,
@@ -18,7 +24,7 @@ from ngio.utils import (
 def _on_disk_numpy_zoom(
     source: zarr.Array,
     target: zarr.Array,
-    order: Literal[0, 1, 2] = 1,
+    order: InterpolationOrder,
 ) -> None:
     target[...] = numpy_zoom(source[...], target_shape=target.shape, order=order)
 
@@ -26,7 +32,7 @@ def _on_disk_numpy_zoom(
 def _on_disk_dask_zoom(
     source: zarr.Array,
     target: zarr.Array,
-    order: Literal[0, 1, 2] = 1,
+    order: InterpolationOrder,
 ) -> None:
     source_array = da.from_zarr(source)
     target_array = dask_zoom(source_array, target_shape=target.shape, order=order)
@@ -39,7 +45,7 @@ def _on_disk_dask_zoom(
 def _on_disk_coarsen(
     source: zarr.Array,
     target: zarr.Array,
-    _order: Literal[0, 1] = 1,
+    order: InterpolationOrder = "linear",
     aggregation_function: Callable | None = None,
 ) -> None:
     """Apply a coarsening operation from a source zarr array to a target zarr array.
@@ -47,10 +53,10 @@ def _on_disk_coarsen(
     Args:
         source (zarr.Array): The source array to coarsen.
         target (zarr.Array): The target array to save the coarsened result to.
-        _order (Literal[0, 1]): The order of interpolation is not really implemented
+        order (InterpolationOrder): The order of interpolation is not really implemented
             for coarsening, but it is kept for compatibility with the zoom function.
-            _order=1 -> linear interpolation ~ np.mean
-            _order=0 -> nearest interpolation ~ np.max
+            order="linear" -> linear interpolation ~ np.mean
+            order="nearest" -> nearest interpolation ~ np.max
         aggregation_function (np.ufunc): The aggregation function to use.
     """
     source_array = da.from_zarr(source)
@@ -64,13 +70,15 @@ def _on_disk_coarsen(
     )
 
     if aggregation_function is None:
-        if _order == 1:
+        if order == "linear":
             aggregation_function = np.mean
-        elif _order == 0:
+        elif order == "nearest":
             aggregation_function = np.max
+        elif order == "cubic":
+            raise NgioValueError("Cubic interpolation is not supported for coarsening.")
         else:
             raise NgioValueError(
-                f"Aggregation function must be provided for order {_order}"
+                f"Aggregation function must be provided for order {order}"
             )
 
     coarsening_setup = {}
@@ -96,7 +104,7 @@ def _on_disk_coarsen(
 def on_disk_zoom(
     source: zarr.Array,
     target: zarr.Array,
-    order: Literal[0, 1, 2] = 1,
+    order: InterpolationOrder = "linear",
     mode: Literal["dask", "numpy", "coarsen"] = "dask",
 ) -> None:
     """Apply a zoom operation from a source zarr array to a target zarr array.
@@ -104,7 +112,7 @@ def on_disk_zoom(
     Args:
         source (zarr.Array): The source array to zoom.
         target (zarr.Array): The target array to save the zoomed result to.
-        order (Literal[0, 1, 2]): The order of interpolation. Defaults to 1.
+        order (InterpolationOrder): The order of interpolation. Defaults to "linear".
         mode (Literal["dask", "numpy", "coarsen"]): The mode to use. Defaults to "dask".
     """
     if not isinstance(source, zarr.Array):
@@ -155,7 +163,7 @@ def _find_closest_arrays(
 def consolidate_pyramid(
     source: zarr.Array,
     targets: list[zarr.Array],
-    order: Literal[0, 1, 2] = 1,
+    order: InterpolationOrder = "linear",
     mode: Literal["dask", "numpy", "coarsen"] = "dask",
 ) -> None:
     """Consolidate the Zarr array."""
@@ -177,6 +185,15 @@ def consolidate_pyramid(
         processed.append(target_image)
 
 
+def _maybe_int(value: float | int) -> float | int:
+    """Convert a float to an int if it is an integer."""
+    if isinstance(value, int):
+        return value
+    if value.is_integer():
+        return int(value)
+    return value
+
+
 def init_empty_pyramid(
     store: StoreOrGroup,
     paths: list[str],
@@ -185,6 +202,8 @@ def init_empty_pyramid(
     chunks: Sequence[int] | None = None,
     dtype: str = "uint16",
     mode: AccessModeLiteral = "a",
+    dimension_separator: DIMENSION_SEPARATOR = "/",
+    compressor="default",
 ) -> None:
     # Return the an Image object
     if chunks is not None and len(chunks) != len(ref_shape):
@@ -200,6 +219,10 @@ def init_empty_pyramid(
             "The shape and scaling factor must have the same number of dimensions."
         )
 
+    # Ensure scaling factors are int if possible
+    # To reduce the risk of floating point issues
+    scaling_factors = [_maybe_int(s) for s in scaling_factors]
+
     root_group = open_group_wrapper(store, mode=mode)
 
     for path in paths:
@@ -213,22 +236,18 @@ def init_empty_pyramid(
             shape=ref_shape,
             dtype=dtype,
             chunks=chunks,
-            dimension_separator="/",
+            dimension_separator=dimension_separator,
             overwrite=True,
+            compressor=compressor,
         )
 
-        # Todo redo this with when a proper build of pyramid is implemented
-        _shape = []
-        for s, sc in zip(ref_shape, scaling_factors, strict=True):
-            if math.floor(s / sc) % 2 == 0:
-                _shape.append(math.floor(s / sc))
-            else:
-                _shape.append(math.ceil(s / sc))
+        _shape = [
+            math.floor(s / sc) for s, sc in zip(ref_shape, scaling_factors, strict=True)
+        ]
         ref_shape = _shape
 
         if chunks is None:
             chunks = new_arr.chunks
-            if chunks is None:
-                raise NgioValueError("Something went wrong with the chunks")
+            assert chunks is not None
         chunks = [min(c, s) for c, s in zip(chunks, ref_shape, strict=True)]
     return None