Bio_Nav Module3：Isaac Sim 6.0.1 + ROS 2 Jazzy 导航

本仓库负责 Bio_Nav 的物理导航主链：场景与传感器、地图与 TF、全局 GVG、 Route Server、Nav2、MPPI、Collision Monitor 和 /cmd_vel。当前开发主线是 Final Rivermark 室外五航点导航收口；酷家乐室内任务和 Attempt31 证据仍保留为兼容与历史复现入口。

当前状态（2026-08-15）

Final clean-revision 已完成正式静态、动态、外观各 20 轮并通过 fail-closed 资格汇总。它使用独立分支 codex/final-outdoor-navigation 和独立场景 identity，不改写 Attempt31 的任何原始轮次：

Final 项目	冻结实现	当前状态
静态物理障碍	4 个 map-frame stationary box，均位于可通行地图格并切入旧 nominal route	20/20 成功且无碰撞，四障碍覆盖 PASS
动态威胁	四 actor 峰值 0.45–0.60 m/s，5 个时序 variant 各重复 4 次	20/20 成功且无碰撞，威胁/交互门 PASS
外观颜色	`dim_warm`、`dim_cool`、`bright_warm`、`bright_cool` 各 5 轮	20/20 成功且无碰撞
正式统计	静态、动态、外观各 20；每轮 G1–G5、无碰撞、证据完整	`FORMAL_QUALIFICATION_PASS`
fail-stop	首个 goal dispatch 前写 `TRIAL_DISPATCHED.json`；dispatch 后失败立即停止且不补轮	已实现并测试
动态有效性	每 actor 的峰值速度、轨迹进度、相对闭合速度、TTC、2.5 m 暴露和最近距离	已实现并测试
99.53% 口径	仅为 adaptation compute latency reduction；不属于导航成功率或端到端加速	已修正

Final final_rivermark_qualification 已通过。资格收据提交在 Integration 的 docs/evidence/final_navigation/outdoor_final_qualification/；原始 evidence 封存在 /mnt/nas_home/Bio_Nav_Data/Attempt32_Final_Qualification_20260814/final_rivermark/formal_036191f。下面的 Attempt31 结果继续作为已冻结历史基线，而不是 Final 结果。

V4 的 Q36_04、Q14_45、Q36_51 四臂工程验证也已完成，共 60/60 完成且无碰撞。 Q36_04 未观察到因果收益，Q14_45 观察到风险信号但不改线，Q36_51 的 SR-only 5/5 改线；因此只能写作场景/arm 依赖的工程证据，不能宣称 Module2 普遍提升。

Attempt31 已在独立 Module3/Integration 工作树完成实现、3×20 正式运行和 fail-closed 资格汇总。60 轮原始 evidence 的冻结代码基线为 Module3 7ff1cec7...、Integration 056dd6af6...；其后的 RViz/交互演示收尾只做回归验证，不回填或改写资格 evidence。

项目	当前实现/结果	状态
物理地图	80 m × 80 m，1600×1600，0.05 m/格	PASS
地图生成	top-down RGB/depth + PhysX occupancy + 高度跃迁/路沿	PASS
导航任务	`start → G1 → G2 → G3 → G4 → G5`，总参考长度 113.0562 m	PASS
静态实验	20/20 严格成功，20/20 无碰撞，最大路径偏差 3.256%	PASS
动态实验	18/20 严格成功，20/20 无碰撞，四阶段 actor 合同 20/20	PASS
外观实验	四种光照/颜色 profile 各 5 轮，共 20/20	PASS
认知分区	16×16 cell、1 m/cell；12 m core/stride + 每侧 2 m halo	PASS
分 tile 缓存	16 entries、320 hits、16 misses；跨区导航不中断	PASS
Module2 在线消费	dynamic-v2 20/20 有健康 prior、正 edge delta 和选中路线代价变化	PASS（非因果声明）
在线适配计算耗时	20 组 paired case 最小提升 99.473%，要求 ≥20%；不是训练或导航时间	PASS（compute-only）
A→B 地图更新	20 组 paired update 最小提升 30.313%，要求 ≥30%	PASS
Module2 四臂因果矩阵	不在 Rivermark 运行	`DEFERRED_TO_V4`

最终资格报告为：

data/experiment_runs/attempt31_rivermark/formal_20260814_v075_r30_cache/
  qualification_v3/attempt31_rivermark_qualification.json
SHA-256: 8abd0a9a9f98ba0f819035ec1dde91fbdf3c459d7490978b01bfebdd35b9af5a

data/experiment_runs/ 是本地原始 evidence，不提交 Git。仓库中保留可复核的地图、配置、paired benchmark、图表、脚本和资格汇总代码。dynamic-v1 的 16/20 STOP 保持不可变；dynamic-v2 使用新配置哈希和新 evidence 根，没有删除或替换失败轮。

地图与五航点示意

导航地图不是从俯视 RGB 简单阈值化得到的。生成器联合使用深度、PhysX occupancy 和局部高度跃迁；0.03 m 以上的局部路沿会形成占据边界，同时排除无物理碰撞语义的曲线、点和渲染阴影。启动入口会拒绝任何不是 1600×1600、0.05 m/格的地图。

除上述自研 top-down 方式外，仓库还提供 Isaac 内置 Occupancy Map Generator （isaacsim.asset.gen.omap 的 PhysX Generator 接口）的建图入口 isaac_sim/tools/rivermark_occupancy_generate.py：经 Integration final 分支的 ./scripts/run_final_outdoor_mapping.sh 一条命令调用，按生产地图同一配方对原 80 m × 80 m candidate A 窗口以 0.05 m/格生成占用图（不做全场景体素化），导出 map_server 兼容的 pgm+yaml 到 workspace runs/operator_maps/<version>/（MAPPING_OUTPUT_ROOT 与 RIVERMARK_MAP_VERSION 可覆盖，已存在的地图产物绝不覆盖）。该入口是工程/操作员工具，不作为资格证据；自研 rivermark_prepare.py 保持为对照实现。

静态、动态和外观三组使用同一套五航点。下图左侧是正式静态轨迹，右侧是 dynamic-v2 机器人与四个物理 actor 的实测轨迹，不是手绘示意。

架构与所有权

Rivermark USD + collision/depth
  → 0.05 m OccupancyGrid（1600×1600）
  → 全局 GVG / nav2_route / CanonicalRoute
  → Smac + MPPI + Collision Monitor
  → /cmd_vel → Isaac Jackal

map pose + current region + CanonicalRoute
  → 16×16 cognitive constraints + route-aligned local goal
  → optional Module2 edge prior
  → 有上界的 edge-cost 增量

Module3 始终拥有物理可达性、edge 合法性、最终路线、局部避障和控制权。
Integration 负责区域约束、T_map_canvas、真实路线上的 lookahead 和 Module2 通信。
Module2 只能返回有界、非负 edge prior；不能创建边、解除 BLOCKED、修改 TF、定位、Costmap 主安全链或直接控制机器人。
prior 超时、不健康、NaN、身份不匹配或覆盖不足时，系统回退 geometry-only。

全场只有一个连续 map 和一个全局 GVG。进入新区域时只切换 cognitive_tile_id、T_map_canvas 和 Module2 短期上下文；不会重启 Isaac/Nav2，不会重置 map→odom，也不会中断当前五航点任务。

快速开始

1. 准备资产和构建

cd /home/lyb/Workspace/Bio_Nav/worktrees/module3/final-outdoor-navigation
git lfs pull
./scripts/import_assets.sh
./scripts/prepare_rivermark_demo.sh

cd /home/lyb/Workspace/Bio_Nav/worktrees/integration/final-indoor-outdoor-navigation/ros2_ws
source /opt/ros/jazzy/setup.bash
colcon build --symlink-install

cd /home/lyb/Workspace/Bio_Nav/worktrees/module3/final-outdoor-navigation/ros2_ws
source /opt/ros/jazzy/setup.bash
source /home/lyb/Workspace/Bio_Nav/worktrees/integration/final-indoor-outdoor-navigation/ros2_ws/install/local_setup.bash
colcon build --symlink-install

默认源场景为 /home/lyb/Rivermark/rivermark.usd；可通过 RIVERMARK_USD 指向同一资产的其他只读位置。

2. 单轮可视化

下面四条就是日常演示入口。每条命令都在当前一个终端内同时管理 Isaac Sim GUI、室外专用 RViz、Module2 和 Module3；前三条自动执行 G1→G5，第四条只接收 RViz 手动目标。按一次 Ctrl+C 会清理整套栈。

cd /home/lyb/Workspace/Bio_Nav/worktrees/module3/final-outdoor-navigation

# 静态导航
ROS_DOMAIN_ID=231 ./scripts/run_rivermark_visual.sh static

# 动态导航：G2--G5 四阶段物理移动障碍
ROS_DOMAIN_ID=231 ./scripts/run_rivermark_visual.sh dynamic

# 外观/光照变化导航；默认 bright_warm
ROS_DOMAIN_ID=231 ./scripts/run_rivermark_visual.sh appearance bright_warm

# 手动导航：不预发航点，在 RViz 中使用 2D Goal Pose
env ROS_DOMAIN_ID=231 ./scripts/run_rivermark_manual.sh static

外观 profile 还可替换为 dim_warm、dim_cool 或 bright_cool。底层 run_rivermark_demo.sh 仍保留给 geometry-only 对照和参数化调试；上面的 visual wrapper 固定启用完整 Module2/Module3/RViz 链路。第一次需要冷启动 12 GB 场景；同一实验组的后续轮次由 campaign runner 复用运行栈，不会每轮重启 Isaac。静态、动态、外观组之间可以重启。四种模式的完整逐步操作、就绪标志、退出和故障判断见 Rivermark 室外演示说明。

无显示器 smoke：

RIVERMARK_HEADLESS=1 RIVERMARK_MAX_STEPS=3000 \
  ROS_DOMAIN_ID=231 ./scripts/run_rivermark_demo.sh off static

室外专用 RViz

GUI 单轮默认启动 robot_description/rviz/rivermark.rviz；headless campaign 默认不启动 RViz。可显式覆盖：

RIVERMARK_RVIZ=1 ROS_DOMAIN_ID=231 ./scripts/run_rivermark_demo.sh module2 static
RIVERMARK_RVIZ=0 ROS_DOMAIN_ID=231 ./scripts/run_rivermark_demo.sh off static

专用视图不是室内配置换地图，而是同时展示：

室外物理层：0.05 m Occupancy、LiDAR、Global/Local Costmap、Jackal footprint；
全局导航层：GVG、CanonicalRoute、Smac、MPPI、实走轨迹、projection/lookahead；
分 tile 层：全部 12 m core、当前 16×16 canvas、256 cells、上一 tile、切换箭头；
Module2 层：place belief/peak、SR、DR、dynamic cost、remap rate 和 edge delta；
Module3 层：结构图状态、runtime suspect/blocked edge、最终 edge cost 和路线进度；
所有权面板：Module2 的 ACTIVE/GUARDED/STALE/OFF，Module3 的物理最终裁决，以及实际 applied edge 数量和累计增量。

注：ownership/active_tile_status/tile_switch_event/dynamic_obstacle_status 与 place_peak 等状态文字默认隐藏，可在 RViz 面板按 namespace 手动开启。退出说明：Ctrl+C 触发有界清理（INT 3 s→TERM 2 s→KILL），清理期间再按一次 Ctrl+C 立即强杀且不留残留进程。

marker 按更新频率拆成 /bio_nav/v310/rviz_static（GVG/tile core/航点，仅图变化时）、 /bio_nav/v310/rviz_edges（Module2→Module3 edge handoff，按数据变化）和 /bio_nav/v310/rviz（当前 tile/执行状态，2 Hz）。RViz 中仍可按 namespace 独立开关；切 tile 时不会再 DELETEALL 并重建整张 GVG。 Module2 没启动或 prior 超时不会留下“看似仍有效”的绿色状态，而会明确显示 GEOMETRY-ONLY FALLBACK。

3. 批量实验

cd /home/lyb/Workspace/Bio_Nav/worktrees/module3/final-outdoor-navigation

# 指定 --run-indices 可做 pilot；省略时运行配置中的完整 20 轮
ROS_DOMAIN_ID=232 ./scripts/run_final_rivermark_campaign.sh static off --run-indices 1 \
  --output data/experiment_runs/final_rivermark/pilots/rev1/static_off
ROS_DOMAIN_ID=232 ./scripts/run_final_rivermark_campaign.sh dynamic medium --run-indices 1 \
  --output data/experiment_runs/final_rivermark/pilots/rev1/dynamic_medium
ROS_DOMAIN_ID=232 ./scripts/run_final_rivermark_campaign.sh appearance medium --run-indices 1 \
  --output data/experiment_runs/final_rivermark/pilots/rev1/appearance_medium

pilot 通过并冻结场景哈希后，去掉 --run-indices 1 才能运行完整 20 轮。Final wrapper 对 pre-dispatch 基础设施错误保留有界重试；一旦 TRIAL_DISPATCHED.json 已写入，任何任务、碰撞、证据或 checksum 失败都会停止 campaign，失败轮原样保留且禁止补跑替换。单轮结束后使用 final_rivermark_pilot_check 复算 checksum 和预注册交互门控，例如：

source /opt/ros/jazzy/setup.bash
source ros2_ws/install/local_setup.bash
ros2 run robot_experiments final_rivermark_pilot_check \
  --group static \
  --root data/experiment_runs/final_rivermark/pilots/rev1/static_off/runs \
  --metric-contract data/rivermark_demo/final_rivermark_metric_contract.yaml \
  --output data/experiment_runs/final_rivermark/pilots/rev1/static_off/pilot_check.json

只读取已完成 evidence 生成资格报告：

source /opt/ros/jazzy/setup.bash
source ros2_ws/install/local_setup.bash
ros2 run robot_experiments final_rivermark_qualification \
  --static-root data/experiment_runs/final_rivermark/static/off/runs \
  --dynamic-root data/experiment_runs/final_rivermark/dynamic/medium/runs \
  --appearance-root data/experiment_runs/final_rivermark/appearance/medium/runs \
  --metric-contract data/rivermark_demo/final_rivermark_metric_contract.yaml \
  --contract-summary data/rivermark_demo/benchmarks/module2_contracts/contract_benchmark_summary.json \
  --output data/experiment_runs/final_rivermark/qualification/qualification.json

Module2 与 tile 证据边界

Rivermark 的 Module2 结论分成两类，不能混用：

runtime_consumption_only 证明 prior 请求真实到达 Route Server，并在有界条件下改变选中路线的 cost snapshot。dynamic-v2 的 20 轮均满足该合同。
16×16 region_22 paired benchmark 证明缓存收敛和 parent-child 增量更新效率。

它们都不能证明 OFF、SR-only、DR-only、SRDR 哪一臂带来因果性能改善。四臂静态因果矩阵已由 V4 单独验证，不在 Rivermark qualification 中运行；最终结果为 ENGINEERING_MIXED_SCENE_DEPENDENT。

Persistent blockage 入口仅用于工程演示：

ROS_DOMAIN_ID=231 ./scripts/trigger_rivermark_blockage.sh blocked
ROS_DOMAIN_ID=231 ./scripts/trigger_rivermark_blockage.sh clear

该注入用于观察重复确认、关闭边和重路由，不属于传感器因果证据，也不计入正式避障率。真实动态障碍仍由 LiDAR/RGB-D、Local Costmap、MPPI 和 Collision Monitor 处理。

验证

当前 Final 增量回归结果：

Final 专项：48 passed；
仓库级非 Isaac/ROS：817 passed、1 skipped、14 deselected；
ROS/colcon：739 tests、0 errors、0 failures、5 skipped。

历史 Attempt31 收尾工作树回归结果：

仓库级 pytest：807 passed，12 skipped；
robot_experiments 安装态：310 passed；
ROS 汇总：591 tests，0 errors，0 failures，1 skipped；
60 个正式轮次和资格报告 checksum 全部通过。

常规本地检查：

./scripts/test.sh
git diff --check

文档入口

目标	文档
Attempt31 完整运行、地图、航点和证据说明	Rivermark 室外导航手册
Attempt31 指标、P0–P8 与完成性	Rivermark 完成性审计
通用 Topic、TF、QoS 与职责	接口文档
Isaac、DDS、RViz、Reset 与 Nav2 排障	排障手册
Module2 与 Nav2 历史融合设计	Module2 × Nav2 规划/风险融合
仓库与远端治理	分支与标签目录

Final 汇总与架构文档（Integration 仓库）

以下文档位于配对的 Integration 工作树 /home/lyb/Workspace/Bio_Nav/worktrees/integration/final-indoor-outdoor-navigation/docs/final_closure/（分支 codex/final-indoor-outdoor-navigation），是本仓库 Final 结果在整体项目口径下的汇总：

目标	文档
室内静态/动态/外观 60 轮结果与指标	`results_indoor_60.md`
室外静态/动态/外观 60 轮结果与指标（含本仓库 Final 资格口径）	`results_outdoor_60.md`
V4 五组四臂 100 行结果与指标	`results_v4_100.md`
Module2 作用机制与有效证据	`module2_effectiveness_evidence.md`
五项工程验收指标总表与资格矩阵	`results_master_summary.md`
整体导航架构（Module1/Module2/Module3 与 Integration）	`final_navigation_architecture.md`

历史兼容入口：Kujiale / Attempt21

酷家乐室内 stable、dynamic_avoidance 和显式 static opt-in 仍保留，不因 Attempt31 改写。历史 4×20、Attempt21 v12/v13/v15/v16、冻结 STOP/PASS 及其 receipt 必须按原文档和原提交解释，不能用 Rivermark 结果回填。

已知边界

当前 Rivermark 是 Ideal Odometry 科研 Demo，不代表真实传感器定位或室外泛化。
源场景部分 foliage point-instancer 缺少 prototype，首次加载会产生渲染 warning；它不参与导航碰撞或栅格生成。
少量缺失材质只影响显示，不改变地图、碰撞体或正式任务几何。

Name		Name	Last commit message	Last commit date
data		data
docs		docs
isaac_sim		isaac_sim
ros2_ws/src		ros2_ws/src
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
pyproject.toml		pyproject.toml

Navigation Menu

Repository files navigation

Bio_Nav Module3：Isaac Sim 6.0.1 + ROS 2 Jazzy 导航

当前状态（2026-08-15）

地图与五航点示意

架构与所有权

快速开始

1. 准备资产和构建

2. 单轮可视化

室外专用 RViz

3. 批量实验

Module2 与 tile 证据边界

验证

文档入口

Final 汇总与架构文档（Integration 仓库）

历史兼容入口：Kujiale / Attempt21

已知边界

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Bio_Nav Module3：Isaac Sim 6.0.1 + ROS 2 Jazzy 导航

当前状态（2026-08-15）

地图与五航点示意

架构与所有权

快速开始

1. 准备资产和构建

2. 单轮可视化

室外专用 RViz

3. 批量实验

Module2 与 tile 证据边界

验证

文档入口

Final 汇总与架构文档（Integration 仓库）

历史兼容入口：Kujiale / Attempt21

已知边界

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages