A generic interface for the environmental perception of automated driving functions in virtual scenarios.
LudwigFriedmannBMW Merge pull request #267 from OpenSimulationInterface/Moving-Objects-r…
…elative-velocity-definition

Update Definition solves #234
Latest commit d144f0c Aug 20, 2018
Permalink
Failed to load latest commit information.
doc/images Images Aug 17, 2018
.clang-format update documentation Aug 20, 2018
.gitignore Add figures to OSI-Documentation Aug 15, 2018
.travis.yml Add proto3 support via script to map file syntax Jun 4, 2018
CMakeLists.txt OSI V3 correct cmake version check and install (#217) Apr 24, 2018
LICENSE Update LICENSE Nov 15, 2017
README.md Add proto3 support via script to map file syntax Jun 4, 2018
VERSION Documenation/GitHub pages (#214) Apr 25, 2018
convert-to-proto3.sh Add proto3 support via script to map file syntax Jun 4, 2018
doxygen_config.cmake.in Documentation/v3.0.1 update 7 (#224) Apr 27, 2018
open_simulation_interface-config-version.cmake.in Documentation/v3.0.1 update 7 (#224) Apr 27, 2018
open_simulation_interface-config.cmake.in Add CMake package install option Feb 8, 2018
osi_common.proto Merge branch 'master' into Moving-Objects-relative-velocity-definition Aug 20, 2018
osi_datarecording.proto Removed SensorDataList, created classification for occupant Mar 29, 2018
osi_detectedlane.proto Additional clang reformating Aug 15, 2018
osi_detectedobject.proto Merge branch 'master' into Moving-Objects-relative-velocity-definition Aug 20, 2018
osi_detectedoccupant.proto Remove doxygen link bugs Apr 18, 2018
osi_detectedroadmarking.proto Add figures to OSI-Documentation Aug 15, 2018
osi_detectedtrafficlight.proto Add figures to OSI-Documentation Aug 15, 2018
osi_detectedtrafficsign.proto Additional clang reformating Aug 15, 2018
osi_environment.proto Additional clang reformating Aug 15, 2018
osi_featuredata.proto Enhance documentation as per issue #250 Jul 31, 2018
osi_groundtruth.proto Additional clang reformating Aug 15, 2018
osi_hostvehicledata.proto Add figures to OSI-Documentation Aug 15, 2018
osi_lane.proto update documentation Aug 20, 2018
osi_object.proto Add figures to OSI-Documentation Aug 15, 2018
osi_occupant.proto Additional clang reformating Aug 15, 2018
osi_roadmarking.proto Add figures to OSI-Documentation Aug 15, 2018
osi_sensordata.proto Merge branch 'master' into Moving-Objects-relative-velocity-definition Aug 20, 2018
osi_sensorspecific.proto Corrected missing BaseStationary in DetectedLandmarks Mar 29, 2018
osi_sensorview.proto Additional clang reformating Aug 15, 2018
osi_sensorviewconfiguration.proto Additional clang reformating Aug 15, 2018
osi_trafficlight.proto Add figures to OSI-Documentation Aug 15, 2018
osi_trafficsign.proto Additional clang reformating Aug 15, 2018
osi_version.proto.in Documentation/v3.0.1 update 7 (#224) Apr 27, 2018
setup.py Fix python3 relative import issue and setup.py Aug 10, 2018
test_cases.py Update Testcases Aug 17, 2018
test_cases_doc.py Documentation/v3.0.1 update 7 (#224) Apr 27, 2018

README.md

Open Simulation Interface (OSI)

Travis Build Status

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

Definition: 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 or interpretation 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
  • Changing the names of messages
  • Adding a new field in a message without changing the numbering of other fields

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

Proto3 Support

For users that need to use proto3 syntax, for example because the language binding of choice only supports proto3 syntax out of the box, a shell script called convert-to-proto3.sh is supplied that converts all proto files to proto3 syntax. If this is run prior to building, the resulting libaries will use proto3, with the on-the-wire format remaining compatible between proto2 and proto3 libraries.

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

The actual documentation of the GitHub master branch is online available.

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 proto2cpp repo. Copy the content of the repo proto2cpp to your desired <path-to-proto2cpp.py>
  3. Install graphviz, 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: cmd 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}} }