Jetson Nano Stereo Risk MVP

English version: README_EN.md

本项目是一个运行在 Jetson Nano 上的双目深度风险感知 MVP，面向“实时避障感知”验证。

核心特点：

• 双目相机 + IMU 异步采集
• VPI CUDA 优先、CPU SGBM 自动回退
• 5x2 空间风险网格（上 5 + 下 5）
• 终端 ASCII 仪表盘实时观察（无 GPIO 依赖）

---

1. 项目结构（已整理）

下面是当前仓库的功能分层结构。

nano_project/
├─ src/                          # 核心运行代码
│  ├─ main.py                    # 程序入口：线程启动、调度与仪表盘渲染
│  ├─ core_hub.py                # 线程安全共享数据中枢（LatestValueStore + SensorHub）
│  ├─ sensors.py                 # 双目 CSI 相机与 ICM20948 IMU 采集线程
│  ├─ depth_engine.py            # 深度线程：VPI/CPU 视差、深度图、风险模型联动
│  └─ risk_model.py              # 5x2 ROI 风险计算（趋势项 + Ground Drop）
├─ scripts/                      # 运维与标定脚本
│  ├─ depoly.sh                  # 本地代码同步到 Nano（rsync）
│  ├─ depoly_and_run.sh          # 同步 + 远端限时运行 + 日志摘要
│  ├─ collect_calib.py           # 采集双目标定图像对（自动判角点）
│  ├─ stereo_calibrate.py        # 执行双目标定并生成标定文件
│  └─ OpenCV-4-5-5.sh            # OpenCV 环境相关脚本
├─ docs/                         # 项目文档与规则
│  ├─ 00_SYSTEM_RULES_AND_SUMMARY.md
│  ├─ 01_architecture_decisions.md
│  ├─ 02_claude_optimizations.md
│  └─ 03_hardware_specs.md
├─ artifacts/                    # 运行产物与标定数据
│  ├─ calib.npz                  # 当前使用的双目标定结果（remap/Q/K/T）
│  ├─ run.log                    # 最近一次远端运行日志（如果存在）
│  ├─ calib_images/
│  │  ├─ left/
│  │  └─ right/
│  └─ archives/                  # 历史打包归档
├─ requirements.txt              # Python 依赖（Jetson 与非 Jetson 分流）
├─ pip.conf                      # pip 配置
└─ README.md

说明：当前仓库已按 src/scripts/docs/artifacts 完成真实目录重构。

---

2. 运行链路总览

Camera Thread (src/sensors.py) ----> hub.camera_store ----\
                                                       \
IMU Thread (src/sensors.py) --------> hub.imu_store -------> Depth Worker (src/depth_engine.py)
                                                         |  - rectify + stereo matching
                                                         |  - depth map
                                                         |  - SpatialRiskGrid
                                                         v
                                                     hub.risk_queue (size=1)
                                                         |
                                                         v
                        Main Loop Dashboard (src/main.py)

设计原则：

• 高频链路只保留最新值，避免积压延迟
• 低频决策槽位队列（size=1）始终保新
• 发生 VPI 上下文问题时自动回退 CPU，保证可用性

---

3. 核心模块说明

src/main.py

• 启动 camera、imu、depth coordinator 三个线程
• 主循环从风险队列取最新包并刷新仪表盘
• 显示内容包括：Risk、真实 ROI 深度、Depth Valid、后端模式、告警

src/core_hub.py

• LatestValueStore：锁保护的“只保留最新值”容器
• SensorHub：统一承载 camera/imu/depth 与 risk_queue
• put_risk_nowait：队列满时丢旧保新

src/sensors.py

• 双路 CSI 相机：nvarguscamerasrc + GStreamer 管线
• 支持 profile 回退、重开、健康度检测、最佳努力重启 Argus
• ICM20948 IMU：I2C 读取 gyro，转换为 rad/s

src/depth_engine.py

• 专用深度工作线程持有 VPI 上下文
• 使用 artifacts/calib.npz remap 做校正，再进行视差计算
• VPI CUDA 优先，失败自动切 CPU SGBM
• 从 Q/K/T 自动提取尺度参数，统一深度换算
• 输出：depth_map、risk_scores、roi_depths、alerts、backend、valid_ratio

src/risk_model.py

• 将 160x120 深度图划分为 10 个 ROI
• 对每个 ROI 计算有限值中位深度
• 风险模型：1/max(depth, 0.3) + 0.5*trend
• Ground Drop 列触发强制高风险（999.0）

---

4. 环境与依赖

推荐平台：Jetson Nano + JetPack 4.x。

先安装系统依赖：

sudo apt-get update
sudo apt-get install -y \
  python3-pip python3-dev python3-opencv python3-numpy python3-smbus \
  i2c-tools v4l-utils \
  gstreamer1.0-tools \
  gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
  gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly

再安装 Python 依赖：

python3 -m pip install -r requirements.txt

说明：

• Jetson aarch64 上优先使用系统 OpenCV/NumPy
• 非 aarch64 开发机按 requirements 条件安装 pip 版本

---

5. 快速开始

5.1 本机运行

python3 src/main.py

5.2 一键部署并短跑回归（推荐）

./scripts/depoly.sh
RUN_SECONDS=12 ./scripts/depoly_and_run.sh

scripts/depoly_and_run.sh 会执行：

• rsync 同步项目
• 远端限时运行 src/main.py
• 打印关键日志摘要与计数统计

---

6. 标定流程

1. 采集棋盘格图像对

python3 scripts/collect_calib.py

2. 执行双目标定并生成 artifacts/calib.npz

python3 scripts/stereo_calibrate.py

3. 重新运行主程序验证深度与风险输出

---

7. 仪表盘读数说明

• Depth Valid：深度图有限值占比（越高通常越稳定）
• Mode：VPI-CUDA 或 CPU-SGBM
• Depth 行：每个 ROI 的真实深度（不是风险反推）
• Alerts：包括 CAMERA: NO FRAME、DEPTH: ERROR、FATAL: GROUND DROP!

---

8. 常见问题排查

启动后出现 CAMERA: NO FRAME

• 检查 CSI 连接和供电
• 手动确认 nvarguscamerasrc 可用
• 若远端脚本无 sudo 权限，自动重启 nvargus-daemon 可能被跳过

VPI 异常或自动切 CPU

• 关注日志中的 VPI 初始化与 context 冲突提示
• CPU 回退是预期保护行为，可先保证链路可用再定位 VPI 环境

深度近距抖动

• 与 max_disp、纹理条件、曝光和标定质量强相关
• 先确认 artifacts/calib.npz 与采集分辨率一致（当前链路按 1280x720 校正）

---

9. 开发约束

• 高频路径避免无界队列和阻塞式串行瓶颈
• 风险和深度核心路径避免像素级 Python 循环
• 若实现与 docs/00_SYSTEM_RULES_AND_SUMMARY.md 冲突，以该文档为准