From 546c67c5eb26bc89e885009138c3cb44832ba6e6 Mon Sep 17 00:00:00 2001
From: Brendan Collins <brendancol@gmail.com>
Date: Sun, 17 May 2026 20:38:53 -0700
Subject: [PATCH] geotiff: follow-up review nits from #1984 PRs 2 and 5

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.
---
 docs/source/user_guide/attrs_contract.rst     | 28 ++++++++++++-------
 .../tests/test_attrs_contract_aliases_1984.py |  3 ++
 2 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/docs/source/user_guide/attrs_contract.rst b/docs/source/user_guide/attrs_contract.rst
index ba79f4243..c1a04ec11 100644
--- a/docs/source/user_guide/attrs_contract.rst
+++ b/docs/source/user_guide/attrs_contract.rst
@@ -42,20 +42,26 @@ write.
      - EPSG code of the horizontal CRS, when one can be resolved.
    * - ``crs_wkt``
      - str
-     - WKT2 string of the horizontal CRS. Always present on read when
-       any CRS information is available, and treated as the canonical
-       CRS representation when both ``crs`` and ``crs_wkt`` are set.
+     - WKT string of the horizontal CRS. Present on read when any CRS
+       information is available, and treated as the canonical CRS
+       representation when both ``crs`` and ``crs_wkt`` are set. The
+       dialect depends on the source: paths that synthesise a WKT from
+       an EPSG code via pyproj emit WKT2; paths that read a WKT
+       verbatim from the file (e.g. a VRT ``SRS`` tag) carry whatever
+       dialect was stored.
    * - ``transform``
      - tuple
-     - ``(origin_x, pixel_width, 0, origin_y, 0, pixel_height)``
-       affine transform tuple matching the GDAL ordering. Omitted for
-       files with no ``ModelTransformation`` / ``ModelPixelScale`` /
-       ``ModelTiepoint`` tags.
+     - ``(pixel_width, 0.0, origin_x, 0.0, pixel_height, origin_y)``
+       affine transform tuple matching the rasterio ``Affine`` ordering.
+       Omitted for files with no ``ModelTransformation`` /
+       ``ModelPixelScale`` / ``ModelTiepoint`` tags.
    * - ``nodata``
      - scalar
      - Numeric NoData sentinel. Emitted by readers when the file
        carries a ``GDAL_NODATA`` tag, and consumed by writers as the
-       primary nodata source.
+       primary nodata source. The read-side precedence chain is
+       ``nodata``, then ``nodatavals``, then ``_FillValue``; see
+       ``_resolve_nodata_attr``.
    * - ``raster_type``
      - str
      - ``'point'`` when the file declares ``RasterPixelIsPoint``;
@@ -176,11 +182,13 @@ must not assume a specific pass-through key survives a round-trip.
      - Raw ``ColorMap`` TIFF tag (tag id 320) values.
    * - ``colormap_rgba``
      - array
-     - Decoded RGBA colormap, when one is present.
+     - Decoded RGBA colormap. Emitted only when the file's photometric
+       interpretation is ``Photometric == 3`` (palette).
    * - ``cmap``
      - ``matplotlib.colors.ListedColormap``
      - Matplotlib colormap built from ``colormap_rgba``. Present only
-       when matplotlib is importable.
+       when matplotlib is importable and the same ``Photometric == 3``
+       gate is satisfied.
 
 
 Round-trip invariants
diff --git a/xrspatial/geotiff/tests/test_attrs_contract_aliases_1984.py b/xrspatial/geotiff/tests/test_attrs_contract_aliases_1984.py
index 0ab9c0c0f..ef10eecc5 100644
--- a/xrspatial/geotiff/tests/test_attrs_contract_aliases_1984.py
+++ b/xrspatial/geotiff/tests/test_attrs_contract_aliases_1984.py
@@ -29,6 +29,9 @@
 from xrspatial.geotiff._attrs import _resolve_nodata_attr
 
 
+# Arbitrary float-castable sentinel that is distinct from any data value
+# used below. The value itself does not matter; the tests assert it
+# survives the alias resolver and the round-trip.
 _SENTINEL = -9999.0