Implement Zarr spatial and proj conventions support by emmanuelmathot · Pull Request #883 · corteva/rioxarray

emmanuelmathot · 2025-12-12T14:54:46Z

Draft for Zarr conventions support according to plan in #882

Closes Proposal: Support Zarr Spatial and Geo-Projection Conventions in rioxarray #882
Tests added
Fully documented, including docs/history.rst for all changes and docs/rioxarray.rst for new API

…g and formatting utilities

…sions' attribute in XRasterBase

rioxarray/crs.py

… for spatial and proj attributes

rioxarray/crs.py

- Introduced a new module `rioxarray/_convention/zarr.py` for handling Zarr conventions. - Implemented functions to read and write CRS and spatial metadata according to Zarr specifications. - Added an enumeration `Convention` in `rioxarray/enum.py` to manage geospatial metadata conventions (CF and Zarr). - Updated `rioxarray/_options.py` to include convention options and validators. - Modified `rioxarray/rioxarray.py` to utilize the new convention architecture for reading and writing CRS and transforms. - Created integration tests for the new convention architecture in `test/integration/test_convention_architecture.py`. - Added unit tests for convention functionality in `test/test_convention_architecture.py`.

rioxarray/rioxarray.py

snowman2 · 2025-12-12T16:52:03Z

If convention is None it should attempt to read both with preference to CF.

rioxarray/_options.py

rioxarray/rioxarray.py

- Added entry in history.rst for Zarr spatial and proj conventions support with Convention enum and Zarr-specific methods (corteva#883). - Included a new section for conventions in index.rst. - Documented the rioxarray.Convention class in rioxarray.rst.

…onvention handling

…n not specified

…hod and improve dimension detection fallback

… CRS reading

…ve test cases

… and improve clarity on default behaviors

…s for attributes

… maintainability

…for Zarr conventions

…ove test coverage

rioxarray/rioxarray.py

snowman2 · 2025-12-17T19:23:11Z

In general, I would like to see only the minimum code needed for rio.write_crs and rio.write_tranform added to this MR. All other code can be discussed later. The reason is to simplify code maintenance and the diff in this PR.

This process may even benefit from breaking down the pieces into separate MRs:

MR 1: Add convention option & move CF to _conventions/cf.py
MR 2: Reading Zarr CRS, Transform, spatial
MR 3: Writing Zarr CRS
MR 4: Writing Zarr Transform
MR ...: Other Zarr convention components

Dividing it up this way will help each component get the review it needs. But, we can stick to a big MR if you prefer,

…Zarr conventions

snowman2 · 2025-12-18T16:13:47Z

rioxarray/_convention/zarr.py

+    return json.loads(projjson_str)
+
+
+def calculate_spatial_bbox(


You could use rasterio.transform.array_bounds to simplify this.

snowman2 · 2025-12-18T16:23:09Z

docs/conventions.rst

+
+When reading geospatial metadata, rioxarray follows this priority order based on the global convention setting:
+
+- **None (default)**: CF conventions first, with Zarr conventions as fallback if explicitly declared


I would like both conventions attempted when reading files regardless of the convention setting. The convention setting changing the search priority is fine. This way you can read in files from either format at the same time with the convention setting set.

snowman2 · 2025-12-18T16:24:12Z

For testing:

Please don't use the class format. Instead, use the functional format.

Imports:

Please import at the top of the file.

snowman2 · 2025-12-18T16:25:18Z

rioxarray/crs.py

+
+    # Handle PROJJSON dict (Zarr proj:projjson convention)
+    if isinstance(crs_input, dict):
+        crs_input = CRS.from_json_dict(crs_input)


This should be handled with CRS.from_user_input below.

https://github.com/rasterio/rasterio/blob/cf0cb0e9fb0c8702cc3bea032d8ad2c1d8c1b44c/rasterio/crs.pyx#L738

snowman2 · 2025-12-18T16:31:18Z

rioxarray/_convention/zarr.py

+    return attrs_out
+
+
+def write_conventions(


This is an extra function I would prefer not included in this PR.

snowman2 · 2025-12-18T16:46:21Z

docs/getting_started/crs_management.ipynb

    "- [rio.write_transform()](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.write_transform)\n",
-    "- [rio.transform()](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.transform)"
+    "- [rio.transform()](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.transform)\n",
+    "- [rio.write_zarr_crs()](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.write_zarr_crs) - New Zarr method\n",


The zarr methods are removed.

snowman2 · 2025-12-18T16:47:20Z

docs/getting_started/crs_management.ipynb

    "- [rio.write_transform()](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.write_transform)\n",
-    "- [rio.transform()](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.transform)"
+    "- [rio.transform()](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.transform)\n",
+    "- [rio.write_zarr_transform()](../rioxarray.rst#rioxarray.rioxarray.XRasterBase.write_zarr_transform) - Zarr-specific method"


zarr method removed.

snowman2 · 2025-12-18T16:47:58Z

docs/getting_started/crs_management.ipynb

+   "id": "5e08da24",
+   "metadata": {},
+   "source": [
+    "## Zarr-Specific Methods\n",


These have been removed.

snowman2 · 2025-12-18T16:48:53Z

rioxarray/__init__.py

 from rioxarray._io import open_rasterio
 from rioxarray._options import set_options
 from rioxarray._show_versions import show_versions
+from rioxarray.enum import Convention


I would prefer this not be added here and stay in the enum namespace for now.

snowman2 · 2025-12-18T16:49:56Z

docs/rioxarray.rst

 .. autoclass:: rioxarray.set_options


+rioxarray.Convention


Move to docs/enum.rst

snowman2 · 2025-12-18T16:51:43Z

pyproject.toml

 requires-python = ">=3.12"
 dependencies = [
    "packaging",
-    "rasterio>=1.4.3",


Please don't remove the dependency pin.

snowman2 · 2025-12-18T16:52:01Z

.pre-commit-config.yaml

@@ -1,5 +1,5 @@
-default_language_version:
-    python: python3.12


Please don't modify this in this PR.

snowman2 · 2025-12-18T16:52:34Z

pyproject.toml

 all = [
    "scipy"
 ]
+test = [


Please don't modify dependencies in this PR.

alfredoahds

Seconding Alan's comment about minimizing the MR surface making this easier to review.

Overall this seems good, one nitpick is the recurring series of

if convention is ...:
   ...
elif convention is ...:
   ...

Maybe we can define a common interface for the convention modules and simplify this down? There will be some unused args in the zarr methods but having something like

convention = _get_convention(convention_input or get_option(CONVENTION))
parsed_crs = convention.read_crs(...)

would reduce that duplication/series of ifs.

alfredoahds · 2025-12-18T17:29:42Z

rioxarray/rioxarray.py

+            # Use CF convention logic for dimension detection
+            # Also use this as fallback when convention is None
+            if "x" in self._obj.dims and "y" in self._obj.dims:
+                self._x_dim = "x"
+                self._y_dim = "y"
+            elif "longitude" in self._obj.dims and "latitude" in self._obj.dims:
+                self._x_dim = "longitude"
+                self._y_dim = "latitude"
+            else:
+                # look for coordinates with CF attributes
+                for coord in self._obj.coords:
+                    # make sure to only look in 1D coordinates
+                    # that has the same dimension name as the coordinate
+                    if self._obj.coords[coord].dims != (coord,):
+                        continue
+                    if (
+                        self._obj.coords[coord].attrs.get("axis", "").upper() == "X"
+                    ) or (
+                        self._obj.coords[coord].attrs.get("standard_name", "").lower()
+                        in ("longitude", "projection_x_coordinate")
+                    ):
+                        self._x_dim = coord
+                    elif (
+                        self._obj.coords[coord].attrs.get("axis", "").upper() == "Y"
+                    ) or (
+                        self._obj.coords[coord].attrs.get("standard_name", "").lower()
+                        in ("latitude", "projection_y_coordinate")
+                    ):
+                        self._y_dim = coord


Thoughts on moving this bit into rioxarray._convention.cf.read_spatial_dimensions so there's a consistent interface for the convention options?

This is the first in a series of PRs splitting corteva#883 as requested by maintainers. **Changes:** - Add `Convention` enum with `CF` value - Add `convention` option to `set_options()` - Create cf.py module with extracted CF read/write logic - Refactor rioxarray.py to use the new CF module This PR establishes the framework for supporting multiple geospatial metadata conventions. Future PRs will add Zarr convention support. --- - [ ] Closes corteva#883 (partial - first of series) - [x] Tests added - [] Fully documented, including history.rst for all changes and rioxarray.rst for new API

emmanuelmathot · 2026-01-28T14:57:00Z

PR#1 : #899
PR#2: #900

emmanuelmathot added 2 commits December 12, 2025 15:48

FEAT: Implement Zarr spatial and proj conventions support with parsin…

19b41ae

…g and formatting utilities

FEAT: Enhance spatial dimension handling to prioritize 'spatial:dimen…

608f3a9

…sions' attribute in XRasterBase