geotiff: add attrs contract documentation page (#1984)#2001
Merged
Conversation
Adds docs/source/user_guide/attrs_contract.rst describing the three-tier attrs contract enforced by the geotiff entry points: * Canonical keys owned by xrspatial (crs, crs_wkt, transform, nodata, raster_type, extra_tags, gdal_metadata, gdal_metadata_xml, x_resolution, y_resolution, resolution_unit, _xrspatial_geotiff_contract). * Compatibility aliases recognised on read but never re-emitted on write (nodatavals, _FillValue). * Pass-through keys surfaced from GeoKeys; the writer reconstructs what it can from crs / crs_wkt and drops the rest silently. Documents per-tier round-trip invariants and the contract version key (_xrspatial_geotiff_contract = 1). Links the new page from docs/source/user_guide/index.rst.
Contributor
Author
PR Review: geotiff: add attrs contract documentation pageBlockers (must fix before merge)
Suggestions (should fix, not blocking)
Nits (optional improvements)
What looks good
Checklist
|
1 task
brendancol
added a commit
that referenced
this pull request
May 17, 2026
- transform: corrected layout to the rasterio Affine ordering (pixel_width, 0.0, origin_x, 0.0, pixel_height, origin_y) that _transform_tuple_from_pixel_geometry actually emits, and replaced the "GDAL ordering" label with "rasterio Affine ordering". - crs_wkt: relaxed "Always present" and "WKT2 string" to reflect that the dialect depends on the source path (pyproj synthesis is WKT2; VRT SRS-tag passthrough carries whatever dialect was on disk). - nodata: documented the read-side precedence chain (nodata, nodatavals, _FillValue) as codified in _resolve_nodata_attr. - colormap_rgba and cmap: noted the Photometric == 3 gate that the reader applies before emitting either attr.
2 tasks
brendancol
added a commit
that referenced
this pull request
May 18, 2026
Two nits from the post-merge reviews on #2001 and #2002 that did not make it into the merged commits. #2001 user-guide page (``docs/source/user_guide/attrs_contract.rst``): - ``transform``: corrected layout from ``(origin_x, pixel_width, 0, origin_y, 0, pixel_height)`` (GDAL ordering) to the rasterio Affine ordering ``(pixel_width, 0.0, origin_x, 0.0, pixel_height, origin_y)`` that ``_transform_tuple_from_pixel_geometry`` actually emits. - ``crs_wkt``: relaxed "Always present" and "WKT2 string" to reflect that the dialect depends on the source path (pyproj synthesis is WKT2; VRT SRS-tag passthrough carries whatever dialect was on disk). - ``nodata``: documented the read-side precedence chain (``nodata``, then ``nodatavals``, then ``_FillValue``) as codified in ``_resolve_nodata_attr``. - ``colormap_rgba`` / ``cmap``: noted the ``Photometric == 3`` gate that the reader applies before emitting either attr. #2002 alias locking test (``xrspatial/geotiff/tests/test_attrs_contract_aliases_1984.py``): - ``_SENTINEL``: added a one-line comment that the value just needs to be float-castable and distinct from data; the resolver and round-trip assertions are what the tests pin. Coordinates with the canonical-tier docstring already corrected on ``_attrs.py`` in main.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR 2 of 7 implementing issue #1984.
Summary
Adds a user-guide page documenting the three-tier attrs contract emitted by the geotiff readers and consumed by the writers.
crs,crs_wkt,transform,nodata,raster_type,extra_tags,gdal_metadata,gdal_metadata_xml,x_resolution,y_resolution,resolution_unit,_xrspatial_geotiff_contract.nodatavals(rioxarray),_FillValue(CF).The page states per-tier round-trip invariants and explains the
_xrspatial_geotiff_contract = 1version key for future revisions.Test plan
:func:roles flagged as unknown, same pattern as the existingdocs/source/reference/geotiff.rst).sphinx-buildfails on an unrelatedconf.pyimport error from a cupy/dask/python 3.14 mismatch; CI runs in a clean env).docs/source/user_guide/index.rstlistsattrs_contractin the toctree so the page is reachable.