YAML: extensionclassExtensionConfig

扩展功能配置

通过 extension_cfg_dict 声明需要启用的扩展实例，键名即运行时访问该扩展的唯一标识。按声明顺序依次启用，data_collect 必须在 record/benchmark 之前。

源码fastsim/configs/extension_cfg.py

顶层字段 ExtensionBaseConfig：通用基础字段（所有扩展）DataCollectorConfig：观测采集 (stereotype: data_collect)RecorderConfig：录制与导出 (stereotype: record)ReplayConfig：轨迹回放 (stereotype: replay)ServerConfig：REST API 服务化 (stereotype: server)BenchmarkConfig：Episode 评估 (stereotype: benchmark)TeleopConfig：遥操作 (stereotype: teleop)PipelineConfig：批量作业 (stereotype: pipeline)SnapshotConfig：状态快照 (stereotype: snapshot)TaskExecutorConfig：任务执行器 (stereotype: task_executor)DomainRandomizationConfig：域随机化 (stereotype: domain_randomization)RosBridgeConfig：ROS 2 桥接 (stereotype: ros_bridge)配置示例

顶层字段1

字段	类型	必填	默认值	说明 / 约束
`extension_cfg_dict`	dict[str, ExtensionBaseConfig]	可选	`{}`	扩展配置字典，键名为实例名（同时是运行时检索的唯一标识），值为各扩展的配置对象 ⚠按键声明顺序依次启用；data_collect 须在 record 和 benchmark 之前声明

ExtensionBaseConfig：通用基础字段（所有扩展）

classExtensionBaseConfigfastsim/extensions/extension_cfg.py

字段	类型	必填	默认值	说明 / 约束
`stereotype`	string	必填	—	扩展类型标识（data_collect / record / replay / server / benchmark / teleop / pipeline / snapshot / task_executor / domain_randomization / ros_bridge）
`enable`	bool	可选	`true`	是否在仿真启动时自动调用 enable(sim)，设为 false 可延迟手动启用

DataCollectorConfig：观测采集 (stereotype: data_collect)

按配置注册多个 observer，每个 observer 负责从场景中采集特定类型的数据。观测结果供 record / benchmark 扩展使用。

classDataCollectorConfigstereotypedata_collectfastsim/extensions/data_collect/data_collector_cfg.py

字段	类型	必填	默认值	说明 / 约束
`observer_cfgs`	list[ObserverConfig]	可选	`[]`	要注册的 observer 列表，每项通过 stereotype 指定采集类型

classRobotObserverConfigstereotyperobot_observerfastsim/extensions/data_collect/observer_cfg.py

字段	类型	必填	默认值	说明 / 约束
`stereotype`	string	必填	—	"robot_observer"
`name`	string	必填	—	机器人实例名（对应 scene.robot_cfg_dict 中的 key）
`target_joint_names`	list[str]	可选	`[]`	需要观测的关节名称列表
`target_link_names`	list[str]	可选	`[]`	需要观测的 link 名称列表
`observe_joint_positions`	bool	可选	`false`	采集各关节位置
`observe_position`	bool	可选	`false`	采集机器人位置
`observe_rotation`	bool	可选	`false`	采集机器人旋转
`observe_joint_velocities`	bool	可选	`false`	采集关节速度
`observe_joint_accelerations`	bool	可选	`false`	采集关节加速度
`observe_joint_position_targets`	bool	可选	`false`	采集关节目标位置
`observe_joint_velocity_targets`	bool	可选	`false`	采集关节目标速度
`observe_link_pose`	bool	可选	`false`	采集 link 位姿
`observe_ee_pose`	bool	可选	`false`	采集末端执行器位姿
`observe_ee_arm_names`	list[str]	可选	`[]`	需要采集 EE 的机械臂名称列表（ModularRobot），空则全部
`observe_ee_state`	bool	可选	`false`	采集每臂 EE 状态
`observe_arm_states`	bool	可选	`false`	采集每臂关节状态
`observe_module_summary`	bool	可选	`false`	采集模块结构摘要

classSensorObserverConfigstereotypesensor_observerfastsim/extensions/data_collect/observer_cfg.py

字段	类型	必填	默认值	说明 / 约束
`stereotype`	string	必填	—	"sensor_observer"
`name`	string	必填	—	传感器实例名（对应 scene.sensor_cfg_dict 中的 key）
`image_save_format`	enum	可选	`jpeg`	图像保存格式 ⚠jpeg / png / npy
`observe_intrinsic_matrix`	bool	可选	`false`	采集相机内参矩阵
`observe_extrinsic_matrix`	bool	可选	`false`	采集相机外参矩阵
`observe_rgb`	bool	可选	`false`	采集 RGB 图像
`observe_depth`	bool	可选	`false`	采集深度图
`observe_depth_npy`	bool	可选	`true`	额外保存原始深度为 .npy（float32 米）
`observe_normals`	bool	可选	`false`	采集法线图
`observe_semantic_segmentation`	bool	可选	`false`	采集语义分割图
`observe_instance_segmentation`	bool	可选	`false`	采集实例分割图

classObjectObserverConfigstereotypeobject_observerfastsim/extensions/data_collect/observer_cfg.py

字段	类型	必填	默认值	说明 / 约束
`stereotype`	string	必填	—	"object_observer"
`name`	string	必填	—	物体实例名（对应 scene.object_cfg_dict 中的 key）
`observe_position`	bool	可选	`false`	采集物体位置
`observe_rotation`	bool	可选	`false`	采集物体旋转
`observe_scale`	bool	可选	`false`	采集物体缩放比例
`target_joint_names`	list[str]	可选	`[]`	需要观测的关节名称列表（关节体适用）
`observe_joint_positions`	bool	可选	`false`	采集关节位置
`observe_joint_velocities`	bool	可选	`false`	采集关节速度
`observe_joint_accelerations`	bool	可选	`false`	采集关节加速度
`observe_joint_target_positions`	bool	可选	`false`	采集关节目标位置
`observe_joint_target_velocities`	bool	可选	`false`	采集关节目标速度

classTaskObserverConfigstereotypetask_observerfastsim/extensions/data_collect/observer_cfg.py

字段	类型	必填	默认值	说明 / 约束
`stereotype`	string	必填	—	"task_observer"
`name`	string	必填	—	任务实例名

RecorderConfig：录制与导出 (stereotype: record)

依赖 data_collect 扩展，将每帧 Observation 异步写入文件系统，仿真终止时执行后处理（生成 HDF5、视频等）。

classRecorderConfigstereotyperecordfastsim/extensions/record/recorder_cfg.py

字段	类型	必填	默认值	说明 / 约束
`backend_root_path`	string	必填	—	录制文件写入根目录（支持 root_key:// 路径）
`record_backend`	string	可选	`lfs`	存储后端类型
`record_fps`	int	可选	`30`	录制帧率（帧节流依据）
`postprocess_list`	list[str]	可选	`[]`	终止后执行的后处理类型 ⚠hdf5 / video / preview_video / npy_to_npz
`use_recorder_step`	bool	可选	`true`	使用 recorder 自己的步进计数，而非全局仿真步
`record_scene`	bool	可选	`true`	是否将当前场景配置导出为 scene.yaml（与录制数据放在同一目录，便于回放时无需原始配置即可恢复场景）
`scene_filename`	string	可选	`scene.yaml`	导出场景配置的文件名（相对于 backend_root_path）
`data_collector_name`	string	可选	`data_collect`	DataCollector 扩展实例名（须与 extension_cfg_dict 中的键名一致）
`record_observer_names`	list[str]	可选	`[]`	限定录制的 observer 名称，空则录制全部
`record_task_summary`	bool	可选	`false`	终止时导出 task_summary.json

ReplayConfig：轨迹回放 (stereotype: replay)

从 record.h5 读取录制轨迹，在仿真中驱动实体按轨迹运动，用于可视化验证或生成对比视频。可附加额外相机（ReplayCameraConfig）进行多视角录制。

classReplayConfigstereotypereplayfastsim/extensions/replay/replay_cfg.py

字段	类型	必填	默认值	说明 / 约束
`replay_cameras`	list[ReplayCameraConfig]	可选	`[]`	回放附加相机列表，见 ReplayCameraConfig
`hdf5_path`	string	必填	—	record.h5 文件路径（支持 root_key:// 路径）
`spawnable_names`	list[str]	可选	`[]`	限定加载的实体名称，空则加载全部
`scene_cfg_path`	string	可选	—	回放时使用的场景配置文件路径
`terminate_sim_when_finished`	bool	可选	`true`	回放完成后是否终止仿真
`skip_rollback`	bool	可选	`false`	是否跳过被回退的帧段，使回放视觉上保持连续（读取 hdf5 根属性中的 dead_segments）
`fps`	int	可选	`30`	回放帧率

classReplayCameraConfigfastsim/extensions/replay/replay_cfg.py

字段	类型	必填	默认值	说明 / 约束
`width`	int	必填	—	图像宽度（像素）
`height`	int	必填	—	图像高度（像素）
`position`	list[3]	必填	—	相机位置 [x, y, z]（米）
`rotation`	list[4]	必填	—	相机旋转，四元数 [w, x, y, z]
`data_types`	list[str]	可选	`["rgb"]`	采集数据类型（与 CameraConfig 相同）

ServerConfig：REST API 服务化 (stereotype: server)

启动 Flask HTTP 服务，将所有标注 @apiclass 的控制器方法自动注册为 POST /{class}/{method} 路由。

classServerConfigstereotypeserverfastsim/extensions/servitize/server_cfg.py

字段	类型	必填	默认值	说明 / 约束
`host`	string	可选	`0.0.0.0`	监听地址
`port`	int	必填	`5000`	监听端口 ⚠1024–65535
`debug`	bool	可选	`false`	Flask debug 模式（生产环境请关闭）

BenchmarkConfig：Episode 评估 (stereotype: benchmark)

在独立控制线程中以 episode 为单位循环运行用户自定义策略，每个 episode 结束后评估 goal 条件，输出成功率等统计指标。策略类需继承 Policy 并实现规定接口。

classBenchmarkConfigstereotypebenchmarkfastsim/extensions/benchmark/benchmark_cfg.py

字段	类型	必填	默认值	说明 / 约束
`required_observer_names`	list[str]	可选	`null`	benchmark 运行所需的 observer 名称列表，null 则不检查
`data_collector_name`	string	必填	`data_collect`	DataCollector 扩展实例名
`goals`	list[GoalConfig]	必填	`[]`	每个 episode 结束后评估的目标条件集合
`policy`	PolicyConfig	必填	—	策略配置，stereotype 指定用户自定义策略类型
`timeout`	float \| null	可选	`null`	benchmark 超时时间（秒），null 则不超时
`action_frequency`	float	必填	`60.0`	策略控制频率（Hz）
`stop_sim_on_end`	bool	必填	`true`	benchmark 完成后是否终止仿真
`result_output_path`	string	可选	`""`	benchmark 结果 JSON 输出路径（支持 asset:// / output:// / demo:// 协议），空字符串则不写入

classPolicyConfigfastsim/extensions/benchmark/policy.py

字段	类型	必填	默认值	说明 / 约束
`stereotype`	string	必填	—	策略类型，与 @stereotype.register_config 注册的 key 对应
`...`	any	可选	—	用户在自定义 PolicyConfig 子类中定义的任意字段，由 @configclass 解析

TeleopConfig：遥操作 (stereotype: teleop)

启用遥操作设备驱动，支持多种输入设备：keyboard、spacemouse、web、gello、vr。

classTeleopConfigstereotypeteleopfastsim/extensions/teleop/teleop_cfg.py

字段	类型	必填	默认值	说明 / 约束
`drivers`	list[TeleopDriverConfig]	必填	—	遥操作驱动列表，每项通过 stereotype 指定驱动类型，见 TeleopDriverConfig
`control_frequency`	float	可选	`30.0`	控制频率（Hz）

classTeleopDriverConfigfastsim/extensions/teleop/teleop_cfg.py

字段	类型	必填	默认值	说明 / 约束
`stereotype`	string	必填	—	驱动类型 ⚠keyboard / spacemouse / web / gello / vr
`target`	TeleopTargetConfig	必填	—	遥操作目标配置，见 TeleopTargetConfig

classTeleopTargetConfigfastsim/extensions/teleop/teleop_cfg.py

字段	类型	必填	默认值	说明 / 约束
`robot_name`	string	必填	—	目标机器人实例名
`arm_name`	string	可选	—	目标机械臂名称（ModularRobot 时需指定）

PipelineConfig：批量作业 (stereotype: pipeline)

以 pipeline 模式运行多个 episode，每个 episode 自动 reset 场景并执行任务/策略，适合批量数据采集和自动化测试。

classPipelineConfigstereotypepipelinefastsim/extensions/pipeline/pipeline_cfg.py

字段	类型	必填	默认值	说明 / 约束
`job_list_file`	string	必填	—	作业列表 JSON 文件路径（映射 job_name → config_path）
`stop_on_failure`	bool	可选	`false`	某个作业失败时是否停止整个 pipeline
`skip_postprocess_on_failure`	bool	可选	`false`	作业失败时是否跳过后处理
`reload_base`	bool	可选	`true`	作业切换时是否重建地基。false 则保留前一作业的 Base，仅更新布局（用于热切换场景）
`reload_objects`	bool	可选	`true`	作业切换时是否重建物体。false 则只对同名物体重新摆位
`reload_robots`	bool	可选	`true`	作业切换时是否重建机器人。false 则保留机器人和规划器（避免规划器初始化开销），仅重新摆位与初始化关节

SnapshotConfig：状态快照 (stereotype: snapshot)

提供仿真状态的快照保存与恢复功能，支持内存快照和 .npz 文件持久化，便于调试和回溯。

classSnapshotConfigstereotypesnapshotfastsim/extensions/snapshot/snapshot_cfg.py

字段	类型	必填	默认值	说明 / 约束
`snapshot_path`	string	必填	—	快照 .npz 文件路径
`target_entities`	list[str]	可选	`[]`	需要快照的实体名称列表，空则包含全部

TaskExecutorConfig：任务执行器 (stereotype: task_executor)

在独立控制线程中执行 task 配置中声明的 action 序列，执行完成后评估 goal 条件。支持交互式调试器，action 失败时进入 REPL。

classTaskExecutorConfigstereotypetask_executorfastsim/extensions/task_executor/task_executor_cfg.py

字段	类型	必填	默认值	说明 / 约束
`stop_sim_on_task_end`	bool	可选	`true`	任务完成后是否终止仿真
`assert_action_success`	bool	可选	`true`	动作目标未满足时是否视为失败
`interactive_debug`	bool	可选	`false`	动作执行失败时是否进入交互式调试器 REPL
`restore_snapshot_path`	string	可选	`null`	任务开始前恢复的快照文件路径
`restore_target_entities`	list[str]	可选	`[]`	快照恢复时的目标实体列表

DomainRandomizationConfig：域随机化 (stereotype: domain_randomization)

在每个 episode 的 reset 阶段对场景实体的物理属性、位姿、材质等进行随机化，用于提升策略的 sim-to-real 迁移能力。

classDomainRandomizationConfigstereotypedomain_randomizationfastsim/extensions/domain_randomization/domain_randomization_cfg.py

字段	类型	必填	默认值	说明 / 约束
`seed`	int	可选	`null`	随机种子，null 则不固定（用于可复现性）
`pose_randomizers`	list[PoseRandomizerConfig]	可选	`[]`	位姿随机化器列表，控制物体位置和旋转的随机范围
`physics_randomizers`	list[PhysicsRandomizerConfig]	可选	`[]`	物理属性随机化器列表（质量、摩擦系数等）
`lighting_randomizers`	list[LightingRandomizerConfig]	可选	`[]`	光照随机化器列表
`camera_randomizers`	list[CameraRandomizerConfig]	可选	`[]`	相机随机化器列表（位姿、内参扰动）
`material_randomizers`	list[MaterialRandomizerConfig]	可选	`[]`	材质随机化器列表。每项含 targets（spawnable 名或 USD prim 路径，支持 /* 通配子 prim）和 material_pool；material_pool 中每个材质既可合成式定义（color / roughness / metallic / diffuse_texture），也可引用外部材质文件（asset_path + source: local/remote/platform，支持 .usd / .usda / .usdc / .mdl）

RosBridgeConfig：ROS 2 桥接 (stereotype: ros_bridge)

将仿真器与 ROS 2 集成，自动发布观测数据到 ROS topic，并订阅外部控制指令。

classRosBridgeConfigstereotyperos_bridgefastsim/extensions/ros_bridge/ros_bridge_cfg.py

字段	类型	必填	默认值	说明 / 约束
`node_name`	string	必填	`fastsim_bridge`	ROS 2 节点名称
`namespace`	string	可选	`""`	ROS 2 节点命名空间
`domain_id`	int	必填	`0`	ROS_DOMAIN_ID ⚠0–232
`publish_fps`	int	必填	`30`	发布频率（Hz），0 则每仿真步发布
`topic_prefix`	string	必填	`/fastsim`	自动生成 topic 名称的前缀
`data_collector_name`	string	必填	`data_collect`	DataCollector 扩展实例名
`publish_observer_names`	list[str]	可选	`null`	限定发布的 observer 名称，null 则全部发布
`command_cfgs`	list[RosBridgeCommandConfig]	可选	`[]`	命令订阅配置列表

classRosBridgeCommandConfigfastsim/extensions/ros_bridge/ros_bridge_cfg.py

字段	类型	必填	默认值	说明 / 约束
`target_name`	string	必填	—	目标实体名称（如机器人名称）
`target_type`	string	必填	`robot`	实体类型 ⚠robot / object / sensor
`command_type`	string	必填	`joint_position`	命令类型 ⚠joint_position / ee_pose / gripper
`topic`	string	可选	`null`	自定义 topic 名称，null 则自动生成

配置示例

extension:
  extension_cfg_dict:
    my_data_collect:            # ← 键名即运行时实例名
      stereotype: data_collect
      enable: true
      observer_cfgs:
        - stereotype: robot_observer
          name: arm
          observe_joint_positions: true
          observe_ee_pose: true
        - stereotype: sensor_observer
          name: wrist_cam
          observe_rgb: true
          observe_depth: true

    record:
      stereotype: record
      enable: true
      backend_root_path: datasets://runs/run001
      record_fps: 30
      postprocess_list: [hdf5, video]
      data_collector_name: my_data_collect

    server:
      stereotype: server
      enable: false
      host: 0.0.0.0
      port: 8080
      debug: false

    teleop:
      stereotype: teleop
      enable: false
      control_frequency: 30.0
      drivers:
        - stereotype: keyboard
          target:
            robot_name: arm
            arm_name: main_arm

    task_runner:
      stereotype: task_executor
      enable: true
      stop_sim_on_task_end: true
      assert_action_success: true
      interactive_debug: false

    domain_rand:
      stereotype: domain_randomization
      enable: true
      seed: 42
      pose_randomizers:
        - target_names: [cube, bottle]
          position_range: [-0.1, 0.1, -0.1, 0.1, 0, 0]

← 上一个task