fix(nav): preserve unknown cells in saved maps

[axelpey]

Summary

• save Nav2 Humble trinary maps with free_thresh_default:=0.196 so gray 205 remains unknown after reload
• atomically migrate the exact legacy mode: trinary + free_thresh: 0.25 signature during map discovery
• keep known-free, occupied, and unknown cells distinct in the GPU grid localizer
• score only in-bounds occupied scan endpoints as matches; unknown and off-map endpoints are mismatches
• add focused metadata and localization-scoring regression tests

Why

Nav2 Humble writes unknown trinary cells as gray 205. With its default YAML free_thresh: 0.25, that pixel reloads as free ((255 - 205) / 255 ≈ 0.1961), so the global planner sees unmapped space as free even with allow_unknown: false.

Correcting the map metadata exposed a second bug: grid_localizer collapsed unknown and occupied into the same binary value and clipped off-map endpoints onto map-edge cells. Unknown space could therefore produce false obstacle matches and near-zero scores at unrelated poses.

Validation

• focused Python tests — 3 passed
• ruff check and ruff format on changed Python files — passed
• git diff --check — passed
• Robot 3 build: colcon build --symlink-install --packages-select mars_nav — passed
• live on mars-the-3rd.local: all 7 maps remain at free_thresh: 0.196; OfficeClean.yaml publishes 80,124 unknown cells; GridBased.allow_unknown=false
• after deploying the scoring fix, four stationary localizations agreed at (0.33, -1.13, 40°) with scores 0.426–0.441; before the fix, repeated runs jumped between opposite map edges with falsely excellent scores 0.002–0.013

The live result is consistent but above the configured 0.3 confidence threshold, so navigation still needs physical pose confirmation before being called healthy.

[greptile-apps]

Greptile Summary

This PR preserves unknown occupancy cells across map saves and reloads while correcting GPU localization scoring.

• Saves trinary maps with a threshold that keeps gray 205 cells unknown.
• Migrates legacy trinary metadata during map discovery.
• Separates free, occupied, and unknown cells and treats unknown or off-map scan endpoints as mismatches.
• Adds focused metadata and scoring regression tests.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
ros2_ws/src/mars_bot/mars_nav/mars_nav/grid_localizer.py	Preserves distinct occupied-map state on CPU and GPU and delegates endpoint scoring without edge clipping.
ros2_ws/src/mars_bot/mars_nav/mars_nav/grid_scoring.py	Adds backend-agnostic occupancy masks and mismatch scoring where only in-bounds occupied endpoints match.
ros2_ws/src/mars_bot/mars_nav/mars_nav/map_metadata.py	Implements narrowly scoped, atomic normalization of legacy trinary map thresholds.
ros2_ws/src/mars_bot/mars_nav/mars_nav/mode_manager.py	Applies metadata repair during discovery and supplies the corrected threshold to map saving.
ros2_ws/src/mars_bot/mars_nav/test/test_grid_scoring.py	Covers free, unknown, occupied, and off-map endpoint scoring.
ros2_ws/src/mars_bot/mars_nav/test/test_map_metadata.py	Covers exact legacy migration and preservation of safe or non-trinary metadata.

Sequence Diagram

sequenceDiagram
  participant MM as Mode Manager
  participant Saver as Nav2 Map Saver
  participant Disk as Map Files
  participant Map as Map Server
  participant GL as Grid Localizer
  participant AMCL as AMCL
  MM->>Saver: "Save map with free_thresh_default=0.196"
  Saver->>Disk: Write image and YAML
  MM->>Disk: Discover and repair exact legacy metadata
  Disk->>Map: Reload trinary occupancy map
  Map->>GL: Publish free, occupied, and unknown cells
  GL->>GL: Score only in-bounds occupied endpoints
  GL->>AMCL: Publish coarse initial pose

Loading

_{Reviews (3): Last reviewed commit: "style(nav): format map metadata helper" | Re-trigger Greptile}