63 lines
2.8 KiB
Markdown
63 lines
2.8 KiB
Markdown
# ADR 0019: preserve LiDAR fields before detector evaluation
|
||
|
||
Date: 2026-07-25
|
||
Status: accepted and implemented
|
||
|
||
## Context
|
||
|
||
The accepted E10 LiDAR replay pack v1 is bound to the E10–E26 result line. It
|
||
stores camera-selected map XYZ and pose but drops the verified intensity byte,
|
||
raw `rgbi`, raw integer coordinates, source header fields and exact host
|
||
timestamps. Mutating that schema would invalidate historical evidence while
|
||
still leaving detector and scanner-quality assumptions implicit.
|
||
|
||
Mission Core also needs one operator surface that can distinguish capture
|
||
quality from later model quality. A successful worker process or a visually
|
||
plausible point cloud is not that evidence.
|
||
|
||
## Decision
|
||
|
||
1. Add the separate immutable `missioncore.lidar-replay-pack/v2`; never rewrite
|
||
E10 replay pack v1.
|
||
2. Bind each v2 pack to the source raw capture and aligned metadata hashes.
|
||
3. Preserve point capture sequence, payload size, exact host epoch and
|
||
monotonic receive times, header seq/stamp/scaler, raw integer XYZ, derived
|
||
map XYZ, raw uint32 `rgbi` and its verified uint8 intensity low byte.
|
||
4. Preserve pose messages independently with their source/header/timing,
|
||
position, quaternion, distance and accuracy fields.
|
||
5. Hash the canonical logical arrays, not only the compressed NPZ bytes.
|
||
6. Re-decode the immutable source and compare all persisted arrays before a
|
||
pack is accepted. Any mismatch fails the pack.
|
||
7. Publish a separate hashed scanner-quality report: cadence, density,
|
||
intensity, sequence anomalies and nearest-pose coverage.
|
||
8. Expose only path-free, read-only catalog/detail responses to React.
|
||
9. Deduplicate superseded producers by logical content identity in the UI.
|
||
10. Keep command, navigation and safety authority false.
|
||
|
||
## Consequences
|
||
|
||
- PointPillars now has retained XYZI evidence for replay, but remains degraded
|
||
because K1 supplies vendor-mapped increments rather than admitted raw sweeps.
|
||
- Scanner/transport timing tails become visible before model tuning.
|
||
- Reprocessing can compare new worker/model generations against exactly the
|
||
same point and pose evidence.
|
||
- The browser displays qualification facts but never loads raw NPZ payloads or
|
||
runs GPU perception.
|
||
- Ring, per-point time, scan geometry and IMU remain explicitly absent.
|
||
- Nvblox, LiDAR odometry and LIO/SLAM remain blocked.
|
||
|
||
## Accepted real evidence
|
||
|
||
The first accepted real pack was built from
|
||
`20260719T220917Z_viewer_live`: 66 point frames, 226,963 points, 70 pose frames,
|
||
24 exact array comparisons and zero mismatches. Pose coverage was 100% at the
|
||
100 ms host-arrival threshold. Point-frame interval was p50 80.4 ms, p95
|
||
186.6 ms and maximum 1,153.4 ms.
|
||
|
||
## References
|
||
|
||
- `src/k1link/compute/lidar_replay.py`
|
||
- `src/k1link/web/lidar_api.py`
|
||
- `apps/control-station/src/workspaces/LidarQualityWorkspace.tsx`
|
||
- `docs/13_LIDAR_WORKER_PRODUCT_AND_ROADMAP.md`
|