Migration to AsciiDoc

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "asciidoc-resources"]
+	path = asciidoc-resources
+	url = https://code.asam.net/simulation/asciidoc-resources.git

doc/architecture/architecture_overview.adoc

@@ -0,0 +1,39 @@
+= 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::{images_open_simulation_interface}/osi-context.png[1100]
+
+
+OSI also defines interfaces for traffic participant models.
+The ``TrafficCommand`` interface allows to send commands to traffic participant models.
+The ``TrafficUpdate`` interface allows to receive their updated state.
+The following figure shows the interfaces of a generic traffic participant.
+
+.Interface of a traffic participant
+image::{images_open_simulation_interface}/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::{images_open_simulation_interface}/osi-traffic-participant-advanced.png[1100]
+
+The ``HostVehicleData`` interface describes the measured internal states of a traffic participant
+OSI currently provides only limited support for data structures describing measured internal states traffic participants.
+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`.
+`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 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 equal to or greater than 10000 are available for user-specific extensions via custom fields.
+Therefore, no future evolution of OSI will use field numbers equal to or greater than 10000.

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 messages and produce sensor-view messages.
+Environmental effect models may, for example, alter sensor-view messages to include effects and phenomena caused by:
+
+* Shadows and occlusions
+* 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 messages contains detected features in the reference frame of a sensor.
+Feature-data messages are generated from ground-truth messages.
+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
+
+The OSI repository contains 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 describing the message type used to serialize data.
+Allowed values are `'SensorView'`, `'GroundTruth'`, or `'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`, or `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 describing the message type used to serialize data.
+Allowed values are `'SensorView'`, `'GroundTruth'`, or `'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 file.
+Allowed values are `'separated'`, or `None`.
+The default value is `None`.

doc/architecture/ground_truth.adoc

@@ -0,0 +1,5 @@
+= Ground truth
+
+Ground-truth messages describe the simulated environment around all simulated objects in the global coordinate system at consecutive time instances.
+It is based on data available to the simulation environment and is published to external subscribers.
+Depending on the external subscriber, ground-truth messages 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 messages and produce sensor-data 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.

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,17 @@
+= Coordinate systems and reference points
+
+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.
+The origin of the corresponding coordinate systems is not necessarily identical to the center of the object's bounding box.
+For example with vehicles, the origin is the middle of the rear axle projected onto the ground.

doc/architecture/sensor_data.adoc

@@ -0,0 +1,7 @@
+= Sensor data
+
+Sensor-data messages imitate the output of real sensors.
+It can be generated from ground-truth messages, sensor-view messages, feature-data messages or from sensor-data messages.
+Except 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.

doc/architecture/sensor_model.adoc

@@ -0,0 +1,6 @@
+= Sensor model
+
+Sensor models consume sensor-view messages and produce sensor-data messages.
+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 messages are derived from ground-truth 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.
+* Ground truth, given in the global coordinate system.

doc/architecture/sensor_view_configuration.adoc

@@ -0,0 +1,15 @@
+= Sensor view configuration
+
+The sensor view configuration configures the sensor view.
+There are two sources for sensor-view-configuration data.
+
+Sensor-view-configuration data can be provided by the environment simulation.
+In this case, the 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 this case, the data 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.
+The configuration requested by the sensor model may differ from the actual configuration.
+This happens when the environment simulation does not support a given requested configuration or when the requested configuration allowed is ambiguous.
+The message describing the requested configuration differs from the message describing the actual configuration.

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.