openSimulationInterface

Store RoadRunner Scenario simulation data in ASAM Open Simulation Interface (OSI) format

Since R2024b

Description

An openSimulationInterface object enables you to store and write RoadRunner Scenario simulation data, such as ground truth information and sensor view information, in the ASAM Open Simulation Interface (OSI)^® V3.5.0 format. The OSI format is an open file format designed to focus on the environmental perception of automated driving functions. It enables automated driving functions to easily work with many different driving simulation frameworks. OSI includes an object-based environment description that uses the Google^® Protocol Buffer (protobuf) message format. You can simulate the specified scenario and populate the SensorView property of the object with information from the environmental perception of the specified sensors or a ground truth data around an ego vehicle in OSI format by using the startRoadRunnerSimulation object function. You can also write the OSI data of each sensor to a distinct binary file by using the write object function.

Creation

Syntax

osiData = openSimulationInterface(scenarioSim,sensors)

osiData = openSimulationInterface(scenarioSim,gtArea)

Description

osiData = openSimulationInterface(scenarioSim,sensors) creates an empty openSimulationInterface object associated with the specified scenario simulation scenarioSim. The object adds the specified sensors sensors to the simulation.

osiData = openSimulationInterface(scenarioSim,gtArea) creates an empty openSimulationInterface object associated with the specified scenario simulation scenarioSim to store the ground truth information of an area, gtArea, in the xy-plane of the world coordinate system, centered around an ego vehicle, in OSI format.

Input Arguments

scenarioSim — RoadRunner Scenario simulation

ScenarioSimulation object

RoadRunner Scenario simulation for which to store the OSI data, specified as a ScenarioSimulation object.

sensors — Sensors to add to RoadRunner Scenario simulation

visionDetectionGenerator object | drivingRadarDataGenerator object | cell array of detection generator objects

Sensors to add to the RoadRunner Scenario simulation, specified as one of these options:

• A single visionDetectionGenerator or drivingRadarDataGenerator object.

• A cell array of visionDetectionGenerator and drivingRadarDataGenerator objects.

Each detection generator must have a unique sensor ID, specified by its SensorIndex property.

gtArea — Ground truth area

groundTruthArea object

Since R2025a

Ground truth area for which to store the ground truth OSI data during RoadRunner Scenario simulation, specified as a groundTruthArea object. This argument specifies an area in the xy-plane of the world coordinate system centered around an ego vehicle.

Properties

GroundTruth — Ground truth message of OSI data

array of openstandards.osi.GroundTruth objects

Ground truth message of the OSI data, specified as an array of openstandards.osi.GroundTruth objects. This message describes the simulated environment of a scenario, detailing all the simulated objects surrounding an ego vehicle within the combined field of view of its attached sensors. For more information on the properties of this object, see the attributes of the OSI GroundTruth message.

SensorView — Sensor view message of OSI data

array of openstandards.osi.SensorView objects

Sensor view message of the OSI data, specified as an array of openstandards.osi.SensorView objects. The sensor view message derives from the ground truth message, and includes information from the environmental perception of the sensors attached to the ego vehicle during scenario simulation. The sensor models use the sensor view information as input, to simulate actual sensors. For more information on the properties of this object, see the attributes of the OSI SensorView message.

SensorData — Sensor data message of OSI data

array of openstandards.osi.SensorData objects

Sensor data message of the OSI data, specified as an array of openstandards.osi.SensorData objects. The sensor data message contains information from the environmental perception of the sensors attached to the ego vehicle during scenario simulation. The sensor models process the sensor data information to replicate the output of the real sensors. For more information on the properties of this object, see the attributes of the OSI SensorData message.

TrafficCommand — Traffic command message of OSI data

array of openstandards.osi.TrafficCommand objects

Traffic command message of the OSI data, specified as an array of openstandards.osi.TrafficCommand objects. This message contains control commands to control the traffic participant models in a scenario. For more information on the properties of this object, see the attributes of the OSI TrafficCommand message.

TrafficUpdate — Traffic update message of OSI data

array of openstandards.osi.TrafficUpdate objects

Traffic update message of the OSI data, specified as an array of openstandards.osi.TrafficUpdtae objects. The traffic participant models of a scenario provide the traffic update message. This message updates their positions, states, and future trajectories in the simulation environment. For more information on the properties of this object, see the attributes of the OSI TrafficUpdate message.

Object Functions

startRoadRunnerSimulation	Start RoadRunner Scenario simulation
write	Write OSI data to binary file
getProtoMessage	Get OSI protocol buffer (protobuf) message at each simulation step

Examples

Generate OSI Trace File Using Single Sensor

Create a roadrunner object to launch the RoadRunner application. Replace "C:\OsiRoadRunnerProject\" with the path to a RoadRunner project folder on your computer.

rrApp = roadrunner(ProjectFolder="C:\OsiRoadRunnerProject\");

Open the scenario file TrajectoryCutIn.rrscenario. This scenario is included with the RoadRunner Scenario application.

openScenario(rrApp,"TrajectoryCutIn");

Create scenarioSim, a ScenarioSimulation object, to connect MATLAB® to the RoadRunner Scenario simulation.

scenarioSim = createSimulation(rrApp);

Create sensorSim, a RoadRunner SensorSimulation object, to control the sensor configuration for the RoadRunner Scenario simulation.

sensorSim = get(scenarioSim,"SensorSimulation");

Configure the sensor model for a radar sensor, to add to the ego vehicle, using a drivingRadarDataGenerator object.

radar = drivingRadarDataGenerator(SensorIndex=1, ...
      MountingLocation=[2.4 0 0.2], ...
      RangeLimits=[0 100], ...
      TargetReportFormat="Detections");

sensors = {radar};

Add the sensor to the ego vehicle actor in the RoadRunner scenario. Specify the Actor ID property of the vehicle.

egoVehicleID = 1;
addSensors(sensorSim,sensors,egoVehicleID);

Create osiData, a RoadRunner openSimulationInterface object, to store RoadRunner Scenario simulation data in OSI format.

osiData = openSimulationInterface(scenarioSim,sensors);

Start the RoadRunner simulation, storing the scenario simulation data in OSI format in the osiData object.

startRoadRunnerSimulation(osiData);

Specify a custom filename for an output binary file, with a .txt extension, and write the OSI data of the sensor to the OSI trace file.

write(osiData,"testEgoFollowSpeed.txt");

Store Ground Truth Information Around Ego Vehicle in OSI Format

Create a roadrunner object to launch the RoadRunner application. Replace "C:\RR\MyProject" with the path to a RoadRunner project folder on your computer.

rrApp = roadrunner(ProjectFolder="C:\RR\MyProject");

Open the scenario file TrajectoryCutIn.rrscenario. This scenario is included with the RoadRunner Scenario application.

openScenario(rrApp,"TrajectoryCutIn");

Connect MATLAB® to the RoadRunner Scenario simulation by creating a ScenarioSimulation object, scenarioSim.

scenarioSim = createSimulation(rrApp);

Specify the area for which you want to store ground truth information in OSI form during simulation by creating a groundTruthArea object, gtArea.

egoID = 1;
area = [40 40 0];
gtArea = groundTruthArea(egoID,area);

Create an openSimulationInterface object, for storing RoadRunner Scenario simulation data in OSI format.

osiData = openSimulationInterface(scenarioSim,gtArea);

Start the RoadRunner simulation, storing the scenario simulation data in OSI format by using the openSimulationInterface object.

startRoadRunnerSimulation(osiData);

Specify a custom filename for an output binary file, with a .txt extension, and write the ground truth OSI data to the OSI trace file.

write(osiData,"testEgoFollowSpeed.txt");

Version History

Introduced in R2024b

R2025a: New syntax to store ground truth information of area around ego vehicle

You can now specify to store the ground truth information of an area in the xy-plane of the world coordinate system, centered at the origin of an ego vehicle, in OSI format by using this new syntax:

osiData = openSimulationInterface(scenarioSim,gtArea).