Fix integer COG overview poisoning by sentinel value

[brendancol]

Summary

• to_geotiff(int_data, cog=True, nodata=N) produced overview pyramids that mixed the sentinel into surrounding valid pixels for mean, min, max, and median resampling.
• The reader can't mask poisoned pixels back to NaN because they don't equal the sentinel, so the user silently sees garbage at every zoom level above 0.
• Fix masks the sentinel to NaN before the nan-aware reduction, gated on representability in the source integer dtype, and rewrites all-sentinel blocks back to the sentinel before the integer cast.
• GPU mirror in _block_reduce_2d_gpu gets the same fix for byte parity with CPU.

Repro

import numpy as np, xarray as xr, tempfile
from xrspatial.geotiff import to_geotiff, open_geotiff

H, W = 256, 256
data = np.full((H, W), 100, dtype=np.int16)
data[64:129, 64:129] = -9999

da = xr.DataArray(data, dims=('y', 'x'),
                  coords={'y': np.arange(H, dtype=np.float64),
                          'x': np.arange(W, dtype=np.float64)},
                  attrs={'crs': 4326})

with tempfile.NamedTemporaryFile(suffix='.tif', delete=False) as f:
    path = f.name

to_geotiff(da, path, nodata=-9999, cog=True,
           overview_levels=[1], overview_resampling='mean')

# Before this PR:
# Level 1 unique: [-9999 -4950 -2425   100]
# The -4950 and -2425 are sentinel-poisoned averages.
#
# After this PR:
# Level 1 unique: [-9999  100]

Test plan

• pytest xrspatial/geotiff/tests/test_cog_int_overview_nodata_2026_05_12.py -- 38 new tests pass.
• pytest xrspatial/geotiff/tests/test_cog_overview_nodata_1613.py xrspatial/geotiff/tests/test_cog_cubic_overview_nodata_1623.py -- regression coverage for the float and cubic cases still passes.
• Full geotiff suite (1606 tests pre-PR) stays green.
• CPU and GPU integer overview output is byte-equivalent (covered by test_gpu_cpu_int_overview_byte_match).

Notes

• Found via /sweep-accuracy on the geotiff module (pass 20). State CSV updated in this PR.
• No new public API. Internal helpers _block_reduce_2d and _block_reduce_2d_gpu accept a more permissive nodata kwarg; existing callers (_make_overview / make_overview_gpu / write()) pass it through unchanged.
• Deferred LOW for a future PR: _read_cog_http accepts band=-1 and silently returns the last channel, while the local / dask / GPU paths raise IndexError (added in Local eager band parameter accepts negative and out-of-range values silently #1673). Separate backend-parity gap; opening as a follow-up per the one-finding-per-PR policy.

[Copilot]

Pull request overview

This PR fixes integer COG overview “sentinel poisoning” during overview pyramid generation by ensuring integer nodata sentinel values are masked to NaN before nan-aware reductions, and that all-sentinel blocks are rewritten back to the sentinel prior to casting back to integer. This aligns CPU and GPU overview generation behavior and prevents corrupted overview values that the reader cannot later re-mask.

Changes:

• Update _block_reduce_2d (CPU) to mask representable integer sentinels to NaN for nan-aware overview reductions, and rewrite all-NaN reduced blocks back to the sentinel before integer casting.
• Apply the same integer-sentinel masking + NaN rewrite logic in _block_reduce_2d_gpu for byte-equivalent CPU/GPU overviews.
• Add a comprehensive regression test suite covering unit-level reducers, end-to-end COG round-trips, and CPU/GPU parity.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
xrspatial/geotiff/_writer.py	Fix integer overview reduction by sentinel-masking before nan-aware aggregation and restoring sentinel for all-missing blocks pre-cast; update related docstrings.
xrspatial/geotiff/_gpu_decode.py	Mirror the integer sentinel masking + all-missing rewrite logic on GPU for CPU/GPU parity.
xrspatial/geotiff/tests/test_cog_int_overview_nodata_2026_05_12.py	Add extensive regression coverage for integer nodata behavior across methods/dtypes, end-to-end COG, and CPU/GPU byte parity.
.claude/sweep-accuracy-state.csv	Update sweep accuracy state to record the finding/fix and test coverage notes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.