ngio 0.5.0b5__tar.gz → 0.5.0b7__tar.gz

{ngio-0.5.0b5 → ngio-0.5.0b7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ngio
-Version: 0.5.0b5
+Version: 0.5.0b7
 Summary: Next Generation file format IO
 Project-URL: homepage, https://github.com/BioVisionCenter/ngio
 Project-URL: repository, https://github.com/BioVisionCenter/ngio

{ngio-0.5.0b5 → ngio-0.5.0b7}/src/ngio/common/_pyramid.py

@@ -1,3 +1,5 @@
+import itertools
+import math
 from collections.abc import Callable, Mapping, Sequence
 from typing import Any, Literal
 
@@ -195,7 +197,7 @@ ChunksLike = tuple[int, ...] | Literal["auto"]
 ShardsLike = tuple[int, ...] | Literal["auto"]
 
 
-def shapes_from_scaling_factors(
+def compute_shapes_from_scaling_factors(
     base_shape: tuple[int, ...],
     scaling_factors: tuple[float, ...],
     num_levels: int,
@@ -215,7 +217,7 @@ def shapes_from_scaling_factors(
     for _ in range(num_levels):
         shapes.append(current_shape)
         current_shape = tuple(
-            max(1, int(s / f))
+            max(1, math.floor(s / f))
             for s, f in zip(current_shape, scaling_factors, strict=True)
         )
     return shapes
@@ -233,6 +235,7 @@ class PyramidLevel(BaseModel):
     path: str
     shape: tuple[int, ...]
     scale: tuple[float, ...]
+    translation: tuple[float, ...]
     chunks: ChunksLike = "auto"
     shards: ShardsLike | None = None
 
@@ -247,6 +250,12 @@ class PyramidLevel(BaseModel):
         if any(isinstance(s, float) and s < 0 for s in self.scale):
             raise NgioValueError("Scale values must be positive.")
 
+        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)}"
+            )
+
         if isinstance(self.chunks, tuple):
             if len(self.chunks) != len(self.shape):
                 raise NgioValueError(
@@ -271,6 +280,63 @@ class PyramidLevel(BaseModel):
         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))
+    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, ...]
@@ -290,6 +356,7 @@ class ImagePyramidBuilder(BaseModel):
         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",
@@ -297,16 +364,39 @@ class ImagePyramidBuilder(BaseModel):
         compressors: Any = "auto",
         zarr_format: Literal[2, 3] = 2,
         other_array_kwargs: Mapping[str, Any] | None = None,
+        precision_scale: bool = True,
     ) -> "ImagePyramidBuilder":
-        shapes = shapes_from_scaling_factors(
+        # 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),
         )
+
+        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),
+            )
+
         return cls.from_shapes(
             shapes=shapes,
-            base_scale=base_scale,
+            base_scale=base_scale_,
             axes=axes,
+            base_translation=base_translation,
             levels_paths=levels_paths,
             chunks=chunks,
             shards=shards,
@@ -321,8 +411,9 @@ class ImagePyramidBuilder(BaseModel):
     def from_shapes(
         cls,
         shapes: Sequence[tuple[int, ...]],
-        base_scale: tuple[float, ...],
+        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,
@@ -335,34 +426,42 @@ class ImagePyramidBuilder(BaseModel):
         levels = []
         if levels_paths is None:
             levels_paths = tuple(str(i) for i in range(len(shapes)))
+
         _check_order(shapes)
-        scale_ = base_scale
-        for i, (path, shape) in enumerate(zip(levels_paths, shapes, strict=True)):
-            levels.append(
-                PyramidLevel(
-                    path=path,
-                    shape=shape,
-                    scale=scale_,
-                    chunks=chunks,
-                    shards=shards,
+        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."
             )
-            if i + 1 < len(shapes):
-                # This only works for downsampling pyramids
-                # The _check_order function ensures that
-                # shapes are decreasing
-                next_shape = shapes[i + 1]
-                scaling_factor = tuple(
-                    s1 / s2
-                    for s1, s2 in zip(
-                        shape,
-                        next_shape,
-                        strict=True,
-                    )
-                )
-                scale_ = tuple(
-                    s * f for s, f in zip(scale_, scaling_factor, strict=True)
-                )
+
+        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,

{ngio-0.5.0b5 → ngio-0.5.0b7}/src/ngio/common/_roi.py

@@ -1,6 +1,6 @@
 """Region of interest (ROI) metadata.
 
-These are the interfaces bwteen the ROI tables / masking ROI tables and
+These are the interfaces between the ROI tables / masking ROI tables and
     the ImageLikeHandler.
 """
 

{ngio-0.5.0b5 → ngio-0.5.0b7}/src/ngio/images/_abstract_image.py

@@ -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 (
@@ -602,32 +608,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 +650,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 +684,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 +696,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 +711,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 +730,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 +747,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 +757,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 +775,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 +787,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 +832,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 +873,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,
@@ -822,8 +901,9 @@ def abstract_derive(
         pixelsize (float | tuple[float, float] | None): The pixel size of the new image.
         z_spacing (float | None): The z spacing of the new image.
         time_spacing (float | None): The time spacing of the new image.
-        axes_names (Sequence[str] | None): The axes names 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).
@@ -837,7 +917,7 @@ def abstract_derive(
         chunks (ChunksLike | None): The chunk shape of the new image.
         shards (ShardsLike | None): The shard shape of the new image.
         dtype (str | None): The data type of the new image.
-        dimension_separator (DIMENSION_SEPARATOR | None): The separator to use for
+        dimension_separator (Literal[".", "/"] | None): The separator to use for
             dimensions.
         compressors (CompressorLike | None): The compressors to use.
         extra_array_kwargs (Mapping[str, Any] | None): Extra arguments to pass to
@@ -868,40 +948,23 @@ def abstract_derive(
             DeprecationWarning,
             stacklevel=2,
         )
-        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
@@ -915,27 +978,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,
@@ -947,10 +1016,9 @@ def abstract_derive(
         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,

{ngio-0.5.0b5 → ngio-0.5.0b7}/src/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
@@ -86,6 +89,7 @@ def create_synthetic_ome_zarr(
         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,