sim-vlm-robot

Isaac Sim + Isaac Lab 方向的具身智能 / VLA 项目。第一阶段（Week 1） 目标是搭建仿真场景、机械臂占位、桌面物体、俯视 RGB-D 相机，以及 RGB / depth / metadata 保存链路。不包含模型训练、Qwen2.5-VL、OpenVLA、ROS2 / MoveIt 或抓取控制。

项目目标

• 在 DGX Spark（Linux aarch64）上建立可复现的 Isaac Sim 桌面操作场景
• 加载 Franka Panda（或几何 placeholder）
• 放置红 / 蓝 / 绿方块与蓝 / 黄托盘
• 固定俯视 RGB-D 相机并导出数据，为后续 VLA 数据管线打基础

Week 1 完成内容

模块	说明
configs/scene.yaml	场景配置（机械臂、桌子、物体、托盘、相机）
sim/scene_builder.py	场景构建（USD 几何体、材质、相机 prim）
sim/assets.py	Isaac Sim 路径与 Franka USD 自动搜索
sim/camera_utils.py	相机姿态、RGB/depth/metadata 保存与采集
scripts/01_test_isaac.py	Isaac Sim Python 环境自检
scripts/02_create_scene.py	创建场景并保存 USD
scripts/03_capture_rgbd.py	采集 RGB-D 与 JSON metadata

环境变量

export ISAACSIM_PATH=/path/to/isaac-sim
export ISAACSIM_PYTHON_EXE=$ISAACSIM_PATH/python.sh

请把 /path/to/isaac-sim 替换为本机 Isaac Sim 安装目录。

安装 Python 依赖

项目根目录下，使用系统 Python 或 Isaac Sim 自带 Python 均可安装轻量依赖（不含 torch / transformers）：

pip install -r requirements.txt

推荐：

$ISAACSIM_PYTHON_EXE -m pip install -r requirements.txt

运行命令

在项目根目录 sim-vlm-robot/ 下执行：

export ISAACSIM_PATH=/path/to/isaac-sim
export ISAACSIM_PYTHON_EXE=$ISAACSIM_PATH/python.sh

# 1. 环境自检
$ISAACSIM_PYTHON_EXE scripts/01_test_isaac.py --headless true

# 2. 创建场景并保存 USD
$ISAACSIM_PYTHON_EXE scripts/02_create_scene.py --headless true --steps 120

# 3. 采集 RGB-D 与 metadata
$ISAACSIM_PYTHON_EXE scripts/03_capture_rgbd.py --headless true --steps 120

可选参数：

• --headless true|false（默认 true）
• --config configs/scene.yaml
• --steps 120（仿真步数）
• --frame-id scene_0001（仅 03_capture_rgbd.py）

输出文件

路径	说明
outputs/logs/week1_scene.usd	场景 USD 快照
outputs/rgb/scene_0001.png	RGB 图像
outputs/depth/scene_0001.npy	深度数组（float32）
outputs/logs/scene_0001.json	场景 metadata（相机、物体位姿、时间戳等）

Metadata 字段包括：camera_resolution、camera_position、camera_target、物体/托盘 3D 位置、timestamp、depth_valid。

Franka USD 资产

sim/assets.py 会在 ISAACSIM_PATH 下递归搜索包含 franka / panda 等关键词的 USD 文件。

若未找到：

• 程序不会崩溃，会使用 base + column + arm 的几何 robot placeholder
• 控制台会打印 WARNING

手动指定真实 Franka 资产（任选其一）：

1. 将 Franka USD 安装到 Isaac Sim 默认资产目录，确保能被搜索到
2. 修改 sim/assets.py 中 find_franka_usd()，直接 return Path("/your/path/to/franka.usd")
3. 在 configs/scene.yaml 的 robot.usd_path 指向本地 franka.usd

常见路径示例（因版本/安装方式而异，仅供参考）：

• {assets_root}/Isaac/Robots/FrankaRobotics/FrankaPanda/franka.usd（Omniverse 云端/缓存）
• $ISAACSIM_PATH/exts/omni.isaac.franka/...

调整机械臂位置（Transform）

Franka 是 articulation 关节链，不要直接改 panda_link0 等 link 的 Transform（Property 面板里往往是灰的或会被仿真覆盖）。

注意： Isaac Sim 里选中 RobotMount 时，视口 pivot 可能显示在机械臂 几何包围盒中心（约比底座高 0.55 m），而不是底座。因此不要把 RobotMount.translate.z 直接设为桌面高度。

本项目语义：

配置项	含义
robot.base_position: [x, y]	底座在桌面上的 XY footprint 中心
robot.z_offset	底座相对桌面的微调（米）
RobotMount.translate.z	自动计算 ≈ table_top + 0.557 + z_offset（pivot 在几何中心，不是桌面高度）
ModelAlign	内部偏移，把 Franka bbox 中心对齐到 mount pivot

方式	做法
改配置文件（推荐）	编辑 base_position / z_offset / rotation，重新运行 02_create_scene.py
GUI 里改	停止仿真 → 改 base_position 后重建；或选中 /World/RobotMount 微调（理解 pivot 在几何中心）

桌面顶面 z = 0.35 + 0.05/2 = 0.375 m。

robot:
  mount_path: /World/RobotMount
  align_path: /World/RobotMount/ModelAlign
  prim_path: /World/RobotMount/ModelAlign/Franka
  base_position: [0.08, 0.0]
  rotation: [0.0, 0.0, 0.0]
  z_offset: 0.002

Depth 采集说明

Isaac Sim 5.x 中，Camera.get_depth() 前必须先调用：

camera.add_distance_to_image_plane_to_frame()

项目已在 sim/camera_utils.py → _prepare_camera_sensor() 中自动注册。验证结果：depth_valid: true，深度单位为米（distance_to_image_plane）。

固定相机 vs 腕部相机： 当前 camera.mount: fixed，相机 prim 独立于机械臂。Week 2 若改为 eye-in-hand，只需修改 configs/scene.yaml 中的 prim_path（例如挂到 panda_hand），capture_rgbd() 无需重写。

相关文件：

• sim/camera_utils.py → capture_rgbd(), _prepare_camera_sensor()
• scripts/03_capture_rgbd.py
• 开发记录：docs/week1_notes.md

常见问题

1. Could not import SimulationApp

• 必须使用 $ISAACSIM_PYTHON_EXE 运行脚本，不要用系统 python3
• 确认 ISAACSIM_PATH 正确

2. ISAACSIM_PATH is not set

export ISAACSIM_PATH=/path/to/isaac-sim

3. RGB 全黑或 placeholder

• 尝试 --headless false 排查渲染
• 增加 --steps（例如 240）
• 检查 GPU 驱动与 Isaac Sim 渲染后端

4. Franka 未加载

• 查看日志中 [assets] Franka USD candidate 或 WARNING
• 按上文「Franka USD 资产」一节手动指定路径

5. aarch64 / DGX Spark

• 确认 Isaac Sim build 支持当前架构
• 资产搜索可能较慢，首次运行请耐心等待

Week 1 Checklist

• [1] 设置 ISAACSIM_PATH / ISAACSIM_PYTHON_EXE
• [1] pip install -r requirements.txt
• [1] 01_test_isaac.py 通过
• 02_create_scene.py 生成 week1_scene.usd
• 场景中有 table、cubes、trays、camera
• Franka 或 placeholder 可见
• 03_capture_rgbd.py 生成 PNG / NPY / JSON
• 填写 docs/week1_notes.md

目录结构

sim-vlm-robot/
├── scripts/
│   ├── 01_test_isaac.py
│   ├── 02_create_scene.py
│   └── 03_capture_rgbd.py
├── sim/
│   ├── assets.py
│   ├── camera_utils.py
│   ├── isaac_app.py
│   └── scene_builder.py
├── configs/scene.yaml
├── outputs/
├── docs/week1_notes.md
├── requirements.txt
└── README.md

下一阶段（非 Week 1）

• Qwen2.5-VL / VLA 模型接入
• 机械臂抓取与轨迹控制
• 强化学习 / 模仿学习数据批量采集

以上均不在当前范围内。