geotiff: extract read_geotiff_gpu to _backends/gpu.py (#1885)

[brendancol]

Summary

Step 7 of #1813's multi-PR refactor of xrspatial/geotiff/__init__.py. Pure code motion; no public API change. Biggest single-function move in the sequence.

Moved into a new xrspatial/geotiff/_backends/gpu.py:

• read_geotiff_gpu — GPU read entry point (~640 lines, the largest single function in __init__.py).
• _gds_chunk_path_available — predicate gating the GDS direct-to-GPU chunked path.
• _decode_window_gpu_direct — per-chunk disk→GPU decode used by the GDS path.
• _read_geotiff_gpu_chunked — lazy Dask+CuPy graph builder for read_geotiff_gpu(chunks=...).
• _read_geotiff_gpu_chunked_gds — direct-to-GPU specialisation when KvikIO + a chunky tiled local file qualifies.

Function bodies are unchanged except for adjusted relative imports (._X → .._X outside _backends, ._gpu_helpers for the already-extracted GPU helpers from #1894). __init__.py re-exports read_geotiff_gpu so from xrspatial.geotiff import read_geotiff_gpu keeps working. The four private helpers are not re-exported because they were only called by read_geotiff_gpu itself; nothing outside the GPU read flow references them.

Test update

One existing test had to update its monkeypatch target: test_gpu_chunks_out_of_core_1876.py patches _decode_window_gpu_direct to spy on chunk-decode calls. The target moves from xrspatial.geotiff to xrspatial.geotiff._backends.gpu so the spy still intercepts the real call site (module-global lookup happens in the defining module). Both spy tests (uses_gds_path_when_available, fallback_when_kvikio_absent) pass after the update.

Circular-import note

The Dask+CuPy chunked-fallback path needs read_geotiff_dask, which still lives in __init__.py. To avoid a circular import, _read_geotiff_gpu_chunked lazy-imports it inside the function body (from .. import read_geotiff_dask). PR #8 (#1886) will move read_geotiff_dask into _backends/dask.py; the lazy import can be promoted to a static one then.

Diff stats

• __init__.py: 3969 → 2962 (-1007 lines, the single biggest reduction in the series).
• New _backends/gpu.py: 1047 lines.

Test plan

• Pixel-byte-parity matrix from geotiff: add end-to-end pixel-byte-parity test matrix (#1879) #1889 — 192/192 pass.
• Runtime-sentinel identity tests from geotiff: extract sentinels, fallback warning, strict-mode helper to _runtime.py (#1880) #1890 — 9/9 pass.
• GPU byteswap (GPU read of big-endian multi-byte TIFFs crashes on cupy.ndarray.byteswap() #1508), GPU kwarg rename (geotiff: gpu keyword has three incompatible value spaces across the public API #1560), GPU chunks out-of-core (geotiff: read_geotiff_gpu(chunks=...) is not actually out-of-core #1876) — all pass, including the GDS spy tests after the monkeypatch-target update.
• Full geotiff suite minus 8 pre-existing main failures (the read_to_array monkeypatch + tile_size_positive_works) — 2862/2862 green.

Closes #1885. Refs #1813.

[Copilot]

Pull request overview

This PR continues the GeoTIFF backend refactor by moving the GPU read entry point and its GPU-chunking helpers out of xrspatial/geotiff/__init__.py into a dedicated backend module while preserving the public read_geotiff_gpu import.

Changes:

• Adds xrspatial/geotiff/_backends/gpu.py containing read_geotiff_gpu and related private GPU chunk helpers.
• Re-exports read_geotiff_gpu from xrspatial.geotiff.
• Updates GPU chunk tests to monkeypatch the helper in its new module.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
xrspatial/geotiff/_backends/gpu.py	New home for GPU GeoTIFF read implementation and private chunk/GDS helpers.
xrspatial/geotiff/__init__.py	Removes the moved implementation and imports the public GPU read entry point from the backend module.
xrspatial/geotiff/tests/test_gpu_chunks_out_of_core_1876.py	Updates monkeypatch targets for moved GPU chunk helper.

Comments suppressed due to low confidence (1)

xrspatial/geotiff/_backends/gpu.py:785

• The mmap fallback in the direct chunk decoder also omits the LERC masked_fill value when calling gpu_decode_tiles. If KvikIO is present but unusable and this fallback runs, LERC valid-mask pixels keep the decoder's zero fill instead of being restored to nodata, so the later nodata mask cannot match them.

        arr_gpu = gpu_decode_tiles(
            compressed_tiles, tw, th, sub_w, sub_h,
            compression, predictor, file_dtype, samples,
            byte_order=byte_order,
        )

---

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

[brendancol]

Addressed Copilot's three line comments:

1. F401 on unused GPU-helper re-imports in __init__.py — fixed in 9275b5b. Dropped _apply_nodata_mask_gpu, _apply_orientation_geo_info, _apply_orientation_gpu, _gpu_apply_window_band, and _gpu_decode_single_band_tiles from the _backends._gpu_helpers re-import block since read_geotiff_gpu (their only caller in __init__.py) has moved out. _is_gpu_data stays because to_geotiff and write_geotiff_gpu still call it.

2. Bool band rejection missing on the GDS chunked path — pre-existing bug in _read_geotiff_gpu_chunked_gds. Tracked in geotiff: GDS chunked GPU path missing bool-band rejection and LERC masked_fill #1896 as a follow-up so this PR stays pure motion.

3. LERC masked_fill dropped on the GDS chunked path — also pre-existing, tracked in geotiff: GDS chunked GPU path missing bool-band rejection and LERC masked_fill #1896 alongside the bool-band fix.

Re-running CI on the new commit.