ngio 0.1.6__py3-none-any.whl → 0.2.0a2__py3-none-any.whl

ngio/ome_zarr_meta/_generic_handlers.py

@@ -0,0 +1,320 @@
+"""Base class for handling OME-NGFF metadata in Zarr groups."""
+
+from typing import Generic, Protocol, TypeVar
+
+from pydantic import ValidationError
+
+from ngio.ome_zarr_meta.ngio_specs import AxesSetup, NgioImageMeta, NgioLabelMeta
+from ngio.utils import (
+    NgioValueError,
+    ZarrGroupHandler,
+)
+
+ConverterError = ValidationError | Exception | None
+
+
+class ImageMetaHandler(Protocol):
+    """Protocol for OME-Zarr image handlers."""
+
+    def __init__(
+        self,
+        group_handler: ZarrGroupHandler,
+        axes_setup: AxesSetup | None = None,
+        allow_non_canonical_axes: bool = False,
+        strict_canonical_order: bool = True,
+    ):
+        """Initialize the handler."""
+        ...
+
+    def safe_load_meta(self) -> NgioImageMeta | ConverterError:
+        """Load the metadata from the store."""
+        ...
+
+    @property
+    def meta(self) -> NgioImageMeta:
+        """Return the metadata."""
+        ...
+
+    def write_meta(self, meta: NgioImageMeta) -> None:
+        """Write the metadata to the store."""
+        ...
+
+
+class LabelMetaHandler(Protocol):
+    """Protocol for OME-Zarr label handlers."""
+
+    def __init__(
+        self,
+        group_handler: ZarrGroupHandler,
+        axes_setup: AxesSetup | None = None,
+        allow_non_canonical_axes: bool = False,
+        strict_canonical_order: bool = True,
+    ):
+        """Initialize the handler."""
+        ...
+
+    def safe_load_meta(self) -> NgioLabelMeta | ConverterError:
+        """Load the metadata from the store."""
+        ...
+
+    @property
+    def meta(self) -> NgioLabelMeta:
+        """Return the metadata."""
+        ...
+
+    def write_meta(self, meta: NgioLabelMeta) -> None:
+        """Write the metadata to the store."""
+        ...
+
+
+###########################################################################
+#
+# The code below implements a generic class for handling OME-Zarr metadata
+# in Zarr groups.
+#
+###########################################################################
+
+
+class ImageMetaImporter(Protocol):
+    @staticmethod
+    def __call__(
+        metadata: dict,
+        axes_setup: AxesSetup | None = None,
+        allow_non_canonical_axes: bool = False,
+        strict_canonical_order: bool = True,
+    ) -> tuple[bool, NgioImageMeta | ConverterError]:
+        """Convert the metadata to a NgioImageMeta object.
+
+        Args:
+            metadata (dict): The metadata (typically from a Zarr group .attrs).
+            axes_setup (AxesSetup, optional): The axes setup.
+                This is used to map axes with non-canonical names.
+            allow_non_canonical_axes (bool, optional): Whether to allow non-canonical
+                axes.
+            strict_canonical_order (bool, optional): Whether to enforce a strict
+                canonical order.
+
+        Returns:
+            tuple[bool, NgioImageMeta | ConverterError]: A tuple with a boolean
+                indicating whether the conversion was successful and the
+                NgioImageMeta object or an error.
+
+        """
+        ...
+
+
+class ImageMetaExporter(Protocol):
+    def __call__(self, metadata: NgioImageMeta) -> dict: ...
+
+
+class LabelMetaImporter(Protocol):
+    @staticmethod
+    def __call__(
+        metadata: dict,
+        axes_setup: AxesSetup | None = None,
+        allow_non_canonical_axes: bool = False,
+        strict_canonical_order: bool = True,
+    ) -> tuple[bool, NgioLabelMeta | ConverterError]:
+        """Convert the metadata to a NgioLabelMeta object.
+
+        Args:
+            metadata (dict): The metadata (typically from a Zarr group .attrs).
+            axes_setup (AxesSetup, optional): The axes setup.
+                This is used to map axes with non-canonical names.
+            allow_non_canonical_axes (bool, optional): Whether to allow non-canonical
+                axes.
+            strict_canonical_order (bool, optional): Whether to enforce a strict
+                canonical order.
+
+        Returns:
+            tuple[bool, NgioLabelMeta | ConverterError]: A tuple with a boolean
+                indicating whether the conversion was successful and the
+                NgioLabelMeta object or an error.
+
+        """
+        ...
+
+
+class LabelMetaExporter(Protocol):
+    def __call__(self, metadata: NgioLabelMeta) -> dict: ...
+
+
+_meta = TypeVar("_meta", NgioImageMeta, NgioLabelMeta)
+_meta_importer = TypeVar("_meta_importer", ImageMetaImporter, LabelMetaImporter)
+_meta_exporter = TypeVar("_meta_exporter", ImageMetaExporter, LabelMetaExporter)
+
+
+class GenericMetaHandler(Generic[_meta, _meta_importer, _meta_exporter]):
+    """Generic class for handling OME-Zarr metadata in Zarr groups."""
+
+    def __init__(
+        self,
+        meta_importer: _meta_importer,
+        meta_exporter: _meta_exporter,
+        group_handler: ZarrGroupHandler,
+        axes_setup: AxesSetup | None = None,
+        allow_non_canonical_axes: bool = False,
+        strict_canonical_order: bool = True,
+    ):
+        """Initialize the handler.
+
+        Args:
+            meta_importer (MetaImporter): The metadata importer.
+            meta_exporter (MetaExporter): The metadata exporter.
+            group_handler (ZarrGroupHandler): The Zarr group handler.
+            axes_setup (AxesSetup, optional): The axes setup.
+                This is used to map axes with non-canonical names.
+            allow_non_canonical_axes (bool, optional): Whether to allow non-canonical
+                axes.
+            strict_canonical_order (bool, optional): Whether to enforce a strict
+                canonical order.
+        """
+        self._group_handler = group_handler
+        self._meta_importer = meta_importer
+        self._meta_exporter = meta_exporter
+        self._axes_setup = axes_setup
+        self._allow_non_canonical_axes = allow_non_canonical_axes
+        self._strict_canonical_order = strict_canonical_order
+
+    def _load_meta(self, return_error: bool = False):
+        """Load the metadata from the store."""
+        attrs = self._group_handler.load_attrs()
+        is_valid, meta_or_error = self._meta_importer(
+            metadata=attrs,
+            axes_setup=self._axes_setup,
+            allow_non_canonical_axes=self._allow_non_canonical_axes,
+            strict_canonical_order=self._strict_canonical_order,
+        )
+        if is_valid:
+            return meta_or_error
+
+        if return_error:
+            return meta_or_error
+
+        raise NgioValueError(f"Could not load metadata: {meta_or_error}")
+
+    def safe_load_meta(self) -> _meta | ConverterError:
+        """Load the metadata from the store."""
+        return self._load_meta(return_error=True)
+
+    def _write_meta(self, meta) -> None:
+        """Write the metadata to the store."""
+        v04_meta = self._meta_exporter(metadata=meta)
+        self._group_handler.write_attrs(v04_meta)
+
+    def write_meta(self, meta: _meta) -> None:
+        """Write the metadata to the store."""
+        raise NotImplementedError
+
+    @property
+    def meta(self) -> _meta:
+        """Return the metadata."""
+        raise NotImplementedError
+
+
+class BaseImageMetaHandler(
+    GenericMetaHandler[NgioImageMeta, ImageMetaImporter, ImageMetaExporter]
+):
+    """Generic class for handling OME-Zarr metadata in Zarr groups."""
+
+    def __init__(
+        self,
+        meta_importer: ImageMetaImporter,
+        meta_exporter: ImageMetaExporter,
+        group_handler: ZarrGroupHandler,
+        axes_setup: AxesSetup | None = None,
+        allow_non_canonical_axes: bool = False,
+        strict_canonical_order: bool = True,
+    ):
+        """Initialize the handler.
+
+        Args:
+            meta_importer (ImageMetaImporter): The metadata importer.
+            meta_exporter (ImageMetaExporter): The metadata exporter.
+            group_handler (ZarrGroupHandler): The Zarr group handler.
+            axes_setup (AxesSetup, optional): The axes setup.
+                This is used to map axes with non-canonical names.
+            allow_non_canonical_axes (bool, optional): Whether to allow non-canonical
+                axes.
+            strict_canonical_order (bool, optional): Whether to enforce a strict
+                canonical order.
+        """
+        super().__init__(
+            meta_importer=meta_importer,
+            meta_exporter=meta_exporter,
+            group_handler=group_handler,
+            axes_setup=axes_setup,
+            allow_non_canonical_axes=allow_non_canonical_axes,
+            strict_canonical_order=strict_canonical_order,
+        )
+
+    def safe_load_meta(
+        self, return_error: bool = False
+    ) -> NgioImageMeta | ConverterError:
+        """Load the metadata from the store."""
+        return self._load_meta(return_error)
+
+    @property
+    def meta(self) -> NgioImageMeta:
+        """Load the metadata from the store."""
+        meta = self._load_meta()
+        if isinstance(meta, NgioImageMeta):
+            return meta
+        raise NgioValueError(f"Could not load metadata: {meta}")
+
+    def write_meta(self, meta: NgioImageMeta) -> None:
+        self._write_meta(meta)
+
+
+class BaseLabelMetaHandler(
+    GenericMetaHandler[NgioLabelMeta, LabelMetaImporter, LabelMetaExporter]
+):
+    """Generic class for handling OME-Zarr metadata in Zarr groups."""
+
+    def __init__(
+        self,
+        meta_importer: LabelMetaImporter,
+        meta_exporter: LabelMetaExporter,
+        group_handler: ZarrGroupHandler,
+        axes_setup: AxesSetup | None = None,
+        allow_non_canonical_axes: bool = False,
+        strict_canonical_order: bool = True,
+    ):
+        """Initialize the handler.
+
+        Args:
+            meta_importer (LabelMetaImporter): The metadata importer.
+            meta_exporter (LabelMetaExporter): The metadata exporter.
+            group_handler (ZarrGroupHandler): The Zarr group handler.
+            axes_setup (AxesSetup, optional): The axes setup.
+                This is used to map axes with non-canonical names.
+            allow_non_canonical_axes (bool, optional): Whether to allow non-canonical
+                axes.
+            strict_canonical_order (bool, optional): Whether to enforce a strict
+                canonical order.
+        """
+        super().__init__(
+            meta_importer=meta_importer,
+            meta_exporter=meta_exporter,
+            group_handler=group_handler,
+            axes_setup=axes_setup,
+            allow_non_canonical_axes=allow_non_canonical_axes,
+            strict_canonical_order=strict_canonical_order,
+        )
+
+    def safe_load_meta(
+        self, return_error: bool = False
+    ) -> NgioLabelMeta | ConverterError:
+        """Load the metadata from the store."""
+        return self._load_meta(return_error)
+
+    @property
+    def meta(self) -> NgioLabelMeta:
+        """Load the metadata from the store."""
+        meta = self._load_meta()
+        if isinstance(meta, NgioLabelMeta):
+            return meta
+        raise NgioValueError(f"Could not load metadata: {meta}")
+
+    def write_meta(self, meta: NgioLabelMeta) -> None:
+        self._write_meta(meta)

ngio/ome_zarr_meta/_meta_handlers.py

@@ -0,0 +1,142 @@
+from typing import Any, Generic, TypeVar
+
+from pydantic import ValidationError
+
+from ngio.ome_zarr_meta._generic_handlers import (
+    ImageMetaHandler,
+    LabelMetaHandler,
+)
+from ngio.ome_zarr_meta.ngio_specs import AxesSetup
+from ngio.ome_zarr_meta.v04 import V04ImageMetaHandler, V04LabelMetaHandler
+from ngio.utils import (
+    AccessModeLiteral,
+    NgioValidationError,
+    NgioValueError,
+    StoreOrGroup,
+    ZarrGroupHandler,
+)
+
+_Image_or_Label_Plugin = TypeVar(
+    "_Image_or_Label_Plugin", ImageMetaHandler, LabelMetaHandler
+)
+
+
+class _ImplementedMetaHandlers(Generic[_Image_or_Label_Plugin]):
+    """This class is a singleton that manages the available image handler plugins."""
+
+    _instance = None
+    _implemented_handlers: dict[str, Any]
+
+    def __new__(cls):
+        """Create a new instance of the class if it does not exist."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._implemented_handlers = {}
+        return cls._instance
+
+    def available_handlers(self) -> list[str]:
+        """Get the available image handler versions.
+
+        The versions are returned in descending order.
+            such that the latest version is the first in the list and the fist to be
+            checked.
+        """
+        return list(reversed(self._implemented_handlers.keys()))
+
+    def find_meta_handler(
+        self,
+        group_handler: ZarrGroupHandler,
+        axes_setup: AxesSetup | None = None,
+        allow_non_canonical_axes: bool = False,
+        strict_canonical_order: bool = True,
+    ) -> _Image_or_Label_Plugin:
+        """Try to get a handler for the given store based on the metadata version."""
+        _errors = {}
+
+        for version, handler in reversed(self._implemented_handlers.items()):
+            handler = handler(
+                group_handler=group_handler,
+                axes_setup=axes_setup,
+                allow_non_canonical_axes=allow_non_canonical_axes,
+                strict_canonical_order=strict_canonical_order,
+            )
+            meta = handler.safe_load_meta()
+            if isinstance(meta, ValidationError):
+                _errors[version] = meta
+                continue
+            return handler
+
+        raise NgioValidationError(
+            f"Could not load OME-Zarr metadata from any known version. "
+            f"Errors: {_errors}"
+        )
+
+    def get_handler(
+        self,
+        version: str,
+        group_handler: ZarrGroupHandler,
+        axes_setup: AxesSetup | None = None,
+        allow_non_canonical_axes: bool = False,
+        strict_canonical_order: bool = True,
+    ) -> _Image_or_Label_Plugin:
+        """Get a handler for a specific version."""
+        if version not in self._implemented_handlers:
+            raise NgioValueError(f"Image handler for version {version} does not exist.")
+        return self._implemented_handlers[version](
+            group_handler=group_handler,
+            axes_setup=axes_setup,
+            allow_non_canonical_axes=allow_non_canonical_axes,
+            strict_canonical_order=strict_canonical_order,
+        )
+
+    def add_handler(
+        self, key: str, handler: type[_Image_or_Label_Plugin], overwrite: bool = False
+    ):
+        """Register a new handler."""
+        if key in self._implemented_handlers and not overwrite:
+            raise NgioValueError(f"Image handler for version {key} already exists.")
+        self._implemented_handlers[key] = handler
+
+
+class ImplementedImageMetaHandlers(_ImplementedMetaHandlers[ImageMetaHandler]):
+    def __init__(self):
+        super().__init__()
+
+
+ImplementedImageMetaHandlers().add_handler("0.4", V04ImageMetaHandler)
+
+
+class ImplementedLabelMetaHandlers(_ImplementedMetaHandlers[LabelMetaHandler]):
+    def __init__(self):
+        super().__init__()
+
+
+ImplementedLabelMetaHandlers().add_handler("0.4", V04LabelMetaHandler)
+
+
+def open_image_meta_handler(
+    store: StoreOrGroup,
+    cache: bool = False,
+    mode: AccessModeLiteral = "a",
+    axes_setup: AxesSetup | None = None,
+    allow_non_canonical_axes: bool = False,
+    strict_canonical_order: bool = True,
+) -> ImageMetaHandler:
+    """Open the metadata of an OME-Zarr image.
+
+    Args:
+        store: The Zarr store or group where the model is
+        cache: Whether to cache the metadata.
+        mode: The store access mode.
+        axes_setup: The axes setup. This is used to map axes with
+            a non-canonical name to a canonical name.
+        allow_non_canonical_axes: Whether to allow non-canonical axes.
+        strict_canonical_order: Whether to enforce strict canonical order.
+    """
+    zarr_group_handler = ZarrGroupHandler(store, cache, mode)
+    return ImplementedImageMetaHandlers().find_meta_handler(
+        zarr_group_handler,
+        axes_setup=axes_setup,
+        allow_non_canonical_axes=allow_non_canonical_axes,
+        strict_canonical_order=strict_canonical_order,
+    )

ngio/ome_zarr_meta/ngio_specs/__init__.py

@@ -0,0 +1,63 @@
+"""ngio internal specs module.
+
+Since the OME-Zarr specification are still evolving, this module provides a
+set of classes to internally handle the metadata.
+
+This models can be tr
+"""
+
+from ngio.ome_zarr_meta.ngio_specs._axes import (
+    AxesExpand,
+    AxesMapper,
+    AxesSetup,
+    AxesSqueeze,
+    AxesTransformation,
+    AxesTranspose,
+    Axis,
+    AxisType,
+    SpaceUnits,
+    TimeUnits,
+    canonical_axes_order,
+    canonical_label_axes_order,
+)
+from ngio.ome_zarr_meta.ngio_specs._channels import (
+    Channel,
+    ChannelsMeta,
+    ChannelVisualisation,
+    NgioColors,
+    default_channel_name,
+)
+from ngio.ome_zarr_meta.ngio_specs._dataset import Dataset
+from ngio.ome_zarr_meta.ngio_specs._ngio_image import (
+    ImageLabelSource,
+    NgioImageLabelMeta,
+    NgioImageMeta,
+    NgioLabelMeta,
+)
+from ngio.ome_zarr_meta.ngio_specs._pixel_size import PixelSize
+
+__all__ = [
+    "AxesExpand",
+    "AxesMapper",
+    "AxesSetup",
+    "AxesSqueeze",
+    "AxesTransformation",
+    "AxesTranspose",
+    "Axis",
+    "AxisType",
+    "Channel",
+    "ChannelVisualisation",
+    "ChannelsMeta",
+    "Dataset",
+    "ImageLabelSource",
+    "NgioColors",
+    "NgioImageLabelMeta",
+    "NgioImageMeta",
+    "NgioLabelMeta",
+    "PixelSize",
+    "SpaceUnits",
+    "TimeUnits",
+    "canonical_axes_order",
+    "canonical_label_axes_order",
+    "default_channel_name",
+]