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

ngio/images/_image.py

@@ -1,8 +1,7 @@
 """Generic class to handle Image-like data in a OME-NGFF file."""
 
-import warnings
-from collections.abc import Mapping, Sequence
-from typing import Any, Literal
+from collections.abc import Sequence
+from typing import Literal
 
 import dask.array as da
 import numpy as np
@@ -13,9 +12,10 @@ from ngio.common import (
     Dimensions,
     InterpolationOrder,
     Roi,
+    RoiPixels,
 )
-from ngio.common._pyramid import ChunksLike, ShardsLike
-from ngio.images._abstract_image import AbstractImage, abstract_derive
+from ngio.images._abstract_image import AbstractImage
+from ngio.images._create import create_empty_image_container
 from ngio.io_pipes import (
     SlicingInputType,
     TransformProtocol,
@@ -24,22 +24,24 @@ from ngio.ome_zarr_meta import (
     ImageMetaHandler,
     NgioImageMeta,
     PixelSize,
+    find_image_meta_handler,
 )
 from ngio.ome_zarr_meta.ngio_specs import (
     Channel,
     ChannelsMeta,
+    ChannelVisualisation,
     DefaultSpaceUnit,
     DefaultTimeUnit,
     NgffVersions,
     SpaceUnits,
     TimeUnits,
 )
-from ngio.ome_zarr_meta.ngio_specs._axes import AxesSetup
 from ngio.utils import (
-    NgioValueError,
+    NgioValidationError,
     StoreOrGroup,
     ZarrGroupHandler,
 )
+from ngio.utils._zarr_utils import find_dimension_separator
 
 
 class ChannelSelectionModel(BaseModel):
@@ -47,7 +49,7 @@ class ChannelSelectionModel(BaseModel):
 
     This model is used to select a channel by label, wavelength ID, or index.
 
-    Properties:
+    Args:
         identifier (str): Unique identifier for the channel.
             This can be a channel label, wavelength ID, or index.
         mode (Literal["label", "wavelength_id", "index"]): Specifies how to
@@ -88,7 +90,7 @@ def _check_channel_meta(meta: NgioImageMeta, dimension: Dimensions) -> ChannelsM
         return ChannelsMeta.default_init(labels=c_dim)
 
     if len(meta.channels_meta.channels) != c_dim:
-        raise NgioValueError(
+        raise NgioValidationError(
             "The number of channels does not match the image. "
             f"Expected {len(meta.channels_meta.channels)} channels, got {c_dim}."
         )
@@ -96,7 +98,7 @@ def _check_channel_meta(meta: NgioImageMeta, dimension: Dimensions) -> ChannelsM
     return meta.channels_meta
 
 
-class Image(AbstractImage):
+class Image(AbstractImage[ImageMetaHandler]):
     """A class to handle a single image (or level) in an OME-Zarr image.
 
     This class is meant to be subclassed by specific image types.
@@ -106,7 +108,7 @@ class Image(AbstractImage):
         self,
         group_handler: ZarrGroupHandler,
         path: str,
-        meta_handler: ImageMetaHandler,
+        meta_handler: ImageMetaHandler | None,
     ) -> None:
         """Initialize the Image at a single level.
 
@@ -116,22 +118,16 @@ class Image(AbstractImage):
             meta_handler: The image metadata handler.
 
         """
+        if meta_handler is None:
+            meta_handler = find_image_meta_handler(group_handler)
         super().__init__(
             group_handler=group_handler, path=path, meta_handler=meta_handler
         )
 
-    @property
-    def meta_handler(self) -> ImageMetaHandler:
-        """Return the metadata handler."""
-        assert isinstance(self._meta_handler, ImageMetaHandler)
-        return self._meta_handler
-
     @property
     def meta(self) -> NgioImageMeta:
         """Return the metadata."""
-        meta = self.meta_handler.get_meta()
-        assert isinstance(meta, NgioImageMeta)
-        return meta
+        return self._meta_handler.meta
 
     @property
     def channels_meta(self) -> ChannelsMeta:
@@ -191,7 +187,7 @@ class Image(AbstractImage):
 
     def get_roi_as_numpy(
         self,
-        roi: Roi,
+        roi: Roi | RoiPixels,
         channel_selection: ChannelSlicingInputType = None,
         axes_order: Sequence[str] | None = None,
         transforms: Sequence[TransformProtocol] | None = None,
@@ -245,7 +241,7 @@ class Image(AbstractImage):
 
     def get_roi_as_dask(
         self,
-        roi: Roi,
+        roi: Roi | RoiPixels,
         channel_selection: ChannelSlicingInputType = None,
         axes_order: Sequence[str] | None = None,
         transforms: Sequence[TransformProtocol] | None = None,
@@ -302,7 +298,7 @@ class Image(AbstractImage):
 
     def get_roi(
         self,
-        roi: Roi,
+        roi: Roi | RoiPixels,
         channel_selection: ChannelSlicingInputType = None,
         axes_order: Sequence[str] | None = None,
         transforms: Sequence[TransformProtocol] | None = None,
@@ -362,7 +358,7 @@ class Image(AbstractImage):
 
     def set_roi(
         self,
-        roi: Roi,
+        roi: Roi | RoiPixels,
         patch: np.ndarray | da.Array,
         channel_selection: ChannelSlicingInputType = None,
         axes_order: Sequence[str] | None = None,
@@ -400,135 +396,67 @@ class Image(AbstractImage):
 
 
 class ImagesContainer:
-    """A class to handle the /images group in an OME-NGFF file."""
+    """A class to handle the /labels group in an OME-NGFF file."""
 
-    def __init__(
-        self,
-        group_handler: ZarrGroupHandler,
-        axes_setup: AxesSetup | None,
-        version: NgffVersions | None = None,
-        validate_paths: bool = True,
-    ) -> None:
-        """Initialize the ImagesContainer."""
+    def __init__(self, group_handler: ZarrGroupHandler) -> None:
+        """Initialize the LabelGroupHandler."""
         self._group_handler = group_handler
-        self._meta_handler = ImageMetaHandler(
-            group_handler=group_handler, axes_setup=axes_setup, version=version
-        )
-        if validate_paths:
-            for level_path in self._meta_handler.get_meta().paths:
-                self.get(path=level_path)
+        self._meta_handler = find_image_meta_handler(group_handler)
 
     @property
     def meta(self) -> NgioImageMeta:
         """Return the metadata."""
-        return self._meta_handler.get_meta()
-
-    @property
-    def channels_meta(self) -> ChannelsMeta:
-        """Return the channels metadata."""
-        return self.get().channels_meta
-
-    @property
-    def axes_setup(self) -> AxesSetup:
-        """Return the axes setup."""
-        return self.meta.axes_handler.axes_setup
-
-    @property
-    def level_paths(self) -> list[str]:
-        """Return the paths of the levels in the image."""
-        return self.meta.paths
-
-    @property
-    def levels_paths(self) -> list[str]:
-        """Deprecated: use 'level_paths' instead."""
-        warnings.warn(
-            "'levels_paths' is deprecated and will be removed in ngio=0.6. "
-            "Please use 'level_paths' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.level_paths
+        return self._meta_handler.meta
 
     @property
     def levels(self) -> int:
         """Return the number of levels in the image."""
-        return self.meta.levels
-
-    @property
-    def is_3d(self) -> bool:
-        """Return True if the image is 3D."""
-        return self.get().is_3d
-
-    @property
-    def is_2d(self) -> bool:
-        """Return True if the image is 2D."""
-        return self.get().is_2d
+        return self._meta_handler.meta.levels
 
     @property
-    def is_time_series(self) -> bool:
-        """Return True if the image is a time series."""
-        return self.get().is_time_series
-
-    @property
-    def is_2d_time_series(self) -> bool:
-        """Return True if the image is a 2D time series."""
-        return self.get().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().is_3d_time_series
-
-    @property
-    def is_multi_channels(self) -> bool:
-        """Return True if the image is multichannel."""
-        return self.get().is_multi_channels
-
-    @property
-    def space_unit(self) -> str | None:
-        """Return the space unit of the image."""
-        return self.meta.space_unit
+    def levels_paths(self) -> list[str]:
+        """Return the paths of the levels in the image."""
+        return self._meta_handler.meta.paths
 
     @property
-    def time_unit(self) -> str | None:
-        """Return the time unit of the image."""
-        return self.meta.time_unit
+    def num_channels(self) -> int:
+        """Return the number of channels."""
+        image = self.get()
+        return image.num_channels
 
     @property
     def channel_labels(self) -> list[str]:
         """Return the channels of the image."""
-        return self.get().channel_labels
+        image = self.get()
+        return image.channel_labels
 
     @property
     def wavelength_ids(self) -> list[str | None]:
-        """Return the list of wavelength of the image."""
-        return self.get().wavelength_ids
-
-    @property
-    def num_channels(self) -> int:
-        """Return the number of channels."""
-        return self.get().num_channels
+        """Return the wavelength of the image."""
+        image = self.get()
+        return image.wavelength_ids
 
     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."""
-        return self.channels_meta.get_channel_idx(
+        """Get the index of a channel by label or wavelength ID.
+
+        Args:
+            channel_label (str | None): The label of the channel.
+                If None a wavelength ID must be provided.
+            wavelength_id (str | None): The wavelength ID of the channel.
+                If None a channel label must be provided.
+
+        Returns:
+            int: The index of the channel.
+
+        """
+        image = self.get()
+        return image.get_channel_idx(
             channel_label=channel_label, wavelength_id=wavelength_id
         )
 
-    def _set_channel_meta(
-        self,
-        channels_meta: ChannelsMeta | None = None,
-    ) -> None:
-        """Set the channels metadata."""
-        if channels_meta is None:
-            channels_meta = ChannelsMeta.default_init(labels=self.num_channels)
-        meta = self.meta
-        meta.set_channels_meta(channels_meta)
-        self._meta_handler.update_meta(meta)
-
-    def _set_channel_meta_legacy(
+    def set_channel_meta(
         self,
         labels: Sequence[str | None] | int | None = None,
         wavelength_id: Sequence[str | None] | None = None,
@@ -564,22 +492,32 @@ class ImagesContainer:
         ref_image = self.get(path=low_res_dataset.path)
 
         if start is not None and end is None:
-            raise NgioValueError("If start is provided, end must be provided as well.")
+            raise NgioValidationError(
+                "If start is provided, end must be provided as well."
+            )
         if end is not None and start is None:
-            raise NgioValueError("If end is provided, start must be provided as well.")
+            raise NgioValidationError(
+                "If end is provided, start must be provided as well."
+            )
 
         if start is not None and percentiles is not None:
-            raise NgioValueError(
+            raise NgioValidationError(
                 "If start and end are provided, percentiles must be None."
             )
 
+        if percentiles is not None:
+            start, end = compute_image_percentile(
+                ref_image,
+                start_percentile=percentiles[0],
+                end_percentile=percentiles[1],
+            )
         elif start is not None and end is not None:
             if len(start) != len(end):
-                raise NgioValueError(
+                raise NgioValidationError(
                     "The start and end lists must have the same length."
                 )
             if len(start) != self.num_channels:
-                raise NgioValueError(
+                raise NgioValidationError(
                     "The start and end lists must have the same length as "
                     "the number of channels."
                 )
@@ -603,212 +541,44 @@ class ImagesContainer:
             data_type=ref_image.dtype,
             **omero_kwargs,
         )
-        self._set_channel_meta(channel_meta)
-        if percentiles is not None:
-            self.set_channel_windows_with_percentiles(percentiles=percentiles)
-
-    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 = None,
-        active: Sequence[bool | None] | None = None,
-        **omero_kwargs: dict,
-    ) -> None:
-        """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.
-        """
-        _is_legacy = any(
-            param is not None
-            for param in [
-                labels,
-                wavelength_id,
-                start,
-                end,
-                percentiles,
-                colors,
-                active,
-            ]
-        )
-        if _is_legacy:
-            warnings.warn(
-                "The following parameters are deprecated and will be removed in "
-                "ngio=0.6: labels, wavelength_id, start, end, percentiles, "
-                "colors, active, omero_kwargs. Please use the "
-                "'channel_meta' parameter instead.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            self._set_channel_meta_legacy(
-                labels=labels,
-                wavelength_id=wavelength_id,
-                start=start,
-                end=end,
-                percentiles=percentiles,
-                colors=colors,
-                active=active,
-                **omero_kwargs,
-            )
-            return None
-        self._set_channel_meta(channel_meta)
 
-    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.
-        """
-        channels_meta = self.channels_meta
-        if len(labels) != len(channels_meta.channels):
-            raise NgioValueError(
-                "The number of labels must match the number of channels."
-            )
-        new_channels = []
-        for label, ch in zip(labels, channels_meta.channels, strict=True):
-            channel = ch.model_copy(update={"label": label})
-            new_channels.append(channel)
-        new_meta = channels_meta.model_copy(update={"channels": new_channels})
-        self._set_channel_meta(new_meta)
-
-    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.
-        """
-        channel_meta = self.channels_meta
-        if len(colors) != len(channel_meta.channels):
-            raise NgioValueError(
-                "The number of colors must match the number of channels."
-            )
-        new_channels = []
-        for color, ch in zip(colors, channel_meta.channels, strict=True):
-            ch_visualisation = ch.channel_visualisation.model_copy(
-                update={"color": color}
-            )
-            channel = ch.model_copy(update={"channel_visualisation": ch_visualisation})
-            new_channels.append(channel)
-        new_meta = channel_meta.model_copy(update={"channels": new_channels})
-        self._set_channel_meta(new_meta)
+        meta = self.meta
+        meta.set_channels_meta(channel_meta)
+        self._meta_handler.write_meta(meta)
 
     def set_channel_percentiles(
         self,
         start_percentile: float = 0.1,
         end_percentile: float = 99.9,
     ) -> None:
-        """Deprecated: Update the channel windows using percentiles.
+        """Update the percentiles of the channels."""
+        if self.meta._channels_meta is None:
+            raise NgioValidationError("The channels meta is not initialized.")
 
-        Args:
-            start_percentile (float): The start percentile.
-            end_percentile (float): The end percentile.
-        """
-        warnings.warn(
-            "The 'set_channel_percentiles' method is deprecated and will be removed in "
-            "ngio=0.6. Please use 'set_channel_windows_with_percentiles' instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        self.set_channel_windows_with_percentiles(
-            percentiles=(start_percentile, end_percentile)
+        low_res_dataset = self.meta.get_lowest_resolution_dataset()
+        ref_image = self.get(path=low_res_dataset.path)
+        starts, ends = compute_image_percentile(
+            ref_image, start_percentile=start_percentile, end_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.
-        """
-        current_channels = self.channels_meta.channels
-        if len(starts_ends) != len(current_channels):
-            raise NgioValueError(
-                "The number of start-end pairs must match the number of channels."
-            )
-        if min_max is not None and len(min_max) != len(current_channels):
-            raise NgioValueError(
-                "The number of min-max pairs must match the number of channels."
-            )
-        if min_max is None:
-            min_max_ = [None] * len(current_channels)
-        else:
-            min_max_ = list(min_max)
         channels = []
-        for se, mm, ch in zip(
-            starts_ends, min_max_, self.channels_meta.channels, strict=True
-        ):
-            updates = {"start": se[0], "end": se[1]}
-            if mm is not None:
-                updates.update({"min": mm[0], "max": mm[1]})
-            channel_visualisation = ch.channel_visualisation.model_copy(update=updates)
-            channel = ch.model_copy(
-                update={"channel_visualisation": channel_visualisation}
+        for c, channel in enumerate(self.meta._channels_meta.channels):
+            new_v = ChannelVisualisation(
+                start=starts[c],
+                end=ends[c],
+                **channel.channel_visualisation.model_dump(exclude={"start", "end"}),
+            )
+            new_c = Channel(
+                channel_visualisation=new_v,
+                **channel.model_dump(exclude={"channel_visualisation"}),
             )
-            channels.append(channel)
+            channels.append(new_c)
+
         new_meta = ChannelsMeta(channels=channels)
+
         meta = self.meta
         meta.set_channels_meta(new_meta)
-        self._meta_handler.update_meta(meta)
-
-    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.
-        """
-        if self.meta._channels_meta is None:
-            raise NgioValueError("The channels meta is not initialized.")
-
-        low_res_dataset = self.meta.get_lowest_resolution_dataset()
-        ref_image = self.get(path=low_res_dataset.path)
-        starts_ends = compute_image_percentile(ref_image, percentiles=percentiles)
-        self.set_channel_windows(starts_ends=starts_ends)
+        self._meta_handler.write_meta(meta)
 
     def set_axes_unit(
         self,
@@ -821,127 +591,64 @@ class ImagesContainer:
             space_unit (SpaceUnits): The space unit of the image.
             time_unit (TimeUnits): The time unit of the image.
         """
-        self.get().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.
-        """
-        image = self.get()
-        image.set_axes_names(axes_names=axes_names)
-        self._meta_handler._axes_setup = image.meta.axes_handler.axes_setup
-
-    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.get().set_name(name=name)
+        meta = self.meta
+        meta = meta.to_units(space_unit=space_unit, time_unit=time_unit)
+        self._meta_handler.write_meta(meta)
 
     def derive(
         self,
         store: StoreOrGroup,
         ref_path: str | None = None,
-        # Metadata parameters
         shape: Sequence[int] | None = None,
-        pixelsize: float | tuple[float, float] | None = None,
-        z_spacing: float | None = None,
-        time_spacing: float | None = None,
+        labels: Sequence[str] | None = None,
+        pixel_size: PixelSize | None = None,
+        axes_names: Sequence[str] | None = None,
         name: str | None = None,
-        translation: Sequence[float] | None = None,
-        channels_meta: Sequence[str | Channel] | None = None,
-        channels_policy: Literal["same", "squeeze", "singleton"] | int = "same",
+        chunks: Sequence[int] | None = None,
+        dtype: str | None = None,
+        dimension_separator: Literal[".", "/"] | None = None,
+        compressors: CompressorLike | None = None,
         ngff_version: NgffVersions | None = None,
-        # Zarr Array parameters
-        chunks: ChunksLike | None = None,
-        shards: ShardsLike | None = None,
-        dtype: str = "uint16",
-        dimension_separator: Literal[".", "/"] = "/",
-        compressors: CompressorLike = "auto",
-        extra_array_kwargs: Mapping[str, Any] | None = None,
         overwrite: bool = False,
-        # Deprecated arguments
-        labels: Sequence[str] | None = None,
-        pixel_size: PixelSize | None = None,
     ) -> "ImagesContainer":
         """Create an empty OME-Zarr image from an existing image.
 
-        If a kwarg is not provided, the value from the reference image will be used.
-
         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.
+            ref_path (str | None): The path to the reference image in
+                the image container.
             shape (Sequence[int] | None): The shape of the new image.
-            pixelsize (float | tuple[float, float] | None): The pixel size of the new
-                image.
-            z_spacing (float | None): The z spacing of the new image.
-            time_spacing (float | None): The time spacing 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 (Sequence[str] | None): The axes names of the new image.
             name (str | None): The name of the new image.
-            translation (Sequence[float] | None): The translation for each axis
-                at the highest resolution level. Defaults to None.
-            channels_meta (Sequence[str | Channel] | None): The channels metadata
-                of the new image.
-            channels_policy (Literal["same", "squeeze", "singleton"] | int):
-                Possible policies:
-                - If "squeeze", the channels axis will be removed (no matter its size).
-                - If "same", the channels axis will be kept as is (if it exists).
-                - If "singleton", the channels axis will be set to size 1.
-                - If an integer is provided, the channels axis will be changed to have
-                    that size.
-            ngff_version (NgffVersions | None): The NGFF version to use.
-            chunks (ChunksLike | None): The chunk shape of the new image.
-            shards (ShardsLike | None): The shard shape of the new image.
+            chunks (Sequence[int] | Literal["auto"]): The chunk shape of the new image.
+            dimension_separator (DIMENSION_SEPARATOR | None): The separator to use for
+                dimensions. If None it will use the same as the reference image.
+            compressors: The compressor to use. If None it will use
+                the same as the reference image.
             dtype (str | None): The data type of the new image.
-            dimension_separator (Literal[".", "/"] | None): The separator to use for
-                dimensions.
-            compressors (CompressorLike | None): The compressors to use.
-            extra_array_kwargs (Mapping[str, Any] | None): Extra arguments to pass to
-                the zarr array creation.
+            ngff_version (NgffVersions): The NGFF version to use.
             overwrite (bool): Whether to overwrite an existing image.
-            labels (Sequence[str] | None): The labels of the new image.
-                This argument is deprecated please use channels_meta instead.
-            pixel_size (PixelSize | None): The pixel size of the new image.
-                This argument is deprecated please use pixelsize, z_spacing,
-                and time_spacing instead.
 
         Returns:
-            ImagesContainer: The new derived image.
-
+            ImagesContainer: The new image
         """
         return derive_image_container(
             image_container=self,
             store=store,
             ref_path=ref_path,
             shape=shape,
-            pixelsize=pixelsize,
-            z_spacing=z_spacing,
-            time_spacing=time_spacing,
+            labels=labels,
+            pixel_size=pixel_size,
+            axes_names=axes_names,
             name=name,
-            translation=translation,
-            channels_meta=channels_meta,
-            channels_policy=channels_policy,
-            ngff_version=ngff_version,
             chunks=chunks,
-            shards=shards,
             dtype=dtype,
             dimension_separator=dimension_separator,
             compressors=compressors,
-            extra_array_kwargs=extra_array_kwargs,
+            ngff_version=ngff_version,
             overwrite=overwrite,
-            labels=labels,
-            pixel_size=pixel_size,
         )
 
     def get(
@@ -960,7 +667,7 @@ class ImagesContainer:
                 closest pixel size level will be returned.
 
         """
-        dataset = self._meta_handler.get_meta().get_dataset(
+        dataset = self._meta_handler.meta.get_dataset(
             path=path, pixel_size=pixel_size, strict=strict
         )
         return Image(
@@ -972,53 +679,34 @@ class ImagesContainer:
 
 def compute_image_percentile(
     image: Image,
-    percentiles: tuple[float, float] | list[tuple[float, float]] = (0.1, 99.9),
-) -> list[tuple[float, float]]:
+    start_percentile: float = 0.1,
+    end_percentile: float = 99.9,
+) -> tuple[list[float], list[float]]:
     """Compute the start and end percentiles for each channel of an image.
 
     Args:
         image: The image to compute the percentiles for.
-        percentiles: The start and end percentiles for each channel.
-            If a single tuple is provided, the same percentiles will be used
-            for all channels.
+        start_percentile: The start percentile to compute.
+        end_percentile: The end percentile to compute.
 
     Returns:
         A tuple containing the start and end percentiles for each channel.
     """
-    num_channels = image.num_channels
-    # handle the case where a single tuple is provided
-    if isinstance(percentiles, tuple):
-        if len(percentiles) != 2:
-            raise NgioValueError(
-                "Percentiles must be a tuple of two floats: "
-                "(start_percentile, end_percentile) or "
-                "a list of such tuples with length equal to the number of channels."
-            )
-        if not isinstance(percentiles[0], float) or not isinstance(
-            percentiles[1], float
-        ):
-            raise NgioValueError(
-                "Percentiles must be a tuple of two floats: "
-                "(start_percentile, end_percentile) or "
-                "a list of such tuples with length equal to the number of channels."
-            )
-        percentiles = [percentiles] * num_channels
+    starts, ends = [], []
+    for c in range(image.num_channels):
+        if image.num_channels == 1:
+            data = image.get_as_dask()
+        else:
+            data = image.get_as_dask(c=c)
 
-    if len(percentiles) != num_channels:
-        raise NgioValueError(
-            "If a list of percentiles is provided, its length must be equal "
-            "to the number of channels."
-        )
-    starts_and_ends = []
-    for c_idx, (start_percentile, end_percentile) in enumerate(percentiles):
-        data = image.get_as_dask(c=c_idx)
         data = da.ravel(data)
         # remove all the zeros
         mask = data > 1e-16
         data = data[mask]
         _data = data.compute()
         if _data.size == 0:
-            starts_and_ends.append((0.0, 0.0))
+            starts.append(0.0)
+            ends.append(0.0)
             continue
 
         # compute the percentiles
@@ -1026,107 +714,153 @@ def compute_image_percentile(
             data, [start_percentile, end_percentile], method="nearest"
         ).compute()  # type: ignore (return type is a tuple of floats)
 
-        starts_and_ends.append((float(_s_perc), float(_e_perc)))
-    return starts_and_ends
+        starts.append(float(_s_perc))
+        ends.append(float(_e_perc))
+    return starts, ends
 
 
 def derive_image_container(
-    *,
     image_container: ImagesContainer,
     store: StoreOrGroup,
     ref_path: str | None = None,
-    # Metadata parameters
     shape: Sequence[int] | None = None,
-    pixelsize: float | tuple[float, float] | None = None,
-    z_spacing: float | None = None,
-    time_spacing: float | None = None,
+    labels: Sequence[str] | None = None,
+    pixel_size: PixelSize | None = None,
+    axes_names: Sequence[str] | None = None,
     name: str | None = None,
-    translation: Sequence[float] | None = None,
-    channels_policy: Literal["same", "squeeze", "singleton"] | int = "same",
-    channels_meta: Sequence[str | Channel] | None = None,
-    ngff_version: NgffVersions | None = None,
-    # Zarr Array parameters
-    chunks: ChunksLike | None = None,
-    shards: ShardsLike | None = None,
+    chunks: Sequence[int] | None = None,
     dtype: str | None = None,
     dimension_separator: Literal[".", "/"] | None = None,
     compressors: CompressorLike | None = None,
-    extra_array_kwargs: Mapping[str, Any] | None = None,
+    ngff_version: NgffVersions | None = None,
     overwrite: bool = False,
-    # Deprecated arguments
-    labels: Sequence[str] | None = None,
-    pixel_size: PixelSize | None = None,
 ) -> ImagesContainer:
-    """Derive a new OME-Zarr image container from an existing image.
-
-    If a kwarg is not provided, the value from the reference image will be used.
+    """Create an empty OME-Zarr image from an existing image.
 
     Args:
-        image_container (ImagesContainer): The image container to derive the new image
-            from.
+        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 (Sequence[int] | None): The shape of the new image.
-        pixelsize (float | tuple[float, float] | None): The pixel size of the new image.
-        z_spacing (float | None): The z spacing of the new image.
-        time_spacing (float | None): The time spacing 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 (Sequence[str] | None): The axes names of the new image.
         name (str | None): The name of the new image.
-        translation (Sequence[float] | None): The translation for each axis
-            at the highest resolution level. Defaults to None.
-        channels_policy (Literal["squeeze", "same", "singleton"] | int): Possible
-            policies:
-            - If "squeeze", the channels axis will be removed (no matter its size).
-            - If "same", the channels axis will be kept as is (if it exists).
-            - If "singleton", the channels axis will be set to size 1.
-            - If an integer is provided, the channels axis will be changed to have
-                that size.
-        channels_meta (Sequence[str | Channel] | None): The channels metadata
-            of the new image.
-        ngff_version (NgffVersions | None): The NGFF version to use.
-        chunks (ChunksLike | None): The chunk shape of the new image.
-        shards (ShardsLike | None): The shard shape of the new image.
+        chunks (Sequence[int] | None): The chunk shape of the new image.
+        dimension_separator (DIMENSION_SEPARATOR | None): The separator to use for
+            dimensions. If None it will use the same as the reference image.
+        compressors (CompressorLike | None): The compressors to use. If None it will use
+            the same as the reference image.
+        ngff_version (NgffVersions): The NGFF version to use.
         dtype (str | None): The data type of the new image.
-        dimension_separator (Literal[".", "/"] | None): The separator to use for
-            dimensions.
-        compressors (CompressorLike | None): The compressors to use.
-        extra_array_kwargs (Mapping[str, Any] | None): Extra arguments to pass to
-            the zarr array creation.
-        overwrite (bool): Whether to overwrite an existing image. Defaults to False.
-        labels (Sequence[str] | None): Deprecated. This argument is deprecated,
-            please use channels_meta instead.
-        pixel_size (PixelSize | None): Deprecated. The pixel size of the new image.
-            This argument is deprecated, please use pixelsize, z_spacing,
-            and time_spacing instead.
+        overwrite (bool): Whether to overwrite an existing image.
 
     Returns:
-        ImagesContainer: The new derived image container.
+        ImagesContainer: The new image
 
     """
-    ref_image = image_container.get(path=ref_path)
-    group_handler, axes_setup = abstract_derive(
-        ref_image=ref_image,
-        meta_type=NgioImageMeta,
+    if ref_path is None:
+        ref_image = image_container.get()
+    else:
+        ref_image = image_container.get(path=ref_path)
+
+    ref_meta = ref_image.meta
+
+    if shape is None:
+        shape = ref_image.shape
+
+    if pixel_size is None:
+        pixel_size = ref_image.pixel_size
+
+    if axes_names is None:
+        axes_names = ref_meta.axes_handler.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
+
+    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 name is None:
+        name = ref_meta.name
+
+    if dtype is None:
+        dtype = ref_image.dtype
+
+    if dimension_separator is None:
+        dimension_separator = find_dimension_separator(ref_image.zarr_array)
+
+    if compressors is None:
+        compressors = ref_image.zarr_array.compressors  # type: ignore
+
+    if ngff_version is None:
+        ngff_version = ref_meta.version
+
+    handler = create_empty_image_container(
         store=store,
         shape=shape,
-        pixelsize=pixelsize,
-        z_spacing=z_spacing,
-        time_spacing=time_spacing,
+        pixelsize=pixel_size.x,
+        z_spacing=pixel_size.z,
+        time_spacing=pixel_size.t,
+        levels=ref_meta.paths,
+        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,
         name=name,
-        translation=translation,
-        channels_meta=channels_meta,
-        channels_policy=channels_policy,
-        ngff_version=ngff_version,
         chunks=chunks,
-        shards=shards,
         dtype=dtype,
         dimension_separator=dimension_separator,
         compressors=compressors,
-        extra_array_kwargs=extra_array_kwargs,
         overwrite=overwrite,
-        labels=labels,
-        pixel_size=pixel_size,
+        version=ngff_version,
     )
-    return ImagesContainer(group_handler=group_handler, axes_setup=axes_setup)
+    image_container = ImagesContainer(handler)
+
+    if ref_image.num_channels == image_container.num_channels:
+        _labels = ref_image.channel_labels
+        wavelength_id = ref_image.wavelength_ids
+
+        channel_meta = ref_image.channels_meta
+        colors = [c.channel_visualisation.color for c in channel_meta.channels]
+        active = [c.channel_visualisation.active for c in channel_meta.channels]
+        start = [c.channel_visualisation.start for c in channel_meta.channels]
+        end = [c.channel_visualisation.end for c in channel_meta.channels]
+    else:
+        _labels = None
+        wavelength_id = None
+        colors = None
+        active = None
+        start = None
+        end = 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.set_channel_meta(
+        labels=_labels,
+        wavelength_id=wavelength_id,
+        percentiles=None,
+        colors=colors,
+        active=active,
+        start=start,
+        end=end,
+    )
+    return image_container
 
 
 def _parse_str_or_model(
@@ -1135,9 +869,9 @@ def _parse_str_or_model(
     """Parse a string or ChannelSelectionModel to an integer channel index."""
     if isinstance(channel_selection, int):
         if channel_selection < 0:
-            raise NgioValueError("Channel index must be a non-negative integer.")
+            raise NgioValidationError("Channel index must be a non-negative integer.")
         if channel_selection >= image.num_channels:
-            raise NgioValueError(
+            raise NgioValidationError(
                 "Channel index must be less than the number "
                 f"of channels ({image.num_channels})."
             )
@@ -1151,11 +885,11 @@ def _parse_str_or_model(
             )
         elif channel_selection.mode == "wavelength_id":
             return image.get_channel_idx(
-                wavelength_id=str(channel_selection.identifier)
+                channel_label=str(channel_selection.identifier)
             )
         elif channel_selection.mode == "index":
             return int(channel_selection.identifier)
-    raise NgioValueError(
+    raise NgioValidationError(
         "Invalid channel selection type. "
         f"{channel_selection} is of type {type(channel_selection)} ",
         "supported types are str, ChannelSelectionModel, and int.",
@@ -1174,7 +908,7 @@ def _parse_channel_selection(
     elif isinstance(channel_selection, Sequence):
         _sequence = [_parse_str_or_model(image, cs) for cs in channel_selection]
         return {"c": _sequence}
-    raise NgioValueError(
+    raise NgioValidationError(
         f"Invalid channel selection type {type(channel_selection)}. "
         "Supported types are int, str, ChannelSelectionModel, and Sequence."
     )
@@ -1188,7 +922,7 @@ def add_channel_selection_to_slicing_dict(
     """Add channel selection information to the slicing dictionary."""
     channel_info = _parse_channel_selection(image, channel_selection)
     if "c" in slicing_dict and channel_info:
-        raise NgioValueError(
+        raise NgioValidationError(
             "Both channel_selection and 'c' in slicing_kwargs are provided. "
             "Which channel selection should be used is ambiguous. "
             "Please provide only one."