Simulator Python API Runtime

Table of Contents

Using the Python API runtime top#

The simulator provides a Python API runtime to allow running Python scripts to control the simulation directly in the WebUI. To use the Python API runtime:

  1. Go to the Simulations tab
  2. Click Add New
  3. Fill out the Simulation Name, Select Cluster, and optionally a description and click Next
  4. In the Runtime Template dropdown menu, select Python API
  5. Select the Map and Vehicle and Sensor Configuration you will be using in from the drop-down menus. This will set the LGSVL__MAP and LGSVL__VEHICLE_0 environment variables to the UUID of the selected map and vehicle. These environment variables can be used in the Python script to load the correct map and vehicle sensor configuration.
  6. In the text box titled Python script, enter your Python code directly and click Next
    • Any maps or vehicles used in the Python script must be added to the users library
    • An example Python script is available below, which requires the BorregasAve map and Lincoln2017MKZ vehicle to be added to the user library
  7. There will be no need to specify an Autopilot; click Next again
  8. Publish the new simulation to use it

Once published, the new simulation will appear in your Simulations page and can be run by clicking on the Run Simulation button.

Note: The Python script should not prompt for user input, otherwise it will result in a timeout as there is no way to get user input after the simulation has started. For example, all of the Python API examples in the quickstart folder in the Python API repository ask for user input before starting the simulation. To use one of the scripts from quickstart all of the input(...) calls should be removed.

Reading Logs top#

In cases where the Python script throws an error the simulator will not be able to run the script properly (or at all) and errors will be written to Playor.log located in the simulator's persistent data path. By default this would be ~/.config/unity3d/LGElectronics/SVLSimulator/Player.log.

Note: Player.log contains all logs from the simulator (not just Python API runtime logs).

Example Python Script top#

Below is an example script to use with the Python API runtime. This script requires the BorregasAve map and the Lincoln2017MKZ vehicle to be added to the user's library. After running the script, the ego vehicle will be spawned at the center of an intersection and an NPC vehicle will pass it on its right, pausing for half a second at every waypoint.

import os
import lgsvl
import copy

sim = lgsvl.Simulator(os.environ.get("LGSVL__SIMULATOR_HOST"), 8181)

# BorregasAve default map must be added to your personal library

spawns = sim.get_spawn()
forward = lgsvl.utils.transform_to_forward(spawns[0])
right = lgsvl.utils.transform_to_right(spawns[0])

state = lgsvl.AgentState()
state.transform = spawns[0]
ego_state = copy.deepcopy(state)
ego_state.transform.position += 50 * forward
ego_state.transform.position -= 3 * right

# The Lincoln2017MKZ default vehicle must be added to your vehicle library
a = sim.add_agent(os.environ.get("LGSVL__VEHICLE_0"), lgsvl.AgentType.EGO, ego_state)

npc_state = copy.deepcopy(state)
npc_state.transform.position += 10 * forward
npc = sim.add_agent("Sedan", lgsvl.AgentType.NPC, npc_state)

vehicles = {
  a: "EGO",
  npc: "Sedan",

# This block creates the list of waypoints that the NPC will follow
# Each waypoint is an position vector paired with the speed that the NPC will drive to it
waypoints = []
x_max = 2
z_delta = 12

layer_mask = 0
layer_mask |= 1 << 0 # 0 is the layer for the road (default)

for i in range(20):
  speed = 24# if i % 2 == 0 else 12
  px = 0
  pz = (i + 1) * z_delta
  # Waypoint angles are input as Euler angles (roll, pitch, yaw)
  angle = spawns[0].rotation
  # Raycast the points onto the ground because BorregasAve is not flat
  hit = sim.raycast(spawns[0].position + pz * forward, lgsvl.Vector(0,-1,0), layer_mask)

  # NPC will wait for 1 second at each waypoint
  wp = lgsvl.DriveWaypoint(hit.point, speed, angle, 1)

# The NPC needs to be given the list of waypoints.
# A bool can be passed as the 2nd argument that controls whether or not the NPC loops over the waypoints (default false)

Environment Variables top#

The simulator uses a set of predefined environment variables to configure the simulation. These variables are listed below.

Environment Variable Description
LGSVL__SIMULATOR_HOST SVL Simulator hostname or IP
LGSVL__MAP UUID of map to be loaded in Simulator
LGSVL__VEHICLE_0 UUID of the first EGO vehicle/sensor configuration to be loaded in Simulator. Subsequent EGO vehicles can be accessed by incrementing the number, e.g. LGSVL_VEHICLE_1.
LGSVL__AUTOPILOT_0_HOST Autopilot bridge hostname or IP. If SVL Simulator is running on a different host than Autopilot, this must be set.
LGSVL__AUTOPILOT_0_PORT Autopilot bridge port
LGSVL__AUTOPILOT_0_VEHICLE_CONFIG Vehicle configuration to be loaded in Dreamview (Capitalization and spacing must match the dropdown in Dreamview) (e.g. Lincoln2017MKZ)
LGSVL__AUTOPILOT_0_VEHICLE_MODULES Comma-separated list of modules to be enabled in Dreamview. Items must be enclosed by double-quotes and there must not be spaces between the double-quotes and commas. (Capitalization and space must match the sliders in Dreamview)
LGSVL__AUTOPILOT_HD_MAP HD map to be loaded in Dreamview (Capitalization and spacing must match the dropdown in Dreamview)
LGSVL__DATE_TIME Date and time to start simulation at. Time is the local time in the time zone of the map origin. Format 'YYYY-mm-ddTHH:MM:SS'
LGSVL__ENVIRONMENT_CLOUDINESS Value of clouds weather effect, clamped to [0.0, 1.0]
LGSVL__ENVIRONMENT_DAMAGE Value of road damage effect, clamped to [0.0, 1.0]
LGSVL__ENVIRONMENT_FOG Value of fog weather effect, clamped to [0.0, 1.0]
LGSVL__ENVIRONMENT_RAIN Value of rain weather effect, clamped to [0.0, 1.0]
LGSVL__ENVIRONMENT_WETNESS Value of wetness weather effect, clamped to [0.0, 1.0]
LGSVL__RANDOM_SEED Seed used to determine random factors (e.g. NPC type, color, behaviour)
LGSVL__SIMULATION_DURATION_SECS The time length of the simulation [int]
LGSVL__SPAWN_BICYCLES Whether or not to spawn bicycles [boolean] (not yet supported)
LGSVL__SPAWN_PEDESTRIANS Whether or not to spawn pedestrians [boolean]
LGSVL__SPAWN_TRAFFIC Whether or not to spawn NPC vehicles [boolean]
LGSVL__TIME_STATIC Whether or not time should remain static [boolean] (True = time is static, False = time moves forward)