data-collection-sim

数据采集仿真

用途

通过 Replicator writers 在无头批处理中生成带标注的静态场景合成数据（RGB、深度、分割、位姿、Kitti/COCO 变体）。

先决条件

• 已构建 Isaac Sim（$ISAAC_SIM_DIR 或 _build/linux-x86_64/release）。
• 配备当前驱动程序的 NVIDIA GPU（nvidia-smi）。
• isaac-sim-orchestrator 的 Shell 环境变量约定：$ISAAC_SIM_DIR、$ISAAC_LAB_DIR、$WORKSPACE_DIR。

限制

• 适用于 Isaac Sim 6 / Kit 110，除非某一节另有说明。
• 无法替代 NVIDIA 官方文档来处理不受支持的边缘情况。

故障排除

错误 / 现象	原因	解决方案
找不到扩展或导入失败	$ISAAC_SIM_DIR 错误或构建已过期	将环境变量指向 _build/linux-x86_64/release，或重新构建
画面全黑或为空	缺少灯光，或渲染模式不是 RTX	添加穹顶灯 / 主光；确认 RTX / PathTracing 设置
加载场景或首次渲染时卡住	MDL 编译或场景过大	按照 isaac-sim-troubleshooting 中的隔离步骤操作

使用 Isaac Sim 6.0 Replicator 构建无头 SDG 流水线。通过 writers 将带标注的帧（RGB、深度、分割、bbox、位姿）输出到磁盘。

可用脚本

脚本	用途	参数
scripts/minimal_sdg_pipeline.py	使用 Isaac Sim Replicator 的最简静态场景 SDG 流水线	参见脚本 --help
scripts/shelf_pose_grid_capture.py	用于静态场景 SDG 的货架位姿网格采集	通过 argparse 传入 CLI 标志（参见脚本 --help）
scripts/validate_sdg_output.sh	验证 SDG 输出	按脚本头部说明传入位置参数（参见脚本）
scripts/warehouse_sdg.py	仓库 SDG	通过 argparse 传入 CLI 标志（参见脚本 --help）

运行脚本

在提供技能执行助手的 Agent 运行时中，使用 run_script() 调用助手：

run_script("scripts/minimal_sdg_pipeline.py", args=["--help"])

在已构建的 Isaac Sim 目录中，从 _build/*/release 使用 ./python.sh（Linux）或 python.bat（Windows）运行同一文件；对于不需要仿真器的 Shell 助手，也可以直接执行。

相关技能

• mobility-gen — 先记录移动机器人轨迹，再回放并渲染（分两个阶段，使用机器人搭载的传感器）
• isaac-sim-sensor — 传感器基元（相机、LiDAR、IMU、接触）
• occupancy-map — 生成用于放置生成点的占据地图

架构

Config (YAML/JSON) → SimulationApp (headless) → Scene Setup → Randomizers → Capture Loop → Writer → Disk

必需的导入

from isaacsim import SimulationApp
simulation_app = SimulationApp({"renderer": "RealTimePathTracing", "headless": True})

import carb.settings
import omni.replicator.core as rep
import omni.usd
import isaacsim.core.experimental.utils.stage as stage_utils
from isaacsim.core.experimental.utils.semantics import add_labels, remove_all_labels
from isaacsim.storage.native import get_assets_root_path

stage_utils.open_stage() / stage_utils.add_reference_to_stage() / stage_utils.define_prim() / stage_utils.get_current_stage() 是 Kit 110 中用于替代旧版 isaacsim.core.utils.stage.* 和 isaacsim.core.utils.prims.create_prim 流程的接口。SDG 基元仍使用 omni.replicator.core。

**迁移：**有关完整的 omni.isaac.* → isaacsim.* 映射，请参见 扩展重命名。

Writers

通过 rep.WriterRegistry.get(name)（或 rep.writers.get(name)，二者使用同一注册表）解析 Writer。

omni.replicator.core 内置 Writer（omni.replicator.core/scripts/writers_default/）：

Writer	用途
BasicWriter	RGB、bbox_2d（紧密/宽松）、bbox_3d、语义/实例/instance_id 分割、深度（图像平面/相机）、法线、遮挡、运动向量、相机参数、点云、骨架
KittiWriter	KITTI 格式数据集
CocoWriter	COCO 格式数据集（实例/bbox）
CosmosWriter	Cosmos 仓库视频片段（PNG 序列，以及每种模态对应的 MP4：rgb、shaded_seg、segmentation、depth、edges）。需要 /app/omni.graph.scriptnode/opt_in = True
FPSWriter	帧率/采集时间遥测数据
自定义 Writer 子类	直接访问 annotator 张量（继承 omni.replicator.core.Writer，并通过 rep.writers.register_writer 注册）

isaacsim.replicator.writers 添加了 Isaac 专用 Writer：

Writer	用途
PoseWriter	6-DoF 物体姿态估计（可选 write_debug_images=True）
DataVisualizationWriter	调试/叠加可视化

已弃用，不适用于新项目：DOPEWriter、YCBVideoWriter、PytorchWriter、PytorchListener（以及 OgnPose 节点）。它们将在未来的主版本中移除。

Writer 初始化模式

支持两种等效模式。近期示例（Isaac Sim 6.0+）倾向于使用显式 backend 的形式：

backend = rep.backends.get("DiskBackend")
backend.initialize(output_dir="/tmp/sdg_output")
writer = rep.writers.get("BasicWriter")
writer.initialize(backend=backend, rgb=True, bounding_box_2d_tight=True)
writer.attach(rp)

旧版简写形式（仍可使用；根据 output_dir 隐式创建 backend）：

writer = rep.WriterRegistry.get("BasicWriter")
writer.initialize(output_dir="/tmp/sdg_output", rgb=True, bounding_box_2d_tight=True)
writer.attach(rp)

Annotators

可通过 rep.annotators.get(name) 使用的核心 annotator：

• rgb — RGBA uint8
• distance_to_image_plane — 深度 float32
• semantic_segmentation — 逐像素类别标签
• instance_segmentation — 逐像素实例 ID
• bounding_box_2d_tight — 紧密 2D 边界框
• bounding_box_2d_loose — 宽松 2D 边界框
• bounding_box_3d — 世界坐标中的 3D 边界框
• camera_params — 内参、外参、分辨率
• occlusion — 每个实例的可见性比例
• normals — 表面法线
• pointcloud — 根据深度生成的 3D 点云

最简 Pipeline

run_minimal_sdg_pipeline(output_dir, num_frames, rt_subframes) — 打开仓库 stage，为道具添加语义标签，创建相机，附加 BasicWriter，并运行采集循环。

参见 scripts/minimal_sdg_pipeline.py。

完整仓库 Pipeline

如需使用配置驱动的无头仓库采集（YAML 配置、--num-frames、--output-dir），请参见 scripts/warehouse_sdg.py。使用 scripts/validate_sdg_output.sh 验证生成的数据集：

bash scripts/validate_sdg_output.sh <output_dir> [expected_frames]

域随机化

使用 rep.functional API 在每帧执行随机化：

# Scatter objects on surface
rep.functional.randomizer.scatter_2d(prims=objects, surface_prims=plane, check_for_collisions=True, rng=rng)

# Randomize camera pose
rep.functional.modify.pose(cam, position_value=rng.uniform(pos_min, pos_max),
                           look_at_value=target_prim, look_at_up_axis=(0, 0, 1))

# Randomize lights via OmniGraph events
rep.utils.send_og_event(event_name="randomize_lights")

无头执行

Isaac Sim 标准 Python 启动器为 python.sh（Windows 上使用 python.bat）。isaac-sim.sh 会启动完整的编辑器应用，不适合作为独立 SDG 脚本的入口。

# $ISAAC_SIM_DIR is either the install root or <repo>/_build/linux-x86_64/release
"$ISAAC_SIM_DIR/python.sh" "$WORKSPACE_DIR/data_collection.py" --config config.yaml

是否无头由脚本中的 SimulationApp({"headless": True}) 控制，而不是由启动器标志控制。

也可以通过 Isaac Lab runner 执行（$ISAAC_LAB_DIR 是你的 Isaac Lab 检出目录）：

"$ISAAC_LAB_DIR/isaaclab.sh" -p data_collection.py --config config.yaml

配置模式

使用 YAML 配置对所有内容进行参数化：

resolution: [1280, 720]
rt_subframes: 32
num_frames: 100
headless: true
env_url: "/Isaac/Environments/Simple_Warehouse/full_warehouse.usd"
writer: BasicWriter
output_dir: /tmp/sdg_output
annotations:
  rgb: true
  bounding_box_2d_tight: true
  semantic_segmentation: true
  distance_to_image_plane: true
  bounding_box_3d: true
objects:
  - url: "/Isaac/Props/YCB/Axis_Aligned/003_cracker_box.usd"
    label: cracker_box
    count: 5
  - url: "/Isaac/Props/YCB/Axis_Aligned/008_pudding_box.usd"
    label: pudding_box
    count: 3

验证清单

1. 输出目录包含预期数量的帧
2. RGB 图像非黑色（平均 RGB > 30）
3. 标注文件的数量与帧数一致
4. 分割图中包含语义标签
5. 边界框面积非零
6. 深度图中没有 NaN

关键规则

• 设置 rep.orchestrator.set_capture_on_play(False)，以手动控制步进。
• rt_subframes：多次渲染同一帧，以减少较大姿态变化造成的重影，并让材质／纹理趋于稳定。请根据渲染器进行调整：对于 RTX Real-Time + DLSS Quality，较小的值（4-8）通常就足够；对于路径追踪或材质流送量较大的场景，通常使用 16-32。
• DLSS Quality：carb.settings.get_settings().set("rtx/post/dlss/execMode", 2)。推荐用于 SDG；默认的 Performance 模式在低于约 600x600 的分辨率下可能产生边缘伪影。
• 使用 add_labels(...)（支持分类体系）或 rep.functional.modify.semantics(...) 为每个需要标注的 prim 添加标签。两者都会写入 UsdSemantics.LabelsAPI 架构。
• 对于静态场景 SDG，将 delta_time=0.0 传给 rep.orchestrator.step，这样时间轴就不会在采集之间前进。
• 清理前调用 rep.orchestrator.wait_until_complete()，确保后台后端已将所有内容写入磁盘。
• 使用 rng = np.random.default_rng(seed) 和 rep.set_global_seed(seed)，以实现可复现的随机化。
• 用于高吞吐量采集的性能调节项（参见 sdg_getting_started_05.py）：
  • rep.orchestrator.step(wait_for_render=False) 可将采集与渲染完成解耦。数据可能对应于上一帧；仅在不要求帧与数据严格对应时使用。
  • carb.settings.get_settings().set("/exts/omni.replicator.core/enableWriteToFabric", True) 会将随机化变化直接写入 Fabric，而不是先经过 USD。速度更快，但属于临时更改，不会保留在 USD 场景中。

相关 SDG 工作流

工作流	模块／示例
移动机器人轨迹记录与回放	mobility-gen skill + isaacsim.replicator.mobility_gen
抓取数据集生成	isaacsim.replicator.grasping（GraspingManager、GraspPhase）— source/standalone_examples/api/isaacsim.replicator.grasping/grasping_workflow_sdg.py
回合记录与回放	isaacsim.replicator.episode_recorder
遥操作记录与回放	isaacsim.replicator.teleop
可复用的随机化行为脚本（附加到 prim，持久保存在 USD 中）	isaacsim.replicator.behavior
传感器基元（LiDAR、IMU、摄像头）	isaac-sim-sensor、isaac-camera
根据地图生成物体位置	occupancy-map

参考示例

相对于 $ISAAC_SIM_DIR（安装根目录；源码构建时为 <this-repo>）和 $ISAAC_LAB_DIR 的路径：

• API 示例：$ISAAC_SIM_DIR/source/standalone_examples/api/isaacsim.replicator.examples/sdg_getting_started_0[1-5].py、sdg_workflow_0[12].py、multi_camera.py、motion_blur_raytracing.py、motion_blur_pathtracing.py、cosmos_writer_simple.py、simready_assets_sdg.py、sdg_deformables.py、sdg_geomsubset.py、subscribers_and_events.py、custom_event_and_write.py、custom_fps_writer_annotator.py。
• 基于场景的 SDG：$ISAAC_SIM_DIR/source/standalone_examples/replicator/scene_based_sdg/
• 基于物体的 SDG：$ISAAC_SIM_DIR/source/standalone_examples/replicator/object_based_sdg/
• 增强流水线：$ISAAC_SIM_DIR/source/standalone_examples/replicator/augmentation/
• Cosmos 仓库写入器：$ISAAC_SIM_DIR/source/standalone_examples/replicator/cosmos_writer_warehouse.py
• Infinigen SDG：$ISAAC_SIM_DIR/source/standalone_examples/replicator/infinigen/
• 抓取 SDG：$ISAAC_SIM_DIR/source/standalone_examples/api/isaacsim.replicator.grasping/grasping_workflow_sdg.py
• Isaac Lab 模仿学习：$ISAAC_LAB_DIR/scripts/imitation_learning/