ngio 0.5.0b6__py3-none-any.whl → 0.5.1__py3-none-any.whl

ngio/images/_abstract_image.py

@@ -1,6 +1,6 @@
 """Generic class to handle Image-like data in a OME-NGFF file."""
 
-import warnings
+import logging
 from abc import ABC, abstractmethod
 from collections.abc import Mapping, Sequence
 from typing import Any, Literal
@@ -16,9 +16,15 @@ from ngio.common import (
     Roi,
     consolidate_pyramid,
 )
-from ngio.common._pyramid import ChunksLike, ShardsLike, shapes_from_scaling_factors
+from ngio.common._pyramid import (
+    ChunksLike,
+    ShardsLike,
+    compute_scales_from_shapes,
+    compute_shapes_from_scaling_factors,
+)
 from ngio.images._create_utils import (
     _image_or_label_meta,
+    compute_base_scale,
     init_image_like_from_shapes,
 )
 from ngio.io_pipes import (
@@ -46,6 +52,13 @@ from ngio.ome_zarr_meta.ngio_specs import (
     NgffVersions,
     NgioLabelMeta,
 )
+from ngio.ome_zarr_meta.ngio_specs._axes import (
+    AxesSetup,
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
+    SpaceUnits,
+    TimeUnits,
+)
 from ngio.tables import RoiTable
 from ngio.utils import (
     NgioFileExistsError,
@@ -55,6 +68,8 @@ from ngio.utils import (
 )
 from ngio.utils._zarr_utils import find_dimension_separator
 
+logger = logging.getLogger(f"ngio:{__name__}")
+
 
 class AbstractImage(ABC):
     """A class to handle a single image (or level) in an OME-Zarr image.
@@ -130,6 +145,11 @@ class AbstractImage(ABC):
         """Return the axes handler of the image."""
         return self.dataset.axes_handler
 
+    @property
+    def axes_setup(self) -> AxesSetup:
+        """Return the axes setup of the image."""
+        return self.axes_handler.axes_setup
+
     @property
     def axes(self) -> tuple[str, ...]:
         """Return the axes of the image."""
@@ -199,6 +219,47 @@ class AbstractImage(ABC):
         """Return True if the image has the given axis."""
         return self.axes_handler.has_axis(axis)
 
+    def set_axes_unit(
+        self,
+        space_unit: SpaceUnits = DefaultSpaceUnit,
+        time_unit: TimeUnits = DefaultTimeUnit,
+    ) -> None:
+        """Set the axes unit of the image.
+
+        Args:
+            space_unit (SpaceUnits): The space unit of the image.
+            time_unit (TimeUnits): The time unit of the image.
+        """
+        meta = self._meta_handler.get_meta()
+        meta = meta.to_units(space_unit=space_unit, time_unit=time_unit)
+        self._meta_handler.update_meta(meta)  # type: ignore
+
+    def set_axes_names(self, axes_names: Sequence[str]) -> None:
+        """Set the axes names of the label.
+
+        Args:
+            axes_names (Sequence[str]): The axes names to set.
+        """
+        meta = self._meta_handler.get_meta()
+        meta = meta.rename_axes(axes_names=axes_names)
+        self._meta_handler._axes_setup = meta.axes_handler.axes_setup
+        self._meta_handler.update_meta(meta)  # type: ignore
+
+    def set_name(
+        self,
+        name: str,
+    ) -> None:
+        """Set the name of the image in the metadata.
+
+        This does not change the group name or any paths.
+
+        Args:
+            name (str): The name of the image.
+        """
+        meta = self._meta_handler.get_meta()
+        meta = meta.rename_image(name=name)
+        self._meta_handler.update_meta(meta)  # type: ignore
+
     def _get_as_numpy(
         self,
         axes_order: Sequence[str] | None = None,
@@ -602,32 +663,39 @@ def consolidate_image(
 
 def _shapes_from_ref_image(
     ref_image: AbstractImage,
-) -> list[tuple[int, ...]]:
+) -> tuple[list[tuple[int, ...]], list[tuple[float, ...]]]:
     """Rebuild base shape based on a new shape."""
-    paths = ref_image.meta.paths
+    meta = ref_image.meta
+    paths = meta.paths
     index_path = paths.index(ref_image.path)
     sub_paths = paths[index_path:]
     group_handler = ref_image._group_handler
-    shapes = []
+    shapes, scales = [], []
     for path in sub_paths:
         zarr_array = group_handler.get_array(path)
         shapes.append(zarr_array.shape)
+        scales.append(meta.get_dataset(path=path).scale)
     if len(shapes) == len(paths):
-        return shapes
+        return shapes, scales
     missing_levels = len(paths) - len(shapes)
-    extended_shapes = shapes_from_scaling_factors(
+    extended_shapes = compute_shapes_from_scaling_factors(
         base_shape=shapes[-1],
         scaling_factors=ref_image.meta.scaling_factor(),
         num_levels=missing_levels + 1,
     )
     shapes.extend(extended_shapes[1:])
-    return shapes
+    extended_scales = compute_scales_from_shapes(
+        shapes=extended_shapes,
+        base_scale=scales[-1],
+    )
+    scales.extend(extended_scales[1:])
+    return shapes, scales
 
 
 def _shapes_from_new_shape(
     ref_image: AbstractImage,
     shape: Sequence[int],
-) -> list[tuple[int, ...]]:
+) -> tuple[list[tuple[int, ...]], list[tuple[float, ...]]]:
     """Rebuild pyramid shapes based on a new base shape."""
     if len(shape) != len(ref_image.shape):
         raise NgioValueError(
@@ -637,27 +705,33 @@ def _shapes_from_new_shape(
     base_shape = tuple(shape)
     scaling_factors = ref_image.meta.scaling_factor()
     num_levels = len(ref_image.meta.paths)
-    return shapes_from_scaling_factors(
+    shapes = compute_shapes_from_scaling_factors(
         base_shape=base_shape,
         scaling_factors=scaling_factors,
         num_levels=num_levels,
     )
+    scales = compute_scales_from_shapes(
+        shapes=shapes,
+        base_scale=ref_image.dataset.scale,
+    )
+    return shapes, scales
 
 
 def _compute_pyramid_shapes(
     ref_image: AbstractImage,
     shape: Sequence[int] | None,
-) -> list[tuple[int, ...]]:
+) -> tuple[list[tuple[int, ...]], list[tuple[float, ...]]]:
     """Rebuild pyramid shapes based on a new base shape."""
     if shape is None:
         return _shapes_from_ref_image(ref_image=ref_image)
     return _shapes_from_new_shape(ref_image=ref_image, shape=shape)
 
 
-def _check_chunks_and_shards_compatibility(
+def _check_len_compatibility(
     ref_shape: tuple[int, ...],
     chunks: ChunksLike,
     shards: ShardsLike | None,
+    translation: Sequence[float] | None = None,
 ) -> None:
     """Check if the chunks and shards are compatible with the reference shape.
 
@@ -665,6 +739,7 @@ def _check_chunks_and_shards_compatibility(
         ref_shape: The reference shape.
         chunks: The chunks to check.
         shards: The shards to check.
+        translation: The translation to check.
     """
     if chunks != "auto":
         if len(chunks) != len(ref_shape):
@@ -676,6 +751,12 @@ def _check_chunks_and_shards_compatibility(
             raise NgioValueError(
                 "The length of the shards must be the same as the number of dimensions."
             )
+    if translation is not None:
+        if len(translation) != len(ref_shape):
+            raise NgioValueError(
+                "The length of the translation must be the same as the number of "
+                "dimensions."
+            )
 
 
 def _apply_channel_policy(
@@ -685,7 +766,16 @@ def _apply_channel_policy(
     axes: tuple[str, ...],
     chunks: ChunksLike,
     shards: ShardsLike | None,
-) -> tuple[list[tuple[int, ...]], tuple[str, ...], ChunksLike, ShardsLike | None]:
+    translation: Sequence[float],
+    scales: list[tuple[float, ...]] | tuple[float, ...],
+) -> tuple[
+    list[tuple[int, ...]],
+    tuple[str, ...],
+    ChunksLike,
+    ShardsLike | None,
+    tuple[float, ...],
+    list[tuple[float, ...]] | tuple[float, ...],
+]:
     """Apply the channel policy to the shapes and axes.
 
     Args:
@@ -695,12 +785,15 @@ def _apply_channel_policy(
         axes: The axes of the image.
         chunks: The chunks of the image.
         shards: The shards of the image.
+        translation: The translation of the image.
+        scales: The scales of the image.
 
     Returns:
         The new shapes and axes after applying the channel policy.
     """
+    translation = tuple(translation)
     if channels_policy == "same":
-        return shapes, axes, chunks, shards
+        return shapes, axes, chunks, shards, translation, scales
 
     if channels_policy == "singleton":
         # Treat 'singleton' as setting channel size to 1
@@ -709,7 +802,7 @@ def _apply_channel_policy(
     channel_index = ref_image.axes_handler.get_index("c")
     if channel_index is None:
         if channels_policy == "squeeze":
-            return shapes, axes, chunks, shards
+            return shapes, axes, chunks, shards, translation, scales
         raise NgioValueError(
             f"Cannot apply channel policy {channels_policy=} to an image "
             "without channels axis."
@@ -719,6 +812,15 @@ def _apply_channel_policy(
         for shape in shapes:
             new_shape = shape[:channel_index] + shape[channel_index + 1 :]
             new_shapes.append(new_shape)
+
+        if isinstance(scales, tuple):
+            new_scales = scales[:channel_index] + scales[channel_index + 1 :]
+        else:
+            new_scales = []
+            for scale in scales:
+                new_scale = scale[:channel_index] + scale[channel_index + 1 :]
+                new_scales.append(new_scale)
+
         new_axes = axes[:channel_index] + axes[channel_index + 1 :]
         if chunks == "auto":
             new_chunks: ChunksLike = "auto"
@@ -728,7 +830,9 @@ def _apply_channel_policy(
             new_shards: ShardsLike | None = shards
         else:
             new_shards = shards[:channel_index] + shards[channel_index + 1 :]
-        return new_shapes, new_axes, new_chunks, new_shards
+
+        translation = translation[:channel_index] + translation[channel_index + 1 :]
+        return new_shapes, new_axes, new_chunks, new_shards, translation, new_scales
     elif isinstance(channels_policy, int):
         new_shapes = []
         for shape in shapes:
@@ -738,7 +842,7 @@ def _apply_channel_policy(
                 *shape[channel_index + 1 :],
             )
             new_shapes.append(new_shape)
-        return new_shapes, axes, chunks, shards
+        return new_shapes, axes, chunks, shards, translation, scales
     else:
         raise NgioValueError(
             f"Invalid channels policy: {channels_policy}. "
@@ -783,6 +887,35 @@ def _check_channels_meta_compatibility(
     return channels_meta_
 
 
+def adapt_scales(
+    scales: list[tuple[float, ...]],
+    pixelsize: float | tuple[float, float] | None,
+    z_spacing: float | None,
+    time_spacing: float | None,
+    ref_image: AbstractImage,
+) -> list[tuple[float, ...]] | tuple[float, ...]:
+    if pixelsize is None and z_spacing is None and time_spacing is None:
+        return scales
+    pixel_size = ref_image.pixel_size
+    if pixelsize is None:
+        pixelsize = (pixel_size.y, pixel_size.x)
+    if z_spacing is None:
+        z_spacing = pixel_size.z
+    else:
+        z_spacing = z_spacing
+    if time_spacing is None:
+        time_spacing = pixel_size.t
+    else:
+        time_spacing = time_spacing
+    base_scale = compute_base_scale(
+        pixelsize=pixelsize,
+        z_spacing=z_spacing,
+        time_spacing=time_spacing,
+        axes_handler=ref_image.axes_handler,
+    )
+    return base_scale
+
+
 def abstract_derive(
     *,
     ref_image: AbstractImage,
@@ -795,6 +928,7 @@ def abstract_derive(
     z_spacing: float | None = None,
     time_spacing: float | None = None,
     name: str | None = None,
+    translation: Sequence[float] | None = None,
     channels_policy: Literal["squeeze", "same", "singleton"] | int = "same",
     channels_meta: Sequence[str | Channel] | None = None,
     ngff_version: NgffVersions | None = None,
@@ -808,7 +942,7 @@ def abstract_derive(
     # Deprecated arguments
     labels: Sequence[str] | None = None,
     pixel_size: PixelSize | None = None,
-) -> ZarrGroupHandler:
+) -> tuple[ZarrGroupHandler, AxesSetup]:
     """Create an empty OME-Zarr image from an existing image.
 
     If a kwarg is not provided, the value from the reference image will be used.
@@ -823,6 +957,8 @@ def abstract_derive(
         z_spacing (float | None): The z spacing of the new image.
         time_spacing (float | None): The time spacing of the new image.
         name (str | None): The name of the new image.
+        translation (Sequence[float] | None): The translation for each axis
+            at the highest resolution level. Defaults to None.
         channels_policy (Literal["squeeze", "same", "singleton"] | int):
             Possible policies:
             - If "squeeze", the channels axis will be removed (no matter its size).
@@ -853,54 +989,34 @@ def abstract_derive(
     """
     # TODO: remove in ngio 0.6
     if labels is not None:
-        warnings.warn(
+        logger.warning(
             "The 'labels' argument is deprecated and will be removed in "
-            "a future release.",
-            DeprecationWarning,
-            stacklevel=2,
+            "ngio=0.6. Please use 'channels_meta' instead."
         )
         channels_meta = list(labels)
     if pixel_size is not None:
-        warnings.warn(
+        logger.warning(
             "The 'pixel_size' argument is deprecated and will be removed in "
-            "a future release.",
-            DeprecationWarning,
-            stacklevel=2,
+            "ngio=0.6. Please use 'pixelsize', 'z_spacing', and 'time_spacing'"
+            "instead."
         )
-        pixelsize_ = (pixel_size.y, pixel_size.x)
-        z_spacing_ = pixel_size.z
-        time_spacing_ = pixel_size.t
-    else:
-        if pixelsize is None:
-            pixelsize_ = (ref_image.pixel_size.y, ref_image.pixel_size.x)
-        else:
-            pixelsize_ = pixelsize
-
-        if z_spacing is None:
-            z_spacing_ = ref_image.pixel_size.z
-        else:
-            z_spacing_ = z_spacing
-
-        if time_spacing is None:
-            time_spacing_ = ref_image.pixel_size.t
-        else:
-            time_spacing_ = time_spacing
+        pixelsize = (pixel_size.y, pixel_size.x)
+    # End of deprecated arguments handling
     ref_meta = ref_image.meta
 
-    shapes = _compute_pyramid_shapes(
+    shapes, scales = _compute_pyramid_shapes(
         shape=shape,
         ref_image=ref_image,
     )
     ref_shape = next(iter(shapes))
 
-    if pixelsize is None:
-        pixelsize = (ref_image.pixel_size.y, ref_image.pixel_size.x)
-
-    if z_spacing is None:
-        z_spacing = ref_image.pixel_size.z
-
-    if time_spacing is None:
-        time_spacing = ref_image.pixel_size.t
+    scales = adapt_scales(
+        scales=scales,
+        pixelsize=pixelsize,
+        z_spacing=z_spacing,
+        time_spacing=time_spacing,
+        ref_image=ref_image,
+    )
 
     if name is None:
         name = ref_meta.name
@@ -914,27 +1030,33 @@ def abstract_derive(
     if compressors is None:
         compressors = ref_image.zarr_array.compressors  # type: ignore
 
+    if translation is None:
+        translation = ref_image.dataset.translation
+
     if chunks is None:
         chunks = ref_image.zarr_array.chunks
     if shards is None:
         shards = ref_image.zarr_array.shards
 
-    _check_chunks_and_shards_compatibility(
+    _check_len_compatibility(
         ref_shape=ref_shape,
         chunks=chunks,
         shards=shards,
+        translation=translation,
     )
 
     if ngff_version is None:
         ngff_version = ref_meta.version
 
-    shapes, axes, chunks, shards = _apply_channel_policy(
+    shapes, axes, chunks, shards, translation, scales = _apply_channel_policy(
         ref_image=ref_image,
         channels_policy=channels_policy,
         shapes=shapes,
         axes=ref_image.axes,
         chunks=chunks,
         shards=shards,
+        translation=translation,
+        scales=scales,
     )
     channels_meta_ = _check_channels_meta_compatibility(
         meta_type=meta_type,
@@ -942,18 +1064,18 @@ def abstract_derive(
         channels_meta=channels_meta,
     )
 
-    handler = init_image_like_from_shapes(
+    handler, axes_setup = init_image_like_from_shapes(
         store=store,
         meta_type=meta_type,
         shapes=shapes,
-        pixelsize=pixelsize_,
-        z_spacing=z_spacing_,
-        time_spacing=time_spacing_,
+        base_scale=scales,
         levels=ref_meta.paths,
+        translation=translation,
         time_unit=ref_image.time_unit,
         space_unit=ref_image.space_unit,
         axes_names=axes,
         name=name,
+        axes_setup=ref_image.axes_setup,
         channels_meta=channels_meta_,
         chunks=chunks,
         shards=shards,
@@ -964,4 +1086,4 @@ def abstract_derive(
         ngff_version=ngff_version,
         extra_array_kwargs=extra_array_kwargs,
     )
-    return handler
+    return handler, axes_setup

ngio/images/_create_synt_container.py

@@ -30,6 +30,7 @@ def create_synthetic_ome_zarr(
     shape: Sequence[int],
     reference_sample: AVAILABLE_SAMPLES | SampleInfo = "Cardiomyocyte",
     levels: int | list[str] = 5,
+    translation: Sequence[float] | None = None,
     table_backend: TableBackend = DefaultTableBackend,
     scaling_factors: Sequence[float] | Literal["auto"] = "auto",
     axes_names: Sequence[str] | None = None,
@@ -51,6 +52,8 @@ def create_synthetic_ome_zarr(
             Defaults to "Cardiomyocyte".
         levels (int | list[str]): The number of levels in the pyramid or a list of
             level names. Defaults to 5.
+        translation (Sequence[float] | None): The translation for each axis
+            at the highest resolution level. Defaults to None.
         table_backend (TableBackend): Table backend to be used to store tables.
             Defaults to DefaultTableBackend.
         scaling_factors (Sequence[float] | Literal["auto"]): The down-scaling factors
@@ -82,10 +85,11 @@ def create_synthetic_ome_zarr(
     ome_zarr = create_ome_zarr_from_array(
         store=store,
         array=raw,
-        pixelsize=sample_info.xy_pixelsize,
+        pixelsize=sample_info.pixelsize,
         z_spacing=sample_info.z_spacing,
         time_spacing=sample_info.time_spacing,
         levels=levels,
+        translation=translation,
         space_unit=sample_info.space_unit,
         time_unit=sample_info.time_unit,
         axes_names=axes_names,