ngio 0.5.0a2__py3-none-any.whl → 0.5.0b1__py3-none-any.whl

ngio/ome_zarr_meta/_meta_handlers.py

@@ -1,33 +1,38 @@
 """Base class for handling OME-NGFF metadata in Zarr groups."""
 
-from typing import Generic, Protocol, TypeVar
-
-from pydantic import ValidationError
+from collections.abc import Callable
+from typing import TypeVar
 
 from ngio.ome_zarr_meta.ngio_specs import (
     AxesSetup,
     NgioImageMeta,
     NgioLabelMeta,
+    NgioLabelsGroupMeta,
     NgioPlateMeta,
     NgioWellMeta,
 )
+from ngio.ome_zarr_meta.ngio_specs._ngio_image import NgffVersions
 from ngio.ome_zarr_meta.v04 import (
     ngio_to_v04_image_meta,
     ngio_to_v04_label_meta,
+    ngio_to_v04_labels_group_meta,
     ngio_to_v04_plate_meta,
     ngio_to_v04_well_meta,
     v04_to_ngio_image_meta,
     v04_to_ngio_label_meta,
+    v04_to_ngio_labels_group_meta,
     v04_to_ngio_plate_meta,
     v04_to_ngio_well_meta,
 )
 from ngio.ome_zarr_meta.v05 import (
     ngio_to_v05_image_meta,
     ngio_to_v05_label_meta,
+    ngio_to_v05_labels_group_meta,
     ngio_to_v05_plate_meta,
     ngio_to_v05_well_meta,
     v05_to_ngio_image_meta,
     v05_to_ngio_label_meta,
+    v05_to_ngio_labels_group_meta,
     v05_to_ngio_plate_meta,
     v05_to_ngio_well_meta,
 )
@@ -37,792 +42,495 @@ from ngio.utils import (
     ZarrGroupHandler,
 )
 
-ConverterError = ValidationError | Exception | None
-
-###########################################################################
-#
-# 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: ...
-
-
-class WellMetaImporter(Protocol):
-    def __call__(
-        self, metadata: dict
-    ) -> tuple[bool, NgioWellMeta | ConverterError]: ...
+# This could be replaced with a more dynamic registry if needed in the future
+_image_encoder_registry = {"0.4": ngio_to_v04_image_meta, "0.5": ngio_to_v05_image_meta}
+_image_decoder_registry = {"0.4": v04_to_ngio_image_meta, "0.5": v05_to_ngio_image_meta}
+_label_encoder_registry = {"0.4": ngio_to_v04_label_meta, "0.5": ngio_to_v05_label_meta}
+_label_decoder_registry = {"0.4": v04_to_ngio_label_meta, "0.5": v05_to_ngio_label_meta}
+_plate_encoder_registry = {"0.4": ngio_to_v04_plate_meta, "0.5": ngio_to_v05_plate_meta}
+_plate_decoder_registry = {"0.4": v04_to_ngio_plate_meta, "0.5": v05_to_ngio_plate_meta}
+_well_encoder_registry = {"0.4": ngio_to_v04_well_meta, "0.5": ngio_to_v05_well_meta}
+_well_decoder_registry = {"0.4": v04_to_ngio_well_meta, "0.5": v05_to_ngio_well_meta}
+_labels_group_encoder_registry = {
+    "0.4": ngio_to_v04_labels_group_meta,
+    "0.5": ngio_to_v05_labels_group_meta,
+}
+_labels_group_decoder_registry = {
+    "0.4": v04_to_ngio_labels_group_meta,
+    "0.5": v05_to_ngio_labels_group_meta,
+}
+
+_meta_type = TypeVar(
+    "_meta_type",
+    NgioImageMeta,
+    NgioLabelMeta,
+    NgioLabelsGroupMeta,
+    NgioPlateMeta,
+    NgioWellMeta,
+)
 
 
-class WellMetaExporter(Protocol):
-    def __call__(self, metadata: NgioWellMeta) -> dict: ...
+def _find_encoder_registry(
+    ngio_meta: _meta_type,
+) -> dict[str, Callable]:
+    if isinstance(ngio_meta, NgioImageMeta):
+        return _image_encoder_registry
+    elif isinstance(ngio_meta, NgioLabelMeta):
+        return _label_encoder_registry
+    elif isinstance(ngio_meta, NgioPlateMeta):
+        return _plate_encoder_registry
+    elif isinstance(ngio_meta, NgioWellMeta):
+        return _well_encoder_registry
+    elif isinstance(ngio_meta, NgioLabelsGroupMeta):
+        return _labels_group_encoder_registry
+    else:
+        raise NgioValueError(f"Unsupported NGIO metadata type: {type(ngio_meta)}")
+
+
+def update_ngio_meta(
+    group_handler: ZarrGroupHandler,
+    ngio_meta: _meta_type,
+) -> None:
+    """Update the metadata in the Zarr group.
+
+    Args:
+        group_handler (ZarrGroupHandler): The Zarr group handler.
+        ngio_meta (_meta_type): The new NGIO metadata.
+
+    """
+    registry = _find_encoder_registry(ngio_meta)
+    exporter = registry.get(ngio_meta.version)
+    if exporter is None:
+        raise NgioValueError(f"Unsupported NGFF version: {ngio_meta.version}")
+
+    zarr_meta = exporter(ngio_meta)
+    group_handler.write_attrs(zarr_meta)
+
+
+def _find_decoder_registry(
+    meta_type: type[_meta_type],
+) -> dict[str, Callable]:
+    if meta_type is NgioImageMeta:
+        return _image_decoder_registry
+    elif meta_type is NgioLabelMeta:
+        return _label_decoder_registry
+    elif meta_type is NgioPlateMeta:
+        return _plate_decoder_registry
+    elif meta_type is NgioWellMeta:
+        return _well_decoder_registry
+    elif meta_type is NgioLabelsGroupMeta:
+        return _labels_group_decoder_registry
+    else:
+        raise NgioValueError(f"Unsupported NGIO metadata type: {meta_type}")
+
+
+def get_ngio_meta(
+    group_handler: ZarrGroupHandler,
+    meta_type: type[_meta_type],
+    version: str | None = None,
+    **kwargs,
+) -> _meta_type:
+    """Retrieve the NGIO metadata from the Zarr group.
+
+    Args:
+        group_handler (ZarrGroupHandler): The Zarr group handler.
+        meta_type (type[_meta_type]): The type of NGIO metadata to retrieve.
+        version (str | None): Optional NGFF version to use for decoding.
+        **kwargs: Additional arguments to pass to the decoder.
+
+    Returns:
+        _meta_type: The NGIO metadata.
+    """
+    registry = _find_decoder_registry(meta_type)
+    if version is not None:
+        decoder = registry.get(version)
+        if decoder is None:
+            raise NgioValueError(f"Unsupported NGFF version: {version}")
+        versions_to_try = {version: decoder}
+    else:
+        versions_to_try = registry
+
+    attrs = group_handler.load_attrs()
+    all_errors = []
+    for version, decoder in versions_to_try.items():
+        try:
+            ngio_meta = decoder(attrs, **kwargs)
+            return ngio_meta
+        except Exception as e:
+            all_errors.append(f"Version {version}: {e}")
+    error_message = (
+        f"Failed to decode NGIO {meta_type.__name__} metadata:\n"
+        + "\n".join(all_errors)
+    )
+    raise NgioValidationError(error_message)
 
 
-class PlateMetaImporter(Protocol):
-    def __call__(
-        self, metadata: dict
-    ) -> tuple[bool, NgioPlateMeta | ConverterError]: ...
+##################################################
+#
+# Concrete implementations for NGIO metadata types
+#
+##################################################
 
 
-class PlateMetaExporter(Protocol):
-    def __call__(self, metadata: NgioPlateMeta) -> dict: ...
+def get_ngio_image_meta(
+    group_handler: ZarrGroupHandler,
+    version: str | None = None,
+    axes_setup: AxesSetup | None = None,
+    allow_non_canonical_axes: bool = False,
+    strict_canonical_order: bool = True,
+) -> NgioImageMeta:
+    """Retrieve the NGIO image metadata from the Zarr group.
+
+    Args:
+        group_handler (ZarrGroupHandler): The Zarr group handler.
+        version (str | None): Optional NGFF version to use for decoding.
+        axes_setup (AxesSetup | None): Optional axes setup for validation.
+        allow_non_canonical_axes (bool): Whether to allow non-canonical axes.
+        strict_canonical_order (bool): Whether to enforce strict canonical order.
+
+    Returns:
+        NgioImageMeta: The NGIO image metadata.
+    """
+    return get_ngio_meta(
+        group_handler=group_handler,
+        meta_type=NgioImageMeta,
+        version=version,
+        axes_setup=axes_setup,
+        allow_non_canonical_axes=allow_non_canonical_axes,
+        strict_canonical_order=strict_canonical_order,
+    )
 
 
-###########################################################################
-#
-# Image and label metadata handlers
-#
-###########################################################################
+def update_ngio_image_meta(
+    group_handler: ZarrGroupHandler,
+    ngio_meta: NgioImageMeta,
+) -> None:
+    """Update the NGIO image metadata in the Zarr group.
 
-_image_meta = TypeVar("_image_meta", NgioImageMeta, NgioLabelMeta)
-_image_meta_importer = TypeVar(
-    "_image_meta_importer", ImageMetaImporter, LabelMetaImporter
-)
-_image_meta_exporter = TypeVar(
-    "_image_meta_exporter", ImageMetaExporter, LabelMetaExporter
-)
+    Args:
+        group_handler (ZarrGroupHandler): The Zarr group handler.
+        ngio_meta (NgioImageMeta): The new NGIO image metadata.
 
+    """
+    update_ngio_meta(
+        group_handler=group_handler,
+        ngio_meta=ngio_meta,
+    )
 
-class GenericMetaHandler(
-    Generic[_image_meta, _image_meta_importer, _image_meta_exporter]
-):
-    """Generic class for handling OME-Zarr metadata in Zarr groups."""
 
+class ImageMetaHandler:
     def __init__(
         self,
-        meta_importer: _image_meta_importer,
-        meta_exporter: _image_meta_exporter,
         group_handler: ZarrGroupHandler,
+        version: str | None = None,
         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._version = version
         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,
+        # Validate metadata
+        meta = self.get_meta()
+        # Store the resolved version
+        self._version = meta.version
+
+    def get_meta(self) -> NgioImageMeta:
+        """Retrieve the NGIO image metadata."""
+        return get_ngio_image_meta(
+            group_handler=self._group_handler,
+            version=self._version,
             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 _write_meta(self, meta) -> None:
-        """Write the metadata to the store."""
-        _meta = self._meta_exporter(metadata=meta)
-        self._group_handler.write_attrs(_meta)
 
-    def write_meta(self, meta: _image_meta) -> None:
-        self._write_meta(meta)
-
-    @property
-    def meta(self) -> _image_meta:
-        """Return the metadata."""
-        raise NotImplementedError("This method should be implemented in a subclass.")
-
-
-class ImageMetaHandler(
-    GenericMetaHandler[NgioImageMeta, ImageMetaImporter, ImageMetaExporter]
-):
-    """Generic class for handling OME-Zarr metadata in Zarr groups."""
-
-    @property
-    def meta(self) -> NgioImageMeta:
-        meta = self._load_meta()
-        if isinstance(meta, NgioImageMeta):
-            return meta
-        raise NgioValueError(f"Could not load metadata: {meta}")
-
-    def safe_load_meta(self) -> NgioImageMeta | ConverterError:
-        """Load the metadata from the store."""
-        return self._load_meta(return_error=True)
-
-
-class LabelMetaHandler(
-    GenericMetaHandler[NgioLabelMeta, LabelMetaImporter, LabelMetaExporter]
-):
-    """Generic class for handling OME-Zarr metadata in Zarr groups."""
+    def update_meta(self, ngio_meta: NgioImageMeta) -> None:
+        """Update the NGIO image metadata."""
+        update_ngio_meta(
+            group_handler=self._group_handler,
+            ngio_meta=ngio_meta,
+        )
 
-    @property
-    def meta(self) -> NgioLabelMeta:
-        meta = self._load_meta()
-        if isinstance(meta, NgioLabelMeta):
-            return meta
-        raise NgioValueError(f"Could not load metadata: {meta}")
 
-    def safe_load_meta(self) -> NgioLabelMeta | ConverterError:
-        """Load the metadata from the store."""
-        return self._load_meta(return_error=True)
+def get_ngio_label_meta(
+    group_handler: ZarrGroupHandler,
+    version: str | None = None,
+    axes_setup: AxesSetup | None = None,
+    allow_non_canonical_axes: bool = False,
+    strict_canonical_order: bool = True,
+) -> NgioLabelMeta:
+    """Retrieve the NGIO label metadata from the Zarr group.
+
+    Args:
+        group_handler (ZarrGroupHandler): The Zarr group handler.
+        version (str | None): Optional NGFF version to use for decoding.
+        axes_setup (AxesSetup | None): Optional axes setup for validation.
+        allow_non_canonical_axes (bool): Whether to allow non-canonical axes.
+        strict_canonical_order (bool): Whether to enforce strict canonical order.
+
+    Returns:
+        NgioLabelMeta: The NGIO label metadata.
+    """
+    return get_ngio_meta(
+        group_handler=group_handler,
+        meta_type=NgioLabelMeta,
+        version=version,
+        axes_setup=axes_setup,
+        allow_non_canonical_axes=allow_non_canonical_axes,
+        strict_canonical_order=strict_canonical_order,
+    )
 
 
-###########################################################################
-#
-# Well and plate metadata handlers
-#
-###########################################################################
+def update_ngio_label_meta(
+    group_handler: ZarrGroupHandler,
+    ngio_meta: NgioLabelMeta,
+) -> None:
+    """Update the NGIO label metadata in the Zarr group.
 
-_hcs_meta = TypeVar("_hcs_meta", NgioWellMeta, NgioPlateMeta)
-_hcs_meta_importer = TypeVar("_hcs_meta_importer", WellMetaImporter, PlateMetaImporter)
-_hcs_meta_exporter = TypeVar("_hcs_meta_exporter", WellMetaExporter, PlateMetaExporter)
+    Args:
+        group_handler (ZarrGroupHandler): The Zarr group handler.
+        ngio_meta (NgioLabelMeta): The new NGIO label metadata.
 
+    """
+    update_ngio_meta(
+        group_handler=group_handler,
+        ngio_meta=ngio_meta,
+    )
 
-class GenericHCSMetaHandler(Generic[_hcs_meta, _hcs_meta_importer, _hcs_meta_exporter]):
-    """Generic class for handling OME-Zarr metadata in Zarr groups."""
 
+class LabelMetaHandler:
     def __init__(
         self,
-        meta_importer: _hcs_meta_importer,
-        meta_exporter: _hcs_meta_exporter,
         group_handler: ZarrGroupHandler,
+        version: str | None = None,
+        axes_setup: AxesSetup | None = None,
+        allow_non_canonical_axes: bool = False,
+        strict_canonical_order: bool = True,
     ):
         self._group_handler = group_handler
-        self._meta_importer = meta_importer
-        self._meta_exporter = meta_exporter
-
-    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)
-        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 _write_meta(self, meta) -> None:
-        _meta = self._meta_exporter(metadata=meta)
-        self._group_handler.write_attrs(_meta)
-
-    def write_meta(self, meta: _hcs_meta) -> None:
-        self._write_meta(meta)
-
-    @property
-    def meta(self) -> _hcs_meta:
-        raise NotImplementedError("This method should be implemented in a subclass.")
-
-
-class WellMetaHandler(
-    GenericHCSMetaHandler[NgioWellMeta, WellMetaImporter, WellMetaExporter]
-):
-    """Generic class for handling OME-Zarr metadata in Zarr groups."""
-
-    @property
-    def meta(self) -> NgioWellMeta:
-        meta = self._load_meta()
-        if isinstance(meta, NgioWellMeta):
-            return meta
-        raise NgioValueError(f"Could not load metadata: {meta}")
+        self._version = version
+        self._axes_setup = axes_setup
+        self._allow_non_canonical_axes = allow_non_canonical_axes
+        self._strict_canonical_order = strict_canonical_order
 
-    def safe_load_meta(self) -> NgioWellMeta | ConverterError:
-        """Load the metadata from the store."""
-        return self._load_meta(return_error=True)
+        # Validate metadata
+        meta = self.get_meta()
+        # Store the resolved version
+        self._version = meta.version
 
+    def get_meta(self) -> NgioLabelMeta:
+        """Retrieve the NGIO label metadata."""
+        return get_ngio_label_meta(
+            group_handler=self._group_handler,
+            version=self._version,
+            axes_setup=self._axes_setup,
+            allow_non_canonical_axes=self._allow_non_canonical_axes,
+            strict_canonical_order=self._strict_canonical_order,
+        )
 
-class PlateMetaHandler(
-    GenericHCSMetaHandler[NgioPlateMeta, PlateMetaImporter, PlateMetaExporter]
-):
-    """Generic class for handling OME-Zarr metadata in Zarr groups."""
+    def update_meta(self, ngio_meta: NgioLabelMeta) -> None:
+        """Update the NGIO label metadata."""
+        update_ngio_meta(
+            group_handler=self._group_handler,
+            ngio_meta=ngio_meta,
+        )
 
-    @property
-    def meta(self) -> NgioPlateMeta:
-        meta = self._load_meta()
-        if isinstance(meta, NgioPlateMeta):
-            return meta
-        raise NgioValueError(f"Could not load metadata: {meta}")
 
-    def safe_load_meta(self) -> NgioPlateMeta | ConverterError:
-        """Load the metadata from the store."""
-        return self._load_meta(return_error=True)
+def get_ngio_plate_meta(
+    group_handler: ZarrGroupHandler,
+    version: str | None = None,
+) -> NgioPlateMeta:
+    """Retrieve the NGIO plate metadata from the Zarr group.
+
+    Args:
+        group_handler (ZarrGroupHandler): The Zarr group handler.
+        version (str | None): Optional NGFF version to use for decoding.
+
+    Returns:
+        NgioPlateMeta: The NGIO plate metadata.
+    """
+    return get_ngio_meta(
+        group_handler=group_handler,
+        meta_type=NgioPlateMeta,
+        version=version,
+    )
 
 
-###########################################################################
-#
-# Metadata importer/exporter registration & builder classes
-#
-###########################################################################
+def update_ngio_plate_meta(
+    group_handler: ZarrGroupHandler,
+    ngio_meta: NgioPlateMeta,
+) -> None:
+    """Update the NGIO plate metadata in the Zarr group.
 
+    Args:
+        group_handler (ZarrGroupHandler): The Zarr group handler.
+        ngio_meta (NgioPlateMeta): The new NGIO plate metadata.
 
-_meta_exporter = TypeVar(
-    "_meta_exporter",
-    ImageMetaExporter,
-    LabelMetaExporter,
-    WellMetaExporter,
-    PlateMetaExporter,
-)
-_meta_importer = TypeVar(
-    "_meta_importer",
-    ImageMetaImporter,
-    LabelMetaImporter,
-    WellMetaImporter,
-    PlateMetaImporter,
-)
+    """
+    update_ngio_meta(
+        group_handler=group_handler,
+        ngio_meta=ngio_meta,
+    )
 
 
-class _ImporterExporter(Generic[_meta_importer, _meta_exporter]):
+class PlateMetaHandler:
     def __init__(
-        self,
-        version: str,
-        importer: _meta_importer,
-        exporter: _meta_exporter,
-    ):
-        self.importer = importer
-        self.exporter = exporter
-        self.version = version
-
-
-ImageImporterExporter = _ImporterExporter[ImageMetaImporter, ImageMetaExporter]
-LabelImporterExporter = _ImporterExporter[LabelMetaImporter, LabelMetaExporter]
-WellImporterExporter = _ImporterExporter[WellMetaImporter, WellMetaExporter]
-PlateImporterExporter = _ImporterExporter[PlateMetaImporter, PlateMetaExporter]
-
-_importer_exporter = TypeVar(
-    "_importer_exporter",
-    ImageImporterExporter,
-    LabelImporterExporter,
-    WellImporterExporter,
-    PlateImporterExporter,
-)
-_image_handler = TypeVar("_image_handler", ImageMetaHandler, LabelMetaHandler)
-_hcs_handler = TypeVar("_hcs_handler", WellMetaHandler, PlateMetaHandler)
-
-
-class ImplementedMetaImporterExporter:
-    _instance = None
-    _image_ie: dict[str, ImageImporterExporter]
-    _label_ie: dict[str, LabelImporterExporter]
-    _well_ie: dict[str, WellImporterExporter]
-    _plate_ie: dict[str, PlateImporterExporter]
-
-    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._image_ie = {}
-            cls._label_ie = {}
-            cls._well_ie = {}
-            cls._plate_ie = {}
-        return cls._instance
-
-    def _find_image_handler(
-        self,
-        group_handler: ZarrGroupHandler,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-        _ie_name: str = "_image_ie",
-        _handler: type[_image_handler] = ImageMetaHandler,
-    ) -> _image_handler:
-        """Get an image metadata handler."""
-        _errors = {}
-
-        dict_ie = self.__getattribute__(_ie_name)
-
-        for ie in reversed(dict_ie.values()):
-            handler = _handler(
-                meta_importer=ie.importer,
-                meta_exporter=ie.exporter,
-                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[ie.version] = meta
-                continue
-            return handler
-
-        raise NgioValidationError(
-            f"Could not load metadata from any known version. Errors: {_errors}"
-        )
-
-    def find_image_handler(
         self,
         group_handler: ZarrGroupHandler,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ) -> ImageMetaHandler:
-        """Get an image metadata handler."""
-        return self._find_image_handler(
-            group_handler=group_handler,
-            axes_setup=axes_setup,
-            allow_non_canonical_axes=allow_non_canonical_axes,
-            strict_canonical_order=strict_canonical_order,
-            _ie_name="_image_ie",
-            _handler=ImageMetaHandler,
-        )
-
-    def get_image_meta_handler(
-        self,
-        group_handler: ZarrGroupHandler,
-        version: str,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ) -> ImageMetaHandler:
-        """Get an image metadata handler."""
-        if version not in self._image_ie:
-            raise NgioValueError(f"Image handler for version {version} does not exist.")
-
-        image_ie = self._image_ie[version]
-        return ImageMetaHandler(
-            meta_importer=image_ie.importer,
-            meta_exporter=image_ie.exporter,
-            group_handler=group_handler,
-            axes_setup=axes_setup,
-            allow_non_canonical_axes=allow_non_canonical_axes,
-            strict_canonical_order=strict_canonical_order,
-        )
-
-    def _register(
-        self,
-        version: str,
-        importer: _importer_exporter,
-        overwrite: bool = False,
-        _ie_name: str = "_image_ie",
-    ):
-        """Register an importer/exporter."""
-        ie_dict = self.__getattribute__(_ie_name)
-        if version in ie_dict and not overwrite:
-            raise NgioValueError(
-                f"Importer/exporter for version {version} already exists. "
-                "Use 'overwrite=True' to overwrite."
-            )
-        ie_dict[version] = importer
-
-    def register_image_ie(
-        self,
-        version: str,
-        importer: ImageMetaImporter,
-        exporter: ImageMetaExporter,
-        overwrite: bool = False,
+        version: str | None = None,
     ):
-        """Register an importer/exporter."""
-        importer_exporter = ImageImporterExporter(
-            version=version, importer=importer, exporter=exporter
-        )
-        self._register(
-            version=version,
-            importer=importer_exporter,
-            overwrite=overwrite,
-            _ie_name="_image_ie",
+        self._group_handler = group_handler
+        self._version = version
+
+        # Validate metadata
+        _ = self.get_meta()
+        # Store the resolved version
+        # self._version = meta.version
+
+    def get_meta(self) -> NgioPlateMeta:
+        """Retrieve the NGIO plate metadata."""
+        return get_ngio_plate_meta(
+            group_handler=self._group_handler,
+            version=self._version,
         )
 
-    def find_label_handler(
-        self,
-        group_handler: ZarrGroupHandler,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ) -> LabelMetaHandler:
-        """Get a label metadata handler."""
-        return self._find_image_handler(
-            group_handler=group_handler,
-            axes_setup=axes_setup,
-            allow_non_canonical_axes=allow_non_canonical_axes,
-            strict_canonical_order=strict_canonical_order,
-            _ie_name="_label_ie",
-            _handler=LabelMetaHandler,
+    def update_meta(self, ngio_meta: NgioPlateMeta) -> None:
+        """Update the NGIO plate metadata."""
+        update_ngio_meta(
+            group_handler=self._group_handler,
+            ngio_meta=ngio_meta,
         )
 
-    def get_label_meta_handler(
-        self,
-        group_handler: ZarrGroupHandler,
-        version: str,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ) -> LabelMetaHandler:
-        """Get a label metadata handler."""
-        if version not in self._label_ie:
-            raise NgioValueError(f"Label handler for version {version} does not exist.")
-
-        label_ie = self._label_ie[version]
-        return LabelMetaHandler(
-            meta_importer=label_ie.importer,
-            meta_exporter=label_ie.exporter,
-            group_handler=group_handler,
-            axes_setup=axes_setup,
-            allow_non_canonical_axes=allow_non_canonical_axes,
-            strict_canonical_order=strict_canonical_order,
-        )
 
-    def register_label_ie(
-        self,
-        version: str,
-        importer: LabelMetaImporter,
-        exporter: LabelMetaExporter,
-        overwrite: bool = False,
-    ):
-        """Register an importer/exporter."""
-        importer_exporter = LabelImporterExporter(
-            version=version, importer=importer, exporter=exporter
-        )
-        self._register(
-            version=version,
-            importer=importer_exporter,
-            overwrite=overwrite,
-            _ie_name="_label_ie",
-        )
+def get_ngio_well_meta(
+    group_handler: ZarrGroupHandler,
+    version: str | None = None,
+) -> NgioWellMeta:
+    """Retrieve the NGIO well metadata from the Zarr group.
+
+    Args:
+        group_handler (ZarrGroupHandler): The Zarr group handler.
+        version (str | None): Optional NGFF version to use for decoding.
+
+    Returns:
+        NgioWellMeta: The NGIO well metadata.
+    """
+    return get_ngio_meta(
+        group_handler=group_handler,
+        meta_type=NgioWellMeta,
+        version=version,
+    )
 
-    def _find_hcs_handler(
-        self,
-        group_handler: ZarrGroupHandler,
-        _ie_name: str = "_well_ie",
-        _handler: type[_hcs_handler] = WellMetaHandler,
-    ) -> _hcs_handler:
-        """Get a handler for a HCS metadata."""
-        _errors = {}
-
-        dict_ie = self.__getattribute__(_ie_name)
-
-        for ie in reversed(dict_ie.values()):
-            handler = _handler(
-                meta_importer=ie.importer,
-                meta_exporter=ie.exporter,
-                group_handler=group_handler,
-            )
-            meta = handler.safe_load_meta()
-            if isinstance(meta, ValidationError):
-                _errors[ie.version] = meta
-                continue
-            return handler
-
-        raise NgioValidationError(
-            f"Could not load metadata from any known version. Errors: {_errors}"
-        )
 
-    def find_well_handler(
-        self,
-        group_handler: ZarrGroupHandler,
-    ) -> WellMetaHandler:
-        """Get a well metadata handler."""
-        return self._find_hcs_handler(
-            group_handler=group_handler,
-            _ie_name="_well_ie",
-            _handler=WellMetaHandler,
-        )
+def update_ngio_well_meta(
+    group_handler: ZarrGroupHandler,
+    ngio_meta: NgioWellMeta,
+) -> None:
+    """Update the NGIO well metadata in the Zarr group.
 
-    def get_well_meta_handler(
-        self,
-        group_handler: ZarrGroupHandler,
-        version: str,
-    ) -> WellMetaHandler:
-        """Get a well metadata handler."""
-        if version not in self._well_ie:
-            raise NgioValueError(f"Well handler for version {version} does not exist.")
-
-        well_ie = self._well_ie[version]
-        return WellMetaHandler(
-            meta_importer=well_ie.importer,
-            meta_exporter=well_ie.exporter,
-            group_handler=group_handler,
-        )
+    Args:
+        group_handler (ZarrGroupHandler): The Zarr group handler.
+        ngio_meta (NgioWellMeta): The new NGIO well metadata.
 
-    def register_well_ie(
-        self,
-        version: str,
-        importer: WellMetaImporter,
-        exporter: WellMetaExporter,
-        overwrite: bool = False,
-    ):
-        """Register an importer/exporter."""
-        importer_exporter = WellImporterExporter(
-            version=version, importer=importer, exporter=exporter
-        )
-        self._register(
-            version=version,
-            importer=importer_exporter,
-            overwrite=overwrite,
-            _ie_name="_well_ie",
-        )
+    """
+    update_ngio_meta(
+        group_handler=group_handler,
+        ngio_meta=ngio_meta,
+    )
 
-    def find_plate_handler(
-        self,
-        group_handler: ZarrGroupHandler,
-    ) -> PlateMetaHandler:
-        """Get a plate metadata handler."""
-        return self._find_hcs_handler(
-            group_handler=group_handler,
-            _ie_name="_plate_ie",
-            _handler=PlateMetaHandler,
-        )
 
-    def get_plate_meta_handler(
+class WellMetaHandler:
+    def __init__(
         self,
         group_handler: ZarrGroupHandler,
-        version: str,
-    ) -> PlateMetaHandler:
-        """Get a plate metadata handler."""
-        if version not in self._plate_ie:
-            raise NgioValueError(f"Plate handler for version {version} does not exist.")
-
-        plate_ie = self._plate_ie[version]
-        return PlateMetaHandler(
-            meta_importer=plate_ie.importer,
-            meta_exporter=plate_ie.exporter,
-            group_handler=group_handler,
-        )
-
-    def register_plate_ie(
-        self,
-        version: str,
-        importer: PlateMetaImporter,
-        exporter: PlateMetaExporter,
-        overwrite: bool = False,
+        version: str | None = None,
     ):
-        """Register an importer/exporter."""
-        importer_exporter = PlateImporterExporter(
-            version=version, importer=importer, exporter=exporter
-        )
-        self._register(
-            version=version,
-            importer=importer_exporter,
-            overwrite=overwrite,
-            _ie_name="_plate_ie",
+        self._group_handler = group_handler
+        self._version = version
+
+        # Validate metadata
+        _ = self.get_meta()
+        # Store the resolved version
+        # self._version = meta.version
+
+    def get_meta(self) -> NgioWellMeta:
+        """Retrieve the NGIO well metadata."""
+        return get_ngio_well_meta(
+            group_handler=self._group_handler,
+            version=self._version,
         )
 
-
-###########################################################################
-#
-# Register metadata importers/exporters
-#
-###########################################################################
-
-
-ImplementedMetaImporterExporter().register_image_ie(
-    version="0.4",
-    importer=v04_to_ngio_image_meta,
-    exporter=ngio_to_v04_image_meta,
-)
-
-ImplementedMetaImporterExporter().register_label_ie(
-    version="0.5",
-    importer=v05_to_ngio_label_meta,
-    exporter=ngio_to_v05_label_meta,
-)
-
-ImplementedMetaImporterExporter().register_label_ie(
-    version="0.4",
-    importer=v04_to_ngio_label_meta,
-    exporter=ngio_to_v04_label_meta,
-)
-ImplementedMetaImporterExporter().register_image_ie(
-    version="0.5",
-    importer=v05_to_ngio_image_meta,
-    exporter=ngio_to_v05_image_meta,
-)
-
-ImplementedMetaImporterExporter().register_well_ie(
-    version="0.4", importer=v04_to_ngio_well_meta, exporter=ngio_to_v04_well_meta
-)
-ImplementedMetaImporterExporter().register_well_ie(
-    version="0.5", importer=v05_to_ngio_well_meta, exporter=ngio_to_v05_well_meta
-)
-ImplementedMetaImporterExporter().register_plate_ie(
-    version="0.4", importer=v04_to_ngio_plate_meta, exporter=ngio_to_v04_plate_meta
-)
-ImplementedMetaImporterExporter().register_plate_ie(
-    version="0.5", importer=v05_to_ngio_plate_meta, exporter=ngio_to_v05_plate_meta
-)
-
-
-###########################################################################
-#
-# Public functions to avoid direct access to the importer/exporter
-# registration methods
-#
-###########################################################################
-
-
-def find_image_meta_handler(
-    group_handler: ZarrGroupHandler,
-    axes_setup: AxesSetup | None = None,
-    allow_non_canonical_axes: bool = False,
-    strict_canonical_order: bool = True,
-) -> ImageMetaHandler:
-    """Open an image metadata handler."""
-    return ImplementedMetaImporterExporter().find_image_handler(
-        group_handler=group_handler,
-        axes_setup=axes_setup,
-        allow_non_canonical_axes=allow_non_canonical_axes,
-        strict_canonical_order=strict_canonical_order,
-    )
+    def update_meta(self, ngio_meta: NgioWellMeta) -> None:
+        """Update the NGIO well metadata."""
+        update_ngio_meta(
+            group_handler=self._group_handler,
+            ngio_meta=ngio_meta,
+        )
 
 
-def get_image_meta_handler(
+def get_ngio_labels_group_meta(
     group_handler: ZarrGroupHandler,
-    version: str,
-    axes_setup: AxesSetup | None = None,
-    allow_non_canonical_axes: bool = False,
-    strict_canonical_order: bool = True,
-) -> ImageMetaHandler:
-    """Open an image metadata handler."""
-    return ImplementedMetaImporterExporter().get_image_meta_handler(
+    version: str | None = None,
+) -> NgioLabelsGroupMeta:
+    """Retrieve the NGIO labels group metadata from the Zarr group.
+
+    Args:
+        group_handler (ZarrGroupHandler): The Zarr group handler.
+        version (str | None): Optional NGFF version to use for decoding.
+
+    Returns:
+        NgioLabelsGroupMeta: The NGIO labels group metadata.
+    """
+    return get_ngio_meta(
         group_handler=group_handler,
+        meta_type=NgioLabelsGroupMeta,
         version=version,
-        axes_setup=axes_setup,
-        allow_non_canonical_axes=allow_non_canonical_axes,
-        strict_canonical_order=strict_canonical_order,
-    )
-
-
-def find_label_meta_handler(
-    group_handler: ZarrGroupHandler,
-    axes_setup: AxesSetup | None = None,
-    allow_non_canonical_axes: bool = False,
-    strict_canonical_order: bool = True,
-) -> LabelMetaHandler:
-    """Open a label metadata handler."""
-    return ImplementedMetaImporterExporter().find_label_handler(
-        group_handler=group_handler,
-        axes_setup=axes_setup,
-        allow_non_canonical_axes=allow_non_canonical_axes,
-        strict_canonical_order=strict_canonical_order,
     )
 
 
-def get_label_meta_handler(
+def update_ngio_labels_group_meta(
     group_handler: ZarrGroupHandler,
-    version: str,
-    axes_setup: AxesSetup | None = None,
-    allow_non_canonical_axes: bool = False,
-    strict_canonical_order: bool = True,
-) -> LabelMetaHandler:
-    """Open a label metadata handler."""
-    return ImplementedMetaImporterExporter().get_label_meta_handler(
-        group_handler=group_handler,
-        version=version,
-        axes_setup=axes_setup,
-        allow_non_canonical_axes=allow_non_canonical_axes,
-        strict_canonical_order=strict_canonical_order,
-    )
+    ngio_meta: NgioLabelsGroupMeta,
+) -> None:
+    """Update the NGIO labels group metadata in the Zarr group.
 
+    Args:
+        group_handler (ZarrGroupHandler): The Zarr group handler.
+        ngio_meta (NgioLabelsGroupMeta): The new NGIO labels group metadata.
 
-def find_well_meta_handler(group_handler: ZarrGroupHandler) -> WellMetaHandler:
-    """Open a well metadata handler."""
-    return ImplementedMetaImporterExporter().find_well_handler(
+    """
+    update_ngio_meta(
         group_handler=group_handler,
+        ngio_meta=ngio_meta,
     )
 
 
-def get_well_meta_handler(
-    group_handler: ZarrGroupHandler,
-    version: str,
-) -> WellMetaHandler:
-    """Open a well metadata handler."""
-    return ImplementedMetaImporterExporter().get_well_meta_handler(
-        group_handler=group_handler,
-        version=version,
-    )
-
+class LabelsGroupMetaHandler:
+    def __init__(
+        self,
+        group_handler: ZarrGroupHandler,
+        version: NgffVersions | None = None,
+    ):
+        self._group_handler = group_handler
+        self._version = version
 
-def find_plate_meta_handler(group_handler: ZarrGroupHandler) -> PlateMetaHandler:
-    """Open a plate metadata handler."""
-    return ImplementedMetaImporterExporter().find_plate_handler(
-        group_handler=group_handler
-    )
+        meta = self.get_meta()
+        self._version = meta.version
 
+    def get_meta(self) -> NgioLabelsGroupMeta:
+        """Retrieve the NGIO labels group metadata."""
+        return get_ngio_labels_group_meta(
+            group_handler=self._group_handler,
+            version=self._version,
+        )
 
-def get_plate_meta_handler(
-    group_handler: ZarrGroupHandler,
-    version: str,
-) -> PlateMetaHandler:
-    """Open a plate metadata handler."""
-    return ImplementedMetaImporterExporter().get_plate_meta_handler(
-        group_handler=group_handler,
-        version=version,
-    )
+    def update_meta(self, ngio_meta: NgioLabelsGroupMeta) -> None:
+        """Update the NGIO labels group metadata."""
+        update_ngio_labels_group_meta(
+            group_handler=self._group_handler,
+            ngio_meta=ngio_meta,
+        )