Feat/s1 rtc stac builder

[lhoupert]

reopen #173

Summary

Adds S1 GRD RTC STAC item generation plus the ingest fixes needed to make those items render correctly in TiTiler.

STAC builder (src/eopf_geozarr/stac/s1_rtc.py)

• build_s1_rtc_stac_item(zarr_store, collection_id) -> pystac.Item
• Opens the Zarr store (works with consolidated and non-consolidated metadata); reads proj:code, spatial:bbox, r10m/time, r10m/platform from each orbit-direction group
• Converts UTM bbox → WGS84 via pyproj; ascending orbit preferred for assets and projection metadata when both orbits are present
• Applies SAR, SAT, and Projection STAC extensions
• Adds the Render extension with a dual-pol VV/VH RGB composite preview (single rescale pair) so titiler-eopf can render previews/tiles
• vv/vh asset hrefs point to the orbit-group root

CLI

• Adds generate-stac-s1 --store <path> [--collection <id>] subcommand

Ingest fixes (src/eopf_geozarr/conversion/s1_ingest.py)

• Supports s3:// URIs in S1Tiling discovery and ingest
• Writes CF grid_mapping and drops tile_matrix_set from the RTC store
• Adds proj:code to resolution-group attrs for TiTiler compatibility
• Handles masked multi-frame acquisition timestamps
• CF-encodes the time coordinate at every multiscale level so per-acquisition previews render by datetime instead of a fragile positional index (details below)
• Stores nodata as NaN, not 0, so titiler masks out-of-swath transparent (fix(s1-rtc): store nodata as NaN, not 0, so titiler masks it transparent #202, completes the _FillValue encoding from fix(s1-rtc): write CF _FillValue on float arrays (#172 parity) #201): s1tiling writes 0.0 out of swath and titiler treats 0 as valid data → opaque black. vv/vh are now masked by border_mask (0 = no-data) and float conditions (gamma_area/lia) by the GeoTIFF's declared nodata, so previews render nodata transparent like the S2 reference. np.nanmean downsampling carries the NaN to every overview level. Affects newly re-ingested cubes only.

Datetime-based per-acquisition rendering (#193, closes #192)

Per-acquisition previews render via titiler sel=time={…}. Previously time was a bare int64 array with no CF datetime metadata, present only at r10m, so titiler could only select positionally (sel=time={index}). That index silently mis-targets — or 400s — once a cube's time axis goes non-monotonic, which happens on a cross-run append of an earlier-dated scene (observed on 31TEH: [idx0=06-08, idx1=06-07], leaving the 06-07 item with no preview). Keeping positional indices correct would require reordering cube data and re-registering every item on every append — not scalable.

Instead, this CF-encodes time (units = "nanoseconds since 1970-01-01", calendar = "proleptic_gregorian", standard_name = "time") and replicates it as a coordinate at every multiscale level:

• TiTiler (v0.5.0) already does label-based da.sel(…, method=…) via open_datatree(decode_times=True); with the CF attrs, time decodes to a datetime64 index and previews can select by exact datetime — which works even on a non-monotonic axis (only nearest/slice need monotonicity). So no cube reorder, and registration can be incremental (only the new item).
• time must resolve at whatever level TiTiler renders (previews use a coarse level). Putting it only at the orbit-group level and relying on DataTree inheritance fails to open while r10m stays bare int64 (AlignmentError: int64 vs datetime64 on the shared time dim) — hence per-level encoding.
• Stored dtype stays int64 ns, so downstream raw readers (e.g. data-pipeline register_per_acquisition) are unaffected.

Implementation: new _create_time_coordinate_array + TIME_CF_ATTRS; time is created/written CF-encoded at every level in the create, append-group, and append-write paths (absolute_orbit/relative_orbit/platform stay at r10m, since they are not selected on). The companion data-pipeline change (per-acquisition render links emitting sel=time={datetime} + incremental registration) is tracked in #192.

Dependencies

• Adds pystac>=1.8.0

Test plan

• tests/test_s1_stac.py — 11 unit tests covering: item id, temporal range, WGS84 bbox, both-orbit bbox union, ascending asset preference, non-consolidated store, empty-store ValueError, asset hrefs, SAR extension fields, and the RGB render extension (incl. ascending preference)
• tests/test_s1_rtc_ingest.py — ingest coverage incl. s3:// discovery, masked multi-frame timestamps, CF grid_mapping/CRS resolution, and absence of tile_matrix_set
• tests/test_s1_rtc_ingest.py::TestTimeCFDatetime (fix(s1-rtc): CF-encode time at every level for datetime-based rendering #193) — 5 tests: CF attrs on time at every level, time decodes to datetime64 via open_datatree, exact datetime .sel on a non-monotonic axis at the native and a coarse level, identical time values across levels, and r10m/time still raw int64 for downstream readers
• tests/test_s1_rtc_ingest.py nodata→NaN (fix(s1-rtc): store nodata as NaN, not 0, so titiler masks it transparent #202) — NaN ⟺ border_mask==0 at native + overview, _FillValue masking round-trips via use_zarr_fill_value_as_mask, and declared-nodata conditions → NaN
• Full suite (excluding integration tests) passes; ruff clean on new files; mypy src/eopf_geozarr/stac/ clean

Branch sync

This branch has been merged up to date with s1-tiling (release 0.10.1), resolving version/dependency conflicts (pyproject.toml, uv.lock, CHANGELOG.md, .release-please-manifest.json). aiohttp>=3.14.0 (CVE fix from main) is included; PR now reports mergeable / clean.

🤖 Generated with Claude Code

[lhoupert]

Tracking a known follow-up surfaced by the 32TLR S1 RTC e2e (data-pipeline #226, item F1):

• S1 RTC: discover_s1tiling_acquisitions returns 0 for multi-frame products (masked acq timestamp) #183 — discover_s1tiling_acquisitions returns 0 for multi-frame products whose GeoTIFF filenames carry a masked acquisition time (…txxxxxx). Durable fix: resolve acq_stamp from the ACQUISITION_DATETIME tag when the filename stamp is masked. data-pipeline has a temporary workaround (#237) that this would retire.

Not required to land this PR — captured here so it's tracked alongside the S1 RTC builder work.

[lhoupert]

Commit bbd18e3 adds a builder fix for #188: build_s1_rtc_stac_item now falls back to a direct (non-consolidated) read when a cube store lacks root consolidated metadata — which happens on a same-orbit time-slice append and broke live S1 RTC STAC registration. Includes a regression test.

[lhoupert]

Nudge to land this: the S1 RTC datetime-rendering work (validated end-to-end, 10/10 stable renders by exact datetime) currently pins eopf-geozarr to 16c5f14 — a squash commit on this branch. We've cut only a provisional validation tag (data-pipeline v0.6.0-s1rtc) because that pin becomes orphaned / GC-eligible if this PR squash-merges. Once #180 lands we'll re-pin to the post-merge commit (or a data-model release) and cut the durable release. Tracking: data-model#192, data-pipeline#232, titiler-eopf#118.

[d-v-b]

typeddictify this

[d-v-b]

would be good to associate special values like this with types. I wonder if we need a NewType for CRS strings.

[d-v-b]

this pattern:

from typing import NewType

BoundingBox2D = NewType("BoundingBox2D", tuple[float, float, float, float])

def make_bounding_box(value: object) -> BoundingBox2D: ...

ensures that we never confuse a bounding box with some other collection of numbers