NODEDC_MISSION_CORE/docs/adr/0020-patchworkpp-vendor-map-boundary.md

ADR 0020: do not promote Patchwork++ on vendor-mapped LiDAR increments

Date: 2026-07-25 Status: accepted and implemented as a diagnostic gate

Context

The L2 roadmap selected Patchwork++ as the first non-neural ground segmentation baseline. The official implementation is designed around a sensor-centric LiDAR scan, radial zones and a physical sensor height. Current K1 lio_pcl evidence instead contains a vendor-mapped point increment in map, an independent best-effort pose and no admitted raw sweep or scan geometry. The pose describes vendor odometry; it does not prove the physical height of the LiDAR above terrain.

Static, read-only analysis of the K1 3.0.2 deployment artifacts narrows this boundary. K1 selects a Livox MID-360 adapter internally, consumes /livox/lidar plus /imu, and its point type carries XYZ, intensity, timestamp and ring. The configured external MQTT point-cloud sample factor is four, while the externally recorded lio_pcl is emitted after the LIO/modeling path. The scanner therefore measures real metric ranges and the appliance has a richer internal source; Mission Core has not yet admitted that internal source through a versioned export or bag contract.

For the handheld capture, the operator measured approximately 1.27 m from the LiDAR head to the ground. This is useful evidence, but it is neither a runtime-attested extrinsic nor proof that the vendor map Z origin coincides with terrain. It may be used only in an explicitly marked diagnostic normalization.

Treating a successful Patchwork++ call as a valid baseline would conflate API compatibility with input-domain compatibility. Choosing a synthetic Z translation until the output looks plausible would use the candidate itself to define the normalization.

Decision

1. Pin the official Patchwork++ v1.4.1 source at commit 3e6903a1d5537a4cc2ace897b0bbb98a92d6014c.
2. Run it only behind the provider-neutral lidar-ground/v1 diagnostic boundary.
3. Bind the exact source commit and compiled binary SHA-256 into every result.
4. Preserve point-aligned ground and assigned masks separately from raw replay.
5. Compare it with the current local-percentile proposal using algorithm-to-algorithm IoU, disagreement and latency.
6. Mark input-domain acceptance, labeled accuracy and production promotion false for current K1 vendor-map evidence.
7. Never present algorithm IoU as ground IoU.
8. Create an all-ignore, content-bound annotation template; only a separate human-reviewed generation may unlock ground IoU, curb/low-obstacle recall and reflection-noise rejection.
9. Bind sensor height, applied map vertical-origin offset and evidence class (missing, operator-estimated or runtime-calibrated) into the immutable benchmark identity.
10. Publish one bounded, path-free point-aligned frame endpoint and render it in React/Three.js with current, candidate and disagreement masks. Heavy processing remains in the worker.
11. Keep command, navigation and safety authority false.

Consequences

• Patchwork++ remains a useful candidate for a future raw vehicle LiDAR feed.
• Its sub-millisecond host latency on the current slice does not compensate for the unaccepted input domain.
• Current K1 work should prioritize independent labels and source evidence, not threshold tuning around a mis-specified sensor model.
• The same immutable benchmark/API/React surface can compare a future raw scan, replay or simulation provider without moving C++ processing into React.
• Firmware evidence justifies implementing an admitted onboard raw point/IMU exporter or bag reader; it does not retroactively upgrade existing MQTT recordings to raw scans.
• The 1.27 m run makes the effect of the operator estimate visible and repeatable, but remains diagnostic-only.

Architecture clarification — 2026-07-25

This ADR rejects one algorithm/input pairing. It does not reject K1 as the physical LiDAR, downgrade its real-time report stream to an offline-only source or require replacement hardware.

• lio_pcl and lio_pose were received while the handheld rig moved and are admitted as the primary real-sensor replay/shadow source.
• The pose permits points to be expressed relative to the current pivot. It does not prove the original firing pose/time of every already mapped point.
• The historical 1.27 m value is never an operational constant. It remains only in the immutable Patchwork++ diagnostic identity.
• A ground-vehicle profile estimates the local surface over time and derives sensor-to-surface height, slope and roughness from that surface. A free-flight profile uses 3D occupancy/clearance and may publish ground as unavailable.
• A future fixed rig contributes T_body_from_lidar; it does not make height above terrain constant.
• Persistent reconstruction and short-TTL perception are separate derivatives of the same immutable K1 evidence. Neither derivative rewrites the source.
• Current work is passive: no K1 firmware change, onboard exporter, internal topic invocation or new application command is authorized.
• RAVNOVES00 is retained as an immutable private experimental dataset. All prior benchmark artifacts remain valid records of the investigated approach.

Real diagnostic evidence

Benchmark ground-benchmark-68cfd7a8f1dd4c0006183bb4f63a23f9ff1dd7459317ff0886e995f6c320d984 processed 66 frames and 226,963 points:

Measurement	Current local percentile	Patchwork++
Ground fraction p50	18.31%	0.53%
Host latency p95	9.74 ms	0.26 ms

Algorithm ground IoU was 2.90% p50 and point disagreement was 17.92% p50. Neither is an accuracy metric. Independent labels are still missing.

The explicit operator-height variant ground-benchmark-87cb3150701f7e21756f46ef5b6ce110df1e07720ef6dc2303c95520932cf43f applied a 1.27 m map-Z offset and processed the same 66 frames and 226,963 points:

Measurement	Current local percentile	Patchwork++
Ground fraction p50	18.31%	2.47%
Host latency p95	11.85 ms	0.42 ms

Algorithm ground IoU was 4.07% p50 and point disagreement was 19.13% p50. This is evidence that height/origin normalization materially changes the candidate result, not evidence that either algorithm is accurate.

References

• src/k1link/compute/lidar_ground.py
• experiments/perception/run_lidar_ground_benchmark.py
• src/k1link/web/lidar_api.py
• apps/control-station/src/workspaces/LidarQualityWorkspace.tsx
• apps/control-station/src/workspaces/LidarGroundPointCloud.tsx
• docs/lab/005_K1_FW302_LIDAR_PIPELINE_20260725.redacted.md
• docs/13_LIDAR_WORKER_PRODUCT_AND_ROADMAP.md