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

max-rosin · max-rosin · commit 42673d690496 · 2021-08-06T14:30:06.000+02:00
Signed-off-by: Maximilian Rosin &lt;maximilian.rosin@parson-europe.com&gt;
diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc
@@ -46,3 +46,7 @@ The default value is `'converted.txth'`.
 Optional string containing the format type of the trace file.
 Allowed values are `'separated'`, or `None`.
 The default value is `None`.
+
+**Related topics**
+
+* xref:#top-1a2f4b0c-195c-4f18-89ad-d48a123bd8c1[OSI trace file formats]
diff --git a/doc/architecture/reference_points_coordinate_systems.adoc b/doc/architecture/reference_points_coordinate_systems.adoc
@@ -4,11 +4,11 @@ OSI uses DIN ISO 8855:2013-11 for coordinate systems and transformations between
 OSI uses three coordinate systems:
 
 World coordinate system::
-Coordinate system for all quantities which are part of ground truth.
+Coordinate system for all entities 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.
+Coordinate system for all entities 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::
diff --git a/doc/architecture/sensor_view_configuration.adoc b/doc/architecture/sensor_view_configuration.adoc
@@ -5,7 +5,7 @@ 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 is not intended to provide parameters to a 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.
diff --git a/doc/architecture/trace_file_formats.adoc b/doc/architecture/trace_file_formats.adoc
@@ -1,10 +1,11 @@
+[#top-1a2f4b0c-195c-4f18-89ad-d48a123bd8c1]
 = 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.
+Messages are separated by a length specification before each message.
 The length is represented by a four-byte, little-endian, unsigned integer.
 The length does not include the integer itself.
 
@@ -15,4 +16,4 @@ 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.
+Such a file may be used for manual checks.
diff --git a/doc/misc/osi_vision.adoc b/doc/misc/osi_vision.adoc
@@ -1,6 +1,5 @@
 = The idea of Open Simulation Interface
 
 The Open Simulation Interface (OSI) is a specification for interfaces between models and components of a distributed simulation.
-OSI uses Google's Protocol Buffers.
 OSI has a strong focus on environmental perception of automated driving functions.
 However, OSI also specifies interfaces for modeling traffic participants.
diff --git a/doc/releases/v02.00.adoc b/doc/releases/v02.00.adoc
@@ -5,7 +5,9 @@ This is the initial version of the Open Simulation Interface (OSI).
 
 == Overview
 
-OSI is a generic interface for the environmental perception of automated driving functions in virtual scenarios. It is primarily conceived to enable easy and straightforward compatibility between automated driving functions and the variety of driving simulation frameworks available. The data description has been derived from the perspective of sensor modeling for automated test and validation of highly automated driving functions.
+OSI is a generic interface for the environmental perception of automated driving functions in virtual scenarios.
+It is primarily conceived to enable easy and straightforward compatibility between automated driving functions and the variety of driving simulation frameworks available.
+The data description has been derived from the perspective of sensor modeling for automated test and validation of highly automated driving functions.
 
 == Implementation
 
@@ -17,9 +19,14 @@ OSI primarily contains an object based environment description using the message
 Top level interfaces::
 OSI consists of two individual top level interfaces for object data: The ``OSI::GroundTruth`` and the ``OSI::SensorData`` interface.
 +
-* The ``OSI::GroundTruth`` interface provides an exact view on the simulated objects in a global coordinate system. This message is populated using the internally available data of the used (driving)-simulation framework and is afterwards published to external subscribers with an exporter plugin.
-* The ``OSI::SensorData`` interface describes the objects in the reference frame of a sensor for environmental perception. It is generated from a ``OSI::GroundTruth`` message and can either be used to directly connect to an automated driving function using ideal simulated data, or may serve as input for a sensor model simulating limited perception as a replication of real world sensor behavior.
+* The ``OSI::GroundTruth`` interface provides an exact view on the simulated objects in a global coordinate system.
+This message is populated using the internally available data of the used (driving)-simulation framework and is afterwards published to external subscribers with an exporter plugin.
+* The ``OSI::SensorData`` interface describes the objects in the reference frame of a sensor for environmental perception.
+It is generated from a ``OSI::GroundTruth`` message and can either be used to directly connect to an automated driving function using ideal simulated data, or may serve as input for a sensor model simulating limited perception as a replication of real world sensor behavior.
 
 Low level interfaces::
 +
-Additionally to the two top level interfaces, OSI contains an ``OSI::LowLevelData`` message. This message describes the output of a (physical) model of the measurement process before tracking and object hypothesis. It does not deal with object data, but may comprise the geometrical influence of 3D simulations e.g. generating Lidar point clouds with a ray-tracer plugin. In addition this message supports generic radar reflection lists and will be extended to supporting low level camera data in the future.
+Additionally to the two top level interfaces, OSI contains an ``OSI::LowLevelData`` message.
+This message describes the output of a (physical) model of the measurement process before tracking and object hypothesis.
+It does not deal with object data, but may comprise the geometrical influence of 3D simulations e.g. generating Lidar point clouds with a ray-tracer plugin.
+In addition this message supports generic radar reflection lists and will be extended to supporting low level camera data in the future.
diff --git a/doc/releases/v03.00.adoc b/doc/releases/v03.00.adoc
@@ -2,7 +2,8 @@
 
 == Purpose
 
-This release is a complete rework including the feedback from many OSI users. Thank you!
+This release is a complete rework including the feedback from many OSI users.
+Thank you!
 We are aligned with the ongoing discussions for the upcoming ISO 23150 standard for hardware sensor outputs in order to bring simulation and the hardware in the car closer together.
 
 == https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.0[Content/Changes]
diff --git a/doc/releases/v03.02.adoc b/doc/releases/v03.02.adoc
@@ -4,7 +4,8 @@ https://www.youtube.com/watch?v=SJUhlRoBL8M[Think p(OSI)tive!]
 
 == Purpose
 
-The work on the OSI project was until now mainly organized by the BMW AG. In order to enable as many interested parties as possible to contribute to the success of the Open Simulation Interface the project has been transferred to the https://www.asam.net/[ASAM e.V.] which has been made public in the https://www.asam.net/news-media/news/detail/news/bmw-transfers-open-simulation-interface-osi-to-asam/[ASAM press release].
+The work on the OSI project was until now mainly organized by the BMW AG.
+In order to enable as many interested parties as possible to contribute to the success of the Open Simulation Interface the project has been transferred to the https://www.asam.net/[ASAM e.V.] which has been made public in the https://www.asam.net/news-media/news/detail/news/bmw-transfers-open-simulation-interface-osi-to-asam/[ASAM press release].
 A new chapter in the development of OSI is now opened with the https://www.asam.net/conferences-events/detail/asam-osi-kick-off-workshop/[kickoff workshop] leading to hopefully many project proposals streamlining the efficient future development of the interface.
 Due to this we decided to focus on the improvement of processes and documentation with this release.
 
diff --git a/doc/releases/v03.03.adoc b/doc/releases/v03.03.adoc
@@ -19,7 +19,8 @@ This minor release highlights the work that has been done on several working pac
 * Add global model reference to ground truth that can be used to specify the 3D model representing the environment.
 * Extended the camera sensor view configuration to better support the configuration of the simulation environment.
 * Added a new field to describe the position of the steering wheel.
-* Added a message MovingObjectClassification for classify-able attributes that are shared between different moving object types. Introduced the assigned lane id and the assigned lane percentage of a moving object there.
+* Added a message MovingObjectClassification for classify-able attributes that are shared between different moving object types.
+  Introduced the assigned lane id and the assigned lane percentage of a moving object there.
 
 * Updated to checklist for pull requests to provide clearer orientation for all users.
 * Updated the documentation of centerline and lane boundaries (ordering of the points, describing those lines).
diff --git a/doc/releases/versioning.adoc b/doc/releases/versioning.adoc
@@ -10,10 +10,10 @@ A change of the major version results in an incompatibility of code and recorded
 Major changes include:
 +
 * An existing field with a number changes its meaning.
-Example: `optional double field = 1;` -> `repeated double field = 1;`.
-* Changing the definition of units or interpretation of a field.
+Example: `optional double field = 1;` changes to `repeated double field = 1;`.
+* Changing the definition of units or the interpretation of a field.
 * Deleting a field and reusing the field number.
-* Changing the technology ProtoBuffer -> FlatBuffer.
+* Changing the technology from Protocol Buffer to FlatBuffer.
 
 Minor::
 A change of the minor version indicates remaining compatibility to previously recorded files.
diff --git a/doc/usecases/modeling_traffic_participant.adoc b/doc/usecases/modeling_traffic_participant.adoc
@@ -30,7 +30,7 @@ The following figure shows a more complex traffic participant.
 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 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.
