Describe the resample as a VRT instead of writing it out

[wrignj08]

Stacks on #11 — based on perf-memory, so retarget to main once that merges.

The problem

resample_input read every band at the new resolution and wrote them out as a GeoTIFF next to the output, so the pipeline could reopen that path and read band_order back. That's a full second copy of the scene on disk — including bands the caller never asks for — plus a second decode of the ones it does.

resample	left on disk
4-band S2 tile → 20 m	362 MB
4-band S2 tile → 5 m	5.8 GB

Nothing downstream wanted a raster. Of the four consumers of that path, three — both build_targets threads and export_to_disk — read only crs, bounds and transform, and never touch a pixel. The file existed because a path was the only way to hand the resampled scene to all of them.

The change

A VRT keeps the path and drops the copy. resample_input wraps the source in a WarpedVRT on the target grid and serialises that description to /vsimem, returning its path — 3 KB of XML saying "I am a raster of this size on this grid; fetch my pixels from that GeoTIFF".

It opens like any other raster, so build_targets, water_inf_helpers and export_to_disk are unchanged apart from widening Path to str | Path. The resampled scene only ever exists as the array the pipeline reads.

Alternatives considered: MemoryFile (same API, but holds an uncompressed duplicate of the resampled raster in RAM — ~240 MB on the 20 m case, wrong direction for this branch), and passing a lightweight georeferencing object instead of a path (no duplicate, but a new type and the same signature churn, since a WarpedVRT has no path either).

Verification

Old vs new, same source, across down- and up-sampling:

res=   20  5490x5490   pixels identical: True   crs/transform/size/bounds: all True
res=   30  3660x3660   pixels identical: True   crs/transform/size/bounds: all True
res=    5  21960x21960 pixels identical: True   crs/transform/size/bounds: all True
res=  7.5  14640x14640 pixels identical: True   crs/transform/size/bounds: all True

Resample-and-read on a 4-band 5490×5490, end to end:

old: write GeoTIFF + reopen   0.62s   artefact 361.7 MB
new: /vsimem VRT + open       0.22s   artefact 0.0 MB

The grid arithmetic is carried over unchanged, and the VRT resamples with nearest — which is what a decimated rasterio read already did, so this is not a behaviour change. (It does make Resampling.average a one-word change if the downsampling aliasing is worth fixing later — deliberately not part of this.)

197 unit tests, 36 e2e, mypy strict and ruff all pass.

Notes for review

• The pipeline's diff looks larger than it is: 141 lines, but 31 ignoring the reindent from wrapping the loop body in try/finally.
• The scene path, the output name and the bands read now come from three places rather than all from the written file's name. The _resample_<res>m suffix is rebuilt explicitly, and input_image keeps naming the real scene in the logs.
• /vsimem is process-global and nothing reclaims it, so the per-scene VRT is released in a finally. Tests cover release on both the success and TargetBuildError paths.
• The exists() cache is gone. It skipped a resample that is now free to redo, and never checked the cached file still matched its input.
• The skip-if-exists branch no longer writes a whole raster before discovering the output was already there.
• The VRT records an absolute path to its source, so it is strictly a within-run object — which is why it lives in /vsimem behind a finally rather than next to the outputs.
• Carries a merge of main for the e2e conftest fix (Let e2e tests resolve the live Overture release #12); without it the e2e suite can't run.

🤖 Generated with Claude Code