fix(docs): Implement review comments (#549)

max-rosin · max-rosin · commit ac9ecd2df395 · 2021-07-13T13:50:37.000+02:00
Signed-off-by: Maximilian Rosin &lt;maximilian.rosin@parson-europe.com&gt;
diff --git a/doc/architecture/environmental_effect_model.adoc b/doc/architecture/environmental_effect_model.adoc
@@ -1,7 +1,7 @@
 = Environmental effect model
 
-Environmental effect models consume sensor-view data and produce sensor-view data.
-Environmental effect models may, for example, include the following:
+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
diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc
@@ -12,8 +12,8 @@ This script takes the following parameters:
 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'`.
+Optional string describing the message type used to serialize data.
+Allowed values are `'SensorView'`, `'GroundTruth'`, or `'SensorData'`.
 The default value is `'SensorView'`.
 
 `--output`, `-o`::
@@ -22,7 +22,7 @@ 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`.
+Allowed values are `True`, or `False`.
 The default value is `False`.
 
 **osi2read.py**
@@ -35,14 +35,14 @@ 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'`.
+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.
-Allowed values are `'separated'`, and `None`.
+Optional string containing the format type of the trace file.
+Allowed values are `'separated'`, or `None`.
 The default value is `None`.
diff --git a/doc/architecture/ground_truth.adoc b/doc/architecture/ground_truth.adoc
@@ -1,5 +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.
+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.
diff --git a/doc/architecture/logical_model.adoc b/doc/architecture/logical_model.adoc
@@ -1,6 +1,6 @@
 = Logical model
 
-Logical models consume sensor-data data and produce sensor-data data.
+Logical models consume sensor-data messages and produce sensor-data messages.
 
-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.
+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.
diff --git a/doc/architecture/sensor_data.adoc b/doc/architecture/sensor_data.adoc
@@ -1,7 +1,7 @@
 = Sensor data
 
-Sensor data imitates the output of real sensors.
-It can be generated from ground-truth data, sensor-view data, feature data or from 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.
diff --git a/doc/architecture/sensor_model.adoc b/doc/architecture/sensor_model.adoc
@@ -1,6 +1,6 @@
 = Sensor model
 
-Sensor models consume sensor-view data and produce sensor-data data.
+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.
diff --git a/doc/architecture/sensor_view.adoc b/doc/architecture/sensor_view.adoc
@@ -1,8 +1,8 @@
 = Sensor view
 
 Sensor view imitates the input of sensors.
-Sensor-view data is derived from ground-truth data.
+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 data, given in the global coordinate system.
+* Ground truth, given in the global coordinate system.
diff --git a/doc/architecture/traffic_command.adoc b/doc/architecture/traffic_command.adoc
@@ -1,3 +1,3 @@
 = Traffic command
 
-Traffic commands contain control commands from the scenario engine to traffic participant models.
+Traffic-command messages contain control commands from the scenario engine to traffic participant models.
diff --git a/doc/architecture/traffic_participant.adoc b/doc/architecture/traffic_participant.adoc
@@ -23,7 +23,7 @@ The following figure shows a more advanced use case for traffic participants.
 .Traffic participant using other OSI interfaces internally
 image::{images_open_simulation_interface}/osi-traffic-participant-advanced.png[1100]
 
-With every simulation step, an OSI traffic participant model receives ground truth data from the environment around itself, the sensor view.
+With every simulation step, an OSI traffic participant model receives ground-truth data from the environment around itself, the sensor view.
 A traffic participant can output its own perceivable state, the traffic update.
 Traffic commands influence the behavior of the traffic participant model.
 They allow event-based communication towards the traffic participant, that is, at certain simulation steps.
diff --git a/doc/architecture/traffic_update.adoc b/doc/architecture/traffic_update.adoc
@@ -1,4 +1,4 @@
 = Traffic update
 
-Traffic updates are provided by traffic participants.
+Traffic-update messages are provided by traffic participants.
 They provide updates of the position, state and future trajectory of a traffic participant back to the simulation environment.
diff --git a/doc/images/osi-traffic-participant-use-case-1.png b/doc/images/osi-traffic-participant-use-case-1.png
diff --git a/doc/images/osi-traffic-participant-use-case-2.png b/doc/images/osi-traffic-participant-use-case-2.png
diff --git a/doc/images/osi-traffic-participant-use-case-3.png b/doc/images/osi-traffic-participant-use-case-3.png
diff --git a/doc/images/osi-traffic-participant-use-case-4.png b/doc/images/osi-traffic-participant-use-case-4.png
diff --git a/doc/open-simulation-interface_user_guide.adoc b/doc/open-simulation-interface_user_guide.adoc
@@ -50,6 +50,8 @@ include::./architecture/logical_model.adoc[leveloffset=+3]
 
 include::./architecture/traffic_participant.adoc[leveloffset=+3]
 
+include::./usecases/modeling_traffic_participant.adoc[leveloffset=+3]
+
 //include::./architecture/vehicle_dynamics.adoc[leveloffset=+3]
 
 === Coordinate systems and reference points
diff --git a/doc/usecases/modeling_traffic_participant.adoc b/doc/usecases/modeling_traffic_participant.adoc
@@ -1,10 +1,48 @@
 = Modeling a traffic participant
 
-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.
+Different models may be involved in modeling a traffic participant.
+In all the use cases, a simulator loads and interprets a scenario and a map prior to execution.
+The scenario is, for example, provided by OpenSCENARIO.
+The map data is, for example, provided by OpenDRIVE.
+During runtime the simulator interacts with the traffic participants via OSI messages.
+There may be multiple instances of a traffic participant.
+The traffic participants are co-simulated.
+
+The following figure shows a very simple use case.
+
+.Simple traffic participant
+image::{images_open_simulation_interface}/osi-traffic-participant-use-case-1.png[1100]
+
+The traffic participant bases its behavior only on an idealized view of the area around it.
+If they exist, the traffic participant’s dynamics are included in the model.
+
+The following figure shows a traffic participant with separately modeled behavior and dynamics.
+
+.Traffic participants with separate dynamics
+image::{images_open_simulation_interface}/osi-traffic-participant-use-case-2.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.
+
+The following figure shows a more complex traffic participant.
+
+.Traffic participant with sensor models, AD function, and dynamics model
+image::{images_open_simulation_interface}/osi-traffic-participant-use-case-3.png[1100]
+
+This use case will probably be relevant for modeling the ego vehicle, which includes the system-under-test.
+The traffic participant includes an arbitrary number of sensor models
+The sensor models consume sensor view and produce sensor data.
+The AD function consumes sensor data and produces input for the dynamics model.
+OSI currently does not support data flow to dynamics models.
+The loop to the environment simulation is closed via traffic update.
+
+The following figure shows a cooperative use case with both an AD function and a human driver.
+
+.Traffic participant with an AD function and a human driver
+image::{images_open_simulation_interface}/osi-traffic-participant-use-case-4.png[1100]
+
+It is possible to model a traffic participant with an AD function in the loop, but a human driver can still override the actuation command.
+Such a cooperative use case is, for example, relevant to studies on human-machine interaction.
+In this example, a virtual on-screen representation of the scenario, or mock-up, is added after the AD function.
+The driver-in-the-loop interacts with the dynamics model via this mock-up.
+OSI's limitations regarding dynamics-model input apply in this example as well.

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,3 @@`
`1`	`1`	`= Traffic command`
`2`	`2`
`3`		`-Traffic commands contain control commands from the scenario engine to traffic participant models.`
	`3`	`+Traffic-command messages contain control commands from the scenario engine to traffic participant models.`