3d6b73753a
- Add pick_test_tube task: USDC asset repackaging, grasp generation, task config - Add tools: usdc_to_obj.py, repackage_test_tube.py, fix_test_tube_materials.py - Add custom_task_guide.md: full Chinese documentation for creating custom tasks - Add crawled InternDataEngine online docs (23 pages) - Add grasp generation script (gen_tube_grasp.py) and pipeline config
304 lines
9.3 KiB
Markdown
304 lines
9.3 KiB
Markdown
# 自定义任务创建指南：从 USDC 资产到完整任务
|
||
|
||
本文档记录了将外部 USDC 资产（以试管为例）转换为 InternDataEngine 可用任务的完整流程。
|
||
|
||
## 前提条件
|
||
|
||
- InternDataEngine 项目已配置完成（IS 5.0.0 + banana500 环境）
|
||
- 有现成的 USD/USDC 3D 模型文件
|
||
- conda 环境 `banana450`（用于 grasp 标注生成，pyarmor 兼容）
|
||
|
||
## 完整流程
|
||
|
||
### Step 1: 准备资产目录
|
||
|
||
在 `workflows/simbox/example_assets/task/` 下创建任务目录：
|
||
|
||
```bash
|
||
mkdir -p workflows/simbox/example_assets/task/pick_test_tube/test_tube
|
||
mkdir -p workflows/simbox/example_assets/task/pick_test_tube/test_tube_rack
|
||
```
|
||
|
||
### Step 2: 从 USDC 导出三角化 OBJ
|
||
|
||
InternDataEngine 的 grasp 生成工具需要 OBJ 格式输入，且必须是纯三角面。使用 `migrate/usdc_to_obj.py` 从 USDC 提取并三角化：
|
||
|
||
```bash
|
||
conda activate banana500
|
||
python migrate/usdc_to_obj.py \
|
||
--input /path/to/your/model.usdc \
|
||
--output workflows/simbox/example_assets/task/pick_test_tube/test_tube/
|
||
```
|
||
|
||
输出文件：`Aligned_obj.obj`（三角化的 OBJ）
|
||
|
||
**注意**：原始 USDC 中的面可能是四边形或多边形，脚本会自动进行 fan 三角化。
|
||
|
||
### Step 3: 重新打包 USD 结构
|
||
|
||
InternDataEngine 要求 USD 资产具有特定的层级结构：
|
||
|
||
```
|
||
/World (defaultPrim, Xform, 无物理属性)
|
||
├── /Looks (Scope, 材质)
|
||
│ ├── Material_0
|
||
│ └── Material_1
|
||
├── /Aligned (Xform, PhysicsRigidBodyAPI + PhysicsMassAPI)
|
||
│ └── /mesh (Mesh, PhysicsCollisionAPI + PhysicsMeshCollisionAPI)
|
||
└── /PhysicsMaterial (Material, PhysicsMaterialAPI)
|
||
```
|
||
|
||
**关键要求**：
|
||
- `/World` 必须是 defaultPrim，且不能有任何物理 schema
|
||
- `/Aligned` 是 `prim_path_child`，必须有 `PhysicsRigidBodyAPI`
|
||
- 碰撞体必须使用 `convexHull` 近似（不能用 triangle mesh）
|
||
- `/Looks` 必须和 `/Aligned` 平级（在同一引用范围内）
|
||
|
||
使用 `migrate/repackage_test_tube.py` 自动重构：
|
||
|
||
```bash
|
||
python migrate/repackage_test_tube.py
|
||
```
|
||
|
||
脚本逻辑：
|
||
1. 创建新 USD，定义 `/World` 为 defaultPrim（纯净 Xform，不挂引用）
|
||
2. 在 `/World/Aligned` 上添加引用，指向源 USD 的子节点（如 `/Test_Tube_AA_01/Test_Tube`）
|
||
3. 在 `/World/Looks` 上添加引用，指向源 USD 的材质（如 `/Test_Tube_AA_01/Looks`）
|
||
4. 给 `/World/Aligned` 添加 `PhysicsRigidBodyAPI` 和 `PhysicsMassAPI`
|
||
5. 给碰撞 mesh 设置 `convexHull` 近似
|
||
|
||
**重新绑定材质**：由于引用子节点后，原始材质绑定路径超出引用范围，需要手动重新绑定：
|
||
|
||
```bash
|
||
python migrate/fix_test_tube_materials.py
|
||
```
|
||
|
||
### Step 4: 生成 Grasp 抓取标注
|
||
|
||
使用项目自带的 grasp 生成工具（需要 `banana450` 环境，因为 pyarmor 加密对 Python 版本敏感）：
|
||
|
||
```bash
|
||
conda activate banana450
|
||
python workflows/simbox/tools/grasp/gen_sparse_label.py \
|
||
--obj_path workflows/simbox/example_assets/task/pick_test_tube/test_tube/Aligned_obj.obj \
|
||
--unit m --sparse_num 3000 --max_widths 0.1
|
||
```
|
||
|
||
输出：`Aligned_grasp_sparse.npy`（3000 x 17 的数组）
|
||
|
||
**可视化验证**：
|
||
|
||
```bash
|
||
python workflows/simbox/tools/grasp/vis_grasp.py \
|
||
--obj_path workflows/simbox/example_assets/task/pick_test_tube/test_tube/Aligned_obj.obj \
|
||
--unit m --N 200
|
||
```
|
||
|
||
会弹出 Open3D 窗口，蓝色线条表示 gripper 姿态，应该合理地分布在物体周围。
|
||
|
||
**Grasp 标注格式（N x 17）**：
|
||
|
||
| 列 | 维度 | 含义 |
|
||
|---|---|---|
|
||
| 0 | 1 | score（质量分数，0.1-1.0，越小越好） |
|
||
| 1 | 1 | width（夹持器开口宽度） |
|
||
| 2 | 1 | height |
|
||
| 3 | 1 | depth |
|
||
| 4:13 | 9 | 旋转矩阵（3x3，row-major） |
|
||
| 13:16 | 3 | 抓取中心点位置（物体坐标系） |
|
||
| 16 | 1 | obj_id（通常为 -1） |
|
||
|
||
### Step 5: 创建任务配置 YAML
|
||
|
||
文件：`workflows/simbox/core/configs/tasks/example/pick_test_tube.yaml`
|
||
|
||
```yaml
|
||
tasks:
|
||
-
|
||
name: banana_base_task
|
||
asset_root: workflows/simbox/example_assets
|
||
task: BananaBaseTask
|
||
task_id: 0
|
||
offset: null
|
||
render: True
|
||
neglect_collision_names: ["table"]
|
||
|
||
arena_file: workflows/simbox/core/configs/arenas/example.yaml
|
||
|
||
env_map:
|
||
envmap_lib: envmap_lib
|
||
apply_randomization: False
|
||
intensity_range: [5000, 5000]
|
||
rotation_range: [0, 0]
|
||
|
||
robots:
|
||
-
|
||
name: "split_aloha"
|
||
robot_config_file: workflows/simbox/core/configs/robots/split_aloha.yaml
|
||
euler: [0.0, 0.0, 90.0]
|
||
ignore_substring: ["material", "table", "test_tube_rack"]
|
||
|
||
objects:
|
||
-
|
||
name: test_tube_right
|
||
path: task/pick_test_tube/test_tube/Aligned_obj.usd
|
||
target_class: RigidObject
|
||
dataset: custom
|
||
category: test_tube
|
||
prim_path_child: Aligned
|
||
translation: [0.0, 0.0, 0.0]
|
||
euler: [0.0, 0.0, 0.0]
|
||
scale: [1, 1, 1]
|
||
apply_randomization: False
|
||
orientation_mode: keep
|
||
|
||
regions:
|
||
-
|
||
object: test_tube_right
|
||
target: table
|
||
random_type: A_on_B_region_sampler
|
||
random_config:
|
||
pos_range: [[0.05, -0.05, 0.0], [0.15, 0.05, 0.0]]
|
||
yaw_rotation: [0.0, 0.0]
|
||
-
|
||
object: split_aloha
|
||
target: table
|
||
random_type: A_on_B_region_sampler
|
||
random_config:
|
||
pos_range: [[0.0, -0.86, -0.75], [0.0, -0.86, -0.75]]
|
||
yaw_rotation: [0.0, 0.0]
|
||
|
||
cameras:
|
||
# ... 复用 split_aloha 的相机配置（详见完整配置文件）
|
||
|
||
data:
|
||
task_dir: "pick_test_tube"
|
||
language_instruction: "Pick up the test tube from the table."
|
||
detailed_language_instruction: "Use the right arm to grasp the test tube."
|
||
collect_info: "Test tube picking task"
|
||
version: "v1.0"
|
||
update: True
|
||
max_episode_length: 2000
|
||
|
||
skills:
|
||
-
|
||
split_aloha:
|
||
-
|
||
right:
|
||
-
|
||
name: pick
|
||
objects: [test_tube_right]
|
||
npy_name: Aligned_grasp_sparse.npy
|
||
filter_y_dir: ["forward", 60]
|
||
filter_z_dir: ["downward", 150]
|
||
pre_grasp_offset: 0.05
|
||
gripper_change_steps: 10
|
||
t_eps: 0.025
|
||
o_eps: 1
|
||
process_valid: True
|
||
lift_th: 0.02
|
||
post_grasp_offset_min: 0.10
|
||
post_grasp_offset_max: 0.15
|
||
-
|
||
name: heuristic__skill
|
||
mode: home
|
||
gripper_state: 1.0
|
||
```
|
||
|
||
**Skill 名称注意**：使用 `register_skill` 装饰器注册的名称（类名转 snake_case），例如：
|
||
- `Pick` → `pick`
|
||
- `Heuristic_Skill` → `heuristic__skill`（双下划线）
|
||
- `Goto_Pose` → `goto__pose`（双下划线）
|
||
|
||
### Step 6: 创建 Pipeline 配置
|
||
|
||
文件：`configs/simbox/de_pick_test_tube.yaml`
|
||
|
||
```yaml
|
||
name: simbox_pick_test_tube
|
||
load_stage:
|
||
scene_loader:
|
||
type: env_loader
|
||
args:
|
||
workflow_type: SimBoxDualWorkFlow
|
||
cfg_path: workflows/simbox/core/configs/tasks/example/pick_test_tube.yaml
|
||
simulator:
|
||
physics_dt: 1/30
|
||
rendering_dt: 1/30
|
||
stage_units_in_meters: 1.0
|
||
headless: False # 调试时用 False（GUI），生产时改 True
|
||
renderer: "RayTracedLighting"
|
||
anti_aliasing: 0
|
||
layout_random_generator:
|
||
type: env_randomizer
|
||
args:
|
||
random_num: 1 # 调试时用 1，生产时增大
|
||
strict_mode: true
|
||
plan_stage:
|
||
seq_planner:
|
||
type: env_planner
|
||
render_stage:
|
||
renderer:
|
||
type: env_renderer
|
||
store_stage:
|
||
writer:
|
||
type: env_writer
|
||
args:
|
||
batch_async: true
|
||
output_dir: output/${name}/
|
||
```
|
||
|
||
### Step 7: 运行测试
|
||
|
||
```bash
|
||
conda activate banana500
|
||
|
||
# GUI 模式调试（headless: False）
|
||
python launcher.py --config configs/simbox/de_pick_test_tube.yaml
|
||
|
||
# 确认后改 headless: True，增大 random_num 批量生产
|
||
```
|
||
|
||
### Step 8: 检查输出
|
||
|
||
输出目录：`output/simbox_pick_test_tube/`
|
||
|
||
```
|
||
output/simbox_pick_test_tube/
|
||
├── pick_test_tube/split_aloha/<task>/right/
|
||
│ ├── <timestamp>/
|
||
│ │ ├── images.rgb.head/
|
||
│ │ ├── images.rgb.hand_right/
|
||
│ │ ├── images.rgb.hand_left/
|
||
│ │ └── lmdb/
|
||
│ └── ...
|
||
└── de_config.yaml
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### Q: `gen_sparse_label.py` 报 `_PyFloat_Pack8` 错误
|
||
A: pyarmor 加密对 Python 版本敏感，使用 `banana450` 环境（Python 3.10 + 旧版依赖）。
|
||
|
||
### Q: USD 打开后材质丢失
|
||
A: 引用子节点时材质路径超出引用范围。需要用 `fix_test_tube_materials.py` 重新绑定。
|
||
|
||
### Q: `RigidContactView` 报 `sensor_count` 错误
|
||
A: USD 结构不对。确保 `/World` (defaultPrim) 没有 `PhysicsRigidBodyAPI`，物理属性只在 `/World/Aligned` 子节点上。
|
||
|
||
### Q: OBJ 导出后 grasp 生成为空（0 条）
|
||
A: OBJ 文件包含非三角形面。使用 `migrate/usdc_to_obj.py` 导出时会自动三角化。
|
||
|
||
### Q: Plan 不收敛
|
||
A: 检查 grasp 标注质量（用 `vis_grasp.py` 可视化），确认姿态合理。调整 `filter_y_dir` / `filter_z_dir` 放宽过滤条件。
|
||
|
||
## 工具脚本一览
|
||
|
||
| 脚本 | 用途 |
|
||
|------|------|
|
||
| `migrate/usdc_to_obj.py` | USDC → 三角化 OBJ |
|
||
| `migrate/repackage_test_tube.py` | 重构 USD 层级结构 |
|
||
| `migrate/fix_test_tube_materials.py` | 修复材质绑定 |
|
||
| `workflows/simbox/tools/grasp/gen_sparse_label.py` | 生成 grasp 标注（需 banana450） |
|
||
| `workflows/simbox/tools/grasp/vis_grasp.py` | 可视化 grasp 标注 |
|