ngio 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

ngio/images/create.py

@@ -12,7 +12,10 @@ from ngio.ome_zarr_meta import (
     get_label_meta_handler,
 )
 from ngio.ome_zarr_meta.ngio_specs import (
-    NgffVersion,
+    DefaultNgffVersion,
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
+    NgffVersions,
     SpaceUnits,
     TimeUnits,
     canonical_axes_order,
@@ -32,10 +35,10 @@ def _init_generic_meta(
     levels: int | list[str] = 5,
     yx_scaling_factor: float | tuple[float, float] = 2.0,
     z_scaling_factor: float = 1.0,
-    space_unit: SpaceUnits | str | None = None,
-    time_unit: TimeUnits | str | None = None,
+    space_unit: SpaceUnits | str | None = DefaultSpaceUnit,
+    time_unit: TimeUnits | str | None = DefaultTimeUnit,
     name: str | None = None,
-    version: NgffVersion = "0.4",
+    version: NgffVersions = DefaultNgffVersion,
 ) -> tuple[_image_or_label_meta, list[float]]:
     """Initialize the metadata for an image or label."""
     scaling_factors = []
@@ -55,20 +58,6 @@ def _init_generic_meta(
         else:
             scaling_factors.append(1.0)
 
-    if space_unit is None:
-        space_unit = SpaceUnits.micrometer
-    elif isinstance(space_unit, str):
-        space_unit = SpaceUnits(space_unit)
-    elif not isinstance(space_unit, SpaceUnits):
-        raise NgioValueError(f"space_unit can not be {type(space_unit)}.")
-
-    if time_unit is None:
-        time_unit = TimeUnits.seconds
-    elif isinstance(time_unit, str):
-        time_unit = TimeUnits(time_unit)
-    elif not isinstance(time_unit, TimeUnits):
-        raise NgioValueError(f"time_units can not be {type(time_unit)}.")
-
     pixel_sizes = PixelSize(
         x=pixelsize,
         y=pixelsize,
@@ -89,7 +78,7 @@ def _init_generic_meta(
     return meta, scaling_factors
 
 
-def _create_empty_label(
+def create_empty_label_container(
     store: StoreOrGroup,
     shape: Collection[int],
     pixelsize: float,
@@ -98,14 +87,14 @@ def _create_empty_label(
     levels: int | list[str] = 5,
     yx_scaling_factor: float | tuple[float, float] = 2.0,
     z_scaling_factor: float = 1.0,
-    space_unit: SpaceUnits | str | None = None,
-    time_unit: TimeUnits | str | None = None,
+    space_unit: SpaceUnits | str | None = DefaultSpaceUnit,
+    time_unit: TimeUnits | str | None = DefaultTimeUnit,
     axes_names: Collection[str] | None = None,
     name: str | None = None,
     chunks: Collection[int] | None = None,
     dtype: str = "uint16",
     overwrite: bool = False,
-    version: NgffVersion = "0.4",
+    version: NgffVersions = DefaultNgffVersion,
 ) -> ZarrGroupHandler:
     """Create an empty label with the given shape and metadata.
 
@@ -122,10 +111,10 @@ def _create_empty_label(
             dimensions. Defaults to 2.0.
         z_scaling_factor (float, optional): The down-scaling factor in z dimension.
             Defaults to 1.0.
-        space_unit (SpaceUnits | str | None, optional): The unit of space. Defaults to
-            None.
-        time_unit (TimeUnits | str | None, optional): The unit of time. Defaults to
-            None.
+        space_unit (SpaceUnits, optional): The unit of space. Defaults to
+            DefaultSpaceUnit.
+        time_unit (TimeUnits, optional): The unit of time. Defaults to
+            DefaultTimeUnit.
         axes_names (Collection[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.
@@ -135,7 +124,7 @@ def _create_empty_label(
         overwrite (bool, optional): Whether to overwrite an existing image.
             Defaults to True.
         version (str, optional): The version of the OME-Zarr specification.
-            Defaults to "0.4".
+            Defaults to DefaultVersion.
 
     """
     if axes_names is None:
@@ -180,7 +169,7 @@ def _create_empty_label(
     return group_handler
 
 
-def _create_empty_image(
+def create_empty_image_container(
     store: StoreOrGroup,
     shape: Collection[int],
     pixelsize: float,
@@ -189,14 +178,14 @@ def _create_empty_image(
     levels: int | list[str] = 5,
     yx_scaling_factor: float | tuple[float, float] = 2,
     z_scaling_factor: float = 1.0,
-    space_unit: SpaceUnits | str | None = None,
-    time_unit: TimeUnits | str | None = None,
+    space_unit: SpaceUnits | str | None = DefaultSpaceUnit,
+    time_unit: TimeUnits | str | None = DefaultTimeUnit,
     axes_names: Collection[str] | None = None,
     name: str | None = None,
     chunks: Collection[int] | None = None,
     dtype: str = "uint16",
     overwrite: bool = False,
-    version: NgffVersion = "0.4",
+    version: NgffVersions = DefaultNgffVersion,
 ) -> ZarrGroupHandler:
     """Create an empty OME-Zarr image with the given shape and metadata.
 
@@ -213,10 +202,10 @@ def _create_empty_image(
             dimensions. Defaults to 2.0.
         z_scaling_factor (float, optional): The down-scaling factor in z dimension.
             Defaults to 1.0.
-        space_unit (SpaceUnits | str | None, optional): The unit of space. Defaults to
-            None.
-        time_unit (TimeUnits | str | None, optional): The unit of time. Defaults to
-            None.
+        space_unit (SpaceUnits, optional): The unit of space. Defaults to
+            DefaultSpaceUnit.
+        time_unit (TimeUnits, optional): The unit of time. Defaults to
+            DefaultTimeUnit.
         axes_names (Collection[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.
@@ -226,7 +215,7 @@ def _create_empty_image(
         overwrite (bool, optional): Whether to overwrite an existing image.
             Defaults to True.
         version (str, optional): The version of the OME-Zarr specification.
-            Defaults to "0.4".
+            Defaults to DefaultVersion.
 
     """
     if axes_names is None:

ngio/images/image.py

@@ -7,14 +7,22 @@ from dask import array as da
 
 from ngio.common import Dimensions
 from ngio.images.abstract_image import AbstractImage, consolidate_image
-from ngio.images.create import _create_empty_image
+from ngio.images.create import create_empty_image_container
 from ngio.ome_zarr_meta import (
     ImageMetaHandler,
     NgioImageMeta,
     PixelSize,
     find_image_meta_handler,
 )
-from ngio.ome_zarr_meta.ngio_specs import Channel, ChannelsMeta, ChannelVisualisation
+from ngio.ome_zarr_meta.ngio_specs import (
+    Channel,
+    ChannelsMeta,
+    ChannelVisualisation,
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
+    SpaceUnits,
+    TimeUnits,
+)
 from ngio.utils import (
     NgioValidationError,
     StoreOrGroup,
@@ -142,10 +150,12 @@ class ImagesContainer:
         image = self.get()
         return image.wavelength_ids
 
-    def initialize_channel_meta(
+    def set_channel_meta(
         self,
         labels: Collection[str] | int | None = None,
         wavelength_id: Collection[str] | None = None,
+        start: Collection[float] | None = None,
+        end: Collection[float] | None = None,
         percentiles: tuple[float, float] | None = None,
         colors: Collection[str] | None = None,
         active: Collection[bool] | None = None,
@@ -158,6 +168,10 @@ class ImagesContainer:
                 If an integer is provided, the channels will be named "channel_i".
             wavelength_id(Collection[str] | None): The wavelength ID of the channel.
                 If None, the wavelength ID will be the same as the channel name.
+            start(Collection[float] | None): The start value for each channel.
+                If None, the start value will be computed from the image.
+            end(Collection[float] | None): The end value for each channel.
+                If None, the end value will be computed from the image.
             percentiles(tuple[float, float] | None): The start and end percentiles
                 for each channel. If None, the percentiles will not be computed.
             colors(Collection[str, NgioColors] | None): The list of colors for the
@@ -169,12 +183,40 @@ class ImagesContainer:
         low_res_dataset = self.meta.get_lowest_resolution_dataset()
         ref_image = self.get(path=low_res_dataset.path)
 
+        if start is not None and end is None:
+            raise NgioValidationError(
+                "If start is provided, end must be provided as well."
+            )
+        if end is not None and start is None:
+            raise NgioValidationError(
+                "If end is provided, start must be provided as well."
+            )
+
+        if start is not None and percentiles is not None:
+            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 NgioValidationError(
+                    "The start and end lists must have the same length."
+                )
+            if len(start) != self.num_channels:
+                raise NgioValidationError(
+                    "The start and end lists must have the same length as "
+                    "the number of channels."
+                )
+
+            start = list(start)
+            end = list(end)
+
         else:
             start, end = None, None
 
@@ -196,7 +238,7 @@ class ImagesContainer:
         meta.set_channels_meta(channel_meta)
         self._meta_handler.write_meta(meta)
 
-    def update_percentiles(
+    def set_channel_percentiles(
         self,
         start_percentile: float = 0.1,
         end_percentile: float = 99.9,
@@ -230,6 +272,21 @@ class ImagesContainer:
         meta.set_channels_meta(new_meta)
         self._meta_handler.write_meta(meta)
 
+    def set_axes_unit(
+        self,
+        space_unit: SpaceUnits = DefaultSpaceUnit,
+        time_unit: TimeUnits = DefaultTimeUnit,
+    ) -> None:
+        """Set the axes unit of the image.
+
+        Args:
+            space_unit (SpaceUnits): The space unit of the image.
+            time_unit (TimeUnits): The time unit of the image.
+        """
+        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,
@@ -238,6 +295,7 @@ class ImagesContainer:
         labels: Collection[str] | None = None,
         pixel_size: PixelSize | None = None,
         axes_names: Collection[str] | None = None,
+        name: str | None = None,
         chunks: Collection[int] | None = None,
         dtype: str | None = None,
         overwrite: bool = False,
@@ -252,6 +310,7 @@ class ImagesContainer:
             labels (Collection[str] | None): The labels of the new image.
             pixel_size (PixelSize | None): The pixel size of the new image.
             axes_names (Collection[str] | None): The axes names of the new image.
+            name (str | None): The name of the new image.
             chunks (Collection[int] | None): The chunk shape of the new image.
             dtype (str | None): The data type of the new image.
             overwrite (bool): Whether to overwrite an existing image.
@@ -267,6 +326,7 @@ class ImagesContainer:
             labels=labels,
             pixel_size=pixel_size,
             axes_names=axes_names,
+            name=name,
             chunks=chunks,
             dtype=dtype,
             overwrite=overwrite,
@@ -346,6 +406,7 @@ def derive_image_container(
     labels: Collection[str] | None = None,
     pixel_size: PixelSize | None = None,
     axes_names: Collection[str] | None = None,
+    name: str | None = None,
     chunks: Collection[int] | None = None,
     dtype: str | None = None,
     overwrite: bool = False,
@@ -360,6 +421,7 @@ def derive_image_container(
         labels (Collection[str] | None): The labels of the new image.
         pixel_size (PixelSize | None): The pixel size of the new image.
         axes_names (Collection[str] | None): The axes names of the new image.
+        name (str | None): The name of the new image.
         chunks (Collection[int] | None): The chunk shape of the new image.
         dtype (str | None): The data type of the new image.
         overwrite (bool): Whether to overwrite an existing image.
@@ -399,9 +461,12 @@ def derive_image_container(
             f"Got {chunks} for shape {shape}."
         )
 
+    if name is None:
+        name = ref_meta.name
+
     if dtype is None:
         dtype = ref_image.dtype
-    handler = _create_empty_image(
+    handler = create_empty_image_container(
         store=store,
         shape=shape,
         pixelsize=pixel_size.x,
@@ -413,6 +478,7 @@ def derive_image_container(
         time_unit=pixel_size.time_unit,
         space_unit=pixel_size.space_unit,
         axes_names=axes_names,
+        name=name,
         chunks=chunks,
         dtype=dtype,
         overwrite=overwrite,
@@ -430,11 +496,17 @@ def derive_image_container(
         active = [
             c.channel_visualisation.active for c in ref_image._channels_meta.channels
         ]
+        start = [
+            c.channel_visualisation.start for c in ref_image._channels_meta.channels
+        ]
+        end = [c.channel_visualisation.end for c in ref_image._channels_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:
@@ -443,11 +515,13 @@ def derive_image_container(
             )
         _labels = labels
 
-    image_container.initialize_channel_meta(
+    image_container.set_channel_meta(
         labels=_labels,
         wavelength_id=wavelength_id,
         percentiles=None,
         colors=colors,
         active=active,
+        start=start,
+        end=end,
     )
     return image_container

ngio/images/label.py

@@ -5,7 +5,7 @@ from typing import Literal
 
 from ngio.common import compute_masking_roi
 from ngio.images.abstract_image import AbstractImage, consolidate_image
-from ngio.images.create import _create_empty_label
+from ngio.images.create import create_empty_label_container
 from ngio.images.image import Image
 from ngio.ome_zarr_meta import (
     LabelMetaHandler,
@@ -13,6 +13,12 @@ from ngio.ome_zarr_meta import (
     PixelSize,
     find_label_meta_handler,
 )
+from ngio.ome_zarr_meta.ngio_specs import (
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
+    SpaceUnits,
+    TimeUnits,
+)
 from ngio.tables import MaskingRoiTable
 from ngio.utils import (
     NgioValidationError,
@@ -54,6 +60,21 @@ class Label(AbstractImage[LabelMetaHandler]):
         """Return the metadata."""
         return self._meta_handler.meta
 
+    def set_axes_unit(
+        self,
+        space_unit: SpaceUnits = DefaultSpaceUnit,
+        time_unit: TimeUnits = DefaultTimeUnit,
+    ) -> None:
+        """Set the axes unit of the image.
+
+        Args:
+            space_unit (SpaceUnits): The space unit of the image.
+            time_unit (TimeUnits): The time unit of the image.
+        """
+        meta = self.meta
+        meta = meta.to_units(space_unit=space_unit, time_unit=time_unit)
+        self._meta_handler.write_meta(meta)
+
     def build_masking_roi_table(self) -> MaskingRoiTable:
         """Compute the masking ROI table."""
         return build_masking_roi_table(self)
@@ -112,6 +133,12 @@ class LabelsContainer:
                 closest pixel size level will be returned.
 
         """
+        if name not in self.list():
+            raise NgioValueError(
+                f"Label '{name}' not found in the Labels group. "
+                f"Available labels: {self.list()}"
+            )
+
         group_handler = self._group_handler.derive_handler(name)
         label_meta_handler = find_label_meta_handler(group_handler)
         path = label_meta_handler.meta.get_dataset(
@@ -122,7 +149,7 @@ class LabelsContainer:
     def derive(
         self,
         name: str,
-        ref_image: Image,
+        ref_image: Image | Label,
         shape: Collection[int] | None = None,
         pixel_size: PixelSize | None = None,
         axes_names: Collection[str] | None = None,
@@ -136,7 +163,8 @@ class LabelsContainer:
 
         Args:
             store (StoreOrGroup): The Zarr store or group to create the image in.
-            ref_image (Image): The reference image.
+            ref_image (Image | Label): A reference image that will be used to create
+                the new image.
             name (str): The name of the new image.
             shape (Collection[int] | None): The shape of the new image.
             pixel_size (PixelSize | None): The pixel size of the new image.
@@ -153,13 +181,13 @@ class LabelsContainer:
         existing_labels = self.list()
         if name in existing_labels and not overwrite:
             raise NgioValueError(
-                f"Table '{name}' already exists in the group. "
+                f"Label '{name}' already exists in the group. "
                 "Use overwrite=True to replace it."
             )
 
         label_group = self._group_handler.get_group(name, create_mode=True)
 
-        _derive_label(
+        derive_label(
             store=label_group,
             ref_image=ref_image,
             name=name,
@@ -178,9 +206,9 @@ class LabelsContainer:
         return self.get(name)
 
 
-def _derive_label(
+def derive_label(
     store: StoreOrGroup,
-    ref_image: Image,
+    ref_image: Image | Label,
     name: str,
     shape: Collection[int] | None = None,
     pixel_size: PixelSize | None = None,
@@ -193,7 +221,8 @@ def _derive_label(
 
     Args:
         store (StoreOrGroup): The Zarr store or group to create the image in.
-        ref_image (Image): The reference image.
+        ref_image (Image | Label): A reference image that will be used to
+            create the new image.
         name (str): The name of the new image.
         shape (Collection[int] | None): The shape of the new image.
         pixel_size (PixelSize | None): The pixel size of the new image.
@@ -253,7 +282,7 @@ def _derive_label(
         axes_names = list(axes_names)
         axes_names = axes_names[:c_axis] + axes_names[c_axis + 1 :]
 
-    _ = _create_empty_label(
+    _ = create_empty_label_container(
         store=store,
         shape=shape,
         pixelsize=ref_image.pixel_size.x,