feat(perception): qualify lidar evidence before models

This commit is contained in:
DCCONSTRUCTIONS
2026-07-25 01:00:26 +03:00
parent 37c24b5fa8
commit 3f549f91f1
8 changed files with 1185 additions and 0 deletions
+7
View File
@@ -1,5 +1,12 @@
# External perception worker contract
The LiDAR-native extension is governed by
`missioncore.lidar-evidence-profile/v1` and
`docs/13_LIDAR_WORKER_PRODUCT_AND_ROADMAP.md`. A worker process starting
successfully is not evidence that its LiDAR assumptions are satisfied. In
particular, the accepted E10 replay pack v1 has no intensity, and the current K1
stream is a vendor map increment rather than an unregistered sensor sweep.
## Boundary
```text
@@ -2,6 +2,11 @@
Status date: 2026-07-20.
LiDAR-native work after E26 follows
`docs/13_LIDAR_WORKER_PRODUCT_AND_ROADMAP.md`: lossless replay and scanner
quality first, then ground segmentation and a PointPillars baseline. Alternative
odometry/SLAM is not admitted for the current vendor-mapped K1 stream.
## Outcome
Mission Core will use the K1 factory camera/LiDAR calibration instead of
+255
View File
@@ -0,0 +1,255 @@
# LiDAR worker: product value, evidence boundary and implementation roadmap
Date: 2026-07-25
Status: accepted architecture plan; L0 contract implemented
Scope: real scanner records, replay and future live shadow processing
Explicitly out of scope: Unreal U0/U1, Gaussian assets and simulator rendering
## 1. Decision
Mission Core does not treat “LiDAR processing” as one model. It owns four
separate products:
1. scanner evidence and quality;
2. geometric preprocessing and map quality;
3. object/occupancy perception;
4. planner-facing local world state.
Simulation can exercise their contracts and generate synthetic regressions, but
it cannot prove real scanner timing, returns, reflectance, calibration, motion
distortion or environmental failure modes.
The AI worker remains external, Linux/NVIDIA-capable and replaceable. React is
the control and review surface. Mission Core owns immutable inputs, exact
profiles, result identities, acceptance gates and diagnostic-only authority.
Models do not gain scanner, navigation, command or safety authority.
## 2. What the current K1 source actually contains
The firmware-3 `lio_pcl` stream currently exposes:
- finite XYZ points already expressed in the canonical `map` frame;
- one verified uint8 intensity value in the low byte of `rgbi`;
- a frame header with sequence, stamp and scaler;
- a separate `T_map_from_lidar` pose stream.
It does not currently expose an admitted:
- raw sensor-frame sweep;
- per-point firing time;
- ring/channel number;
- IMU sample stream;
- LiDAR/IMU extrinsic;
- proven common hardware clock for LiDAR and cameras;
- LiDAR scan model required by projective integrations.
The accepted `missioncore.e10-lidar-replay-pack/v1` narrows this further: it
keeps XYZ, pose and best-effort camera binding, but drops intensity. It must not
be silently mutated because E10E26 results are content-bound to that schema.
These facts have architectural consequences:
- current K1 points can support display, calibrated projection, persistent
support and bounded geometric analysis;
- the live stream can be converted back to a pose-relative sensor XYZI tensor;
- the v1 replay pack cannot feed the admitted NVIDIA PointPillars baseline;
- KISS-ICP, KISS-SLAM, FAST-LIO2, LIO-SAM or GLIM cannot honestly rebuild K1
odometry from points that are already vendor-mapped;
- deskew and LiDAR-inertial SLAM are blocked until the scanner or a future
vehicle LiDAR driver supplies raw scans, timing and IMU evidence.
The executable truth is
`missioncore.lidar-evidence-profile/v1` in
`src/k1link/compute/lidar_contract.py`. It assesses each stage as `ready`,
`degraded` or `blocked` and refuses to infer absent sensor fields.
## 3. Current system result
The existing camera-heavy E10E26 line is valuable and remains in place:
- raw recording and content-addressed worker handoff;
- camera detection and semantic segmentation;
- factory KB4 camera/LiDAR projection;
- map-frame LiDAR support and ground-aware cuboids;
- bounded temporal stabilization;
- persistent support motion evidence;
- camera ego-motion evidence and conservative fusion.
E25 proved the LiDAR limit: missing current returns cannot be recovered by
threshold tuning. E26 passed its reviewed 11/11 diagnostic windows by adding
camera parallax, but it is not planner-ready: most camera observations remain
unknown, camera-only velocity is not metric, 374 conflicts remain, and the
benchmark is not independent ground truth.
The next work must therefore improve the LiDAR-native input and evaluation
surface, not add another visual smoothing pass.
## 4. Market and stack assessment
### 4.1 NVIDIA components worth retaining
| Component | Correct use in Mission Core | Decision |
| --- | --- | --- |
| [TAO PointPillars](https://docs.nvidia.com/tao/tao-toolkit/latest/text/cv_finetuning/pytorch/point_cloud/pointpillars.html) | Train/evaluate a LiDAR-native 3D detector over sensor-frame XYZI | First neural 3D baseline after replay v2 and labels |
| [DeepStream LiDAR 3D inference](https://docs.nvidia.com/metropolis/deepstream/7.1/text/DS_3D_Lidar_Inference.html) | Reference production pipeline for XYZI → Triton/TensorRT → 3D boxes | Reuse the inference pattern, not its file loader or UI |
| [TAO Deploy PointPillars](https://docs.nvidia.com/tao/tao-toolkit/latest/text/tao_deploy/pointpillars.html) | Build a pinned FP16/FP32 TensorRT engine and evaluate it | Worker optimization only after an accuracy baseline |
| [Isaac ROS nvblox](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_nvblox/isaac_ros_nvblox/index.html) | GPU local TSDF/occupancy/ESDF and Nav2 cost-map producer | Later; blocked on admitted scan geometry and better timing |
| DeepStream multimodal 3D fusion | Later camera/LiDAR BEV baseline | Deferred until LiDAR-only, sync and calibration gates pass |
NVIDIA does not provide a magic “clean the K1 map” stage. PointPillars produces
classified 3D objects. Nvblox produces reconstruction and distance fields. The
quality of both remains bounded by source timing, calibration, scan geometry
and training-domain fit.
### 4.2 Independent components worth benchmarking
| Component | Correct use | Decision |
| --- | --- | --- |
| [Patchwork++](https://github.com/url-kaist/patchwork-plusplus) | Fast adaptive ground segmentation, including reflection-noise handling | First non-neural geometry baseline |
| [Autoware CenterPoint](https://github.com/autowarefoundation/autoware_universe/tree/main/perception/autoware_lidar_centerpoint) | Mature ROS 2/TensorRT 3D detection and multi-frame reference | Second detector baseline after PointPillars |
| [MMDetection3D](https://github.com/open-mmlab/mmdetection3d) | Training/evaluation harness and dataset adapters | Laboratory only |
| [OpenPCDet](https://github.com/open-mmlab/OpenPCDet) | Alternative LiDAR detector benchmark/model zoo | Laboratory only; not the production runtime |
| [KISS-ICP](https://github.com/PRBonn/kiss-icp) | Simple LiDAR-only odometry baseline | Future raw sensor scans only |
| [KISS-SLAM](https://github.com/PRBonn/kiss-slam) | Global LiDAR SLAM/loop-closure baseline | Future raw sensor scans only |
| [FAST-LIO2](https://github.com/hku-mars/FAST_LIO) | Raw LiDAR + IMU odometry/mapping | Future vehicle sensor profile only |
| [LIO-SAM](https://github.com/TixiaoShan/LIO-SAM) | Deskewed LiDAR-inertial factor-graph reference | Future profile with ring/time/IMU only |
| [GLIM](https://github.com/koide3/glim) | GPU-accelerated range-inertial mapping, loop correction and map cleanup | Strong future mapping candidate; blocked for current K1 evidence |
Autoware is a useful architecture and component reference; importing the whole
autonomous-driving distribution into the worker would add a large operational
surface that Mission Core does not currently need.
## 5. Target worker shape
The worker exposes provider-neutral jobs rather than one growing camera script:
| Job profile | Input | Output | Authority |
| --- | --- | --- | --- |
| `lidar-quality/v1` | immutable LiDAR evidence | field/timing/density/intensity report | diagnostic |
| `lidar-ground/v1` | sensor-frame XYZI + pose | ground/non-ground points and metrics | diagnostic |
| `lidar-3d-detection/v1` | sensor-frame XYZI | classified 3D observations + uncertainty | shadow |
| `lidar-local-map/v1` | scans + synchronized pose | occupancy/TSDF/ESDF artifacts | shadow |
| `lidar-mapping-benchmark/v1` | raw scans + optional IMU | trajectory/map comparison | offline diagnostic |
Every result is content-addressed and binds:
- source evidence identity;
- exact evidence profile/readiness document;
- model, weights, runtime and preprocessing identities;
- coordinate transforms and timestamp basis;
- resource/queue/drop telemetry;
- acceptance policy and explicit authority.
Offline replay may batch work for throughput. Live shadow uses bounded
latest-wins queues. Accuracy is frozen before FP16/INT8, CUDA graph, pinned
memory, zero-copy or batching optimizations are accepted.
## 6. Implementation sequence
### L0 — evidence truth and detector adapter — complete
- [x] Add `missioncore.lidar-evidence-profile/v1`.
- [x] Encode current live K1 and replay-pack-v1 facts.
- [x] Produce deterministic stage readiness and blockers.
- [x] Add tested `map + T_map_from_lidar + intensity → sensor XYZI`.
- [x] Add bounded live point-count, cadence and intensity telemetry to the
existing external worker report.
- [x] Keep authority diagnostic-only.
### L1 — lossless replay v2 and scanner quality
- [ ] Create a new replay schema; do not rewrite pack v1.
- [ ] Preserve XYZ, intensity, source sequence/header stamp/scaler and exact
host capture/receive times.
- [ ] Record explicitly absent ring, per-point time and IMU fields.
- [ ] Add bounded reports for frame gaps, arrival jitter, points/frame, range
distribution, intensity distribution and pose coverage.
- [ ] Compare live-vs-replay decoding byte-for-byte on a frozen slice.
- [ ] Publish the report to the React observation view without bundling a
desktop renderer.
Exit: a recording cannot be called detector-ready when required fields were
dropped, and an operator can distinguish scanner dropout from model failure.
### L2 — geometric baseline
- [ ] Run Patchwork++ over the frozen XYZI slice.
- [ ] Retain ground and non-ground outputs separately; never delete raw points.
- [ ] Label a small independent ground/obstacle evaluation set in CVAT or an
equivalent accepted annotation workspace.
- [ ] Measure ground IoU, curb/low-obstacle recall, reflection-noise rejection
and CPU/GPU latency.
- [ ] Compare against the current heuristic ground proposal branch.
Exit: an evidence-backed decision to retain or reject Patchwork++.
### L3 — LiDAR-native 3D detection
- [ ] Freeze independent 3D annotations covering people, vehicles, cyclists,
stroller groups, vegetation and confusing static structures.
- [ ] Run NVIDIA PointPillars through the existing external worker/Triton seam.
- [ ] Treat pretrained output as a baseline, not an accepted product model.
- [ ] Measure class precision/recall, center/range/yaw error, distance-bucket
recall, false occupied objects and end-to-end latency.
- [ ] Compare Autoware CenterPoint only after the PointPillars harness is stable.
- [ ] Fine-tune only if the baseline demonstrates useful transfer and the
annotation budget is justified.
Exit: the selected detector beats the camera-derived cuboid baseline on the
independent gate without increasing unsafe false-free or false-dynamic output.
### L4 — live shadow integration
- [ ] Add a bounded LiDAR queue independent of camera cadence.
- [ ] Run the accepted detector profile on the NVIDIA worker.
- [ ] Fuse LiDAR-native objects with E26 camera evidence as independent sources.
- [ ] Publish `agree`, `single-source`, `conflict` and `unknown`; unknown remains
occupied.
- [ ] Measure sensor-to-result latency, deadline misses, drops, memory and GPU
headroom on a physical run.
Exit: repeatable shadow telemetry only. Navigation and safety acceptance remain
false.
### L5 — local occupancy and Nav2
- [ ] Obtain and validate the K1/future vehicle LiDAR scan model, or use a
different admitted source that supplies it.
- [ ] Prove pose and time behavior required by nvblox.
- [ ] Benchmark static occupancy/TSDF and ESDF output on real replay.
- [ ] Keep dynamic observations in a separate decaying layer.
- [ ] Connect the accepted 2D slice to Nav2 through the existing world-state
boundary.
Exit: local collision-space quality and deadline gates pass in replay and
shadow. This still does not authorize control.
### L6 — alternative odometry/mapping
This stage starts only when a source supplies unregistered sensor scans. Add
per-point time and IMU/extrinsic requirements before FAST-LIO2, LIO-SAM or GLIM.
Benchmark KISS-ICP first, then a global SLAM candidate using ATE/RPE, loop
closure residual, wall/surface thickness, map entropy, repeat-pass alignment
and compute cost.
The current K1 `lio_pcl` stream cannot satisfy this gate.
## 7. Product value
The near-term value is not a prettier point cloud:
- a trustworthy observation tells the operator whether the scanner, transport,
pose, calibration or model failed;
- lossless replay makes model and worker upgrades repeatable;
- LiDAR-native objects reduce dependence on camera visibility and provide
metric geometry;
- ground/non-ground and local occupancy become the bridge from archive review
to route validation and later collision checking;
- the same job/result contracts accept real, replayed or simulated sources
without moving heavy compute into React;
- hardware selection becomes evidence-driven: a future vehicle LiDAR is
accepted by its timing/fields/profile, not by vendor marketing.
The highest-value immediate work is L1, followed by L2 and L3. Nvblox and
alternative SLAM are useful, but starting them before their input gates would
produce attractive demos with unqualified geometry.
@@ -0,0 +1,55 @@
# ADR 0018: qualify LiDAR evidence before selecting accelerated models
Date: 2026-07-25
Status: accepted
## Context
Mission Core preserves K1 point clouds, poses, cameras and factory calibration
and already runs an external NVIDIA worker for camera perception. The next
candidate components include PointPillars, CenterPoint, Patchwork++, nvblox and
several LiDAR SLAM systems.
Those components do not share the same input assumptions. The current K1
`lio_pcl` source is a vendor-mapped increment in the canonical `map` frame with intensity and a
separate best-effort pose. It is not an unregistered sweep and exposes no
admitted ring, per-point time or IMU stream. The accepted E10 replay pack also
drops intensity.
Installing a component without expressing those facts would let runtime success
be mistaken for geometric validity.
## Decision
1. Mission Core owns a versioned, provider-neutral
`missioncore.lidar-evidence-profile/v1`.
2. Each processing stage receives a deterministic readiness result with
explicit blockers.
3. Existing content-addressed replay schemas are immutable. A lossless replay
improvement is a new version.
4. The first detector seam consumes sensor-frame XYZI. Map-frame K1 points are
converted only with the bound `T_map_from_lidar` pose, and verified uint8
intensity is normalized to `[0, 1]`.
5. Missing ring, point time, scan geometry or IMU evidence remains missing. It
is never synthesized to satisfy a model.
6. Accelerated models remain external worker providers. React consumes reports,
overlays and world-state products; it does not host CUDA/TensorRT/ROS 2
compute.
7. All LiDAR results remain diagnostic/shadow until separate navigation and
safety gates pass.
## Consequences
- PointPillars integration is blocked for replay pack v1 and degraded for the
current live vendor-mapped source.
- Nvblox is blocked until the LiDAR scan geometry and timing/pose contract are
admitted.
- LiDAR odometry and LiDAR-inertial SLAM are blocked for current K1 evidence.
- L1 lossless replay and scanner-quality telemetry precede new model installs.
- Future scanners, simulation providers and datasets can use the same
readiness contract without being forced into K1-specific code.
## References
The detailed product rationale, market review, gates and sequence are in
`docs/13_LIDAR_WORKER_PRODUCT_AND_ROADMAP.md`.