Open Simulation Interface (OSI)

General description

TUM Department of Electrical and Computer Engineering

Global remarks

All fields in the interface are set to optional and required is not used. This has been done to allow backward compatible changes in the field. Additionally, this is the default behavior in protobuf version 3 that does no longer have the required type and therefore ensures update compatibility. However, this does not mean that filling the field is optional. 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.

Compatibility

Defintion: FAITHFULLY "All recorded data is correctly interpreted by the interface"

Forward compatibility: Definition: "An older version of the code can be used to read new files" Data recorded with a higher minor or patch version can be interpreted by code built using the same major version of the interface but lower minor and/or patch version. In this case, additional fields of a newer minor version are silently ignored. All patch versions of the same major and minor version are FAITHFULLY forward compatible.

Backward compatibility: Definition: "A newer version of code can be used to read old files" All files that have been recorded in the past with a specific major version are FAITHFULLY valid with all combinations of higher minor and patch versions of the same major version.

Fault injection: how-to

Injection of pre-defined sensor errors should be handled by a specialized "fault injector" component that acts like a sensor model component, i.e. it takes a SensorData message as input and returns a modified SensorData message as output. Specific errors should be handled as follows:

• Ghost objects / false positive: An additional SensorDataObject is added to the list of objects in SensorData.object with SensorDataObject.model_internal_object.ground_truth_type set to kTypeGhost.
• False negative: The object is marked as not seen by the sensor by setting the property SensorDataObject.model_internal_object.is_seen to false. The implementation of field-of-view calculation modules should respect this flag and never reset an object marked as not-seen to seen.

Versioning

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

Major: A change of the major version results in an incompatibility of code and recorded proto messages.

• An existing field with a number changes its meaning optional double field = 1; -> repeated double field = 1; Changing the definition of units of a field
• Deleting a field and reusing the field number
• Changing the technology ProtoBuffer -> FlatBuffer

Minor: A change of the minor version indicates remaining compatibility to previously recorded files. The code on the other hand needs fixing.

• Renaming of a field without changing the field number and the meanning of the field contents.
• Changing the names of messages without varing the meaning of the messages.
• Adding a new field in a message without changing the numbering of other fields, all new add fields are appended to the message due to field index numbers increment. The sorting of fields in minor version changing is logical based. A resorting to merge the logical and index will be performed in the coming major version changing.

Patch: The compatibility of both recorded files and code remains.

• File or folder structure which does not affect including the code in other projects
• Changing or adding comments
• Clarification of text passages explaining the message content

Compatibility: Major changes: If a major version changing occurs, the serialization and deserialization (separated on different locations & applications) are not compatibile. E.g. An OSI message that serilized in App_1 with OSI major.x.x locally built is NOT compatible to be deserilized in App_2 with OSI major +/- x.x.x locally built, and as versa.

Users have to update source codes if an upgrade of OSI major version changing in the application is needed.

Minor changes: If a minor version changing occurs, the serialization and deserialization (separated on different locations & applications) are compatibile. E.g. An OSI message that serilized in App_1 with OSI major.minor.x locally built is compatible to be deserilized in App_2 with OSI major.minor +/- x.x locally built, and as versa.

With the same major version, if an upgrade of OSI minor version in the application is needed, users might need to update the application source codes, when some new fields are necessary to use in the applciation but not defined in the OSI with last minor version release. As versa, when the new fields in the OSI minor version changing are un-used in the application, users are not obligated to update the source codes of the application.

Patch changes: With the same major and minor versions, the serialization and deserialization of OSI messages with different patch versions are compatible.

Packaging

A specification to package sensor models using OSI as (extended) Functional Mock-up Units (FMUs) for use in simulation environments is available here.

Documentation

Detailed information about installation and usage of OSI can be found in the Wiki

In order to generate the doxygen documentation for OSI, please follow the following steps:

1. Install Doxygen, set an environmental variable 'doxygen' with the path to the binary file and add it to the PATH variable: PATH += %doxygen%.
2. Download the vg-1.5.0.zip. Unpack and copy the content of folder /vg-1.5.0/contrib/proto2cpp to your desired <path-to-proto2cpp.py>
3. Install graphviz-2.38, set an environmental variable 'graphviz' with the path to the binary file and add it to the PATH variable: PATH += %graphviz%.
4. From the cmd navigate to the build directory and run:

cmake -DFILTER_PROTO2CPP_PY_PATH=<path-to-proto2cpp.py> <path-to-CMakeLists.txt>

5. The build process will then generate the doxygen documentation under the directory doc.

Citing

Use the following citation for referencing the OSI interface in your scientific work:

@misc{osi.2017,
        author = {Hanke, Timo and Hirsenkorn, Nils and {van~Driesten}, Carlo and {Garcia~Ramos}, Pilar and Schiementz, Mark and Schneider, Sebastian},
        year = {2017},
        title = {{Open Simulation Interface: A generic interface for the environment perception of automated driving functions in virtual scenarios.}},
        url = {http://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/},
        note = {{Accessed: 2017-08-28}}
}