docs(perception): define traversability evaluation sequence

2026-08-26 16:56:15 +03:00
parent 7fa2bfe52d
commit 1b6131904a
5 changed files with 452 additions and 0 deletions
@@ -189,6 +189,13 @@ sealed Current/Patchwork++ comparison rejected Patchwork++ for navigation:
 despite much lower latency and a small Ground-IoU gain, obstacle non-ground
 recall regressed from `80.46%` to `69.70%`.
 Operator review of the later M4.8R3 LOW-STEP replay rejected its connected-
 component camera boxes as the product representation for general static
 obstacles. The replacement evaluation is terrain-relative and sequential:
 GSeg3D plus Nav2 Ground Consistency first, TRAVEL as the class-free challenger,
 and nvblox only as a separately measured occupancy/ESDF candidate. See the
 [traversability and static-obstacle stack decision](docs/23_TRAVERSABILITY_AND_STATIC_OBSTACLE_STACK_DECISION.md).
 See [the Dataset Gateway plan](docs/14_LIDAR_DATASET_GATEWAY.md),
 [the laboratory run canon](docs/15_LABORATORY_RUN_CANON.md) and
 [ADR 0021](docs/adr/0021-dataset-gateway-representation-boundary.md).
@@ -0,0 +1,67 @@
 {
  "schema_version": "missioncore.traversability-candidate-manifest/v1",
  "decision_document": "docs/23_TRAVERSABILITY_AND_STATIC_OBSTACLE_STACK_DECISION.md",
  "frozen_utc": "2026-08-26T13:53:55Z",
  "source_contract": {
    "source_id": "RAVNOVES00",
    "expected_timeline_frames": 4489,
    "input_representation": "registered-vendor-map-increment-plus-causal-local-support/v1",
    "future_frames_allowed": false,
    "missing_support_means_free": false
  },
  "candidates": [
    {
      "sequence": 1,
      "candidate_id": "gseg3d-ground-consistency",
      "role": "primary",
      "components": [
        {
          "repository": "https://github.com/dfki-ric/ground_segmentation_ros2.git",
          "revision": "5c5ba6f5ca0d682db2d59b2ad2f6a317ee938b95",
          "observed_ref": "refs/heads/master",
          "license": "BSD-3-Clause"
        },
        {
          "repository": "https://github.com/dfki-ric/nav2_ground_consistency_costmap_plugin.git",
          "revision": "41cec620efba6c370dccfc59a6ec1134775ff48a",
          "observed_ref": "refs/heads/main",
          "license": "BSD-3-Clause"
        }
      ]
    },
    {
      "sequence": 2,
      "candidate_id": "travel",
      "role": "class-free-challenger",
      "components": [
        {
          "repository": "https://github.com/url-kaist/TRAVEL.git",
          "revision": "95dc2fbd66a343efd9060c45a5711b6307a950a4",
          "observed_ref": "refs/heads/main",
          "license": "GPL-3.0"
        }
      ]
    },
    {
      "sequence": 3,
      "candidate_id": "isaac-ros-nvblox",
      "role": "separate-gpu-occupancy-esdf-probe",
      "components": [
        {
          "repository": "https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_nvblox.git",
          "revision": "ef47346399c71a4342c03bdbec2136ec735da4b8",
          "observed_ref": "refs/tags/v4.6-0",
          "license": "Apache-2.0"
        }
      ]
    }
  ],
  "execution_policy": {
    "heavy_candidates_run_sequentially": true,
    "allow_parallel_gauss_compute": false,
    "allow_source_mutation": false,
    "allow_navigation_or_actuation": false,
    "allow_camera_resize_or_rectification": false,
    "allow_new_semantic_model": false
  }
 }
@@ -1539,6 +1539,11 @@ production navigation cutover. The result remains replay-simulated;
 physical-live authority, commands, actuation, planner-authoritative free space
 and collision-safety acceptance are false. The next milestone boundary is
 M4.9 recorded-realtime release-candidate validation using this frozen graph.
 Subsequent operator visual review rejected the LOW-STEP connected-component
 camera boxes as a general static-obstacle product path. That decision does not
 alter the immutable M4.8R3 runtime evidence; it redirects the next perception
 evaluation to the terrain-relative sequence in
 [`docs/23_TRAVERSABILITY_AND_STATIC_OBSTACLE_STACK_DECISION.md`](23_TRAVERSABILITY_AND_STATIC_OBSTACLE_STACK_DECISION.md).
 ## Implementation order
@@ -0,0 +1,278 @@
 # Traversability and class-free static-obstacle stack decision
 Date: 2026-08-26
 Status: accepted for sequential recorded-replay evaluation; not accepted for
 navigation or actuation
 ## Decision summary
 Mission Core stops treating the M4.8R3 `LOW-STEP` connected-component and
 camera-box projection as the product path for general static-obstacle
 perception. M4.8R3 remains immutable evidence that a bounded occupied-only
 heuristic can execute in the realtime envelope. Operator review of the complete
 visual result rejected its obstacle quality and representation:
 - isolated vegetation, curb edges and sparse returns become false obstacles;
 - bins, carts, thin posts, railings and hemispheres are inconsistently lost;
 - spatially unrelated points merge into large rectangular camera regions;
 - one-frame components flicker without ground/obstacle evidence competition;
 - 2D rectangles erase the free passage between separate 3D obstacles.
 This is an abstraction failure, not a threshold-tuning failure. A navigation
 system requires a terrain-relative occupancy and traversability product, not a
 detector that attempts to name every static object and not a bounding box as
 the safety primitive.
 The sequential evaluation order is:
 1. **GSeg3D + Nav2 Ground Consistency + Nav2 Costmap** — primary candidate.
 2. **TRAVEL + the same costmap boundary** — class-free challenger if the
   primary candidate misses compact or thin obstacles or merges passages.
 3. **Isaac ROS nvblox** — separate GPU occupancy/ESDF candidate after the CPU
   terrain contour is measured; it is not stacked into the first test.
 RF-DETR remains the semantic risk provider for people, children, animals,
 cars, trucks, motorcycles and bicycles. It does not decide the presence or
 shape of an unknown static obstacle. Native `800x600` fisheye input remains
 unchanged.
 ## Required product representation
 ```text
 LiDAR + pose + optional IMU
        |
        v
 terrain-relative ground / non-ground evidence
        |
        v
 temporally stable local occupancy and UNKNOWN support state
        |
        v
 robot-footprint collision cost + traversability
        |
        +----> planner / collision monitor (future authority gate)
        |
        +----> camera projection (diagnostic visualization only)
 camera RF-DETR ----> dynamic semantic risk hints ----------------+
 ```
 The canonical safety output is a costmap/elevation/occupancy product. Camera
 boxes may be derived for operator review, but a box must never be the source of
 occupied cells, clearance, passage width or a control action.
 ## Candidate A — GSeg3D and Ground Consistency
 ### GSeg3D
 [DFKI GSeg3D ROS 2](https://github.com/dfki-ric/ground_segmentation_ros2)
 is a BSD-3-Clause ROS 2 component for CPU realtime processing of 3D LiDAR. It
 publishes separate ground and obstacle point clouds and provides:
 - optional IMU gravity alignment;
 - two-phase coarse/fine ground segmentation;
 - configurable slope, local height and inlier thresholds;
 - ROS 2 Humble and Jazzy support;
 - no task-specific dataset or neural-network inference.
 Mission Core evaluates it as the first replacement for the current local
 height connected-component heuristic.
 ### Nav2 Ground Consistency
 [DFKI Ground Consistency](https://github.com/dfki-ric/nav2_ground_consistency_costmap_plugin)
 is a BSD-3-Clause Nav2 costmap layer and is included in the current
 [Nav2 outdoor 3D-LiDAR tutorial](https://ros-navigation.github.io/mkdocs.nav2.org/rolling/tutorials/general_tutorials/navigation2_with_ground_consistency_layer/navigation2_with_ground_consistency_layer/).
 It consumes ground and non-ground point clouds and supplies the missing product
 semantics:
 - ground and obstacle evidence compete per costmap cell;
 - evidence accumulates and decays instead of trusting one point in one frame;
 - obstacle height is evaluated relative to local ground;
 - robot height and minimum clearance are explicit configuration inputs;
 - sparse cells can use bounded neighboring-ground interpolation;
 - a cell without reliable support can fail closed instead of becoming free.
 The first test keeps all free-space and actuation authority false. The layer is
 evaluated only as a recorded-replay occupancy provider.
 ### Nav2 boundary
 [Nav2 Costmap 2D](https://docs.nav2.org/configuration/packages/configuring-costmaps.html)
 provides footprint-aware obstacle, voxel and inflation layers. A later physical
 gate may add the independent
 [Nav2 Collision Monitor](https://docs.nav2.org/rolling/configuration_and_development/configuration_guide/core_servers/collision_monitor/configuring_collision_monitor_node/),
 but recorded replay does not publish commands.
 ## Candidate B — TRAVEL
 [TRAVEL](https://github.com/url-kaist/TRAVEL) performs class-free traversable
 ground detection and above-ground instance clustering. Its ROS 2 wrapper is
 verified by the project on Humble and Jazzy. The published evaluation reports
 roughly `20-30 Hz` and explicitly targets safe navigation in unseen urban and
 wild environments without assigning names such as pole, vehicle or wall.
 TRAVEL is valuable when individual compact obstacles and the gaps between them
 must remain spatially distinct. Its GPL-3.0 license prevents silent admission
 into a proprietary product runtime. It is initially a benchmark/challenger;
 distribution consequences require a separate decision.
 Primary reference:
 [TRAVEL paper](https://arxiv.org/abs/2206.03190).
 ## Candidate C — Isaac ROS nvblox
 [Isaac ROS nvblox](https://nvidia-isaac-ros.github.io/repositories_and_packages/isaac_ros_nvblox/index.html)
 uses GPU-accelerated TSDF/ESDF reconstruction from depth and/or 3D LiDAR and
 publishes a Nav2 costmap. Current NVIDIA documentation supports ROS 2 Jazzy on
 x86_64 with an Ampere-or-newer NVIDIA GPU and at least 8 GiB VRAM; Worker 006's
 RTX 4090 is inside that hardware class.
 Nvblox is evaluated separately because it answers dense occupied-space and
 clearance questions well, but it is not by itself a complete terrain-relative
 traversability classifier. Its official kernel timings are not an end-to-end
 Mission Core FPS guarantee.
 ## Candidates not admitted to the first sequence
 | Candidate | Reason not first |
 | --- | --- |
 | Autoware Universe | Mature road-vehicle perception and occupancy, but a large automotive/lane-driving stack for this rover-sized contour. |
 | Offroad-Nav 2026 | Relevant complete pipeline, but currently ROS 1 Noetic; ROS 2 port is in development and the real-robot branch is not published. |
 | `elevation_mapping_cupy` | Strong GPU elevation-map implementation, but the maintained integration remains ROS 1/catkin. It is retained as an algorithmic reference. |
 | CMU AEDE/FAR/TARE | Proven research navigation components, but not the shortest supported ROS 2 product baseline for this test. |
 | Additional image segmentation model | Consumes GPU and still cannot establish metric support, clearance or unknown space. |
 ## Source representation boundary
 `RAVNOVES00` does not contain a conventional complete raw LiDAR scan per video
 frame. Its `lio_pcl` stream is a registered vendor-map increment in the SLAM
 map frame. Missing republication is not free-space evidence.
 Therefore every candidate run must preserve three distinct products:
 1. exact current registered increment;
 2. bounded causal rolling support/occupancy in the map frame;
 3. candidate ground/non-ground/costmap output with source lineage.
 For Candidate A, the evaluation adapter may present a bounded causal local
 cloud in the current body frame. It may not use future frames, clear cells from
 missing points, or relabel unobserved space as free. Dynamic-object semantics
 remain outside this static replay adapter.
 ## Operator-reviewed regression set
 The following RAVNOVES00 source frames are mandatory review anchors. They are
 operator-reviewed engineering cases, not independent statistical ground truth.
 | Frame | Required observation |
 | ---: | --- |
 | 171 | The grass/curb region must not become a large blocking object; the visible bin must remain obstacle evidence when supported by LiDAR. |
 | 306 | The cart and right hemisphere must not be lost while curb corners become dominant. |
 | 368 | The hemisphere extent must stay compact; the right railing must remain obstacle evidence. |
 | 402 | The near hemisphere must not inflate into a camera-sized rectangular exclusion zone. |
 | 450 | Curb/ramp terrain must be evaluated relative to local ground instead of becoming arbitrary boxes. |
 | 509 | Isolated vegetation or sparse returns must not immediately become a stable blocking object. |
 | 525 | Sparse local returns must not merge into one large occupied camera rectangle. |
 | 744 | The grass/curb strip must not be promoted into a wall. |
 | 1122 | The compact hemisphere and both thin posts must be represented when LiDAR support is present. |
 | 1856 | Two posts remain separate, two hemispheres remain separate, and the passages between them remain explicit. |
 ## Acceptance contract
 ### Quality
 - Static obstacle output is class-free and geometry-backed.
 - All supported critical anchors above are occupied or conservatively unknown,
  never false-free.
 - Vegetation, curb edges and isolated returns do not create large persistent
  lethal regions without sustained non-ground evidence.
 - Separate posts and hemispheres remain separate at the costmap resolution.
 - A camera rectangle cannot merge two distinct occupied regions or erase their
  gap.
 - Unobserved support, drop-offs and no-return regions remain `UNKNOWN/LETHAL`
  until positive support is observed.
 - No manual object-class annotation or detector training is permitted for this
  gate.
 ### Realtime and resource envelope
 - Process all `4,489` timeline frames with zero unaccounted loss.
 - Isolated candidate output keeps up with at least the recorded `10 Hz` source
  cadence.
 - Integrated graph FPS regression is at most `5%` relative to the immutable
  M4.8R3 `11.79902 FPS` reference.
 - Candidate-stage p95 latency is at most `25 ms` and p99 at most `50 ms` in the
  recorded replay contour.
 - The primary CPU candidate does not add another neural model or consume the
  RF-DETR GPU budget.
 - CPU, RAM, GPU, VRAM, queue depth, supersession and output age are recorded;
  no result is accepted only because it looks good in selected frames.
 ### Authority
 Passing this document's tests accepts a recorded-replay perception provider.
 It does not accept physical free space, navigation, commands, actuation,
 collision safety or a robot body model.
 ## Sequential execution plan
 ### T0 — Worker and source preflight
 - Inventory Worker 006 OS/WSL, ROS 2, Docker, compiler, CPU/RAM and RTX 4090.
 - Confirm the immutable RAVNOVES00 source and accepted M4.8R3 result locally on
  the worker without copying private source evidence back to the Mac.
 - Record a content-addressed candidate manifest and exact upstream revisions.
 The first T0 snapshot is recorded in
 [`experiments/perception/M49_T0_TRAVERSABILITY_PREFLIGHT_2026-08-26.md`](../experiments/perception/M49_T0_TRAVERSABILITY_PREFLIGHT_2026-08-26.md).
 Exact upstream revisions are frozen in
 [`config/perception/m49-traversability-candidate-manifest-v1.json`](../config/perception/m49-traversability-candidate-manifest-v1.json).
 T0 found the source and the accepted raw M4.8R3 run intact, but did not start a
 build: the parallel GAUSS contour was active and free Worker memory had fallen
 to approximately `669 MiB`. That is a resource-admission stop, not a candidate
 failure.
 ### T1 — Candidate A isolated qualification
 - Build GSeg3D and Ground Consistency in a new isolated `ndc-` worker contour.
 - Run upstream sample/demo data first to prove the unmodified components.
 - Measure component latency and memory before adding Mission Core adapters.
 ### T2 — Candidate A RAVNOVES00 replay
 - Feed the bounded causal local cloud with exact pose lineage.
 - Produce ground, non-ground, occupancy and unknown layers for all frames.
 - Review the ten mandatory anchors and compute full-run stability/resource
  metrics.
 - Do not draw system camera boxes until the costmap result is sealed.
 ### T3 — Candidate B challenger
 - Run TRAVEL against the identical source representation and anchors.
 - Compare compact-obstacle recall, passage preservation, temporal stability and
  CPU cost against Candidate A.
 - Stop if Candidate A already passes and TRAVEL adds no measurable value that
  justifies GPL runtime implications.
 ### T4 — Candidate C occupancy/ESDF probe
 - Run nvblox separately with RF-DETR disabled for the isolated probe.
 - Measure GPU/VRAM and 3D occupied-space quality.
 - Admit it only if it supplies a measured capability missing from the accepted
  CPU terrain contour inside the one-RTX-4090 production ceiling.
 ### T5 — Product integration gate
 - Select one terrain provider and at most one justified occupancy complement.
 - Re-enable the frozen RF-DETR semantic-risk provider.
 - Repeat complete recorded-source-paced load acceptance.
 - Publish a LAB only after the costmap/elevation outputs and limitations are
  sealed.
 ## Immediate next action
 Resume T1 for Candidate A only after the Worker resource gate in the T0 report
 passes. No LOW-STEP tuning, new object model, camera resize, fisheye
 rectification, manual dataset or parallel heavy Worker job is authorized by
 this decision.
@@ -0,0 +1,95 @@
 # M4.9 T0 traversability candidate preflight — 2026-08-26
 Status: source and revision preflight complete; Candidate A build not started
 because the Worker resource-admission gate was closed
 ## Purpose
 T0 verifies that the first terrain-relative candidate can be evaluated against
 the immutable Mission Core source without colliding with another heavy Worker
 job. It does not qualify obstacle quality, realtime performance, navigation or
 actuation.
 The governing decision is
 [`docs/23_TRAVERSABILITY_AND_STATIC_OBSTACLE_STACK_DECISION.md`](../../docs/23_TRAVERSABILITY_AND_STATIC_OBSTACLE_STACK_DECISION.md).
 The exact upstream revisions are frozen in
 [`config/perception/m49-traversability-candidate-manifest-v1.json`](../../config/perception/m49-traversability-candidate-manifest-v1.json).
 ## Read-only Worker snapshot
 Observed at `2026-08-26T13:53:55Z` on Worker 006
 (`DESKTOP-OPJ8J04`):
 | Item | Observation |
 | --- | --- |
 | OS | Windows 11 Pro, version `10.0.26200`, build `26200` |
 | CPU | Intel Core i9-13900KF, 24 cores / 32 logical processors |
 | Physical memory | `100,502,708 KiB` visible; `685,344 KiB` free at the final snapshot |
 | GPU | NVIDIA GeForce RTX 4090, driver `610.47`, `24,564 MiB` total VRAM |
 | GPU snapshot | `9,131 MiB` used, `47%` utilization, `44 C` |
 | WSL | `docker-desktop` running; Ubuntu 24.04, MissionCore-Sim and MissionCore-CVAT stopped |
 | Mission Core inference | Canonical `ndc-mission-core-triton` remained healthy |
 | Parallel work | GAUSS gateway and builder containers were healthy and active |
 No container, WSL distribution, service or source file was started, stopped,
 rebuilt or modified during this inspection.
 ## Source and baseline evidence
 The canonical RAVNOVES00 camera index, LiDAR pack, local-surface pack and native
 fisheye video are present on the Worker at their existing content-addressed
 paths. The accepted raw M4.8R3 full run is present at:
 `D:\NDC_MISSIONCORE\runtime\results\m48r3-static-occupancy-shadow\ravnoves00-full-exact6-near8-12fps-v1`
 Its `result.json` SHA-256 is
 `0fe50546801d1284eb7af7ffcee0fbfc98985094c678256007b10eade0e54488`.
 The raw result reports:
 - source `RAVNOVES00`, `4,489` frames at requested `12 Hz`;
 - integrated runtime gate passed;
 - graph completion p95 `56.74324 ms`;
 - geometry p95/p99 `8.420913/13.732692 ms`;
 - GPU utilization p95/maximum `54%/58%`;
 - maximum GPU memory `9,743 MiB`.
 The separately sealed Mission Core product identity remains
 `m48r3-static-occupancy-shadow-d1577870b098bcd0b67cc51798234f224b348ad3954ead72f3ce6df414875a29`.
 This T0 check does not reopen or alter that evidence.
 ## Frozen candidates
 | Order | Candidate | Exact revision | Admission role |
 | ---: | --- | --- | --- |
 | 1 | DFKI GSeg3D | `5c5ba6f5ca0d682db2d59b2ad2f6a317ee938b95` | Primary terrain-relative ground/non-ground provider |
 | 1 | DFKI Nav2 Ground Consistency | `41cec620efba6c370dccfc59a6ec1134775ff48a` | Primary temporal costmap evidence layer |
 | 2 | TRAVEL | `95dc2fbd66a343efd9060c45a5711b6307a950a4` | Class-free challenger |
 | 3 | Isaac ROS nvblox `v4.6-0` | `ef47346399c71a4342c03bdbec2136ec735da4b8` | Separate GPU occupancy/ESDF probe |
 These SHAs were resolved directly from the official upstream repositories. A
 moving branch name is not an executable test identity.
 ## Resource-admission result
 **T1 was intentionally not started.** Free physical memory fell from roughly
 `3.3 GiB` during the first inventory to `669 MiB` at the final snapshot while
 the parallel GAUSS contour was active. Starting a ROS 2 image build or another
 replay in that state would make the measurement invalid and could destabilize
 unrelated work.
 Candidate A may start only when all of the following are true:
 1. no unrelated heavy Worker build or replay is active;
 2. free physical memory is at least `16 GiB` before the build;
 3. GPU utilization is at most `10%` before an integrated replay, unless the
   active GPU process is an explicitly admitted part of that replay;
 4. canonical Mission Core Triton is healthy and is not stopped or replaced;
 5. the candidate uses a new `ndc-` isolated build/runtime contour.
 ## Next command boundary
 The next authorized action is T1 Candidate A upstream qualification: build the
 pinned GSeg3D and Ground Consistency revisions in an isolated ROS 2 contour,
 run their upstream sample path, and record build identity, latency and memory.
 RAVNOVES00 replay begins only after that unmodified upstream qualification
 passes.