ngio 0.2.0b3__py3-none-any.whl → 0.2.2__py3-none-any.whl

ngio/images/{omezarr_container.py → 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
@@ -14,13 +14,17 @@ from ngio.ome_zarr_meta import (
     PixelSize,
 )
 from ngio.ome_zarr_meta.ngio_specs import (
+    DefaultNgffVersion,
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
+    NgffVersions,
     SpaceUnits,
     TimeUnits,
 )
 from ngio.tables import (
     FeatureTable,
     GenericRoiTable,
-    MaskingROITable,
+    MaskingRoiTable,
     RoiTable,
     Table,
     TablesContainer,
@@ -155,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,
@@ -165,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,
@@ -174,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,
@@ -193,7 +227,7 @@ class OmeZarrContainer:
         """Get an image at a specific level.
 
         Args:
-            path (str | None): The path to the image in the omezarr file.
+            path (str | None): The path to the image in the ome_zarr file.
             pixel_size (PixelSize | None): The pixel size of the image.
             strict (bool): Only used if the pixel size is provided. If True, the
                 pixel size must match the image pixel size exactly. If False, the
@@ -217,7 +251,7 @@ class OmeZarrContainer:
         Args:
             masking_label_name (str): The name of the label.
             masking_table_name (str | None): The name of the masking table.
-            path (str | None): The path to the image in the omezarr file.
+            path (str | None): The path to the image in the ome_zarr file.
             pixel_size (PixelSize | None): The pixel size of the image.
             strict (bool): Only used if the pixel size is provided. If True, the
                 pixel size must match the image pixel size exactly. If False, the
@@ -250,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,
@@ -268,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.
@@ -283,6 +319,7 @@ class OmeZarrContainer:
             labels=labels,
             pixel_size=pixel_size,
             axes_names=axes_names,
+            name=name,
             chunks=chunks,
             dtype=dtype,
             overwrite=overwrite,
@@ -292,21 +329,21 @@ class OmeZarrContainer:
             store, cache=self._group_handler.use_cache, mode=self._group_handler.mode
         )
 
-        new_omezarr = OmeZarrContainer(
+        new_ome_zarr = OmeZarrContainer(
             group_handler=handler,
             validate_arrays=False,
         )
 
         if copy_labels:
             self.labels_container._group_handler.copy_handler(
-                new_omezarr.labels_container._group_handler
+                new_ome_zarr.labels_container._group_handler
             )
 
         if copy_tables:
             self.tables_container._group_handler.copy_handler(
-                new_omezarr.tables_container._group_handler
+                new_ome_zarr.tables_container._group_handler
             )
-        return new_omezarr
+        return new_ome_zarr
 
     def list_tables(self) -> list[str]:
         """List all tables in the image."""
@@ -325,7 +362,7 @@ class OmeZarrContainer:
     @overload
     def get_table(
         self, name: str, check_type: Literal["masking_roi_table"]
-    ) -> MaskingROITable: ...
+    ) -> MaskingRoiTable: ...
 
     @overload
     def get_table(
@@ -348,7 +385,7 @@ class OmeZarrContainer:
                     )
                 return table
             case "masking_roi_table":
-                if not isinstance(table, MaskingROITable):
+                if not isinstance(table, MaskingRoiTable):
                     raise NgioValueError(
                         f"Table '{name}' is not a masking ROI table. "
                         f"Found type: {table.type()}"
@@ -379,7 +416,7 @@ class OmeZarrContainer:
         """Compute the ROI table for an image."""
         return self.get_image().build_image_roi_table(name=name)
 
-    def build_masking_roi_table(self, label: str) -> MaskingROITable:
+    def build_masking_roi_table(self, label: str) -> MaskingRoiTable:
         """Compute the masking ROI table for a label."""
         return self.get_label(label).build_masking_roi_table()
 
@@ -410,7 +447,7 @@ class OmeZarrContainer:
 
         Args:
             name (str): The name of the label.
-            path (str | None): The path to the image in the omezarr file.
+            path (str | None): The path to the image in the ome_zarr file.
             pixel_size (PixelSize | None): The pixel size of the image.
             strict (bool): Only used if the pixel size is provided. If True, the
                 pixel size must match the image pixel size exactly. If False, the
@@ -435,7 +472,7 @@ class OmeZarrContainer:
             label_name (str): The name of the label.
             masking_label_name (str): The name of the masking label.
             masking_table_name (str | None): The name of the masking table.
-            path (str | None): The path to the image in the omezarr file.
+            path (str | None): The path to the image in the ome_zarr file.
             pixel_size (PixelSize | None): The pixel size of the image.
             strict (bool): Only used if the pixel size is provided. If True, the
                 pixel size must match the image pixel size exactly. If False, the
@@ -507,7 +544,7 @@ class OmeZarrContainer:
         )
 
 
-def open_omezarr_container(
+def open_ome_zarr_container(
     store: StoreOrGroup,
     cache: bool = False,
     mode: AccessModeLiteral = "r+",
@@ -533,7 +570,7 @@ def open_image(
 
     Args:
         store (StoreOrGroup): The Zarr store or group to create the image in.
-        path (str | None): The path to the image in the omezarr file.
+        path (str | None): The path to the image in the ome_zarr file.
         pixel_size (PixelSize | None): The pixel size of the image.
         strict (bool): Only used if the pixel size is provided. If True, the
                 pixel size must match the image pixel size exactly. If False, the
@@ -551,7 +588,7 @@ def open_image(
     )
 
 
-def create_empty_omezarr(
+def create_empty_ome_zarr(
     store: StoreOrGroup,
     shape: Collection[int],
     xy_pixelsize: float,
@@ -560,8 +597,8 @@ def create_empty_omezarr(
     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,
@@ -572,7 +609,7 @@ def create_empty_omezarr(
     channel_colors: Collection[str] | None = None,
     channel_active: Collection[bool] | None = None,
     overwrite: bool = False,
-    version: str = "0.4",
+    version: NgffVersions = DefaultNgffVersion,
 ) -> OmeZarrContainer:
     """Create an empty OME-Zarr image with the given shape and metadata.
 
@@ -589,10 +626,10 @@ def create_empty_omezarr(
             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.
@@ -611,10 +648,10 @@ def create_empty_omezarr(
             active. Defaults to None.
         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".
+        version (NgffVersion, optional): The version of the OME-Zarr specification.
+            Defaults to DefaultNgffVersion.
     """
-    handler = _create_empty_image(
+    handler = create_empty_image_container(
         store=store,
         shape=shape,
         pixelsize=xy_pixelsize,
@@ -633,18 +670,18 @@ def create_empty_omezarr(
         version=version,
     )
 
-    omezarr = OmeZarrContainer(group_handler=handler)
-    omezarr.initialize_channel_meta(
+    ome_zarr = OmeZarrContainer(group_handler=handler)
+    ome_zarr.set_channel_meta(
         labels=channel_labels,
         wavelength_id=channel_wavelengths,
         percentiles=percentiles,
         colors=channel_colors,
         active=channel_active,
     )
-    return omezarr
+    return ome_zarr
 
 
-def create_omezarr_from_array(
+def create_ome_zarr_from_array(
     store: StoreOrGroup,
     array: np.ndarray,
     xy_pixelsize: float,
@@ -653,8 +690,8 @@ def create_omezarr_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,
@@ -664,7 +701,7 @@ def create_omezarr_from_array(
     name: str | None = None,
     chunks: Collection[int] | None = None,
     overwrite: bool = False,
-    version: str = "0.4",
+    version: NgffVersions = DefaultNgffVersion,
 ) -> OmeZarrContainer:
     """Create an OME-Zarr image from a numpy array.
 
@@ -681,10 +718,10 @@ def create_omezarr_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.
@@ -703,9 +740,9 @@ def create_omezarr_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,
@@ -724,15 +761,15 @@ def create_omezarr_from_array(
         version=version,
     )
 
-    omezarr = OmeZarrContainer(group_handler=handler)
-    image = omezarr.get_image()
+    ome_zarr = OmeZarrContainer(group_handler=handler)
+    image = ome_zarr.get_image()
     image.set_array(array)
     image.consolidate()
-    omezarr.initialize_channel_meta(
+    ome_zarr.set_channel_meta(
         labels=channel_labels,
         wavelength_id=channel_wavelengths,
         percentiles=percentiles,
         colors=channel_colors,
         active=channel_active,
     )
-    return omezarr
+    return ome_zarr

ngio/ome_zarr_meta/__init__.py

@@ -16,11 +16,13 @@ from ngio.ome_zarr_meta.ngio_specs import (
     AxesMapper,
     Dataset,
     ImageInWellPath,
+    NgffVersions,
     NgioImageMeta,
     NgioLabelMeta,
     NgioPlateMeta,
     NgioWellMeta,
     PixelSize,
+    path_in_well_validation,
 )
 
 __all__ = [
@@ -31,6 +33,8 @@ __all__ = [
     "ImageMetaHandler",
     "LabelMetaHandler",
     "LabelMetaHandler",
+    "NgffVersions",
+    "NgffVersions",
     "NgioImageMeta",
     "NgioLabelMeta",
     "NgioPlateMeta",
@@ -44,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,9 +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,
+    NgffVersions,
     NgioImageLabelMeta,
     NgioImageMeta,
     NgioLabelMeta,
@@ -54,8 +59,12 @@ __all__ = [
     "ChannelVisualisation",
     "ChannelsMeta",
     "Dataset",
+    "DefaultNgffVersion",
+    "DefaultSpaceUnit",
+    "DefaultTimeUnit",
     "ImageInWellPath",
     "ImageLabelSource",
+    "NgffVersions",
     "NgioColors",
     "NgioImageLabelMeta",
     "NgioImageMeta",
@@ -68,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.