World Schema

The world schema looks as follows, where <angle brackets> are placeholders:

# General parameters
params:
   name: <world_name>
   inflation_radius: <value>  # Collision padding radius around rooms/hallways/locations
   object_radius: <value>  # Collision padding radius around objects
   wall_height: <value>  # Vertical (Z) height of walls, can override with individual entities

# Metadata
metadata:
   locations:
    - <path/to/location_data1_file.yaml>
    - <path/to/location_data2_file.yaml>
    - ...
    - <path/to/location_dataN_file.yaml>
   objects:
    - </path/to/object_data1_file.yaml>
    - </path/to/object_data2_file.yaml>
    - ...
    - </path/to/object_dataN_file.yaml>

# Robots: Each robot contains basic properties, plus other add-ons such as path planners and grasp generators
robots:
  - name: <name>
    radius: <value>  # Robot radius
    height: <value>  # Robot height
    location: <loc_name>  # Initial location
    pose:  # Initial pose, if not specified will sample
      position:
        x: <x>
        y: <y>
      rotation_eul:
        yaw: <yaw>
        angle_units: <units>  # Can be "radians" (default) or "degrees"
    initial_battery_level: 50.0
    # Dynamics limits
    max_linear_velocity: <value>
    max_angular_velocity: <value>
    max_linear_acceleration: <value>
    max_angular_acceleration: <value>
    # Specialized capabilities
    path_planner:  # Local robot path planner -- generally refers to single-query planners
      type: rrt  # Supported types -- astar, rrt, prm, world_graph
      <property>: <planner_property>
    path_executor:  # For following a path
      type: constant_velocity  # Supported types -- constant_velocity
      <property>: <path_executor_property>
    grasp_generator:  # For object grasp generation
      type: parallel_grasp  # Supported types -- parallel_grasp
      <property>: <grasp_generator_property>
    partial_observability: False  # If True, robot starts with no detected objects
    # Options to control the execution of actions
    action_execution_options:
      navigate:
        delay: 0.1
        success_probability: 0.9
        rng_seed: 42
        battery_usage: 1.0
      pick:
        delay: 1.0
        battery_usage: 5.0
      place:
        success_probability: 0.75
        battery_usage: 5.0
  - ...
  - ...

# Rooms
rooms:
  - name: <room_name>  # If not specified, will be automatic
    footprint:
      type: <footprint_type>
      <property>: <footprint_property>
    pose:  # If not specified, will use the room's centroid
      position:
        x: <x>
        y: <y>
      rotation_eul:
        yaw: <yaw>
    nav_poses:
      - [<x1>, <y1>, <z1>, <yaw1>]
      - ...
      - [<xN>, <yN>, <zN>, <yawN>]
    wall_width: <value>
    color: [<r>, <g>, <b>] or <"color_name"> or <"hexadecimalcode">
  - ...
  - ...

# Hallways
hallways:
  - room_start: <room1>
    room_end: <room2>
    width: <value>
    conn_method: <type>
    <conn_property>: <value>
    is_open: true  # Can only navigate through hallway if open
    is_locked: false  # Can only open and close if unlocked
  - ...
  - ...

# Locations
locations:
  - name: <loc_name>  # If not specified, will be automatic
    category: <loc_category>  # From location YAML file
    parent: <room_name>
    pose:  # If not specified, will sample
     position:
       x: <x>
       y: <y>
     rotation_eul:
       yaw: <yaw>
       angle_units: <units>  # Can be "radians" (default) or "degrees"
     relative_to: <room_name>  # If not specified, uses absolute pose
    is_open: true  # Can only pick, place, and detect if open
    is_locked: true  # Can only open and close if unlocked
    is_charger: false  # Robots can charge at this location
  - ...
  - ...

# Objects
objects:
  - name: <obj_name>  # If not specified, will be automatic
    category: <obj_category>  # From object YAML file
    parent: <loc_name>
    pose:  # If not specified, will sample
      position:
        x: <x>
        y: <y>
      rotation_quat:
        w: <w>
        x: <x>
        y: <y>
        z: <z>
      relative_to: <loc_name>  # If not specified, uses absolute pose

Specifying Poses

There are a few ways to specify poses in PyRoboSim YAML files: lists and dictionaries.

# Valid list formats
pose: [<x>, <y>]
pose: [<x>, <y>, <z>]
pose: [<x>, <y>, <z>, <yaw>]  # Angle units always in radians

If possible, you should use the dictionary format, as the list format is at this point only around for backward compatibility. Anything below this line is only supported in dictionary format.

Note that you can use both Euler angles and quaternions to specify poses. If specifying rotation using Euler angles, you can specify angle either in radians or degrees. Any unspecified values will default to 0.0.

# Euler angles in radians (default), fully specified
pose:
  position:
    x: 1.0
    y: 2.0
    z: 3.0
  rotation_eul:
    yaw: 0.1
    pitch: 0.2
    roll: 0.3

# Euler angles in degrees, partially specified
pose:
  position:
    x: 1.0
    y: 2.0
  rotation_eul:
    yaw: 45.0
    angle_units: "degrees"

# Quaternion
pose:
  position:
    x: 1.0
    y: 2.0
  rotation_quat:
    w: 0.707
    x: 0.0
    y: 0.0
    z: -0.707

You can also use the relative_to field when specifying poses. This makes it easier to specify poses relative to other entities in the world (rooms, locations, objects, etc.).

pose:
  position:
    x: 1.0
    y: 2.0
  rotation_eul:
    yaw: 45.0
    angle_units: "degrees"
  relative_to: "table0"