ngio 0.5.0__py3-none-any.whl → 0.5.0a2__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 Dimensions, Roi, RoiSlice
+from ngio.common import Dimensions, Roi, RoiPixels
 from ngio.hcs import (
     OmeZarrPlate,
     OmeZarrWell,
@@ -37,7 +37,6 @@ from ngio.ome_zarr_meta.ngio_specs import (
     NgffVersions,
     PixelSize,
 )
-from ngio.utils import NgioSupportedStore, StoreOrGroup
 
 __all__ = [
     "AxesSetup",
@@ -48,14 +47,12 @@ __all__ = [
     "ImageInWellPath",
     "Label",
     "NgffVersions",
-    "NgioSupportedStore",
     "OmeZarrContainer",
     "OmeZarrPlate",
     "OmeZarrWell",
     "PixelSize",
     "Roi",
-    "RoiSlice",
-    "StoreOrGroup",
+    "RoiPixels",
     "create_empty_ome_zarr",
     "create_empty_plate",
     "create_empty_well",

ngio/common/__init__.py

@@ -2,27 +2,22 @@
 
 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._pyramid import consolidate_pyramid, init_empty_pyramid, on_disk_zoom
+from ngio.common._roi import (
+    Roi,
+    RoiPixels,
 )
-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",
+    "RoiPixels",
     "compute_masking_roi",
     "consolidate_pyramid",
     "dask_zoom",
+    "init_empty_pyramid",
     "numpy_zoom",
     "on_disk_zoom",
 ]

ngio/common/_masking_roi.py

@@ -1,14 +1,13 @@
 """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.common._roi import Roi, RoiPixels
 from ngio.ome_zarr_meta import PixelSize
 from ngio.utils import NgioValueError
 
@@ -99,14 +98,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 using lazy evaluation.
-
-    Args:
-        segmentation: The dask segmentation array.
-
-    Returns:
-        A dictionary mapping label IDs to their bounding box slices.
-    """
+    """Compute slices for each label in a segmentation."""
     global_offsets = _compute_offsets(segmentation.chunks)
     delayed_chunks = segmentation.to_delayed()  # type: ignore
 
@@ -123,32 +115,18 @@ def lazy_compute_slices(segmentation: da.Array) -> dict[int, tuple[slice, ...]]:
 
 
 def compute_masking_roi(
-    segmentation: np.ndarray | da.Array,
-    pixel_size: PixelSize,
-    axes_order: Sequence[str],
+    segmentation: np.ndarray | da.Array, pixel_size: PixelSize
 ) -> list[Roi]:
-    """Compute ROIs for each label in a segmentation.
-
-    This function expects a 2D, 3D, or 4D segmentation array.
-    The axes order should match the segmentation dimensions.
+    """Compute a ROIs for each label in a segmentation.
 
-    Args:
-        segmentation: The segmentation array (2D, 3D, or 4D).
-        pixel_size: The pixel size metadata for coordinate conversion.
-        axes_order: The order of axes in the segmentation (e.g., 'zyx' or 'yx').
+    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.
 
-    Returns:
-        A list of Roi objects, one for each unique label in the segmentation.
     """
     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:
@@ -156,11 +134,53 @@ def compute_masking_roi(
 
     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"
+        if len(slice_) == 2:
+            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=z_length,
+            t_length=t_length,
+            x=min_x,
+            y=min_y,
+            z=min_z,
+            label=label,
         )
-        roi = roi.to_world(pixel_size=pixel_size)
+
+        roi = roi.to_roi(pixel_size)
         rois.append(roi)
     return rois

ngio/common/_pyramid.py

@@ -1,13 +1,13 @@
-import itertools
 import math
-from collections.abc import Callable, Mapping, Sequence
-from typing import Any, Literal
+from collections.abc import Callable, Sequence
+from typing import Literal
 
 import dask.array as da
 import numpy as np
 import zarr
-from pydantic import BaseModel, ConfigDict, model_validator
+from zarr.core.array import CompressorLike
 
+# from zarr.types import DIMENSION_SEPARATOR
 from ngio.common._zoom import (
     InterpolationOrder,
     _zoom_inputs_check,
@@ -15,7 +15,10 @@ from ngio.common._zoom import (
     numpy_zoom,
 )
 from ngio.utils import (
+    AccessModeLiteral,
     NgioValueError,
+    StoreOrGroup,
+    open_group_wrapper,
 )
 
 
@@ -94,7 +97,16 @@ def _on_disk_coarsen(
 
     coarsening_setup = {}
     for i, s in enumerate(_scale):
-        coarsening_setup[i] = int(np.round(1 / s))
+        factor = 1 / s
+        # This check is very strict, but it is necessary to avoid
+        # a few pixels shift in the coarsening
+        # We could add a tolerance
+        if factor.is_integer():
+            coarsening_setup[i] = int(factor)
+        else:
+            raise NgioValueError(
+                f"Coarsening factor must be an integer, got {factor} on axis {i}"
+            )
 
     out_target = da.coarsen(
         aggregation_function, source_array, coarsening_setup, trim_excess=True
@@ -187,321 +199,85 @@ def consolidate_pyramid(
         processed.append(target_image)
 
 
-################################################
-#
-# Builders for image pyramids
-#
-################################################
-
-ChunksLike = tuple[int, ...] | Literal["auto"]
-ShardsLike = tuple[int, ...] | Literal["auto"]
-
-
-def compute_shapes_from_scaling_factors(
-    base_shape: tuple[int, ...],
-    scaling_factors: tuple[float, ...],
-    num_levels: int,
-) -> list[tuple[int, ...]]:
-    """Compute the shapes of each level in the pyramid from scaling factors.
-
-    Args:
-        base_shape (tuple[int, ...]): The shape of the base level.
-        scaling_factors (tuple[float, ...]): The scaling factors between levels.
-        num_levels (int): The number of levels in the pyramid.
-
-    Returns:
-        list[tuple[int, ...]]: The shapes of each level in the pyramid.
-    """
-    shapes = []
-    current_shape = base_shape
-    for _ in range(num_levels):
-        shapes.append(current_shape)
-        current_shape = tuple(
-            max(1, math.floor(s / f))
-            for s, f in zip(current_shape, scaling_factors, strict=True)
+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],
+    ref_shape: Sequence[int],
+    scaling_factors: Sequence[float],
+    axes: Sequence[str],
+    chunks: Sequence[int] | Literal["auto"] = "auto",
+    dtype: str = "uint16",
+    mode: AccessModeLiteral = "a",
+    dimension_separator: Literal[".", "/"] = "/",
+    compressors: CompressorLike = "auto",
+    zarr_format: Literal[2, 3] = 2,
+) -> None:
+    # Return the an Image object
+    if chunks != "auto" and len(chunks) != len(ref_shape):
+        raise NgioValueError(
+            "The shape and chunks must have the same number of dimensions."
         )
-    return shapes
 
+    if chunks != "auto":
+        chunks = tuple(min(c, s) for c, s in zip(chunks, ref_shape, strict=True))
+    else:
+        chunks = "auto"
 
-def _check_order(shapes: Sequence[tuple[int, ...]]):
-    """Check if the shapes are in decreasing order."""
-    num_pixels = [np.prod(shape) for shape in shapes]
-    for i in range(1, len(num_pixels)):
-        if num_pixels[i] >= num_pixels[i - 1]:
-            raise NgioValueError("Shapes are not in decreasing order.")
-
+    if len(ref_shape) != len(scaling_factors):
+        raise NgioValueError(
+            "The shape and scaling factor must have the same number of dimensions."
+        )
 
-class PyramidLevel(BaseModel):
-    path: str
-    shape: tuple[int, ...]
-    scale: tuple[float, ...]
-    translation: tuple[float, ...]
-    chunks: ChunksLike = "auto"
-    shards: ShardsLike | None = None
+    # 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]
 
-    @model_validator(mode="after")
-    def _model_validation(self) -> "PyramidLevel":
-        # Same length as shape
-        if len(self.scale) != len(self.shape):
-            raise NgioValueError(
-                "Scale must have the same length as shape "
-                f"({len(self.shape)}), got {len(self.scale)}"
-            )
-        if any(isinstance(s, float) and s < 0 for s in self.scale):
-            raise NgioValueError("Scale values must be positive.")
+    root_group = open_group_wrapper(store, mode=mode, zarr_format=zarr_format)
 
-        if len(self.translation) != len(self.shape):
-            raise NgioValueError(
-                "Translation must have the same length as shape "
-                f"({len(self.shape)}), got {len(self.translation)}"
-            )
+    array_static_kwargs = {
+        "dtype": dtype,
+        "overwrite": True,
+        "compressors": compressors,
+    }
 
-        if isinstance(self.chunks, tuple):
-            if len(self.chunks) != len(self.shape):
-                raise NgioValueError(
-                    "Chunks must have the same length as shape "
-                    f"({len(self.shape)}), got {len(self.chunks)}"
-                )
-            normalized_chunks = []
-            for dim_size, chunk_size in zip(self.shape, self.chunks, strict=True):
-                normalized_chunks.append(min(dim_size, chunk_size))
-            self.chunks = tuple(normalized_chunks)
-
-        if isinstance(self.shards, tuple):
-            if len(self.shards) != len(self.shape):
-                raise NgioValueError(
-                    "Shards must have the same length as shape "
-                    f"({len(self.shape)}), got {len(self.shards)}"
-                )
-            normalized_shards = []
-            for dim_size, shard_size in zip(self.shape, self.shards, strict=True):
-                normalized_shards.append(min(dim_size, shard_size))
-            self.shards = tuple(normalized_shards)
-        return self
-
-
-def compute_scales_from_shapes(
-    shapes: Sequence[tuple[int, ...]],
-    base_scale: tuple[float, ...],
-) -> list[tuple[float, ...]]:
-    scales = [base_scale]
-    scale_ = base_scale
-    for current_shape, next_shape in itertools.pairwise(shapes):
-        # This only works for downsampling pyramids
-        # The _check_order function (called before) ensures that the
-        # shapes are decreasing
-        _scaling_factor = tuple(
-            s1 / s2
-            for s1, s2 in zip(
-                current_shape,
-                next_shape,
-                strict=True,
-            )
-        )
-        scale_ = tuple(s * f for s, f in zip(scale_, _scaling_factor, strict=True))
-        scales.append(scale_)
-    return scales
-
-
-def _compute_translations_from_shapes(
-    scales: Sequence[tuple[float, ...]],
-    base_translation: Sequence[float] | None,
-) -> list[tuple[float, ...]]:
-    translations = []
-    if base_translation is None:
-        n_dim = len(scales[0])
-        base_translation = tuple(0.0 for _ in range(n_dim))
+    if zarr_format == 2:
+        array_static_kwargs["chunk_key_encoding"] = {
+            "name": "v2",
+            "separator": dimension_separator,
+        }
     else:
-        base_translation = tuple(base_translation)
-
-    translation_ = base_translation
-    for _ in scales:
-        # TBD: How to update translation
-        # For now, we keep it constant but we should probably change it
-        # to reflect the shift introduced by downsampling
-        # translation_ = translation_ + _scaling_factor
-        translations.append(translation_)
-    return translations
-
-
-def _compute_scales_from_factors(
-    base_scale: tuple[float, ...], scaling_factors: tuple[float, ...], num_levels: int
-) -> list[tuple[float, ...]]:
-    precision_scales = []
-    current_scale = base_scale
-    for _ in range(num_levels):
-        precision_scales.append(current_scale)
-        current_scale = tuple(
-            s * f for s, f in zip(current_scale, scaling_factors, strict=True)
-        )
-    return precision_scales
-
-
-class ImagePyramidBuilder(BaseModel):
-    levels: list[PyramidLevel]
-    axes: tuple[str, ...]
-    data_type: str = "uint16"
-    dimension_separator: Literal[".", "/"] = "/"
-    compressors: Any = "auto"
-    zarr_format: Literal[2, 3] = 2
-    other_array_kwargs: Mapping[str, Any] = {}
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    @classmethod
-    def from_scaling_factors(
-        cls,
-        levels_paths: tuple[str, ...],
-        scaling_factors: tuple[float, ...],
-        base_shape: tuple[int, ...],
-        base_scale: tuple[float, ...],
-        axes: tuple[str, ...],
-        base_translation: Sequence[float] | None = None,
-        chunks: ChunksLike = "auto",
-        shards: ShardsLike | None = None,
-        data_type: str = "uint16",
-        dimension_separator: Literal[".", "/"] = "/",
-        compressors: Any = "auto",
-        zarr_format: Literal[2, 3] = 2,
-        other_array_kwargs: Mapping[str, Any] | None = None,
-        precision_scale: bool = True,
-    ) -> "ImagePyramidBuilder":
-        # Since shapes needs to be rounded to integers, we compute them here
-        # and then pass them to from_shapes
-        # This ensures that the shapes and scaling factors are consistent
-        # and avoids accumulation of rounding errors
-        shapes = compute_shapes_from_scaling_factors(
-            base_shape=base_shape,
-            scaling_factors=scaling_factors,
-            num_levels=len(levels_paths),
-        )
+        array_static_kwargs["chunk_key_encoding"] = {
+            "name": "default",
+            "separator": dimension_separator,
+        }
+        array_static_kwargs["dimension_names"] = axes
 
-        if precision_scale:
-            # Compute precise scales from shapes
-            # Since shapes are rounded to integers, the scaling factors
-            # may not be exactly the same as the input scaling factors
-            # Thus, we compute the scales from the shapes to ensure consistency
-            base_scale_ = compute_scales_from_shapes(
-                shapes=shapes,
-                base_scale=base_scale,
-            )
-        else:
-            base_scale_ = _compute_scales_from_factors(
-                base_scale=base_scale,
-                scaling_factors=scaling_factors,
-                num_levels=len(levels_paths),
+    for path in paths:
+        if any(s < 1 for s in ref_shape):
+            raise NgioValueError(
+                "Level shape must be at least 1 on all dimensions. "
+                f"Calculated shape: {ref_shape} at level {path}."
             )
-
-        return cls.from_shapes(
-            shapes=shapes,
-            base_scale=base_scale_,
-            axes=axes,
-            base_translation=base_translation,
-            levels_paths=levels_paths,
+        new_arr = root_group.create_array(
+            name=path,
+            shape=tuple(ref_shape),
             chunks=chunks,
-            shards=shards,
-            data_type=data_type,
-            dimension_separator=dimension_separator,
-            compressors=compressors,
-            zarr_format=zarr_format,
-            other_array_kwargs=other_array_kwargs,
+            **array_static_kwargs,
         )
 
-    @classmethod
-    def from_shapes(
-        cls,
-        shapes: Sequence[tuple[int, ...]],
-        base_scale: tuple[float, ...] | list[tuple[float, ...]],
-        axes: tuple[str, ...],
-        base_translation: Sequence[float] | None = None,
-        levels_paths: Sequence[str] | None = None,
-        chunks: ChunksLike = "auto",
-        shards: ShardsLike | None = None,
-        data_type: str = "uint16",
-        dimension_separator: Literal[".", "/"] = "/",
-        compressors: Any = "auto",
-        zarr_format: Literal[2, 3] = 2,
-        other_array_kwargs: Mapping[str, Any] | None = None,
-    ) -> "ImagePyramidBuilder":
-        levels = []
-        if levels_paths is None:
-            levels_paths = tuple(str(i) for i in range(len(shapes)))
-
-        _check_order(shapes)
-        if isinstance(base_scale, tuple) and all(
-            isinstance(s, float) for s in base_scale
-        ):
-            scales = compute_scales_from_shapes(shapes, base_scale)
-        elif isinstance(base_scale, list):
-            scales = base_scale
-            if len(scales) != len(shapes):
-                raise NgioValueError(
-                    "Scales must have the same length as shapes "
-                    f"({len(shapes)}), got {len(scales)}"
-                )
-        else:
-            raise NgioValueError(
-                "base_scale must be either a tuple of floats or a list of tuples "
-                " of floats."
-            )
-
-        translations = _compute_translations_from_shapes(scales, base_translation)
-        for level_path, shape, scale, translation in zip(
-            levels_paths,
-            shapes,
-            scales,
-            translations,
-            strict=True,
-        ):
-            level = PyramidLevel(
-                path=level_path,
-                shape=shape,
-                scale=scale,
-                translation=translation,
-                chunks=chunks,
-                shards=shards,
-            )
-            levels.append(level)
-        other_array_kwargs = other_array_kwargs or {}
-        return cls(
-            levels=levels,
-            axes=axes,
-            data_type=data_type,
-            dimension_separator=dimension_separator,
-            compressors=compressors,
-            zarr_format=zarr_format,
-            other_array_kwargs=other_array_kwargs,
+        ref_shape = [
+            math.floor(s / sc) for s, sc in zip(ref_shape, scaling_factors, strict=True)
+        ]
+        chunks = tuple(
+            min(c, s) for c, s in zip(new_arr.chunks, ref_shape, strict=True)
         )
-
-    def to_zarr(self, group: zarr.Group) -> None:
-        """Save the pyramid specification to a Zarr group.
-
-        Args:
-            group (zarr.Group): The Zarr group to save the pyramid specification to.
-        """
-        array_static_kwargs = {
-            "dtype": self.data_type,
-            "overwrite": True,
-            "compressors": self.compressors,
-            **self.other_array_kwargs,
-        }
-
-        if self.zarr_format == 2:
-            array_static_kwargs["chunk_key_encoding"] = {
-                "name": "v2",
-                "separator": self.dimension_separator,
-            }
-        else:
-            array_static_kwargs["chunk_key_encoding"] = {
-                "name": "default",
-                "separator": self.dimension_separator,
-            }
-            array_static_kwargs["dimension_names"] = self.axes
-        for p_level in self.levels:
-            group.create_array(
-                name=p_level.path,
-                shape=tuple(p_level.shape),
-                chunks=p_level.chunks,
-                shards=p_level.shards,
-                **array_static_kwargs,
-            )
+    return None