Scenarios

When you call biguasim.make() to create an environment, you pass in the name of a scenario, eg. biguasim.make("Pier-Hover-"). A scenario tells BiguaSim:

  • Which world to load

  • What agents are present

  • Where they are

  • What sensors they have

BiguaSim worlds are meant to be configurable by changing out the scenario. Scenarios allow the same world to be used for different purposes. For different senarios using the same world, the world or map itself doesn’t change, but the things in the world and your objective can change.

BiguaSim is intended to be used with user-created scenarios as well. Custom scenarios can be created using a dictionary in a Python script or by creating a .json file. Both methods follow the same format, described below.

Scenario File Format

Scenario .json files are distributed in packages (see Package Contents), and must be named {WorldName}-{ScenarioName}.json. By default they are stored in the worlds/{PackageName} directory (see Package Installation Location).

Scenarios can be defined using a .json file or in a Python script using a dictionary. Both methods follow the same format using key-value pairs. An example dictionary is given below:

{
   "name": "{Scenario Name}",
   "world": "{world it is associated with}",
   "package_name": "{package it is associated with}",
   "agents":[
      "array of agent objects"
   ],
   "ticks_per_sec": 30,
   "frames_per_sec": 30,
   "env_min": [-10, -10, -10],
   "env_max": [10, 10, 10],
   "octree_min": 0.1,
   "octree_max": 5,
   "window_width":  1280,
   "window_height": 720,
   "lcm_provider": "provider name"
}

Note

At a minimum, a scenario must contain name, world, and package_name keys, and at least one agent object. All other keys are optional and will default to a set value if not provided.

Below is a description of some of the keys in the scenario dictionary.

Name and World

  • name is a string that specifies the name of the scenario.

    This name is part of the string passed to biguasim.make() to create an environment.

  • world is a string that specifies the world to load.

    It must match the name of the world file in the package folder (see BiguaSim Packages).

  • package_name is a string that specifies the package the world is associated with.

Agent Objects

BiguaSim agents are declared in a list in the scenario dictionary. Each agent is defined using a new dictionary in the list.

Below is an example of an agent configuration. For detailed descriptions of the keys and values, see Agent Configuration.

"agents":[
   {
      "agent_name": "uav0",
      "agent_type": "{agent types}",
      "sensors": [
         "array of sensor objects"
      ],
      "control_abstraction": "{control abstraction type}",
      "location": [1.0, 2.0, 3.0],
      "rotation": [1.0, 2.0, 3.0],
      "location_randomization": [1, 2, 3],
      "rotation_randomization": [10, 10, 10],
      "dynamics" : {
             "batch_size" : 1,
      },
   }
]

Sensor Objects

Each agent can be equipped with one or more sensors, including cameras and sonar. Sensor definition happens within each agent definition.

Below is an example of a sensor definition. For detailed descriptions of the keys and values, see Sensor Configuration.

"sensors":[
   {
      "sensor_type": "RGBCamera",
      "sensor_name": "FrontCamera",
      "socket": "socket name",
      "location": [1.0, 2.0, 3.0],
      "rotation": [1.0, 2.0, 3.0],
      "Hz": 5,
      "lcm_channel": "channel_name",
      "configuration": {
         "array of sensor configurations"
      }
   }
]

Frame Rates

The frame rate in BiguaSim is controlled using two parameters: ticks_per_sec and frames_per_sec.

  • ticks_per_sec changes how many ticks are in a simulation second.

    This must be higher than any “Hz” sampling rate used by any sensors. Defaults to 30.

  • frames_per_sec is the max FPS the environment can run at.

    • If true, it will match ticks_per_sec.

    • If false, FPS will not be capped, and the environment will run as fast as possible.

    • If a number is given, the simulation will attempt to reach that frame rate, but no higher.

    • Defaults to true.

For running the simulation in real time (for example, when Manually Controlling an Agent), set frames_per_sec to true. For running BiguaSim headless, you’ll likely want the simulation to run as fast as possible, so frames_per_sec should be set to false. When using a GPU, simulations can run much faster than realtime, making things difficult to control when the framerate is unlimited. In this case, capping frames_per_sec at a specific value can be useful.

Octree Configuration

When using a form of sonar sensor and initializing the world, an Octree will either be created or loaded from a cache. The parameters of these can be set using the env_min, env_max, octree_min, and octree_max. The octrees are cached in the Linux/Holodeck/Octrees folder in the worlds folder (see Package Installation Location).

env_min/env_max are used to set the upper/lower bounds of the environment. They should be set in Package Structure, but the values set here will override it.

octree_min/octree_max are used to set the minimum/mid-level size of the octree. octree_min can go as low as .01 (1cm), and then the octree will double in size until it reaches octree_max.

For more information about Octrees, see Octree Generation.

Other Scenario Parameters

  • window_width/height control the size of the viewport window opened when an environment is created.

    Sizes are in pixels.

  • lcm_provider is an optional parameter that specifies where to publish LCM messages.

    For more detail, see Publishing Data Using LCM.

Making Custom Scenarios

You can create custom scenarios in two ways: with a dictionary in a Python script, or by creating a .json file. Both methods follow the same format as described in the section above.

Using a Dictionary for a Scenario Config

Create a dictionary in Python that matches the structure specified in Scenario File Format, and pass it in to biguasim.make() using the scenario_cfg variable.

An example is given below:

import biguasim

scenario = {
     "name": "test_rgb_camera",
     "world": "Bridge",
     "package_name": "SkyDive",
     "main_agent": "auv0",
     "ticks_per_sec": 60,
     "agents": [
         {
            "agent_name": "auv0",
            "agent_type": "BlueROV2",
            "sensors": [
               {
               "sensor_type": "DynamicsSensor",
               "socket": "IMUSocket",
               "configuration": {
                     "UseCOM": True,
                     "UseRPY": False
                  }
               },
               {
                  "sensor_type": "RGBCamera",
                  "socket": "CameraSocket",
                  "configuration": {
                        "CaptureWidth": 512,
                        "CaptureHeight": 512
                  }
               }
            ],

            "dynamics" : {
               "batch_size" : 1,
            },
            "control_abstraction": 'cmd_vel',
            "location": [0, 0, -10],
            "rotation": [0.0, 0.0, 90.0]
         }
     ]
}

 with biguasim.make(scenario_cfg=scenario) as env:
     for _ in range(200):

         state = env.tick()
         if "RGBCamera" in state:
            pixels = state["RGBCamera"]
            frame = pixels[:, :, 0:3].astype(np.uint8)

            cv2.imshow("Camera Output", frame)

            if cv2.waitKey(1) & 0xFF == ord('q'):
               break

Using a .json file for a Scenario Config

You can specify a custom scenario by creating a .json file that follows the format given in Scenario File Format and either:

  1. Loading it yourself in a Python script and parsing it into a dictionary, then using that dictionary as described above.

  2. Placing it in BiguaSim’s scenario search path.

When you give a scenario name to biguasim.make(), BiguaSim will search each package folder (see Package Installation Location) until it finds a .json file that matches the scenario name.

To use custom scenario .json files, place them in the Oceans package folder (or the package folder that contains the world your scenario uses). For details on package folder locations, see Package Installation Location. BiguaSim will automatically find and use .json scenario files in the package folder.

Warning

If you remove and reinstall a package, BiguaSim will clear the contents of that folder. Be sure to remove any custom scenario .json files from the package folder before uninstalling and reinstalling a package.