From 28502d2caba42d0cb07a5dd8a1893f15025352ba Mon Sep 17 00:00:00 2001 From: Brendan Collins Date: Mon, 18 May 2026 08:35:07 -0700 Subject: [PATCH] geotiff: sync attrs contract docs with masked_nodata (#1984) The canonical-tier description of ``nodata`` carried the hedge "intended behaviour once #1988 lands." That blocker was resolved by #2008, which added ``attrs['masked_nodata']`` and wired ``_set_nodata_attrs`` into the read paths, but the docstring text and the user-guide page were not updated to match. Rewrite the ``nodata`` entry to describe the shipping behaviour and add a ``masked_nodata`` entry alongside it in both ``xrspatial/geotiff/_attrs.py`` and ``docs/source/user_guide/attrs_contract.rst``. The pairing semantics are already locked by ``test_nodata_semantics_split_1988.py``. Refs #1984. --- docs/source/user_guide/attrs_contract.rst | 7 +++++++ xrspatial/geotiff/_attrs.py | 12 +++++++++--- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/source/user_guide/attrs_contract.rst b/docs/source/user_guide/attrs_contract.rst index a309c0c31..25e161640 100644 --- a/docs/source/user_guide/attrs_contract.rst +++ b/docs/source/user_guide/attrs_contract.rst @@ -63,6 +63,13 @@ write. primary nodata source. The read-side precedence chain is ``nodata``, then ``nodatavals``, then ``_FillValue``; see ``_resolve_nodata_attr``. + * - ``masked_nodata`` + - bool + - Paired with ``nodata``. ``True`` when the in-memory array is + float dtype and the reader's sentinel-to-NaN step ran; + ``False`` when the array still carries the literal integer + sentinel. Only set when ``nodata`` is set; absence means no + declared sentinel. * - ``raster_type`` - str - ``'point'`` when the file declares ``RasterPixelIsPoint``; diff --git a/xrspatial/geotiff/_attrs.py b/xrspatial/geotiff/_attrs.py index 2d6752026..d0da7c148 100644 --- a/xrspatial/geotiff/_attrs.py +++ b/xrspatial/geotiff/_attrs.py @@ -37,9 +37,15 @@ ``(pixel_width, 0.0, origin_x, 0.0, pixel_height, origin_y)``. Omitted for files with no GeoTIFF transform tags (ModelTransformation, ModelPixelScale, or ModelTiepoint). -- ``nodata``: declared file sentinel as stored in the GDAL_NODATA tag. The - declared-vs-masked split is tracked in issue #1988; the canonical - semantics here describe the intended behaviour once #1988 lands. +- ``nodata``: declared file sentinel as stored in the GDAL_NODATA tag. + Set whenever the source declares one, as a scalar of the source + dtype, regardless of whether the in-memory array is float-with-NaN + or int-with-sentinels. +- ``masked_nodata``: boolean flag paired with ``nodata``. ``True`` iff + the in-memory array is float dtype and the reader's sentinel-to-NaN + step ran; ``False`` iff the array still carries the literal integer + sentinel. Only emitted when ``nodata`` is set; absence is the + "no declared sentinel" signal. See ``_set_nodata_attrs``. - ``raster_type``: ``'area'`` (implicit / RasterPixelIsArea) or ``'point'`` (explicit / RasterPixelIsPoint). - ``extra_tags``: list of ``(tag_id, type_id, count, value)`` tuples for