geotiff: extract GPU helpers to _backends/_gpu_helpers.py (#1884)

[brendancol]

Summary

Step 6 of #1813's multi-PR refactor of xrspatial/geotiff/__init__.py. Pure code motion; no public API change. First PR to create the _backends/ subpackage.

Created xrspatial/geotiff/_backends/__init__.py (empty placeholder) and moved into _backends/_gpu_helpers.py:

• _is_gpu_data — cupy-backed array / DataArray detection.
• _apply_nodata_mask_gpu — cupy mirror of the CPU sentinel→NaN mask, with the same out-of-range / fractional / non-finite skips as _resolve_masked_fill in _reader.py.
• _gpu_decode_single_band_tiles — two-stage GPU decode (GDS, then CPU-extracted bytes) for the PlanarConfiguration=2 path.
• _apply_orientation_gpu — cupy mirror of the CPU orientation flip for all eight TIFF Orientation values.
• _apply_orientation_geo_info — GeoTransform update after an orientation flip, with the geotiff: orientation 5-8 on georeferenced TIFFs returns wrong coords behind a warning #1765 refusal for georeferenced orientations 5–8.
• _gpu_apply_window_band — post-decode window + band slice on device.

Every helper lazy-imports cupy at call time so the module imports cleanly on numpy-only environments. __init__.py re-imports the six helpers from _backends._gpu_helpers so existing callers (read_geotiff_gpu, to_geotiff's GPU branch, write_geotiff_gpu) keep identical signatures.

The leading-underscore module name (_gpu_helpers.py) is intentional: it keeps _backends/gpu.py free for the read_geotiff_gpu entry-point body in step 7.

Diff stats

• __init__.py: 4271 → 3969 (-302 lines).
• New _backends/__init__.py: 8 lines.
• New _backends/_gpu_helpers.py: 335 lines.

Test plan

• Pixel-byte-parity matrix from geotiff: add end-to-end pixel-byte-parity test matrix (#1879) #1889 — 192/192 pass (all GPU cells exercise the moved helpers).
• 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), overview-nodata inheritance (geotiff: overview reads silently drop attrs['nodata'] from level 0; pixel sentinel survives #1739) — all pass.
• 230/230 of the regression-backstop tests green.
• from xrspatial.geotiff import _is_gpu_data, _apply_nodata_mask_gpu, _gpu_decode_single_band_tiles, _apply_orientation_gpu, _apply_orientation_geo_info, _gpu_apply_window_band — every re-export resolves.
• Module imports on a numpy-only environment (cupy is lazy-imported inside each function).

Closes #1884. Refs #1813.

[Copilot]

Pull request overview

Refactors the GeoTIFF GPU backend internals by extracting six GPU-only helper functions out of xrspatial/geotiff/__init__.py into a new private _backends/ subpackage, keeping the public API and existing import paths stable via re-exports.

Changes:

• Added xrspatial/geotiff/_backends/_gpu_helpers.py containing the GPU helper implementations (lazy CuPy imports preserved).
• Added _backends/__init__.py to establish the new internal subpackage.
• Updated xrspatial/geotiff/__init__.py to import/re-export the helpers from the new module and removed the inlined implementations.

Reviewed changes

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

File	Description
xrspatial/geotiff/_backends/_gpu_helpers.py	New internal module hosting the extracted GPU helper implementations with lazy CuPy imports.
xrspatial/geotiff/_backends/__init__.py	Introduces the internal _backends subpackage (docstring-only placeholder).
xrspatial/geotiff/__init__.py	Re-exports the moved GPU helpers and deletes the previous in-file definitions.

---

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