Add OBN Continuous Receiver Gathers (CRG) template

[andgineer]

Draft — opening early to start the discussion on the two API questions at the bottom. Code and tests are complete and green locally; happy to reshape the public surface before this is reviewed properly.

What this adds

A template for OBN continuous receiver gathers (CRG). Unlike shot-organised OBN data, CRG receivers record continuously, so there is no shot index to grid on. The natural key is (component, receiver_line, receiver), and each receiver holds a long run of time segments sharing that key.

Rather than introduce a new grid-override mechanism, this extends the existing HasDuplicates path, which already solves exactly this problem — it appends a per-tuple counter as a synthetic trace dimension. Two knobs were missing for the CRG scale, so those come first and the template builds on them.

Resulting layout: (component, receiver_line, receiver, trace, time).

Chunk size and dtype for the inserted trace dimension

The inserted trace dimension was hardcoded to chunk size 1 and an int16 counter. That caps a gather at 32,767 duplicates — past which the counter raises OverflowError — and forces one chunk per trace. A full CRG campaign runs to roughly 2.6e5 segments per receiver, and chunk-per-trace gives unusably small objects.

• GridOverrides.chunksize now applies to has_duplicates as well as non_binned.
• New optional GridOverrides.trace_dtype sets the dtype of the inserted dimension — both the counter and the coordinate it is stored as. It is typed ScalarType and restricted to integer types, so a dtype that cannot count traces is rejected at construction instead of failing deep inside numpy. It reaches the non_binned path too, since that inserts the same axis and has the same ceiling.

Omitting both reproduces today's behaviour exactly: chunk 1, an int16 counter stored as an int32 coordinate. That pair of legacy defaults is named (LEGACY_COUNTER_DTYPE, LEGACY_TRACE_DTYPE) and pinned by explicit backwards-compatibility tests.

This part also generalizes _resolve_synthesize_dims to read a template's synthesize_missing_dims attribute instead of isinstance-checking Seismic3DObnReceiverGathersTemplate. The OBN template already sets that attribute, so its behaviour is unchanged; this just lets other templates opt in. ingestion/segy/validation.py keys its optional-dimension exemption off the same attribute so the two cannot drift, and the attribute is now declared on AbstractDatasetTemplate itself rather than assigned in __init__, so consumers can read the hook off any template without a getattr fallback.

The template

ObnContinuousReceiverGathers3D, registered as a built-in. Grids on the three spatial dimensions and leaves the segment axis to HasDuplicates. component is declared in synthesize_missing_dims, so single-component files carrying no component header ingest against the same template with the dimension synthesized — one template covers both layouts.

Tests

tests/unit tests/integration -m "not cloud" → 569 passed.

• Template contract, coordinate-spec sync, registry inventory.
• Grid-override plumbing: the inserted trace honours chunksize and trace_dtype in both the header counter and the stored coordinate, plus BC tests asserting the default path still yields chunk 1, an int16 counter and an int32 coordinate.
• A non-integer trace_dtype is rejected at construction, and a gather that outgrows the counter raises OverflowError rather than wrapping to a wrong index.
• Two integration tests ingesting mock CRG SEG-Y: one multi-component, asserting the uint32 segment axis and the realized chunk shape, and one exercising the synthesized-component path.

Questions for maintainers

1. Is the API shape right for the new knobs? I put trace_dtype on GridOverrides alongside the existing chunksize, since that is where non_binned already carries its chunk size and it keeps the two paths symmetric. It governs the counter and the stored coordinate together, on both paths that insert a trace axis. The alternative is to carry it on the template instead, which would keep GridOverrides narrower but split the configuration for one dimension across two objects. Happy to move it.

2. Is "extend HasDuplicates" the direction you want? The alternative is a dedicated override (something like CalculateTimeSegmentIndex) that does not touch the existing path at all. Extending seemed better because the semantics are genuinely identical — a counter disambiguating repeated index tuples — and a separate override would duplicate the machinery. But it does widen a shipping public surface, so say the word if you would rather have this isolated.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.21%. Comparing base (c3ba558) to head (5ac13c0).
⚠️ Report is 247 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #850      +/-   ##
==========================================
+ Coverage   85.30%   93.21%   +7.90%     
==========================================
  Files          46      148     +102     
  Lines        2219     8588    +6369     
  Branches      306      474     +168     
==========================================
+ Hits         1893     8005    +6112     
- Misses        281      509     +228     
- Partials       45       74      +29     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[andgineer]

abandon in favor of better Brian's PR #851