VTD Simulator Binding

The VTD simulator binding is used to enable Cloe to communicate with VTD. This involves retrieving sensor-, vehicle- and groundtruth data from VTD and converting it to the respective Cloe data structures. Additionally Cloe’s actuation requests are converted into VTD’s format and VTD is requested to proceed simulation for an instance of time.

Initially VTD is configured and a scenario is selected and started. All this is done using information from the configuration.

Configuration

This simulator binding can be configured in a Cloe Stackfile. There are both general and VTD specific configuration options. The general options are described in the main config reference because they are common for any simulator binding.

In the following sections you’ll find an example and reference for VTD simulator binding specific configuration options.

setup

The VTD setup to use. It contains VTD configuration that influences how VTD is started and which parts of VTD (GUI, image generator(s), …) are used. We mainly use it to distinguish between interactive and headless operation. The following setups are maintained for Cloe operation:

• Cloe.Default for interactive operation with GUI and render window

• Cloe.noGUInoIG for headless operation (e.g. automated tests)

• Cloe.noGUI to open only the render window

scenario

The path to the scenario relative to the VTD project’s scenario directory. So any scenario directly located in that directory can just be defined by their name as in the example below.

dat_file

VTD can optionally write a file recording all the available ground truth data in a VTD specific format. Specify a file path here to enable the output. Usually VTD will be run inside a container. In order to prevent the file to be deleted together with the container after simulation, you will have to define a storage entry in order to map the output directory to a sensible storage. Again, compare the example below.

vehicles

VTD specific vehicle configuration for each vehicle.

vehicles/<name>

Configuration for a particular VTD vehicle. The vehicle’s name is as defined in the selected scenario. It is usually called Ego but it can be identified by the vehicle’s “Animation” field set to “external” in the Scenario Editor. Note that in a multi agent simulation scenario there are multiple “external” vehicles with different names.

vehicles/<name>/sensors

Definition of a vehicle’s set of VTD sensors. There’s currently two subsections sensors and components first of which describes the sensor configuration. Each sensor might offer data of different types like objects, lanes or road signs. Which are referred to as components in Cloe.

vehicles/<name>/sensors/<sensorname>

Definition of a single VTD sensor. In future we may support different formats to specify the sensor properties in order to perform simple things in a simple way. Currently the only way is to define it in terms of the VTD module manager XML configuration as described in the following section.

vehicles/<name>/sensors/<sensorname>/xml

VTD module manager XML configuration for a single VTD sensor. You can for example specify the mounting position and orientation, the sensor’s field and range of view (a.k.a. frustum) and filters defining which types of objects are to be perceived by the sensor. Cloe needs you to fill in placeholders for values that are known at runtime but not at the time of your configuration.

• [[ sensor_id ]] Sensor id to create a unique sensor name in the Sensor tag

• [[ sensor_name ]] Sensor name e.g. for a speaking sensor name in Sensor tag

• [[ sensor_port ]] TCP port for the sensor’s RDB channel in the Port tag

• [[ player_id ]] Player id for the Player tag

Guess your configuration options from the example or refer to the Vires VTD Wiki.

vehicles/<name>/components

The component configuration maps the sensors’ data streams to Cloe components and makes them available under a certain name.

vehicles/<name>/components/<component_name>

The component name is used to get access to the component through the get functions of a Cloe Vehicle object. Each Cloe controller binding knows the vehicle it is associated with (or mounted in). The implementor of the binding can access sensor data by this component name and is likely also the author of this part of the Cloe Stackfile.

vehicles/<name>/components/<component_name>/from

Refers to the <sensorname> as defined in sensors section. This defines the VTD sensor to take a particular type of data from. Note that all types of data in this sensor are expressed relatively to this sensor’s mounting position and filtered according to the defined field and range of view.

vehicles/<name>/components/<component_name>/type

Defines the Cloe component type. Currently available are

• lane_sensor

• object_sensor

Note that this type of data needs to be enabled in the VTD sensor’s configuration. E.g. the roadMarks filter for the lane_sensor component. There is no warning whatsoever in case this is missed, but the respective data will be unavailable in the controller binding implementation.

vehicles/<name>/components/<component_name>/override

Declares whether the intention is to override an existing component with that name. Override defaults to false. If its value is false, then declaring a component name already in use will lead to an error message. If true, cloe expects the component name to be already in use and override it with the newly declared one or terminate with an error if no such component can be found.

scp_actions

A dictionary defining keywords to SCP actions. These can then be referred to by the scp action. For example:

"scp_actions": {
  "stop": "<SimCtrl><Stop/></SimCtrl>"
}

Ground Truth

Ground truth, that is complete and unaltered data from the VTD environment model, is made available by VTD over the so called TaskControl RDB channel. Data passed on this channel is agnostic of any sensor. Objects are given in absolute coordinates (relative to VTD’s map origin).

We make parts of the ground truth data on the following Cloe component:

• cloe::gndtruth_world_sensor => Groundtruth objects

For the closest thing to ground truth for lanes and traffic signs, refer to Perfect Sensor. Complete ground truth data for these types of data can be found in the opendrive map used by the current scenario.

Perfect Sensor

In order to provide the user with a reasaonable default, the VTD plugin always configures a Perfect Sensor. It is an idealized sensor as its parameters suggest:

• Positioned in the vehicle’s origin (ground under center of rear axle)

• Zero rotation (so exact same coordinate frame as vehicle)

• Surround view

• Range 0m - 180m

• Up to 50 objects

The different types of sensor data which in Cloe terms are called ‘components’ are made available with the following component names:

• cloe::default_world_sensor => dynamic objects

• cloe::default_lane_sensor => lane boundary segments

• cloe::default_ego_sensor => ego pose/odometry

The above is sensible only for a single agent simulation. In case of a multi agent scenario you should define your sensors and map your sensor components explicitly as described in Configuration: section.

Triggers

The following actions are provided by the plugin. Plugin trigger action names are dependent on the given name of a plugin in a simulation. This is by default the name of the plugin itself; this default name is used in this documentation.

<vtd>/scp

The VTD plugin makes this action available to send SCP messages to the VTD simulator. The name of the action is prefixed by the given name of the plugin.

There are two variants of this action. Either a template is predefined in the configuration /scp_actions field or raw XML is provided. If a template is defined, then variables can be specified via this syntax: [[ var ]].

XML Variant

Parameter	Required	Type	Description
xml	yes	string	Raw XML data to send to simulator

Template Variant

Parameter	Required	Type	Description
template	yes	string	Switch to enable or disable
data	no	bool	Push button to cycle distance profiles.

Inline short-form is supported as a reference to template to use. No data interpolation is supported in this form:

vtd/scp=stop

Examples

Given the following simulator configuration:

version: "4"
defaults:
  simulators:
    binding: vtd
    args:
      scp_actions:
        simctrl: "<SimCtrl><[[cmd]]/></SimCtrl>"
        stop: >
            <SimCtrl>
                <Stop/>
            </SimCtrl>

The the following triggers are all identical:

[
  {
    "event": "time=5",
    "action": "vtd/scp=stop"
  },
  {
    "event": "time=5",
    "action": {
      "name": "vtd/scp",
      "xml": "<SimCtrl><Stop/></SimCtrl>"
    }
  },
  {
    "event": "time=5",
    "action": {
      "name": "vtd/scp",
      "template": "simctrl",
      "data": {
        "cmd": "Stop"
      }
    }
  }
]

Example

simulators:
  - binding: vtd
    args:
      setup: Cloe.noGUInoIG
      project: example_vtd_project
      scenario: acc.xml
      dat_file: /output/vtd-basic-example.dat
      vehicles:
        Ego:
          components:
            "cloe::default_lane_sensor":
              from: camera
              type: lane_sensor
              override: true
            "cloe::default_world_sensor":
              from: camera
              type: object_sensor
              override: true
            "sysut::radar1":
              from: radar_1
              type: object_sensor
            "sysut::radar2":
              from: radar_2
              type: object_sensor

          sensors:
            radar_1:
              ...
            radar_5:
              ...
            camera:
              xml: >
                <Sensor name='Sensor_[[ sensor_id ]]_[[ sensor_name ]]' type='video'>
                  <Load
                    lib='libModulePerfectSensor.so'
                    path=''
                    persistent='true'
                    />
                  <Frustum
                    near='0.0'
                    far='180.0'
                    left='180.0'
                    right='180.0'
                    bottom='180.0'
                    top='180.0'
                    />
                  <Origin type='sensor' />
                  <Cull maxObjects='50' enable='true' />
                  <Port name='RDBout' number='[[ sensor_port ]]' type='TCP' sendEgo='true' />
                  <Player id="[[ player_id ]]" />
                  <Position dx='0.0' dy='0.0' dz='0.0' dhDeg='0.0' dpDeg='0.0' drDeg='0.0' />
                  <Database resolveRepeatedObjects='true' continuousObjectTesselation='2.0' />
                  <Filter objectType='pedestrian'/>
                  <Filter objectType='vehicle'/>
                  <Filter objectType='obstacle'/>
                  <Filter
                    objectType="roadMarks"
                    roadmarkPreviewDistance="100.0"
                    tesselate="true"
                    tesselateNoPoints="10"
                    tesselateFixedStep="true"
                    />
                </Sensor>
      stack:
        image: dtr.cucumber.tld/cloe/vtd-cloe:2.2.0
        storage:
          # define a storage volume from a path on your host
          - name: example_vtd_project
            host_path: ~/.vtd_projects/example_vtd_project
          - name: output
            host_path: .
...

Defaults

The following help can be viewed with cloe-engine usage vtd:

Name: vtd
Type: simulator
Path: ~/.conan/data/cloe-plugin-vtd/0.20.0/cloe/develop/package/7e58df8cb379ba7703d10f34d6afe33281d13a30/lib/cloe/simulator_vtd.so
Usage: {
  "camera": {
    "focus_on": "string :: player to focus on",
    "third_person": "boolean :: whether to use third person camera"
  },
  "configuration_retry_attempts": "integer :: attempts to retry connection on broken pipe",
  "connection": "object :: scp connection parameters",
  "dat_file": "string :: filepath to write VTD data output to",
  "image_generator": "boolean :: switch whether VTD should use image generator",
  "label_vehicle": "string :: how to label vehicle modes in VTD [off,text,human,symbol,unicode]",
  "paramserver": "object :: parameter sever connection parameters",
  "project": "string :: indicate which project to find the scenario in (informative)",
  "rdb_params": "object :: rdb connection parameters",
  "scenario": "string :: VTD scenario to use (project must already be loaded)",
  "scp_actions": "object :: predefined SCP actions for use by action trigger",
  "sensor_initial_port": "integer :: initial port for sensor communication",
  "setup": "string :: indicate which setup you are using",
  "task_control_params": "object :: task control connection parameters",
  "vehicles": "object :: vehicle configuration like sensors and component mapping"
}
Defaults: {
  "camera": {
    "focus_on": "",
    "third_person": true
  },
  "configuration_retry_attempts": 10,
  "connection": {
    "host": "localhost",
    "port": 48179,
    "retry_attempts": 60,
    "retry_delay_s": 1.0
  },
  "dat_file": "",
  "image_generator": true,
  "label_vehicle": "text",
  "paramserver": {
    "host": "localhost",
    "port": 54345,
    "retry_attempts": 60,
    "retry_delay_s": 1.0
  },
  "project": "",
  "rdb_params": {
    "retry_attempts": 60,
    "retry_delay_s": 0.5
  },
  "scenario": "",
  "sensor_initial_port": 48196,
  "setup": "Cloe.Default",
  "task_control_params": {
    "retry_attempts": 60,
    "retry_delay_s": 0.5
  }
}

JSON Schema

The following can be viewed with cloe-engine usage --json vtd:

{
  "$id": "~/.conan/data/cloe-plugin-vtd/0.20.0/cloe/develop/package/7e58df8cb379ba7703d10f34d6afe33281d13a30/lib/cloe/simulator_vtd.so",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false,
  "description": "VIRES Virtual Test Drive",
  "properties": {
    "camera": {
      "additionalProperties": false,
      "properties": {
        "focus_on": {
          "description": "player to focus on",
          "type": "string"
        },
        "third_person": {
          "description": "whether to use third person camera",
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "configuration_retry_attempts": {
      "description": "attempts to retry connection on broken pipe",
      "maximum": 65535,
      "minimum": 0,
      "type": "integer"
    },
    "connection": {
      "additionalProperties": false,
      "description": "scp connection parameters",
      "properties": {
        "host": {
          "description": "hostname of connection",
          "type": "string"
        },
        "port": {
          "description": "port of connection",
          "maximum": 65535,
          "minimum": 0,
          "type": "integer"
        },
        "retry_attempts": {
          "description": "connection retry attempts",
          "maximum": 2147483647,
          "minimum": -2147483648,
          "type": "integer"
        },
        "retry_delay_s": {
          "description": "time delay between connection attempts",
          "maximum": 3.4028234663852886e+38,
          "minimum": -3.4028234663852886e+38,
          "type": "number"
        }
      },
      "type": "object"
    },
    "dat_file": {
      "description": "filepath to write VTD data output to",
      "type": "string"
    },
    "image_generator": {
      "description": "switch whether VTD should use image generator",
      "type": "boolean"
    },
    "label_vehicle": {
      "description": "how to label vehicle modes in VTD [off,text,human,symbol,unicode]",
      "enum": [
        "off",
        "text",
        "human",
        "symbol",
        "unicode"
      ],
      "type": "string"
    },
    "paramserver": {
      "additionalProperties": false,
      "description": "parameter sever connection parameters",
      "properties": {
        "host": {
          "description": "hostname of connection",
          "type": "string"
        },
        "port": {
          "description": "port of connection",
          "maximum": 65535,
          "minimum": 0,
          "type": "integer"
        },
        "retry_attempts": {
          "description": "connection retry attempts",
          "maximum": 2147483647,
          "minimum": -2147483648,
          "type": "integer"
        },
        "retry_delay_s": {
          "description": "time delay between connection attempts",
          "maximum": 3.4028234663852886e+38,
          "minimum": -3.4028234663852886e+38,
          "type": "number"
        }
      },
      "type": "object"
    },
    "project": {
      "description": "indicate which project to find the scenario in (informative)",
      "type": "string"
    },
    "rdb_params": {
      "additionalProperties": false,
      "description": "rdb connection parameters",
      "properties": {
        "retry_attempts": {
          "description": "connection retry attempts",
          "maximum": 2147483647,
          "minimum": -2147483648,
          "type": "integer"
        },
        "retry_delay_s": {
          "description": "time delay between connection attempts",
          "maximum": 3.4028234663852886e+38,
          "minimum": -3.4028234663852886e+38,
          "type": "number"
        }
      },
      "type": "object"
    },
    "scenario": {
      "description": "VTD scenario to use (project must already be loaded)",
      "type": "string"
    },
    "scp_actions": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "predefined SCP actions for use by action trigger",
      "type": "object"
    },
    "sensor_initial_port": {
      "description": "initial port for sensor communication",
      "maximum": 65535,
      "minimum": 0,
      "type": "integer"
    },
    "setup": {
      "description": "indicate which setup you are using",
      "type": "string"
    },
    "task_control_params": {
      "additionalProperties": false,
      "description": "task control connection parameters",
      "properties": {
        "retry_attempts": {
          "description": "connection retry attempts",
          "maximum": 2147483647,
          "minimum": -2147483648,
          "type": "integer"
        },
        "retry_delay_s": {
          "description": "time delay between connection attempts",
          "maximum": 3.4028234663852886e+38,
          "minimum": -3.4028234663852886e+38,
          "type": "number"
        }
      },
      "type": "object"
    },
    "vehicles": {
      "additionalProperties": {
        "additionalProperties": false,
        "properties": {
          "components": {
            "additionalProperties": {
              "additionalProperties": false,
              "properties": {
                "from": {
                  "description": "VTD sensor to retrieve the component data from",
                  "type": "string"
                },
                "override": {
                  "description": "Override an existing component with the same name",
                  "type": "boolean"
                },
                "type": {
                  "description": "Component type to register",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "description": "component definitions",
            "type": "object"
          },
          "sensors": {
            "additionalProperties": {
              "additionalProperties": false,
              "properties": {
                "mock_level": {
                  "additionalProperties": false,
                  "description": "Sensor data mock level",
                  "properties": {
                    "detected_lane_boundaries": {
                      "description": "mock level for detected lane boundaries",
                      "enum": [
                        "overwrite_none",
                        "interpolate_missing",
                        "overwrite_all"
                      ],
                      "type": "string"
                    },
                    "detected_moving_objects": {
                      "description": "mock level for detected moving objects",
                      "enum": [
                        "overwrite_none",
                        "interpolate_missing",
                        "overwrite_all"
                      ],
                      "type": "string"
                    },
                    "mounting_position": {
                      "description": "mock level for sensor mounting position",
                      "enum": [
                        "overwrite_none",
                        "interpolate_missing",
                        "overwrite_all"
                      ],
                      "type": "string"
                    }
                  },
                  "type": "object"
                },
                "protocol": {
                  "description": "VTD module manager sensor connection protocol ( rdb | osi )",
                  "enum": [
                    "rdb",
                    "osi"
                  ],
                  "type": "string"
                },
                "xml": {
                  "description": "VTD module manager sensor configuration",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "description": "sensor definitions",
            "type": "object"
          }
        },
        "type": "object"
      },
      "description": "vehicle configuration like sensors and component mapping",
      "type": "object"
    }
  },
  "title": "vtd",
  "type": "object"
}