ngio 0.4.0a2__tar.gz → 0.4.0a4__tar.gz

{ngio-0.4.0a2 → ngio-0.4.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ngio
-Version: 0.4.0a2
+Version: 0.4.0a4
 Summary: Next Generation file format IO
 Project-URL: homepage, https://github.com/BioVisionCenter/ngio
 Project-URL: repository, https://github.com/BioVisionCenter/ngio

{ngio-0.4.0a2 → ngio-0.4.0a4}/docs/getting_started/3_tables.md

@@ -38,7 +38,7 @@ Ngio supports three types of tables: `roi_table`, `feature_table`, and `masking_
     image_data = image_3.get_array(c=0)
     image_data = np.squeeze(image_data)
     roi = roi_table.get("FOV_1")
-    roi = roi.to_roi_pixels(pixel_size=image_3.pixel_size, dimensions=image_3.dimensions)
+    roi = roi.to_roi_pixels(pixel_size=image_3.pixel_size)
     #label_3 = ome_zarr_container.get_label("nuclei", pixel_size=image_3.pixel_size)
     #label_data = label_3.get_array()
     #label_data = np.squeeze(label_data)

{ngio-0.4.0a2 → ngio-0.4.0a4}/src/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-0.4.0a4/src/ngio/common/__init__.py

@@ -0,0 +1,23 @@
+"""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 consolidate_pyramid, init_empty_pyramid, on_disk_zoom
+from ngio.common._roi import (
+    Roi,
+    RoiPixels,
+)
+from ngio.common._zoom import InterpolationOrder, dask_zoom, numpy_zoom
+
+__all__ = [
+    "Dimensions",
+    "InterpolationOrder",
+    "Roi",
+    "RoiPixels",
+    "compute_masking_roi",
+    "consolidate_pyramid",
+    "dask_zoom",
+    "init_empty_pyramid",
+    "numpy_zoom",
+    "on_disk_zoom",
+]

ngio-0.4.0a4/src/ngio/common/_dimensions.py

@@ -0,0 +1,315 @@
+"""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
+
+
+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.
+    """
+
+    def __init__(
+        self,
+        shape: tuple[int, ...],
+        dataset: Dataset,
+    ) -> None:
+        """Create a Dimension object from a Zarr array.
+
+        Args:
+            shape: The shape of the Zarr array.
+            dataset: The dataset object.
+        """
+        self._shape = shape
+        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 tuple(self._shape)
+
+    @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", default=1) == 1:
+            return False
+        return True
+
+    @property
+    def is_2d(self) -> bool:
+        """Return whether the data 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 self.is_2d and self.is_time_series
+
+    @property
+    def is_3d(self) -> bool:
+        """Return whether the data 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 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", 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 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]
+
+    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)
+
+
+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}."
+            )
+
+
+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-0.4.0a2 → ngio-0.4.0a4}/src/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