YAML: extensionclassExtensionConfig

Extension

Declares extension instances via extension_cfg_dict; the key name is the unique runtime identifier. Extensions are enabled in declaration order — data_collect must precede record/benchmark.

sourcefastsim/configs/extension_cfg.py

Top-level fields ExtensionBaseConfig: Common Fields (all extensions)DataCollectorConfig: Observation Collection (stereotype: data_collect)RecorderConfig: Recording & Export (stereotype: record)ReplayConfig: Trajectory Replay (stereotype: replay)ServerConfig: REST API Server (stereotype: server)BenchmarkConfig: Episode Evaluation (stereotype: benchmark)TeleopConfig: Teleoperation (stereotype: teleop)PipelineConfig: Batch Jobs (stereotype: pipeline)SnapshotConfig: State Snapshot (stereotype: snapshot)TaskExecutorConfig: Task Executor (stereotype: task_executor)DomainRandomizationConfig: Domain Randomization (stereotype: domain_randomization)RosBridgeConfig: ROS 2 Bridge (stereotype: ros_bridge)Example

Top-level Fields1

Field	Type	Required	Default	Description / Constraints
`extension_cfg_dict`	dict[str, ExtensionBaseConfig]	optional	`{}`	Extension config dict; key is instance name (also the unique runtime lookup key), value is the extension config object ⚠Enabled in declaration order; data_collect must be declared before record and benchmark

ExtensionBaseConfig: Common Fields (all extensions)

classExtensionBaseConfigfastsim/extensions/extension_cfg.py

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	Extension type (data_collect / record / replay / server / benchmark / teleop / pipeline / snapshot / task_executor / domain_randomization / ros_bridge)
`enable`	bool	optional	`true`	Whether to auto-call enable(sim) on simulation startup; set false to defer manual activation

DataCollectorConfig: Observation Collection (stereotype: data_collect)

Registers multiple observers, each collecting a specific data type from the scene. Observations are consumed by the record / benchmark extensions.

classDataCollectorConfigstereotypedata_collectfastsim/extensions/data_collect/data_collector_cfg.py

Field	Type	Required	Default	Description / Constraints
`observer_cfgs`	list[ObserverConfig]	optional	`[]`	List of observers to register; each typed by stereotype

classRobotObserverConfigstereotyperobot_observerfastsim/extensions/data_collect/observer_cfg.py

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"robot_observer"
`name`	string	required	—	Robot instance name (matches key in scene.robot_cfg_dict)
`target_joint_names`	list[str]	optional	`[]`	Joint names to observe
`target_link_names`	list[str]	optional	`[]`	Link names to observe
`observe_joint_positions`	bool	optional	`false`	Collect joint positions
`observe_position`	bool	optional	`false`	Collect robot position
`observe_rotation`	bool	optional	`false`	Collect robot rotation
`observe_joint_velocities`	bool	optional	`false`	Collect joint velocities
`observe_joint_accelerations`	bool	optional	`false`	Collect joint accelerations
`observe_joint_position_targets`	bool	optional	`false`	Collect joint position targets
`observe_joint_velocity_targets`	bool	optional	`false`	Collect joint velocity targets
`observe_link_pose`	bool	optional	`false`	Collect link pose
`observe_ee_pose`	bool	optional	`false`	Collect end-effector pose
`observe_ee_arm_names`	list[str]	optional	`[]`	Arm names for EE observation (ModularRobot); empty = all arms
`observe_ee_state`	bool	optional	`false`	Collect per-arm EE state
`observe_arm_states`	bool	optional	`false`	Collect per-arm joint state
`observe_module_summary`	bool	optional	`false`	Collect module structure summary

classSensorObserverConfigstereotypesensor_observerfastsim/extensions/data_collect/observer_cfg.py

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"sensor_observer"
`name`	string	required	—	Sensor instance name (matches key in scene.sensor_cfg_dict)
`image_save_format`	enum	optional	`jpeg`	Image save format ⚠jpeg / png / npy
`observe_intrinsic_matrix`	bool	optional	`false`	Collect camera intrinsic matrix
`observe_extrinsic_matrix`	bool	optional	`false`	Collect camera extrinsic matrix
`observe_rgb`	bool	optional	`false`	Collect RGB image
`observe_depth`	bool	optional	`false`	Collect depth map
`observe_depth_npy`	bool	optional	`true`	Additionally save raw depth as .npy (float32 meters)
`observe_normals`	bool	optional	`false`	Collect normals
`observe_semantic_segmentation`	bool	optional	`false`	Collect semantic segmentation
`observe_instance_segmentation`	bool	optional	`false`	Collect instance segmentation

classObjectObserverConfigstereotypeobject_observerfastsim/extensions/data_collect/observer_cfg.py

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"object_observer"
`name`	string	required	—	Object instance name (matches key in scene.object_cfg_dict)
`observe_position`	bool	optional	`false`	Collect object position
`observe_rotation`	bool	optional	`false`	Collect object rotation
`observe_scale`	bool	optional	`false`	Collect object scale
`target_joint_names`	list[str]	optional	`[]`	Joint names to observe (for articulated objects)
`observe_joint_positions`	bool	optional	`false`	Collect joint positions
`observe_joint_velocities`	bool	optional	`false`	Collect joint velocities
`observe_joint_accelerations`	bool	optional	`false`	Collect joint accelerations
`observe_joint_target_positions`	bool	optional	`false`	Collect joint target positions
`observe_joint_target_velocities`	bool	optional	`false`	Collect joint target velocities

classTaskObserverConfigstereotypetask_observerfastsim/extensions/data_collect/observer_cfg.py

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"task_observer"
`name`	string	required	—	Task instance name

RecorderConfig: Recording & Export (stereotype: record)

Depends on a data_collect extension; asynchronously writes per-frame observations to disk, then post-processes on termination (HDF5, video, etc.).

classRecorderConfigstereotyperecordfastsim/extensions/record/recorder_cfg.py

Field	Type	Required	Default	Description / Constraints
`backend_root_path`	string	required	—	Root directory for recording output (supports root_key:// paths)
`record_backend`	string	optional	`lfs`	Storage backend type
`record_fps`	int	optional	`30`	Recording frame rate (used for frame throttling)
`postprocess_list`	list[str]	optional	`[]`	Post-processing types to run on termination ⚠hdf5 / video / preview_video / npy_to_npz
`use_recorder_step`	bool	optional	`true`	Use the recorder's own step counter instead of the global simulation step
`record_scene`	bool	optional	`true`	Export current scene config as scene.yaml next to recording so replay can restore scene without original config
`scene_filename`	string	optional	`scene.yaml`	Filename for the exported scene config (relative to backend_root_path)
`data_collector_name`	string	optional	`data_collect`	DataCollector extension instance name (must match the key in extension_cfg_dict)
`record_observer_names`	list[str]	optional	`[]`	Observer names to record; empty = record all
`record_task_summary`	bool	optional	`false`	Export task_summary.json on termination

ReplayConfig: Trajectory Replay (stereotype: replay)

Reads a trajectory from record.h5 and drives entities in simulation to replay it. Additional cameras (ReplayCameraConfig) can be added for multi-angle recording.

classReplayConfigstereotypereplayfastsim/extensions/replay/replay_cfg.py

Field	Type	Required	Default	Description / Constraints
`replay_cameras`	list[ReplayCameraConfig]	optional	`[]`	Additional cameras for replay; see ReplayCameraConfig
`hdf5_path`	string	required	—	Path to record.h5 (supports root_key:// paths)
`spawnable_names`	list[str]	optional	`[]`	Entity names to load; empty = load all
`scene_cfg_path`	string	optional	—	Scene config file path to use during replay
`terminate_sim_when_finished`	bool	optional	`true`	Whether to terminate simulation when replay finishes
`skip_rollback`	bool	optional	`false`	Skip frames belonging to rolled-back segments so replay stays visually continuous (reads dead_segments from hdf5 root attrs)
`fps`	int	optional	`30`	Replay frame rate

classReplayCameraConfigfastsim/extensions/replay/replay_cfg.py

Field	Type	Required	Default	Description / Constraints
`width`	int	required	—	Image width in pixels
`height`	int	required	—	Image height in pixels
`position`	list[3]	required	—	Camera position [x, y, z] in meters
`rotation`	list[4]	required	—	Camera rotation as quaternion [w, x, y, z]
`data_types`	list[str]	optional	`["rgb"]`	Data types to collect (same as CameraConfig)

ServerConfig: REST API Server (stereotype: server)

Starts a Flask HTTP server, auto-registering all @apiclass-decorated controller methods as POST /{class}/{method} routes.

classServerConfigstereotypeserverfastsim/extensions/servitize/server_cfg.py

Field	Type	Required	Default	Description / Constraints
`host`	string	optional	`0.0.0.0`	Listen address
`port`	int	required	`5000`	Listen port ⚠1024–65535
`debug`	bool	optional	`false`	Flask debug mode (disable in production)

BenchmarkConfig: Episode Evaluation (stereotype: benchmark)

Runs user-defined policy evaluation in a separate thread per episode, assessing goal conditions and reporting success rate. Policy class must extend Policy and implement the required interface.

classBenchmarkConfigstereotypebenchmarkfastsim/extensions/benchmark/benchmark_cfg.py

Field	Type	Required	Default	Description / Constraints
`required_observer_names`	list[str]	optional	`null`	Observer names required for the benchmark to run; null skips check
`data_collector_name`	string	required	`data_collect`	DataCollector extension instance name
`goals`	list[GoalConfig]	required	`[]`	Goal conditions evaluated at the end of each episode
`policy`	PolicyConfig	required	—	Policy config; stereotype specifies the user-defined policy type
`timeout`	float \| null	optional	`null`	Benchmark timeout in seconds; null = no timeout
`action_frequency`	float	required	`60.0`	Policy control frequency in Hz
`stop_sim_on_end`	bool	required	`true`	Whether to terminate the simulation when the benchmark finishes
`result_output_path`	string	optional	`""`	Benchmark result JSON output path (supports asset:// / output:// / demo:// schemes); empty = do not write

classPolicyConfigfastsim/extensions/benchmark/policy.py

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	Policy type; must match the key registered with @stereotype.register_config
`...`	any	optional	—	Any additional fields defined in the user's PolicyConfig subclass, parsed by @configclass

TeleopConfig: Teleoperation (stereotype: teleop)

Enables teleoperation with various input devices: keyboard, spacemouse, web, gello, vr.

classTeleopConfigstereotypeteleopfastsim/extensions/teleop/teleop_cfg.py

Field	Type	Required	Default	Description / Constraints
`drivers`	list[TeleopDriverConfig]	required	—	List of teleop drivers; each typed by stereotype. See TeleopDriverConfig
`control_frequency`	float	optional	`30.0`	Control frequency in Hz

classTeleopDriverConfigfastsim/extensions/teleop/teleop_cfg.py

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	Driver type ⚠keyboard / spacemouse / web / gello / vr
`target`	TeleopTargetConfig	required	—	Teleop target configuration; see TeleopTargetConfig

classTeleopTargetConfigfastsim/extensions/teleop/teleop_cfg.py

Field	Type	Required	Default	Description / Constraints
`robot_name`	string	required	—	Target robot instance name
`arm_name`	string	optional	—	Target arm module name (required for ModularRobot)

PipelineConfig: Batch Jobs (stereotype: pipeline)

Runs multiple episodes in pipeline mode, auto-resetting the scene and executing tasks/policies per episode. Ideal for batch data collection and automated testing.

classPipelineConfigstereotypepipelinefastsim/extensions/pipeline/pipeline_cfg.py

Field	Type	Required	Default	Description / Constraints
`job_list_file`	string	required	—	Job list JSON file path mapping job_name → config_path
`stop_on_failure`	bool	optional	`false`	Whether to stop the entire pipeline when a job fails
`skip_postprocess_on_failure`	bool	optional	`false`	Whether to skip post-processing when a job fails
`reload_base`	bool	optional	`true`	Whether to rebuild the base when switching jobs. false = keep prior base, only update layout (hot-swap)
`reload_objects`	bool	optional	`true`	Whether to rebuild objects when switching jobs. false = only re-pose same-named objects
`reload_robots`	bool	optional	`true`	Whether to rebuild robots when switching jobs. false = keep robot and planner (skip planner warmup), only re-pose and re-init joints

SnapshotConfig: State Snapshot (stereotype: snapshot)

Provides simulation state snapshot save/restore, supporting in-memory snapshots and .npz file persistence for debugging and rollback.

classSnapshotConfigstereotypesnapshotfastsim/extensions/snapshot/snapshot_cfg.py

Field	Type	Required	Default	Description / Constraints
`snapshot_path`	string	required	—	Snapshot .npz file path
`target_entities`	list[str]	optional	`[]`	Entity names to snapshot; empty = all entities

TaskExecutorConfig: Task Executor (stereotype: task_executor)

Executes the action sequence declared in the task config in a separate control thread, then evaluates goal conditions. Supports an interactive debugger that enters a REPL on action failure.

classTaskExecutorConfigstereotypetask_executorfastsim/extensions/task_executor/task_executor_cfg.py

Field	Type	Required	Default	Description / Constraints
`stop_sim_on_task_end`	bool	optional	`true`	Whether to terminate simulation after task completion
`assert_action_success`	bool	optional	`true`	Whether to fail if action goals are not met
`interactive_debug`	bool	optional	`false`	Whether to enter interactive debugger REPL on action failure
`restore_snapshot_path`	string	optional	`null`	Snapshot file path to restore before task execution
`restore_target_entities`	list[str]	optional	`[]`	Target entity names for snapshot restore

DomainRandomizationConfig: Domain Randomization (stereotype: domain_randomization)

Randomizes physics properties, poses, and materials of scene entities during each episode reset to improve sim-to-real transfer.

classDomainRandomizationConfigstereotypedomain_randomizationfastsim/extensions/domain_randomization/domain_randomization_cfg.py

Field	Type	Required	Default	Description / Constraints
`seed`	int	optional	`null`	Random seed; null = non-deterministic (for reproducibility)
`pose_randomizers`	list[PoseRandomizerConfig]	optional	`[]`	List of pose randomizers controlling object position/rotation ranges
`physics_randomizers`	list[PhysicsRandomizerConfig]	optional	`[]`	List of physics randomizers (mass, friction, etc.)
`lighting_randomizers`	list[LightingRandomizerConfig]	optional	`[]`	List of lighting randomizers
`camera_randomizers`	list[CameraRandomizerConfig]	optional	`[]`	List of camera randomizers (pose, intrinsics perturbation)
`material_randomizers`	list[MaterialRandomizerConfig]	optional	`[]`	List of material randomizers. Each entry has targets (spawnable name or USD prim path, /* wildcard binds children) and material_pool. Each material can be either synthesized (color / roughness / metallic / diffuse_texture) or referenced from an external file (asset_path + source: local/remote/platform; supports .usd / .usda / .usdc / .mdl)

RosBridgeConfig: ROS 2 Bridge (stereotype: ros_bridge)

Integrates the simulator with ROS 2, auto-publishing observations to topics and subscribing to external control commands.

classRosBridgeConfigstereotyperos_bridgefastsim/extensions/ros_bridge/ros_bridge_cfg.py

Field	Type	Required	Default	Description / Constraints
`node_name`	string	required	`fastsim_bridge`	ROS 2 node name
`namespace`	string	optional	`""`	ROS 2 node namespace
`domain_id`	int	required	`0`	ROS_DOMAIN_ID ⚠0–232
`publish_fps`	int	required	`30`	Publishing rate in Hz; 0 = every simulation step
`topic_prefix`	string	required	`/fastsim`	Prefix for all auto-generated topic names
`data_collector_name`	string	required	`data_collect`	DataCollector extension instance name
`publish_observer_names`	list[str]	optional	`null`	Observer names to publish; null = publish all
`command_cfgs`	list[RosBridgeCommandConfig]	optional	`[]`	List of command subscription configurations

classRosBridgeCommandConfigfastsim/extensions/ros_bridge/ros_bridge_cfg.py

Field	Type	Required	Default	Description / Constraints
`target_name`	string	required	—	Target entity name (e.g. robot name)
`target_type`	string	required	`robot`	Entity type ⚠robot / object / sensor
`command_type`	string	required	`joint_position`	Command type ⚠joint_position / ee_pose / gripper
`topic`	string	optional	`null`	Custom topic name; null = auto-generated

Example

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]

← Prevtask