Merge pull request #44 from OpenSimulationInterface/rework-osi-documentation

Rework OSI documentation

Author: Stefan Cyliax

appendix/releases/compatibility.adoc

@@ -0,0 +1,11 @@
+= Compatibility
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+Et malesuada fames ac turpis egestas.
+Mauris pharetra et ultrices neque ornare aenean euismod elementum nisi.
+Nulla facilisi morbi tempus iaculis urna id. Justo eget magna fermentum iaculis.
+Sed augue lacus viverra vitae congue eu.
+Velit ut tortor pretium viverra suspendisse.
+Amet commodo nulla facilisi nullam vehicula ipsum a.
+Nibh nisl condimentum id venenatis a.
+Diam vel quam elementum pulvinar etiam non quam lacus suspendisse.

appendix/releases/v02.00.adoc

@@ -0,0 +1,32 @@
+= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.0.0[v2.0.0 - OSI Initial Commit]
+
+
+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.
+
+*Implementation*
+
+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::
+OSI consists of two individual top level interfaces for object data: The ``OSI::GroundTruth`` and the ``OSI::SensorData`` interface.
++
+* The ``OSI::GroundTruth`` interface provides an exact view on the simulated objects in a global coordinate system.
+This message is populated using the internally available data of the used (driving)-simulation framework and is afterwards published to external subscribers with an exporter plugin.
+* The ``OSI::SensorData`` interface describes the objects in the reference frame of a sensor for environmental perception.
+It is generated from a ``OSI::GroundTruth`` message and can either be used to directly connect to an automated driving function using ideal simulated data, or may serve as input for a sensor model simulating limited perception as a replication of real world sensor behavior.
+
+Low level interfaces::
++
+Additionally to the two top level interfaces, OSI contains an ``OSI::LowLevelData`` message.
+This message describes the output of a (physical) model of the measurement process before tracking and object hypothesis.
+It does not deal with object data, but may comprise the geometrical influence of 3D simulations e.g. generating Lidar point clouds with a ray-tracer plugin.
+In addition this message supports generic radar reflection lists and will be extended to supporting low level camera data in the future.

appendix/releases/v02.01.adoc

@@ -0,0 +1,12 @@
+= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.1.0[v2.1.0 - OSI "Agile Andretti"]
+
+*Purpose*
+
+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]!
+Naming convention: "adjective + last name driver" -> Alliteration necessary!

appendix/releases/v02.02.adoc

@@ -0,0 +1,26 @@
+= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.0[v2.2.0 - OSI "Brave Brabham"]
+
+*Purpose*
+
+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.
+* 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.
+* 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]
+
+*Purpose*
+
+This release focuses on optimizing the build process and ensures the proper installation of different versions of OSI on a single system.
+
+*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.

appendix/releases/v03.00.adoc

@@ -0,0 +1,57 @@
+= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.0[v3.0.0 - OSI "Cosmic Coulthard"]
+
+*Purpose*
+
+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 cite:[iso23150] standard for hardware sensor outputs in order to bring simulation and the hardware in the car closer together.
+
+*https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.0[Content/Changes]*
+
+* Added major version to package label (osi3), allowing concurrent use of OSI 2.x and OSI 3.x in one process.
+* Added new top-level messages (new concept SensorView (Configuration),etc.).
+** GroundTruth.
+** SensorView.
+** 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.).
+* Improved messages and definitions (additional RoadConditions, country code in GT, AmbientIllumination, etc.).
+* Use ISO 8855 cite:[iso8855] 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).
+* New FeatureData messages (rework of previous LowLevelData message) - aligned with an upcoming standard ISO 23150 cite:[iso23150].
+* FeatureData usable for fusion units.
+* Extension and clarification of the existing doxygen documentation.
+* Improved doxygen collaboration diagrams.
+* 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 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/releases/tag/v3.0.1[v3.0.1 - OSI "Cosmic Coulthard", Update 1]
+
+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 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
+* 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

appendix/releases/v03.01.adoc

@@ -0,0 +1,37 @@
+= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.0[v3.1.0 - OSI "Dynamic Duncan"]
+
+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 cite:[iso23150]] 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.
+* Introduced light states for emergency and service vehicles.
+* Added orientation_acceleration and updated formulas.
+* Extended documentation with svg images.
+* Added model_reference for static and moving objects.
+* Added map_reference in ground truth.
+* Added proj4 string for coordinate transformations.
+* Introduced raster_lidar_proposal from innoviz.
+* Improved documentation with HTML tables and images for all traffic signs.
+
+= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.1[v3.1.1 - OSI "Dynamic Duncan", Update 1]
+
+*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).
+
+= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.2[v3.1.2 - OSI "Dynamic Duncan", Update 2]
+
+*https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.2[Content/Changes]*
+
+* **Bugfix**: The version number is now correct in the VERSION file.

appendix/releases/v03.02.adoc

@@ -0,0 +1,38 @@
+= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.2.0[v3.2.0 - OSI "Editorial Eaton"]
+
+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.
+
+*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

appendix/releases/v03.03.adoc

@@ -0,0 +1,39 @@
+= https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.0[v3.3.0 - OSI "Fabulous Fangio"]
+
+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.
+
+*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.
+* 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.
+* 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 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.
+
+* 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]
+
+*https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/18?closed=1[Content/Changes]*
+
+* **Bug Fix**: Fixed outdated version information in VERSION file in 3.3.0.
+This led to wrong versioning in proto definitions and Doxygen documentation.
+* **Bug Fix**: Removed outdated picture in README.md.

contributing/commenting_fields_enums.adoc

@@ -56,5 +56,4 @@ message EnvironmentalConditions
 
 **Related topics**
 
-- <<_writing_custom_rules>>
 - <<_guidelines_for_creating_literary_references>>