geotiff: canonical round-trip invariants module (#1986)

[brendancol]

Summary

First slice of issue #1986. Adds xrspatial/geotiff/tests/test_round_trip_invariants.py -- one canonical module that enumerates the supported round-trip cases and pins the invariant per case.

The existing per-incident round-trip files (test_metadata_round_trip_1484.py, test_int_coords_round_trip_hotfix_1962.py, test_no_georef_writer_round_trip_1949.py, test_miniswhite_writer_roundtrip_1836.py) stay as regression markers for their bug numbers. This module is the canonical contract going forward.

Cases covered

Case	Invariant	Notes
int single-band, no nodata	byte-equivalent	int16 / int32 / uint16
float single-band, no nodata	byte-equivalent	float32 / float64; NaN-as-data preserved without synthetic GDAL_NODATA
int with declared nodata	documented drift	reader promotes int -> float64 + NaN; valid pixels byte-equal, sentinel survives in attrs
multiband chunky	byte-equivalent	2 / 3 / 4 bands
no-georef	semantic	transform / crs attrs absent on read and through round-trip
PixelIsPoint	byte-equivalent	raster_type attr round-trips; default PixelIsArea leaves it absent

Each case also asserts fixed-point convergence: a second write -> read cycle reproduces the first read exactly (pixels, dtype, dims, attrs key set).

Deferred to follow-up PRs

Called out in the module docstring:

• Float with non-NaN declared nodata -- depends on the masked / declared nodata split from issue geotiff: split declared nodata from masked-data state in DataArray attrs #1988.
• Planar multiband -- the writer emits chunky only.
• Overviews / COG.
• VRT round-trip with XML normalisation.

Test plan

• pytest xrspatial/geotiff/tests/test_round_trip_invariants.py -v -- 14 passed
• CI green on the existing geotiff suite (the per-incident round-trip files are untouched)

Closes part of #1986.

[brendancol]

PR Review: geotiff: canonical round-trip invariants module (#1986)

Test-only PR. Steps for algorithm correctness, backend dispatch, CUDA register pressure, and README feature matrix do not apply -- no production code changed, no new public API. Review focuses on test quality, the asserted invariants, and coverage gaps the module itself flags.

Blockers

None.

Suggestions

• _assert_fixed_point compares the attrs key set but not the values of canonical attrs. A writer regression that flips crs from 32610 to a WKT string, or perturbs transform, would pass the current check. Lock value parity for crs, transform, nodata, raster_type when present on both sides. Fixed in df2273a.
• TestIntSingleBandNoNodata and TestMultibandChunky do not assert 'nodata' not in attrs. The float-no-nodata test does. Add the symmetric assertion so the reader cannot quietly start emitting a synthetic sentinel. Fixed in df2273a.

Nits

• arr[arr != -9999].ravel() in TestIntWithDeclaredNodata::test_int32_sentinel_promotes_and_masks -- a boolean-masked array is already 1D, .ravel() is a no-op. Fixed in df2273a.
• TestNoGeorefSemantic::test_no_transform_survives_round_trip does not assert dtype on the read DataArray. Added a da1.dtype == np.float32 check so the array equality cannot accidentally pass via broadcasting. Fixed in df2273a.

What looks good

• Module docstring states the two invariants explicitly and the deferred cases so a reader knows what is and is not promised.
• Fixed-point convergence (_assert_fixed_point) is checked per case, which is the missing piece in the per-incident files.
• The int-with-declared-nodata case is documented as drift rather than asserted-clean, which keeps the test honest while geotiff: split declared nodata from masked-data state in DataArray attrs #1988's masked / declared split is pending.
• Filenames carry the _1986 suffix and live under tmp_path, so parallel test runs and other worktrees will not collide.

Checklist

• Algorithm matches reference/paper -- N/A, test-only.
• All implemented backends produce consistent results -- N/A, no backend dispatch changed; the reader/writer paths under test are numpy-only.
• NaN handling is correct -- np.isnan mask, no == np.nan.
• Edge cases are covered by tests -- multiple dtypes, NaN-as-data, no-georef, PixelIsPoint, default PixelIsArea absent.
• Dask chunk boundaries handled correctly -- N/A, no dask in this slice.
• No premature materialization or unnecessary copies -- N/A.
• Benchmark exists or is not needed -- not needed; contract tests.
• README feature matrix updated (if applicable) -- N/A.
• Docstrings present and accurate -- module and class docstrings explain the invariant per case.