ngio 0.2.0a2__py3-none-any.whl → 0.5.0b4__py3-none-any.whl

ngio/ome_zarr_meta/ngio_specs/_ngio_image.py

@@ -6,71 +6,144 @@ But they can be built from the OME standard metadata, and the
 can be converted to the OME standard.
 """
 
-from collections.abc import Collection
-from enum import Enum
-from typing import Any, TypeVar
+from collections.abc import Sequence
+from typing import Any, Literal, TypeVar
 
 import numpy as np
 from pydantic import BaseModel
 
 from ngio.ome_zarr_meta.ngio_specs._axes import (
+    AxesHandler,
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
     SpaceUnits,
     TimeUnits,
-    canonical_axes,
 )
-from ngio.ome_zarr_meta.ngio_specs._channels import Channel, ChannelsMeta
+from ngio.ome_zarr_meta.ngio_specs._channels import ChannelsMeta
 from ngio.ome_zarr_meta.ngio_specs._dataset import Dataset
 from ngio.ome_zarr_meta.ngio_specs._pixel_size import PixelSize
 from ngio.utils import NgioValidationError, NgioValueError
 
 T = TypeVar("T")
-
-
-class NgffVersion(str, Enum):
-    """Allowed NGFF versions."""
-
-    v04 = "0.4"
+NgffVersions = Literal["0.4", "0.5"]
+DefaultNgffVersion: Literal["0.4"] = "0.4"
 
 
 class ImageLabelSource(BaseModel):
     """Image label source model."""
 
-    version: NgffVersion
+    version: NgffVersions
     source: dict[str, str | None]
 
     @classmethod
-    def default_init(cls, version: NgffVersion) -> "ImageLabelSource":
+    def default_init(cls, version: NgffVersions) -> "ImageLabelSource":
         """Initialize the ImageLabelSource object."""
         return cls(version=version, source={"image": "../../"})
 
 
+class NgioLabelsGroupMeta(BaseModel):
+    """Metadata model for the /labels group in OME-NGFF."""
+
+    version: NgffVersions
+    labels: list[str]
+
+
 class AbstractNgioImageMeta:
     """Base class for ImageMeta and LabelMeta."""
 
-    def __init__(self, version: str, name: str | None, datasets: list[Dataset]) -> None:
+    def __init__(
+        self, version: NgffVersions, name: str | None, datasets: list[Dataset]
+    ) -> None:
         """Initialize the ImageMeta object."""
-        self._version = NgffVersion(version)
+        self._version = version
         self._name = name
 
         if len(datasets) == 0:
             raise NgioValidationError("At least one dataset must be provided.")
 
         self._datasets = datasets
+        self._axes_handler = datasets[0].axes_handler
 
     def __repr__(self):
         class_name = type(self).__name__
         paths = [dataset.path for dataset in self.datasets]
-        on_disk_axes = self.datasets[0].axes_mapper.on_disk_axes_names
-        return (
-            f"{class_name}(name={self.name}, "
-            f"datasets={paths}, "
-            f"on_disk_axes={on_disk_axes})"
+        axes = self.axes_handler.axes_names
+        return f"{class_name}(name={self.name}, datasets={paths}, axes={axes})"
+
+    @classmethod
+    def default_init(
+        cls,
+        levels: Sequence[str],
+        axes_handler: AxesHandler,
+        scales: Sequence[tuple[float, ...]],
+        translations: Sequence[tuple[float, ...] | None],
+        name: str | None = None,
+        version: NgffVersions = DefaultNgffVersion,
+    ):
+        """Initialize the ImageMeta object."""
+        datasets = []
+        for level, scale, translation in zip(levels, scales, translations, strict=True):
+            dataset = Dataset(
+                path=level,
+                axes_handler=axes_handler,
+                scale=scale,
+                translation=translation,
+            )
+            datasets.append(dataset)
+
+        return cls(
+            version=version,
+            name=name,
+            datasets=datasets,
+        )
+
+    def to_units(
+        self,
+        *,
+        space_unit: SpaceUnits = DefaultSpaceUnit,
+        time_unit: TimeUnits = DefaultTimeUnit,
+    ):
+        """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_handler = self.axes_handler.to_units(
+            space_unit=space_unit,
+            time_unit=time_unit,
+        )
+        new_datasets = []
+        for dataset in self.datasets:
+            new_dataset = Dataset(
+                path=dataset.path,
+                axes_handler=new_axes_handler,
+                scale=dataset.scale,
+                translation=dataset.translation,
+            )
+            new_datasets.append(new_dataset)
+
+        return type(self)(
+            version=self.version,
+            name=self.name,
+            datasets=new_datasets,
         )
 
     @property
-    def version(self) -> NgffVersion:
+    def version(self) -> NgffVersions:
         """Version of the OME-NFF metadata used to build the object."""
-        return self._version
+        return self._version  # type: ignore (version is a Literal type)
+
+    @property
+    def zarr_format(self) -> Literal[2, 3]:
+        """Zarr version used to store the data."""
+        match self.version:
+            case "0.4":
+                return 2
+            case "0.5":
+                return 3
+            case _:
+                raise NgioValueError(f"Unsupported NGFF version: {self.version}")
 
     @property
     def name(self) -> str | None:
@@ -82,6 +155,11 @@ class AbstractNgioImageMeta:
         """List of datasets in the multiscale."""
         return self._datasets
 
+    @property
+    def axes_handler(self):
+        """Return the axes mapper."""
+        return self._axes_handler
+
     @property
     def levels(self) -> int:
         """Number of levels in the multiscale."""
@@ -92,6 +170,16 @@ class AbstractNgioImageMeta:
         """List of paths of the datasets."""
         return [dataset.path for dataset in self.datasets]
 
+    @property
+    def space_unit(self) -> str | None:
+        """Get the space unit of the pixel size."""
+        return self.axes_handler.space_unit
+
+    @property
+    def time_unit(self) -> str | None:
+        """Get the time unit of the pixel size."""
+        return self.axes_handler.time_unit
+
     def _get_dataset_by_path(self, path: str) -> Dataset:
         """Get a dataset by its path."""
         for dataset in self.datasets:
@@ -105,49 +193,102 @@ class AbstractNgioImageMeta:
             raise NgioValueError(f"Index {idx} out of range.")
         return self.datasets[idx]
 
-    def _get_dataset_by_pixel_size(
-        self, pixel_size: PixelSize, strict: bool = False, tol: float = 1e-6
-    ) -> Dataset:
-        """Get a dataset with the closest pixel size.
+    def _find_closest_dataset(
+        self, pixel_size: PixelSize, mode: str = "any"
+    ) -> Dataset | None:
+        """Find the closest dataset to the given pixel size.
 
         Args:
             pixel_size(PixelSize): The pixel size to search for.
-            strict(bool): If True, the pixel size must smaller than tol.
-            tol(float): Any pixel size with a distance less than tol will be considered.
+            mode(str): The mode to find the closest dataset.
+                "any": Will find the closest dataset.
+                "lr": Will find closest "lower" resolution dataset.
+                "hr": Will find closest "higher" resolution
         """
         min_dist = np.inf
-
         closest_dataset = None
-        for dataset in self.datasets:
-            dist = dataset.pixel_size.distance(pixel_size)
+
+        if mode == "any":
+            datasets = self.datasets
+        elif mode == "lr":
+            # Lower resolution means that the pixel size is larger.
+            datasets = [d for d in self.datasets if d.pixel_size > pixel_size]
+        elif mode == "hr":
+            # Higher resolution means that the pixel size is smaller.
+            datasets = [d for d in self.datasets if d.pixel_size < pixel_size]
+        else:
+            raise NgioValueError(f"Mode {mode} not recognized.")
+
+        for d in datasets:
+            dist = d.pixel_size.distance(pixel_size)
             if dist < min_dist:
                 min_dist = dist
-                closest_dataset = dataset
+                closest_dataset = d
+
+        return closest_dataset
+
+    def _get_closest_dataset(
+        self, pixel_size: PixelSize, strict: bool = False
+    ) -> Dataset:
+        """Get a dataset with the closest pixel size.
+
+        Args:
+            pixel_size(PixelSize): The pixel size to search for.
+            strict(bool): If True, the pixel size must be exactly the same.
+        """
+        closest_dataset = self._find_closest_dataset(pixel_size, mode="any")
 
         if closest_dataset is None:
             raise NgioValueError("No dataset found.")
 
-        if strict and min_dist > tol:
-            raise NgioValueError("No dataset with a pixel size close enough.")
-
+        if strict and closest_dataset.pixel_size != pixel_size:
+            raise NgioValueError(
+                "No dataset with a pixel size close enough. "
+                "Best match is "
+                f"{closest_dataset.path}:{closest_dataset.pixel_size}"
+            )
         return closest_dataset
 
+    def get_lowest_resolution_dataset(self) -> Dataset:
+        """Get the dataset with the lowest resolution."""
+        dataset = self.datasets[-1]
+        while True:
+            lower_res_dataset = self._find_closest_dataset(
+                dataset.pixel_size, mode="lr"
+            )
+            if lower_res_dataset is None:
+                break
+            dataset = lower_res_dataset
+        return dataset
+
+    def get_highest_resolution_dataset(self) -> Dataset:
+        """Get the dataset with the highest resolution."""
+        dataset = self.datasets[0]
+        while True:
+            higher_res_dataset = self._find_closest_dataset(
+                dataset.pixel_size, mode="hr"
+            )
+            if higher_res_dataset is None:
+                break
+            dataset = higher_res_dataset
+        return dataset
+
     def get_dataset(
         self,
         *,
         path: str | None = None,
         idx: int | None = None,
         pixel_size: PixelSize | None = None,
-        highest_resolution: bool = False,
         strict: bool = False,
     ) -> Dataset:
         """Get a dataset by its path, index or pixel size.
 
+        If all arguments are None, the dataset with the highest resolution is returned.
+
         Args:
             path(str): The path of the dataset.
             idx(int): The index of the dataset.
             pixel_size(PixelSize): The pixel size to search for.
-            highest_resolution(bool): If True, the dataset with the highest resolution
             strict(bool): If True, the pixel size must be exactly the same.
                 If pixel_size is None, strict is ignored.
         """
@@ -158,115 +299,41 @@ class AbstractNgioImageMeta:
                     path is not None,
                     idx is not None,
                     pixel_size is not None,
-                    highest_resolution,
                 ]
             )
-            != 1
+            > 1
         ):
-            raise NgioValueError("get_dataset must receive only one argument.")
+            raise NgioValueError("get_dataset must receive only one argument or None.")
 
         if path is not None:
             return self._get_dataset_by_path(path)
         elif idx is not None:
             return self._get_dataset_by_index(idx)
         elif pixel_size is not None:
-            return self._get_dataset_by_pixel_size(pixel_size, strict=strict)
-        elif highest_resolution:
-            return self.get_highest_resolution_dataset()
+            return self._get_closest_dataset(pixel_size, strict=strict)
         else:
-            raise NgioValueError("get_dataset has no valid arguments.")
-
-    @classmethod
-    def default_init(
-        cls,
-        levels: int | Collection[str],
-        axes_names: Collection[str],
-        pixel_size: PixelSize,
-        scaling_factors: Collection[float] | None = None,
-        name: str | None = None,
-        version: str = "0.4",
-    ):
-        """Initialize the ImageMeta object."""
-        axes = canonical_axes(
-            axes_names,
-            space_units=pixel_size.space_unit,
-            time_units=pixel_size.time_unit,
-        )
-
-        px_size_dict = pixel_size.as_dict()
-        scale = [px_size_dict.get(ax.on_disk_name, 1.0) for ax in axes]
-        translation = [0.0] * len(scale)
-
-        if scaling_factors is None:
-            _default = {"x": 2.0, "y": 2.0}
-            scaling_factors = [_default.get(ax.on_disk_name, 1.0) for ax in axes]
-
-        if isinstance(levels, int):
-            levels = [str(i) for i in range(levels)]
-
-        datasets = []
-        for level in levels:
-            dataset = Dataset(
-                path=level,
-                on_disk_axes=axes,
-                on_disk_scale=scale,
-                on_disk_translation=translation,
-                allow_non_canonical_axes=False,
-                strict_canonical_order=True,
-            )
-            datasets.append(dataset)
-            scale = [s * f for s, f in zip(scale, scaling_factors, strict=True)]
-
-        return cls(
-            version=version,
-            name=name,
-            datasets=datasets,
-        )
-
-    def get_highest_resolution_dataset(self) -> Dataset:
-        """Get the dataset with the highest resolution."""
-        return self._get_dataset_by_pixel_size(
-            pixel_size=PixelSize(
-                x=0.0,
-                y=0.0,
-                z=0.0,
-                t=0.0,
-                space_unit=SpaceUnits.micrometer,
-                time_unit=TimeUnits.s,
-            ),
-            strict=False,
-        )
-
-    def get_scaling_factor(self, axis_name: str) -> float:
-        """Get the scaling factors of the dataset."""
-        scaling_factors = []
-        for d1, d2 in zip(self.datasets[1:], self.datasets[:-1], strict=True):
-            scale_d1 = d1.get_scale(axis_name)
-            scale_d2 = d2.get_scale(axis_name)
-            scaling_factors.append(scale_d1 / scale_d2)
-
-        if not np.allclose(scaling_factors, scaling_factors[0]):
-            raise NgioValidationError(
-                f"Inconsistent scaling factors are not supported. {scaling_factors}"
-            )
-        return scaling_factors[0]
+            return self.get_highest_resolution_dataset()
 
-    @property
-    def xy_scaling_factor(self) -> float:
-        """Get the xy scaling factor of the dataset."""
-        x_scaling_factors = self.get_scaling_factor("x")
-        y_scaling_factors = self.get_scaling_factor("y")
-        if not np.isclose(x_scaling_factors, y_scaling_factors):
-            raise NgioValidationError(
-                "Inconsistent scaling factors are not supported. "
-                f"{x_scaling_factors}, {y_scaling_factors}"
+    def _get_closest_datasets(self, path: str | None = None) -> tuple[Dataset, Dataset]:
+        """Get the closest datasets to a dataset."""
+        dataset = self.get_dataset(path=path)
+        lr_dataset = self._find_closest_dataset(dataset.pixel_size, mode="lr")
+        if lr_dataset is None:
+            raise NgioValueError(
+                "No lower resolution dataset found. "
+                "This is the lowest resolution dataset."
             )
-        return x_scaling_factors
+        return dataset, lr_dataset
 
-    @property
-    def z_scaling_factor(self) -> float:
-        """Get the z scaling factor of the dataset."""
-        return self.get_scaling_factor("z")
+    def scaling_factor(self, path: str | None = None) -> tuple[float, ...]:
+        """Get the scaling factors to downscale to the next lower resolution dataset."""
+        if self.levels == 1:
+            return (1.0,) * len(self.axes_handler.axes_names)
+        dataset, lr_dataset = self._get_closest_datasets(path=path)
+        scale = dataset.scale
+        lr_scale = lr_dataset.scale
+        scaling_factors = [s / s_lr for s_lr, s in zip(scale, lr_scale, strict=True)]
+        return tuple(scaling_factors)
 
 
 class NgioLabelMeta(AbstractNgioImageMeta):
@@ -274,19 +341,13 @@ class NgioLabelMeta(AbstractNgioImageMeta):
 
     def __init__(
         self,
-        version: str,
+        version: NgffVersions,
         name: str | None,
         datasets: list[Dataset],
         image_label: ImageLabelSource | None = None,
     ) -> None:
         """Initialize the ImageMeta object."""
         super().__init__(version, name, datasets)
-
-        # Make sure that there are no channel axes
-        channel_axis = self.datasets[0].axes_mapper.get_axis("c")
-        if channel_axis is not None:
-            raise NgioValidationError("Label metadata must not have channel axes.")
-
         image_label = (
             ImageLabelSource.default_init(self.version)
             if image_label is None
@@ -319,7 +380,7 @@ class NgioImageMeta(AbstractNgioImageMeta):
 
     def __init__(
         self,
-        version: str,
+        version: NgffVersions,
         name: str | None,
         datasets: list[Dataset],
         channels: ChannelsMeta | None = None,
@@ -373,62 +434,5 @@ class NgioImageMeta(AbstractNgioImageMeta):
         )
         self.set_channels_meta(channels_meta=channels_meta)
 
-    @property
-    def channels(self) -> list[Channel]:
-        """Get the channels in the image."""
-        if self._channels_meta is None:
-            return []
-        assert self.channels_meta is not None
-        return self.channels_meta.channels
-
-    @property
-    def channel_labels(self) -> list[str]:
-        """Get the labels of the channels in the image."""
-        return [channel.label for channel in self.channels]
-
-    @property
-    def channel_wavelength_ids(self) -> list[str | None]:
-        """Get the wavelength IDs of the channels in the image."""
-        return [channel.wavelength_id for channel in self.channels]
-
-    def _get_channel_idx_by_label(self, label: str) -> int | None:
-        """Get the index of a channel by its label."""
-        if self._channels_meta is None:
-            return None
-
-        if label not in self.channel_labels:
-            raise NgioValueError(f"Channel with label {label} not found.")
-
-        return self.channel_labels.index(label)
-
-    def _get_channel_idx_by_wavelength_id(self, wavelength_id: str) -> int | None:
-        """Get the index of a channel by its wavelength ID."""
-        if self._channels_meta is None:
-            return None
-
-        if wavelength_id not in self.channel_wavelength_ids:
-            raise NgioValueError(
-                f"Channel with wavelength ID {wavelength_id} not found."
-            )
-
-        return self.channel_wavelength_ids.index(wavelength_id)
-
-    def get_channel_idx(
-        self, label: str | None = None, wavelength_id: str | None = None
-    ) -> int | None:
-        """Get the index of a channel by its label or wavelength ID."""
-        # Only one of the arguments must be provided
-        if sum([label is not None, wavelength_id is not None]) != 1:
-            raise NgioValueError("get_channel_idx must receive only one argument.")
-
-        if label is not None:
-            return self._get_channel_idx_by_label(label)
-        elif wavelength_id is not None:
-            return self._get_channel_idx_by_wavelength_id(wavelength_id)
-        else:
-            raise NgioValueError(
-                "get_channel_idx must receive either label or wavelength_id."
-            )
-
 
 NgioImageLabelMeta = NgioImageMeta | NgioLabelMeta

ngio/ome_zarr_meta/ngio_specs/_pixel_size.py

@@ -1,8 +1,18 @@
 """Fractal internal module for dataset metadata handling."""
 
+import math
+from functools import total_ordering
+from typing import overload
+
 import numpy as np
+from pydantic import BaseModel
 
-from ngio.ome_zarr_meta.ngio_specs import SpaceUnits, TimeUnits
+from ngio.ome_zarr_meta.ngio_specs import (
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
+    SpaceUnits,
+    TimeUnits,
+)
 
 ################################################################################################
 #
@@ -13,47 +23,75 @@ from ngio.ome_zarr_meta.ngio_specs import SpaceUnits, TimeUnits
 #################################################################################################
 
 
-def _validate_type(value: float, name: str) -> float:
-    """Check the type of the value."""
-    if not isinstance(value, int | float):
-        raise TypeError(f"{name} must be a number.")
-    return float(value)
-
-
-class PixelSize:
+@total_ordering
+class PixelSize(BaseModel):
     """PixelSize class to store the pixel size in 3D space."""
 
-    def __init__(
-        self,
-        x: float,
-        y: float,
-        z: float,
-        t: float = 0,
-        space_unit: SpaceUnits = SpaceUnits.micrometer,
-        time_unit: TimeUnits | None = TimeUnits.s,
-    ):
-        """Initialize the pixel size."""
-        self.x = _validate_type(x, "x")
-        self.y = _validate_type(y, "y")
-        self.z = _validate_type(z, "z")
-        self.t = _validate_type(t, "t")
-
-        if not isinstance(space_unit, SpaceUnits):
-            raise TypeError("space_unit must be of type SpaceUnits.")
-        self.space_unit = space_unit
-
-        if time_unit is not None and not isinstance(time_unit, TimeUnits):
-            raise TypeError("time_unit must be of type TimeUnits.")
-        self.time_unit = time_unit
+    x: float
+    y: float
+    z: float
+    t: float = 1
+    space_unit: SpaceUnits | str | None = DefaultSpaceUnit
+    time_unit: TimeUnits | str | None = DefaultTimeUnit
 
     def __repr__(self) -> str:
         """Return a string representation of the pixel size."""
         return f"PixelSize(x={self.x}, y={self.y}, z={self.z}, t={self.t})"
 
-    def as_dict(self) -> dict:
+    def __eq__(self, other) -> bool:
+        """Check if two pixel sizes are equal."""
+        if not isinstance(other, PixelSize):
+            raise TypeError("Can only compare PixelSize with PixelSize.")
+
+        if (
+            self.time_unit is not None
+            and other.time_unit is None
+            and self.time_unit != other.time_unit
+        ):
+            return False
+
+        if self.space_unit != other.space_unit:
+            return False
+        return math.isclose(self.distance(other), 0)
+
+    def __lt__(self, other: "PixelSize") -> bool:
+        """Check if one pixel size is less than the other."""
+        if not isinstance(other, PixelSize):
+            raise TypeError("Can only compare PixelSize with PixelSize.")
+        ref = PixelSize(
+            x=0,
+            y=0,
+            z=0,
+            t=0,
+            space_unit=self.space_unit,
+            time_unit=self.time_unit,  # type: ignore
+        )
+        return self.distance(ref) < other.distance(ref)
+
+    def as_dict(self) -> dict[str, float]:
         """Return the pixel size as a dictionary."""
         return {"t": self.t, "z": self.z, "y": self.y, "x": self.x}
 
+    @overload
+    def get(self, axis: str, default: float) -> float: ...
+
+    @overload
+    def get(self, axis: str, default: None = None) -> float | None: ...
+
+    def get(self, axis: str, default: float | None = None) -> float | None:
+        """Get the pixel size for a given axis (in canonical name)."""
+        px_size = self.as_dict().get(axis, default)
+        if px_size is None:
+            raise ValueError(
+                f"Invalid axis name: {axis}, must be one of 'x', 'y', 'z', 't'."
+            )
+        return px_size
+
+    @property
+    def tzyx(self) -> tuple[float, float, float, float]:
+        """Return the voxel size in t, z, y, x order."""
+        return self.t, self.z, self.y, self.x
+
     @property
     def zyx(self) -> tuple[float, float, float]:
         """Return the voxel size in z, y, x order."""
@@ -80,5 +118,5 @@ class PixelSize:
         return self.t
 
     def distance(self, other: "PixelSize") -> float:
-        """Return the distance between two pixel sizes in 3D space."""
-        return float(np.linalg.norm(np.array(self.zyx) - np.array(other.zyx)))
+        """Return the distance between two pixel sizes."""
+        return float(np.linalg.norm(np.array(self.tzyx) - np.array(other.tzyx)))