YAML: sceneclassSceneConfig

Scene

Declaratively describes the simulation world: base environment, robots, objects, sensors, and lights. SceneManager instantiates and injects all entities at runtime.

sourcefastsim/configs/scene_cfg.py

Top-level fields BaseConfig: Ground & Environment (base_config)ObjectConfig: Scene Objects (object_cfg_dict)RobotConfig: Robot (robot_cfg_dict)SensorConfig: Sensor (sensor_cfg_dict)LightConfig: Light (light_cfg_dict)Example

Top-level Fields8

Field	Type	Required	Default	Description / Constraints
`name`	string	optional	—	Scene name
`position`	list[3]	optional	`[0.0, 0.0, 0.0]`	Scene base position [x, y, z] in meters
`rotation`	list[4]	optional	`[1.0, 0.0, 0.0, 0.0]`	Scene base rotation as quaternion [w, x, y, z] ⚠Must be a unit quaternion: w²+x²+y²+z²=1
`base_config`	BaseConfig	optional	—	Ground / environment config; type selected via the stereotype field
`robot_cfg_dict`	dict[str, RobotConfig]	optional	`{}`	Robot config dict; key is instance name, accessed via SceneManager.get_robot(name)
`object_cfg_dict`	dict[str, ObjectConfig]	optional	`{}`	Scene object config dict; key is instance name
`sensor_cfg_dict`	dict[str, SensorConfig]	optional	`{}`	Sensor config dict; key is instance name
`light_cfg_dict`	dict[str, LightConfig]	optional	`{}`	Light source config dict; key is instance name

BaseConfig: Ground & Environment (base_config)

Each scene has exactly one Base that defines the physics ground or loads a full environment USD. The concrete subclass is selected by stereotype.

classGroundPlaneBaseConfigstereotypeground_planeextendsBaseConfig, SpawnableConfigfastsim/unisim/bases/models/ground_plane_base.py

Field	Type	Required	Default	Description / Constraints
`ground_plane_size`	list[2]	optional	`[10.0, 10.0]`	Ground visual size [x, y] in meters; physics extends infinitely ⚠Each value must be > 0

Inherited fromSpawnableConfig5

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"ground_plane"
`name`	string	required	—	Entity name ⚠1-100 chars, no / or \
`prim_path`	string	optional	—	USD prim path ⚠Must start with /
`position`	list[3]	optional	`[0.0, 0.0, 0.0]`	Position [x, y, z] in meters
`rotation`	list[4]	optional	`[1.0, 0.0, 0.0, 0.0]`	Rotation (quaternion [w, x, y, z])

classUsdBaseConfigstereotypeusdextendsBaseConfig, SpawnableConfigfastsim/unisim/bases/models/usd_base.py

Field	Type	Required	Default	Description / Constraints
`asset_path`	string	required	—	Environment USD file path (supports root_key:// protocol)
`source`	string	required	`local`	Asset source ⚠local / remote

Inherited fromSpawnableConfig5

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"usd"
`name`	string	required	—	Entity name
`prim_path`	string	optional	—	USD prim path
`position`	list[3]	optional	`[0.0, 0.0, 0.0]`	Position [x, y, z]
`rotation`	list[4]	optional	`[1.0, 0.0, 0.0, 0.0]`	Rotation (quaternion)

classEmptyBaseConfigstereotypeemptyextendsBaseConfig, SpawnableConfigfastsim/unisim/bases/models/empty_base.py

Inherited fromSpawnableConfig4

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"empty" — for fully custom physics scenes
`name`	string	required	—	Entity name
`position`	list[3]	optional	`[0.0, 0.0, 0.0]`	Position
`rotation`	list[4]	optional	`[1.0, 0.0, 0.0, 0.0]`	Rotation

ObjectConfig: Scene Objects (object_cfg_dict)

classRigidObjectConfigstereotyperigidextendsObjectConfig, SpawnableConfigfastsim/unisim/objects/models/rigid_object.py

Field	Type	Required	Default	Description / Constraints
`mass`	float	required	`1.0`	Object mass in kg
`density`	float	required	`1000`	Object density in kg/m³
`disable_gravity`	bool	required	`false`	Whether to disable gravity
`kinematic_enabled`	bool	optional	`false`	Enable kinematic mode (not affected by forces)
`disable_rigid_body`	bool	optional	`false`	Disable rigid body properties
`enable_collision`	bool	required	`true`	Enable collision
`primitive_type`	enum	optional	—	Primitive shape type (when not using USD) ⚠box / sphere / cylinder / cone / disk
`primitive_radius`	float	optional	—	Primitive radius (sphere / cylinder / cone / disk)
`primitive_size`	list[3]	optional	—	Primitive size [x, y, z] (box)
`primitive_height`	float	optional	—	Primitive height (cylinder / cone)

Inherited fromObjectConfig4

Field	Type	Required	Default	Description / Constraints
`source`	string	required	`primitive`	Asset source ⚠local / remote / primitive
`asset_path`	string	optional	—	USD asset path (required when source is local/remote)
`scale`	list[3]	optional	`[1, 1, 1]`	Scale [x, y, z]
`axis_y_up`	bool	optional	`false`	Whether the asset uses Y-up axis

Inherited fromSpawnableConfig5

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"rigid"
`name`	string	required	—	Entity name
`prim_path`	string	optional	—	USD prim path
`position`	list[3]	optional	`[0.0, 0.0, 0.0]`	Position [x, y, z]
`rotation`	list[4]	optional	`[1.0, 0.0, 0.0, 0.0]`	Rotation (quaternion)

classArticulatedObjectConfigstereotypearticulatedextendsObjectConfig, ArticulationConfig, SpawnableConfigfastsim/unisim/objects/models/articulated_object.py

Inherited fromArticulationConfig3

Field	Type	Required	Default	Description / Constraints
`actuator_cfg_dict`	dict[str, ActuatorConfig]	required	`{}`	Actuator config dict (joint drive groups)
`init_joint_position`	dict[str, float]	optional	`{}`	Initial joint positions
`init_joint_velocity`	dict[str, float]	optional	`{}`	Initial joint velocities

Inherited fromObjectConfig3

Field	Type	Required	Default	Description / Constraints
`source`	string	required	`local`	Asset source ⚠local / remote
`asset_path`	string	required	—	USD asset path
`scale`	list[3]	optional	`[1, 1, 1]`	Scale

Inherited fromSpawnableConfig4

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"articulated"
`name`	string	required	—	Entity name
`position`	list[3]	optional	`[0.0, 0.0, 0.0]`	Position
`rotation`	list[4]	optional	`[1.0, 0.0, 0.0, 0.0]`	Rotation

classSoftObjectConfigstereotypesoftextendsObjectConfig, SpawnableConfigfastsim/unisim/objects/models/soft_object.py

Field	Type	Required	Default	Description / Constraints
`mass`	float	required	`0.1`	Total object mass in kg
`density`	float	required	`1000`	Object density in kg/m³
`youngs_modulus`	float	optional	`10000`	Young's modulus for volumetric soft body (Pa)
`poissons_ratio`	float	optional	`0.3`	Poisson's ratio, lateral-to-axial strain ratio ⚠Must be in [0, 0.5)
`damping`	float	optional	`0.01`	Global damping coefficient
`dynamic_friction`	float	optional	`0.5`	Dynamic friction coefficient
`static_friction`	float	optional	`0.5`	Static friction coefficient
`stretch_stiffness`	float	optional	`10000`	Stretch stiffness (N/m), cloth only
`shear_stiffness`	float	optional	`1000`	Shear stiffness (N/m), cloth only
`bending_stiffness`	float	optional	`10.0`	Bending stiffness (N·m), cloth only
`pressure`	float	optional	`0.0`	Internal pressure (Pa) for inflatable bodies; 0 disables
`soft_body_type`	enum	optional	`volumetric`	Soft-body model type hint for the simulator ⚠cloth / volumetric / inflatable
`simulation_hex_mesh`	bool	optional	`false`	Use hexahedral mesh for volumetric FEM; defaults to tetrahedral
`particle_contact_offset`	float	optional	`0.02`	Particle contact detection radius (meters)
`solver_position_iterations`	int	optional	`16`	Position-projection iterations per step ⚠>= 1
`enable_collision`	bool	required	`true`	Enable collision with other objects
`self_collision`	bool	optional	`false`	Enable self-collision within the soft body
`disable_gravity`	bool	optional	`false`	Disable gravity for the soft body

Inherited fromObjectConfig4

Field	Type	Required	Default	Description / Constraints
`source`	string	required	`primitive`	Asset source ⚠local / remote / primitive
`asset_path`	string	optional	—	USD asset path
`scale`	list[3]	optional	`[1, 1, 1]`	Scale
`axis_y_up`	bool	optional	`false`	Asset uses Y-up axis

Inherited fromSpawnableConfig5

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"soft"
`name`	string	required	—	Entity name
`prim_path`	string	optional	—	USD prim path
`position`	list[3]	optional	`[0.0, 0.0, 0.0]`	Position
`rotation`	list[4]	optional	`[1.0, 0.0, 0.0, 0.0]`	Rotation

RobotConfig: Robot (robot_cfg_dict)

PlannerConfig is a nested config extended by user-defined planner implementations; base robot fields are in RobotConfig, concrete subclass selected by stereotype.

classGeneralRobotConfigstereotypegeneral_robotextendsRobotConfig, ArticulationConfig, SpawnableConfigfastsim/unisim/robots/models/general_robot.py

Inherited fromRobotConfig4

Field	Type	Required	Default	Description / Constraints
`ee_link_name`	string	optional	—	End-effector link name
`ik_joint_names`	list[str]	optional	—	Joint names used for IK (defaults to all movable joints)
`use_planner`	bool	optional	`false`	Whether to attach a motion planner (e.g. Curobo)
`planner_cfg`	PlannerConfig	optional	—	Planner configuration, active when use_planner is true

Inherited fromArticulationConfig6

Field	Type	Required	Default	Description / Constraints
`asset_path`	string	required	—	Robot USD asset path
`source`	string	required	`local`	Asset source ⚠local / remote
`actuator_cfg_dict`	dict[str, ActuatorConfig]	required	`{}`	Actuator config dict
`init_joint_position`	dict[str, float]	optional	`{}`	Initial joint positions
`init_joint_velocity`	dict[str, float]	optional	`{}`	Initial joint velocities
`scale`	list[3]	optional	`[1, 1, 1]`	Scale

Inherited fromSpawnableConfig4

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"general_robot"
`name`	string	required	—	Entity name
`position`	list[3]	optional	`[0.0, 0.0, 0.0]`	Position
`rotation`	list[4]	optional	`[1.0, 0.0, 0.0, 0.0]`	Rotation

classSingleGripperArmRobotConfigstereotypesingle_gripper_arm_robotextendsRobotConfig, ArticulationConfig, SpawnableConfigfastsim/unisim/robots/models/single_gripper_arm_robot.py

Field	Type	Required	Default	Description / Constraints
`arm_actuator_name`	string	required	—	Arm actuator group name (must match the USD definition)
`gripper_actuator_name`	string	required	—	Gripper actuator group name

Inherited fromRobotConfig4

Field	Type	Required	Default	Description / Constraints
`ee_link_name`	string	optional	—	End-effector link name
`ik_joint_names`	list[str]	optional	—	Joint names for IK
`use_planner`	bool	optional	`false`	Attach a motion planner
`planner_cfg`	PlannerConfig	optional	—	Planner configuration

Inherited fromArticulationConfig6

Field	Type	Required	Default	Description / Constraints
`asset_path`	string	required	—	Robot USD asset path
`source`	string	required	`local`	Asset source
`actuator_cfg_dict`	dict[str, ActuatorConfig]	required	`{}`	Actuator config dict
`init_joint_position`	dict[str, float]	optional	`{}`	Initial joint positions
`init_joint_velocity`	dict[str, float]	optional	`{}`	Initial joint velocities
`scale`	list[3]	optional	`[1, 1, 1]`	Scale

Inherited fromSpawnableConfig4

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"single_gripper_arm_robot"
`name`	string	required	—	Entity name
`position`	list[3]	optional	`[0.0, 0.0, 0.0]`	Position
`rotation`	list[4]	optional	`[1.0, 0.0, 0.0, 0.0]`	Rotation

classPlannerConfigfastsim/configs/scene_cfg.py

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	Planner type (defined by the planner plugin being used)
`extra_parameters`	dict	optional	`{}`	Extra parameters interpreted by the specific planner implementation

SensorConfig: Sensor (sensor_cfg_dict)

classCameraConfigstereotypecameraextendsSensorConfig, SpawnableConfigfastsim/unisim/sensors/models/camera.py

Field	Type	Required	Default	Description / Constraints
`width`	int	required	—	Image width in pixels
`height`	int	required	—	Image height in pixels
`data_types`	list[str]	required	—	List of data types to collect ⚠rgb / depth / semantic_segmentation / instance_segmentation / normals
`clip_range`	list[2]	optional	—	Depth clip range [near, far] in meters
`attach_to`	AttachToConfig	optional	—	Attach configuration (mount to an entity or link)
`look_at`	LookAtConfig	optional	—	Look-at configuration (point toward a target or coordinate)
`convention`	enum	optional	`world`	Coordinate convention ⚠world / opengl / ros

Inherited fromSpawnableConfig5

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"camera"
`name`	string	required	—	Sensor name
`prim_path`	string	optional	—	USD prim path
`position`	list[3]	optional	`[0.0, 0.0, 0.0]`	Position [x, y, z]
`rotation`	list[4]	optional	`[1.0, 0.0, 0.0, 0.0]`	Rotation (quaternion)

LightConfig: Light (light_cfg_dict)

classGeneralLightConfigstereotypegeneral_lightextendsLightConfig, SpawnableConfigfastsim/unisim/lights/models/general_light.py

Field	Type	Required	Default	Description / Constraints
`light_type`	enum	required	—	Light type ⚠distant / sphere / disk
`intensity`	float	optional	`1.0`	Light intensity ⚠>= 0
`exposure`	float	optional	`0.0`	Exposure value
`color`	list[3]	optional	`[1.0, 1.0, 1.0]`	Color [r, g, b] in 0–1 range
`visible`	bool	optional	`true`	Whether the light mesh itself is visible in the render
`enable_color_temperature`	bool	optional	`false`	Enable color temperature (overrides color when enabled)
`color_temperature`	float	optional	`6500`	Color temperature in Kelvin
`normalize`	bool	optional	`false`	Whether to normalize light intensity
`radius`	float	optional	—	Light radius (sphere type) ⚠> 0
`angle`	float	optional	—	Light angle (distant type)
`texture_file`	string	optional	—	Texture file path

Inherited fromSpawnableConfig4

Field	Type	Required	Default	Description / Constraints
`stereotype`	string	required	—	"general_light"
`name`	string	required	—	Light name
`position`	list[3]	optional	`[0.0, 0.0, 0.0]`	Position
`rotation`	list[4]	optional	`[1.0, 0.0, 0.0, 0.0]`	Rotation

Example

scene:
  name: pick_and_place_scene
  position: [0.0, 0.0, 0.0]
  rotation: [1.0, 0.0, 0.0, 0.0]

  base_config:
    stereotype: ground_plane
    ground_plane_size: [10.0, 10.0]

  robot_cfg_dict:
    arm:
      stereotype: single_gripper_arm_robot
      asset_path: assets://robots/ur5_with_gripper.usd
      ee_link_name: tool0
      use_planner: true
      arm_actuator_name: arm
      gripper_actuator_name: gripper

  object_cfg_dict:
    cube:
      stereotype: rigid
      asset_path: assets://objects/cube_red.usd
      mass: 0.2
      enable_gravity: true
    cloth:
      stereotype: soft
      asset_path: assets://objects/cloth.usd
      soft_body_type: cloth
      mass: 0.05
      stretch_stiffness: 8000
      bending_stiffness: 5.0

  sensor_cfg_dict:
    wrist_cam:
      stereotype: camera
      width: 640
      height: 480
      data_types: [rgb, depth]
      attach_to: arm
      convention: ros

  light_cfg_dict:
    main_light:
      stereotype: general_light
      light_type: distant
      intensity: 3000
      color: [1.0, 1.0, 1.0]

← PrevsimulationNext →task