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

ngio/images/ome_zarr_container.py

@@ -5,7 +5,7 @@ from typing import Literal, overload
 
 import numpy as np
 
-from ngio.images.create import _create_empty_image
+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
@@ -13,7 +13,14 @@ from ngio.ome_zarr_meta import (
     NgioImageMeta,
     PixelSize,
 )
-from ngio.ome_zarr_meta.ngio_specs import NgffVersion, SpaceUnits, TimeUnits
+from ngio.ome_zarr_meta.ngio_specs import (
+    DefaultNgffVersion,
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
+    NgffVersions,
+    SpaceUnits,
+    TimeUnits,
+)
 from ngio.tables import (
     FeatureTable,
     GenericRoiTable,
@@ -152,7 +159,17 @@ class OmeZarrContainer:
         """Return True if the image is multichannel."""
         return self.get_image().is_multi_channels
 
-    def initialize_channel_meta(
+    @property
+    def space_unit(self) -> str | None:
+        """Return the space unit of the image."""
+        return self.image_meta.space_unit
+
+    @property
+    def time_unit(self) -> str | None:
+        """Return the time unit of the image."""
+        return self.image_meta.time_unit
+
+    def set_channel_meta(
         self,
         labels: Collection[str] | int | None = None,
         wavelength_id: Collection[str] | None = None,
@@ -162,7 +179,7 @@ class OmeZarrContainer:
         **omero_kwargs: dict,
     ) -> None:
         """Create a ChannelsMeta object with the default unit."""
-        self._images_container.initialize_channel_meta(
+        self._images_container.set_channel_meta(
             labels=labels,
             wavelength_id=wavelength_id,
             percentiles=percentiles,
@@ -171,16 +188,36 @@ class OmeZarrContainer:
             **omero_kwargs,
         )
 
-    def update_percentiles(
+    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.update_percentiles(
+        self._images_container.set_channel_percentiles(
             start_percentile=start_percentile, end_percentile=end_percentile
         )
 
+    def set_axes_units(
+        self,
+        space_unit: SpaceUnits = DefaultSpaceUnit,
+        time_unit: TimeUnits = DefaultTimeUnit,
+        set_labels: bool = True,
+    ) -> None:
+        """Set the units of the image.
+
+        Args:
+            space_unit (SpaceUnits): The unit of space.
+            time_unit (TimeUnits): The unit of time.
+            set_labels (bool): Whether to set the units for the labels as well.
+        """
+        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 get_image(
         self,
         path: str | None = None,
@@ -247,6 +284,7 @@ class OmeZarrContainer:
         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,
         copy_labels: bool = False,
@@ -265,6 +303,7 @@ class OmeZarrContainer:
             axes_names (Collection[str] | None): The axes names of the new image.
             chunks (Collection[int] | None): The chunk shape of the new image.
             dtype (str | None): The data type of the new image.
+            name (str | None): The name of the new image.
             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.
@@ -280,6 +319,7 @@ class OmeZarrContainer:
             labels=labels,
             pixel_size=pixel_size,
             axes_names=axes_names,
+            name=name,
             chunks=chunks,
             dtype=dtype,
             overwrite=overwrite,
@@ -462,7 +502,7 @@ class OmeZarrContainer:
     def derive_label(
         self,
         name: str,
-        ref_image: Image | None = None,
+        ref_image: Image | Label | None = None,
         shape: Collection[int] | None = None,
         pixel_size: PixelSize | None = None,
         axes_names: Collection[str] | None = None,
@@ -475,9 +515,9 @@ class OmeZarrContainer:
         And add the label to the /labels group.
 
         Args:
-            store (StoreOrGroup): The Zarr store or group to create the image in.
-            ref_image (Image): The reference image.
             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.
             pixel_size (PixelSize | None): The pixel size of the new image.
             axes_names (Collection[str] | None): The axes names of the new image.
@@ -557,19 +597,18 @@ def create_empty_ome_zarr(
     levels: int | list[str] = 5,
     xy_scaling_factor: float = 2,
     z_scaling_factor: float = 1.0,
-    space_unit: SpaceUnits | str | None = None,
-    time_unit: TimeUnits | str | None = None,
+    space_unit: SpaceUnits = DefaultSpaceUnit,
+    time_unit: TimeUnits = DefaultTimeUnit,
     axes_names: Collection[str] | None = None,
     name: str | None = None,
     chunks: Collection[int] | None = None,
     dtype: str = "uint16",
     channel_labels: list[str] | None = None,
     channel_wavelengths: list[str] | None = None,
-    percentiles: tuple[float, float] | None = None,
     channel_colors: Collection[str] | None = None,
     channel_active: Collection[bool] | None = None,
     overwrite: bool = False,
-    version: NgffVersion = "0.4",
+    version: NgffVersions = DefaultNgffVersion,
 ) -> OmeZarrContainer:
     """Create an empty OME-Zarr image with the given shape and metadata.
 
@@ -586,10 +625,10 @@ def create_empty_ome_zarr(
             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.
@@ -600,8 +639,6 @@ def create_empty_ome_zarr(
             Defaults to None.
         channel_wavelengths (list[str] | None, optional): The wavelengths of the
             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.
             Defaults to None.
         channel_active (Collection[bool] | None, optional): Whether the channels are
@@ -609,9 +646,9 @@ def create_empty_ome_zarr(
         overwrite (bool, optional): Whether to overwrite an existing image.
             Defaults to True.
         version (NgffVersion, optional): The version of the OME-Zarr specification.
-            Defaults to "0.4".
+            Defaults to DefaultNgffVersion.
     """
-    handler = _create_empty_image(
+    handler = create_empty_image_container(
         store=store,
         shape=shape,
         pixelsize=xy_pixelsize,
@@ -631,10 +668,10 @@ def create_empty_ome_zarr(
     )
 
     ome_zarr = OmeZarrContainer(group_handler=handler)
-    ome_zarr.initialize_channel_meta(
+    ome_zarr.set_channel_meta(
         labels=channel_labels,
         wavelength_id=channel_wavelengths,
-        percentiles=percentiles,
+        percentiles=None,
         colors=channel_colors,
         active=channel_active,
     )
@@ -650,8 +687,8 @@ def create_ome_zarr_from_array(
     levels: int | list[str] = 5,
     xy_scaling_factor: float = 2.0,
     z_scaling_factor: float = 1.0,
-    space_unit: SpaceUnits | str | None = None,
-    time_unit: TimeUnits | str | None = None,
+    space_unit: SpaceUnits = DefaultSpaceUnit,
+    time_unit: TimeUnits = DefaultTimeUnit,
     axes_names: Collection[str] | None = None,
     channel_labels: list[str] | None = None,
     channel_wavelengths: list[str] | None = None,
@@ -661,7 +698,7 @@ def create_ome_zarr_from_array(
     name: str | None = None,
     chunks: Collection[int] | None = None,
     overwrite: bool = False,
-    version: NgffVersion = "0.4",
+    version: NgffVersions = DefaultNgffVersion,
 ) -> OmeZarrContainer:
     """Create an OME-Zarr image from a numpy array.
 
@@ -678,10 +715,10 @@ def create_ome_zarr_from_array(
             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.
@@ -700,9 +737,9 @@ def create_ome_zarr_from_array(
         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 DefaultNgffVersion.
     """
-    handler = _create_empty_image(
+    handler = create_empty_image_container(
         store=store,
         shape=array.shape,
         pixelsize=xy_pixelsize,
@@ -725,7 +762,7 @@ def create_ome_zarr_from_array(
     image = ome_zarr.get_image()
     image.set_array(array)
     image.consolidate()
-    ome_zarr.initialize_channel_meta(
+    ome_zarr.set_channel_meta(
         labels=channel_labels,
         wavelength_id=channel_wavelengths,
         percentiles=percentiles,

ngio/ome_zarr_meta/__init__.py

@@ -16,12 +16,13 @@ from ngio.ome_zarr_meta.ngio_specs import (
     AxesMapper,
     Dataset,
     ImageInWellPath,
-    NgffVersion,
+    NgffVersions,
     NgioImageMeta,
     NgioLabelMeta,
     NgioPlateMeta,
     NgioWellMeta,
     PixelSize,
+    path_in_well_validation,
 )
 
 __all__ = [
@@ -32,8 +33,8 @@ __all__ = [
     "ImageMetaHandler",
     "LabelMetaHandler",
     "LabelMetaHandler",
-    "NgffVersion",
-    "NgffVersion",
+    "NgffVersions",
+    "NgffVersions",
     "NgioImageMeta",
     "NgioLabelMeta",
     "NgioPlateMeta",
@@ -47,4 +48,5 @@ __all__ = [
     "get_label_meta_handler",
     "get_plate_meta_handler",
     "get_well_meta_handler",
+    "path_in_well_validation",
 ]

ngio/ome_zarr_meta/ngio_specs/__init__.py

@@ -15,6 +15,8 @@ from ngio.ome_zarr_meta.ngio_specs._axes import (
     AxesTranspose,
     Axis,
     AxisType,
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
     SpaceUnits,
     TimeUnits,
     canonical_axes_order,
@@ -32,10 +34,12 @@ from ngio.ome_zarr_meta.ngio_specs._ngio_hcs import (
     ImageInWellPath,
     NgioPlateMeta,
     NgioWellMeta,
+    path_in_well_validation,
 )
 from ngio.ome_zarr_meta.ngio_specs._ngio_image import (
+    DefaultNgffVersion,
     ImageLabelSource,
-    NgffVersion,
+    NgffVersions,
     NgioImageLabelMeta,
     NgioImageMeta,
     NgioLabelMeta,
@@ -55,9 +59,12 @@ __all__ = [
     "ChannelVisualisation",
     "ChannelsMeta",
     "Dataset",
+    "DefaultNgffVersion",
+    "DefaultSpaceUnit",
+    "DefaultTimeUnit",
     "ImageInWellPath",
     "ImageLabelSource",
-    "NgffVersion",
+    "NgffVersions",
     "NgioColors",
     "NgioImageLabelMeta",
     "NgioImageMeta",
@@ -70,4 +77,5 @@ __all__ = [
     "canonical_axes_order",
     "canonical_label_axes_order",
     "default_channel_name",
+    "path_in_well_validation",
 ]

ngio/ome_zarr_meta/ngio_specs/_axes.py

@@ -3,7 +3,7 @@
 from collections.abc import Collection
 from enum import Enum
 from logging import Logger
-from typing import TypeVar
+from typing import Literal, TypeVar
 
 import numpy as np
 from pydantic import BaseModel, ConfigDict, Field
@@ -32,98 +32,108 @@ class AxisType(str, Enum):
     space = "space"
 
 
-class SpaceUnits(str, Enum):
-    """Allowed space units."""
-
-    nanometer = "nanometer"
-    nm = "nm"
-    micrometer = "micrometer"
-    um = "um"
-    millimeter = "millimeter"
-    mm = "mm"
-    centimeter = "centimeter"
-    cm = "cm"
-
-    @classmethod
-    def default(cls) -> "SpaceUnits":
-        return SpaceUnits.um
-
-
-class TimeUnits(str, Enum):
-    """Allowed time units."""
-
-    seconds = "seconds"
-    s = "s"
-
-    @classmethod
-    def default(cls) -> "TimeUnits":
-        return TimeUnits.s
+SpaceUnits = Literal[
+    "micrometer",
+    "nanometer",
+    "angstrom",
+    "picometer",
+    "millimeter",
+    "centimeter",
+    "decimeter",
+    "meter",
+    "inch",
+    "foot",
+    "yard",
+    "mile",
+    "kilometer",
+    "hectometer",
+    "megameter",
+    "gigameter",
+    "terameter",
+    "petameter",
+    "exameter",
+    "parsec",
+    "femtometer",
+    "attometer",
+    "zeptometer",
+    "yoctometer",
+    "zettameter",
+    "yottameter",
+]
+DefaultSpaceUnit = "micrometer"
+
+TimeUnits = Literal[
+    "attosecond",
+    "centisecond",
+    "day",
+    "decisecond",
+    "exasecond",
+    "femtosecond",
+    "gigasecond",
+    "hectosecond",
+    "hour",
+    "kilosecond",
+    "megasecond",
+    "microsecond",
+    "millisecond",
+    "minute",
+    "nanosecond",
+    "petasecond",
+    "picosecond",
+    "second",
+    "terasecond",
+    "yoctosecond",
+    "yottasecond",
+    "zeptosecond",
+    "zettasecond",
+]
+DefaultTimeUnit = "second"
 
 
 class Axis(BaseModel):
     """Axis infos model."""
 
     on_disk_name: str
-    unit: SpaceUnits | TimeUnits | None = None
+    unit: str | None = None
     axis_type: AxisType | None = None
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
     def implicit_type_cast(self, cast_type: AxisType) -> "Axis":
+        unit = self.unit
         if self.axis_type != cast_type:
             logger.warning(
                 f"Axis {self.on_disk_name} has type {self.axis_type}. "
                 f"Casting to {cast_type}."
             )
-        new_axis = Axis(
-            on_disk_name=self.on_disk_name, axis_type=cast_type, unit=self.unit
-        )
-        if cast_type == AxisType.time and not isinstance(self.unit, TimeUnits):
+
+        if cast_type == AxisType.time and unit is None:
             logger.warning(
                 f"Time axis {self.on_disk_name} has unit {self.unit}. "
-                f"Casting to {TimeUnits.default()}."
-            )
-            new_axis = Axis(
-                on_disk_name=self.on_disk_name,
-                axis_type=AxisType.time,
-                unit=TimeUnits.default(),
-            )
-        elif cast_type == AxisType.space and not isinstance(self.unit, SpaceUnits):
-            logger.warning(
-                f"Space axis {self.on_disk_name} has unit {self.unit}. "
-                f"Casting to {SpaceUnits.default()}."
+                f"Casting to {DefaultSpaceUnit}."
             )
-            new_axis = Axis(
-                on_disk_name=self.on_disk_name,
-                axis_type=AxisType.space,
-                unit=SpaceUnits.default(),
-            )
-        elif cast_type == AxisType.channel and self.unit is not None:
+            unit = DefaultTimeUnit
+
+        if cast_type == AxisType.space and unit is None:
             logger.warning(
-                f"Channel axis {self.on_disk_name} has unit {self.unit}. Removing unit."
-            )
-            new_axis = Axis(
-                on_disk_name=self.on_disk_name,
-                axis_type=AxisType.channel,
-                unit=None,
+                f"Space axis {self.on_disk_name} has unit {unit}. "
+                f"Casting to {DefaultSpaceUnit}."
             )
-        return new_axis
+            unit = DefaultSpaceUnit
+
+        return Axis(on_disk_name=self.on_disk_name, axis_type=cast_type, unit=unit)
 
     def canonical_axis_cast(self, canonical_name: str) -> "Axis":
         """Cast the implicit axis to the correct type."""
         match canonical_name:
             case "t":
-                if self.axis_type != AxisType.time or not isinstance(
-                    self.unit, TimeUnits
-                ):
+                if self.axis_type != AxisType.time or self.unit is None:
                     return self.implicit_type_cast(AxisType.time)
             case "c":
-                if self.axis_type != AxisType.channel or self.unit is not None:
+                if self.axis_type != AxisType.channel:
                     return self.implicit_type_cast(AxisType.channel)
             case "z" | "y" | "x":
-                if self.axis_type != AxisType.space or not isinstance(
-                    self.unit, SpaceUnits
-                ):
+                if self.axis_type != AxisType.space or self.unit is None:
                     return self.implicit_type_cast(AxisType.space)
         return self
 
@@ -345,6 +355,11 @@ class AxesMapper:
                 _index_mapping[canonical_key] = None
         return _index_mapping
 
+    @property
+    def axes_setup(self) -> AxesSetup:
+        """Return the axes setup."""
+        return self._axes_setup
+
     @property
     def on_disk_axes(self) -> list[Axis]:
         return list(self._on_disk_axes)
@@ -353,6 +368,16 @@ class AxesMapper:
     def on_disk_axes_names(self) -> list[str]:
         return [ax.on_disk_name for ax in self._on_disk_axes]
 
+    @property
+    def allow_non_canonical_axes(self) -> bool:
+        """Return if non canonical axes are allowed."""
+        return self._allow_non_canonical_axes
+
+    @property
+    def strict_canonical_order(self) -> bool:
+        """Return if strict canonical order is enforced."""
+        return self._strict_canonical_order
+
     def get_index(self, name: str) -> int | None:
         """Get the index of the axis by name."""
         if name not in self._index_mapping.keys():
@@ -443,8 +468,8 @@ class AxesMapper:
 
 def canonical_axes(
     axes_names: Collection[str],
-    space_units: SpaceUnits | None = None,
-    time_units: TimeUnits | None = None,
+    space_units: SpaceUnits | None = DefaultSpaceUnit,
+    time_units: TimeUnits | None = DefaultTimeUnit,
 ) -> list[Axis]:
     """Create a new canonical axes mapper.
 

ngio/ome_zarr_meta/ngio_specs/_dataset.py

@@ -6,6 +6,9 @@ from ngio.ome_zarr_meta.ngio_specs._axes import (
     AxesMapper,
     AxesSetup,
     Axis,
+    AxisType,
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
     SpaceUnits,
     TimeUnits,
 )
@@ -86,7 +89,7 @@ class Dataset:
         return self._path
 
     @property
-    def space_unit(self) -> SpaceUnits:
+    def space_unit(self) -> str | None:
         """Return the space unit for a given axis."""
         x_axis = self._axes_mapper.get_axis("x")
         y_axis = self._axes_mapper.get_axis("y")
@@ -97,8 +100,6 @@ class Dataset:
             )
 
         if x_axis.unit == y_axis.unit:
-            if not isinstance(x_axis.unit, SpaceUnits):
-                raise NgioValidationError("The space unit must be of type SpaceUnits.")
             return x_axis.unit
         else:
             raise NgioValidationError(
@@ -107,13 +108,11 @@ class Dataset:
             )
 
     @property
-    def time_unit(self) -> TimeUnits | None:
+    def time_unit(self) -> str | None:
         """Return the time unit for a given axis."""
         t_axis = self._axes_mapper.get_axis("t")
         if t_axis is None:
             return None
-        if not isinstance(t_axis.unit, TimeUnits):
-            raise NgioValidationError("The time unit must be of type TimeUnits.")
         return t_axis.unit
 
     @property
@@ -124,11 +123,50 @@ class Dataset:
             y=self.get_scale("y"),
             z=self.get_scale("z"),
             t=self.get_scale("t"),
-            space_unit=self.space_unit,
-            time_unit=self.time_unit,
+            space_unit=self.space_unit,  # type: ignore
+            time_unit=self.time_unit,  # type: ignore
         )
 
     @property
     def axes_mapper(self) -> AxesMapper:
         """Return the axes mapper object."""
         return self._axes_mapper
+
+    def to_units(
+        self,
+        *,
+        space_unit: SpaceUnits = DefaultSpaceUnit,
+        time_unit: TimeUnits = DefaultTimeUnit,
+    ) -> "Dataset":
+        """Convert the pixel size to the given units.
+
+        Args:
+            space_unit(str): The space unit to convert to.
+            time_unit(str): The time unit to convert to.
+        """
+        new_axes = []
+        for ax in self.axes_mapper.on_disk_axes:
+            if ax.axis_type == AxisType.space:
+                new_ax = Axis(
+                    on_disk_name=ax.on_disk_name,
+                    axis_type=ax.axis_type,
+                    unit=space_unit,
+                )
+                new_axes.append(new_ax)
+            elif ax.axis_type == AxisType.time:
+                new_ax = Axis(
+                    on_disk_name=ax.on_disk_name, axis_type=ax.axis_type, unit=time_unit
+                )
+                new_axes.append(new_ax)
+            else:
+                new_axes.append(ax)
+
+        return Dataset(
+            path=self.path,
+            on_disk_axes=new_axes,
+            on_disk_scale=self._on_disk_scale,
+            on_disk_translation=self._on_disk_translation,
+            axes_setup=self.axes_mapper.axes_setup,
+            allow_non_canonical_axes=self.axes_mapper.allow_non_canonical_axes,
+            strict_canonical_order=self.axes_mapper.strict_canonical_order,
+        )