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

ngio/images/_create.py

@@ -0,0 +1,287 @@
+"""Utility functions for working with OME-Zarr images."""
+
+from collections.abc import Sequence
+from typing import Literal, TypeVar
+
+from zarr.core.array import CompressorLike
+
+from ngio.common._pyramid import init_empty_pyramid
+from ngio.ome_zarr_meta import (
+    NgioImageMeta,
+    NgioLabelMeta,
+    PixelSize,
+    get_image_meta_handler,
+    get_label_meta_handler,
+)
+from ngio.ome_zarr_meta.ngio_specs import (
+    DefaultNgffVersion,
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
+    NgffVersions,
+    SpaceUnits,
+    TimeUnits,
+    canonical_axes_order,
+    canonical_label_axes_order,
+)
+from ngio.utils import NgioValueError, StoreOrGroup, ZarrGroupHandler
+
+_image_or_label_meta = TypeVar("_image_or_label_meta", NgioImageMeta, NgioLabelMeta)
+
+
+def _init_generic_meta(
+    meta_type: type[_image_or_label_meta],
+    pixelsize: float,
+    axes_names: Sequence[str],
+    z_spacing: float = 1.0,
+    time_spacing: float = 1.0,
+    levels: int | list[str] = 5,
+    yx_scaling_factor: float | tuple[float, float] = 2.0,
+    z_scaling_factor: float = 1.0,
+    space_unit: SpaceUnits | str | None = DefaultSpaceUnit,
+    time_unit: TimeUnits | str | None = DefaultTimeUnit,
+    name: str | None = None,
+    ngff_version: NgffVersions = DefaultNgffVersion,
+) -> tuple[_image_or_label_meta, list[float]]:
+    """Initialize the metadata for an image or label."""
+    scaling_factors = []
+    for ax in axes_names:
+        if ax == "z":
+            scaling_factors.append(z_scaling_factor)
+        elif ax in ["x"]:
+            if isinstance(yx_scaling_factor, tuple):
+                scaling_factors.append(yx_scaling_factor[1])
+            else:
+                scaling_factors.append(yx_scaling_factor)
+        elif ax in ["y"]:
+            if isinstance(yx_scaling_factor, tuple):
+                scaling_factors.append(yx_scaling_factor[0])
+            else:
+                scaling_factors.append(yx_scaling_factor)
+        else:
+            scaling_factors.append(1.0)
+
+    pixel_sizes = PixelSize(
+        x=pixelsize,
+        y=pixelsize,
+        z=z_spacing,
+        t=time_spacing,
+        space_unit=space_unit,
+        time_unit=time_unit,
+    )
+
+    meta = meta_type.default_init(
+        name=name,
+        levels=levels,
+        axes_names=axes_names,
+        pixel_size=pixel_sizes,
+        scaling_factors=scaling_factors,
+        version=ngff_version,
+    )
+    return meta, scaling_factors
+
+
+def create_empty_label_container(
+    store: StoreOrGroup,
+    shape: Sequence[int],
+    pixelsize: float,
+    z_spacing: float = 1.0,
+    time_spacing: float = 1.0,
+    levels: int | list[str] = 5,
+    yx_scaling_factor: float | tuple[float, float] = 2.0,
+    z_scaling_factor: float = 1.0,
+    space_unit: SpaceUnits | str | None = DefaultSpaceUnit,
+    time_unit: TimeUnits | str | None = DefaultTimeUnit,
+    axes_names: Sequence[str] | None = None,
+    name: str | None = None,
+    chunks: Sequence[int] | Literal["auto"] = "auto",
+    dtype: str = "uint32",
+    dimension_separator: Literal[".", "/"] = "/",
+    compressors: CompressorLike = "auto",
+    overwrite: bool = False,
+    ngff_version: NgffVersions = DefaultNgffVersion,
+) -> ZarrGroupHandler:
+    """Create an empty label 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.
+        pixelsize (float): The pixel size in x and y dimensions.
+        z_spacing (float, optional): The spacing between z slices. Defaults to 1.0.
+        time_spacing (float, optional): The spacing between time points.
+            Defaults to 1.0.
+        levels (int | list[str], optional): The number of levels in the pyramid or a
+            list of level names. Defaults to 5.
+        yx_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.
+        space_unit (SpaceUnits, optional): The unit of space. Defaults to
+            DefaultSpaceUnit.
+        time_unit (TimeUnits, optional): The unit of time. Defaults to
+            DefaultTimeUnit.
+        axes_names (Sequence[str] | None, optional): The names of the axes.
+            If None the canonical names are used. Defaults to None.
+        name (str | None, optional): The name of the image. Defaults to None.
+        chunks (Sequence[int] | Literal["auto"]): The chunk shape. If None the shape
+            is used. Defaults to None.
+        dimension_separator (DIMENSION_SEPARATOR): The separator to use for
+            dimensions. Defaults to "/".
+        compressors (CompressorLike): The compressors to use. Defaults to "auto".
+        dtype (str, optional): The data type of the image. Defaults to "uint16".
+        overwrite (bool, optional): Whether to overwrite an existing image.
+            Defaults to True.
+        ngff_version (str, optional): The version of the OME-Zarr specification.
+            Defaults to DefaultVersion.
+
+    """
+    if axes_names is None:
+        axes_names = canonical_label_axes_order()[-len(shape) :]
+
+    if len(axes_names) != len(shape):
+        raise NgioValueError(
+            f"Number of axes names {axes_names} does not match the number of "
+            f"dimensions {shape}."
+        )
+
+    meta, scaling_factors = _init_generic_meta(
+        meta_type=NgioLabelMeta,
+        pixelsize=pixelsize,
+        z_spacing=z_spacing,
+        time_spacing=time_spacing,
+        levels=levels,
+        yx_scaling_factor=yx_scaling_factor,
+        z_scaling_factor=z_scaling_factor,
+        space_unit=space_unit,
+        time_unit=time_unit,
+        axes_names=axes_names,
+        name=name,
+        ngff_version=ngff_version,
+    )
+
+    mode = "w" if overwrite else "w-"
+    group_handler = ZarrGroupHandler(
+        store=store, mode=mode, cache=False, zarr_format=meta.zarr_format
+    )
+    image_handler = get_label_meta_handler(
+        version=ngff_version, group_handler=group_handler
+    )
+    image_handler.write_meta(meta)
+
+    init_empty_pyramid(
+        store=store,
+        paths=meta.paths,
+        scaling_factors=scaling_factors,
+        ref_shape=shape,
+        chunks=chunks,
+        axes=axes_names,
+        dtype=dtype,
+        mode="a",
+        dimension_separator=dimension_separator,
+        compressors=compressors,
+    )
+    group_handler._mode = "r+"
+    return group_handler
+
+
+def create_empty_image_container(
+    store: StoreOrGroup,
+    shape: Sequence[int],
+    pixelsize: float,
+    z_spacing: float = 1.0,
+    time_spacing: float = 1.0,
+    levels: int | list[str] = 5,
+    yx_scaling_factor: float | tuple[float, float] = 2,
+    z_scaling_factor: float = 1.0,
+    space_unit: SpaceUnits | str | None = DefaultSpaceUnit,
+    time_unit: TimeUnits | str | None = DefaultTimeUnit,
+    axes_names: Sequence[str] | None = None,
+    name: str | None = None,
+    chunks: Sequence[int] | Literal["auto"] = "auto",
+    dtype: str = "uint16",
+    dimension_separator: Literal[".", "/"] = "/",
+    compressors: CompressorLike = "auto",
+    overwrite: bool = False,
+    ngff_version: NgffVersions = DefaultNgffVersion,
+) -> ZarrGroupHandler:
+    """Create an empty 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.
+        pixelsize (float): The pixel size in x and y dimensions.
+        z_spacing (float, optional): The spacing between z slices. Defaults to 1.0.
+        time_spacing (float, optional): The spacing between time points.
+            Defaults to 1.0.
+        levels (int | list[str], optional): The number of levels in the pyramid or a
+            list of level names. Defaults to 5.
+        yx_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.
+        space_unit (SpaceUnits, optional): The unit of space. Defaults to
+            DefaultSpaceUnit.
+        time_unit (TimeUnits, optional): The unit of time. Defaults to
+            DefaultTimeUnit.
+        axes_names (Sequence[str] | None, optional): The names of the axes.
+            If None the canonical names are used. Defaults to None.
+        name (str | None, optional): The name of the image. Defaults to None.
+        chunks (Sequence[int] | Literal["auto"]): 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 "/".
+        compressors (CompressorLike): The compressors to use. Defaults to "auto".
+        overwrite (bool, optional): Whether to overwrite an existing image.
+            Defaults to True.
+        ngff_version (str, optional): The version of the OME-Zarr specification.
+            Defaults to DefaultVersion.
+
+    """
+    if axes_names is None:
+        axes_names = canonical_axes_order()[-len(shape) :]
+
+    if len(axes_names) != len(shape):
+        raise NgioValueError(
+            f"Number of axes names {axes_names} does not match the number of "
+            f"dimensions {shape}."
+        )
+
+    meta, scaling_factors = _init_generic_meta(
+        meta_type=NgioImageMeta,
+        pixelsize=pixelsize,
+        z_spacing=z_spacing,
+        time_spacing=time_spacing,
+        levels=levels,
+        yx_scaling_factor=yx_scaling_factor,
+        z_scaling_factor=z_scaling_factor,
+        space_unit=space_unit,
+        time_unit=time_unit,
+        axes_names=axes_names,
+        name=name,
+        ngff_version=ngff_version,
+    )
+    mode = "w" if overwrite else "w-"
+    group_handler = ZarrGroupHandler(
+        store=store, mode=mode, cache=False, zarr_format=meta.zarr_format
+    )
+    image_handler = get_image_meta_handler(
+        version=ngff_version, group_handler=group_handler
+    )
+    image_handler.write_meta(meta)
+
+    init_empty_pyramid(
+        store=store,
+        paths=meta.paths,
+        scaling_factors=scaling_factors,
+        ref_shape=shape,
+        chunks=chunks,
+        axes=axes_names,
+        dtype=dtype,
+        mode="a",
+        dimension_separator=dimension_separator,
+        compressors=compressors,
+        zarr_format=meta.zarr_format,
+    )
+
+    group_handler._mode = "r+"
+    return group_handler

ngio/images/_create_synt_container.py

@@ -1,17 +1,15 @@
 """Abstract class for handling OME-NGFF images."""
 
-from collections.abc import Mapping, Sequence
-from typing import Any, Literal
+from collections.abc import Sequence
+from typing import Literal
 
 import numpy as np
 import PIL.Image
 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,
 )
@@ -30,48 +28,52 @@ 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",
+    xy_scaling_factor: float = 2,
+    z_scaling_factor: float = 1.0,
     axes_names: Sequence[str] | None = None,
-    channels_meta: Sequence[str | Channel] | None = None,
-    ngff_version: NgffVersions = DefaultNgffVersion,
-    chunks: ChunksLike = "auto",
-    shards: ShardsLike | None = None,
+    chunks: Sequence[int] | Literal["auto"] = "auto",
+    channel_labels: list[str] | None = None,
+    channel_wavelengths: list[str] | None = None,
+    channel_colors: Sequence[str] | None = None,
+    channel_active: Sequence[bool] | None = None,
+    table_backend: TableBackend = DefaultTableBackend,
     dimension_separator: Literal[".", "/"] = "/",
     compressors: CompressorLike = "auto",
-    extra_array_kwargs: Mapping[str, Any] | None = None,
     overwrite: bool = False,
+    ngff_version: NgffVersions = DefaultNgffVersion,
 ) -> OmeZarrContainer:
-    """Create a synthetic OME-Zarr image with the given shape and metadata.
+    """Create an empty 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.
-            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.
+        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] | Literal["auto"]): The chunk shape. If None the shape
+            is used. Defaults to "auto".
+        channel_labels (list[str] | None, optional): The labels of the channels.
             Defaults to None.
-        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
+        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 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 "/".
         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.
+        overwrite (bool, optional): Whether to overwrite an existing image.
+            Defaults to True.
+        ngff_version (NgffVersion, optional): The version of the OME-Zarr specification.
+            Defaults to DefaultNgffVersion.
     """
     if isinstance(reference_sample, str):
         sample_info = get_sample_info(reference_sample)
@@ -85,20 +87,21 @@ def create_synthetic_ome_zarr(
     ome_zarr = create_ome_zarr_from_array(
         store=store,
         array=raw,
-        pixelsize=sample_info.pixelsize,
+        xy_pixelsize=sample_info.xy_pixelsize,
         z_spacing=sample_info.z_spacing,
         time_spacing=sample_info.time_spacing,
         levels=levels,
-        translation=translation,
+        xy_scaling_factor=xy_scaling_factor,
+        z_scaling_factor=z_scaling_factor,
         space_unit=sample_info.space_unit,
         time_unit=sample_info.time_unit,
         axes_names=axes_names,
-        channels_meta=channels_meta,
-        scaling_factors=scaling_factors,
-        extra_array_kwargs=extra_array_kwargs,
+        channel_labels=channel_labels,
+        channel_wavelengths=channel_wavelengths,
+        channel_colors=channel_colors,
+        channel_active=channel_active,
         name=sample_info.name,
         chunks=chunks,
-        shards=shards,
         overwrite=overwrite,
         dimension_separator=dimension_separator,
         compressors=compressors,