Describe top-level messages (#506)

max-rosin · max-rosin · commit ed79c7092331 · 2021-07-07T14:19:02.000+02:00
Signed-off-by: Maximilian Rosin &lt;maximilian.rosin@parson-europe.com&gt;
diff --git a/doc/architecture/feature_data.adoc b/doc/architecture/feature_data.adoc
@@ -1,10 +1,5 @@
 = Feature data
 
-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.
+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.
diff --git a/doc/architecture/ground_truth.adoc b/doc/architecture/ground_truth.adoc
@@ -1,10 +1,11 @@
 = Ground truth
 
-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.
+Ground truth describes the simulated environment around all simulated host vehicles in a global coordinate system.
+Ground truth provides an exact view on the simulated objects in a global coordinate system.
+It is based on internally available data and published to external subscribers.
+Depending on the external subscriber, ground-truth data may be individually restricted.
+
+//TODO: It looks like we may have two conflicting descriptions here.
+// I cannot tell which one is correct or if they are conflicting at all.
+// The first sentence is based on the comments in the proto files.
+// The second sentence is based on the description on Github pages.
diff --git a/doc/architecture/sensor_data.adoc b/doc/architecture/sensor_data.adoc
@@ -1,9 +1,6 @@
 = Sensor data
 
-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.
+Sensor data imitates the output of real sensors.
+It is generated from ground-truth 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 of an automated driving function,  a sensor model simulating limited perception, or a sensor fusion model.
diff --git a/doc/architecture/sensor_view.adoc b/doc/architecture/sensor_view.adoc
@@ -1,9 +1,8 @@
 = Sensor view
 
-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.
+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:
+
+* Individual 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 global coordinates.
diff --git a/doc/architecture/sensor_view_configuration.adoc b/doc/architecture/sensor_view_configuration.adoc
@@ -1,9 +1,11 @@
 = Sensor view configuration
 
-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.
+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.
