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

ngio/images/_create_utils.py

@@ -1,6 +1,6 @@
 """Utility functions for working with OME-Zarr images."""
 
-import warnings
+import logging
 from collections.abc import Mapping, Sequence
 from typing import Any, Literal, TypeVar
 
@@ -22,6 +22,7 @@ from ngio.ome_zarr_meta.ngio_specs import (
     NgffVersions,
     SpaceUnits,
     TimeUnits,
+    build_axes_handler,
     build_canonical_axes_handler,
     canonical_axes_order,
     canonical_label_axes_order,
@@ -29,37 +30,9 @@ from ngio.ome_zarr_meta.ngio_specs import (
 from ngio.ome_zarr_meta.ngio_specs._axes import AxesSetup
 from ngio.utils import NgioValueError, StoreOrGroup, ZarrGroupHandler
 
-_image_or_label_meta = TypeVar("_image_or_label_meta", NgioImageMeta, NgioLabelMeta)
-
+logger = logging.getLogger(f"ngio:{__name__}")
 
-def _build_axes_handler(
-    *,
-    shape: tuple[int, ...],
-    axes_names: Sequence[str] | None,
-    default_channel_order: tuple[str, ...],
-    space_units: SpaceUnits | str | None = DefaultSpaceUnit,
-    time_units: TimeUnits | str | None = DefaultTimeUnit,
-    axes_setup: AxesSetup | None = None,
-    allow_non_canonical_axes: bool = False,
-    strict_canonical_order: bool = False,
-) -> AxesHandler:
-    """Compute axes names for given shape."""
-    if axes_names is None:
-        axes_names = default_channel_order[-len(shape) :]
-    # Validate length
-    if len(axes_names) != len(shape):
-        raise NgioValueError(
-            f"Number of axes names {axes_names} does not match the number of "
-            f"dimensions {shape}."
-        )
-    return build_canonical_axes_handler(
-        axes_names=axes_names,
-        space_units=space_units,
-        time_units=time_units,
-        axes_setup=axes_setup,
-        allow_non_canonical_axes=allow_non_canonical_axes,
-        strict_canonical_order=strict_canonical_order,
-    )
+_image_or_label_meta = TypeVar("_image_or_label_meta", NgioImageMeta, NgioLabelMeta)
 
 
 def _align_to_axes(
@@ -85,9 +58,9 @@ def _check_deprecated_scaling_factors(
     shape: tuple[int, ...],
 ) -> Sequence[float] | Literal["auto"]:
     if yx_scaling_factor is not None or z_scaling_factor is not None:
-        warnings.warn(
+        logger.warning(
             "The 'yx_scaling_factor' and 'z_scaling_factor' arguments are deprecated "
-            "and will be removed in future versions. Please use the 'scaling_factors' "
+            "and will be removed in ngio=0.6. Please use the 'scaling_factors' "
             "argument instead.",
             DeprecationWarning,
             stacklevel=2,
@@ -149,7 +122,7 @@ def _compute_scaling_factors(
     return tuple(scaling_factors)
 
 
-def _compute_base_scale(
+def compute_base_scale(
     *,
     pixelsize: float | tuple[float, float],
     z_spacing: float,
@@ -231,6 +204,38 @@ def _add_channels_meta(
     return meta
 
 
+def _build_axes_handler(
+    *,
+    shape: tuple[int, ...],
+    meta_type: type[_image_or_label_meta],
+    axes_names: Sequence[str] | None = None,
+    axes_setup: AxesSetup | None = None,
+    space_unit: SpaceUnits | str | None = None,
+    time_unit: TimeUnits | str | None = None,
+) -> AxesHandler:
+    """Build axes handler for given shape and axes names."""
+    if meta_type is NgioImageMeta:
+        canonical_axes_order_ = canonical_axes_order()
+    else:
+        canonical_axes_order_ = canonical_label_axes_order()
+    if axes_names is None:
+        axes_names = canonical_axes_order_[-len(shape) :]
+
+    if axes_setup is None:
+        return build_canonical_axes_handler(
+            axes_names=axes_names,
+            canonical_channel_order=canonical_axes_order_,
+            space_unit=space_unit,
+            time_unit=time_unit,
+        )
+    return build_axes_handler(
+        axes_names=axes_names,
+        axes_setup=axes_setup,
+        space_unit=space_unit,
+        time_unit=time_unit,
+    )
+
+
 def init_image_like(
     *,
     # Where to create the image
@@ -243,6 +248,7 @@ def init_image_like(
     time_spacing: float = 1.0,
     scaling_factors: Sequence[float] | Literal["auto"] = "auto",
     levels: int | list[str] = 5,
+    translation: Sequence[float] | None = None,
     space_unit: SpaceUnits | str | None = DefaultSpaceUnit,
     time_unit: TimeUnits | str | None = DefaultTimeUnit,
     axes_names: Sequence[str] | None = None,
@@ -258,32 +264,28 @@ def init_image_like(
     extra_array_kwargs: Mapping[str, Any] | None = None,
     # internal axes configuration for advanced use cases
     axes_setup: AxesSetup | None = None,
-    allow_non_canonical_axes: bool = False,
-    strict_canonical_order: bool = False,
     # Whether to overwrite existing image
     overwrite: bool = False,
     # Deprecated arguments
     yx_scaling_factor: float | tuple[float, float] | None = None,
     z_scaling_factor: float | None = None,
-) -> ZarrGroupHandler:
+) -> tuple[ZarrGroupHandler, AxesSetup]:
     """Create an empty OME-Zarr image with the given shape and metadata."""
     shape = tuple(shape)
-    if meta_type is NgioImageMeta:
-        default_axes_order = canonical_axes_order()
-    else:
-        default_axes_order = canonical_label_axes_order()
-
     axes_handler = _build_axes_handler(
         shape=shape,
+        meta_type=meta_type,
         axes_names=axes_names,
-        default_channel_order=default_axes_order,
-        space_units=space_unit,
-        time_units=time_unit,
         axes_setup=axes_setup,
-        allow_non_canonical_axes=allow_non_canonical_axes,
-        strict_canonical_order=strict_canonical_order,
+        space_unit=space_unit,
+        time_unit=time_unit,
     )
-    base_scale = _compute_base_scale(
+    if len(shape) != len(axes_handler.axes_names):
+        raise NgioValueError(
+            f"Mismatch between shape {shape} "
+            f"and number of axes {len(axes_handler.axes_names)}."
+        )
+    base_scale = compute_base_scale(
         pixelsize=pixelsize,
         z_spacing=z_spacing,
         time_spacing=time_spacing,
@@ -306,6 +308,7 @@ def init_image_like(
         scaling_factors=scaling_factors,
         base_shape=shape,
         base_scale=base_scale,
+        base_translation=translation,
         axes=axes_handler.axes_names,
         chunks=chunks,
         data_type=dtype,
@@ -319,18 +322,19 @@ def init_image_like(
         levels=[p.path for p in pyramid_builder.levels],
         axes_handler=axes_handler,
         scales=[p.scale for p in pyramid_builder.levels],
-        translations=[None for _ in pyramid_builder.levels],
+        translations=[p.translation for p in pyramid_builder.levels],
         name=name,
         version=ngff_version,
     )
     meta = _add_channels_meta(meta=meta, channels_meta=channels_meta)
     # Keep this creation at the end to avoid partial creations on errors
-    return _create_image_like_group(
+    image_handler = _create_image_like_group(
         store=store,
         pyramid_builder=pyramid_builder,
         meta=meta,
         overwrite=overwrite,
     )
+    return image_handler, axes_handler.axes_setup
 
 
 def init_image_like_from_shapes(
@@ -340,10 +344,9 @@ def init_image_like_from_shapes(
     # Ngff image parameters
     meta_type: type[_image_or_label_meta],
     shapes: Sequence[tuple[int, ...]],
-    pixelsize: float | tuple[float, float],
-    z_spacing: float = 1.0,
-    time_spacing: float = 1.0,
+    base_scale: tuple[float, ...] | list[tuple[float, ...]],
     levels: list[str] | None = None,
+    translation: Sequence[float] | None = None,
     space_unit: SpaceUnits | str | None = DefaultSpaceUnit,
     time_unit: TimeUnits | str | None = DefaultTimeUnit,
     axes_names: Sequence[str] | None = None,
@@ -359,34 +362,24 @@ def init_image_like_from_shapes(
     extra_array_kwargs: Mapping[str, Any] | None = None,
     # internal axes configuration for advanced use cases
     axes_setup: AxesSetup | None = None,
-    allow_non_canonical_axes: bool = False,
-    strict_canonical_order: bool = False,
     # Whether to overwrite existing image
     overwrite: bool = False,
-) -> ZarrGroupHandler:
+) -> tuple[ZarrGroupHandler, AxesSetup]:
     """Create an empty OME-Zarr image with the given shape and metadata."""
     base_shape = shapes[0]
-    if meta_type is NgioImageMeta:
-        default_axes_order = canonical_axes_order()
-    else:
-        default_axes_order = canonical_label_axes_order()
-
     axes_handler = _build_axes_handler(
         shape=base_shape,
+        meta_type=meta_type,
         axes_names=axes_names,
-        default_channel_order=default_axes_order,
-        space_units=space_unit,
-        time_units=time_unit,
         axes_setup=axes_setup,
-        allow_non_canonical_axes=allow_non_canonical_axes,
-        strict_canonical_order=strict_canonical_order,
-    )
-    base_scale = _compute_base_scale(
-        pixelsize=pixelsize,
-        z_spacing=z_spacing,
-        time_spacing=time_spacing,
-        axes_handler=axes_handler,
+        space_unit=space_unit,
+        time_unit=time_unit,
     )
+    if len(base_shape) != len(axes_handler.axes_names):
+        raise NgioValueError(
+            f"Mismatch between shape {base_shape} "
+            f"and number of axes {len(axes_handler.axes_names)}."
+        )
     if levels is None:
         levels_paths = tuple(str(i) for i in range(len(shapes)))
     else:
@@ -395,6 +388,7 @@ def init_image_like_from_shapes(
     pyramid_builder = ImagePyramidBuilder.from_shapes(
         shapes=shapes,
         base_scale=base_scale,
+        base_translation=translation,
         levels_paths=levels_paths,
         axes=axes_handler.axes_names,
         chunks=chunks,
@@ -409,15 +403,16 @@ def init_image_like_from_shapes(
         levels=[p.path for p in pyramid_builder.levels],
         axes_handler=axes_handler,
         scales=[p.scale for p in pyramid_builder.levels],
-        translations=[None for _ in pyramid_builder.levels],
+        translations=[p.translation for p in pyramid_builder.levels],
         name=name,
         version=ngff_version,
     )
     meta = _add_channels_meta(meta=meta, channels_meta=channels_meta)
     # Keep this creation at the end to avoid partial creations on errors
-    return _create_image_like_group(
+    image_handler = _create_image_like_group(
         store=store,
         pyramid_builder=pyramid_builder,
         meta=meta,
         overwrite=overwrite,
     )
+    return image_handler, axes_handler.axes_setup