Merge pull request #576 from OpenSimulationInterface/documentation/native-speaker-review

Stefan Cyliax · web-flow · commit d36ce8862356 · 2021-09-10T20:54:48.000+02:00
docs: native speaker review
diff --git a/doc/architecture/architecture_overview.adoc b/doc/architecture/architecture_overview.adoc
@@ -1,7 +1,7 @@
 = Overview of OSI architecture
 
 OSI contains an object-based environment description that uses the message format of the https://github.com/protocolbuffers/protobuf/wiki[Protocol Buffer] library.
-The Protocol Buffer library was developed and is maintained by Google.
+Google developed and maintains the Protocol Buffer library.
 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 interfaces `SensorView`, `SensorViewConfiguration`, and `FeatureData`.
 
@@ -27,15 +27,15 @@ image::{images_open_simulation_interface}/osi-traffic-participant-advanced.png[1
 
 The `HostVehicleData` interface describes the measured internal states of a traffic participant.
 OSI currently provides only limited support for data structures that describe measured internal states of traffic participants.
-Actuator intentions are currently not covered by OSI and must be handled with a different data description format.
+Actuator intentions are currently not covered by OSI and must be handled using 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.
+Additionally, this is the default behavior in Protocol Buffer version 3 that no longer has the `required` type.
 Setting all fields to `optional` thus 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.
+However, this does not mean that it is optional to fill the field.
+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.
+No future evolution of OSI will therefore use field numbers equal to or greater than 10000.
diff --git a/doc/architecture/data_layer.adoc b/doc/architecture/data_layer.adoc
@@ -1,14 +1,14 @@
 = Data layer
 
-The data layer of OSI is defined in the message specifications using the ProtoBuf IDL.
-It defines the data that can be transmitted using OSI, including the structure and the semantics of the data.
+The OSI data layer is defined in the message specifications using the ProtoBuf IDL.
+This defines the data that can be transmitted using OSI, including the structure and the semantics of the data.
 
 Additionally, it specifies the encoding to be used when OSI data is transmitted.
 Currently, ProtoBuf encoding is used, but other encodings are possible with the ProtoBuf IDL.
 FlatBuffer encoding has been implemented as an experimental feature.
 
 The data layer does not directly define components and transmission routes.
-These are defined in the packaging layer of OSI.
+These are defined in the OSI packaging layer.
 There may be different packaging layer implementations using the shared data layer definitions.
 The data that is exchanged remains compatible regardless of the packaging layer implementation.
 The use of a shared data layer ensures easy bridging between different packaging layer implementations.
diff --git a/doc/architecture/feature_data.adoc b/doc/architecture/feature_data.adoc
@@ -2,4 +2,4 @@
 
 Feature-data messages contain detected features in the reference frame of a sensor.
 Feature-data messages are generated from ground-truth messages.
-They serve, for example, as input to sensor models simulating object detection or feature fusion models.
+They serve, for example, as an input to sensor models simulating object detection or feature fusion models.
diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc
@@ -1,6 +1,6 @@
 = Trace-file formatting scripts
 
-The OSI repository contains Python scripts for converting trace files from one format to the other.
+The OSI repository contains Python scripts for converting trace files from one format to another.
 The formatting scripts are stored in `open-simulation-interface/format/`
 
 **txt2osi.py**
@@ -13,16 +13,16 @@ 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'`.
+`'SensorView'`, `'GroundTruth'`, or `'SensorData'` are permitted values.
 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`.
+Optional Boolean controlling whether to compress the output to an lzma file.
+`True`, or `False` are permitted values.
 The default value is `False`.
 
 **osi2read.py**
@@ -35,7 +35,7 @@ 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'`.
+`'SensorView'`, `'GroundTruth'`, or `'SensorData'` are permitted values.
 The default value is `'SensorView'`.
 
 `--output`, `-o`::
@@ -44,7 +44,7 @@ The default value is `'converted.txth'`.
 
 `--format`, `-f`::
 Optional string containing the format type of the trace file.
-Allowed values are `'separated'`, or `None`.
+`'separated'`, or `None` are permitted values.
 The default value is `None`.
 
 **Related topics**
diff --git a/doc/architecture/ground_truth.adoc b/doc/architecture/ground_truth.adoc
@@ -1,5 +1,5 @@
 = Ground truth
 
 Ground-truth messages describe the simulated environment containing all simulated objects in the global coordinate system at consecutive time instances.
-It is based on data available to the simulation environment.
-Typically, ground-truth messages are contained in sensor view messages.
+They are based on data available to the simulation environment.
+Ground-truth messages are typically contained in sensor view messages.
diff --git a/doc/architecture/packaging_layer.adoc b/doc/architecture/packaging_layer.adoc
@@ -1,8 +1,8 @@
 = Packaging layer
 
-The packaging layer of OSI specifies how components that use the OSI data layer, for example, sensor models, are packaged for exchange.
+The OSI packaging layer specifies how components that use the OSI data layer, for example, sensor models, are packaged for exchange.
 
-It specifies model types and their mandatory and optional OSI inputs, OSI outputs, and parameter interfaces.
+This specifies model types and their mandatory and optional OSI inputs, OSI outputs, and parameter interfaces.
 A model type may be, for example, a sensor model or a traffic participant model.
 The packaging layer also specifies component technology standards.
 This makes it possible to encapsulate model types in easily exchangeable component packages that can be used across platforms and implementations.
diff --git a/doc/architecture/sensor_data.adoc b/doc/architecture/sensor_data.adoc
@@ -1,7 +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.
+They can be generated from ground-truth messages, sensor-view messages, feature-data messages, or sensor-data messages.
+With the exception of 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_view.adoc b/doc/architecture/sensor_view.adoc
@@ -5,5 +5,5 @@ 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.
-  Example of technology-specific data: https://opensimulationinterface.github.io/open-simulation-interface/structosi3_1_1CameraSensorView.html#ac58456a34babf78792ea2608eb963f36[`image_data` of `osi3::CameraSensorView`]
-* Ground truth, given in the global coordinate system.
+  One example of technology-specific data is: https://opensimulationinterface.github.io/open-simulation-interface/structosi3_1_1CameraSensorView.html#ac58456a34babf78792ea2608eb963f36[`image_data` of `osi3::CameraSensorView`]
+* Ground truth given in the global coordinate system.
diff --git a/doc/architecture/sensor_view_configuration.adoc b/doc/architecture/sensor_view_configuration.adoc
@@ -1,27 +1,27 @@
 = Sensor view configuration
 
-The sensor view is flexibly defined to provide different kinds of sensor models with appropriate input.
+The sensor view is flexibly defined to provide different kinds of sensor models with an appropriate input.
 The sensor view configuration defines the configuration of a particular sensor view.
 
 The sensor-view-configuration message is used in the initialization phase of a simulation to negotiate the sensor view configuration for a particular sensor view input.
 It is also included as a sub-message in sensor view messages to indicate that the sensor view configuration is valid for a particular sensor view message.
 
 Sensor-view-configuration data has two main applications:
 
-- It enables the environment simulation to provide the necessary input to a sensor model.
-- It enables a sensor model to check whether the input matches its requirements.
+- Enable the environment simulation to provide the necessary input to a sensor model.
+- Enable a sensor model to check whether the input matches its requirements.
 If the input does not match the requirements, the sensor model may terminate the simulation.
 
-NOTE: Sensor-view-configuration data is intended for the automatic configuration of the sensor view interface between environment simulation and sensor model.
-The data is not intended as a mechanism to parametrize a generic sensor model.
+NOTE: Sensor-view-configuration data is intended for the automatic configuration of the sensor view interface between an environment simulation and sensor model.
+The data is not intended to be a mechanism for parametrizing a generic sensor model.
 
 During the initialization phase, there are two sources for sensor-view-configuration data:
 
-1. Sensor-view-configuration data may be provided by the sensor model to the environment simulation.
+1. Sensor-view configuration data may be provided by the sensor model to the environment simulation.
 In this case, the data describes the input configuration that is requested by the sensor model.
-If no such data is provided by the sensor model, then the environment simulation will fall back to manual configuration of the sensor view.
+If the sensor model does not provide such data, then the environment simulation will fall back to manual configuration of the sensor view.
 
-2. Sensor-view-configuration data may be provided by the environment simulation.
+2. Sensor-view configuration data may be provided by the environment simulation.
 In response to the request by the sensor model, or based on manual configuration, the environment simulation configures the input and provides a new message that describes the actual configuration.
 
 The configuration requested by the sensor model may differ from the configuration provided by the environment simulation.
diff --git a/doc/architecture/trace_file_formats.adoc b/doc/architecture/trace_file_formats.adoc
@@ -1,7 +1,7 @@
 [#top-1a2f4b0c-195c-4f18-89ad-d48a123bd8c1]
 = OSI trace file formats
 
-There are multiple formats for storing multiple serialized OSI messages into one trace file.
+There are multiple formats for storing multiple serialized OSI messages in one trace file.
 
 *.osi::
 Binary trace file.
@@ -16,4 +16,4 @@ Messages are separated by `$$__$$`.
 *.txth::
 Human-readable plain-text trace file.
 Messages are separated by newlines.
-Such a file may be used for manual checks.
+These files may be used for manual checks.
diff --git a/doc/architecture/trace_file_naming.adoc b/doc/architecture/trace_file_naming.adoc
@@ -2,7 +2,7 @@
 
 **Name format**
 
-Names of OSI trace files should have the following format:
+The names of OSI trace files should have the following format:
 
 [source]
 ----
@@ -39,20 +39,20 @@ Given an OSI trace file with the following information:
 |Type
 |SensorView
 
-|OSI Version
+|OSI version
 |3.1.2
 
-|Protobuf Version
+|Protobuf version
 |3.0.0
 
 |Number of frames
 |1523
 
-|Custom Trace Name
+|Custom trace name
 |highway
 |===
 
-The recommended file name is: 
+The recommended file name is:
 
 [source]
 ----
diff --git a/doc/architecture/traffic_participant.adoc b/doc/architecture/traffic_participant.adoc
@@ -1,16 +1,16 @@
 = Traffic participant
 
-A traffic participant is an element of the simulated world, which can change its state during simulation time, for example, position and orientation.
+A traffic participant is an element of the simulated world and can change its state during simulation time, for example, its position and orientation.
 A traffic participant represents one of the following:
 
-- A living being.
-- A means of transportation for living beings
-- A means of transportation for goods
-- Any other movable object that may travel the road network
+- Living being.
+- Means of transportation for living beings
+- Means of transportation for goods
+- Any other movable object that may travel on the road network
 
 Pedestrians and animals are examples of traffic participants that are living beings.
-Vehicles are examples of traffic participants that are means of transportation.
-Therefore, the ego vehicle is also a traffic participant.
+Vehicles are examples of traffic participants that are a means of transportation.
+The ego vehicle is therefore also a traffic participant.
 
 The following figure shows the interface of a traffic participant.
 
@@ -28,4 +28,4 @@ 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.
 Traffic commands do not necessarily need to come from the environment simulation.
-They may come from a separate source, for example, a scenario engine.
+They may come from a separate source, such as a scenario engine.
diff --git a/doc/architecture/traffic_update.adoc b/doc/architecture/traffic_update.adoc
@@ -1,4 +1,4 @@
 = Traffic update
 
 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.
+They provide updates on the position, state, and future trajectory of a traffic participant back to the simulation environment.
diff --git a/doc/misc/osi_vision.adoc b/doc/misc/osi_vision.adoc
@@ -1,5 +1,5 @@
-= The idea of Open Simulation Interface
+= Idea behind Open Simulation Interface
 
 The Open Simulation Interface (OSI) is a specification for interfaces between models and components of a distributed simulation.
-OSI has a strong focus on environmental perception of automated driving functions.
+OSI is strongly focused on the environmental perception of automated driving functions.
 However, OSI also specifies interfaces for modeling traffic participants.
diff --git a/doc/releases/versioning.adoc b/doc/releases/versioning.adoc
@@ -1,23 +1,23 @@
-= Versioning and Compatibility
+= Versioning and compatibility
 
 The version number is defined in `InterfaceVersion::version_number` in `osi_version.proto` as the field's default value.
 
 OSI uses https://semver.org/[Semantic Versioning].
 
 Major::
-A change of the major version results in an incompatibility of code and recorded proto messages.
+A change in the major version makes the code and recorded proto messages incompatible.
 +
 Major changes include:
 +
-* An existing field with a number changes its meaning.
+* An existing field with a number changing its meaning.
 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 from Protocol Buffers to FlatBuffers.
 
 Minor::
-A change of the minor version indicates remaining compatibility to previously recorded files.
-The code on the other hand needs fixing.
+A change in the minor version indicates there is still compatibility with previously recorded files.
+However, the code needs fixing.
 +
 Minor changes include:
 +
@@ -26,10 +26,10 @@ Minor changes include:
 * Adding a new field in a message without changing the numbering of other fields.
 
 Patch::
-The compatibility of both recorded files and code remains.
+Both recorded files and code still have compatibility.
 +
 Patches include:
 +
-* File or folder structure which does not affect including the code in other projects.
+* File or folder structure that does not affect integration of the code in other projects.
 * Changing or adding comments.
-* Clarification of text passages explaining the message content.
+* Clarifying text passages explaining the message content.
diff --git a/doc/setup/installing_linux_cpp.adoc b/doc/setup/installing_linux_cpp.adoc
@@ -2,7 +2,7 @@
 
 **Prerequisites**
 
-* You have _cmake_ installed.
+* You have installed _cmake_.
 * You have installed _protobuf_.
 * You must have super user privileges.
 
@@ -16,7 +16,7 @@
 git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
 ----
 +
-. Change into the repository directory.
+. Switch to the repository directory.
 +
 [source]
 ----
@@ -30,7 +30,7 @@ cd open-simulation-interface
 mkdir build
 ----
 +
-. Change into the new directory.
+. Switch to the new directory.
 +
 [source]
 ----
diff --git a/doc/setup/installing_linux_python.adoc b/doc/setup/installing_linux_python.adoc
@@ -5,7 +5,7 @@
 * You have installed _pip3_.
 * You have installed _python-setuptools_.
 * You have installed _protobuf_.
-* For local installation, you have installed _virtualenv_.
+* For a local installation, you have installed _virtualenv_.
 
 **Steps**
 
@@ -17,7 +17,7 @@
 git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
 ----
 +
-. Change into the repository directory.
+. Switch to the repository directory.
 +
 [source]
 ----
diff --git a/doc/setup/installing_windows_cpp.adoc b/doc/setup/installing_windows_cpp.adoc
@@ -2,8 +2,8 @@
 
 **Prerequisites**
 
-* You have installed _cmake_ as administrator.
-* You have installed _protobuf_ as administrator.
+* You have installed _cmake_ as an administrator.
+* You have installed _protobuf_ as an administrator.
 
 **Steps**
 
@@ -15,7 +15,7 @@
 git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git
 ----
 +
-. Change into the repository directory.
+. Switch to the repository directory.
 +
 [source]
 ----
@@ -29,7 +29,7 @@ cd open-simulation-interface
 mkdir build
 ----
 +
-. Change into the new directory.
+. Switch to the new directory.
 +
 [source]
 ----
diff --git a/doc/setup/installing_windows_python.adoc b/doc/setup/installing_windows_python.adoc
diff --git a/doc/usecases/modeling_traffic_participant.adoc b/doc/usecases/modeling_traffic_participant.adoc
diff --git a/doc/usecases/transforming_coordinate_systems.adoc b/doc/usecases/transforming_coordinate_systems.adoc
