Add Spatial Zarr Convention models and metadata (#100)

* feat: add Spatial Zarr Convention models and metadata

- Introduced models for the Spatial Zarr Convention in spatial.py.
- Defined SpatialConvention and SpatialConventionMetadata classes with relevant metadata.
- Implemented Spatial model with fields for dimensions, bounding box, transformation type, transformation matrix, shape, and registration.
- Utilized Pydantic for data validation and serialization.

* fix: enhance multiscales metadata handling with fallback for bounds and transform

* Update eopf-geozarr version to 0.5.1.dev18+g4528bb6b0.d20251216 in uv.lock

* fix: improve formatting and consistency in geospatial metadata classes

* feat: add spatial properties to overview level metadata and update type definitions

* feat: implement tests for Spatial Zarr Convention models and metadata

* feat: enhance Proj and ProjConventionMetadata tests for serialization and validation

* feat: add validation for non-empty dimensions in Spatial model

* fix: remove redundant imports of ProjConventionMetadata and SpatialConventionMetadata in s2_multiscale.py

* feat: add spatial properties and projection information to Zarr convention metadata for S2A, S2B, and S2C examples

* feat: update spatial metadata and derivation chains in Zarr examples for improved consistency

* fix: remove redundant version field from MultiscaleMeta and Multiscales classes

* refactor: streamline spatial metadata calculation and error handling in write_geo_metadata function

* fix: remove redundant version field from multiscales and optimized geozarr example JSON files

* fix: improve transform calculation logging for multiscales metadata

* fix: add validation for spatial transform data to prevent all-zero entries

* fix: remove redundant spatial transform entries from optimized geozarr example JSON files

* fix: allow spatial_transform to be None in OverviewLevelJSON type definition

* fix: refactor ScaleLevel initialization and remove redundant spatial_transform entries

Author: emmanuelmathot

.vscode/launch.json

@@ -1,54 +1,61 @@
 """
-Models for the GeoProj Zarr Convention
+Models for the Proj Zarr Convention (v1.0)
 """
 
 from __future__ import annotations
 
-from typing import Literal, Self
+from typing import Literal
 
 from pydantic import BaseModel, Field, model_validator
 from typing_extensions import TypedDict
 
-from eopf_geozarr.data_api.geozarr.common import is_none
+from eopf_geozarr.data_api.geozarr.common import ZarrConventionMetadata, is_none
 from eopf_geozarr.data_api.geozarr.projjson import ProjJSON  # noqa: TC001
 
-GEO_PROJ_UUID: Literal["f17cb550-5864-4468-aeb7-f3180cfb622f"] = (
-    "f17cb550-5864-4468-aeb7-f3180cfb622f"
-)
+PROJ_UUID: Literal["f17cb550-5864-4468-aeb7-f3180cfb622f"] = "f17cb550-5864-4468-aeb7-f3180cfb622f"
 
 
-class GeoProjConvention(TypedDict):
-    version: Literal["0.1.0"]
-    schema: Literal[
-        "https://raw.githubusercontent.com/zarr-experimental/geo-proj/refs/tags/v0.1.0/schema.json"
+class ProjConvention(TypedDict):
+    uuid: Literal["f17cb550-5864-4468-aeb7-f3180cfb622f"]
+    name: Literal["proj:"]
+    schema_url: Literal[
+        "https://raw.githubusercontent.com/zarr-experimental/geo-proj/refs/tags/v1/schema.json"
     ]
-    name: Literal["geo-proj"]
+    spec_url: Literal["https://github.com/zarr-experimental/geo-proj/blob/v1/README.md"]
     description: Literal["Coordinate reference system information for geospatial data"]
-    spec: Literal["https://github.com/zarr-experimental/geo-proj/blob/v0.1.0/README.md"]
 
 
-GeoProjConventions = TypedDict(  # type: ignore[misc]
-    "GeoProjConventions", {GEO_PROJ_UUID: GeoProjConvention}, closed=False
-)
+class ProjConventionMetadata(ZarrConventionMetadata):
+    uuid: Literal["f17cb550-5864-4468-aeb7-f3180cfb622f"] = PROJ_UUID
+    name: Literal["proj:"] = "proj:"
+    schema_url: Literal[
+        "https://raw.githubusercontent.com/zarr-experimental/geo-proj/refs/tags/v1/schema.json"
+    ] = "https://raw.githubusercontent.com/zarr-experimental/geo-proj/refs/tags/v1/schema.json"
+    spec_url: Literal["https://github.com/zarr-experimental/geo-proj/blob/v1/README.md"] = (
+        "https://github.com/zarr-experimental/geo-proj/blob/v1/README.md"
+    )
+    description: Literal["Coordinate reference system information for geospatial data"] = (
+        "Coordinate reference system information for geospatial data"
+    )
 
 
-class GeoProj(BaseModel):
+class Proj(BaseModel):
+    # At least one of code, wkt2, or projjson must be provided
     code: str | None = Field(None, alias="proj:code", exclude_if=is_none)
     wkt2: str | None = Field(None, alias="proj:wkt2", exclude_if=is_none)
     projjson: ProjJSON | None = Field(None, alias="proj:projjson", exclude_if=is_none)
-    spatial_dimensions: tuple[str, str] = Field(alias="proj:spatial_dimensions")
-    transform: tuple[float, float, float, float, float, float] | None = Field(
-        None, alias="proj:transform", exclude_if=is_none
-    )
-    bbox: tuple[float, float, float, float] | None = Field(
-        None, alias="proj:bbox", exclude_if=is_none
-    )
-    shape: tuple[int, int] | None = Field(None, alias="proj:shape", exclude_if=is_none)
 
     model_config = {"extra": "allow", "serialize_by_alias": True}
 
     @model_validator(mode="after")
-    def ensure_required_conditional_attributes(self) -> Self:
-        if self.code is None and self.wkt2 is None and self.projjson is None:
-            raise ValueError("One of 'code', 'wkt2', or 'projjson' must be provided.")
+    def validate_at_least_one_crs(self) -> Proj:
+        """Validate that at least one CRS field is provided"""
+        if not any([self.code, self.wkt2, self.projjson]):
+            raise ValueError(
+                "At least one of proj:code, proj:wkt2, or proj:projjson must be provided"
+            )
         return self
+
+
+# Backwards compatibility alias
+GeoProj = Proj

src/eopf_geozarr/data_api/geozarr/geoproj.py

@@ -103,6 +103,7 @@ class Multiscales(BaseModel):
 
 
 class MultiscalesJSON(TypedDict):
+    version: NotRequired[str]
     layout: tuple[ScaleLevelJSON, ...]
     resampling_method: NotRequired[str]
 

src/eopf_geozarr/data_api/geozarr/multiscales/zcm.py

@@ -0,0 +1,58 @@
+"""
+Models for the Spatial Zarr Convention
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+from typing_extensions import TypedDict
+
+from eopf_geozarr.data_api.geozarr.common import ZarrConventionMetadata, is_none
+
+SPATIAL_UUID: Literal["689b58e2-cf7b-45e0-9fff-9cfc0883d6b4"] = (
+    "689b58e2-cf7b-45e0-9fff-9cfc0883d6b4"
+)
+
+
+class SpatialConvention(TypedDict):
+    uuid: Literal["689b58e2-cf7b-45e0-9fff-9cfc0883d6b4"]
+    name: Literal["spatial:"]
+    schema_url: Literal[
+        "https://raw.githubusercontent.com/zarr-conventions/spatial/refs/tags/v1/schema.json"
+    ]
+    spec_url: Literal["https://github.com/zarr-conventions/spatial/blob/v1/README.md"]
+    description: Literal["Spatial coordinate and transformation information"]
+
+
+class SpatialConventionMetadata(ZarrConventionMetadata):
+    uuid: Literal["689b58e2-cf7b-45e0-9fff-9cfc0883d6b4"] = SPATIAL_UUID
+    name: Literal["spatial:"] = "spatial:"
+    schema_url: Literal[
+        "https://raw.githubusercontent.com/zarr-conventions/spatial/refs/tags/v1/schema.json"
+    ] = "https://raw.githubusercontent.com/zarr-conventions/spatial/refs/tags/v1/schema.json"
+    spec_url: Literal["https://github.com/zarr-conventions/spatial/blob/v1/README.md"] = (
+        "https://github.com/zarr-conventions/spatial/blob/v1/README.md"
+    )
+    description: Literal["Spatial coordinate and transformation information"] = (
+        "Spatial coordinate and transformation information"
+    )
+
+
+class Spatial(BaseModel):
+    dimensions: list[str] = Field(alias="spatial:dimensions")  # Required field
+    bbox: list[float] | None = Field(None, alias="spatial:bbox", exclude_if=is_none)
+    transform_type: str = Field("affine", alias="spatial:transform_type")
+    transform: list[float] | None = Field(None, alias="spatial:transform", exclude_if=is_none)
+    shape: list[int] | None = Field(None, alias="spatial:shape", exclude_if=is_none)
+    registration: str = Field("pixel", alias="spatial:registration")
+
+    model_config = {"extra": "allow", "serialize_by_alias": True}
+
+    @model_validator(mode="after")
+    def validate_dimensions_not_empty(self) -> Spatial:
+        """Validate that dimensions list is not empty."""
+        if not self.dimensions:
+            raise ValueError("spatial:dimensions must contain at least one dimension")
+        return self