Be more forgiving on some broken metadata (#356)

* Add version metadata fixing for Plate

* Automatically fix transforms in wrong order

* Add changelog entry

* Implement transform swapping for v05

* Fix method name

* Add missing files

* pre-commit fixes

* Fixes

* Fix doc import

* Add TOC entry

* Minor doc improvements

Author: dstansby

.gitignore

@@ -11,3 +11,5 @@ coverage.xml
 
 # Where `mkdocs build` puts local website build
 site
+
+.idea

.pre-commit-config.yaml

@@ -53,7 +53,7 @@ repos:
     rev: v1.29.4
     hooks:
       - id: typos
-        files: \.(py|md|rst|yaml|toml)
+        files: \.(py|md|rst|toml)
         # empty to do not write fixes
         args: []
         exclude: pyproject.toml

docs/api/common/exceptions.md

@@ -0,0 +1,3 @@
+# Exceptions and warnings
+
+::: ome_zarr_models.exceptions

docs/changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.4
+
+### Fixing metadata
+
+ome-zarr-models now has support for fixing common issues with OME-Zarr metadata when loading.
+See [the metadata fixes page](fixes.md) for more information.
+
 ## 1.3
 
 ### Bug fixes

docs/fixes.md

@@ -0,0 +1,15 @@
+# Metadata fixing
+
+ome-zarr-models will attempt to fix metadata that is not technically compliant with the OME-Zarr specification, but can still be unambiguously interpreted and made compliant.
+In these cases a ValidationWarning will be emitted explaining the fix made.
+This provides a useful interface for software packages and users to read metadata with mistakes, but still access it from ome-zarr-models with those mistakes corrected.
+
+ome-zarr-models will always write specification-compliant metadata.
+The `ome-zarr-models validate` command will always raise an error on invalid metadata, regardless of whether a fix is available or not.
+
+If you have a suggestion for a fix we could add, please open an issue!
+
+## Implemented fixes
+
+- If the "version" field is not present in OME-Zarr 0.5 Plate metadata it is automatically set to `"0.5"`.
+- If the order of transforms is incorrect in OME-Zarr 0.4 images, they are automatically swapped to be in the correct order.

mkdocs.yml

@@ -82,6 +82,7 @@ nav:
   - Command line: cli.md
   - Python tutorial: tutorial.py
   - How do I...?: how-to.md
+  - Metadata fixes: fixes.md
   - API reference:
       - api/index.md
       - v05:
@@ -105,6 +106,7 @@ nav:
       - Shared:
           - Base objects: api/common/base.md
           - Validation: api/common/validation.md
+          - Exceptions: api/common/exceptions.md
           - Well: api/common/well.md
   - Changelog: changelog.md
   - Contributing: contributing.md

src/ome_zarr_models/_cli.py

@@ -2,9 +2,11 @@
 
 import argparse
 import sys
+import warnings
 from typing import TYPE_CHECKING, Literal
 
 from ome_zarr_models import __version__, open_ome_zarr
+from ome_zarr_models.exceptions import ValidationWarning
 
 if TYPE_CHECKING:
     from zarr.storage import StoreLike
@@ -70,7 +72,8 @@ def validate(path: StoreLike, version: Literal["0.4", "0.5"] | None = None) -> N
     ```
     """
     try:
-        open_ome_zarr(path, version=version)
+        with warnings.catch_warnings(action="error", category=ValidationWarning):
+            open_ome_zarr(path, version=version)
     except Exception as e:
         print(f"{e}\n")
         print(f"❌ Invalid OME-Zarr: {path}")

src/ome_zarr_models/exceptions.py

@@ -0,0 +1,10 @@
+"""
+Custom exceptions and warnings used by `ome-zarr-models`
+"""
+
+
+class ValidationWarning(UserWarning):
+    """
+    Warning emitted for OME-Zarr data that can be interpreted
+    by `ome-zarr-models`, but is not strictly compliant with the specification.
+    """

src/ome_zarr_models/v04/multiscales.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from collections import Counter
 from typing import TYPE_CHECKING, Any, Literal, Self
 
@@ -19,6 +20,7 @@
     ValidTransform,
     VectorScale,
     VectorTransform,
+    VectorTranslation,
     _build_transforms,
     _ndim,
 )
@@ -27,6 +29,7 @@
     check_ordered_scales,
     unique_items_validator,
 )
+from ome_zarr_models.exceptions import ValidationWarning
 from ome_zarr_models.v04.axes import Axes
 
 if TYPE_CHECKING:
@@ -243,23 +246,40 @@ class Transforms(BaseModel):
         transforms = Transforms(transforms=transforms_obj).transforms
         check_length(transforms, valid_lengths=[1, 2], variable_name="transforms")
 
-        maybe_scale = transforms[0]
-        if maybe_scale.type != "scale":
-            msg = (
-                "The first element of `coordinateTransformations` must be a scale "
-                f"transform. Got {maybe_scale} instead."
-            )
-            raise ValueError(msg)
-        if len(transforms) == 2:
-            maybe_trans = transforms[1]
-            if (maybe_trans.type) != "translation":
-                msg = (
-                    "The second element of `coordinateTransformations` must be a "
-                    f"translation transform. Got {maybe_trans} instead."
+        transform_types = tuple(t.type for t in transforms)
+        if transform_types == ("scale",) or transform_types == ("scale", "translation"):
+            return transforms_obj
+        elif transform_types == ("translation", "scale"):
+            if isinstance(transforms[0], VectorTranslation) and isinstance(
+                transforms[1], VectorScale
+            ):
+                # Can only do the swap if we know the vectors
+                warnings.warn(
+                    "Translation and scale are in the wrong order "
+                    "(scale should come first). Swapping transforms.",
+                    ValidationWarning,
+                    stacklevel=2,
                 )
-                raise ValueError(msg)
+                new_transforms = (
+                    transforms[1],
+                    VectorTranslation(
+                        type="translation",
+                        translation=[
+                            t * s
+                            for t, s in zip(
+                                transforms[0].translation,
+                                transforms[1].scale,
+                                strict=False,
+                            )
+                        ],
+                    ),
+                )
+                return new_transforms
 
-        return transforms_obj
+        raise ValueError(
+            "Expected a scale or (scale, translation) transform. "
+            f"Got {transform_types} instead."
+        )
 
     @field_validator("coordinateTransformations", mode="after")
     @classmethod

src/ome_zarr_models/v05/multiscales.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from collections import Counter
 from typing import TYPE_CHECKING, Any, Self
 
@@ -19,6 +20,7 @@
     ValidTransform,
     VectorScale,
     VectorTransform,
+    VectorTranslation,
     _build_transforms,
     _ndim,
 )
@@ -27,6 +29,7 @@
     check_ordered_scales,
     unique_items_validator,
 )
+from ome_zarr_models.exceptions import ValidationWarning
 from ome_zarr_models.v05.axes import Axes
 
 if TYPE_CHECKING:
@@ -242,23 +245,40 @@ class Transforms(BaseModel):
         transforms = Transforms(transforms=transforms_obj).transforms
         check_length(transforms, valid_lengths=[1, 2], variable_name="transforms")
 
-        maybe_scale = transforms[0]
-        if maybe_scale.type != "scale":
-            msg = (
-                "The first element of `coordinateTransformations` must be a scale "
-                f"transform. Got {maybe_scale} instead."
-            )
-            raise ValueError(msg)
-        if len(transforms) == 2:
-            maybe_trans = transforms[1]
-            if (maybe_trans.type) != "translation":
-                msg = (
-                    "The second element of `coordinateTransformations` must be a "
-                    f"translation transform. Got {maybe_trans} instead."
+        transform_types = tuple(t.type for t in transforms)
+        if transform_types == ("scale",) or transform_types == ("scale", "translation"):
+            return transforms_obj
+        elif transform_types == ("translation", "scale"):
+            if isinstance(transforms[0], VectorTranslation) and isinstance(
+                transforms[1], VectorScale
+            ):
+                # Can only do the swap if we know the vectors
+                warnings.warn(
+                    "Translation and scale are in the wrong order "
+                    "(scale should come first). Swapping transforms.",
+                    ValidationWarning,
+                    stacklevel=2,
                 )
-                raise ValueError(msg)
+                new_transforms = (
+                    transforms[1],
+                    VectorTranslation(
+                        type="translation",
+                        translation=[
+                            t * s
+                            for t, s in zip(
+                                transforms[0].translation,
+                                transforms[1].scale,
+                                strict=False,
+                            )
+                        ],
+                    ),
+                )
+                return new_transforms
 
-        return transforms_obj
+        raise ValueError(
+            "Expected a scale or (scale, translation) transform. "
+            f"Got {transform_types} instead."
+        )
 
     @field_validator("coordinateTransformations", mode="after")
     @classmethod