You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Simplified readme
* Used only python example and removed hashes
* Added console output of osi message
* Added links to Python and C++ protobufs
* Venv don't need sudo
* Added language colors
[TUM Department of Electrical and Computer Engineering](https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/)
11
-
12
-
13
-
Global remarks
14
-
--------------
15
-
All fields in the interface are set to optional and required is not used. This has been done to allow backward
16
-
compatible changes in the field. Additionally, this is the default behavior in protobuf version 3 that does no longer
17
-
have the required type and therefore ensures update compatibility.
18
-
However, this does not mean that filling the field is optional. For the purpose of providing a complete interface, all
19
-
existing fields should be set, unless not setting a field carries a specific meaning as indicated in the accompanying
20
-
comment.
21
-
22
-
23
-
Compatibility
24
-
--------------
25
-
Definition: FAITHFULLY "All recorded data is correctly interpreted by the interface"
26
-
27
-
Forward compatibility:
28
-
Definition: "An older version of the code can be used to read new files"
29
-
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.
30
-
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.
31
-
32
-
Backward compatibility:
33
-
Definition: "A newer version of code can be used to read old files"
34
-
All files that have been recorded in the past with a specific major version are FAITHFULLY valid with all combinations of
35
-
higher minor and patch versions of the same major version.
36
-
37
-
38
-
Fault injection: how-to
39
-
------------------------
40
-
Injection of pre-defined sensor errors should be handled by a specialized "fault injector" component that acts like a
41
-
sensor model component, i.e. it takes a SensorData message as input and returns a modified SensorData message as output.
42
-
Specific errors should be handled as follows:
43
-
- Ghost objects / false positive:
44
-
An additional SensorDataObject is added to the list of objects in SensorData.object
45
-
with SensorDataObject.model_internal_object.ground_truth_type set to kTypeGhost.
46
-
- False negative:
47
-
The object is marked as not seen by the sensor by setting the property
48
-
SensorDataObject.model_internal_object.is_seen to false. The implementation
49
-
of field-of-view calculation modules should respect this flag and never reset
50
-
an object marked as not-seen to seen.
51
-
52
-
53
-
Versioning
54
-
----------
55
-
The version number is defined in InterfaceVersion::version_number in osi_common.proto as the field's default value.
56
-
57
-
Major:
58
-
A change of the major version results in an incompatibility of code and recorded proto messages.
59
-
- An existing field with a number changes its meaning
60
-
`optional double field = 1;` -> `repeated double field = 1;`
61
-
Changing the definition of units or interpretation of a field
62
-
- Deleting a field and reusing the field number
63
-
- Changing the technology
64
-
ProtoBuffer -> FlatBuffer
65
-
66
-
Minor:
67
-
A change of the minor version indicates remaining compatibility to previously recorded files. The code on the other hand needs fixing.
68
-
- Renaming of a field without changing the field number
69
-
- Changing the names of messages
70
-
- Adding a new field in a message without changing the numbering of other fields
71
-
72
-
Patch:
73
-
The compatibility of both recorded files and code remains.
74
-
- File or folder structure which does not affect including the code in other projects
75
-
- Changing or adding comments
76
-
- Clarification of text passages explaining the message content
77
-
78
-
79
-
Proto3 Support
80
-
--------------
81
-
82
-
For users that need to use proto3 syntax, for example because the language
83
-
binding of choice only supports proto3 syntax out of the box, a shell script
84
-
called `convert-to-proto3.sh` is supplied that converts all proto files to
85
-
proto3 syntax. If this is run prior to building, the resulting libaries will
86
-
use proto3, with the on-the-wire format remaining compatible between proto2
87
-
and proto3 libraries.
88
-
89
-
Packaging
90
-
---------
91
-
92
-
A specification to package sensor models using OSI as (extended)
93
-
Functional Mock-up Units (FMUs) for use in simulation environments
94
-
is available [here](https://github.com/OpenSimulationInterface/osi-sensor-model-packaging).
95
-
96
-
97
-
Documentation
98
-
-------------
99
-
100
-
The actual documentation of the GitHub master branch is [online](https://opensimulationinterface.github.io/open-simulation-interface/) available.
101
-
102
-
Detailed information about installation and usage of OSI can be found in the [Wiki](https://github.com/OpenSimulationInterface/open-simulation-interface/wiki)
103
-
104
-
In order to generate the doxygen documentation for OSI, please follow the following steps:
105
-
1. Install [Doxygen](http://www.stack.nl/~dimitri/doxygen/download.html), set an environmental variable 'doxygen' with the path to the binary file and add it to the PATH variable: `PATH += %doxygen%`.
106
-
2. Download the [proto2cpp](https://github.com/OpenSimulationInterface/proto2cpp) repo.
107
-
Copy the content of the repo proto2cpp to your desired `<path-to-proto2cpp.py>`
108
-
3. Install [graphviz](https://graphviz.gitlab.io/_pages/Download/Download_windows.html), set an environmental variable 'graphviz' with the path to the binary file and add it to the PATH variable: `PATH += %graphviz%`.
109
-
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>`
110
-
5. The build process will then generate the doxygen documentation under the directory doc.
111
-
112
-
113
-
Citing
114
-
------
115
-
116
-
Use the following citation for referencing the OSI interface in your scientific work: `
117
-
@misc{osi.2017,
118
-
author = {Hanke, Timo and Hirsenkorn, Nils and {van~Driesten}, Carlo and {Garcia~Ramos}, Pilar and Schiementz, Mark and Schneider, Sebastian},
119
-
year = {2017},
120
-
title = {{Open Simulation Interface: A generic interface for the environment perception of automated driving functions in virtual scenarios.}},
The Open Simulation Interface <sup>[[1]](https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/)</sup> (OSI) is a generic interface based on [Google's protocol buffers](https://developers.google.com/protocol-buffers/) for the environmental perception of automated driving functions in virtual scenarios.
7
+
8
+
As the complexity of automated driving functions rapidly increases, the requirements for test and development methods are growing. Testing in virtual environments offers the advantage of completely controlled and reproducible environment conditions.
9
+
10
+
In this context, OSI defines generic interfaces to ensure modularity, integrability, and interchangeability of the individual components:
11
+
12
+
13
+
For more information on OSI see the [official documentation](https://opensimulationinterface.github.io/osi-documentation/) or the [official reference documentation](https://opensimulationinterface.github.io/open-simulation-interface/) for defined protobuf messages.
14
+
15
+
[[1]](https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/)*A generic interface for the environment perception of automated driving functions in virtual scenarios.(Dated 03.02.2017) T. Hanke, N. Hirsenkorn, C. van-Driesten, P. Garcia-Ramos, M. Schiementz, S. Schneider, E. Biebl*
16
+
17
+
## Usage
18
+
##### Example of writing and reading an OSI message in `Python`
19
+
```python
20
+
from osi3.osi_sensorview_pb2 import SensorView
21
+
from osi3.osi_sensordata_pb2 import SensorData
22
+
23
+
defmain():
24
+
"""Initialize SensorView and SensorData"""
25
+
sensorview = SensorView()
26
+
sensordata = SensorData()
27
+
28
+
"""Clear SensorData"""
29
+
sensordata.Clear()
30
+
31
+
"""Get boundary line attributes from SensorView"""
"""Clear SensorData to show parsing from string"""
54
+
sensordata.Clear()
55
+
56
+
"""The received string buffer can now be parsed"""
57
+
sensordata.ParseFromString(string_buffer)
58
+
59
+
"""Print SensorData"""
60
+
print(sensordata)
61
+
62
+
if__name__=="__main__":
63
+
main()
64
+
```
65
+
**Output**:
66
+
```bash
67
+
lane_boundary {
68
+
boundary_line {
69
+
position {
70
+
x: 1699.2
71
+
y: 100.16
72
+
z: 0.0
73
+
}
74
+
width: 0.13
75
+
height: 0.0
76
+
}
77
+
}
78
+
```
79
+
See Google's documentation for more tutorials on how to use protocol buffers with [Python](https://developers.google.com/protocol-buffers/docs/pythontutorial) or [C++](https://developers.google.com/protocol-buffers/docs/cpptutorial).
0 commit comments