Documentation Migration Preview

doc/architecture/architecture_overview.adoc

@@ -0,0 +1,36 @@
+= Overview of OSI architecture
+
+OSI contains an object-based environment description using the message format of the https://github.com/protocolbuffers/protobuf/wiki[Protocol Buffer] library developed and maintained by Google.
+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 ``SensorView``, ``SensorViewConfiguration`` and ``FeatureData`` interfaces.
+
+The following figure shows the interfaces and models involved in modeling a sensor.
+
+.Open Simulation Interface overview
+image::osi-context.png[1100]
+
+
+OSI also defines interfaces for traffic participant models.
+These interfaces allow to send commands to traffic participant models and to receive their updated state.
+The following figure shows the interfaces of a generic traffic participant.
+
+.Interface of a traffic participant
+image::osi-traffic-participant-principle.png[1100]
+
+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.
+
+.Traffic participant with sensor models, AD function, and dynamic model
+image::osi-traffic-participant-advanced.png[1100]
+
+OSI currently provides only limited support for data structures describing measured internal states of the traffic participant.
+Actuator intentions are currently not covered by OSI and must be handled with a different data description format.
+
+All fields in an 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.
+
+All field numbers of 10000 and upward are available for user-specific extensions via custom fields.
+Therefore, no future evolution of OSI will use field numbers of 10000 or above.

doc/architecture/data_layer.adoc

@@ -0,0 +1,10 @@
+= Data layer
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Et malesuada fames ac turpis egestas.
+Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi.
+Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis.
+Sed augue lacus viverra vitae congue eu. Velit ut tortor pretium viverra suspendisse.
+Amet commodo nulla facilisi nullam vehicula ipsum a.
+Nibh nisl condimentum id venenatis a.
+Diam vel quam elementum pulvinar etiam non quam lacus suspendisse.

doc/architecture/environmental_effect_model.adoc

@@ -0,0 +1,9 @@
+= Environmental effect model
+
+Environmental effect models consume sensor-view data and produce sensor-view data.
+Environmental effect models may, for example, include the following:
+
+* Shadows and oclusion
+* Weather effects
+* Physics of a sensor
+* Pre-processing of raw sensor data

doc/architecture/feature_data.adoc

@@ -0,0 +1,5 @@
+= Feature data
+
+Feature data contains detected features in the reference frame of a sensor.
+Feature data is generated from ground-truth data.
+It serves, for example, as input for sensor models simulating object detection or feature fusion models.

doc/architecture/formatting_scripts.adoc

@@ -0,0 +1,48 @@
+# Trace-file formatting scripts
+
+OSI provides Python scripts for converting trace files from one format to the other.
+The formatting scripts are stored in `open-simulation-interface/format/`
+
+**txt2osi.py**
+
+`txt2osi.py` converts plain-text trace files to binary `.osi` trace files.
+This script takes the following parameters:
+
+`--data`, `-d`::
+String containing the path to the file with serialized data.
+
+`--type`, `-t`::
+Optional string containing the name of the type used to serialize data.
+Allowed values are `'SensorView'`, `'GroundTruth'`, and `'SensorData'`.
+The default value is `'SensorView'`.
+
+`--output`, `-o`::
+Optional string containing the name of the output file.,
+The default value is `'converted.osi'`.
+
+`--compress`, `-c`::
+Optional boolean controlling whether to compress the output to a lzma file..
+Allowed values are `True`, and `False`.
+The default value is `False`.
+
+**osi2read.py**
+
+`osi2read.py` converts trace files to human-readable `.txth` trace files.
+This script takes the following parameters:
+
+`--data`, `-d`::
+String containing the path to the file with serialized data.
+
+`--type`, `-t`::
+Optional string containing the name of the type used to serialize data.
+Allowed values are `'SensorView'`, `'GroundTruth'`, and `'SensorData'`.
+The default value is `'SensorView'`.
+
+`--output`, `-o`::
+Optional string containing the name of the output file.,
+The default value is `'converted.txth'`.
+
+`--format`, `-f`::
+Optional string containing the format type of the trace.
+Allowed values are `'separated'`, and `None`.
+The default value is `None`.

doc/architecture/ground_truth.adoc

@@ -0,0 +1,5 @@
+= Ground truth
+
+Ground truth describes the simulated environment around all simulated objects in the global coordinate system.
+It is based on data available to the simulation environment and published to external subscribers.
+Depending on the external subscriber, ground-truth data may be individually restricted to reduce the data to be exchanged.

doc/architecture/logical_model.adoc

@@ -0,0 +1,6 @@
+= Logical model
+
+Logical models consume sensor-data data and produce sensor-data data.
+
+An example of a logical model is a sensor-fusion model, which fuses the output of multiple sensor models.
+Another use case is the injection of faults after the sensor model.

doc/architecture/packaging_layer.adoc

@@ -0,0 +1,9 @@
+= Packaging layer
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Et malesuada fames ac turpis egestas.
+Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi.
+Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis.
+Sed augue lacus viverra vitae congue eu. Velit ut tortor pretium viverra suspendisse.
+Amet commodo nulla facilisi nullam vehicula ipsum a. Nibh nisl condimentum id venenatis a.
+Diam vel quam elementum pulvinar etiam non quam lacus suspendisse.

doc/architecture/proto-files.adoc

@@ -0,0 +1,78 @@
+= Protobuffer files
+
+TODO: Add general description.
+
+osi_common.proto::
+TODO: Add description.
+
+osi_datarecording.proto::
+TODO: Add description.
+
+osi_detectedlane.proto::
+TODO: Add description.
+
+osi_detectedobject.proto::
+TODO: Add description.
+
+osi_detectedoccupant.proto::
+TODO: Add description.
+
+osi_detectedroadmarking.proto::
+TODO: Add description.
+
+osi_detectedtrafficlight.proto::
+TODO: Add description.
+
+osi_detectedtrafficsign.proto::
+TODO: Add description.
+
+osi_environment.proto::
+TODO: Add description.
+
+osi_featuredata.proto::
+TODO: Add description.
+
+osi_groundtruth.proto::
+TODO: Add description.
+
+osi_hostvehicledata.proto::
+TODO: Add description.
+
+osi_lane.proto::
+TODO: Add description.
+
+osi_logicaldetectiondata.proto::
+TODO: Add description.
+
+osi_object.proto::
+TODO: Add description.
+
+osi_occupant.proto::
+TODO: Add description.
+
+osi_roadmarking.proto::
+TODO: Add description.
+
+osi_sensordata.proto::
+TODO: Add description.
+
+osi_sensorspecific.proto::
+TODO: Add description.
+
+osi_sensorview.proto::
+TODO: Add description.
+
+osi_sensorviewconfiguration.proto::
+TODO: Add description.
+
+osi_trafficcommand.proto::
+TODO: Add description.
+
+osi_trafficlight.proto::
+TODO: Add description.
+
+osi_trafficsign.proto::
+TODO: Add description.
+
+osi_trafficupdate.proto::
+TODO: Add description.

doc/architecture/reference_points_coordinate_systems.adoc

@@ -0,0 +1,26 @@
+= Reference points and coordinate systems
+
+With Open Simulation Interface, an object's position coordinates refer to the center of the object's bounding box.
+This reference point is not necessarily identical to the origin of the respective coordinate systems.
+OSI uses DIN ISO 8855:2013-11 for coordinate systems and transformations between coordinate systems.
+
+OSI uses three coordinate systems:
+
+World coordinate system::
+Coordinate system for all quantities which are part of ground truth.
+The world coordinate system is an inertial x/y/z-coordinate system.
+
+Sensor coordinate system::
+Coordinate system for all quantities which are part of sensor data.
+The origin is the mounting position of the physical sensor or a virtual mounting position, depending on the technology.
+
+Object coordinate system::
+Coordinate system for local object coordinates, for example, vehicle coordinates.
+For vehicles, the origin is the middle of the rear axle projected onto the ground.
+Other objects may use different origins.
+
+The following image shows an example of the differents coordinate systems.
+It also shows that the reference point of the vehicle is located in the center of its bounding box whereas the origin of the vehicle coordinate system is the middle of rear axle projected onto the ground.
+In this example, the virtual mounting position coincides with the origin of the vehicle coordinate system.
+
+image::{imagedir}/osi_coordinate_systems.png[]

doc/architecture/sensor_data.adoc

@@ -0,0 +1,6 @@
+= Sensor data
+
+Sensor data imitates the output of real sensors.
+It is generated from ground-truth data, sensor-view data, feature data or from sensor data.
+All information regarding the environment is given with respect to the virtual sensor coordinate system, except for feature data, which 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.

doc/architecture/sensor_model.adoc

@@ -0,0 +1,6 @@
+= Sensor model
+
+Sensor models consume sensor-view data and produce sensor-data data.
+Those models can be based on physics or phenomenological.
+
+Sensor-model output does not represent raw data, but detected features or classified objects.

doc/architecture/sensor_view.adoc

@@ -0,0 +1,8 @@
+= Sensor view
+
+Sensor view imitates the input of sensors.
+Sensor-view data is derived from ground-truth data.
+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.
+* Ground-truth data, given in the global coordinate system.

doc/architecture/sensor_view_configuration.adoc

@@ -0,0 +1,11 @@
+= Sensor view configuration
+
+The sensor view configuration configures the sensor view.
+It is provided by the environment simulation.
+Sensor view configuration data is intended for the automatic configuration of an environment simulation in order to supply the necessary input to a sensor model.
+Sensor view configuration data is not intended to provide parameters to a generic sensor model. 
+
+Sensor view configuration data can also be provided by the sensor model to the environment simulation.
+In that case, it describes the input configuration that is desired by the sensor model.
+In response the environment simulation will configure the input and provide a new message which describes the actual configuration.
+These two messages may differ, when the environment simulation does not support a given requested configuration or when the requested configuration allowed is ambiguous.

doc/architecture/test_scripts.adoc

@@ -0,0 +1,45 @@
+= Test scripts
+
+TODO: Add general description.
+
+__init__.py::
+TODO: Add description.
+
+test_comment_type.py::
+TODO: Add description.
+
+test_doxygen_output.py::
+TODO: Add description.
+
+test_invalid_comment.py::
+TODO: Add description.
+
+test_invalid_enum.py::
+TODO: Add description.
+
+test_invalid_html.py::
+TODO: Add description.
+
+test_invalid_message.py::
+TODO: Add description.
+
+test_invalid_punctuation.py::
+TODO: Add description.
+
+test_invalid_tabs.py::
+TODO: Add description.
+
+test_newline.py::
+TODO: Add description.
+
+test_non_ascii.py::
+TODO: Add description.
+
+test_osi_trace.py::
+TODO: Add description.
+
+test_rules.py::
+TODO: Add description.
+
+test_units.py::
+TODO: Add description.

doc/architecture/trace_file_formats.adoc

@@ -0,0 +1,18 @@
+= OSI trace file formats
+
+There are multiple formats for storing multiple serialized OSI messages into one trace file
+
+*.osi::
+Binary trace file.
+Messages are separated by a length specifications before each message.
+The length is represented by a four-byte, little-endian, unsigned integer.
+The length does not include the integer itself.
+
+*.txt::
+Plain-text trace file.
+Messages are separated by `$$__$$`.
+
+*.txth::
+Human-readable plain-text trace file.
+Messages are separated by newlines.
+Such a filen may be used for manual checks.

doc/architecture/trace_file_naming.adoc

@@ -0,0 +1,21 @@
+= OSI trace file naming conventions
+
+**Name format**
+
+Names of OSI trace files should have the following format:
+
+[source]
+----
+<type>_<osi-version>_<protobuf-version>_<frame-number>_<custom-trace-name>.osi
+----
+
+**Types**
+
+`sd`::
+Trace file contains sensor-data messages.
+
+`sv`::
+Trace file contains sensor-view messages.
+
+`gt`::
+Trace file contains ground-truth messages.

doc/architecture/traffic_command.adoc

@@ -0,0 +1,3 @@
+= Traffic command
+
+Traffic commands contain control commands from the scenario engine to traffic participant models.