ngio 0.2.0a2__py3-none-any.whl → 0.2.0b1__py3-none-any.whl

ngio/images/create.py

@@ -5,11 +5,11 @@ from typing import TypeVar
 
 from ngio.common._pyramid import init_empty_pyramid
 from ngio.ome_zarr_meta import (
-    ImplementedImageMetaHandlers,
-    ImplementedLabelMetaHandlers,
     NgioImageMeta,
     NgioLabelMeta,
     PixelSize,
+    get_image_meta_handler,
+    get_label_meta_handler,
 )
 from ngio.ome_zarr_meta.ngio_specs import (
     SpaceUnits,
@@ -17,19 +17,19 @@ from ngio.ome_zarr_meta.ngio_specs import (
     canonical_axes_order,
     canonical_label_axes_order,
 )
-from ngio.utils import StoreOrGroup, ZarrGroupHandler
+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],
-    xy_pixelsize: float,
+    pixelsize: float,
     axes_names: Collection[str],
     z_spacing: float = 1.0,
     time_spacing: float = 1.0,
     levels: int | list[str] = 5,
-    xy_scaling_factor: float = 2.0,
+    yx_scaling_factor: float | tuple[float, float] = 2.0,
     z_scaling_factor: float = 1.0,
     space_unit: SpaceUnits | str | None = None,
     time_unit: TimeUnits | str | None = None,
@@ -41,8 +41,16 @@ def _init_generic_meta(
     for ax in axes_names:
         if ax == "z":
             scaling_factors.append(z_scaling_factor)
-        elif ax in ["x", "y"]:
-            scaling_factors.append(xy_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)
 
@@ -51,18 +59,18 @@ def _init_generic_meta(
     elif isinstance(space_unit, str):
         space_unit = SpaceUnits(space_unit)
     elif not isinstance(space_unit, SpaceUnits):
-        raise ValueError(f"space_unit can not be {type(space_unit)}.")
+        raise NgioValueError(f"space_unit can not be {type(space_unit)}.")
 
     if time_unit is None:
         time_unit = TimeUnits.seconds
     elif isinstance(time_unit, str):
         time_unit = TimeUnits(time_unit)
     elif not isinstance(time_unit, TimeUnits):
-        raise ValueError(f"time_units can not be {type(time_unit)}.")
+        raise NgioValueError(f"time_units can not be {type(time_unit)}.")
 
     pixel_sizes = PixelSize(
-        x=xy_pixelsize,
-        y=xy_pixelsize,
+        x=pixelsize,
+        y=pixelsize,
         z=z_spacing,
         t=time_spacing,
         space_unit=space_unit,
@@ -83,11 +91,11 @@ def _init_generic_meta(
 def _create_empty_label(
     store: StoreOrGroup,
     shape: Collection[int],
-    xy_pixelsize: float,
+    pixelsize: float,
     z_spacing: float = 1.0,
     time_spacing: float = 1.0,
     levels: int | list[str] = 5,
-    xy_scaling_factor: float = 2.0,
+    yx_scaling_factor: float | tuple[float, float] = 2.0,
     z_scaling_factor: float = 1.0,
     space_unit: SpaceUnits | str | None = None,
     time_unit: TimeUnits | str | None = None,
@@ -103,13 +111,13 @@ def _create_empty_label(
     Args:
         store (StoreOrGroup): The Zarr store or group to create the image in.
         shape (Collection[int]): The shape of the image.
-        xy_pixelsize (float): The pixel size in x and y dimensions.
+        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.
-        xy_scaling_factor (float, optional): The down-scaling factor in x and y
+        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.
@@ -132,13 +140,19 @@ def _create_empty_label(
     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,
-        xy_pixelsize=xy_pixelsize,
+        pixelsize=pixelsize,
         z_spacing=z_spacing,
         time_spacing=time_spacing,
         levels=levels,
-        xy_scaling_factor=xy_scaling_factor,
+        yx_scaling_factor=yx_scaling_factor,
         z_scaling_factor=z_scaling_factor,
         space_unit=space_unit,
         time_unit=time_unit,
@@ -149,9 +163,7 @@ def _create_empty_label(
 
     mode = "w" if overwrite else "w-"
     group_handler = ZarrGroupHandler(store=store, mode=mode, cache=False)
-    image_handler = ImplementedLabelMetaHandlers().get_handler(
-        version=version, group_handler=group_handler
-    )
+    image_handler = get_label_meta_handler(version=version, group_handler=group_handler)
     image_handler.write_meta(meta)
 
     init_empty_pyramid(
@@ -163,17 +175,18 @@ def _create_empty_label(
         dtype=dtype,
         mode="a",
     )
+    group_handler._mode = "r+"
     return group_handler
 
 
 def _create_empty_image(
     store: StoreOrGroup,
     shape: Collection[int],
-    xy_pixelsize: float,
+    pixelsize: float,
     z_spacing: float = 1.0,
     time_spacing: float = 1.0,
     levels: int | list[str] = 5,
-    xy_scaling_factor: float = 2,
+    yx_scaling_factor: float | tuple[float, float] = 2,
     z_scaling_factor: float = 1.0,
     space_unit: SpaceUnits | str | None = None,
     time_unit: TimeUnits | str | None = None,
@@ -189,13 +202,13 @@ def _create_empty_image(
     Args:
         store (StoreOrGroup): The Zarr store or group to create the image in.
         shape (Collection[int]): The shape of the image.
-        xy_pixelsize (float): The pixel size in x and y dimensions.
+        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.
-        xy_scaling_factor (float, optional): The down-scaling factor in x and y
+        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.
@@ -218,13 +231,19 @@ def _create_empty_image(
     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,
-        xy_pixelsize=xy_pixelsize,
+        pixelsize=pixelsize,
         z_spacing=z_spacing,
         time_spacing=time_spacing,
         levels=levels,
-        xy_scaling_factor=xy_scaling_factor,
+        yx_scaling_factor=yx_scaling_factor,
         z_scaling_factor=z_scaling_factor,
         space_unit=space_unit,
         time_unit=time_unit,
@@ -234,9 +253,7 @@ def _create_empty_image(
     )
     mode = "w" if overwrite else "w-"
     group_handler = ZarrGroupHandler(store=store, mode=mode, cache=False)
-    image_handler = ImplementedImageMetaHandlers().get_handler(
-        version=version, group_handler=group_handler
-    )
+    image_handler = get_image_meta_handler(version=version, group_handler=group_handler)
     image_handler.write_meta(meta)
 
     init_empty_pyramid(
@@ -248,4 +265,6 @@ def _create_empty_image(
         dtype=dtype,
         mode="a",
     )
+
+    group_handler._mode = "r+"
     return group_handler

ngio/images/image.py

@@ -10,9 +10,9 @@ from ngio.images.abstract_image import AbstractImage, consolidate_image
 from ngio.images.create import _create_empty_image
 from ngio.ome_zarr_meta import (
     ImageMetaHandler,
-    ImplementedImageMetaHandlers,
     NgioImageMeta,
     PixelSize,
+    find_image_meta_handler,
 )
 from ngio.ome_zarr_meta.ngio_specs import Channel, ChannelsMeta, ChannelVisualisation
 from ngio.utils import (
@@ -60,9 +60,7 @@ class Image(AbstractImage[ImageMetaHandler]):
 
         """
         if meta_handler is None:
-            meta_handler = ImplementedImageMetaHandlers().find_meta_handler(
-                group_handler
-            )
+            meta_handler = find_image_meta_handler(group_handler)
         super().__init__(
             group_handler=group_handler, path=path, meta_handler=meta_handler
         )
@@ -109,9 +107,7 @@ class ImagesContainer:
     def __init__(self, group_handler: ZarrGroupHandler) -> None:
         """Initialize the LabelGroupHandler."""
         self._group_handler = group_handler
-        self._meta_handler = ImplementedImageMetaHandlers().find_meta_handler(
-            group_handler
-        )
+        self._meta_handler = find_image_meta_handler(group_handler)
 
     @property
     def meta(self) -> NgioImageMeta:
@@ -170,17 +166,20 @@ class ImagesContainer:
                 be shown by default.
             omero_kwargs(dict): Extra fields to store in the omero attributes.
         """
-        ref = self.get()
+        low_res_dataset = self.meta.get_lowest_resolution_dataset()
+        ref_image = self.get(path=low_res_dataset.path)
 
         if percentiles is not None:
             start, end = compute_image_percentile(
-                ref, start_percentile=percentiles[0], end_percentile=percentiles[1]
+                ref_image,
+                start_percentile=percentiles[0],
+                end_percentile=percentiles[1],
             )
         else:
             start, end = None, None
 
         if labels is None:
-            labels = ref.num_channels
+            labels = ref_image.num_channels
 
         channel_meta = ChannelsMeta.default_init(
             labels=labels,
@@ -189,7 +188,7 @@ class ImagesContainer:
             start=start,
             end=end,
             active=active,
-            data_type=ref.dtype,
+            data_type=ref_image.dtype,
             **omero_kwargs,
         )
 
@@ -206,9 +205,10 @@ class ImagesContainer:
         if self.meta._channels_meta is None:
             raise NgioValidationError("The channels meta is not initialized.")
 
-        image = self.get()
+        low_res_dataset = self.meta.get_lowest_resolution_dataset()
+        ref_image = self.get(path=low_res_dataset.path)
         starts, ends = compute_image_percentile(
-            image, start_percentile=start_percentile, end_percentile=end_percentile
+            ref_image, start_percentile=start_percentile, end_percentile=end_percentile
         )
 
         channels = []
@@ -235,20 +235,40 @@ class ImagesContainer:
         store: StoreOrGroup,
         ref_path: str | None = None,
         shape: Collection[int] | None = None,
+        labels: Collection[str] | None = None,
+        pixel_size: PixelSize | None = None,
+        axes_names: Collection[str] | None = None,
         chunks: Collection[int] | None = None,
-        xy_scaling_factor: float = 2.0,
-        z_scaling_factor: float = 1.0,
+        dtype: str | None = None,
         overwrite: bool = False,
     ) -> "ImagesContainer":
-        """Create an OME-Zarr image from a numpy array."""
+        """Create an empty OME-Zarr image from an existing image.
+
+        Args:
+            store (StoreOrGroup): The Zarr store or group to create the image in.
+            ref_path (str | None): The path to the reference image in
+                the image container.
+            shape (Collection[int] | None): The shape of the new image.
+            labels (Collection[str] | None): The labels of the new image.
+            pixel_size (PixelSize | None): The pixel size of the new image.
+            axes_names (Collection[str] | None): The axes names of the new image.
+            chunks (Collection[int] | None): The chunk shape of the new image.
+            dtype (str | None): The data type of the new image.
+            overwrite (bool): Whether to overwrite an existing image.
+
+        Returns:
+            ImagesContainer: The new image
+        """
         return derive_image_container(
             image_container=self,
             store=store,
             ref_path=ref_path,
             shape=shape,
+            labels=labels,
+            pixel_size=pixel_size,
+            axes_names=axes_names,
             chunks=chunks,
-            xy_scaling_factor=xy_scaling_factor,
-            z_scaling_factor=z_scaling_factor,
+            dtype=dtype,
             overwrite=overwrite,
         )
 
@@ -256,13 +276,20 @@ class ImagesContainer:
         self,
         path: str | None = None,
         pixel_size: PixelSize | None = None,
-        highest_resolution: bool = True,
+        strict: bool = False,
     ) -> Image:
-        """Get an image at a specific level."""
-        if path is not None or pixel_size is not None:
-            highest_resolution = False
+        """Get an image at a specific level.
+
+        Args:
+            path (str | None): The path to the image in the omezarr file.
+            pixel_size (PixelSize | None): The pixel size of the image.
+            strict (bool): Only used if the pixel size is provided. If True, the
+                pixel size must match the image pixel size exactly. If False, the
+                closest pixel size level will be returned.
+
+        """
         dataset = self._meta_handler.meta.get_dataset(
-            path=path, pixel_size=pixel_size, highest_resolution=highest_resolution
+            path=path, pixel_size=pixel_size, strict=strict
         )
         return Image(
             group_handler=self._group_handler,
@@ -308,7 +335,6 @@ def compute_image_percentile(
 
         starts.append(float(_s_perc))
         ends.append(float(_e_perc))
-
     return starts, ends
 
 
@@ -317,12 +343,31 @@ def derive_image_container(
     store: StoreOrGroup,
     ref_path: str | None = None,
     shape: Collection[int] | None = None,
+    labels: Collection[str] | None = None,
+    pixel_size: PixelSize | None = None,
+    axes_names: Collection[str] | None = None,
     chunks: Collection[int] | None = None,
-    xy_scaling_factor: float = 2.0,
-    z_scaling_factor: float = 1.0,
+    dtype: str | None = None,
     overwrite: bool = False,
 ) -> ImagesContainer:
-    """Create an OME-Zarr image from a numpy array."""
+    """Create an empty OME-Zarr image from an existing image.
+
+    Args:
+        image_container (ImagesContainer): The image container to derive the new image.
+        store (StoreOrGroup): The Zarr store or group to create the image in.
+        ref_path (str | None): The path to the reference image in the image container.
+        shape (Collection[int] | None): The shape of the new image.
+        labels (Collection[str] | None): The labels of the new image.
+        pixel_size (PixelSize | None): The pixel size of the new image.
+        axes_names (Collection[str] | None): The axes names of the new image.
+        chunks (Collection[int] | None): The chunk shape of the new image.
+        dtype (str | None): The data type of the new image.
+        overwrite (bool): Whether to overwrite an existing image.
+
+    Returns:
+        ImagesContainer: The new image
+
+    """
     if ref_path is None:
         ref_image = image_container.get()
     else:
@@ -332,58 +377,77 @@ def derive_image_container(
 
     if shape is None:
         shape = ref_image.shape
-    else:
-        if len(shape) != len(ref_image.shape):
-            raise NgioValidationError(
-                "The shape of the new image does not match the reference image."
-            )
+
+    if pixel_size is None:
+        pixel_size = ref_image.pixel_size
+
+    if axes_names is None:
+        axes_names = ref_meta.axes_mapper.on_disk_axes_names
+
+    if len(axes_names) != len(shape):
+        raise NgioValidationError(
+            "The axes names of the new image does not match the reference image."
+            f"Got {axes_names} for shape {shape}."
+        )
 
     if chunks is None:
         chunks = ref_image.chunks
-    else:
-        if len(chunks) != len(ref_image.chunks):
-            raise NgioValidationError(
-                "The chunks of the new image does not match the reference image."
-            )
 
+    if len(chunks) != len(shape):
+        raise NgioValidationError(
+            "The chunks of the new image does not match the reference image."
+            f"Got {chunks} for shape {shape}."
+        )
+
+    if dtype is None:
+        dtype = ref_image.dtype
     handler = _create_empty_image(
         store=store,
         shape=shape,
-        xy_pixelsize=ref_image.pixel_size.x,
-        z_spacing=ref_image.pixel_size.z,
-        time_spacing=ref_image.pixel_size.t,
+        pixelsize=pixel_size.x,
+        z_spacing=pixel_size.z,
+        time_spacing=pixel_size.t,
         levels=ref_meta.levels,
-        xy_scaling_factor=xy_scaling_factor,
-        z_scaling_factor=z_scaling_factor,
-        time_unit=ref_image.pixel_size.time_unit,
-        space_unit=ref_image.pixel_size.space_unit,
-        axes_names=ref_image.dataset.axes_mapper.on_disk_axes_names,
+        yx_scaling_factor=ref_meta.yx_scaling(),
+        z_scaling_factor=ref_meta.z_scaling(),
+        time_unit=pixel_size.time_unit,
+        space_unit=pixel_size.space_unit,
+        axes_names=axes_names,
         chunks=chunks,
-        dtype=ref_image.dtype,
+        dtype=dtype,
         overwrite=overwrite,
         version=ref_meta.version,
     )
-
     image_container = ImagesContainer(handler)
 
     if ref_image.num_channels == image_container.num_channels:
-        labels = ref_image.channel_labels
+        _labels = ref_image.channel_labels
         wavelength_id = ref_image.wavelength_ids
+
         colors = [
             c.channel_visualisation.color for c in ref_image._channels_meta.channels
         ]
         active = [
             c.channel_visualisation.active for c in ref_image._channels_meta.channels
         ]
-
-        image_container.initialize_channel_meta(
-            labels=labels,
-            wavelength_id=wavelength_id,
-            percentiles=None,
-            colors=colors,
-            active=active,
-        )
     else:
-        image_container.initialize_channel_meta()
+        _labels = None
+        wavelength_id = None
+        colors = None
+        active = None
 
+    if labels is not None:
+        if len(labels) != image_container.num_channels:
+            raise NgioValidationError(
+                "The number of labels does not match the number of channels."
+            )
+        _labels = labels
+
+    image_container.initialize_channel_meta(
+        labels=_labels,
+        wavelength_id=wavelength_id,
+        percentiles=None,
+        colors=colors,
+        active=active,
+    )
     return image_container