ASAM OSI® (Open Simulation Interface)

Disclaimer

This document is the copyrighted property of ASAM e.V. Any use is limited to the scope described in the license terms.

Foreword

The ASAM OSI® (Open Simulation Interface) is a specification for interfaces between models and components of a distributed simulation. OSI is strongly focused on the environmental perception of automated driving functions.

The complexity of automated driving functions is rapidly increasing, which means the requirements for testing and development methods are growing too. Testing in virtual environments makes it possible to control and reproduce environment conditions.

To enable the widespread use of driving simulators for developers of functions, generic and standardized interfaces are needed for the connection between the function-development framework and the simulation environment. OSI permits easy and straight-forward compatibility between automated driving functions and the variety of driving-simulation frameworks that are available. OSI addresses the emerging standard ISO 23150 [1] for a real sensors’ standardized communication interface. OSI defines generic interfaces to ensure the modularity, integrability, and interchangeability of the individual components.

The vision is to make it possible to connect any automated driving function to any driving simulator and emerging new hardware sensor generations using a standardized ISO 23150 [1] interface. This will simplify integration, significantly strengthening the accessibility and usefulness of virtual testing in the process.

1. Introduction

1.1. What has changed

Documentation Updates

Updated the documentation’s structure and migrated it to AsciiDoc.
Updated the description of OSI’s top level messages.
Updates on additional descriptions, like those for trace file formats, naming conventions and installation instructions for Linux/Windows.

Technical Updates

Extended SensorViewConfiguration message to allow the consumer to choose to not include static content in the SensorView ground truth information.
Updated StationaryObject classification enums to avoid "pylon" duplication.
Extended StationaryObject classification message to include speed bumps.
Extended StationaryObject to include emitting structures of electromagnetic waves (for example this can be used to define a streetlamp).
Extended the TrafficSign classification message, by adding attributes country, country_revision, code and sub_code, to better support internationalization and to align with ASAM OpenDRIVE.
Updated the color coding message description to better align with ASAM OpenDRIVE.
Update the color coding message description to include Grey, RGB, RGBIR, HSV, LUV and thus align with ISO-23150.
Added an enum for dashed lane boundaries to disambiguate start and end of those.
Extended HostVehcileData with more comprehensive on-board information, and promoted the message to a top-level message for exchange between simulation environments and (external) dynamic models.
Extended LidarDetection message under feature data to include echo pulse width information to better support several sensor outputs that are currently on the market.
Extended OSI to include a generic external reference message to enable traceability for data from other standards, including other ASAM OpenX standards.
Added support for using OSI with Flatbuffers encoding for OSI messages instead of ProtoBuffers, in preparation for a potential switch of default encoding in a future major release.
Extended LaneBoundary message to include additional types, to better align with ASAM OpenDRIVE.

1.2. Deliverables

The following deliverables are provided for ASAM OSI®:

User guide, that is, this document (partly normative)
.proto files (normative)
Doxygen reference documentation (not normative)
OSMP packaging (OSMP packaging has its own version number, but is compatible with the version of ASAM OSI®.)

Related topics

Section 1.4
Section 1.3

1.3. ASAM OSI® repositories

ASAM OSI® is an open-source standardization project. OSI and its supporting tools are developed publicly on GitHub.

The source code and documentation for OSI and OSI-related tools are spread over several repositories:

open-simulation-interface: Main repository containing the interface description based on Google’s Protocol Buffers, including helper scripts and test scripts. Hosts the .proto files as well as the Doxygen reference documentation.
osi-documentation: Source for the OSI user guide sources and hosts the ASAM OSI® user guide.
osi-sensor-model-packaging: Packaging specification for OSI models used in FMI 2.0 [2] simulation environments, including examples.
proto2cpp: Doxygen filter for creating the reference documentation from OSI .proto files.

1.4. Normative and non-normative statements

This specification uses a standard information structure. The following rules apply regarding normativity of the different sections:

Statements expressed as requirements, permissions, or prohibitions according to the use of modal verbs, as defined in Section 1.5.2, "Modal verbs", are normative.
Rules in "Rules" sections are normative.
.proto files are normative.
Examples, use case descriptions, and instructions are non-normative.
Doxygen reference documentation is non-normative.

1.5. Conventions

1.5.1. Units

Every field has its own unit that is defined in the proto files. For more information, see the example in the contribution guidelines.

1.5.2. Modal verbs

To ensure compliance with the ASAM OSI® standard, users need to be able to distinguish between mandatory requirements, recommendations, permissions, as well as possibilities and capabilities.

The following rules for using modal verbs apply:

Table 1. Rules for using modal verbs
Provision	Verbal form
Requirements Requirements shall be followed strictly in order to conform to the standard. Deviations are not allowed.	shall shall not
Recommendations Recommendations indicate that one possibility out of the several available is particularly suitable, without mentioning or excluding the other possibilities.	should should not
Permissions Permissions indicate a course of action permissible within the limits of ASAM OSI® deliverables.	may need not
Possibilities and capabilities Verbal forms used to state possibilities or capabilities, whether technical, material, physical, etc.	can cannot
Obligations and necessities Verbal forms used to describe legal, organizational, or technical obligations and necessities that are not regulated or enforced by the ASAM OSI® standard.	must must not

1.5.3. Typographic conventions

This documentation uses the following typographical conventions:

Table 2. Typographical conventions
Mark-up	Definition
`Code elements`	This format is used for code elements, such as technical names of classes and attributes, as well as attribute values.
Technical concepts	This format is used for technical concepts. Technical concepts as opposed to code elements do not have a special highlighting.
`Code snippets`	This format is used for excerpts of code that serve as an example for implementation.
Terms	This format is used to introduce glossary terms, new terms and to emphasize terms.
`Mathematical elements`	This format is used for calculations and mathematical elements.
`<element>`	This describes a tag for an XML element
`@attribute`	The "@" identifies an attribute of an XML element.

1.6. Versioning and compatibility

The version number is defined in InterfaceVersion::version_number in osi_version.proto as the field’s default value.

OSI uses Semantic Versioning.

Major

A change in the major version makes the code and recorded proto messages incompatible.

Major changes include:

An existing field with a number changing its meaning. Example: optional double field = 1; changes to repeated double field = 1;.
Changing the definition of units or the interpretation of a field.
Deleting a field and reusing the field number.
Changing the technology from Protocol Buffers to FlatBuffers.

Minor

A change in the minor version indicates there is still compatibility with previously recorded files. However, the code needs fixing.

Minor changes include:

Renaming a field without changing the field number.
Changing the names of messages.
Adding a new field in a message without changing the numbering of other fields.

Patch

Both recorded files and code still have compatibility.

Patches include:

File or folder structure that does not affect integration of the code in other projects.
Changing or adding comments.
Clarifying text passages explaining the message content.

1.7. Relationships with other standards

1.7.1. Positioning of ASAM OSI® within ASAM activities

ASAM OSI® (Open Simulation Interface) is part of the ASAM simulation standards that focus on simulation data for the automotive environment. Next to ASAM OSI®, ASAM provides other standards for the simulation domain, like OpenDRIVE [3], OpenSCENARIO [4] and OpenCRG [5].

OpenDRIVE defines a storage format for the static description of road networks. In combination with OpenCRG it is possible to add very detailed road surface descriptions to the road network. OpenDRIVE and OpenCRG only contain static content. To add dynamic content, OpenSCENARIO is needed. Combining all three standards provides a scenario-driven description of traffic simulation that contains static and dynamic content.

1.7.2. References to other standards

DIN ISO 8855:2013-11: Road vehicles - Vehicle dynamics and road-holding ability - Vocabulary [6]
ISO 23150: Road vehicles — Data communication between sensors and data fusion unit for automated driving functions — Logical interface [1]
FMI 2.0: Functional Mock-up Interface for Model Exchange and Co-Simulation [2]

2. Open Simulation Interface

2.1. Idea behind Open Simulation Interface

ASAM OSI® Open Simulation Interface is a specification for interfaces between models and components of a distributed simulation. OSI is strongly focused on the environmental perception of automated driving functions. However, OSI also specifies interfaces for modeling traffic participants.

2.2. The basic design of OSI

2.2.1. Overview of OSI architecture

OSI contains an object-based environment description that uses the message format of the Protocol Buffer library. Google developed and maintains the Protocol Buffer library. OSI defines top-level messages that are used to exchange data between separate models. Top-level messages define the GroundTruth interface, the SensorData interface, and – since OSI version 3.0.0 – the interfaces SensorView, SensorViewConfiguration, and FeatureData.

The following figure shows the interfaces and models involved in modeling a sensor.

Figure 1. Open Simulation Interface overview

OSI also defines interfaces for traffic participant models. The TrafficCommand interface makes it possible to send commands to traffic participant models. The TrafficUpdate interface makes it possible to receive the updated state from traffic participant models. The following figure shows the interfaces of a generic traffic participant.

Figure 2. Interface of a traffic participant

Traffic participant models may use other OSI interfaces internally, for example, to model autonomous vehicles. The following figure shows a more advanced use case for traffic participants.

Figure 3. Traffic participant with sensor models, AD function, and dynamic model

The HostVehicleData interface describes the measured internal states of a traffic participant. OSI currently provides only limited support for data structures that describe measured internal states of traffic participants. One example would be the MotionRequest interface that can be used to communicate the results of the behavior planning to the dynamic model.

OSI uses singular instead of plural for repeated field names.

All fields in an interface are set to optional. required is not used.

This has been done to allow backward-compatible changes in the field. Additionally, this is the default behavior in Protocol Buffer version 3 that no longer has the required type. Setting all fields to optional thus ensures update compatibility. However, this does not mean that it is optional to fill the field. For the purpose of providing a complete interface, all existing fields should be set, unless not setting a field carries a specific meaning, as indicated in the accompanying comment.

All field numbers equal to or greater than 10000 are available for user-specific extensions via custom fields. No future evolution of OSI will therefore use field numbers equal to or greater than 10000.

2.2.2. Top-level interfaces

2.2.2.1. Ground truth

GroundTruth messages describe the simulated environment containing all simulated objects in the global coordinate system at consecutive time instances. They are based on data available to the simulation environment. GroundTruth messages are typically contained in Sensorview messages.

2.2.2.2. Feature data

FeatureData messages contain detected features in the reference frame of a sensor. FeatureData messages are generated from GroundTruth messages. They serve, for example, as an input to sensor models simulating object detection or feature fusion models.

2.2.2.3. Sensor view

The sensor view provides the input to OSI sensor models. SensorView messages are derived from GroundTruth messages. All information regarding the environment is given with respect to the virtual sensor coordinate system, with two exceptions:

Physical technology-specific data, given with respect to the physical sensor coordinate system specified in the corresponding physical sensor’s mounting position. One example of technology-specific data is: image_data of osi3::CameraSensorView
Ground truth given in the global coordinate system.

2.2.2.4. Sensor-view configuration

The sensor view is flexibly defined to provide different kinds of sensor models with an appropriate input. The sensor-view configuration defines the configuration of a particular sensor view.

The SensorViewConfiguration message is used in the initialization phase of a simulation to negotiate the sensor-view configuration for a particular SensorView input. It is also included as a sub-message in SensorView messages to indicate that the sensor-view configuration is valid for a particular SensorView message.

SensorViewConfiguration data has two main applications:

Enable the environment simulation to provide the necessary input to a sensor model.
Enable a sensor model to check whether the input matches its requirements. If the input does not match the requirements, the sensor model may terminate the simulation.

SensorViewConfiguration data is intended for the automatic configuration of the SensorView interface between an environment simulation and sensor model. The data is not intended to be a mechanism for parametrizing a generic sensor model.

During the initialization phase, there are two sources for SensorViewConfiguration data:

SensorViewConfiguration data may be provided by the sensor model to the environment simulation. In this case, the data describes the input configuration that is requested by the sensor model. If the sensor model does not provide such data, then the environment simulation will fall back to manual configuration of the sensor view.
SensorViewConfiguration data may be provided by the environment simulation. In response to the request by the sensor model, or based on manual configuration, the environment simulation configures the input and provides a new message that describes the actual configuration.

The configuration requested by the sensor model may differ from the configuration provided by the environment simulation. This happens when the environment simulation does not support a requested configuration or when the requested configuration is ambiguous.

In response to this difference, the sensor model can either accept this difference and adapt to it, or it can terminate the simulation to indicate that it is not able to accept the difference.

The packaging layer defines the specifics of this auto-negotiation mechanism.

After the initialization phase, the environment simulation provides the actual sensor-view configuration as part of each SensorView message.

2.2.2.5. Sensor data

SensorData messages imitate the output of real sensors. They can be generated from GroundTruth messages, SensorView messages, FeatureData messages, or SensorData messages. With the exception of feature data, all information regarding the environment is given with respect to the virtual sensor coordinate system. Feature data is given with respect to the physical sensor coordinate system. Sensor data can be used as input for an automated driving function, a sensor model simulating limited perception, or a sensor fusion model.

2.2.2.6. Traffic command

TrafficCommand messages contain control commands from the scenario engine to traffic participant models.

2.2.2.7. Motion Request

MotionRequest messages are traffic participant internal messages. They function as a interface between a motion/behavior planning model and a dynamics model including, for example, controllers and vehicle kinematics.

2.2.2.8. Traffic update

TrafficUpdate messages are provided by traffic participants. They provide updates on the position, state, and future trajectory of a traffic participant back to the simulation environment.

2.2.3. Model types

2.2.3.1. Environmental effect model

Environmental effect models consume SensorView messages and produce SensorView messages. Environmental effect models may, for example, alter SensorView messages to include effects and phenomena caused by:

Shadows and occlusions
Weather effects
Physics of a sensor
Pre-processing of raw sensor data

2.2.3.2. Sensor model

Sensor models consume SensorView messages and produce SensorData messages. Sensor-model output does not represent raw data but detected features or classified objects.

2.2.3.3. Logical model

Logical models consume SensorData messages and produce SensorData messages.

An example of a logical model is a sensor-fusion model, which combines the output of multiple sensor models to produce data with less uncertainty. Another use case is the fault-injection model which, contrary to a sensor-fusion model, may be used to increase uncertainties.

2.2.3.4. Traffic participant

A traffic participant is an element of the simulated world and can change its state during simulation time, for example, its position and orientation. A traffic participant represents one of the following:

Living being
Means of transportation for living beings
Means of transportation for goods
Any other movable object that may travel on the road network

Pedestrians and animals are examples of traffic participants that are living beings. Vehicles are examples of traffic participants that are a means of transportation. The ego vehicle is therefore also a traffic participant.

The following figure shows the interface of a traffic participant.

Figure 4. Interface of a traffic participant

Traffic participant models may use other OSI interfaces, for example, the SensorData and MotionRequest message, internally. The following figure shows a more advanced use case for traffic participants, that can, for example, be used to model an autonomous vehicle.

Figure 5. Traffic participant using other OSI interfaces internally

With every simulation step, an OSI traffic participant model receives ground-truth data from the environment around itself, the sensor view. A traffic participant can output its own perceivable state, the traffic update. Traffic commands influence the behavior of the traffic participant model. They allow event-based communication towards the traffic participant, that is, at certain simulation steps. Traffic commands do not necessarily need to come from the environment simulation. They may come from a separate source, such as a scenario engine.

Modeling a traffic participant

Different models may be involved in modeling a traffic participant. In all the use cases, a simulator loads and interprets a scenario and a map prior to execution. The scenario is, for example, provided by OpenSCENARIO. The map data is, for example, provided by OpenDRIVE. During runtime the simulator interacts with the traffic participants via OSI messages. There may be multiple instances of a traffic participant. The traffic participants are co-simulated.

The following figure shows a very simple use case.

Figure 6. Simple traffic participant

The traffic participant bases its behavior only on an idealized view of the area around it. The traffic participant’s dynamics are included in the model if they exist.

The following figure shows a traffic participant with separately modeled behavior and dynamics.

Figure 7. Traffic participants with separate dynamics

OSI currently provides only limited support for data structures that describe measured internal states of the traffic participant. An example for a traffic participant internal interface is the MotionRequest message that can be used to communicate planned behaviors from a behavior planning model to a dynamics model including, for example motion controllers and vehicle dynamics.

The following figure shows a more complex traffic participant.

Figure 8. Traffic participant with sensor models, AD function, and dynamics model

This use case will probably be relevant for modeling the ego vehicle, which includes the system under test. The traffic participant includes an arbitrary number of sensor models. The sensor models consume sensor view and produce sensor data. The AD function consumes sensor data and produces input for the dynamics model. The loop to the environment simulation is closed via traffic update.

The following figure shows a cooperative use case with both an AD function and a human driver.

Figure 9. Traffic participant with an AD function and human driver

It is possible to model a traffic participant with an AD function in the loop, but a human driver can still override the actuation command. This type of cooperative use case is, for example, relevant to studies on human-machine interaction. In this example, a virtual on-screen representation of the scenario, or mock-up, is added after the AD function. The driver-in-the-loop interacts with the dynamics model via this mock-up. OSI currently provides only limited interfaces for data flow between the driver and the dynamics model.

2.2.4. Coordinate systems and reference points

2.2.4.1. Coordinate systems, reference points and coordinate transformation

OSI uses DIN ISO 8855:2013-11 [6] for coordinate systems and transformations between coordinate systems. OSI uses the following coordinate systems:

Global coordinate system: Coordinate system for all entities that are part of ground truth. The global coordinate system is an inertial x/y/z-coordinate system. The origin is the global reference point that is determined by the environment simulation. This reference point may be derived from map data or other considerations. Global coordinates can be mapped to a geographic coordinate system via osi3::GroundTruth::proj_string.
Host vehicle coordinate system: The host vehicle coordinate system’s origin is defined to be at the center of the rear axle of the host vehicle.
Sensor coordinate system: Coordinate system for all entities that are part of sensor data. The origin is the mounting position of the physical sensor or a virtual mounting position, depending on the OSI message. Both physical and virtual sensor coordinate systems are relative to the host vehicle coordinate system.
Object coordinate system: Local object coordinate system. The origin of the corresponding coordinate system is not necessarily identical to the center of the object’s bounding box. If the origin of the corresponding coordinate system is not identical to the center of the object’s bounding box, the object documentation will provide the actual definition.

2.2.4.2. Coordinate transformations

Vehicle and sensor coordinate systems

When running simulations, it is frequently necessary to transform coordinates from the global coordinate system for a specific vehicle and its sensors.

This section provides an overview of the messages and fields involved and their relationship for this task. It demonstrates how a global coordinate system, vehicle coordinate system, and sensor coordinate system are related on the basis of a specific (ego) vehicle.

Mathematical Definitions of Coordinate Transformations

All vectors and matrices are noted with reference frame as a superscript index and the direction of translation as a subscript index. [7] The translation direction is from the first index to the second index (src: source coordinate system, trg: target coordinate system). The vector \(\boldsymbol{v}^x\) denotes the 3D position of an object in the coordinate frame \(x\). Vector \(\boldsymbol{t}\) is the translation vector between two coordinate systems with the described indices for reference frame and direction. The angles yaw \(\psi\) around the z-axis, pitch \(\theta\) around the y-axis and roll \(\phi\) around the x-axis are defined in a right handed coordinate system according to DIN ISO 8855:2013 [6]. The sign of the angles corresponds to the direction of the transformation.

Transformation from source \(src\) to target \(trg\) coordinates:

\[\boldsymbol{v}^{trg} = \boldsymbol{R}_{src}^{trg} (\boldsymbol{v}^{src} - \boldsymbol{t}_{src,trg}^{src})\]

Transformation back from target \(trg\) to source \(src\) coordinates

\[\boldsymbol{v}^{src} = (\boldsymbol{R}_{src}^{trg})^{-1} \boldsymbol{v}^{trg} + \boldsymbol{t}_{src,trg}^{src}\]

With the rotation matrix (from rotating the coordinate system) [8]:

\[\boldsymbol{R}_{src}^{trg}=\boldsymbol{R}_{yaw,pitch,roll} = \boldsymbol{R}_{z,y,x} = \boldsymbol{R}_{x}(\phi) \boldsymbol{R}_{y}(\theta) \boldsymbol{R}_{z}(\psi) \\ \boldsymbol{R}_{z,y,x} = \begin{pmatrix} 1 & 0 & 0\\ 0 & \cos(\phi) & \sin(\phi)\\ 0 & -\sin(\phi) & \cos(\phi) \end{pmatrix} \begin{pmatrix} \cos(\theta) & 0 & -\sin(\theta)\\ 0 & 1 & 0\\ \sin(\theta) & 0 & \cos(\theta) \end{pmatrix} \begin{pmatrix} \cos(\psi) & \sin(\psi) & 0\\ -\sin(\psi) & \cos(\psi) & 0\\ 0 & 0 &1 \end{pmatrix} \\ \boldsymbol{R}_{z,y,x} = \begin{pmatrix} \cos(\theta)\cos(\psi) & \cos(\theta)\sin(\psi) & -\sin(\theta)\\ \sin(\phi)\sin(\theta)\cos(\psi)-\cos(\phi)\sin(\psi) & \sin(\phi)\sin(\theta)\sin(\psi)+\cos(\phi)\cos(\psi) & \sin(\phi)\cos(\theta)\\ \cos(\phi)\sin(\theta)\cos(\psi)+\sin(\phi)\sin(\psi) & \cos(\phi)\sin(\theta)\sin(\psi)-\sin(\phi)\cos(\psi) & \cos(\phi)\cos(\theta) \end{pmatrix}\]

Get Tait–Bryan angles from rotation matrix [9]:

\[\theta = -\arcsin(R_{13}) \\ \psi = \arctan2(R_{12}/\cos(\theta),R_{11}/\cos(\theta)) \\ \phi = \arctan2(R_{23}/\cos(\theta),R_{33}/\cos(\theta))\]

Relative orientation:

Object rotation Matrix: \(\boldsymbol{R}_{object}^{src}\)
Host vehicle rotation Matrix: \(\boldsymbol{R}_{ego}^{src}\)
Resulting rotation matrix between object and host: \(\boldsymbol{R}_{object}^{src}(\boldsymbol{R}_{ego}^{src})^{T}\)

To transform from world coordinates into host vehicle coordinates and back use the formulas from above with the world coordinates frame \(w\) as source system \(src\) and host vehicle coordinates frame \(v\) as target system \(trg\). To transform from host vehicle coordinates into sensor coordinates and back use the formulas from above with the host vehicle coordinates frame \(v\) as source system \(src\) and sensor coordinates frame \(s\) as target system \(trg\).

Corresponding messages

GroundTruth::moving_object::base::position: This field defines the position of the vehicle’s reference point in global coordinates. In Open Simulation Interface, an object’s position is defined by the coordinates of the center of the object’s 3D bounding box.
GroundTruth::moving_object::base::orientation: This field defines the orientation of the vehicle’s reference point in global coordinates.
GroundTruth::moving_object::vehicle_attributes::bbcenter_to_rear: This field specifies the vector pointing from the vehicle’s reference point to the middle of the rear axle under neutral load conditions.
SensorData::mounting_position: This field defines the sensor’s virtual mounting position and orientation and thereby the origin of the virtual sensor coordinate system. The mounting position is given in the host vehicle coordinate system.

Example

The following image shows the relationship between the coordinate systems. The reference point of the vehicle is given by a vector in the global coordinate system. A vector pointing from the reference position of the vehicle to the center of the rear axle then yields the origin of the host vehicle coordinate system. The mounting positions of the sensors and therefore the origins of the corresponding sensor coordinate systems are given with respect to the host vehicle coordinate system.