ngio 0.1.6__py3-none-any.whl → 0.2.0a1__py3-none-any.whl

ngio/{core/roi.py → common/_roi.py}

@@ -4,19 +4,18 @@ These are the interfaces bwteen the ROI tables / masking ROI tables and
     the ImageLikeHandler.
 """
 
-from typing import Any
-
 import numpy as np
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
-from ngio.core.dimensions import Dimensions
-from ngio.ngff_meta.fractal_image_meta import PixelSize, SpaceUnits
+from ngio.common._dimensions import Dimensions
+from ngio.ome_zarr_meta.ngio_specs import PixelSize, SpaceUnits
 
 
 def _to_raster(value: float, pixel_size: float, max_shape: int) -> int:
     """Convert to raster coordinates."""
     round_value = int(np.round(value / pixel_size))
-    return min(round_value, max_shape)
+    # Ensure the value is within the image shape boundaries
+    return max(0, min(round_value, max_shape))
 
 
 def _to_world(value: int, pixel_size: float) -> float:
@@ -27,6 +26,7 @@ def _to_world(value: int, pixel_size: float) -> float:
 class WorldCooROI(BaseModel):
     """Region of interest (ROI) metadata."""
 
+    name: str
     x_length: float
     y_length: float
     z_length: float = 1.0
@@ -34,7 +34,8 @@ class WorldCooROI(BaseModel):
     y: float = 0.0
     z: float = 0.0
     unit: SpaceUnits = Field(SpaceUnits.micrometer, repr=False)
-    infos: dict[str, Any] = Field(default_factory=dict, repr=False)
+
+    model_config = ConfigDict(extra="allow")
 
     def to_raster_coo(
         self, pixel_size: PixelSize, dimensions: Dimensions
@@ -42,51 +43,49 @@ class WorldCooROI(BaseModel):
         """Convert to raster coordinates."""
         dim_x = dimensions.get("x")
         dim_y = dimensions.get("y")
-        dim_z = dimensions.get("z", 1)
+        # Will default to 1 if z does not exist
+        dim_z = dimensions.get("z", strict=False)
 
         return RasterCooROI(
+            name=self.name,
             x=_to_raster(self.x, pixel_size.x, dim_x),
             y=_to_raster(self.y, pixel_size.y, dim_y),
             z=_to_raster(self.z, pixel_size.z, dim_z),
             x_length=_to_raster(self.x_length, pixel_size.x, dim_x),
             y_length=_to_raster(self.y_length, pixel_size.y, dim_y),
             z_length=_to_raster(self.z_length, pixel_size.z, dim_z),
-            original_roi=self,
         )
 
 
 class RasterCooROI(BaseModel):
     """Region of interest (ROI) metadata."""
 
+    name: str
     x: int
     y: int
     z: int
     x_length: int
     y_length: int
     z_length: int
-    original_roi: WorldCooROI = Field(..., repr=False)
+    model_config = ConfigDict(extra="allow")
 
     def to_world_coo_roi(self, pixel_size: PixelSize) -> WorldCooROI:
         """Convert to world coordinates."""
         return WorldCooROI(
+            name=self.name,
             x=_to_world(self.x, pixel_size.x),
             y=_to_world(self.y, pixel_size.y),
             z=_to_world(self.z, pixel_size.z),
             x_length=_to_world(self.x_length, pixel_size.x),
             y_length=_to_world(self.y_length, pixel_size.y),
             z_length=_to_world(self.z_length, pixel_size.z),
-            unit=pixel_size.unit,
-            infos=self.original_roi.infos,
+            unit=pixel_size.space_unit,
         )
 
-    def x_slice(self) -> slice:
-        """Return the slice for the x-axis."""
-        return slice(self.x, self.x + self.x_length)
-
-    def y_slice(self) -> slice:
-        """Return the slice for the y-axis."""
-        return slice(self.y, self.y + self.y_length)
-
-    def z_slice(self) -> slice:
-        """Return the slice for the z-axis."""
-        return slice(self.z, self.z + self.z_length)
+    def to_slices(self) -> dict[str, slice]:
+        """Return the slices for the ROI."""
+        return {
+            "x": slice(self.x, self.x + self.x_length),
+            "y": slice(self.y, self.y + self.y_length),
+            "z": slice(self.z, self.z + self.z_length),
+        }

ngio/common/_slicer.py

@@ -0,0 +1,97 @@
+# %%
+from collections.abc import Iterable
+
+import dask.array as da
+import numpy as np
+import zarr
+
+from ngio.common._dimensions import Dimensions
+from ngio.ome_zarr_meta.ngio_specs import AxesTransformation
+from ngio.utils import NgioValueError
+
+
+def _validate_int(value: int, shape: int) -> int:
+    if not isinstance(value, int):
+        raise NgioValueError(f"Invalid value {value} of type {type(value)}")
+    if value < 0 or value >= shape:
+        raise NgioValueError(
+            f"Invalid value {value}. Index out of bounds for axis of shape {shape}"
+        )
+    return value
+
+
+def _validate_iter_of_ints(value: Iterable[int], shape: int) -> list[int]:
+    if not isinstance(value, list):
+        raise NgioValueError(f"Invalid value {value} of type {type(value)}")
+    value = [_validate_int(v, shape=shape) for v in value]
+    return value
+
+
+def _validate_slice(value: slice, shape: int) -> slice:
+    start = value.start if value.start is not None else 0
+    start = max(start, 0)
+    stop = value.stop if value.stop is not None else shape
+    return slice(start, stop)
+
+
+class SliceTransform(AxesTransformation):
+    slices: tuple[slice | tuple[int, ...], ...]
+
+
+def compute_and_slices(
+    *,
+    dimensions: Dimensions,
+    **slice_kwargs: slice | int | Iterable[int],
+) -> SliceTransform:
+    _slices = {}
+    axes_names = dimensions._axes_mapper.on_disk_axes_names
+    for axis_name, slice_ in slice_kwargs.items():
+        axis = dimensions._axes_mapper.get_axis(axis_name)
+        if axis is None:
+            raise NgioValueError(
+                f"Invalid axis {axis_name}. "
+                f"Not found on the on-disk axes {axes_names}. "
+                "If you want to get/set a singletorn value include "
+                "it in the axes_order parameter."
+            )
+
+        shape = dimensions.get(axis.on_disk_name)
+
+        if isinstance(slice_, int):
+            slice_ = _validate_int(slice_, shape)
+            slice_ = slice(slice_, slice_ + 1)
+
+        elif isinstance(slice_, Iterable):
+            slice_ = _validate_iter_of_ints(slice_, shape)
+            slice_ = tuple(slice_)
+
+        elif isinstance(slice_, slice):
+            slice_ = _validate_slice(slice_, shape)
+
+        elif not isinstance(slice_, slice):
+            raise ValueError(
+                f"Invalid slice definition {slice_} of type {type(slice_)}"
+            )
+        _slices[axis.on_disk_name] = slice_
+
+    slices = tuple(_slices.get(axis, slice(None)) for axis in axes_names)
+    return SliceTransform(slices=slices)
+
+
+def numpy_get_slice(array: zarr.Array, slices: SliceTransform) -> np.ndarray:
+    return array[slices.slices]
+
+
+def dask_get_slice(array: zarr.Array, slices: SliceTransform) -> da.Array:
+    da_array = da.from_zarr(array)
+    return da_array[slices.slices]
+
+
+def numpy_set_slice(
+    array: zarr.Array, patch: np.ndarray, slices: SliceTransform
+) -> None:
+    array[slices.slices] = patch
+
+
+def dask_set_slice(array: zarr.Array, patch: da.Array, slices: SliceTransform) -> None:
+    da.to_zarr(arr=patch, url=array, region=slices.slices)

ngio/{pipes/_zoom_utils.py → common/_zoom.py}

@@ -3,7 +3,6 @@ from typing import Literal
 
 import dask.array as da
 import numpy as np
-import zarr
 from scipy.ndimage import zoom as scipy_zoom
 
 
@@ -76,7 +75,7 @@ def _zoom_inputs_check(
     return _scale, _target_shape
 
 
-def _dask_zoom(
+def dask_zoom(
     source_array: da.Array,
     scale: tuple[int, ...] | None = None,
     target_shape: tuple[int, ...] | None = None,
@@ -127,7 +126,7 @@ def _dask_zoom(
     return out_array
 
 
-def _numpy_zoom(
+def numpy_zoom(
     source_array: np.ndarray,
     scale: tuple[int, ...] | None = None,
     target_shape: tuple[int, ...] | None = None,
@@ -155,78 +154,3 @@ def _numpy_zoom(
     )
     assert isinstance(out_array, np.ndarray)
     return out_array
-
-
-def on_disk_zoom(
-    source: zarr.Array,
-    target: zarr.Array,
-    order: Literal[0, 1, 2] = 1,
-    mode: Literal["dask", "numpy"] = "dask",
-) -> None:
-    """Apply a zoom operation from a source zarr array to a target zarr array.
-
-    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.
-        mode (Literal["dask", "numpy"]): The mode to use. Defaults to "dask".
-    """
-    if not isinstance(source, zarr.Array):
-        raise ValueError("source must be a zarr array")
-
-    if not isinstance(target, zarr.Array):
-        raise ValueError("target must be a zarr array")
-
-    if source.dtype != target.dtype:
-        raise ValueError("source and target must have the same dtype")
-
-    assert mode in ["dask", "numpy"], "mode must be either 'dask' or 'numpy'"
-
-    if mode == "numpy":
-        target[...] = _numpy_zoom(source[...], target_shape=target.shape, order=order)
-        return None
-
-    source_array = da.from_zarr(source)
-    target_array = _dask_zoom(source_array, target_shape=target.shape, order=order)
-
-    target_array = target_array.rechunk(target.chunks)
-    target_array.compute_chunk_sizes()
-    target_array.to_zarr(target)
-
-
-def on_disk_coarsen(
-    source: zarr.Array,
-    target: zarr.Array,
-    aggregation_function: np.ufunc,
-) -> None:
-    """Apply a coarsening operation from a source zarr array to a target zarr array.
-
-    Args:
-        source (zarr.Array): The source array to coarsen.
-        target (zarr.Array): The target array to save the coarsened result to.
-        aggregation_function (np.ufunc): The aggregation function to use.
-    """
-    source_array = da.from_zarr(source)
-
-    _scale, _target_shape = _zoom_inputs_check(
-        source_array=source_array, scale=None, target_shape=target.shape
-    )
-
-    assert (
-        _target_shape == target.shape
-    ), "Target shape must match the target array shape"
-    coarsening_setup = {}
-    for i, s in enumerate(_scale):
-        factor = 1 / s
-        if factor.is_integer():
-            coarsening_setup[i] = int(factor)
-        else:
-            raise ValueError(
-                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
-    )
-    out_target = out_target.rechunk(target.chunks)
-    out_target.to_zarr(target)

ngio/hcs/__init__.py

@@ -0,0 +1,60 @@
+"""OME-Zarr HCS objects models."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ngio.images import OmeZarrContainer
+
+
+class OmeZarrPlate:
+    """Placeholder for the OME-Zarr image object."""
+
+    def __init__(self, *args, **kwargs):
+        """Initialize the OME-Zarr plate."""
+        raise NotImplementedError
+
+    def wells(self) -> list[str]:
+        """Return the wells."""
+        raise NotImplementedError
+
+    def columns(self) -> list[str]:
+        """Return the number of columns."""
+        raise NotImplementedError
+
+    def rows(self) -> list[str]:
+        """Return the number of rows."""
+        raise NotImplementedError
+
+    def get_omezarr_well(self, *args, **kwargs) -> "OmeZarrWell":
+        """Return the OME-Zarr well."""
+        raise NotImplementedError
+
+    def get_omezarr_image(self, *args, **kwargs) -> "OmeZarrContainer":
+        """Return the OME-Zarr image."""
+        raise NotImplementedError
+
+
+class OmeZarrWell:
+    """Placeholder for the Image object."""
+
+    def __init__(self, *args, **kwargs):
+        """Initialize the OME-Zarr well."""
+        raise NotImplementedError
+
+    def acquisitions(self) -> list[str]:
+        """Return the acquisition."""
+        raise NotImplementedError
+
+    def get_ome_zarr_image(self, *args, **kwargs) -> "OmeZarrContainer":
+        """Return the OME-Zarr image."""
+        raise NotImplementedError
+
+
+def open_omezarr_plate(*args, **kwargs):
+    """Open an OME-Zarr plate."""
+    return OmeZarrPlate(*args, **kwargs)
+
+
+def open_omezarr_well(*args, **kwargs):
+    """Open an OME-Zarr well."""
+    return OmeZarrWell(*args, **kwargs)

ngio/images/__init__.py

@@ -0,0 +1,23 @@
+"""OME-Zarr object models."""
+
+from ngio.images.image import Image, ImagesContainer
+from ngio.images.label import Label, LabelsContainer
+from ngio.images.omezarr_container import (
+    OmeZarrContainer,
+    create_empty_omezarr,
+    create_omezarr_from_array,
+    open_image,
+    open_omezarr_container,
+)
+
+__all__ = [
+    "Image",
+    "ImagesContainer",
+    "Label",
+    "LabelsContainer",
+    "OmeZarrContainer",
+    "create_empty_omezarr",
+    "create_omezarr_from_array",
+    "open_image",
+    "open_omezarr_container",
+]

ngio/images/abstract_image.py

@@ -0,0 +1,240 @@
+"""Generic class to handle Image-like data in a OME-NGFF file."""
+
+from collections.abc import Collection, Iterable
+from typing import Generic, Literal, TypeVar
+
+import zarr
+
+from ngio.common import (
+    ArrayLike,
+    Dimensions,
+    WorldCooROI,
+    consolidate_pyramid,
+    get_pipe,
+    set_pipe,
+)
+from ngio.ome_zarr_meta import (
+    Dataset,
+    ImageMetaHandler,
+    LabelMetaHandler,
+    PixelSize,
+)
+from ngio.utils import (
+    NgioFileExistsError,
+    ZarrGroupHandler,
+)
+
+_image_handler = TypeVar("_image_handler", ImageMetaHandler, LabelMetaHandler)
+
+
+class AbstractImage(Generic[_image_handler]):
+    """A class to handle a single image (or level) in an OME-Zarr image.
+
+    This class is meant to be subclassed by specific image types.
+    """
+
+    def __init__(
+        self,
+        group_handler: ZarrGroupHandler,
+        path: str,
+        meta_handler: _image_handler,
+    ) -> None:
+        """Initialize the Image at a single level.
+
+        Args:
+            group_handler: The Zarr group handler.
+            path: The path to the image in the omezarr file.
+            meta_handler: The image metadata handler.
+
+        """
+        self._path = path
+        self._group_handler = group_handler
+        self._meta_handler = meta_handler
+
+        self._dataset = self._meta_handler.meta.get_dataset(path=path)
+        self._pixel_size = self._dataset.pixel_size
+
+        try:
+            self._zarr_array = self._group_handler.get_array(self._dataset.path)
+        except NgioFileExistsError as e:
+            raise NgioFileExistsError(f"Could not find the dataset at {path}.") from e
+
+        self._dimensions = Dimensions(
+            shape=self._zarr_array.shape, axes_mapper=self._dataset.axes_mapper
+        )
+
+        self._axer_mapper = self._dataset.axes_mapper
+
+    def __repr__(self) -> str:
+        """Return a string representation of the image."""
+        return f"Image(path={self.path}, {self.dimensions})"
+
+    @property
+    def meta_handler(self) -> _image_handler:
+        """Return the metadata."""
+        return self._meta_handler
+
+    @property
+    def zarr_array(self) -> zarr.Array:
+        """Return the Zarr array."""
+        return self._zarr_array
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        """Return the shape of the image."""
+        return self.zarr_array.shape
+
+    @property
+    def dtype(self) -> str:
+        """Return the dtype of the image."""
+        return str(self.zarr_array.dtype)
+
+    @property
+    def chunks(self) -> tuple[int, ...]:
+        """Return the chunks of the image."""
+        return self.zarr_array.chunks
+
+    @property
+    def dimensions(self) -> Dimensions:
+        """Return the dimensions of the image."""
+        return self._dimensions
+
+    @property
+    def pixel_size(self) -> PixelSize:
+        """Return the pixel size of the image."""
+        return self._pixel_size
+
+    @property
+    def dataset(self) -> Dataset:
+        """Return the dataset of the image."""
+        return self._dataset
+
+    @property
+    def path(self) -> str:
+        """Return the path of the image."""
+        return self._dataset.path
+
+    def get_array(
+        self,
+        axes_order: Collection[str] | None = None,
+        mode: Literal["numpy", "dask", "delayed"] = "numpy",
+        **slice_kwargs: slice | int | Iterable[int],
+    ) -> ArrayLike:
+        """Get a slice of the image.
+
+        Args:
+            axes_order: The order of the axes to return the array.
+            mode: The mode to return the array.
+            **slice_kwargs: The slices to get the array.
+
+        Returns:
+            The array of the region of interest.
+        """
+        return get_pipe(
+            array=self.zarr_array,
+            dimensions=self.dimensions,
+            axes_order=axes_order,
+            mode=mode,
+            **slice_kwargs,
+        )
+
+    def get_roi(
+        self,
+        roi: WorldCooROI,
+        axes_order: Collection[str] | None = None,
+        mode: Literal["numpy", "dask", "delayed"] = "numpy",
+        **slice_kwargs: slice | int | Iterable[int],
+    ) -> ArrayLike:
+        """Get a slice of the image.
+
+        Args:
+            roi: The region of interest to get the array.
+            axes_order: The order of the axes to return the array.
+            mode: The mode to return the array.
+            **slice_kwargs: The slices to get the array.
+
+        Returns:
+            The array of the region of interest.
+        """
+        raster_roi = roi.to_raster_coo(
+            pixel_size=self.pixel_size, dimensions=self.dimensions
+        ).to_slices()
+
+        for key in slice_kwargs.keys():
+            if key in raster_roi:
+                raise ValueError(
+                    f"Key {key} is already in the slice_kwargs. "
+                    "Ambiguous which one to use: "
+                    f"{key}={slice_kwargs[key]} or roi_{key}={raster_roi[key]}"
+                )
+        return self.get_array(
+            axes_order=axes_order, mode=mode, **raster_roi, **slice_kwargs
+        )
+
+    def set_array(
+        self,
+        patch: ArrayLike,
+        axes_order: Collection[str] | None = None,
+        **slice_kwargs: slice | int | Iterable[int],
+    ) -> None:
+        """Set a slice of the image.
+
+        Args:
+            patch: The patch to set.
+            axes_order: The order of the axes to set the patch.
+            **slice_kwargs: The slices to set the patch.
+
+        """
+        set_pipe(
+            array=self.zarr_array,
+            patch=patch,
+            dimensions=self.dimensions,
+            axes_order=axes_order,
+            **slice_kwargs,
+        )
+
+    def set_roi(
+        self,
+        roi: WorldCooROI,
+        patch: ArrayLike,
+        axes_order: Collection[str] | None = None,
+        **slice_kwargs: slice | int | Iterable[int],
+    ) -> None:
+        """Set a slice of the image.
+
+        Args:
+            roi: The region of interest to set the patch.
+            patch: The patch to set.
+            axes_order: The order of the axes to set the patch.
+            **slice_kwargs: The slices to set the patch.
+
+        """
+        raster_roi = roi.to_raster_coo(
+            pixel_size=self.pixel_size, dimensions=self.dimensions
+        ).to_slices()
+
+        for key in slice_kwargs.keys():
+            if key in raster_roi:
+                raise ValueError(
+                    f"Key {key} is already in the slice_kwargs. "
+                    "Ambiguous which one to use: "
+                    f"{key}={slice_kwargs[key]} or roi_{key}={raster_roi[key]}"
+                )
+        self.set_array(patch=patch, axes_order=axes_order, **raster_roi, **slice_kwargs)
+
+
+def consolidate_image(
+    image: AbstractImage,
+    order: Literal[0, 1, 2] = 1,
+    mode: Literal["dask", "numpy", "coarsen"] = "dask",
+) -> None:
+    """Consolidate the image on disk."""
+    target_paths = image._meta_handler.meta.paths
+    targets = [
+        image._group_handler.get_array(path)
+        for path in target_paths
+        if path != image.path
+    ]
+    consolidate_pyramid(
+        source=image.zarr_array, targets=targets, order=order, mode=mode
+    )