Skip to content

Commit f7ab440

Browse files
paschedStefan Cyliax
pasched
authored and
Stefan Cyliax
committed
style(docs): linguistic review (#549)
Signed-off-by: Patrick Schedlbauer <patrick.schedlbauer@parson-europe.com>
1 parent df12fac commit f7ab440

File tree

6 files changed

+42
-33
lines changed

6 files changed

+42
-33
lines changed

‎doc/architecture/architecture_overview.adoc‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
= Overview of OSI architecture
22

3-
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.
3+
OSI contains an object-based environment description that uses the message format of the https://github.com/protocolbuffers/protobuf/wiki[Protocol Buffer] library.
4+
The Protocol Buffer library was developed and is maintained by Google.
45
OSI defines top-level messages that are used to exchange data between separate models.
5-
Top-level messages define the ``GroundTruth`` interface, the ``SensorData`` interface and, since OSI version 3.0.0, the ``SensorView``, ``SensorViewConfiguration`` and ``FeatureData`` interfaces.
6+
Top-level messages define the `GroundTruth` interface, the `SensorData` interface, and – since OSI version 3.0.0 – the interfaces `SensorView`, `SensorViewConfiguration`, and `FeatureData`.
67

78
The following figure shows the interfaces and models involved in modeling a sensor.
89

@@ -11,8 +12,8 @@ image::{images_open_simulation_interface}/osi-context.png[1100]
1112

1213

1314
OSI also defines interfaces for traffic participant models.
14-
The ``TrafficCommand`` interface allows to send commands to traffic participant models.
15-
The ``TrafficUpdate`` interface allows to receive their updated state.
15+
The `TrafficCommand` interface makes it possible to send commands to traffic participant models.
16+
The `TrafficUpdate` interface makes it possible to receive the updated state from traffic participant models.
1617
The following figure shows the interfaces of a generic traffic participant.
1718

1819
.Interface of a traffic participant
@@ -24,14 +25,15 @@ The following figure shows a more advanced use case for traffic participants.
2425
.Traffic participant with sensor models, AD function, and dynamic model
2526
image::{images_open_simulation_interface}/osi-traffic-participant-advanced.png[1100]
2627

27-
The ``HostVehicleData`` interface describes the measured internal states of a traffic participant
28-
OSI currently provides only limited support for data structures describing measured internal states of traffic participants.
28+
The `HostVehicleData` interface describes the measured internal states of a traffic participant.
29+
OSI currently provides only limited support for data structures that describe measured internal states of traffic participants.
2930
Actuator intentions are currently not covered by OSI and must be handled with a different data description format.
3031

3132
All fields in an interface are set to `optional`.
3233
`required` is not used.
3334
This has been done to allow backward-compatible changes in the field.
34-
Additionally, this is the default behavior in Protocol Buffer version 3 that does no longer have the `required` type and therefore ensures update compatibility.
35+
Additionally, this is the default behavior in Protocol Buffer version 3 that does no longer have the `required` type.
36+
Setting all fields to `optional` thus ensures update compatibility.
3537
However, this does not mean that filling the field is optional.
3638
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.
3739

‎doc/architecture/data_layer.adoc‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
= Data layer
22

3-
The data layer of OSI resides in the message specifications given using the ProtoBuf IDL.
4-
It defines the data that can be transmitted using OSI, including the structure and semantics of the data.
3+
The data layer of OSI is defined in the message specifications using the ProtoBuf IDL.
4+
It defines the data that can be transmitted using OSI, including the structure and the semantics of the data.
55

6-
Additionally, it also specifies the encoding(s) to be used when transmitting OSI data.
7-
Currently, this is the ProtoBuf encoding, but other encodings can be supported from the same IDL, with FlatBuffer encoding a currently experimental feature.
6+
Additionally, it specifies the encoding to be used when OSI data is transmitted.
7+
Currently, ProtoBuf encoding is used, but other encodings are possible with the ProtoBuf IDL.
8+
FlatBuffer encoding has been implemented as an experimental feature.
89

9-
The data layer does not directly define components and transmission routes, which are defined in the packaging layer of OSI.
10-
There can be many packaging layer implementations using the shared data layer definitions.
11-
The flexibility this gives enables easy bridging of information between components using different packaging layer implementations since the data that is exchanged remains compatible.
10+
The data layer does not directly define components and transmission routes.
11+
These are defined in the packaging layer of OSI.
12+
There may be different packaging layer implementations using the shared data layer definitions.
13+
The data that is exchanged remains compatible regardless of the packaging layer implementation.
14+
The use of a shared data layer ensures easy bridging between different packaging layer implementations.

‎doc/architecture/formatting_scripts.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,4 +49,4 @@ The default value is `None`.
4949

5050
**Related topics**
5151

52-
* xref:#top-1a2f4b0c-195c-4f18-89ad-d48a123bd8c1[OSI trace file formats]
52+
* <<#top-1a2f4b0c-195c-4f18-89ad-d48a123bd8c1>>[OSI trace file formats]

‎doc/architecture/packaging_layer.adoc‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
= Packaging layer
22

3-
The packaging layer of OSI specifies how components (like sensor models) using the OSI data layer are packaged for exchange.
3+
The packaging layer of OSI specifies how components that use the OSI data layer, for example, sensor models, are packaged for exchange.
44

5-
It specifies model types (like sensor model, traffic participant model) and their mandatory and optional OSI inputs, outputs, and parameter interfaces.
6-
It also specifies specific component technology standards to allow encapsulation of those model types in easily exchangeable component packages that enable use across platforms and implementations.
5+
It specifies model types and their mandatory and optional OSI inputs, OSI outputs, and parameter interfaces.
6+
A model type may be, for example, a sensor model or a traffic participant model.
7+
The packaging layer also specifies component technology standards.
8+
This makes it possible to encapsulate model types in easily exchangeable component packages that can be used across platforms and implementations.
79

8-
Multiple packaging layer implementations are possible within the OSI framework, with the shared data layer ensuring ease of bridging between different implementations.
9-
The current centrally defined packaging layer is the OSI Sensor Model Packaging (OSMP) specification.
10-
It is defined based on FMI 2.0 and certain additional conventions to allow packaging of OSI using models as FMUs.
10+
Multiple packaging layer implementations are possible within the OSI framework.
11+
The shared data layer ensures easy bridging between the different implementations.
12+
The currently defined central packaging layer is the OSI Sensor Model Packaging (OSMP) specification.
13+
It is based on FMI 2.0 and uses certain additional conventions to allow packaging of OSI using models as FMUs.

‎doc/architecture/reference_points_coordinate_systems.adoc‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,14 @@ OSI uses DIN ISO 8855:2013-11 for coordinate systems and transformations between
44
OSI uses three coordinate systems:
55

66
World coordinate system::
7-
Coordinate system for all entities which are part of ground truth.
7+
Coordinate system for all entities that are part of ground truth.
88
The world coordinate system is an inertial x/y/z-coordinate system.
9-
The origin is the global reference point, which is determined by the environment simulation.
9+
The origin is the global reference point that is determined by the environment simulation.
1010
This reference point may be derived from map data or other considerations.
1111
World coordinates can be mapped to a geographic coordinate system via `osi3::GroundTruth::proj_string`.
1212

1313
Sensor coordinate system::
14-
Coordinate system for all entities which are part of sensor data.
14+
Coordinate system for all entities that are part of sensor data.
1515
The origin is the mounting position of the physical sensor or a virtual mounting position, depending on the OSI message.
1616

1717
Object coordinate system::

‎doc/architecture/sensor_view_configuration.adoc‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,18 @@
11
= Sensor view configuration
22

3-
The sensor view configuration configures the sensor view.
43
Sensor-view-configuration data enables the environment simulation to supply the necessary input to a sensor model.
54

6-
There are two sources for sensor-view-configuration data.
5+
There are two sources for sensor-view-configuration data:
76

8-
Sensor-view-configuration data can be provided by the environment simulation.
9-
Note that the data is intended for the automatic configuration of an environment simulation.
10-
Sensor-view-configuration data is not intended to provide parameters to a sensor model.
7+
1. Sensor-view-configuration data may be provided by the environment simulation.
8+
+
9+
NOTE: The data is intended for the automatic configuration of an environment simulation. Sensor-view-configuration data is not intended to provide parameters to a sensor model.
1110
12-
Sensor-view-configuration data can also be provided by the sensor model to the environment simulation.
11+
2. Sensor-view-configuration data may be provided by the sensor model to the environment simulation.
12+
+
1313
In this case, the data describes the input configuration that is requested by the sensor model.
14-
In response, the environment simulation will configure the input and provide a new message which describes the actual configuration.
15-
The configuration requested by the sensor model may differ from the configuration provided by the environment simulation.
16-
This happens when the environment simulation does not support a requested configuration or when the requested configuration is ambiguous.
14+
In response, the environment simulation configures the input and provides a new message that describes the actual configuration.
15+
1716
The message describing the configuration requested by the sensor model differs from the message describing the configuration provided by the environment simulation.
17+
The configuration requested by the sensor model may differ from the configuration provided by the environment simulation.
18+
This happens when the environment simulation does not support a requested configuration or when the requested configuration is ambiguous.

0 commit comments

Comments
 (0)