ngio 0.4.8__py3-none-any.whl → 0.5.0__py3-none-any.whl

ngio/images/_create_synt_container.py

@@ -1,14 +1,17 @@
 """Abstract class for handling OME-NGFF images."""
 
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
+from typing import Any, Literal
 
 import numpy as np
 import PIL.Image
-from zarr.types import DIMENSION_SEPARATOR
+from zarr.core.array import CompressorLike
 
+from ngio.common._pyramid import ChunksLike, ShardsLike
 from ngio.common._synt_images_utils import fit_to_shape
 from ngio.images._ome_zarr_container import OmeZarrContainer, create_ome_zarr_from_array
 from ngio.ome_zarr_meta.ngio_specs import (
+    Channel,
     DefaultNgffVersion,
     NgffVersions,
 )
@@ -27,52 +30,48 @@ def create_synthetic_ome_zarr(
     shape: Sequence[int],
     reference_sample: AVAILABLE_SAMPLES | SampleInfo = "Cardiomyocyte",
     levels: int | list[str] = 5,
-    xy_scaling_factor: float = 2,
-    z_scaling_factor: float = 1.0,
-    axes_names: Sequence[str] | None = None,
-    chunks: Sequence[int] | None = None,
-    channel_labels: list[str] | None = None,
-    channel_wavelengths: list[str] | None = None,
-    channel_colors: Sequence[str] | None = None,
-    channel_active: Sequence[bool] | None = None,
+    translation: Sequence[float] | None = None,
     table_backend: TableBackend = DefaultTableBackend,
-    dimension_separator: DIMENSION_SEPARATOR = "/",
-    compressor="default",
+    scaling_factors: Sequence[float] | Literal["auto"] = "auto",
+    axes_names: Sequence[str] | None = None,
+    channels_meta: Sequence[str | Channel] | None = None,
+    ngff_version: NgffVersions = DefaultNgffVersion,
+    chunks: ChunksLike = "auto",
+    shards: ShardsLike | None = None,
+    dimension_separator: Literal[".", "/"] = "/",
+    compressors: CompressorLike = "auto",
+    extra_array_kwargs: Mapping[str, Any] | None = None,
     overwrite: bool = False,
-    version: NgffVersions = DefaultNgffVersion,
 ) -> OmeZarrContainer:
-    """Create an empty OME-Zarr image with the given shape and metadata.
+    """Create a synthetic OME-Zarr image with the given shape and metadata.
 
     Args:
         store (StoreOrGroup): The Zarr store or group to create the image in.
         shape (Sequence[int]): The shape of the image.
         reference_sample (AVAILABLE_SAMPLES | SampleInfo): The reference sample to use.
-        levels (int | list[str], optional): The number of levels in the pyramid or a
-            list of level names. Defaults to 5.
-        xy_scaling_factor (float, optional): The down-scaling factor in x and y
-            dimensions. Defaults to 2.0.
-        z_scaling_factor (float, optional): The down-scaling factor in z dimension.
-            Defaults to 1.0.
-        axes_names (Sequence[str] | None, optional): The names of the axes.
-            If None the canonical names are used. Defaults to None.
-        chunks (Sequence[int] | None, optional): The chunk shape. If None the shape
-            is used. Defaults to None.
-        channel_labels (list[str] | None, optional): The labels of the channels.
-            Defaults to None.
-        channel_wavelengths (list[str] | None, optional): The wavelengths of the
-            channels. Defaults to None.
-        channel_colors (Sequence[str] | None, optional): The colors of the channels.
+            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
+            for the pyramid levels. Defaults to "auto".
+        axes_names (Sequence[str] | None): The names of the axes. If None the
+            canonical names are used. Defaults to None.
+        channels_meta (Sequence[str | Channel] | None): The channels metadata.
             Defaults to None.
-        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.
+        ngff_version (NgffVersions): The version of the OME-Zarr specification.
             Defaults to DefaultNgffVersion.
+        chunks (ChunksLike): The chunk shape. Defaults to "auto".
+        shards (ShardsLike | None): The shard shape. Defaults to None.
+        dimension_separator (Literal[".", "/"]): The separator to use for
+            dimensions. Defaults to "/".
+        compressors (CompressorLike): The compressors to use. Defaults to "auto".
+        extra_array_kwargs (Mapping[str, Any] | None): Extra arguments to pass to
+            the zarr array creation. Defaults to None.
+        overwrite (bool): Whether to overwrite an existing image. Defaults to False.
     """
     if isinstance(reference_sample, str):
         sample_info = get_sample_info(reference_sample)
@@ -86,25 +85,24 @@ def create_synthetic_ome_zarr(
     ome_zarr = create_ome_zarr_from_array(
         store=store,
         array=raw,
-        xy_pixelsize=sample_info.xy_pixelsize,
+        pixelsize=sample_info.pixelsize,
         z_spacing=sample_info.z_spacing,
         time_spacing=sample_info.time_spacing,
         levels=levels,
-        xy_scaling_factor=xy_scaling_factor,
-        z_scaling_factor=z_scaling_factor,
+        translation=translation,
         space_unit=sample_info.space_unit,
         time_unit=sample_info.time_unit,
         axes_names=axes_names,
-        channel_labels=channel_labels,
-        channel_wavelengths=channel_wavelengths,
-        channel_colors=channel_colors,
-        channel_active=channel_active,
+        channels_meta=channels_meta,
+        scaling_factors=scaling_factors,
+        extra_array_kwargs=extra_array_kwargs,
         name=sample_info.name,
         chunks=chunks,
+        shards=shards,
         overwrite=overwrite,
         dimension_separator=dimension_separator,
-        compressor=compressor,
-        version=version,
+        compressors=compressors,
+        ngff_version=ngff_version,
     )
 
     image = ome_zarr.get_image()

ngio/images/_create_utils.py

@@ -0,0 +1,406 @@
+"""Utility functions for working with OME-Zarr images."""
+
+import warnings
+from collections.abc import Mapping, Sequence
+from typing import Any, Literal, TypeVar
+
+from zarr.core.array import CompressorLike
+
+from ngio.common._pyramid import ChunksLike, ImagePyramidBuilder, ShardsLike
+from ngio.ome_zarr_meta import (
+    NgioImageMeta,
+    NgioLabelMeta,
+    update_ngio_meta,
+)
+from ngio.ome_zarr_meta.ngio_specs import (
+    AxesHandler,
+    Channel,
+    ChannelsMeta,
+    DefaultNgffVersion,
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
+    NgffVersions,
+    SpaceUnits,
+    TimeUnits,
+    build_axes_handler,
+    build_canonical_axes_handler,
+    canonical_axes_order,
+    canonical_label_axes_order,
+)
+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)
+
+
+def _align_to_axes(
+    *,
+    values: dict[str, float],
+    axes_handler: AxesHandler,
+    default_value: float = 1.0,
+) -> tuple[float, ...]:
+    """Align given values to axes names."""
+    aligned_values = [default_value] * len(axes_handler.axes_names)
+    for ax, value in values.items():
+        index = axes_handler.get_index(ax)
+        if index is not None:
+            aligned_values[index] = value
+    return tuple(aligned_values)
+
+
+def _check_deprecated_scaling_factors(
+    *,
+    yx_scaling_factor: float | tuple[float, float] | None = None,
+    z_scaling_factor: float | None = None,
+    scaling_factors: Sequence[float] | Literal["auto"] = "auto",
+    shape: tuple[int, ...],
+) -> Sequence[float] | Literal["auto"]:
+    if yx_scaling_factor is not None or z_scaling_factor is not None:
+        warnings.warn(
+            "The 'yx_scaling_factor' and 'z_scaling_factor' arguments are deprecated "
+            "and will be removed in ngio=0.6. Please use the 'scaling_factors' "
+            "argument instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        if scaling_factors != "auto":
+            raise NgioValueError(
+                "Cannot use both 'scaling_factors' and deprecated "
+                "'yx_scaling_factor'/'z_scaling_factor' arguments."
+            )
+        if isinstance(yx_scaling_factor, tuple):
+            if len(yx_scaling_factor) != 2:
+                raise NgioValueError(
+                    "yx_scaling_factor tuple must have length 2 for y and x scaling."
+                )
+            y_scale = yx_scaling_factor[0]
+            x_scale = yx_scaling_factor[1]
+        else:
+            y_scale = yx_scaling_factor if yx_scaling_factor is not None else 2.0
+            x_scale = yx_scaling_factor if yx_scaling_factor is not None else 2.0
+        z_scale = z_scaling_factor if z_scaling_factor is not None else 1.0
+        scaling_factors = (z_scale, x_scale, y_scale)
+        if len(scaling_factors) < len(shape):
+            padding = (1.0,) * (len(shape) - len(scaling_factors))
+            scaling_factors = padding + scaling_factors
+
+        return scaling_factors
+    return scaling_factors
+
+
+def _compute_scaling_factors(
+    *,
+    scaling_factors: Sequence[float] | Literal["auto"],
+    shape: tuple[int, ...],
+    axes_handler: AxesHandler,
+    xy_scaling_factor: float | tuple[float, float] | None = None,
+    z_scaling_factor: float | None = None,
+) -> tuple[float, ...]:
+    """Compute scaling factors for given axes names."""
+    # TODO remove with ngio 0.6
+    scaling_factors = _check_deprecated_scaling_factors(
+        yx_scaling_factor=xy_scaling_factor,
+        z_scaling_factor=z_scaling_factor,
+        scaling_factors=scaling_factors,
+        shape=shape,
+    )
+    if scaling_factors == "auto":
+        return _align_to_axes(
+            values={
+                "x": 2.0,
+                "y": 2.0,
+                "z": 1.0,
+            },
+            axes_handler=axes_handler,
+        )
+    if len(scaling_factors) != len(shape):
+        raise NgioValueError(
+            "Length of scaling_factors does not match the number of dimensions."
+        )
+    return tuple(scaling_factors)
+
+
+def compute_base_scale(
+    *,
+    pixelsize: float | tuple[float, float],
+    z_spacing: float,
+    time_spacing: float,
+    axes_handler: AxesHandler,
+) -> tuple[float, ...]:
+    """Compute base scale for given axes names."""
+    if isinstance(pixelsize, tuple):
+        if len(pixelsize) != 2:
+            raise NgioValueError(
+                "pixelsize tuple must have length 2 for y and x pixel sizes."
+            )
+        x_size = pixelsize[1]
+        y_size = pixelsize[0]
+    else:
+        x_size = pixelsize
+        y_size = pixelsize
+    return _align_to_axes(
+        values={
+            "x": x_size,
+            "y": y_size,
+            "z": z_spacing,
+            "t": time_spacing,
+        },
+        axes_handler=axes_handler,
+    )
+
+
+def _create_image_like_group(
+    *,
+    store: StoreOrGroup,
+    pyramid_builder: ImagePyramidBuilder,
+    meta: _image_or_label_meta,
+    overwrite: bool = False,
+) -> ZarrGroupHandler:
+    """Advanced create empty image container function placeholder."""
+    mode = "w" if overwrite else "w-"
+    group_handler = ZarrGroupHandler(
+        store=store, mode=mode, cache=False, zarr_format=meta.zarr_format
+    )
+    update_ngio_meta(group_handler, meta)
+    # Reopen in r+ mode
+    group_handler = group_handler.reopen_handler()
+    # Write the pyramid
+    pyramid_builder.to_zarr(group=group_handler.group)
+    return group_handler
+
+
+def _add_channels_meta(
+    *,
+    meta: _image_or_label_meta,
+    channels_meta: Sequence[str | Channel] | None = None,
+) -> _image_or_label_meta:
+    """Create ChannelsMeta from given channels_meta input."""
+    if isinstance(meta, NgioLabelMeta):
+        if channels_meta is not None:
+            raise NgioValueError(
+                "Cannot add channels_meta to NgioLabelMeta. "
+                "Labels do not have channels."
+            )
+        else:
+            return meta
+    if channels_meta is None:
+        return meta
+    list_of_channels = []
+    for c in channels_meta:
+        if isinstance(c, str):
+            channel = Channel.default_init(label=c)
+        elif isinstance(c, Channel):
+            channel = c
+        else:
+            raise NgioValueError(
+                "channels_meta must be a list of strings or Channel objects."
+            )
+        list_of_channels.append(channel)
+
+    channels_meta_ = ChannelsMeta(channels=list_of_channels)
+    meta.set_channels_meta(channels_meta=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,
+) -> 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_,
+        )
+    return build_axes_handler(
+        axes_names=axes_names,
+        axes_setup=axes_setup,
+    )
+
+
+def init_image_like(
+    *,
+    # Where to create the image
+    store: StoreOrGroup,
+    # Ngff image parameters
+    meta_type: type[_image_or_label_meta],
+    shape: Sequence[int],
+    pixelsize: float | tuple[float, float],
+    z_spacing: float = 1.0,
+    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,
+    name: str | None = None,
+    channels_meta: Sequence[str | Channel] | None = None,
+    ngff_version: NgffVersions = DefaultNgffVersion,
+    # Zarr Array parameters
+    chunks: ChunksLike = "auto",
+    shards: ShardsLike | None = None,
+    dtype: str = "uint16",
+    dimension_separator: Literal[".", "/"] = "/",
+    compressors: CompressorLike = "auto",
+    extra_array_kwargs: Mapping[str, Any] | None = None,
+    # internal axes configuration for advanced use cases
+    axes_setup: AxesSetup | None = None,
+    # 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,
+) -> tuple[ZarrGroupHandler, AxesSetup]:
+    """Create an empty OME-Zarr image with the given shape and metadata."""
+    shape = tuple(shape)
+    axes_handler = _build_axes_handler(
+        shape=shape,
+        meta_type=meta_type,
+        axes_names=axes_names,
+        axes_setup=axes_setup,
+    )
+    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,
+        axes_handler=axes_handler,
+    )
+    scaling_factors = _compute_scaling_factors(
+        scaling_factors=scaling_factors,
+        shape=shape,
+        axes_handler=axes_handler,
+        xy_scaling_factor=yx_scaling_factor,
+        z_scaling_factor=z_scaling_factor,
+    )
+    if isinstance(levels, int):
+        levels_paths = tuple(str(i) for i in range(levels))
+    else:
+        levels_paths = tuple(levels)
+
+    pyramid_builder = ImagePyramidBuilder.from_scaling_factors(
+        levels_paths=levels_paths,
+        scaling_factors=scaling_factors,
+        base_shape=shape,
+        base_scale=base_scale,
+        base_translation=translation,
+        axes=axes_handler.axes_names,
+        chunks=chunks,
+        data_type=dtype,
+        dimension_separator=dimension_separator,
+        compressors=compressors,
+        shards=shards,
+        zarr_format=2 if ngff_version == "0.4" else 3,
+        other_array_kwargs=extra_array_kwargs,
+    )
+    meta = meta_type.default_init(
+        levels=[p.path for p in pyramid_builder.levels],
+        axes_handler=axes_handler,
+        scales=[p.scale for p 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
+    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(
+    *,
+    # Where to create the image
+    store: StoreOrGroup,
+    # Ngff image parameters
+    meta_type: type[_image_or_label_meta],
+    shapes: Sequence[tuple[int, ...]],
+    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,
+    name: str | None = None,
+    channels_meta: Sequence[str | Channel] | None = None,
+    ngff_version: NgffVersions = DefaultNgffVersion,
+    # Zarr Array parameters
+    chunks: ChunksLike = "auto",
+    shards: ShardsLike | None = None,
+    dtype: str = "uint16",
+    dimension_separator: Literal[".", "/"] = "/",
+    compressors: CompressorLike = "auto",
+    extra_array_kwargs: Mapping[str, Any] | None = None,
+    # internal axes configuration for advanced use cases
+    axes_setup: AxesSetup | None = None,
+    # Whether to overwrite existing image
+    overwrite: bool = False,
+) -> tuple[ZarrGroupHandler, AxesSetup]:
+    """Create an empty OME-Zarr image with the given shape and metadata."""
+    base_shape = shapes[0]
+    axes_handler = _build_axes_handler(
+        shape=base_shape,
+        meta_type=meta_type,
+        axes_names=axes_names,
+        axes_setup=axes_setup,
+    )
+    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:
+        levels_paths = tuple(levels)
+
+    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,
+        data_type=dtype,
+        dimension_separator=dimension_separator,
+        compressors=compressors,
+        shards=shards,
+        zarr_format=2 if ngff_version == "0.4" else 3,
+        other_array_kwargs=extra_array_kwargs,
+    )
+    meta = meta_type.default_init(
+        levels=[p.path for p in pyramid_builder.levels],
+        axes_handler=axes_handler,
+        scales=[p.scale for p 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
+    image_handler = _create_image_like_group(
+        store=store,
+        pyramid_builder=pyramid_builder,
+        meta=meta,
+        overwrite=overwrite,
+    )
+    return image_handler, axes_handler.axes_setup