geotiff: extract read_vrt and VRT dask helpers to _backends/vrt.py (#1887)

[brendancol]

Summary

Step 9 of #1813's multi-PR refactor of xrspatial/geotiff/__init__.py. Pure code motion; no public API change.

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

• read_vrt — VRT read entry point (~250 lines), with the eager-path CRS/transform/holes attrs population, the per-band nodata selection (read_vrt(band=N) reports band 0's nodata in attrs and skips masking for band N #1598), and the integer-sentinel post-decode mask (read_vrt(band=None) only masks band 0's nodata sentinel on multi-band integer VRTs #1611, geotiff: refactor read_vrt chunked path to share logic with eager #1825) intact.
• _vrt_chunk_read — per-chunk delayed reader used by the dask graph.
• _read_vrt_chunked — lazy dask dispatch when chunks= is set (geotiff: read_vrt(chunks=...) materialises the full mosaic before chunking #1814), including the parse-time hole detection and the 50k-task graph cap.
• _MAX_VRT_DASK_CHUNKS constant.

The XML parsing, source-path containment, per-source decode, and _apply_integer_sentinel_mask already live in xrspatial/geotiff/_vrt.py (untouched here); this module orchestrates only the eager / dask / GPU dispatch around them.

Function bodies are unchanged except for adjusted relative imports (._X → .._X). __init__.py re-exports read_vrt so the public surface is unchanged.

Knock-on cleanup

_backends/dask.py had a lazy from .. import read_vrt added in #1897 because read_vrt was still in __init__.py. With read_vrt now in a sibling backend module, the import is promoted to a static top-of-module from .vrt import read_vrt and the dispatch site becomes a direct call.

Diff stats

• __init__.py: 2505 → 1905 (-600 lines).
• New _backends/vrt.py: 624 lines.

Test plan

• Pixel-byte-parity matrix from geotiff: add end-to-end pixel-byte-parity test matrix (#1879) #1889 — 192/192 pass (including the 2x2 VRT mosaic cell and the cross-entry-point parity for open_geotiff(.vrt) vs read_vrt).
• Runtime-sentinel identity tests from geotiff: extract sentinels, fallback warning, strict-mode helper to _runtime.py (#1880) #1890 — 9/9 pass.
• VRT-specific tests: lazy chunks (geotiff: read_vrt(chunks=...) materialises the full mosaic before chunking #1814 + read_vrt chunks mode materializes the full mosaic before chunking #1798), window validation (read_vrt: out-of-bounds window silently clamped instead of raising (drift from local/HTTP) #1697), backend coverage — all pass.
• Full geotiff suite minus the 8 pre-existing main failures — 2862/2862 green.

Closes #1887. Refs #1813.

[Copilot]

Pull request overview

This PR is part of the ongoing GeoTIFF refactor (#1813), extracting the VRT read entry point (read_vrt) and its dask chunking helpers out of xrspatial/geotiff/__init__.py into a dedicated backend module, while keeping the public API stable via re-export.

Changes:

• Added xrspatial/geotiff/_backends/vrt.py containing read_vrt, _vrt_chunk_read, _read_vrt_chunked, and _MAX_VRT_DASK_CHUNKS.
• Updated xrspatial/geotiff/_backends/dask.py to use a static import of read_vrt from the sibling backend module.
• Updated xrspatial/geotiff/__init__.py to re-export read_vrt from the new backend module and removed the inlined implementation.

Reviewed changes

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

File	Description
xrspatial/geotiff/_backends/vrt.py	New VRT backend module holding read_vrt and its eager/dask/GPU orchestration.
xrspatial/geotiff/_backends/dask.py	Switches VRT dispatch from a lazy .. import read_vrt to static from .vrt import read_vrt.
xrspatial/geotiff/__init__.py	Re-exports read_vrt from _backends/vrt.py and removes the previous in-file implementation.

Comments suppressed due to low confidence (1)

xrspatial/geotiff/_backends/vrt.py:205

• This comment says “lenient mode (the default)”, but missing_sources now defaults to 'raise' (and strict mode can force raising). Please update the wording to reflect that the lenient path is opt-in via missing_sources='warn', so the comment stays consistent with the function signature and docstring above.

    # Surface skipped-source records as ``attrs['vrt_holes']`` so
    # callers can detect a partial mosaic by attribute lookup. Under
    # lenient mode (the default), the underlying ``_vrt.read_vrt``
    # already warned per skipped source but the warning is easy to
    # miss in a pipeline; the attr lets downstream code branch on

---

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