ngio 0.3.4__py3-none-any.whl → 0.4.0__py3-none-any.whl

ngio/images/_ome_zarr_container.py

@@ -1,18 +1,16 @@
 """Abstract class for handling OME-NGFF images."""
 
 import warnings
-from collections.abc import Collection
+from collections.abc import Sequence
 
 import numpy as np
+from zarr.types import DIMENSION_SEPARATOR
 
 from ngio.images._create import create_empty_image_container
 from ngio.images._image import Image, ImagesContainer
 from ngio.images._label import Label, LabelsContainer
 from ngio.images._masked_image import MaskedImage, MaskedLabel
-from ngio.ome_zarr_meta import (
-    NgioImageMeta,
-    PixelSize,
-)
+from ngio.ome_zarr_meta import NgioImageMeta, PixelSize, find_label_meta_handler
 from ngio.ome_zarr_meta.ngio_specs import (
     DefaultNgffVersion,
     DefaultSpaceUnit,
@@ -58,7 +56,21 @@ def _default_label_container(handler: ZarrGroupHandler) -> LabelsContainer | Non
 
 
 class OmeZarrContainer:
-    """This class contains an OME-Zarr image and its associated tables and labels."""
+    """This class is an object representation of an OME-Zarr image.
+
+    It provides methods to access:
+        - The multiscale image metadata
+        - To open images at different levels of resolution
+        - To access labels and tables associated with the image.
+        - To derive new images, labels, and add tables to the image.
+        - To modify the image metadata, such as axes units and channel metadata.
+
+    Attributes:
+        images_container (ImagesContainer): The container for the images.
+        labels_container (LabelsContainer): The container for the labels.
+        tables_container (TablesContainer): The container for the tables.
+
+    """
 
     _images_container: ImagesContainer
     _labels_container: LabelsContainer | None
@@ -71,7 +83,14 @@ class OmeZarrContainer:
         label_container: LabelsContainer | None = None,
         validate_paths: bool = False,
     ) -> None:
-        """Initialize the OmeZarrContainer."""
+        """Initialize the OmeZarrContainer.
+
+        Args:
+            group_handler (ZarrGroupHandler): The Zarr group handler.
+            table_container (TablesContainer | None): The tables container.
+            label_container (LabelsContainer | None): The labels container.
+            validate_paths (bool): Whether to validate the paths of the image multiscale
+        """
         self._group_handler = group_handler
         self._images_container = ImagesContainer(self._group_handler)
 
@@ -101,7 +120,11 @@ class OmeZarrContainer:
 
     @property
     def images_container(self) -> ImagesContainer:
-        """Return the image container."""
+        """Return the images container.
+
+        Returns:
+            ImagesContainer: The images container.
+        """
         return self._images_container
 
     def _get_labels_container(self) -> LabelsContainer | None:
@@ -193,19 +216,47 @@ class OmeZarrContainer:
         """Return the time unit of the image."""
         return self.image_meta.time_unit
 
+    @property
+    def channel_labels(self) -> list[str]:
+        """Return the channels of the image."""
+        image = self.get_image()
+        return image.channel_labels
+
+    @property
+    def wavelength_ids(self) -> list[str | None]:
+        """Return the list of wavelength of the image."""
+        image = self.get_image()
+        return image.wavelength_ids
+
+    @property
+    def num_channels(self) -> int:
+        """Return the number of channels."""
+        return len(self.channel_labels)
+
+    def get_channel_idx(
+        self, channel_label: str | None = None, wavelength_id: str | None = None
+    ) -> int:
+        """Get the index of a channel by its label or wavelength ID."""
+        image = self.get_image()
+        return image.channels_meta.get_channel_idx(
+            channel_label=channel_label, wavelength_id=wavelength_id
+        )
+
     def set_channel_meta(
         self,
-        labels: Collection[str] | int | None = None,
-        wavelength_id: Collection[str] | None = None,
+        labels: Sequence[str] | int | None = None,
+        wavelength_id: Sequence[str] | None = None,
         percentiles: tuple[float, float] | None = None,
-        colors: Collection[str] | None = None,
-        active: Collection[bool] | None = None,
+        colors: Sequence[str] | None = None,
+        active: Sequence[bool] | None = None,
         **omero_kwargs: dict,
     ) -> None:
         """Create a ChannelsMeta object with the default unit."""
         self._images_container.set_channel_meta(
             labels=labels,
             wavelength_id=wavelength_id,
+            start=None,
+            end=None,
             percentiles=percentiles,
             colors=colors,
             active=active,
@@ -262,9 +313,57 @@ class OmeZarrContainer:
             path=path, pixel_size=pixel_size, strict=strict
         )
 
+    def _find_matching_masking_label(
+        self,
+        masking_label_name: str | None = None,
+        masking_table_name: str | None = None,
+        pixel_size: PixelSize | None = None,
+    ) -> tuple[Label, MaskingRoiTable]:
+        if masking_label_name is not None and masking_table_name is not None:
+            # Both provided
+            masking_label = self.get_label(
+                name=masking_label_name, pixel_size=pixel_size, strict=False
+            )
+            masking_table = self.get_masking_roi_table(name=masking_table_name)
+
+        elif masking_label_name is not None and masking_table_name is None:
+            # Only the label provided
+            masking_label = self.get_label(
+                name=masking_label_name, pixel_size=pixel_size, strict=False
+            )
+
+            for table_name in self.list_roi_tables():
+                table = self.get_generic_roi_table(name=table_name)
+                if isinstance(table, MaskingRoiTable):
+                    if table.reference_label == masking_label_name:
+                        masking_table = table
+                        break
+            else:
+                masking_table = masking_label.build_masking_roi_table()
+
+        elif masking_table_name is not None and masking_label_name is None:
+            # Only the table provided
+            masking_table = self.get_masking_roi_table(name=masking_table_name)
+
+            if masking_table.reference_label is None:
+                raise NgioValueError(
+                    f"Masking table {masking_table_name} does not have a reference "
+                    "label. Please provide the masking_label_name explicitly."
+                )
+            masking_label = self.get_label(
+                name=masking_table.reference_label,
+                pixel_size=pixel_size,
+                strict=False,
+            )
+        else:
+            raise NgioValueError(
+                "Neither masking_label_name nor masking_table_name were provided."
+            )
+        return masking_label, masking_table
+
     def get_masked_image(
         self,
-        masking_label_name: str,
+        masking_label_name: str | None = None,
         masking_table_name: str | None = None,
         path: str | None = None,
         pixel_size: PixelSize | None = None,
@@ -273,26 +372,27 @@ class OmeZarrContainer:
         """Get a masked image at a specific level.
 
         Args:
-            masking_label_name (str): The name of the label.
-            masking_table_name (str | None): The name of the masking table.
+            masking_label_name (str | None): The name of the masking label to use.
+                If None, the masking table must be provided.
+            masking_table_name (str | None): The name of the masking table to use.
+                If None, the masking label must be provided.
             path (str | None): The path to the image in the ome_zarr file.
+                If None, the first level will be used.
             pixel_size (PixelSize | None): The pixel size of the image.
+                This is only used if path is None.
             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.
         """
         image = self.get_image(path=path, pixel_size=pixel_size, strict=strict)
-        masking_label = self.get_label(
-            name=masking_label_name, path=path, pixel_size=pixel_size, strict=strict
+        masking_label, masking_table = self._find_matching_masking_label(
+            masking_label_name=masking_label_name,
+            masking_table_name=masking_table_name,
+            pixel_size=pixel_size,
         )
-        if masking_table_name is None:
-            masking_table = masking_label.build_masking_roi_table()
-        else:
-            masking_table = self.get_masking_roi_table(name=masking_table_name)
-
         return MaskedImage(
             group_handler=image._group_handler,
-            path=masking_label.path,
+            path=image.path,
             meta_handler=image.meta_handler,
             label=masking_label,
             masking_roi_table=masking_table,
@@ -302,13 +402,15 @@ class OmeZarrContainer:
         self,
         store: StoreOrGroup,
         ref_path: str | None = None,
-        shape: Collection[int] | None = None,
-        labels: Collection[str] | None = None,
+        shape: Sequence[int] | None = None,
+        labels: Sequence[str] | None = None,
         pixel_size: PixelSize | None = None,
-        axes_names: Collection[str] | None = None,
+        axes_names: Sequence[str] | None = None,
         name: str | None = None,
-        chunks: Collection[int] | None = None,
+        chunks: Sequence[int] | None = None,
         dtype: str | None = None,
+        dimension_separator: DIMENSION_SEPARATOR | None = None,
+        compressor=None,
         copy_labels: bool = False,
         copy_tables: bool = False,
         overwrite: bool = False,
@@ -319,13 +421,18 @@ class OmeZarrContainer:
             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.
+            shape (Sequence[int] | None): The shape of the new image.
+            labels (Sequence[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.
+            axes_names (Sequence[str] | None): The axes names of the new image.
+            chunks (Sequence[int] | None): The chunk shape of the new image.
             dtype (str | None): The data type of the new image.
             name (str | None): The name of the new image.
+            dimension_separator (DIMENSION_SEPARATOR | None): The dimension
+                separator to use. If None, the dimension separator of the
+                reference image will be used.
+            compressor: The compressor to use. If None, the compressor of the
+                reference image will be used.
             copy_labels (bool): Whether to copy the labels from the reference image.
             copy_tables (bool): Whether to copy the tables from the reference image.
             overwrite (bool): Whether to overwrite an existing image.
@@ -344,6 +451,8 @@ class OmeZarrContainer:
             name=name,
             chunks=chunks,
             dtype=dtype,
+            dimension_separator=dimension_separator,
+            compressor=compressor,
             overwrite=overwrite,
         )
 
@@ -490,7 +599,7 @@ class OmeZarrContainer:
             backend=backend,
         )
 
-    def build_image_roi_table(self, name: str = "image") -> RoiTable:
+    def build_image_roi_table(self, name: str | None = "image") -> RoiTable:
         """Compute the ROI table for an image."""
         return self.get_image().build_image_roi_table(name=name)
 
@@ -541,7 +650,7 @@ class OmeZarrContainer:
     def get_masked_label(
         self,
         label_name: str,
-        masking_label_name: str,
+        masking_label_name: str | None = None,
         masking_table_name: str | None = None,
         path: str | None = None,
         pixel_size: PixelSize | None = None,
@@ -551,7 +660,7 @@ class OmeZarrContainer:
 
         Args:
             label_name (str): The name of the label.
-            masking_label_name (str): The name of the masking label.
+            masking_label_name (str | None): The name of the masking label.
             masking_table_name (str | None): The name of the masking table.
             path (str | None): The path to the image in the ome_zarr file.
             pixel_size (PixelSize | None): The pixel size of the image.
@@ -562,14 +671,11 @@ class OmeZarrContainer:
         label = self.get_label(
             name=label_name, path=path, pixel_size=pixel_size, strict=strict
         )
-        masking_label = self.get_label(
-            name=masking_label_name, path=path, pixel_size=pixel_size, strict=strict
+        masking_label, masking_table = self._find_matching_masking_label(
+            masking_label_name=masking_label_name,
+            masking_table_name=masking_table_name,
+            pixel_size=pixel_size,
         )
-        if masking_table_name is None:
-            masking_table = masking_label.build_masking_roi_table()
-        else:
-            masking_table = self.get_masking_roi_table(name=masking_table_name)
-
         return MaskedLabel(
             group_handler=label._group_handler,
             path=label.path,
@@ -582,11 +688,13 @@ class OmeZarrContainer:
         self,
         name: str,
         ref_image: Image | Label | None = None,
-        shape: Collection[int] | None = None,
+        shape: Sequence[int] | None = None,
         pixel_size: PixelSize | None = None,
-        axes_names: Collection[str] | None = None,
-        chunks: Collection[int] | None = None,
-        dtype: str | None = None,
+        axes_names: Sequence[str] | None = None,
+        chunks: Sequence[int] | None = None,
+        dtype: str = "uint32",
+        dimension_separator: DIMENSION_SEPARATOR | None = None,
+        compressor=None,
         overwrite: bool = False,
     ) -> "Label":
         """Create an empty OME-Zarr label from a reference image.
@@ -597,12 +705,17 @@ class OmeZarrContainer:
             name (str): The name of the new image.
             ref_image (Image | Label | None): A reference image that will be used
                 to create the new image.
-            shape (Collection[int] | None): The shape of the new image.
+            shape (Sequence[int] | None): The shape 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.
+            axes_names (Sequence[str] | None): The axes names of the new image.
                 For labels, the channel axis is not allowed.
-            chunks (Collection[int] | None): The chunk shape of the new image.
-            dtype (str | None): The data type of the new image.
+            chunks (Sequence[int] | None): The chunk shape of the new image.
+            dtype (str): The data type of the new label.
+            dimension_separator (DIMENSION_SEPARATOR | None): The dimension
+                separator to use. If None, the dimension separator of the
+                reference image will be used.
+            compressor: The compressor to use. If None, the compressor of the
+                reference image will be used.
             overwrite (bool): Whether to overwrite an existing image.
 
         Returns:
@@ -619,6 +732,8 @@ class OmeZarrContainer:
             axes_names=axes_names,
             chunks=chunks,
             dtype=dtype,
+            dimension_separator=dimension_separator,
+            compressor=compressor,
             overwrite=overwrite,
         )
 
@@ -667,9 +782,50 @@ def open_image(
     )
 
 
+def open_label(
+    store: StoreOrGroup,
+    name: str | None = None,
+    path: str | None = None,
+    pixel_size: PixelSize | None = None,
+    strict: bool = True,
+    cache: bool = False,
+    mode: AccessModeLiteral = "r+",
+) -> Label:
+    """Open a single level label from an OME-Zarr Label group.
+
+    Args:
+        store (StoreOrGroup): The Zarr store or group to create the image in.
+        name (str | None): The name of the label. If None,
+            we will try to open the store as a multiscale label.
+        path (str | None): The path to the image in the ome_zarr 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.
+        cache (bool): Whether to use a cache for the zarr group metadata.
+        mode (AccessModeLiteral): The access mode for the image. Defaults to "r+".
+
+    """
+    group_handler = ZarrGroupHandler(store, cache, mode)
+    if name is None:
+        label_meta_handler = find_label_meta_handler(group_handler)
+        path = label_meta_handler.meta.get_dataset(
+            path=path, pixel_size=pixel_size, strict=strict
+        ).path
+        return Label(group_handler, path, label_meta_handler)
+
+    labels_container = LabelsContainer(group_handler)
+    return labels_container.get(
+        name=name,
+        path=path,
+        pixel_size=pixel_size,
+        strict=strict,
+    )
+
+
 def create_empty_ome_zarr(
     store: StoreOrGroup,
-    shape: Collection[int],
+    shape: Sequence[int],
     xy_pixelsize: float,
     z_spacing: float = 1.0,
     time_spacing: float = 1.0,
@@ -678,14 +834,16 @@ def create_empty_ome_zarr(
     z_scaling_factor: float = 1.0,
     space_unit: SpaceUnits = DefaultSpaceUnit,
     time_unit: TimeUnits = DefaultTimeUnit,
-    axes_names: Collection[str] | None = None,
+    axes_names: Sequence[str] | None = None,
     name: str | None = None,
-    chunks: Collection[int] | None = None,
+    chunks: Sequence[int] | None = None,
     dtype: str = "uint16",
+    dimension_separator: DIMENSION_SEPARATOR = "/",
+    compressor="default",
     channel_labels: list[str] | None = None,
     channel_wavelengths: list[str] | None = None,
-    channel_colors: Collection[str] | None = None,
-    channel_active: Collection[bool] | None = None,
+    channel_colors: Sequence[str] | None = None,
+    channel_active: Sequence[bool] | None = None,
     overwrite: bool = False,
     version: NgffVersions = DefaultNgffVersion,
 ) -> OmeZarrContainer:
@@ -693,7 +851,7 @@ def create_empty_ome_zarr(
 
     Args:
         store (StoreOrGroup): The Zarr store or group to create the image in.
-        shape (Collection[int]): The shape of the image.
+        shape (Sequence[int]): The shape of the image.
         xy_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.
@@ -708,19 +866,22 @@ def create_empty_ome_zarr(
             DefaultSpaceUnit.
         time_unit (TimeUnits, optional): The unit of time. Defaults to
             DefaultTimeUnit.
-        axes_names (Collection[str] | None, optional): The names of the axes.
+        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 (Collection[int] | None, optional): The chunk shape. If None the shape
+        chunks (Sequence[int] | None, optional): 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 dimension
+            separator to use. Defaults to "/".
+        compressor: The compressor to use. Defaults to "default".
         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 (Collection[str] | None, optional): The colors of the channels.
+        channel_colors (Sequence[str] | None, optional): The colors of the channels.
             Defaults to None.
-        channel_active (Collection[bool] | None, optional): Whether the channels are
+        channel_active (Sequence[bool] | None, optional): Whether the channels are
             active. Defaults to None.
         overwrite (bool, optional): Whether to overwrite an existing image.
             Defaults to True.
@@ -742,6 +903,8 @@ def create_empty_ome_zarr(
         name=name,
         chunks=chunks,
         dtype=dtype,
+        dimension_separator=dimension_separator,
+        compressor=compressor,
         overwrite=overwrite,
         version=version,
     )
@@ -768,14 +931,16 @@ def create_ome_zarr_from_array(
     z_scaling_factor: float = 1.0,
     space_unit: SpaceUnits = DefaultSpaceUnit,
     time_unit: TimeUnits = DefaultTimeUnit,
-    axes_names: Collection[str] | None = None,
+    axes_names: Sequence[str] | None = None,
     channel_labels: list[str] | None = None,
     channel_wavelengths: list[str] | None = None,
     percentiles: tuple[float, float] | None = (0.1, 99.9),
-    channel_colors: Collection[str] | None = None,
-    channel_active: Collection[bool] | None = None,
+    channel_colors: Sequence[str] | None = None,
+    channel_active: Sequence[bool] | None = None,
     name: str | None = None,
-    chunks: Collection[int] | None = None,
+    chunks: Sequence[int] | None = None,
+    dimension_separator: DIMENSION_SEPARATOR = "/",
+    compressor: str = "default",
     overwrite: bool = False,
     version: NgffVersions = DefaultNgffVersion,
 ) -> OmeZarrContainer:
@@ -798,10 +963,10 @@ def create_ome_zarr_from_array(
             DefaultSpaceUnit.
         time_unit (TimeUnits, optional): The unit of time. Defaults to
             DefaultTimeUnit.
-        axes_names (Collection[str] | None, optional): The names of the axes.
+        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 (Collection[int] | None, optional): The chunk shape. If None the shape
+        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.
@@ -809,10 +974,13 @@ def create_ome_zarr_from_array(
             channels. Defaults to None.
         percentiles (tuple[float, float] | None, optional): The percentiles of the
             channels. Defaults to None.
-        channel_colors (Collection[str] | None, optional): The colors of the channels.
+        channel_colors (Sequence[str] | None, optional): The colors of the channels.
             Defaults to None.
-        channel_active (Collection[bool] | None, optional): Whether the channels are
+        channel_active (Sequence[bool] | None, optional): Whether the channels are
             active. Defaults to None.
+        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 (str, optional): The version of the OME-Zarr specification.
@@ -834,6 +1002,8 @@ def create_ome_zarr_from_array(
         chunks=chunks,
         dtype=str(array.dtype),
         overwrite=overwrite,
+        dimension_separator=dimension_separator,
+        compressor=compressor,
         version=version,
     )