ngio 0.4.0a3__py3-none-any.whl → 0.4.0a4__py3-none-any.whl

ngio/images/_abstract_image.py

@@ -8,24 +8,26 @@ import numpy as np
 import zarr
 
 from ngio.common import (
-    ArrayLike,
     Dimensions,
+    InterpolationOrder,
     Roi,
     RoiPixels,
+    consolidate_pyramid,
+)
+from ngio.io_pipes import (
+    DaskGetter,
+    DaskRoiGetter,
+    DaskRoiSetter,
+    DaskSetter,
+    NumpyGetter,
+    NumpyRoiGetter,
+    NumpyRoiSetter,
+    NumpySetter,
     SlicingInputType,
     TransformProtocol,
-    build_dask_getter,
-    build_dask_setter,
-    build_numpy_getter,
-    build_numpy_setter,
-    build_roi_dask_getter,
-    build_roi_dask_setter,
-    build_roi_numpy_getter,
-    build_roi_numpy_setter,
-    consolidate_pyramid,
 )
 from ngio.ome_zarr_meta import (
-    AxesMapper,
+    AxesHandler,
     Dataset,
     ImageMetaHandler,
     LabelMetaHandler,
@@ -61,29 +63,50 @@ class AbstractImage(Generic[_image_handler]):
         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)
+            self._zarr_array = self._group_handler.get_array(self._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._axes_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 path(self) -> str:
+        """Return the path of the image."""
+        return self._path
+
     @property
     def meta_handler(self) -> _image_handler:
         """Return the metadata."""
         return self._meta_handler
 
+    @property
+    def dataset(self) -> Dataset:
+        """Return the dataset of the image."""
+        return self.meta_handler.meta.get_dataset(path=self.path)
+
+    @property
+    def dimensions(self) -> Dimensions:
+        """Return the dimensions of the image."""
+        return Dimensions(shape=self.zarr_array.shape, dataset=self.dataset)
+
+    @property
+    def pixel_size(self) -> PixelSize:
+        """Return the pixel size of the image."""
+        return self.dataset.pixel_size
+
+    @property
+    def axes_handler(self) -> AxesHandler:
+        """Return the axes handler of the image."""
+        return self.dataset.axes_handler
+
+    @property
+    def axes(self) -> tuple[str, ...]:
+        """Return the axes of the image."""
+        return self.dimensions.axes
+
     @property
     def zarr_array(self) -> zarr.Array:
         """Return the Zarr array."""
@@ -104,16 +127,6 @@ class AbstractImage(Generic[_image_handler]):
         """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 axes_mapper(self) -> AxesMapper:
-        """Return the axes mapper of the image."""
-        return self._axes_mapper
-
     @property
     def is_3d(self) -> bool:
         """Return True if the image is 3D."""
@@ -147,31 +160,15 @@ class AbstractImage(Generic[_image_handler]):
     @property
     def space_unit(self) -> str | None:
         """Return the space unit of the image."""
-        return self.meta_handler.meta.space_unit
+        return self.axes_handler.space_unit
 
     @property
     def time_unit(self) -> str | None:
         """Return the time unit of the image."""
-        return self.meta_handler.meta.time_unit
-
-    @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
+        return self.axes_handler.time_unit
 
     def has_axis(self, axis: str) -> bool:
         """Return True if the image has the given axis."""
-        self.axes_mapper.get_index("x")
         return self.dimensions.has_axis(axis)
 
     def _get_as_numpy(
@@ -190,7 +187,7 @@ class AbstractImage(Generic[_image_handler]):
         Returns:
             The array of the region of interest.
         """
-        numpy_getter = build_numpy_getter(
+        numpy_getter = NumpyGetter(
             zarr_array=self.zarr_array,
             dimensions=self.dimensions,
             axes_order=axes_order,
@@ -217,11 +214,10 @@ class AbstractImage(Generic[_image_handler]):
         Returns:
             The array of the region of interest.
         """
-        numpy_roi_getter = build_roi_numpy_getter(
+        numpy_roi_getter = NumpyRoiGetter(
             zarr_array=self.zarr_array,
             dimensions=self.dimensions,
             roi=roi,
-            pixel_size=self.pixel_size,
             axes_order=axes_order,
             transforms=transforms,
             slicing_dict=slicing_kwargs,
@@ -241,7 +237,7 @@ class AbstractImage(Generic[_image_handler]):
             transforms: The transforms to apply to the array.
             **slicing_kwargs: The slices to get the array.
         """
-        dask_getter = build_dask_getter(
+        dask_getter = DaskGetter(
             zarr_array=self.zarr_array,
             dimensions=self.dimensions,
             axes_order=axes_order,
@@ -265,11 +261,10 @@ class AbstractImage(Generic[_image_handler]):
             transforms: The transforms to apply to the array.
             **slicing_kwargs: The slices to get the array.
         """
-        roi_dask_getter = build_roi_dask_getter(
+        roi_dask_getter = DaskRoiGetter(
             zarr_array=self.zarr_array,
             dimensions=self.dimensions,
             roi=roi,
-            pixel_size=self.pixel_size,
             axes_order=axes_order,
             transforms=transforms,
             slicing_dict=slicing_kwargs,
@@ -282,7 +277,7 @@ class AbstractImage(Generic[_image_handler]):
         transforms: Sequence[TransformProtocol] | None = None,
         mode: Literal["numpy", "dask"] = "numpy",
         **slicing_kwargs: SlicingInputType,
-    ) -> ArrayLike:
+    ) -> np.ndarray | da.Array:
         """Get a slice of the image.
 
         Args:
@@ -305,7 +300,7 @@ class AbstractImage(Generic[_image_handler]):
             )
         else:
             raise ValueError(
-                f"Unknown mode: {mode}. Choose from 'numpy', 'dask', or 'delayed'."
+                f"Unsupported mode: {mode}. Supported modes are: numpy, dask."
             )
 
     def _get_roi(
@@ -315,7 +310,7 @@ class AbstractImage(Generic[_image_handler]):
         transforms: Sequence[TransformProtocol] | None = None,
         mode: Literal["numpy", "dask"] = "numpy",
         **slice_kwargs: SlicingInputType,
-    ) -> ArrayLike:
+    ) -> np.ndarray | da.Array:
         """Get a slice of the image.
 
         Args:
@@ -339,12 +334,12 @@ class AbstractImage(Generic[_image_handler]):
             )
         else:
             raise ValueError(
-                f"Unknown mode: {mode}. Choose from 'numpy', 'dask', or 'delayed'."
+                f"Unsupported mode: {mode}. Supported modes are: numpy, dask."
             )
 
     def _set_array(
         self,
-        patch: ArrayLike,
+        patch: np.ndarray | da.Array,
         axes_order: Sequence[str] | None = None,
         transforms: Sequence[TransformProtocol] | None = None,
         **slicing_kwargs: SlicingInputType,
@@ -359,7 +354,7 @@ class AbstractImage(Generic[_image_handler]):
 
         """
         if isinstance(patch, np.ndarray):
-            numpy_setter = build_numpy_setter(
+            numpy_setter = NumpySetter(
                 zarr_array=self.zarr_array,
                 dimensions=self.dimensions,
                 axes_order=axes_order,
@@ -369,7 +364,7 @@ class AbstractImage(Generic[_image_handler]):
             numpy_setter(patch)
 
         elif isinstance(patch, da.Array):
-            dask_setter = build_dask_setter(
+            dask_setter = DaskSetter(
                 zarr_array=self.zarr_array,
                 dimensions=self.dimensions,
                 axes_order=axes_order,
@@ -387,7 +382,7 @@ class AbstractImage(Generic[_image_handler]):
     def _set_roi(
         self,
         roi: Roi | RoiPixels,
-        patch: ArrayLike,
+        patch: np.ndarray | da.Array,
         axes_order: Sequence[str] | None = None,
         transforms: Sequence[TransformProtocol] | None = None,
         **slicing_kwargs: SlicingInputType,
@@ -403,11 +398,10 @@ class AbstractImage(Generic[_image_handler]):
 
         """
         if isinstance(patch, np.ndarray):
-            roi_numpy_setter = build_roi_numpy_setter(
+            roi_numpy_setter = NumpyRoiSetter(
                 zarr_array=self.zarr_array,
                 dimensions=self.dimensions,
                 roi=roi,
-                pixel_size=self.pixel_size,
                 axes_order=axes_order,
                 transforms=transforms,
                 slicing_dict=slicing_kwargs,
@@ -415,11 +409,10 @@ class AbstractImage(Generic[_image_handler]):
             roi_numpy_setter(patch)
 
         elif isinstance(patch, da.Array):
-            roi_dask_setter = build_roi_dask_setter(
+            roi_dask_setter = DaskRoiSetter(
                 zarr_array=self.zarr_array,
                 dimensions=self.dimensions,
                 roi=roi,
-                pixel_size=self.pixel_size,
                 axes_order=axes_order,
                 transforms=transforms,
                 slicing_dict=slicing_kwargs,
@@ -434,7 +427,7 @@ class AbstractImage(Generic[_image_handler]):
 
     def _consolidate(
         self,
-        order: Literal[0, 1, 2] = 1,
+        order: InterpolationOrder = "linear",
         mode: Literal["dask", "numpy", "coarsen"] = "dask",
     ) -> None:
         """Consolidate the image on disk.
@@ -445,14 +438,86 @@ class AbstractImage(Generic[_image_handler]):
         """
         consolidate_image(image=self, order=order, mode=mode)
 
+    def roi(self, name: str | None = "image") -> Roi:
+        """Return the ROI covering the entire image."""
+        dim_x = self.dimensions.get("x")
+        dim_y = self.dimensions.get("y")
+        assert dim_x is not None and dim_y is not None
+        dim_z = self.dimensions.get("z")
+        z = None if dim_z is None else 0
+        dim_t = self.dimensions.get("t")
+        t = None if dim_t is None else 0
+        roi_px = RoiPixels(
+            name=name,
+            x=0,
+            y=0,
+            z=z,
+            t=t,
+            x_length=dim_x,
+            y_length=dim_y,
+            z_length=dim_z,
+            t_length=dim_t,
+        )
+        return roi_px.to_roi(pixel_size=self.pixel_size)
+
     def build_image_roi_table(self, name: str | None = "image") -> RoiTable:
         """Build the ROI table for an image."""
-        return build_image_roi_table(image=self, name=name)
+        return RoiTable(rois=[self.roi(name=name)])
+
+    def require_dimensions_match(
+        self,
+        other: "AbstractImage",
+        allow_singleton: bool = False,
+    ) -> None:
+        """Assert that two images have matching spatial dimensions.
+
+        Args:
+            other: The other image to compare to.
+            allow_singleton: If True, allow singleton dimensions to be
+                compatible with non-singleton dimensions.
+
+        Raises:
+            NgioValueError: If the images do not have compatible dimensions.
+        """
+        self.dimensions.require_dimensions_match(
+            other.dimensions, allow_singleton=allow_singleton
+        )
+
+    def require_axes_match(
+        self,
+        other: "AbstractImage",
+    ) -> None:
+        """Assert that two images have compatible axes.
+
+        Args:
+            other: The other image to compare to.
+
+        Raises:
+            NgioValueError: If the images do not have compatible axes.
+        """
+        self.dimensions.require_axes_match(other.dimensions)
+
+    def require_can_be_rescaled(
+        self,
+        other: "AbstractImage",
+    ) -> None:
+        """Assert that two images can be rescaled to each other.
+
+        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: The other image to compare to.
+
+        Raises:
+            NgioValueError: If the images cannot be scaled to each other.
+        """
+        self.dimensions.require_can_be_rescaled(other.dimensions)
 
 
 def consolidate_image(
     image: AbstractImage,
-    order: Literal[0, 1, 2] = 1,
+    order: InterpolationOrder = "linear",
     mode: Literal["dask", "numpy", "coarsen"] = "dask",
 ) -> None:
     """Consolidate the image on disk."""
@@ -465,26 +530,3 @@ def consolidate_image(
     consolidate_pyramid(
         source=image.zarr_array, targets=targets, order=order, mode=mode
     )
-
-
-def build_image_roi_table(image: AbstractImage, name: str | None = "image") -> RoiTable:
-    """Build the ROI table for an image."""
-    dim_x = image.dimensions.get("x")
-    dim_y = image.dimensions.get("y")
-    assert dim_x is not None and dim_y is not None
-    dim_z = image.dimensions.get("z")
-    z = None if dim_z is None else 0
-    dim_t = image.dimensions.get("t")
-    t = None if dim_t is None else 0
-    image_roi = RoiPixels(
-        name=name,
-        x=0,
-        y=0,
-        z=z,
-        t=t,
-        x_length=dim_x,
-        y_length=dim_y,
-        z_length=dim_z,
-        t_length=dim_t,
-    )
-    return RoiTable(rois=[image_roi.to_roi(pixel_size=image.pixel_size)])

ngio/images/_create.py

@@ -3,6 +3,8 @@
 from collections.abc import Sequence
 from typing import TypeVar
 
+from zarr.types import DIMENSION_SEPARATOR
+
 from ngio.common._pyramid import init_empty_pyramid
 from ngio.ome_zarr_meta import (
     NgioImageMeta,
@@ -93,6 +95,8 @@ def create_empty_label_container(
     name: str | None = None,
     chunks: Sequence[int] | None = None,
     dtype: str = "uint32",
+    dimension_separator: DIMENSION_SEPARATOR = "/",
+    compressor="default",
     overwrite: bool = False,
     version: NgffVersions = DefaultNgffVersion,
 ) -> ZarrGroupHandler:
@@ -120,6 +124,9 @@ def create_empty_label_container(
         name (str | None, optional): The name of the image. Defaults to None.
         chunks (Sequence[int] | None, optional): The chunk shape. If None the shape
             is used. Defaults to None.
+        dimension_separator (DIMENSION_SEPARATOR): The separator to use for
+            dimensions. Defaults to "/".
+        compressor: The compressor to use. Defaults to "default".
         dtype (str, optional): The data type of the image. Defaults to "uint16".
         overwrite (bool, optional): Whether to overwrite an existing image.
             Defaults to True.
@@ -164,6 +171,8 @@ def create_empty_label_container(
         chunks=chunks,
         dtype=dtype,
         mode="a",
+        dimension_separator=dimension_separator,
+        compressor=compressor,
     )
     group_handler._mode = "r+"
     return group_handler
@@ -184,6 +193,8 @@ def create_empty_image_container(
     name: str | None = None,
     chunks: Sequence[int] | None = None,
     dtype: str = "uint16",
+    dimension_separator: DIMENSION_SEPARATOR = "/",
+    compressor="default",
     overwrite: bool = False,
     version: NgffVersions = DefaultNgffVersion,
 ) -> ZarrGroupHandler:
@@ -212,6 +223,9 @@ def create_empty_image_container(
         chunks (Sequence[int] | None, optional): The chunk shape. If None the shape
             is used. Defaults to None.
         dtype (str, optional): The data type of the image. Defaults to "uint16".
+        dimension_separator (DIMENSION_SEPARATOR): The separator to use for
+            dimensions. Defaults to "/".
+        compressor: The compressor to use. Defaults to "default".
         overwrite (bool, optional): Whether to overwrite an existing image.
             Defaults to True.
         version (str, optional): The version of the OME-Zarr specification.
@@ -254,6 +268,8 @@ def create_empty_image_container(
         chunks=chunks,
         dtype=dtype,
         mode="a",
+        dimension_separator=dimension_separator,
+        compressor=compressor,
     )
 
     group_handler._mode = "r+"

ngio/images/_create_synt_container.py

@@ -4,6 +4,7 @@ from collections.abc import Sequence
 
 import numpy as np
 import PIL.Image
+from zarr.types import DIMENSION_SEPARATOR
 
 from ngio.common._synt_images_utils import fit_to_shape
 from ngio.images._ome_zarr_container import OmeZarrContainer, create_ome_zarr_from_array
@@ -35,6 +36,8 @@ def create_synthetic_ome_zarr(
     channel_colors: Sequence[str] | None = None,
     channel_active: Sequence[bool] | None = None,
     table_backend: TableBackend = DefaultTableBackend,
+    dimension_separator: DIMENSION_SEPARATOR = "/",
+    compressor="default",
     overwrite: bool = False,
     version: NgffVersions = DefaultNgffVersion,
 ) -> OmeZarrContainer:
@@ -63,6 +66,9 @@ def create_synthetic_ome_zarr(
         channel_active (Sequence[bool] | None, optional): Whether the channels are
             active. Defaults to None.
         table_backend (TableBackend): Table backend to be used to store tables
+        dimension_separator (DIMENSION_SEPARATOR): The separator to use for
+            dimensions. Defaults to "/".
+        compressor: The compressor to use. Defaults to "default".
         overwrite (bool, optional): Whether to overwrite an existing image.
             Defaults to True.
         version (NgffVersion, optional): The version of the OME-Zarr specification.
@@ -96,6 +102,8 @@ def create_synthetic_ome_zarr(
         name=sample_info.name,
         chunks=chunks,
         overwrite=overwrite,
+        dimension_separator=dimension_separator,
+        compressor=compressor,
         version=version,
     )
 
@@ -108,6 +116,8 @@ def create_synthetic_ome_zarr(
         label = ome_zarr.get_label(name=label_info.name)
 
         ref_label = np.asarray(PIL.Image.open(label_info.label_path))
+        ref_label = ref_label.astype(label_info.dtype)
+
         ref_label = fit_to_shape(
             arr=ref_label,
             out_shape=label.shape,

ngio/images/_image.py

@@ -6,17 +6,20 @@ from typing import Literal
 import dask.array as da
 import numpy as np
 from pydantic import BaseModel, model_validator
+from zarr.types import DIMENSION_SEPARATOR
 
 from ngio.common import (
-    ArrayLike,
     Dimensions,
+    InterpolationOrder,
     Roi,
     RoiPixels,
-    SlicingInputType,
-    TransformProtocol,
 )
 from ngio.images._abstract_image import AbstractImage
 from ngio.images._create import create_empty_image_container
+from ngio.io_pipes import (
+    SlicingInputType,
+    TransformProtocol,
+)
 from ngio.ome_zarr_meta import (
     ImageMetaHandler,
     NgioImageMeta,
@@ -269,7 +272,7 @@ class Image(AbstractImage[ImageMetaHandler]):
         transforms: Sequence[TransformProtocol] | None = None,
         mode: Literal["numpy", "dask"] = "numpy",
         **slicing_kwargs: SlicingInputType,
-    ) -> ArrayLike:
+    ) -> np.ndarray | da.Array:
         """Get the image as a zarr array.
 
         Args:
@@ -299,7 +302,7 @@ class Image(AbstractImage[ImageMetaHandler]):
         transforms: Sequence[TransformProtocol] | None = None,
         mode: Literal["numpy", "dask"] = "numpy",
         **slicing_kwargs: SlicingInputType,
-    ) -> ArrayLike:
+    ) -> np.ndarray | da.Array:
         """Get the image as a zarr array for a region of interest.
 
         Args:
@@ -328,7 +331,7 @@ class Image(AbstractImage[ImageMetaHandler]):
 
     def set_array(
         self,
-        patch: ArrayLike,
+        patch: np.ndarray | da.Array,
         channel_selection: ChannelSlicingInputType = None,
         axes_order: Sequence[str] | None = None,
         transforms: Sequence[TransformProtocol] | None = None,
@@ -354,7 +357,7 @@ class Image(AbstractImage[ImageMetaHandler]):
     def set_roi(
         self,
         roi: Roi | RoiPixels,
-        patch: ArrayLike,
+        patch: np.ndarray | da.Array,
         channel_selection: ChannelSlicingInputType = None,
         axes_order: Sequence[str] | None = None,
         transforms: Sequence[TransformProtocol] | None = None,
@@ -383,7 +386,7 @@ class Image(AbstractImage[ImageMetaHandler]):
 
     def consolidate(
         self,
-        order: Literal[0, 1, 2] = 1,
+        order: InterpolationOrder = "linear",
         mode: Literal["dask", "numpy", "coarsen"] = "dask",
     ) -> None:
         """Consolidate the label on disk."""
@@ -601,6 +604,8 @@ class ImagesContainer:
         name: str | None = None,
         chunks: Sequence[int] | None = None,
         dtype: str | None = None,
+        dimension_separator: DIMENSION_SEPARATOR | None = None,
+        compressor: str | None = None,
         overwrite: bool = False,
     ) -> "ImagesContainer":
         """Create an empty OME-Zarr image from an existing image.
@@ -615,6 +620,10 @@ class ImagesContainer:
             axes_names (Sequence[str] | None): The axes names of the new image.
             name (str | None): The name of the new image.
             chunks (Sequence[int] | None): The chunk shape of the new image.
+            dimension_separator (DIMENSION_SEPARATOR | None): The separator to use for
+                dimensions. If None it will use the same as the reference image.
+            compressor (str | None): The compressor to use. If None it will use
+                the same as the reference image.
             dtype (str | None): The data type of the new image.
             overwrite (bool): Whether to overwrite an existing image.
 
@@ -714,6 +723,8 @@ def derive_image_container(
     name: str | None = None,
     chunks: Sequence[int] | None = None,
     dtype: str | None = None,
+    dimension_separator: DIMENSION_SEPARATOR | None = None,
+    compressor=None,
     overwrite: bool = False,
 ) -> ImagesContainer:
     """Create an empty OME-Zarr image from an existing image.
@@ -728,6 +739,10 @@ def derive_image_container(
         axes_names (Sequence[str] | None): The axes names of the new image.
         name (str | None): The name of the new image.
         chunks (Sequence[int] | None): The chunk shape of the new image.
+        dimension_separator (DIMENSION_SEPARATOR | None): The separator to use for
+            dimensions. If None it will use the same as the reference image.
+        compressor: The compressor to use. If None it will use
+            the same as the reference image.
         dtype (str | None): The data type of the new image.
         overwrite (bool): Whether to overwrite an existing image.
 
@@ -749,7 +764,7 @@ def derive_image_container(
         pixel_size = ref_image.pixel_size
 
     if axes_names is None:
-        axes_names = ref_meta.axes_mapper.axes_names
+        axes_names = ref_meta.axes_handler.axes_names
 
     if len(axes_names) != len(shape):
         raise NgioValidationError(
@@ -771,6 +786,13 @@ def derive_image_container(
 
     if dtype is None:
         dtype = ref_image.dtype
+
+    if dimension_separator is None:
+        dimension_separator = ref_image.zarr_array._dimension_separator  # type: ignore
+
+    if compressor is None:
+        compressor = ref_image.zarr_array.compressor  # type: ignore
+
     handler = create_empty_image_container(
         store=store,
         shape=shape,
@@ -786,6 +808,8 @@ def derive_image_container(
         name=name,
         chunks=chunks,
         dtype=dtype,
+        dimension_separator=dimension_separator,  # type: ignore
+        compressor=compressor,  # type: ignore
         overwrite=overwrite,
         version=ref_meta.version,
     )