From fe4b4a6732779df7ee738dfc9a9c76ae97eaa79f Mon Sep 17 00:00:00 2001 From: Patrick Schedlbauer Date: Thu, 9 Sep 2021 12:32:59 +0200 Subject: [PATCH 1/3] docs: native speaker review Signed-off-by: Patrick Schedlbauer --- doc/architecture/architecture_overview.adoc | 12 ++-- doc/architecture/data_layer.adoc | 6 +- doc/architecture/feature_data.adoc | 2 +- doc/architecture/formatting_scripts.adoc | 12 ++-- doc/architecture/ground_truth.adoc | 4 +- doc/architecture/packaging_layer.adoc | 4 +- doc/architecture/sensor_data.adoc | 4 +- doc/architecture/sensor_view.adoc | 4 +- .../sensor_view_configuration.adoc | 16 +++--- doc/architecture/trace_file_formats.adoc | 4 +- doc/architecture/trace_file_naming.adoc | 10 ++-- doc/architecture/traffic_participant.adoc | 16 +++--- doc/architecture/traffic_update.adoc | 2 +- doc/misc/osi_vision.adoc | 4 +- doc/releases/v02.00.adoc | 23 ++++---- doc/releases/v02.01.adoc | 4 +- doc/releases/v02.02.adoc | 8 +-- doc/releases/v03.00.adoc | 42 +++++++------- doc/releases/v03.01.adoc | 14 ++--- doc/releases/v03.02.adoc | 57 ++++++++++--------- doc/releases/v03.03.adoc | 24 ++++---- doc/releases/versioning.adoc | 16 +++--- doc/setup/installing_linux_cpp.adoc | 6 +- doc/setup/installing_linux_python.adoc | 4 +- doc/setup/installing_windows_cpp.adoc | 8 +-- doc/setup/installing_windows_python.adoc | 2 +- .../modeling_traffic_participant.adoc | 13 +++-- .../transforming_coordinate_systems.adoc | 18 +++--- 28 files changed, 170 insertions(+), 169 deletions(-) diff --git a/doc/architecture/architecture_overview.adoc b/doc/architecture/architecture_overview.adoc index 6f146eb41..13e5d70b9 100644 --- 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 newline at end of file +No future evolution of OSI will therefore use field numbers equal to or greater than 10000. \ No newline at end of file diff --git a/doc/architecture/data_layer.adoc b/doc/architecture/data_layer.adoc index 2c3959bfd..9e048334f 100644 --- 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. \ No newline at end of file diff --git a/doc/architecture/feature_data.adoc b/doc/architecture/feature_data.adoc index a92720506..e9b1c9c81 100644 --- 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 index 8bed56627..d1ee28b3d 100644 --- 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,7 +13,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`:: @@ -21,8 +21,8 @@ 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 index 9db2e216a..b6599acf0 100644 --- 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. \ No newline at end of file +They are based on data available to the simulation environment. +Ground-truth messages are typically contained in sensor view messages. \ No newline at end of file diff --git a/doc/architecture/packaging_layer.adoc b/doc/architecture/packaging_layer.adoc index 386394dcf..3c6182a56 100644 --- 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 index 9504bd950..17722ac78 100644 --- 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 index a63f06433..a143ed182 100644 --- 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. \ No newline at end of file + 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. \ No newline at end of file diff --git a/doc/architecture/sensor_view_configuration.adoc b/doc/architecture/sensor_view_configuration.adoc index 46e878398..ed8165a5f 100644 --- a/doc/architecture/sensor_view_configuration.adoc +++ b/doc/architecture/sensor_view_configuration.adoc @@ -1,6 +1,6 @@ = 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. @@ -8,20 +8,20 @@ It is also included as a sub-message in sensor view messages to indicate that th 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 index cedc65075..a029d2d1b 100644 --- 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 index 225bce382..b2fbc8abc 100644 --- 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 index fdce08be9..5e6ccd993 100644 --- 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. \ No newline at end of file +They may come from a separate source, such as a scenario engine. \ No newline at end of file diff --git a/doc/architecture/traffic_update.adoc b/doc/architecture/traffic_update.adoc index 29ed49c5a..528056991 100644 --- 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. \ No newline at end of file +They provide updates on the position, state, and future trajectory of a traffic participant back to the simulation environment. \ No newline at end of file diff --git a/doc/misc/osi_vision.adoc b/doc/misc/osi_vision.adoc index f9dc39d93..9e5cb6171 100644 --- 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. \ No newline at end of file diff --git a/doc/releases/v02.00.adoc b/doc/releases/v02.00.adoc index 38f903060..b93d1d2ae 100644 --- a/doc/releases/v02.00.adoc +++ b/doc/releases/v02.00.adoc @@ -6,27 +6,26 @@ 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. +It has been primarily conceived to enable easy and straightforward compatibility between automated driving functions and the variety of driving simulation frameworks that are available. +The data description has been derived from the perspective of sensor modeling for automated testing and validation of highly automated driving functions. == Implementation -OSI primarily contains an object based environment description using the message format of the protocol buffers library developed and maintained by Google. +OSI primarily contains an object based environment description using the message format of the protocol buffers library, which Google has developed and maintains. == Detailed description - -Top level interfaces:: +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::GroundTruth`` interface provides an exact view of the simulated objects in a global coordinate system. +This message is populated using the internally available data of the used (driving) simulation framework and then 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. +It is generated from an ``OSI::GroundTruth`` message and can either be used to directly connect to an automated driving function using ideal simulated data, or it may serve as an input for a sensor model simulating limited perception as a replication of real world sensor behavior. -Low level interfaces:: +Low-level interfaces:: + -Additionally to the two top level interfaces, OSI contains an ``OSI::LowLevelData`` message. +In addition 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. +It does not deal with object data, but may comprise the geometrical influence of 3D simulations, for example, generating Lidar point clouds with a ray-tracer plugin. +This message also supports generic radar reflection lists and will be extended to supporting low-level camera data in the future. diff --git a/doc/releases/v02.01.adoc b/doc/releases/v02.01.adoc index 005e4e1ac..23850d102 100644 --- a/doc/releases/v02.01.adoc +++ b/doc/releases/v02.01.adoc @@ -2,11 +2,11 @@ == Purpose -This is the initial BASE VERSION for Tool Development. +This is the initial BASE VERSION for tool development. https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/1?closed=1[Content/Changes] == Remarks -We will now release the versions using the name of a https://en.wikipedia.org/wiki/List_of_Formula_One_drivers[Formula 1 driver]! +We will be releasing the versions using the name of a https://en.wikipedia.org/wiki/List_of_Formula_One_drivers[Formula 1 driver]! Naming convention: "adjective + last name driver" -> Alliteration necessary! \ No newline at end of file diff --git a/doc/releases/v02.02.adoc b/doc/releases/v02.02.adoc index a0ef709e7..2b12de277 100644 --- a/doc/releases/v02.02.adoc +++ b/doc/releases/v02.02.adoc @@ -7,11 +7,11 @@ This release focuses on optimizing the build process and documentation. == https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/2?closed=1[Content/Changes] * Added a shared library target to the CMake build script. -* Generated a proper doxygen documentation. +* Generated proper doxygen documentation. * Placed the version number in one file (VERSION). * Added unit testing mechanism including style guide checking. * Redefined precipitation and added a fog definition to the environmental conditions message. -* Added layer id to low level point cloud data. +* Added a layer id to low-level point cloud data. * Reworked large parts of the build instructions in the WIKI. = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.1[v2.2.1 - OSI "Brave Brabham", Update 1] @@ -22,5 +22,5 @@ This release focuses on optimizing the build process and ensures the proper inst == https://github.com/OpenSimulationInterface/open-simulation-interface/compare/maintenance/v2.2.x[Content/Changes] -* Allowing several OSI versions on the same computer. -* Improves CI builds to also test the installation cmake targets for proper completion. +* Allowed several OSI versions on the same computer. +* Improved CI builds to also test the installation cmake targets for proper completion. diff --git a/doc/releases/v03.00.adoc b/doc/releases/v03.00.adoc index 75c25a959..1b3e8de33 100644 --- a/doc/releases/v03.00.adoc +++ b/doc/releases/v03.00.adoc @@ -2,7 +2,7 @@ == Purpose -This release is a complete rework including the feedback from many OSI users. +This release is a complete rework and includes 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. @@ -12,46 +12,46 @@ We are aligned with the ongoing discussions for the upcoming ISO 23150 standard * Added new top-level messages (new concept SensorView (Configuration),etc.). ** GroundTruth. ** SensorView. -** SensorData / FeatureData. +** SensorData/FeatureData. ** SensorViewConfiguration (used for auto-configuration of SensorView). * Added technology-specific SensorView sub-messages to aid physical models. * Introduced conceptual separation of “SensorModels” and “LogicModels”. -* Extended enumerations (e.g. traffic sign Type according to StVO, vehicle Type, etc.). +* Extended enumerations (for example, traffic sign type according to StVO and vehicle type). * Improved messages and definitions (additional RoadConditions, country code in GT, AmbientIllumination, etc.). -* Use ISO 8855 coordinate systems (incompatible with earlier OSI versions). +* Introduced ISO 8855 coordinate systems (incompatible with earlier OSI versions). * Redefined DetectedXXX messages. * Introduced DetectedStationaryObjects. * Merged MovingObjects and Vehicle messages. * Redefined Lane messages (with separated lane boundary messages and intersections). * Redefined TrafficLight messages. -* Redefined TrafficSigns (1 x MainSign + n x SupplementarySign inclusive BaseStationary). +* Redefined TrafficSigns (1 x MainSign + n x SupplementarySign including BaseStationary). * New FeatureData messages (rework of previous LowLevelData message) - aligned with an upcoming standard ISO 23150. -* FeatureData usable for fusion units. -* Extension and clarification of the existing doxygen documentation. +* Made FeatureData usable for fusion units. +* Extended and clarified the existing doxygen documentation. * Improved doxygen collaboration diagrams. -* Build process improvements, added install targets. +* Improved Build process and added install targets. * Made proto definitions compatible with proto3 restrictions to allow concurrent use with proto3-only implementations in the future. * Fixed version-checking of transmitted data. -* AND MUCH MORE ENJOY!!! +* AND MUCH MORE, SO PLEASE ENJOY!!! -https://github.com/OpenSimulationInterface/open-simulation-interface/files/2297162/osi_overview_v2.2_vs_v3.0.pdf>[See for more information the `changelog`] +https://github.com/OpenSimulationInterface/open-simulation-interface/files/2297162/osi_overview_v2.2_vs_v3.0.pdf>[For more information, view the `changelog`] = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.1[v3.0.1 - OSI "Cosmic Coulthard", Update 1] -https://www.youtube.com/watch?v=yG0oBPtyNb0[Summertime :)] +https://www.youtube.com/watch?v=yG0oBPtyNb0[Summer time :)] == Purpose -This release is a patch reworking parts of the documentation in order to avoid ambiguities and improving the build/installation process of OSI. +This release is a patch reworking parts of the documentation in order to avoid ambiguities and improve the OSI build/installation process. == https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.1[Content/Changes] -* Added script to automatically convert the messages from proto2 to proto3 with on the wire compatibility -* cmake enhancements to enable multi-version support of OSI 2 and OSI 3 -* Added Python 3 support -* Clarification of multiple comments -* Added explanatory images in the documentation -* centerline definition improved -* signal_strength definition in LidarSensorView corrected -* FeatureData::ambiguity_id definition clarified -* RadarSensorViewConfiguration::AntennaDiagram::response definition clarified +* Added script to automatically convert the messages from proto2 to proto3 with on the wire compatibility. +* Made cmake enhancements to enable multi-version support for OSI 2 and OSI 3. +* Added Python 3 support. +* Clarified multiple comments. +* Added explanatory images in the documentation. +* Improved centerline definition. +* Corrected signal_strength definition in LidarSensorView. +* Clarified FeatureData::ambiguity_id definition. +* Clarified RadarSensorViewConfiguration::AntennaDiagram::response definition. diff --git a/doc/releases/v03.01.adoc b/doc/releases/v03.01.adoc index 1835671b7..414402b24 100644 --- a/doc/releases/v03.01.adoc +++ b/doc/releases/v03.01.adoc @@ -4,16 +4,16 @@ https://www.youtube.com/watch?v=fu3uA8K6ApQ>[(O SI)lent night] == Purpose -This time of the year Santa comes with presents and has also thought about the sensor modelers of this planet. -We introduce the current state of the ISO 23150 discussions including Ultrasonic and Camera Detections. +At this time of the year Santa goes on his rounds and has also given thought to this planet’s sensor modelers.”. +We have taken note of the current status of the ISO 23150 discussions, including ultrasonic and camera detections. The traffic signs have been reworked and the documentation has been extended for a perfect user experience. Trust me - it's amazing! == https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.0>[Content/Changes] -* Complete rework of traffic signs including images in documentation. -* Added Camera Detections in osi_featuredata.proto. -* Added Ultrasonic Detections in osi_featuredata.proto. +* Completely reworked traffic signs including images in documentation. +* Added camera detections in osi_featuredata.proto. +* Added ultrasonic detections in osi_featuredata.proto. * Introduced light states for emergency and service vehicles. * Added orientation_acceleration and updated formulas. * Extended documentation with svg images. @@ -27,8 +27,8 @@ Trust me - it's amazing! == https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.1[Content/Changes] -* **Bug Fix**: Changed open_simulation_interface target back from being a static library to a shared library, as before (this reverts an inadvertent change in v3.1.0 from previous releases). -v3.1.0 breaks all users of the shared library (i.e. everyone building on Linux/Unix systems, and even some using the DLL on Windows). +* **Bug Fix**: Changed open_simulation_interface target back from being a static library to its previous state as a shared library (this reverts an inadvertent change in v3.1.0 from previous releases). +v3.1.0 breaks all users of the shared library (that is, everyone building on Linux/Unix systems, and even some using the DLL on Windows). = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.2[v3.1.2 - OSI "Dynamic Duncan", Update 2] diff --git a/doc/releases/v03.02.adoc b/doc/releases/v03.02.adoc index 28fa51e97..f4c7d64af 100644 --- a/doc/releases/v03.02.adoc +++ b/doc/releases/v03.02.adoc @@ -4,35 +4,36 @@ 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]. -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. +It was previously the case that the company BMW AG organized most of the work on the OSI project. +To make it possible for as many interested parties as possible to contribute to the success of the Open Simulation Interface, the project has been transferred to https://www.asam.net/[ASAM e.V.]. +This 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 has been opened with the https://www.asam.net/conferences-events/detail/asam-osi-kick-off-workshop/[kickoff workshop], which will hopefully generate lots of project proposals to streamline the efficient future development of the interface. +Whith this release, we therefore decided to focus on improving processes and documentation. == https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.2.0[Content/Changes] -* Updated README according to K(eep) I(t) S(imply) S(tupid) principle -* Added Issue and Pullrequest templates -* Travis CI updated -** Update to bionic 18.04 -** Added tests for building protobuf 2.6 and 3.0 in parallel -** Bugfixed the display of doubled documentation -* Fixed several typos in the comments -* Added a centralized documentation in https://github.com/OpenSimulationInterface/osi-documentation[OSI-Documentation] -** Added contributors guidelines -** Added commenting style guidelines -** Added uniform citation style according to APA -** Updated installation guides for osi in Linux and Windows -** Added a reference in sphinx based on the generated doxygen documentation -* Added rules to the comments in order to enforce osi message validation with the https://github.com/OpenSimulationInterface/osi-validation[OSI-Validator] -* Added the rule definitions in the rules.yml -* Modularized testing of commenting style into python unit tests -* Defined a standardazied a file format for reading trace files (*.osi) -* Defined naming conventions of osi files -* Added a *.txt to *.osi file converter for backward compatibility -* Added a script to make traces readable for plausibility checks -* Corrected the citing style for OSI Bibtex -* Corrected unit specifications and references according to DIN (e.g. removed Unit: []) -* Added timestamp in osi_environment -* Added is_out_of_service bool to traffic light / traffic sign +* Updated README according to K(eep) I(t) S(imply) S(tupid) principle. +* Added Issue and Pullrequest templates. +* Updated Travis CI. +** Updated to bionic 18.04. +** Added tests for building protobuf 2.6 and 3.0 in parallel. +** Bugfixed the display of doubled documentation. +* Fixed several typos in the comments. +* Added a centralized documentation in https://github.com/OpenSimulationInterface/osi-documentation[OSI-Documentation]. +** Added contributors guidelines. +** Added commenting style guidelines. +** Added a uniform citation style based on APA. +** Updated installation guides for osi in Linux and Windows. +** Added a reference in sphinx based on generated doxygen documentation. +* Added rules to the comments to enforce osi message validation with the https://github.com/OpenSimulationInterface/osi-validation[OSI-Validator]. +* Added the rule definitions in the rules.yml. +* Modularized testing of commenting style into python unit tests. +* Defined a standardized file format for reading trace files (*.osi). +* Defined naming conventions for osi files. +* Added a *.txt to *.osi file converter for backward compatibility. +* Added a script to make traces readable for plausibility checks. +* Corrected the citing style for OSI Bibtex. +* Corrected unit specifications and references according to DIN (for example, removed Unit: []). +* Added a timestamp in osi_environment. +* Added is_out_of_service bool to traffic light / traffic sign. diff --git a/doc/releases/v03.03.adoc b/doc/releases/v03.03.adoc index 457c12e21..35ad04c19 100644 --- a/doc/releases/v03.03.adoc +++ b/doc/releases/v03.03.adoc @@ -4,30 +4,30 @@ Stay p(OSI)tive! == Purpose -As a part of the increasing adoption of OSI in the industry, and its movement to ASAM as its home, several new use cases and extensions for OSI have been identified. -This minor release highlights the work that has been done on several working packages including the introduction of brand new top level messages which extend OSI's scope beyond the specialized world of sensor modeling. +With the increasing adoption of OSI within the industry and its migration to ASAM as its home, several new use cases and extensions for OSI have been identified. +This minor release highlights the work that has been done on several working packages, including the introduction of brand new top-level messages which extend OSI's scope beyond the specialized world of sensor modeling. == https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/13?closed=1[Content/Changes] -* Introduced the TrafficCommand top-level message which enables event-based control of traffic participant models, e.g. with regard to a scenario specification. -* Introduced the TrafficUpdate top-level message to send updated properties of traffic participant models. -* Add new LogicalDetectionData message to SensorData, which provides detection data with respect to the reference frame of the logical/virtual sensor. +* Introduced the TrafficCommand top-level message which enables event-based control of traffic participant models, for example, with regard to a scenario specification. +* Introduced the TrafficUpdate top-level message to send updated properties of traffic participant models. +* Added new LogicalDetectionData message to SensorData, which provides detection data with respect to the reference frame of the logical/virtual sensor. * Added a new submessage to further specify wheel data. * Added a new field to support future trajectories of moving objects. -* Added a new subtype message to osi_lane to better align with OpenDrive's lane type information and enable traffic participant models to identify lanes on which they are supposed to move. -* Extended traffic lights and signs messages to include the model_references attribute that can be used to point out to a 3D-model. -* Add global model reference to ground truth that can be used to specify the 3D model representing the environment. +* Added a new subtype message to osi_lane to better align with OpenDrive's lane type information and enable traffic participant models to identify lanes in which they are supposed to move. +* Extended traffic lights and signs messages to include the model_references attribute that can be used to point to a 3D-model. +* Added 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. -* Updated to checklist for pull requests to provide clearer orientation for all users. +* Updated the checklist for pull requests to provide clearer guidance for all users. * Updated the documentation of centerline and lane boundaries (ordering of the points, describing those lines). -* Updated the documentation of 3D bounding boxes. -* Update the documentation of ground clearance. +* Updated the documentation for 3D bounding boxes. +* Updated the ground clearance documentation. -* Make handling of enums in rules check more robust, especially ones. +* Made handling of enums in rules check more robust, especially ones. * Set the default compiler to C++ 11 to support protobuf>3.6. = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.1[v3.3.1 - OSI "Fabulous Fangio", Update 1] diff --git a/doc/releases/versioning.adoc b/doc/releases/versioning.adoc index bdaf96f13..f8d347b48 100644 --- 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 index c743b197b..4dd9c1a10 100644 --- 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 index 8b753aba8..8d0069c67 100644 --- 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 index 93ad4c9d3..44757cfa9 100644 --- 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 index f1b0640e3..4f48d42d9 100644 --- a/doc/setup/installing_windows_python.adoc +++ b/doc/setup/installing_windows_python.adoc @@ -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] ---- diff --git a/doc/usecases/modeling_traffic_participant.adoc b/doc/usecases/modeling_traffic_participant.adoc index e1898024b..e3d10e7c2 100644 --- a/doc/usecases/modeling_traffic_participant.adoc +++ b/doc/usecases/modeling_traffic_participant.adoc @@ -14,22 +14,23 @@ The following figure shows a very simple use case. 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 traffic participant's dynamics are included in the model if they exist. 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. +OSI currently provides only limited support for data structures that describe measured internal states of the traffic participant. +OSI does not currently cover actuator intentions. +These 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. +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. @@ -38,11 +39,11 @@ 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 +.Traffic participant with an AD function and 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. +This type of 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. \ No newline at end of file diff --git a/doc/usecases/transforming_coordinate_systems.adoc b/doc/usecases/transforming_coordinate_systems.adoc index 7a9743aa1..6935d8bef 100644 --- a/doc/usecases/transforming_coordinate_systems.adoc +++ b/doc/usecases/transforming_coordinate_systems.adoc @@ -1,11 +1,11 @@ -= Coordinate Transformations += Coordinate transformations -== Vehicle and Sensor Coordinate Systems +== Vehicle and sensor coordinate systems -Transforming coordinates from the world coordinate system for a specific vehicle and its sensors is frequently needed when running simulations. +When running simulations, it is frequently necessary to transform coordinates from the world coordinate system for a specific vehicle and its sensors. -This section provides an overview of the involved messages and fields and their relationship for this task. -It demonstrates how world coordinate system, vehicle coordinate system, and sensor coordinate system are related given a specific (ego-)vehicle. +This section provides an overview of the messages and fields involved and their relationship for this task. +It demonstrates how a world coordinate system, vehicle coordinate system, and sensor coordinate system are related on the basis of a specific (ego) vehicle. //TODO: Should we add one or more sentences about the mathematical operations involved? @@ -13,16 +13,16 @@ It demonstrates how world coordinate system, vehicle coordinate system, and sens ``GroundTruth::moving_object::base::position``:: This field defines the position of the vehicle's reference point in world coordinates. -In Open Simulation Interface, the position of an object is defined by the coordinates of the center of the object's 3D bounding box. +In Open Simulation Interface, an object's position is defined by the coordinates of the center of the object's 3D bounding box. ``GroundTruth::moving_object::base::orientation``:: This field defines the orientation of the vehicle's reference point in world coordinates. ``GroundTruth::moving_object::vehicle_attributes::bbcenter_to_rear``:: -This field specifies the vector pointing from the vehicle's reference point to the middle of the rear axle under neutral load conditions in vehicle coordinates. +This field specifies the vector pointing from the vehicle's reference point to the middle of the rear axle under neutral load conditions in the vehicle coordinates. ``SensorData::mounting_position``:: -This field defines the sensor's position and orientation and, thereby, the origin of the sensor coordinate system. +This field defines the sensor's position and orientation and thereby the origin of the sensor coordinate system. The mounting position is given in the vehicle coordinate system. **Example** @@ -30,6 +30,6 @@ The mounting position is given in the vehicle coordinate system. The following image shows the relationship between the coordinate systems. The reference point of the vehicle is given by a vector in the world coordinate system. A vector pointing from the reference position of the vehicle to the center of the rear axle then yields the origin of the vehicle coordinate system. -The mounting positions of the sensors and, therefore, the origins of the corresponding sensor coordinate systems are given with respect to the vehicle coordinate system. +The mounting positions of the sensors and therefore the origins of the corresponding sensor coordinate systems are given with respect to the vehicle coordinate system. image::{images_open_simulation_interface}/osi_example_coordinate_systems.png[] \ No newline at end of file From 80470f4bc7eea3fd4d1b6aa1287d10f37e11a67c Mon Sep 17 00:00:00 2001 From: Patrick Schedlbauer Date: Fri, 10 Sep 2021 17:05:11 +0200 Subject: [PATCH 2/3] docs: reverted changes in release notes Signed-off-by: Patrick Schedlbauer --- doc/releases/v02.00.adoc | 23 ++++++++------- doc/releases/v02.01.adoc | 4 +-- doc/releases/v02.02.adoc | 8 ++--- doc/releases/v03.00.adoc | 42 +++++++++++++------------- doc/releases/v03.01.adoc | 14 ++++----- doc/releases/v03.02.adoc | 57 ++++++++++++++++++------------------ doc/releases/v03.03.adoc | 24 +++++++-------- doc/releases/versioning.adoc | 16 +++++----- 8 files changed, 94 insertions(+), 94 deletions(-) diff --git a/doc/releases/v02.00.adoc b/doc/releases/v02.00.adoc index b93d1d2ae..38f903060 100644 --- a/doc/releases/v02.00.adoc +++ b/doc/releases/v02.00.adoc @@ -6,26 +6,27 @@ 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 has been primarily conceived to enable easy and straightforward compatibility between automated driving functions and the variety of driving simulation frameworks that are available. -The data description has been derived from the perspective of sensor modeling for automated testing and validation of highly automated driving functions. +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 -OSI primarily contains an object based environment description using the message format of the protocol buffers library, which Google has developed and maintains. +OSI primarily contains an object based environment description using the message format of the protocol buffers library developed and maintained by Google. == Detailed description -Top-level interfaces:: + +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 of the simulated objects in a global coordinate system. -This message is populated using the internally available data of the used (driving) simulation framework and then published to external subscribers with an exporter plugin. +* 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 an ``OSI::GroundTruth`` message and can either be used to directly connect to an automated driving function using ideal simulated data, or it may serve as an input for a sensor model simulating limited perception as a replication of real world sensor behavior. +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:: +Low level interfaces:: + -In addition to the two top-level interfaces, OSI contains an ``OSI::LowLevelData`` message. +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, for example, generating Lidar point clouds with a ray-tracer plugin. -This message also supports generic radar reflection lists and will be extended to supporting low-level camera data in the future. +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/v02.01.adoc b/doc/releases/v02.01.adoc index 23850d102..005e4e1ac 100644 --- a/doc/releases/v02.01.adoc +++ b/doc/releases/v02.01.adoc @@ -2,11 +2,11 @@ == Purpose -This is the initial BASE VERSION for tool development. +This is the initial BASE VERSION for Tool Development. https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/1?closed=1[Content/Changes] == Remarks -We will be releasing the versions using the name of a https://en.wikipedia.org/wiki/List_of_Formula_One_drivers[Formula 1 driver]! +We will now release the versions using the name of a https://en.wikipedia.org/wiki/List_of_Formula_One_drivers[Formula 1 driver]! Naming convention: "adjective + last name driver" -> Alliteration necessary! \ No newline at end of file diff --git a/doc/releases/v02.02.adoc b/doc/releases/v02.02.adoc index 2b12de277..a0ef709e7 100644 --- a/doc/releases/v02.02.adoc +++ b/doc/releases/v02.02.adoc @@ -7,11 +7,11 @@ This release focuses on optimizing the build process and documentation. == https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/2?closed=1[Content/Changes] * Added a shared library target to the CMake build script. -* Generated proper doxygen documentation. +* Generated a proper doxygen documentation. * Placed the version number in one file (VERSION). * Added unit testing mechanism including style guide checking. * Redefined precipitation and added a fog definition to the environmental conditions message. -* Added a layer id to low-level point cloud data. +* Added layer id to low level point cloud data. * Reworked large parts of the build instructions in the WIKI. = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.1[v2.2.1 - OSI "Brave Brabham", Update 1] @@ -22,5 +22,5 @@ This release focuses on optimizing the build process and ensures the proper inst == https://github.com/OpenSimulationInterface/open-simulation-interface/compare/maintenance/v2.2.x[Content/Changes] -* Allowed several OSI versions on the same computer. -* Improved CI builds to also test the installation cmake targets for proper completion. +* Allowing several OSI versions on the same computer. +* Improves CI builds to also test the installation cmake targets for proper completion. diff --git a/doc/releases/v03.00.adoc b/doc/releases/v03.00.adoc index 1b3e8de33..75c25a959 100644 --- a/doc/releases/v03.00.adoc +++ b/doc/releases/v03.00.adoc @@ -2,7 +2,7 @@ == Purpose -This release is a complete rework and includes feedback from many OSI users. +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. @@ -12,46 +12,46 @@ We are aligned with the ongoing discussions for the upcoming ISO 23150 standard * Added new top-level messages (new concept SensorView (Configuration),etc.). ** GroundTruth. ** SensorView. -** SensorData/FeatureData. +** SensorData / FeatureData. ** SensorViewConfiguration (used for auto-configuration of SensorView). * Added technology-specific SensorView sub-messages to aid physical models. * Introduced conceptual separation of “SensorModels” and “LogicModels”. -* Extended enumerations (for example, traffic sign type according to StVO and vehicle type). +* Extended enumerations (e.g. traffic sign Type according to StVO, vehicle Type, etc.). * Improved messages and definitions (additional RoadConditions, country code in GT, AmbientIllumination, etc.). -* Introduced ISO 8855 coordinate systems (incompatible with earlier OSI versions). +* Use ISO 8855 coordinate systems (incompatible with earlier OSI versions). * Redefined DetectedXXX messages. * Introduced DetectedStationaryObjects. * Merged MovingObjects and Vehicle messages. * Redefined Lane messages (with separated lane boundary messages and intersections). * Redefined TrafficLight messages. -* Redefined TrafficSigns (1 x MainSign + n x SupplementarySign including BaseStationary). +* Redefined TrafficSigns (1 x MainSign + n x SupplementarySign inclusive BaseStationary). * New FeatureData messages (rework of previous LowLevelData message) - aligned with an upcoming standard ISO 23150. -* Made FeatureData usable for fusion units. -* Extended and clarified the existing doxygen documentation. +* FeatureData usable for fusion units. +* Extension and clarification of the existing doxygen documentation. * Improved doxygen collaboration diagrams. -* Improved Build process and added install targets. +* Build process improvements, added install targets. * Made proto definitions compatible with proto3 restrictions to allow concurrent use with proto3-only implementations in the future. * Fixed version-checking of transmitted data. -* AND MUCH MORE, SO PLEASE ENJOY!!! +* AND MUCH MORE ENJOY!!! -https://github.com/OpenSimulationInterface/open-simulation-interface/files/2297162/osi_overview_v2.2_vs_v3.0.pdf>[For more information, view the `changelog`] +https://github.com/OpenSimulationInterface/open-simulation-interface/files/2297162/osi_overview_v2.2_vs_v3.0.pdf>[See for more information the `changelog`] = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.1[v3.0.1 - OSI "Cosmic Coulthard", Update 1] -https://www.youtube.com/watch?v=yG0oBPtyNb0[Summer time :)] +https://www.youtube.com/watch?v=yG0oBPtyNb0[Summertime :)] == Purpose -This release is a patch reworking parts of the documentation in order to avoid ambiguities and improve the OSI build/installation process. +This release is a patch reworking parts of the documentation in order to avoid ambiguities and improving the build/installation process of OSI. == https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.1[Content/Changes] -* Added script to automatically convert the messages from proto2 to proto3 with on the wire compatibility. -* Made cmake enhancements to enable multi-version support for OSI 2 and OSI 3. -* Added Python 3 support. -* Clarified multiple comments. -* Added explanatory images in the documentation. -* Improved centerline definition. -* Corrected signal_strength definition in LidarSensorView. -* Clarified FeatureData::ambiguity_id definition. -* Clarified RadarSensorViewConfiguration::AntennaDiagram::response definition. +* Added script to automatically convert the messages from proto2 to proto3 with on the wire compatibility +* cmake enhancements to enable multi-version support of OSI 2 and OSI 3 +* Added Python 3 support +* Clarification of multiple comments +* Added explanatory images in the documentation +* centerline definition improved +* signal_strength definition in LidarSensorView corrected +* FeatureData::ambiguity_id definition clarified +* RadarSensorViewConfiguration::AntennaDiagram::response definition clarified diff --git a/doc/releases/v03.01.adoc b/doc/releases/v03.01.adoc index 414402b24..1835671b7 100644 --- a/doc/releases/v03.01.adoc +++ b/doc/releases/v03.01.adoc @@ -4,16 +4,16 @@ https://www.youtube.com/watch?v=fu3uA8K6ApQ>[(O SI)lent night] == Purpose -At this time of the year Santa goes on his rounds and has also given thought to this planet’s sensor modelers.”. -We have taken note of the current status of the ISO 23150 discussions, including ultrasonic and camera detections. +This time of the year Santa comes with presents and has also thought about the sensor modelers of this planet. +We introduce the current state of the ISO 23150 discussions including Ultrasonic and Camera Detections. The traffic signs have been reworked and the documentation has been extended for a perfect user experience. Trust me - it's amazing! == https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.0>[Content/Changes] -* Completely reworked traffic signs including images in documentation. -* Added camera detections in osi_featuredata.proto. -* Added ultrasonic detections in osi_featuredata.proto. +* Complete rework of traffic signs including images in documentation. +* Added Camera Detections in osi_featuredata.proto. +* Added Ultrasonic Detections in osi_featuredata.proto. * Introduced light states for emergency and service vehicles. * Added orientation_acceleration and updated formulas. * Extended documentation with svg images. @@ -27,8 +27,8 @@ Trust me - it's amazing! == https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.1[Content/Changes] -* **Bug Fix**: Changed open_simulation_interface target back from being a static library to its previous state as a shared library (this reverts an inadvertent change in v3.1.0 from previous releases). -v3.1.0 breaks all users of the shared library (that is, everyone building on Linux/Unix systems, and even some using the DLL on Windows). +* **Bug Fix**: Changed open_simulation_interface target back from being a static library to a shared library, as before (this reverts an inadvertent change in v3.1.0 from previous releases). +v3.1.0 breaks all users of the shared library (i.e. everyone building on Linux/Unix systems, and even some using the DLL on Windows). = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.2[v3.1.2 - OSI "Dynamic Duncan", Update 2] diff --git a/doc/releases/v03.02.adoc b/doc/releases/v03.02.adoc index f4c7d64af..28fa51e97 100644 --- a/doc/releases/v03.02.adoc +++ b/doc/releases/v03.02.adoc @@ -4,36 +4,35 @@ https://www.youtube.com/watch?v=SJUhlRoBL8M[Think p(OSI)tive!] == Purpose -It was previously the case that the company BMW AG organized most of the work on the OSI project. -To make it possible for as many interested parties as possible to contribute to the success of the Open Simulation Interface, the project has been transferred to https://www.asam.net/[ASAM e.V.]. -This 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 has been opened with the https://www.asam.net/conferences-events/detail/asam-osi-kick-off-workshop/[kickoff workshop], which will hopefully generate lots of project proposals to streamline the efficient future development of the interface. -Whith this release, we therefore decided to focus on improving processes and documentation. +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. == https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.2.0[Content/Changes] -* Updated README according to K(eep) I(t) S(imply) S(tupid) principle. -* Added Issue and Pullrequest templates. -* Updated Travis CI. -** Updated to bionic 18.04. -** Added tests for building protobuf 2.6 and 3.0 in parallel. -** Bugfixed the display of doubled documentation. -* Fixed several typos in the comments. -* Added a centralized documentation in https://github.com/OpenSimulationInterface/osi-documentation[OSI-Documentation]. -** Added contributors guidelines. -** Added commenting style guidelines. -** Added a uniform citation style based on APA. -** Updated installation guides for osi in Linux and Windows. -** Added a reference in sphinx based on generated doxygen documentation. -* Added rules to the comments to enforce osi message validation with the https://github.com/OpenSimulationInterface/osi-validation[OSI-Validator]. -* Added the rule definitions in the rules.yml. -* Modularized testing of commenting style into python unit tests. -* Defined a standardized file format for reading trace files (*.osi). -* Defined naming conventions for osi files. -* Added a *.txt to *.osi file converter for backward compatibility. -* Added a script to make traces readable for plausibility checks. -* Corrected the citing style for OSI Bibtex. -* Corrected unit specifications and references according to DIN (for example, removed Unit: []). -* Added a timestamp in osi_environment. -* Added is_out_of_service bool to traffic light / traffic sign. +* Updated README according to K(eep) I(t) S(imply) S(tupid) principle +* Added Issue and Pullrequest templates +* Travis CI updated +** Update to bionic 18.04 +** Added tests for building protobuf 2.6 and 3.0 in parallel +** Bugfixed the display of doubled documentation +* Fixed several typos in the comments +* Added a centralized documentation in https://github.com/OpenSimulationInterface/osi-documentation[OSI-Documentation] +** Added contributors guidelines +** Added commenting style guidelines +** Added uniform citation style according to APA +** Updated installation guides for osi in Linux and Windows +** Added a reference in sphinx based on the generated doxygen documentation +* Added rules to the comments in order to enforce osi message validation with the https://github.com/OpenSimulationInterface/osi-validation[OSI-Validator] +* Added the rule definitions in the rules.yml +* Modularized testing of commenting style into python unit tests +* Defined a standardazied a file format for reading trace files (*.osi) +* Defined naming conventions of osi files +* Added a *.txt to *.osi file converter for backward compatibility +* Added a script to make traces readable for plausibility checks +* Corrected the citing style for OSI Bibtex +* Corrected unit specifications and references according to DIN (e.g. removed Unit: []) +* Added timestamp in osi_environment +* Added is_out_of_service bool to traffic light / traffic sign diff --git a/doc/releases/v03.03.adoc b/doc/releases/v03.03.adoc index 35ad04c19..457c12e21 100644 --- a/doc/releases/v03.03.adoc +++ b/doc/releases/v03.03.adoc @@ -4,30 +4,30 @@ Stay p(OSI)tive! == Purpose -With the increasing adoption of OSI within the industry and its migration to ASAM as its home, several new use cases and extensions for OSI have been identified. -This minor release highlights the work that has been done on several working packages, including the introduction of brand new top-level messages which extend OSI's scope beyond the specialized world of sensor modeling. +As a part of the increasing adoption of OSI in the industry, and its movement to ASAM as its home, several new use cases and extensions for OSI have been identified. +This minor release highlights the work that has been done on several working packages including the introduction of brand new top level messages which extend OSI's scope beyond the specialized world of sensor modeling. == https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/13?closed=1[Content/Changes] -* Introduced the TrafficCommand top-level message which enables event-based control of traffic participant models, for example, with regard to a scenario specification. -* Introduced the TrafficUpdate top-level message to send updated properties of traffic participant models. -* Added new LogicalDetectionData message to SensorData, which provides detection data with respect to the reference frame of the logical/virtual sensor. +* Introduced the TrafficCommand top-level message which enables event-based control of traffic participant models, e.g. with regard to a scenario specification. +* Introduced the TrafficUpdate top-level message to send updated properties of traffic participant models. +* Add new LogicalDetectionData message to SensorData, which provides detection data with respect to the reference frame of the logical/virtual sensor. * Added a new submessage to further specify wheel data. * Added a new field to support future trajectories of moving objects. -* Added a new subtype message to osi_lane to better align with OpenDrive's lane type information and enable traffic participant models to identify lanes in which they are supposed to move. -* Extended traffic lights and signs messages to include the model_references attribute that can be used to point to a 3D-model. -* Added global model reference to ground truth that can be used to specify the 3D model representing the environment. +* Added a new subtype message to osi_lane to better align with OpenDrive's lane type information and enable traffic participant models to identify lanes on which they are supposed to move. +* Extended traffic lights and signs messages to include the model_references attribute that can be used to point out to a 3D-model. +* 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. -* Updated the checklist for pull requests to provide clearer guidance for all users. +* 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). -* Updated the documentation for 3D bounding boxes. -* Updated the ground clearance documentation. +* Updated the documentation of 3D bounding boxes. +* Update the documentation of ground clearance. -* Made handling of enums in rules check more robust, especially ones. +* Make handling of enums in rules check more robust, especially ones. * Set the default compiler to C++ 11 to support protobuf>3.6. = https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.1[v3.3.1 - OSI "Fabulous Fangio", Update 1] diff --git a/doc/releases/versioning.adoc b/doc/releases/versioning.adoc index f8d347b48..bdaf96f13 100644 --- 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 in the major version makes the code and recorded proto messages incompatible. +A change of the major version results in an incompatibility of code and recorded proto messages. + Major changes include: + -* An existing field with a number changing its meaning. +* An existing field with a number changes 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 in the minor version indicates there is still compatibility with previously recorded files. -However, the code needs fixing. +A change of the minor version indicates remaining compatibility to previously recorded files. +The code on the other hand 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:: -Both recorded files and code still have compatibility. +The compatibility of both recorded files and code remains. + Patches include: + -* File or folder structure that does not affect integration of the code in other projects. +* File or folder structure which does not affect including the code in other projects. * Changing or adding comments. -* Clarifying text passages explaining the message content. +* Clarification of text passages explaining the message content. From 15878d097bf2b92d012d3959f78c1ec722b3fd32 Mon Sep 17 00:00:00 2001 From: Stefan Cyliax Date: Fri, 10 Sep 2021 20:37:46 +0200 Subject: [PATCH 3/3] included native speaker review in versioning chapter Signed-off-by: Stefan Cyliax --- doc/releases/versioning.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/releases/versioning.adoc b/doc/releases/versioning.adoc index bdaf96f13..f8d347b48 100644 --- 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.