# D-InSAR Province Coverage Pairing Design

Date: 2026-07-06

## Goal

Provide a planning mode for near-term province-wide D-InSAR delivery. The user enters a target production time range as the scene pool and selects a province/AOI. The system builds standard D-InSAR candidate pairs, then greedily selects pairs that add the most new AOI spatial coverage. The time range is a freshness/pool constraint, not the primary coverage objective.

## Scope

- Reuse `pairing_metric_cache` as the only candidate source.
- Keep the existing standard D-InSAR thresholds: temporal baseline, overlap, center distance, same mode, same polarization, same family, orbit availability.
- Add a planning endpoint that returns normal `RadarPair` rows, so existing pair list, batch save, copy, and production flow remain unchanged.
- Store the selected network through `pairing_network_runs` / `pairing_network_edges` for traceability.

## Greedy Policy

1. Build candidate windows from `master_imaging_date` to `slave_imaging_date`.
2. Start with the requested target window.
3. Query candidates in the target pool plus `extension_days`.
4. When an AOI is available, prefer candidates that add new uncovered AOI area.
5. Use target-window temporal coverage as a secondary score and diagnostic.
6. Score each candidate:
   - new AOI area covered
   - total AOI area covered by the pair
   - new target days covered
   - existing target coverage overlap
   - scene overlap ratio
   - D-InSAR quality score
   - shorter temporal baseline and smaller center distance as tie-breakers
7. Select the best edge, mark covered AOI area and days, then repeat until:
   - AOI area has no meaningful new coverage candidates
   - no candidate adds coverage
   - `max_pairs` is reached

## Coverage Semantics

Coverage here means AOI spatial coverage when an AOI is supplied. Temporal coverage is reported separately to show whether the selected pairs span the requested production window. For province-wide use, the user must select the province AOI and set an AOI overlap threshold appropriate for production planning.

## API

`POST /pairing/coverage-plan`

Form fields:

- `target_date_from`, `target_date_to`: required `YYYYMMDD`
- standard pairing fields: `time_baseline_min`, `time_baseline_max`, `overlap_threshold`, `spatial_baseline_max_meters`, `aoi_overlap_threshold`, `allowed_satellites`
- `extension_days`: default 15
- `max_pairs`: default 200
- `require_orbit_data`: default true
- `files` or `aoi_geojson`: optional AOI, same as `/find-pairs`

Response:

- `pairs`: selected `RadarPair` rows
- `coverage`: requested range, effective query range, covered days, coverage ratio, uncovered ranges
- `warnings`, `network_run_id`, `candidate_count`, `selected_edge_count`

## Notes

- This is a planning tool, not a new production engine.
- Existing batch splitting remains the operational control for producing 100-by-100 or any user-selected batch size.
- Produced pairs should still be filtered in the pair list by existing result status indicators before batch creation.