ngio 0.5.0b7__py3-none-any.whl → 0.5.1__py3-none-any.whl

ngio/images/_ome_zarr_container.py

@@ -1,6 +1,6 @@
 """Abstract class for handling OME-NGFF images."""
 
-import warnings
+import logging
 from collections.abc import Mapping, Sequence
 from typing import Any, Literal
 
@@ -26,6 +26,8 @@ from ngio.ome_zarr_meta.ngio_specs import (
     SpaceUnits,
     TimeUnits,
 )
+from ngio.ome_zarr_meta.ngio_specs._axes import AxesSetup
+from ngio.ome_zarr_meta.ngio_specs._channels import ChannelsMeta
 from ngio.tables import (
     ConditionTable,
     DefaultTableBackend,
@@ -48,6 +50,8 @@ from ngio.utils import (
     ZarrGroupHandler,
 )
 
+logger = logging.getLogger(f"ngio:{__name__}")
+
 
 def _try_get_table_container(
     handler: ZarrGroupHandler, create_mode: bool = True
@@ -61,12 +65,19 @@ def _try_get_table_container(
 
 
 def _try_get_label_container(
-    handler: ZarrGroupHandler, ngff_version: NgffVersions, create_mode: bool = True
+    handler: ZarrGroupHandler,
+    ngff_version: NgffVersions,
+    axes_setup: AxesSetup | None = None,
+    create_mode: bool = True,
 ) -> LabelsContainer | None:
     """Return a default label container."""
     try:
         label_handler = handler.get_handler("labels", create_mode=create_mode)
-        return LabelsContainer(label_handler, ngff_version=ngff_version)
+        return LabelsContainer(
+            group_handler=label_handler,
+            axes_setup=axes_setup,
+            ngff_version=ngff_version,
+        )
     except FileNotFoundError:
         return None
 
@@ -97,6 +108,7 @@ class OmeZarrContainer:
         group_handler: ZarrGroupHandler,
         table_container: TablesContainer | None = None,
         label_container: LabelsContainer | None = None,
+        axes_setup: AxesSetup | None = None,
         validate_paths: bool = False,
     ) -> None:
         """Initialize the OmeZarrContainer.
@@ -105,16 +117,19 @@ class OmeZarrContainer:
             group_handler (ZarrGroupHandler): The Zarr group handler.
             table_container (TablesContainer | None): The tables container.
             label_container (LabelsContainer | None): The labels container.
+            axes_setup (AxesSetup | None): Axes setup to load ome-zarr with
+                non-standard axes configurations.
             validate_paths (bool): Whether to validate the paths of the image multiscale
         """
         self._group_handler = group_handler
-        self._images_container = ImagesContainer(self._group_handler)
-
+        self._images_container = ImagesContainer(
+            self._group_handler, axes_setup=axes_setup
+        )
         self._labels_container = label_container
         self._tables_container = table_container
 
         if validate_paths:
-            for level_path in self._images_container.levels_paths:
+            for level_path in self._images_container.level_paths:
                 self.get_image(path=level_path)
 
     def __repr__(self) -> str:
@@ -151,7 +166,8 @@ class OmeZarrContainer:
         _labels_container = _try_get_label_container(
             self._group_handler,
             create_mode=create_mode,
-            ngff_version=self.image_meta.version,
+            ngff_version=self.meta.version,
+            axes_setup=self._images_container.axes_setup,
         )
         self._labels_container = _labels_container
         return self._labels_container
@@ -183,116 +199,232 @@ class OmeZarrContainer:
             raise NgioValidationError("No tables found in the image.")
         return _tables_container
 
+    @property
+    def meta(self) -> NgioImageMeta:
+        """Return the image metadata."""
+        return self.images_container.meta
+
     @property
     def image_meta(self) -> NgioImageMeta:
         """Return the image metadata."""
-        return self._images_container.meta
+        logger.warning(
+            "'image_meta' is deprecated and will be removed in ngio=0.6. "
+            "Please use 'meta' instead."
+        )
+        return self.images_container.meta
+
+    @property
+    def axes_setup(self) -> AxesSetup:
+        """Return the axes setup."""
+        return self.images_container.axes_setup
 
     @property
     def levels(self) -> int:
         """Return the number of levels in the image."""
-        return self._images_container.levels
+        return self.images_container.levels
 
     @property
-    def levels_paths(self) -> list[str]:
+    def level_paths(self) -> list[str]:
         """Return the paths of the levels in the image."""
-        return self._images_container.levels_paths
+        return self.images_container.level_paths
+
+    @property
+    def levels_paths(self) -> list[str]:
+        """Deprecated: use 'level_paths' instead."""
+        logger.warning(
+            "'levels_paths' is deprecated and will be removed in ngio=0.6. "
+            "Please use 'level_paths' instead."
+        )
+        return self.images_container.level_paths
 
     @property
     def is_3d(self) -> bool:
         """Return True if the image is 3D."""
-        return self.get_image().is_3d
+        return self.images_container.is_3d
 
     @property
     def is_2d(self) -> bool:
         """Return True if the image is 2D."""
-        return self.get_image().is_2d
+        return self.images_container.is_2d
 
     @property
     def is_time_series(self) -> bool:
         """Return True if the image is a time series."""
-        return self.get_image().is_time_series
+        return self.images_container.is_time_series
 
     @property
     def is_2d_time_series(self) -> bool:
         """Return True if the image is a 2D time series."""
-        return self.get_image().is_2d_time_series
+        return self.images_container.is_2d_time_series
 
     @property
     def is_3d_time_series(self) -> bool:
         """Return True if the image is a 3D time series."""
-        return self.get_image().is_3d_time_series
+        return self.images_container.is_3d_time_series
 
     @property
     def is_multi_channels(self) -> bool:
         """Return True if the image is multichannel."""
-        return self.get_image().is_multi_channels
+        return self.images_container.is_multi_channels
 
     @property
     def space_unit(self) -> str | None:
         """Return the space unit of the image."""
-        return self.image_meta.space_unit
+        return self.images_container.space_unit
 
     @property
     def time_unit(self) -> str | None:
         """Return the time unit of the image."""
-        return self.image_meta.time_unit
+        return self.images_container.time_unit
 
     @property
     def channel_labels(self) -> list[str]:
         """Return the channels of the image."""
-        image = self.get_image()
-        return image.channel_labels
+        return self.images_container.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
+        return self.images_container.wavelength_ids
 
     @property
     def num_channels(self) -> int:
         """Return the number of channels."""
-        return len(self.channel_labels)
+        return self.images_container.num_channels
 
     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(
+        return self.images_container.get_channel_idx(
             channel_label=channel_label, wavelength_id=wavelength_id
         )
 
     def set_channel_meta(
         self,
+        channel_meta: ChannelsMeta | None = None,
         labels: Sequence[str | None] | int | None = None,
         wavelength_id: Sequence[str | None] | None = None,
+        start: Sequence[float | None] | None = None,
+        end: Sequence[float | None] | None = None,
         percentiles: tuple[float, float] | None = None,
-        colors: Sequence[str] | None = None,
-        active: Sequence[bool] | None = None,
+        colors: Sequence[str | None] | None = None,
+        active: Sequence[bool | None] | None = None,
         **omero_kwargs: dict,
     ) -> None:
-        """Create a ChannelsMeta object with the default unit."""
+        """Create a ChannelsMeta object with the default unit.
+
+        Args:
+            channel_meta (ChannelsMeta | None): The channels metadata to set.
+                If none, it will fall back to the deprecated parameters.
+            labels(Sequence[str | None] | int): Deprecated. The list of channels names
+                in the image. If an integer is provided, the channels will
+                be named "channel_i".
+            wavelength_id(Sequence[str | None]): Deprecated. The wavelength ID of the
+                channel. If None, the wavelength ID will be the same as
+                the channel name.
+            start(Sequence[float | None]): Deprecated. The start value for each channel.
+                If None, the start value will be computed from the image.
+            end(Sequence[float | None]): Deprecated. The end value for each channel.
+                If None, the end value will be computed from the image.
+            percentiles(tuple[float, float] | None): Deprecated. The start and end
+                percentiles for each channel. If None, the percentiles will
+                not be computed.
+            colors(Sequence[str | None]): Deprecated. The list of colors for the
+                channels. If None, the colors will be random.
+            active (Sequence[bool | None]): Deprecated. Whether the channel should
+                be shown by default.
+            omero_kwargs(dict): Deprecated. Extra fields to store in the omero
+                attributes.
+        """
         self._images_container.set_channel_meta(
+            channel_meta=channel_meta,
             labels=labels,
             wavelength_id=wavelength_id,
-            start=None,
-            end=None,
+            start=start,
+            end=end,
             percentiles=percentiles,
             colors=colors,
             active=active,
             **omero_kwargs,
         )
 
+    def set_channel_labels(
+        self,
+        labels: Sequence[str],
+    ) -> None:
+        """Update the labels of the channels.
+
+        Args:
+            labels (Sequence[str]): The new labels for the channels.
+        """
+        self._images_container.set_channel_labels(labels=labels)
+
+    def set_channel_colors(
+        self,
+        colors: Sequence[str],
+    ) -> None:
+        """Update the colors of the channels.
+
+        Args:
+            colors (Sequence[str]): The new colors for the channels.
+        """
+        self._images_container.set_channel_colors(colors=colors)
+
     def set_channel_percentiles(
         self,
         start_percentile: float = 0.1,
         end_percentile: float = 99.9,
     ) -> None:
-        """Update the percentiles of the image."""
-        self._images_container.set_channel_percentiles(
-            start_percentile=start_percentile, end_percentile=end_percentile
+        """Deprecated: Update the channel windows using percentiles.
+
+        Args:
+            start_percentile (float): The start percentile.
+            end_percentile (float): The end percentile.
+        """
+        logger.warning(
+            "The 'set_channel_percentiles' method is deprecated and will be removed in "
+            "ngio=0.6. Please use 'set_channel_windows_with_percentiles' instead."
+        )
+        self._images_container.set_channel_windows_with_percentiles(
+            percentiles=(start_percentile, end_percentile)
+        )
+
+    def set_channel_windows(
+        self,
+        starts_ends: Sequence[tuple[float, float]],
+        min_max: Sequence[tuple[float, float]] | None = None,
+    ) -> None:
+        """Update the channel windows.
+
+        These values are used by viewers to set the display
+        range of each channel.
+
+        Args:
+            starts_ends (Sequence[tuple[float, float]]): The start and end values
+                for each channel.
+            min_max (Sequence[tuple[float, float]] | None): The min and max values
+                for each channel. If None, the min and max values will not be updated.
+        """
+        self._images_container.set_channel_windows(
+            starts_ends=starts_ends,
+            min_max=min_max,
+        )
+
+    def set_channel_windows_with_percentiles(
+        self,
+        percentiles: tuple[float, float] | list[tuple[float, float]] = (0.1, 99.9),
+    ) -> None:
+        """Update the channel windows using percentiles.
+
+        Args:
+            percentiles (tuple[float, float] | list[tuple[float, float]]):
+                The start and end percentiles for each channel.
+                If a single tuple is provided,
+                the same percentiles will be used for all channels.
+        """
+        self._images_container.set_channel_windows_with_percentiles(
+            percentiles=percentiles
         )
 
     def set_axes_units(
@@ -308,12 +440,35 @@ class OmeZarrContainer:
             time_unit (TimeUnits): The unit of time.
             set_labels (bool): Whether to set the units for the labels as well.
         """
+        if set_labels:
+            for label_name in self.list_labels():
+                label = self.get_label(label_name)
+                label.set_axes_unit(space_unit=space_unit, time_unit=time_unit)
         self._images_container.set_axes_unit(space_unit=space_unit, time_unit=time_unit)
-        if not set_labels:
-            return
-        for label_name in self.list_labels():
-            label = self.get_label(label_name)
-            label.set_axes_unit(space_unit=space_unit, time_unit=time_unit)
+
+    def set_axes_names(
+        self,
+        axes_names: Sequence[str],
+    ) -> None:
+        """Set the axes names of the image.
+
+        Args:
+            axes_names (Sequence[str]): The axes names of the image.
+        """
+        self._images_container.set_axes_names(axes_names=axes_names)
+
+    def set_name(
+        self,
+        name: str,
+    ) -> None:
+        """Set the name of the image in the metadata.
+
+        This does not change the group name or any paths.
+
+        Args:
+            name (str): The name of the image.
+        """
+        self._images_container.set_name(name=name)
 
     def get_image(
         self,
@@ -520,10 +675,10 @@ class OmeZarrContainer:
             labels=labels,
             pixel_size=pixel_size,
         )
-
         new_ome_zarr = OmeZarrContainer(
             group_handler=new_container._group_handler,
             validate_paths=False,
+            axes_setup=new_container.meta.axes_handler.axes_setup,
         )
 
         if copy_labels:
@@ -631,12 +786,10 @@ class OmeZarrContainer:
 
         """
         if check_type is not None:
-            warnings.warn(
-                "The 'check_type' argument is deprecated, and will be removed in "
-                "ngio=0.3. Use 'get_table_as' instead or one of the "
-                "type specific get_*table() methods.",
-                DeprecationWarning,
-                stacklevel=2,
+            logger.warning(
+                "The 'check_type' argument is deprecated and will be removed in "
+                "ngio=0.6. Please use 'get_table_as' instead or one of the "
+                "type specific get_*table() methods."
             )
         return self.tables_container.get(name=name, strict=False)
 
@@ -878,6 +1031,7 @@ def open_ome_zarr_container(
     store: StoreOrGroup,
     cache: bool = False,
     mode: AccessModeLiteral = "r+",
+    axes_setup: AxesSetup | None = None,
     validate_arrays: bool = True,
 ) -> OmeZarrContainer:
     """Open an OME-Zarr image."""
@@ -885,6 +1039,7 @@ def open_ome_zarr_container(
     return OmeZarrContainer(
         group_handler=handler,
         validate_paths=validate_arrays,
+        axes_setup=axes_setup,
     )
 
 
@@ -893,6 +1048,7 @@ def open_image(
     path: str | None = None,
     pixel_size: PixelSize | None = None,
     strict: bool = True,
+    axes_setup: AxesSetup | None = None,
     cache: bool = False,
     mode: AccessModeLiteral = "r+",
 ) -> Image:
@@ -905,12 +1061,14 @@ def open_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.
+        axes_setup (AxesSetup | None): Axes setup to load ome-zarr with
+            non-standard axes configurations.
         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=store, cache=cache, mode=mode)
-    images_container = ImagesContainer(group_handler)
+    images_container = ImagesContainer(group_handler, axes_setup=axes_setup)
     return images_container.get(
         path=path,
         pixel_size=pixel_size,
@@ -924,6 +1082,7 @@ def open_label(
     path: str | None = None,
     pixel_size: PixelSize | None = None,
     strict: bool = True,
+    axes_setup: AxesSetup | None = None,
     cache: bool = False,
     mode: AccessModeLiteral = "r+",
 ) -> Label:
@@ -938,13 +1097,15 @@ def open_label(
         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.
+        axes_setup (AxesSetup | None): Axes setup to load ome-zarr with
+            non-standard axes configurations.
         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=store, cache=cache, mode=mode)
     if name is None:
-        label_meta_handler = LabelMetaHandler(group_handler)
+        label_meta_handler = LabelMetaHandler(group_handler, axes_setup=axes_setup)
         path = (
             label_meta_handler.get_meta()
             .get_dataset(path=path, pixel_size=pixel_size, strict=strict)
@@ -952,7 +1113,7 @@ def open_label(
         )
         return Label(group_handler, path, label_meta_handler)
 
-    labels_container = LabelsContainer(group_handler)
+    labels_container = LabelsContainer(group_handler, axes_setup=axes_setup)
     return labels_container.get(
         name=name,
         path=path,
@@ -975,6 +1136,7 @@ def create_empty_ome_zarr(
     axes_names: Sequence[str] | None = None,
     channels_meta: Sequence[str | Channel] | None = None,
     name: str | None = None,
+    axes_setup: AxesSetup | None = None,
     ngff_version: NgffVersions = DefaultNgffVersion,
     chunks: ChunksLike = "auto",
     shards: ShardsLike | None = None,
@@ -1014,6 +1176,8 @@ def create_empty_ome_zarr(
         channels_meta (Sequence[str | Channel] | None): The channels metadata.
             Defaults to None.
         name (str | None): The name of the image. Defaults to None.
+        axes_setup (AxesSetup | None): Axes setup to create ome-zarr with
+            non-standard axes configurations. Defaults to None.
         ngff_version (NgffVersions): The version of the OME-Zarr specification.
             Defaults to DefaultNgffVersion.
         chunks (ChunksLike): The chunk shape. Defaults to "auto".
@@ -1034,19 +1198,15 @@ def create_empty_ome_zarr(
         channel_active (Sequence[bool] | None): Deprecated. Use channels_meta instead.
     """
     if xy_pixelsize is not None:
-        warnings.warn(
-            "'xy_pixelsize' is deprecated and will be removed in a future "
-            "version. Please use 'pixelsize' instead.",
-            DeprecationWarning,
-            stacklevel=2,
+        logger.warning(
+            "'xy_pixelsize' is deprecated and will be removed in ngio=0.6. "
+            "Please use 'pixelsize' instead."
         )
         pixelsize = xy_pixelsize
     if xy_scaling_factor is not None or z_scaling_factor is not None:
-        warnings.warn(
+        logger.warning(
             "'xy_scaling_factor' and 'z_scaling_factor' are deprecated and will be "
-            "removed in a future version. Please use 'scaling_factors' instead.",
-            DeprecationWarning,
-            stacklevel=2,
+            "removed in ngio=0.6. Please use 'scaling_factors' instead."
         )
         xy_scaling_factor_ = xy_scaling_factor or 2.0
         z_scaling_factor_ = z_scaling_factor or 1.0
@@ -1057,40 +1217,32 @@ def create_empty_ome_zarr(
             scaling_factors = (1.0,) * (len(shape) - 3) + zyx_factors
 
     if channel_labels is not None:
-        warnings.warn(
-            "'channel_labels' is deprecated and will be removed in a future "
-            "version. Please use 'channels_meta' instead.",
-            DeprecationWarning,
-            stacklevel=2,
+        logger.warning(
+            "'channel_labels' is deprecated and will be removed in ngio=0.6. "
+            "Please use 'channels_meta' instead."
         )
         channels_meta = channel_labels
 
     if channel_wavelengths is not None:
-        warnings.warn(
-            "'channel_wavelengths' is deprecated and will be removed in a future "
-            "version. Please use 'channels_meta' instead.",
-            DeprecationWarning,
-            stacklevel=2,
+        logger.warning(
+            "'channel_wavelengths' is deprecated and will be removed in ngio=0.6. "
+            "Please use 'channels_meta' instead."
         )
     if channel_colors is not None:
-        warnings.warn(
-            "'channel_colors' is deprecated and will be removed in a future "
-            "version. Please use 'channels_meta' instead.",
-            DeprecationWarning,
-            stacklevel=2,
+        logger.warning(
+            "'channel_colors' is deprecated and will be removed in ngio=0.6. "
+            "Please use 'channels_meta' instead."
         )
     if channel_active is not None:
-        warnings.warn(
-            "'channel_active' is deprecated and will be removed in a future "
-            "version. Please use 'channels_meta' instead.",
-            DeprecationWarning,
-            stacklevel=2,
+        logger.warning(
+            "'channel_active' is deprecated and will be removed in ngio=0.6. "
+            "Please use 'channels_meta' instead."
         )
 
     if pixelsize is None:
         raise NgioValueError("pixelsize must be provided.")
 
-    handler = init_image_like(
+    handler, axes_setup = init_image_like(
         store=store,
         meta_type=NgioImageMeta,
         shape=shape,
@@ -1105,6 +1257,7 @@ def create_empty_ome_zarr(
         axes_names=axes_names,
         channels_meta=channels_meta,
         name=name,
+        axes_setup=axes_setup,
         ngff_version=ngff_version,
         chunks=chunks,
         shards=shards,
@@ -1115,25 +1268,22 @@ def create_empty_ome_zarr(
         overwrite=overwrite,
     )
 
-    ome_zarr = OmeZarrContainer(group_handler=handler)
+    ome_zarr = OmeZarrContainer(group_handler=handler, axes_setup=axes_setup)
     if (
-        channel_wavelengths is not None
+        channel_labels is not None
+        or channel_wavelengths is not None
         or channel_colors is not None
         or channel_active is not None
     ):
-        channel_names = ome_zarr.channel_labels
+        # Deprecated way of setting channel metadata
+        # we set it here for backward compatibility
         ome_zarr.set_channel_meta(
-            labels=channel_names,
+            labels=channel_labels,
             wavelength_id=channel_wavelengths,
             percentiles=None,
             colors=channel_colors,
             active=channel_active,
         )
-    else:
-        ome_zarr.set_channel_meta(
-            labels=ome_zarr.channel_labels,
-            percentiles=None,
-        )
     return ome_zarr
 
 
@@ -1152,6 +1302,7 @@ def create_ome_zarr_from_array(
     channels_meta: Sequence[str | Channel] | None = None,
     percentiles: tuple[float, float] = (0.1, 99.9),
     name: str | None = None,
+    axes_setup: AxesSetup | None = None,
     ngff_version: NgffVersions = DefaultNgffVersion,
     chunks: ChunksLike = "auto",
     shards: ShardsLike | None = None,
@@ -1192,6 +1343,8 @@ def create_ome_zarr_from_array(
         percentiles (tuple[float, float]): The percentiles of the channels for
             computing display ranges. Defaults to (0.1, 99.9).
         name (str | None): The name of the image. Defaults to None.
+        axes_setup (AxesSetup | None): Axes setup to create ome-zarr with
+            non-standard axes configurations. Defaults to None.
         ngff_version (NgffVersions): The version of the OME-Zarr specification.
             Defaults to DefaultNgffVersion.
         chunks (ChunksLike): The chunk shape. Defaults to "auto".
@@ -1210,6 +1363,10 @@ def create_ome_zarr_from_array(
         channel_colors (Sequence[str] | None): Deprecated. Use channels_meta instead.
         channel_active (Sequence[bool] | None): Deprecated. Use channels_meta instead.
     """
+    if len(percentiles) != 2:
+        raise NgioValueError(
+            f"'percentiles' must be a tuple of two values. Got {percentiles}"
+        )
     ome_zarr = create_empty_ome_zarr(
         store=store,
         shape=array.shape,
@@ -1224,6 +1381,7 @@ def create_ome_zarr_from_array(
         axes_names=axes_names,
         channels_meta=channels_meta,
         name=name,
+        axes_setup=axes_setup,
         ngff_version=ngff_version,
         chunks=chunks,
         shards=shards,
@@ -1242,12 +1400,5 @@ def create_ome_zarr_from_array(
     image = ome_zarr.get_image()
     image.set_array(array)
     image.consolidate()
-    if len(percentiles) != 2:
-        raise NgioValueError(
-            f"'percentiles' must be a tuple of two values. Got {percentiles}"
-        )
-    ome_zarr.set_channel_percentiles(
-        start_percentile=percentiles[0],
-        end_percentile=percentiles[1],
-    )
+    ome_zarr.set_channel_windows_with_percentiles(percentiles=percentiles)
     return ome_zarr