diff --git a/doc/architecture/architecture_overview.adoc b/doc/architecture/architecture_overview.adoc new file mode 100644 index 000000000..0bbbe8e05 --- /dev/null +++ b/doc/architecture/architecture_overview.adoc @@ -0,0 +1,11 @@ += Overview of OSI architecture + +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. \ No newline at end of file diff --git a/doc/architecture/coordinate_systems.adoc b/doc/architecture/coordinate_systems.adoc new file mode 100644 index 000000000..2034e3cd7 --- /dev/null +++ b/doc/architecture/coordinate_systems.adoc @@ -0,0 +1,11 @@ += Coordinate systems + +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. \ No newline at end of file diff --git a/doc/architecture/data_layer.adoc b/doc/architecture/data_layer.adoc new file mode 100644 index 000000000..7f23e28c7 --- /dev/null +++ b/doc/architecture/data_layer.adoc @@ -0,0 +1,10 @@ += Data layer + +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. \ No newline at end of file diff --git a/doc/architecture/environmental_effect_model.adoc b/doc/architecture/environmental_effect_model.adoc new file mode 100644 index 000000000..6c79080e1 --- /dev/null +++ b/doc/architecture/environmental_effect_model.adoc @@ -0,0 +1,10 @@ += Environmental effect model + +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. \ No newline at end of file diff --git a/doc/architecture/feature_data.adoc b/doc/architecture/feature_data.adoc new file mode 100644 index 000000000..c1bd3ec51 --- /dev/null +++ b/doc/architecture/feature_data.adoc @@ -0,0 +1,10 @@ += Feature data + +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. \ No newline at end of file diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc new file mode 100644 index 000000000..de9f61dc1 --- /dev/null +++ b/doc/architecture/formatting_scripts.adoc @@ -0,0 +1,12 @@ += Formatting scripts + +TODO: Add general description. + +osi2read.py:: +TODO: Add description. + +OSITrace.py:: +TODO: Add description. + +txt2osi.py:: +TODO: Add description. diff --git a/doc/architecture/ground_truth.adoc b/doc/architecture/ground_truth.adoc new file mode 100644 index 000000000..b15de8ab6 --- /dev/null +++ b/doc/architecture/ground_truth.adoc @@ -0,0 +1,10 @@ += Ground truth + +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. \ No newline at end of file diff --git a/doc/architecture/logical_model.adoc b/doc/architecture/logical_model.adoc new file mode 100644 index 000000000..af8dbb0e8 --- /dev/null +++ b/doc/architecture/logical_model.adoc @@ -0,0 +1,10 @@ += Logical model + +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. \ No newline at end of file diff --git a/doc/architecture/packaging_layer.adoc b/doc/architecture/packaging_layer.adoc new file mode 100644 index 000000000..2a42960e6 --- /dev/null +++ b/doc/architecture/packaging_layer.adoc @@ -0,0 +1,9 @@ += Packaging layer + +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. \ No newline at end of file diff --git a/doc/architecture/proto-files.adoc b/doc/architecture/proto-files.adoc new file mode 100644 index 000000000..a5ee64802 --- /dev/null +++ b/doc/architecture/proto-files.adoc @@ -0,0 +1,78 @@ += Protobuffer files + +TODO: Add general description. + +osi_common.proto:: +TODO: Add description. + +osi_datarecording.proto:: +TODO: Add description. + +osi_detectedlane.proto:: +TODO: Add description. + +osi_detectedobject.proto:: +TODO: Add description. + +osi_detectedoccupant.proto:: +TODO: Add description. + +osi_detectedroadmarking.proto:: +TODO: Add description. + +osi_detectedtrafficlight.proto:: +TODO: Add description. + +osi_detectedtrafficsign.proto:: +TODO: Add description. + +osi_environment.proto:: +TODO: Add description. + +osi_featuredata.proto:: +TODO: Add description. + +osi_groundtruth.proto:: +TODO: Add description. + +osi_hostvehicledata.proto:: +TODO: Add description. + +osi_lane.proto:: +TODO: Add description. + +osi_logicaldetectiondata.proto:: +TODO: Add description. + +osi_object.proto:: +TODO: Add description. + +osi_occupant.proto:: +TODO: Add description. + +osi_roadmarking.proto:: +TODO: Add description. + +osi_sensordata.proto:: +TODO: Add description. + +osi_sensorspecific.proto:: +TODO: Add description. + +osi_sensorview.proto:: +TODO: Add description. + +osi_sensorviewconfiguration.proto:: +TODO: Add description. + +osi_trafficcommand.proto:: +TODO: Add description. + +osi_trafficlight.proto:: +TODO: Add description. + +osi_trafficsign.proto:: +TODO: Add description. + +osi_trafficupdate.proto:: +TODO: Add description. diff --git a/doc/architecture/reference_points.adoc b/doc/architecture/reference_points.adoc new file mode 100644 index 000000000..39ebf5240 --- /dev/null +++ b/doc/architecture/reference_points.adoc @@ -0,0 +1,10 @@ += Reference points + +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. \ No newline at end of file diff --git a/doc/architecture/sensor_data.adoc b/doc/architecture/sensor_data.adoc new file mode 100644 index 000000000..ef5164e41 --- /dev/null +++ b/doc/architecture/sensor_data.adoc @@ -0,0 +1,9 @@ += Sensor data + +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. \ No newline at end of file diff --git a/doc/architecture/sensor_model.adoc b/doc/architecture/sensor_model.adoc new file mode 100644 index 000000000..c6b93997e --- /dev/null +++ b/doc/architecture/sensor_model.adoc @@ -0,0 +1,9 @@ += Sensor model + +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. \ No newline at end of file diff --git a/doc/architecture/sensor_view.adoc b/doc/architecture/sensor_view.adoc new file mode 100644 index 000000000..1bdec6fc7 --- /dev/null +++ b/doc/architecture/sensor_view.adoc @@ -0,0 +1,9 @@ += Sensor view + +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. \ No newline at end of file diff --git a/doc/architecture/sensor_view_configuration.adoc b/doc/architecture/sensor_view_configuration.adoc new file mode 100644 index 000000000..c7e9f3f02 --- /dev/null +++ b/doc/architecture/sensor_view_configuration.adoc @@ -0,0 +1,9 @@ += Sensor view configuration + +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. \ No newline at end of file diff --git a/doc/architecture/test_scripts.adoc b/doc/architecture/test_scripts.adoc new file mode 100644 index 000000000..72a061235 --- /dev/null +++ b/doc/architecture/test_scripts.adoc @@ -0,0 +1,45 @@ += Test scripts + +TODO: Add general description. + +__init__.py:: +TODO: Add description. + +test_comment_type.py:: +TODO: Add description. + +test_doxygen_output.py:: +TODO: Add description. + +test_invalid_comment.py:: +TODO: Add description. + +test_invalid_enum.py:: +TODO: Add description. + +test_invalid_html.py:: +TODO: Add description. + +test_invalid_message.py:: +TODO: Add description. + +test_invalid_punctuation.py:: +TODO: Add description. + +test_invalid_tabs.py:: +TODO: Add description. + +test_newline.py:: +TODO: Add description. + +test_non_ascii.py:: +TODO: Add description. + +test_osi_trace.py:: +TODO: Add description. + +test_rules.py:: +TODO: Add description. + +test_units.py:: +TODO: Add description. diff --git a/doc/architecture/trace_file_formats.adoc b/doc/architecture/trace_file_formats.adoc new file mode 100644 index 000000000..8367a3a53 --- /dev/null +++ b/doc/architecture/trace_file_formats.adoc @@ -0,0 +1,9 @@ += OSI trace file formats + +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. \ No newline at end of file diff --git a/doc/architecture/trace_file_naming.adoc b/doc/architecture/trace_file_naming.adoc new file mode 100644 index 000000000..c2c717835 --- /dev/null +++ b/doc/architecture/trace_file_naming.adoc @@ -0,0 +1,9 @@ += OSI trace file naming conventions + +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. \ No newline at end of file diff --git a/doc/architecture/traffic_participant.adoc b/doc/architecture/traffic_participant.adoc new file mode 100644 index 000000000..137bea8d0 --- /dev/null +++ b/doc/architecture/traffic_participant.adoc @@ -0,0 +1,24 @@ += 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 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 + +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. + +The following figure shows the interface of a traffic participant. + +TODO: Add image of traffic participant interface. + +With every simulation step, an OSI traffic participant model receives ground truth data from the environment around itself, the sensor view. +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 diff --git a/doc/architecture/vehicle_dynamics.adoc b/doc/architecture/vehicle_dynamics.adoc new file mode 100644 index 000000000..ff7d9c2b2 --- /dev/null +++ b/doc/architecture/vehicle_dynamics.adoc @@ -0,0 +1,9 @@ += Vehicle dynamics + +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. \ No newline at end of file diff --git a/doc/commenting.rst b/doc/commenting.rst deleted file mode 100644 index cabb5f584..000000000 --- a/doc/commenting.rst +++ /dev/null @@ -1,339 +0,0 @@ -.. _commenting: - -Commenting -=========== - -During the building process of open simulation interface (using the `proto2cpp `_ filter), doxygen is creating a `reference documentation `_ processing all comments written in the code of the interface. In order to do that doxygen needs the comments to be written in a certain way. Please follow these rules to achieve that the reference documentation is created correctly. You will find further information on doxygen `here `_. - -For any additional comment styles see `list `_ of doxygen commands. - -Reference for writing values and units: ISO 80000-1:2013-08, Quantities and units – Part 1: General -Nice summary in German: `Rohde & Schwarz: Der korrekte Umgang mit Groessen, Einheiten und Gleichungen `_ - - -Commenting with block syntax ------------------------------ -Start every comment with ``//`` and do not use ``///``. - - -Commenting on messages ------------------------- -When writing comments specifying messages please use the following template: - -.. code-block:: protobuf - - // - // - message ExampleMessage - { - } - -Doxygen will interpret a comment consisting just of one single line as a brief description. -However to keep the style of the documentation coherent there should not be any brief description when commenting on fields and enums. That is why adding one more empty line when commenting becomes necessary. There is no need for an extra empty line if you are commenting more than one line anyways. - -.. code-block:: protobuf - - // - // <... you do not need to add an empty line> - message ExampleMessage - { - } - -The commenting for messages follows the following order: - -1. Brief description -2. Image -3. Detailed description -4. Note - -First you define the message. - -.. code-block:: protobuf - - message EnvironmentalConditions - { - } - -Next provide a brief description of the message with ``\brief``. - -.. code-block:: protobuf - - // \brief The conditions of the environment. - // - message EnvironmentalConditions - { - } - -Then you can optionally provide an image to explain the message better. A picture is worth a thousand words. - -.. code-block:: protobuf - - // \brief The conditions of the environment. - // - // \image html EnvironmentalConditions.svg - // - message EnvironmentalConditions - { - } - -You can optionally add a detailed description which can have multiple lines. - -.. code-block:: protobuf - - // \brief The conditions of the environment. - // - // \image html EnvironmentalConditions.svg - // - // Definition of light, weather conditions and other environmental conditions. - // - message EnvironmentalConditions - { - } - -Lastly you can add a small note about the message and have a completely commented message. - -.. code-block:: protobuf - - // \brief The conditions of the environment. - // - // \image html EnvironmentalConditions.svg - // - // Definition of light, weather conditions and other environmental conditions. - // - // \note These conditions apply locally around the host vehicle. - // - message EnvironmentalConditions - { - } - -Commenting on fields and enums --------------------------------- -The commenting for fields and enums follows the following order: - -1. Explanation -2. Unit -3. Note -4. Reference -5. Rule - -First you add a field into a message with an appropriate index number. - -.. code-block:: protobuf - - // \brief The conditions of the environment. - // - // \image html EnvironmentalConditions.svg - // - // Definition of light, weather conditions and other environmental conditions. - // - // \note These conditions apply locally around the host vehicle. - // - message EnvironmentalConditions - { - optional double atmospheric_pressure = 1; - } - - - -Then you describe the field by adding an explanation. - -.. code-block:: protobuf - - // \brief The conditions of the environment. - // - // \image html EnvironmentalConditions.svg - // - // Definition of light, weather conditions and other environmental conditions. - // - // \note These conditions apply locally around the host vehicle. - // - message EnvironmentalConditions - { - // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa). - // - optional double atmospheric_pressure = 1; - } - -Next you decide the unit of the field. - -.. code-block:: protobuf - - // \brief The conditions of the environment. - // - // \image html EnvironmentalConditions.svg - // - // Definition of light, weather conditions and other environmental conditions. - // - // \note These conditions apply locally around the host vehicle. - // - message EnvironmentalConditions - { - // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa). - // - // Unit: Pa - // - optional double atmospheric_pressure = 1; - } - -You can optionally add a note to the field to describe the field better. - -.. code-block:: protobuf - - // \brief The conditions of the environment. - // - // \image html EnvironmentalConditions.svg - // - // Definition of light, weather conditions and other environmental conditions. - // - // \note These conditions apply locally around the host vehicle. - // - message EnvironmentalConditions - { - // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa). - // - // Unit: Pa - // - // \note 100000 Pa = 1 bar - // - optional double atmospheric_pressure = 1; - } - -To help understanding the field, you should add a reference. -Every OSI message should be defined properly and should have a well cited reference. - -**Citation style for different sources:** - -- Within the text, the number system is used with the number of the source in brackets [#] for mentioning. -- We use the so called `"APA style" `_ from the American Psychological Association for referencing. -- In the references list, the number in brackets [#] is followed by a full citation. -- For writing the title in italic, use title. -- If the list contains more than one entry, add " \n " at the end of the line to create a line break within the list. -- Author names are written as , like Authorname, A. A. -- Editor names are written as like B. B. Editorname. -- Naming pages at the end is optional to enable finding in long texts or for direct citations. -- All citations should be primary citations. Sources like Wikipedia et al. are not allowed. -- Find filled-out examples under `https://apastyle.apa.org `_ and in existing entries. -- The scheme of popular sources for the reference list is as follows (replace tags with corresponding values): - -1. , , & . (). Contribution in a compilation title. . . . . . . . - -2. , & . (). . . . . . - -3. & . (). . In & (Eds.), (). . . . - -4. & . (). . . . . . . - -5. . (). . Phd. thesis. . . . . - -6. . (, ). . Retrieved , , from . - -7. . (). </em>. (<standard identifier>). <location>. - -8. <author>. (<year>). <em><patent title and id></em>. <location>. <organisation>. - - - -.. code-block:: protobuf - - // \brief The conditions of the environment. - // - // \image html EnvironmentalConditions.svg - // - // Definition of light, weather conditions and other environmental conditions. - // - // \note These conditions apply locally around the host vehicle. - // - message EnvironmentalConditions - { - // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa) [1, 2]. - // - // Unit: Pa - // - // \note 100000 Pa = 1 bar - // - // \par References: - // [1] DIN Deutsches Institut fuer Normung e. V. (1982). <em>DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik</em>. (DIN 5031-3:1982-03). Berlin, Germany. \n - // [2] Rapp, C. (2017). Grundlagen der Physik. In <em>Hydraulik fuer Ingenieure und Naturwissenschaftler</em> (pp.23-36). Springer Vieweg. Wiesbaden, Germany. https://doi.org/10.1007/978-3-658-18619-7_3. p. 105. - // - optional double atmospheric_pressure = 1; - } - -Finally you can provide a set of rules which this field needs to be followed. The available rules can be found below. When adding rules to \*.proto files make sure that the rules are encapsulated between the ``\rules`` and ``\endrules`` tags. Now you have a fully commented message with a fully commented field. - -.. code-block:: protobuf - - // \brief The conditions of the environment. - // - // \image html EnvironmentalConditions.svg - // - // Definition of light, weather conditions and other environmental conditions. - // - // \note These conditions apply locally around the host vehicle. - // - message EnvironmentalConditions - { - // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa) [1, 2]. - // - // Unit: Pa - // - // \note 100000 Pa = 1 bar - // - // \par References: - // [1] DIN Deutsches Institut fuer Normung e. V. (1982). <em>DIN 5031-3 Strahlungsphysik im optischen Bereich und Lichttechnik - Groessen, Formelzeichen und Einheiten der Lichttechnik</em>. (DIN 5031-3:1982-03). Berlin, Germany. \n - // [2] Rapp, C. (2017). Grundlagen der Physik. In <em>Hydraulik fuer Ingenieure und Naturwissenschaftler</em> (pp.23-36). Springer Vieweg. Wiesbaden, Germany. https://doi.org/10.1007/978-3-658-18619-7_3. p. 105. - // - // \rules - // is_optional - // is_greater_than_or_equal_to: 90000 - // is_less_than_or_equal_to: 200000 - // \endrules - // - optional double atmospheric_pressure = 1; - } - - -The rule definition must follow the syntax which is defined by a regex search which you can see below: - -.. code-block:: python - - 'is_greater_than': r'^[ ]\b(is_greater_than)\b: ([\s\d]+)$' # is_greater_than: 1 - 'is_greater_than_or_equal_to': r'^[ ]\b(is_greater_than_or_equal_to)\b: ([\s\d]+)$' # is_greater_than_or_equal_to: 1 - 'is_less_than_or_equal_to': r'^[ ]\b(is_less_than_or_equal_to)\b: ([\s\d]+)$' # is_less_than_or_equal_to: 10 - 'is_less_than': r'^[ ]\b(is_less_than)\b: ([\s\d]+)$' # is_less_than: 2 - 'is_equal': r'^[ ]\b(is_equal_to)\b: ([\s\d]+)$' # is_equal_to: 1 - 'is_different': r'^[ ]\b(is_different_to)\b: ([\s\d]+)$' # is_different_to: 2 - 'is_global_unique': r'^[ ]\b(is_globally_unique)\b' # is_globally_unique - 'refers': r'^[ ]\b(refers_to)\b' # refers_to: DetectedObject - 'is_iso_country_code': r'^[ ]\b(is_iso_country_code)\b' # is_iso_country_code - 'first_element': r'^[ ]\b(first_element)\b' # first_element height is_equal_to 0.13 - 'last_element': r'^[ ]\b(last_element)\b' # last_element width is_equal_to 0.13 - 'check_if': r'^[ ](\bcheck_if\b)(.*\belse do_check\b)' # check_if this.type is_equal_to 2 else do_check is_set - -You can check the correctness of these regular expression on `regex101 <https://regex101.com/r/P4KeuO/1>`_. - - -Commenting with doxygen references ------------------------------------- -If you need to reference to another message etc., you can achieve that by just using the exact same name of this message (upper and lower case sensitive) in your comment and put '\c' in front of the message name. - -.. code-block:: protobuf - - // A reference to \c GroundTruth message. - -If you want to reference a nested message, use '::' instead of '.' as separators in comments. - -If you want to reference message fields and enums add '#' to the enum/field name. - -.. code-block:: protobuf - - // A reference to a enum e.g. \c #COLOR_GREEN. - -Commenting with links (e.g. in references) ------------------------------------------- -With ``[<add name of your link>](<add url of your link>)`` you can integrate a link to a certain homepage while commenting. - -Commenting with images ----------------------- -To include images write your comment similar to this ``// \image html <Add name of your image> "<Add optional caption here>"`` -Please place all your included images in ``./open-simulation-interface/docs/images``. - diff --git a/doc/coordinatesystem.rst b/doc/coordinatesystem.rst deleted file mode 100644 index 064894593..000000000 --- a/doc/coordinatesystem.rst +++ /dev/null @@ -1,37 +0,0 @@ -Coordinate systems and reference points -============================================ - -Coordinate systems -------------------- - -Currently three coordinate systems exist. - -- world frame (for all quantities which are part of groundtruth) -- sensor frame (for all quantities which are part of sensordata) -- object frame (for local object coordinates like axle offset vectors) - -The transformation between frames for a specific vehicle/sensor is performed using the information in - -- ``GroundTruth::moving_object::base::position and ::orientation``: These define the position and orientation of the vehicle's reference point, i.e. center of bounding box. -- ``GroundTruth::moving_object::vehicle_attributes::bbcenter_to_rear``: This defines the vehicle frame origin resp. the relative frame of the vehicle, i.e. it defines the offset of the rear axis center relative to the vehicle's reference point (center of bounding box). This offset is static and given in vehicle coordinates. -- ``SensorData::mounting_position``: This defines the sensor's position and orientation relative to the vehicle frame's origin, i.e. rear axis center, and therefore defines sensor frame origin resp. the relative frame of the sensor. - - -Reference points ------------------- - -All position coordinates refer to the center of the bounding box of the object (vehicle or otherwise). This does not depend on the reference frame and is identical for all objects without exceptions. - - -Example: Position vectors of vehicles ---------------------------------------- - -A position vector consists of two points + orientation / coordinate system: - -**start point**: This is the origin of the coordinate system. (i.e. sensor frame or world frame). - -**end point**: often referred to as reference point. It is always the middle of the bounding box. - -**orientation**: captured by the coordinate system. (i.e. sensor frame or world frame). - -Open Simulation Interface uses DIN ISO 8855:2013-11 for coordinate systems and transformations between coordinate systems. \ No newline at end of file diff --git a/doc/description.rst b/doc/description.rst deleted file mode 100644 index 055143f70..000000000 --- a/doc/description.rst +++ /dev/null @@ -1,188 +0,0 @@ -General description -====================== - -`TUM Department of Electrical and Computer Engineering`_ - -Global remarks --------------- - -All fields in the interface are set to optional and required is not -used. This has been done to allow backward compatible changes in the -field. Additionally, this is the default behavior in protobuf version 3 -that does no longer have the required type and therefore 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. - -All field numbers of 10000 and upward are available for user-specific -extensions (i.e. custom fields), so no future evolution of OSI will -use field numbers of 10000 or above itself. - -Compatibility -------------- - -Definition: FAITHFULLY "All recorded data is correctly interpreted by -the interface" - -Forward compatibility: Definition: "An older version of the code can be -used to read new files" Data recorded with a higher minor or patch -version can be interpreted by code built using the same major version of -the interface but lower minor and/or patch version. In this case, -additional fields of a newer minor version are silently ignored. All -patch versions of the same major and minor version are FAITHFULLY -forward compatible. - -Backward compatibility: Definition: "A newer version of code can be used -to read old files" All files that have been recorded in the past with a -specific major version are FAITHFULLY valid with all combinations of -higher minor and patch versions of the same major version. - -.. # Old way of OSI 2 to inject errors -.. Fault injection: how-to -.. ----------------------- - -.. Injection of predefined sensor errors should be handled by a -.. specialized "fault injector" component that acts like a sensor model -.. component, i.e. it takes a SensorData message as input and returns a -.. modified SensorData message as output. Specific errors should be handled -.. as follows: - -.. - Ghost objects / false positive: An additional SensorDataObject is -.. added to the list of objects in SensorData.object with -.. SensorDataObject.model_internal_object.ground_truth_type set to -.. kTypeGhost. -.. - False negative: The object is marked as not seen by the sensor by -.. setting the property SensorDataObject.model_internal_object.is_seen -.. to false. The implementation of field-of-view calculation modules -.. should respect this flag and never reset an object marked as not-seen -.. to seen. - -Proto3 Support --------------- - -For users that need to use proto3 syntax, for example because the -language binding of choice only supports proto3 syntax out of the box, a -shell script called `convert-to-proto3.sh <https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/convert-to-proto3.sh>`_ is supplied that converts -all proto files to proto3 syntax. If this is run prior to building, the -resulting libraries will use proto3, with the on-the-wire format -remaining compatible between proto2 and proto3 libraries. - -.. note:: - In the current OSI proto2 files there are no "required" fields or "[default = xx] values assigned. - This is intentional since the use is prohibited for now. The reason for that is the conversion from proto2 to proto3 which would require to remove defaults or required attributes and therefore change the meaning of the proto file (and thus also the valid on-the-wire protocol) silently, and is thus dangerous. - -OSI Trace Files ---------------- - -If you have a serialized txt trace file which is separating OSI messages by ``$$__$$`` you can convert -the trace file to the official OSI file format which uses the length of OSI messages to store and read them in a file. -Use the script txt2osi.py in the ``format`` directory for that. See usage example below: - -.. code-block:: bash - - python3 txt2osi.py -h - python3 txt2osi.py -d trace.txt - python3 txt2osi.py -d trace.txt -o myfile - -To make serialized txt/osi files human readable call the converter osi2read.py. See usage example below: - -.. code-block:: bash - - python3 osi2read.py -h - python3 osi2read.py -d trace.osi - python3 osi2read.py -d trace.txt -f separated -o myfile - - -Packaging ---------- - -A specification to package sensor models using OSI as (extended) -Functional Mock-up Units (FMUs) for use in simulation environments is -available `here`_. - -Vector Images --------------- -The vector images for the open-simulation-interface documentation are provided in the .svg-format. - -Creating vector images -~~~~~~~~~~~~~~~~~~~~~~~ - -Objects such as roads, vehicles, signs, etc. that are embedded in the graphics are based on realistic high detailed 3D models. -The overall scene and 3D objects are modelled using the 3D modelling software `Blender <https://www.blender.org/>`_. -The Freestyle SVG Exporter from Blender is used to convert the modelled 3D scene into vector graphics. - -The Freestyle SVG Exporter add-on from Blender can be activated via the Render user settings. -The GUI for the Exporter is located in the Render tab of the Properties Editor. After rendering, the exported .svg file is written to the output path. - -For more information about Blender's Freestyle SVG Exporter add-on see: `docs.blender.org <https://docs.blender.org/manual/en/latest/render/freestyle/export_svg.html>`_ - -Following settings are used for exporting: -Freestyle SVG Export: -Frame, Round; -LineThickness = Absolute, 1.000px; - -Freestyle Line Set: -Visibility = Visible, -Edgetype = Inclusive, -Silhouette = true, -Border = true; - -Editing vector images -~~~~~~~~~~~~~~~~~~~~~~~ - -The exported 3D vector graphics can be opened and edited with any image editing program. (e.g. `Inkscape <https://inkscape.org/de/>`_) -The vectors and labels are placed accordingly. -The graphics should generally be kept in a grayscale style. -RGBA code for grey: b3b3b3ff - - -.. Doxygen Reference Documentation -.. -------------------------------- - -.. The doxygen reference documentation of the GitHub master branch is `online`_ -.. available. - - -.. In order to generate the doxygen documentation for OSI, please follow -.. the following steps: - -.. 1. Install `Doxygen`_, set an environmental variable 'doxygen' with the -.. path to the binary file and add it to the PATH variable: -.. ``PATH += %doxygen%``. -.. 2. Download the `proto2cpp`_ repo. Copy the content of the repo -.. proto2cpp to your desired ``<path-to-proto2cpp.py>`` -.. 3. Install `graphviz`_, set an environmental variable 'graphviz' with -.. the path to the binary file and add it to the PATH variable: -.. ``PATH += %graphviz%``. -.. 4. From the cmd navigate to the build directory and run: -.. ``cmd cmake -DFILTER_PROTO2CPP_PY_PATH=<path-to-proto2cpp.py> <path-to-CMakeLists.txt>`` -.. 5. The build process will then generate the doxygen documentation under -.. the directory doc. - -Citing ------- - -Use the following citation for referencing the OSI interface in your -scientific work: - -.. code-block:: latex - - @misc{osi.2017, - author = {Hanke, Timo and Hirsenkorn, Nils and {van~Driesten}, Carlo and {Garcia~Ramos}, Pilar and Schiementz, Mark and Schneider, Sebastian and Biebl, Erwin}, - year = {2017}, - title = {{Open Simulation Interface: A generic interface for the environment perception of automated driving functions in virtual scenarios.}}, - url = {https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/}, - note = {{Accessed: 2019-11-05}}} - -.. _here: https://github.com/OpenSimulationInterface/osi-sensor-model-packaging -.. _online: https://opensimulationinterface.github.io/open-simulation-interface/ -.. _Doxygen: http://www.doxygen.nl/download.html -.. _proto2cpp: https://github.com/OpenSimulationInterface/proto2cpp -.. _graphviz: https://graphviz.gitlab.io/_pages/Download/Download_windows.html -.. _`http://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/}`: http://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/} -.. _Online Doxygen Documentation: https://opensimulationinterface.github.io/open-simulation-interface/ -.. _TUM Department of Electrical and Computer Engineering: https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/ - -.. |Travis Build Status| image:: https://travis-ci.org/OpenSimulationInterface/open-simulation-interface.svg?branch=master - :target: https://travis-ci.org/OpenSimulationInterface/open-simulation-interface diff --git a/doc/fileformat.rst b/doc/fileformat.rst deleted file mode 100644 index 7e882a541..000000000 --- a/doc/fileformat.rst +++ /dev/null @@ -1,126 +0,0 @@ -OSI File Format -=============== -Formats --------- - -\*.osi -~~~~~~~ -To save multiple serialized OSI messages into one trace file we use the length of each OSI message and save it before the actual OSI message. -The length is represented by the first four bytes which are a little endian unsigned int that represents the length of the followed message, not including the integer itself. - -\*.txt -~~~~~~~ -If you happen to have a trace file which uses ``$$__$$`` separation you can convert it to the official OSI trace file by running: - -.. code-block:: bash - - python3 txt2osi.py -d trace.txt - -\*.txth -~~~~~~~ -To read to content of a serialized txt/osi trace file we also provide a converter ``osi2read.py``. -See the usage below: - -.. code-block:: bash - - python3 osi2read.py -d trace.osi -o readable_trace - python3 osi2read.py -d trace.txt -f separated -o readable_trace - -which outputs a ``readable_trace.txth`` which can be opened by any text editor. - -Summary -~~~~~~~ -In summary we have currently three types of formats: - -1. ``*.osi`` trace files which are length separated. -2. ``*.txt`` trace files which are ``$$__$$`` separated. -3. ``*.txth`` files which are human readable trace files for just plausibility checks. - -Trace file naming convention ------------------------------ -As best practice we recommend to name the trace files in the following format: - -.. code-block:: txt - - <type>_<osi-version>_<protobuf-version>_<frame-number>_<custom-trace-name>.osi - -For example a naming for a trace with the information below: - -.. code-block:: txt - - Type = SensorView - OSI Version= 3.1.2 - Protobuf Version = 3.0.0 - Number of frames = 1523 - Scenario name = highway - -would then look like this: - -.. code-block:: txt - - sv_312_300_1523_highway.osi - -The type definition would only be possible for ``SensorView = sv``, ``SensorData = sd`` and ``GroundTruth = gt``. -By following this best practice users can understand the general content of a file. By comparing the information provided by the naming and the actual trace the user can check the overall validity of a trace file. - -Generate OSI traces --------------------- -If you want to generate a valid OSI trace file which can be used as an input for the `osi-validator <https://github.com/OpenSimulationInterface/osi-validation>`_ or the `osi-visualizer <https://github.com/OpenSimulationInterface/osi-visualizer>`_ see the example script in python below: - -.. code-block:: python - - from osi3.osi_sensorview_pb2 import SensorView - import struct - - def main(): - """Initialize SensorView""" - f = open("sv_312_320_10_movingobject.osi", "ab") - sensorview = SensorView() - - sv_ground_truth = sensorview.global_ground_truth - sv_ground_truth.version.version_major = 3 - sv_ground_truth.version.version_minor = 0 - sv_ground_truth.version.version_patch = 0 - - sv_ground_truth.timestamp.seconds = 0 - sv_ground_truth.timestamp.nanos = 0 - - moving_object = sv_ground_truth.moving_object.add() - moving_object.id.value = 114 - - # Generate 10 OSI messages for 9 seconds - for i in range(10): - - # Increment the time - sv_ground_truth.timestamp.seconds += 1 - sv_ground_truth.timestamp.nanos += 100000 - - moving_object.vehicle_classification.type = 2 - - moving_object.base.dimension.length = 5 - moving_object.base.dimension.width = 2 - moving_object.base.dimension.height = 1 - - moving_object.base.position.x = 0.0 + i - moving_object.base.position.y = 0.0 - moving_object.base.position.z = 0.0 - - moving_object.base.orientation.roll = 0.0 - moving_object.base.orientation.pitch = 0.0 - moving_object.base.orientation.yaw = 0.0 - - """Serialize""" - bytes_buffer = sensorview.SerializeToString() - f.write(struct.pack("<L", len(bytes_buffer)) + bytes_buffer) - - f.close() - - if __name__ == "__main__": - main() - -In the script we initialize the type we want to use for the messages. Here we use the type ``SensorView``. -For the ``SensorView`` it is mandatory to define the version and the timestamp. After that we can add objects. -Here we add a moving object with the ID 114. For this object we generate in a for loop 10 OSI messages which all have different x values over a time span of 9 seconds. -This means the object is changing the position in the x direction through the iteration each second. -Each time we change the x value and the timestamp we append the length of the OSI message and the serialized OSI message itself to a file called ``sv_312_320_10_movingobject.osi``. -After finishing the loop we now have a ``sv_312_320_10_movingobject.osi`` file which can be `validated <https://github.com/OpenSimulationInterface/osi-validation>`_ and `visualized <https://github.com/OpenSimulationInterface/osi-visualizer>`_. diff --git a/doc/howtocontribute.rst b/doc/howtocontribute.rst deleted file mode 100644 index 29a912ece..000000000 --- a/doc/howtocontribute.rst +++ /dev/null @@ -1,319 +0,0 @@ -.. _how-to-contribute: - -Contributors' Guidelines -========================= - -Introduction ------------- - -The purpose of this document is to help contributors get started with -the ASAM Open Simulation Interface (OSI) codebase. - -As an open-source standardisation project, we welcome and encourage the community to submit patches directly to the project. In our collaborative open source environment, standards and methods for submitting changes help reduce the chaos that can result from an active development community. - -This document explains how to participate in project conversations, log bugs and enhancement requests, and submit patches to the project so your patch will be accepted quickly in the codebase. - -Licensing ---------- - -OSI uses the Mozilla Public License, v. 2.0. (as found in the LICENSE file in the project’s GitHub repo). - -The license tells you what rights you have as a developer, provided by the copyright holder. It is important that the contributor fully understands the licensing rights and agrees to them. Sometimes the copyright holder isn’t the contributor, such as when the contributor is doing work on behalf of a company. - -Developer Certification of Origin (DCO) ---------------------------------------- - -To make a good faith effort to ensure licensing criteria are met, the OSI project requires the Developer Certificate of Origin (DCO) process to be followed. - -The DCO is an attestation attached to every contribution made by every developer. In the commit message of the contribution, (described more fully later in this document), the developer simply adds a Signed-off-by statement and thereby agrees to the DCO. - -When a developer submits a patch, it is a commitment that the contributor has the right to submit the patch per the license. The DCO agreement is shown below and `online <http://developercertificate.org/>`_. -:: - - Developer's Certificate of Origin 1.1 - - By making a contribution to this project, I certify that: - - (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - - (b) The contribution is based upon previous work that, to the - best of my knowledge, is covered under an appropriate open - source license and I have the right under that license to - submit that work with modifications, whether created in whole - or in part by me, under the same open source license (unless - I am permitted to submit under a different license), as - Indicated in the file; or - - (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including - all personal information I submit with it, including my - sign-off) is maintained indefinitely and may be redistributed - consistent with this project or the open source license(s) - involved. - -DCO Sign-Off Methods --------------------- - -The DCO requires a sign-off message in the following format appear on each commit in the pull request: -:: - - Signed-off-by: Firstname Lastname <email@address.com> - -The DCO text can either be manually added to your commit body, or you can add either ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget to add the sign-off you can also amend a previous commit with the sign-off by running ``git commit --amend -s``. You can add sign-offs to multiple commits (including commits originally authored by others, if you are authorized to do so) using ``git rebase --signoff``. If you’ve pushed your changes to GitHub already you’ll need to force push your branch after this with ``git push --force-with-lease``. - -If you want to be reminded to add the sign-off for commits in your repository, you can add the following commit-message git hook to your repository: - -.. code:: shell - - #!/bin/sh - # - # Check for DCO/Signed-off-by in message - # - - if ! grep -q "^Signed-off-by: " "$1" - then - echo "Aborting commit: Commit message is not signed off" >&2 - exit 1 - fi - -Placing this script into a file called ``.git/hooks/commit-msg`` and making it executable (e.g. using ``chmod a+x .git/hooks/commit-msg`` on unixoid operating systems) will prevent commits without a sign-off. - - -Reporting issues ----------------- - -The simplest way to contribute to OSI is to report issues that you may -find with the project on `github <https://github.com/OpenSimulationInterface/open-simulation-interface>`__. Everyone can create issues. -Always make sure to search the existing issues before reporting a new one. -Issues may be created to discuss: - -- `Feature requests or Ideas <https://github.com/OpenSimulationInterface/open-simulation-interface/issues/new?assignees=&labels=feature+request&template=feature_request.md&title=>`_ -- `Bugs <https://github.com/OpenSimulationInterface/open-simulation-interface/issues/new?assignees=&labels=bug&template=bug_report.md&title=>`_ -- `Questions <https://github.com/OpenSimulationInterface/open-simulation-interface/issues/new?assignees=&labels=question&template=question.md&title=>`_ -- `Other <https://github.com/OpenSimulationInterface/open-simulation-interface/issues/new>`_ - -If practicable issues should be closed by a referenced pull request or commit (`here <https://help.github.com/en/articles/closing-issues-using-keywords>`_ you can find keywords to close issues automatically). To help developers and maintainers we provide a `pull request template <https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/.github/pull_request_template.md>`_ which will be generated each time you create a new pull request. - -First steps ------------ - -First, make sure that you are proficient enough in protobuf. The developers -website https://developers.google.com/protocol-buffers/ is a great place to start learning. -You may want to make sure that you master these `advanced concepts <https://developers.google.com/protocol-buffers/docs/proto3>`_. - -Download and install the protocol buffer on your computer, pick up your favorite programming language and try to encode and decode your custom made osi messages. -It is a good idea to read the `tutorials <https://developers.google.com/protocol-buffers/docs/tutorials>`_ for that in your favorite programming language. - -For contribution you also need be proficient in Git. You can download and read the book Pro Git by Scott Chacon and Ben Straub `here <https://link.springer.com/book/10.1007%2F978-1-4842-0076-6>`_ for free. -Learn `how to fork a repository <https://help.github.com/en/articles/fork-a-repo>`_ and follow the suggested `fork workflow <https://www.atlassian.com/git/tutorials/comparing-workflows>`_ by Atlassian. -Become a github guru :). - -Where to start --------------- - -While you familiarize yourself with the basics as suggested above, you -can have a look at the `doxgen API reference <https://opensimulationinterface.github.io/open-simulation-interface/annotated.html>`_ of OSI. It will -give you an overview of the OSI messages, fields, their main components and their meaning. - -Our git workflow ----------------- - -First, the main repository of the OSI Organization is https://github.com/OpenSimulationInterface/open-simulation-interface. -The other repositories are optional extensions which add functionality to OSI like `validation <https://github.com/OpenSimulationInterface/osi-validation>`_, `visualization <https://github.com/OpenSimulationInterface/osi-visualizer>`_ and `model packaging <https://github.com/OpenSimulationInterface/osi-sensor-model-packaging>`_. -The repository `proto2cpp <https://github.com/OpenSimulationInterface/proto2cpp>`_ is a fork which is used in this organization to convert \*.proto files into \*.cpp files which can be parsed by doxygen to create a `reference documentation <https://opensimulationinterface.github.io/open-simulation-interface/>`_. - -Then, there are many ways to use Git, here is ours: - -After you have opened an issue, with the tag ``feature request`` or ``idea`` -explaining your enhancement to the project, you should -also provide a possible approach or suggest a possible solution. -After a discussion if the feature is plausible or adds value -to the project you can create a pull request -and reference it to your opened issue. - -We mostly use squash and merge for pull requests for master. -Instead of seeing all of a -contributor's individual commits from a topic branch, -the commits are combined -into one commit and merged into the master branch. -Once a pull request is ready, it is reviewed and -approved, then squashed using the ``--fast-forward`` option of Git in order to -maintain a streamlined Git history. Pull requests without a Sign-Off message (see DCO above) will not be accepted. - -**We also enforce a few hygiene rules**: - -- Prefer small atomic commits over a large one that do many things. -- Don’t mix refactoring and new features. -- Never mix re indentation, whitespace deletion, or other style changes - with actual code changes. -- If you add new osi messages into a \*.proto file, don’t forget to - extend the documentation and comment on the message and on each field (for more information see :ref:`commenting`). -- Don't forget to run the unit tests for comment compliance in the folder `tests <https://github.com/OpenSimulationInterface/open-simulation-interface/tree/master/tests>`_ with ``python -m unittest discover tests`` to check if you followed the correct syntax guidelines for \*.proto files -- Try and mimic the style of commit messages, and for non trivial - commits, add an extended commit message. - -**As per the hygiene of commits themselves**: - -- Give appropriate titles to the commits, and when non-trivial add a - detailed motivated explanation. -- Give meaningful and consistent names to branches. -- Don’t forget to put a ``WIP:`` flag when it is a work in progress - - -**Our branching workflow summary (member)**: - -- Create issues for changes, improvements and ideas! -- Clone repository on your local machine -- Create a branch with a meaningful name: ``prefix/name``, ``feature/new-environmental-conditions`` -- prefixes: feature, experimental, bug, etc. -- Add your suggestions to the code Do not use: ``*git add -A *git commit -A`` -- The code should compile and pass all `unit tests <https://github.com/OpenSimulationInterface/open-simulation-interface/tree/master/tests>`_ for a pull-request! -- Try to make small changes for easier discussions -- The person willing to merge needs to adjust the version according to :ref:`versioning` before hitting merge - - -**Our forking workflow summary (no member)**: - -- Create a personal fork on your account -- Clone to your local machine -- Make changes -- Create pull-request -- Discuss with issues and with comments in the pull-request -- !!! Consider becoming a member !!! - -**Documentation changes**: - -- Can be performed by anyone. -- Consider adding stuff to the `osi-documentation <https://github.com/OpenSimulationInterface/osi-documentation>`_ or directly to the `doc <https://github.com/OpenSimulationInterface/open-simulation-interface/tree/master/doc>`_ folder in the repository. -- When new changes are made directly to the osi-documentation repo the documentation will be rebuild and the new changes can be seen. When making documentation changes in the doc folder of the osi repository the changes will be visible when the daily chron job of osi-documentation is executed. - -Code Review ------------ - -At OSI all the code is peer reviewed before getting committed in the -master branch. Briefly, a code review is a discussion between two or -more developers about changes to the code to address an issue. - -Author Perspective -~~~~~~~~~~~~~~~~~~ - -Code review is a tool among others to enhance the quality of the code and to -reduce the likelihood of introducing new bugs in the code base. It is a -technical discussion, it is not an exam, but it is a common effort to -learn from each other. - -These are a few common suggestions we often give while reviewing new code. -Addressing these points beforehand makes the reviewing process easier and less -painful for everybody. The reviewer is your ally, not your enemy. - -- Commented code: Did I remove any commented out lines? - Did I leave a ``TODO`` or an old comment? - -- Readability: Is the code easy to understand? Is it worth adding - a comment to the code to explain a particular operation and its - repercussion on the rest of the code? - -- Variable and function names: These should be meaningful and in line - with the convention adopted in the code base. - -- Are your Commit messages meaningful? (i.e., https://chris.beams.io/posts/git-commit/ ) - -Review your own code before calling for a peer review from a college. - -Reviewer Perspective -~~~~~~~~~~~~~~~~~~~~ - -Code review can be challenging at times. These are suggestions and common -pitfalls a code reviewer should avoid. - -- Ask questions: What is the purpose of this message? If this requirement changes, - what else would have to change? How could we make this more maintainable? - -- Discuss in person for more detailed points: Online comments are useful for - focused technical questions. In many occasions it is more productive to - discuss it in person rather than in the comments. Similarly, if discussion - about a point goes back and forth, It will be often more productive to pick - it up in person and finish out the discussion. - -- Explain reasoning: Sometimes it is best to both ask if there is a better - alternative and at the same time justify why a problem in the code is worth - fixing. Sometimes it can feel like the changes suggested are nit-picky - without context or explanation. - -- Make it about the code: It is easy to take notes from code reviews - personally, especially if we take pride in our work. It is best to make - discussions about the code than about the developer. It lowers resistance and - it is not about the developer anyway, it is about improving the quality of - the code. - -- Suggest importance of fixes: While offering many suggestions at once, it is - important to also clarify that not all of them need to be acted upon and some - are more important than others. It gives an important guidance to the developer - to improve their work incrementally. - -- Take the developer's opinion into consideration: Imposing a particular design - choice out of personal preferences and without a real explanation will - incentivize the developer to be a passive executor instead of a creative agent. - -- Do not re-write, remove or re-do all the work: Sometimes it is easier to - re-do the work yourself discarding the work of the developer. This can give - the impression that the work of the developer is worthless and adds - additional work for the reviewer that effectively takes responsibility for - the code. - -- Consider the person you are reviewing: Each developer is a person. If you - know the person, consider their personality and experience while reviewing their - code. Sometime it is possible with somebody to be more direct and terse, while - other people require a more thorough explanation. - -- Avoid confrontational and authoritative language: The way we communicate has - an impact on the receiver. If communicating a problem in the code or a - suggestion is the goal, making an effort to remove all possible noise from - the message is important. Consider these two statements to communicate about - a problem in the code : "This operation is wrong. Please fix it." and - "Doing this operation might result in an error, can you please - review it?". The first one implies you made an error (confrontational), and - you should fix it (authority). The second suggest to review the code because - there might be a mistake. Despite the message being the same, the recipient might - have a different reactions to it and impact on the quality of this work. This - general remark is valid for any comment. - -Practicalities : how to ask for a code review. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Our code review process uses Github. First a developer creates a new -branch (it is often useful to prefix the name of the branch with the name of -the developer to make it clear at glance who is working on what : e.g. -``john@new-feature``). This is a private new branch, the developer is free to -rebase, squash commits, rewrite history (``git push --force``), etc. at will. - -Once the code is ready to be shared with the rest of the team, the developer -opens a Merge Request. It is useful to add a precise description of the code -changes while opening the MR and check if those are in line with the initial -requirements. - -If the code is still not ready to be peer reviewed, but it is merely a -RFC, we prefix the MR with ``WIP:`` (work in progress). This will tell everybody -they can look at the code, comment, but there is still work to be done and the -branch can change and history be rewritten. - -Finally, when the code is ready to be audited, we remove the WIP status of the -MR and we freeze the branch. From this moment on, the developer will refrain to -rewrite history (but he/she can add new commits) and to rebase the branch -without notice. At this point the developer waits for the reviewer to add his -comments and suggestions. - -Github allows to comment both on the code and to add general comments on the -MR. Each comment should be addressed by the developer. He/she can add -additional commits to address each comment. This incremental approach will make -it easier for the reviewer to keep interacting till each discussion is -resolved. When the reviewer is satisfied, he/she will mark the discussion resolved. - -When all discussions are resolved, the reviewer will rebase the branch, -squash commits and merge the MR in the master branch. diff --git a/doc/installation.rst b/doc/installation.rst deleted file mode 100644 index d2b5b1ade..000000000 --- a/doc/installation.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _how-to-install: - -Installation -=============== - -Please keep in mind that the C++ installing process and the cmake install prefix presented below are not implemented in the current version of the master branch yet! While working with the open simulation interface master branch just follow the steps regarding the configuration of cmake/protobuf and the building process! - -.. toctree:: - :maxdepth: 1 - - linux - windows - - diff --git a/doc/interfaceconventions.rst b/doc/interfaceconventions.rst deleted file mode 100644 index 8171868b7..000000000 --- a/doc/interfaceconventions.rst +++ /dev/null @@ -1,103 +0,0 @@ -.. _iconventions: - -Interface Conventions -====================== - -When adding new messages, enums, field messages and field enums to OSI we enforce a few naming conventions for each type like in the `style guide <https://developers.google.com/protocol-buffers/docs/style>`_ from protobuf. - -Message Naming ---------------- -A message definition should always be in PascalCase. This means that the first letter of each word in a message should be upper case without any spaces. See example below: - -.. code-block:: protobuf - - message EnvironmentalConditions - { - } - -Top-Level Messages -------------------- -All messages that are intended to be exchanged as a stand-alone message, i.e. not required to be embedded in another message, like e.g. ``SensorView`` or ``SensorViewConfiguration``, are required to carry an ``InterfaceVersion`` field as their first field, and a ``Timestamp`` field as their second field, e.g.: - -.. code-block:: protobuf - - message TopLevel - { - // The interface version used by the sender (simulation environment). - // - optional InterfaceVersion version = 1; - - // The data timestamp of the simulation environment. Zero time is arbitrary - // but must be identical for all messages. Zero time does not need to - // coincide with the UNIX epoch. Recommended is the starting time point of - // the simulation. - // - optional Timestamp timestamp = 2; - } - -Field Message Naming ---------------------- -After defining a message fields can be added to it in snake_case format. This means every letter is lower case and the words are connected through an underline character. See example below: - -.. code-block:: protobuf - - message EnvironmentalConditions - { - optional double atmospheric_pressure = 1; - } - -Field Numbering ----------------- - -Fields should be numbered consecutively starting from 1 on first definition. During maintenance, the rules of backward/forward-compatibility require that fields are never renumbered, and field numbers never re-used unless a major release is performed. - -All field numbers of 10000 and above are reserved for user-defined extensions and will thus never be used by OSI message fields. - -Enum Naming ------------- -The naming of an enum should be PascalCase. See example below: - -.. code-block:: protobuf - - message EnvironmentalConditions - { - optional double atmospheric_pressure = 1; - - enum AmbientIllumination - { - } - } - -Enum Field Naming ------------- -The naming of an enum field should be all in upper case. The start should be converted from the enum name PascalCase to UPPER_CASE_SNAKE_CASE. It is mandatory to add to the first enum field name the postfix ``_UNKNOWN`` and to the second the postfix ``_OTHER``. After that the naming can be decided by the user. It is often mentioned that the value ``_UNKNOWN`` should not be used in a ``GroundTruth`` message as there are now uncertanties by definition in ``the truth``. These values are mostly used in messages like ``SensorData`` where the content is subject to interpretation. See example below: - -.. code-block:: protobuf - - message EnvironmentalConditions - { - optional double atmospheric_pressure = 1; - - enum AmbientIllumination - { - AMBIENT_ILLUMINATION_UNKNOWN = 0; - - AMBIENT_ILLUMINATION_OTHER = 1; - - AMBIENT_ILLUMINATION_LEVEL1 = 2; - } - } - -Summary --------- -Here a small summary for the naming conventions: - -Messages: PascalCase - -Message Fields: snake_case - -Enum: PascalCase - -Enum Fields: Name of enum converted in UPPER_CASE_SNAKE_CASE and then following the specified name - -After defining the messages do not forget to comment them. See also the `section for commenting <https://opensimulationinterface.github.io/osi-documentation/open-simulation-interface/doc/commenting.html>`_ of fields and messages. diff --git a/doc/linux.rst b/doc/linux.rst deleted file mode 100644 index d3e0bd5b6..000000000 --- a/doc/linux.rst +++ /dev/null @@ -1,56 +0,0 @@ -Linux -===== -Install ``cmake`` 3.10.2: - -.. code-block:: shell - - $ sudo apt-get install cmake - -Install ``pip3`` and missing python packages: - -.. code-block:: shell - - $ sudo apt-get install python3-pip python-setuptools - -Install ``protobuf`` 3.0.0: - -.. code-block:: shell - - $ sudo apt-get install libprotobuf-dev protobuf-compiler - -C++ ------- - -.. code-block:: shell - - $ git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git - $ cd open-simulation-interface - $ mkdir build - $ cd build - $ cmake .. - $ make - $ sudo make install - - -P.S.: To build a 32-bit target under 64-bit linux, please add ``-DCMAKE_CXX_FLAGS="-m32"`` to the ``cmake`` command. In this case, please make sure that ``protobuf`` is in a 32-bit mode too. - -Python ------------ -**Local**: - -.. code-block:: shell - - $ git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git - $ cd open-simulation-interface - $ sudo pip3 install virtualenv - $ virtualenv -p python3 venv - $ source venv/bin/activate - $ pip install . - -**Global**: - -.. code-block:: shell - - $ git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git - $ cd open-simulation-interface - $ sudo pip3 install . \ No newline at end of file diff --git a/doc/misc/osi_reference.adoc b/doc/misc/osi_reference.adoc new file mode 100644 index 000000000..0f0224886 --- /dev/null +++ b/doc/misc/osi_reference.adoc @@ -0,0 +1,13 @@ += Reference documentation + +TODO: Add link to the doxygen reference documentation. + +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. \ No newline at end of file diff --git a/doc/misc/osi_vision.adoc b/doc/misc/osi_vision.adoc new file mode 100644 index 000000000..fec1c1f8b --- /dev/null +++ b/doc/misc/osi_vision.adoc @@ -0,0 +1,11 @@ += The vision of Open Simulation Interface + +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. \ No newline at end of file diff --git a/doc/open-simulation-interface_user_guide.adoc b/doc/open-simulation-interface_user_guide.adoc new file mode 100644 index 000000000..287f8cbdf --- /dev/null +++ b/doc/open-simulation-interface_user_guide.adoc @@ -0,0 +1,121 @@ += Open simulation interface +:revnumber: v.v.v +:revdate: dd.mm.yyyy +:toc: left +:toclevels: 2 +:sectnums: + +:topicdir: topics +:reusedir: reuse + +// header & footer for html +// html themes +// +// source highlighting +:source-highlighter: rouge +:rouge-style: base16.solarized.light +// +// :nofooter: +:last-update-label!: +//embed images into html +:data-uri: +:mathematical-format: svg +:imagesoutdir: ../images/generated_images + +include::./misc/osi_vision.adoc[leveloffset=+1] + +== The basic design of OSI + +include::./architecture/architecture_overview.adoc[leveloffset=+2] + +=== Top-level interfaces + +include::./architecture/ground_truth.adoc[leveloffset=+3] + +include::./architecture/feature_data.adoc[leveloffset=+3] + +include::./architecture/sensor_view.adoc[leveloffset=+3] + +include::./architecture/sensor_view_configuration.adoc[leveloffset=+3] + +include::./architecture/sensor_data.adoc[leveloffset=+3] + +=== Model types + +include::./architecture/environmental_effect_model.adoc[leveloffset=+3] + +include::./architecture/sensor_model.adoc[leveloffset=+3] + +include::./architecture/logical_model.adoc[leveloffset=+3] + +include::./architecture/traffic_participant.adoc[leveloffset=+3] + +include::./architecture/vehicle_dynamics.adoc[leveloffset=+3] + +=== Coordinate systems and reference points + +include::./architecture/coordinate_systems.adoc[leveloffset=+3] + +include::./architecture/reference_points.adoc[leveloffset=+3] + +=== Layering + +include::./architecture/data_layer.adoc[leveloffset=+3] + +include::./architecture/packaging_layer.adoc[leveloffset=+3] + +=== OSI trace files + +include::./architecture/trace_file_formats.adoc[leveloffset=+3] + +include::./architecture/trace_file_naming.adoc[leveloffset=+3] + +=== Files and scripts + +include::./architecture/proto-files.adoc[leveloffset=+3] + +include::./architecture/test_scripts.adoc[leveloffset=+3] + +include::./architecture/formatting_scripts.adoc[leveloffset=+3] + +== Setting up OSI + +include::./setup/installing_linux.adoc[leveloffset=+2] + +include::./setup/installing_macos.adoc[leveloffset=+2] + +include::./setup/installing_windows.adoc[leveloffset=+2] + +include::./setup/using_osi_support_tools.adoc[leveloffset=+2] + +include::./setup/including_osi_dev_projects.adoc[leveloffset=+2] + +== Example use cases for OSI + +include::./usecases/modeling_lidar_sensor.adoc[leveloffset=+2] + +include::./usecases/modeling_camera_electronics.adoc[leveloffset=+2] + +include::./usecases/injecting_faults.adoc[leveloffset=+2] + +include::./usecases/fusing_sensor_outputs.adoc[leveloffset=+2] + +include::./usecases/modeling_traffic_participant.adoc[leveloffset=+2] + +include::./usecases/benchmark_integration_gpu_radar.adoc[leveloffset=+2] + +include::./usecases/generating_osi_traces.adoc[leveloffset=+2] + +== Improving performance + +TODO: Define topics and issues regarding performance. + +include::./misc/osi_reference.adoc[leveloffset=+1] + +== Releases and compatibility + +include::./releases/releases.adoc[leveloffset=+2] + +include::./releases/versioning.adoc[leveloffset=+2] + +include::./releases/compatibility.adoc[leveloffset=+2] diff --git a/doc/osifiles.rst b/doc/osifiles.rst deleted file mode 100644 index fc65137a8..000000000 --- a/doc/osifiles.rst +++ /dev/null @@ -1,103 +0,0 @@ -OSI files description -====================== -`osi_version.proto`_ ---------------------------------- -This file gives you an interface for defining the version number of the OSI code base. - -`osi_common.proto`_ ---------------------------------- -OSI common provides the building blocks for the OSI field messages. - -`osi_datarecording.proto`_ ---------------------------------- - -`osi_detectedtrafficsign.proto`_ ---------------------------------- - -`osi_detectedtrafficlight.proto`_ ---------------------------------- - -`osi_detectedroadmarking.proto`_ ---------------------------------- - -`osi_detectedobject.proto`_ ---------------------------------- - -`osi_detectedoccupant.proto`_ ---------------------------------- - -`osi_detectedlane.proto`_ ---------------------------------- - -`osi_environment.proto`_ ---------------------------------- - -`osi_groundtruth.proto`_ ---------------------------------- - -`osi_hostvehicledata.proto`_ ---------------------------------- - -`osi_trafficcommand.proto`_ ---------------------------------- - -`osi_trafficupdate.proto`_ ---------------------------------- - -`osi_trafficsign.proto`_ ---------------------------------- - -`osi_trafficlight.proto`_ ---------------------------------- - -`osi_roadmarking.proto`_ ---------------------------------- - -`osi_featuredata.proto`_ ---------------------------------- - -`osi_logicaldetectiondata.proto`_ ---------------------------------- - -`osi_object.proto`_ ---------------------------------- - -`osi_occupant.proto`_ ---------------------------------- - -`osi_lane.proto`_ ---------------------------------- - -`osi_sensordata.proto`_ ---------------------------------- - -`osi_sensorviewconfiguration.proto`_ --------------------------------------- - -`osi_sensorspecific.proto`_ ---------------------------------- - -`osi_sensorview.proto`_ ---------------------------------- - - -.. _osi_version.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_version.proto.in -.. _osi_common.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_common.proto -.. _osi_datarecording.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_datarecording.proto -.. _osi_detectedlane.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_detectedlane.proto -.. _osi_detectedobject.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_detectedobject.proto -.. _osi_detectedoccupant.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_detectedoccupant.proto -.. _osi_detectedroadmarking.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_detectedroadmarking.proto -.. _osi_detectedtrafficlight.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_detectedtrafficlight.proto - -.. _osi_datarecording.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_datarecording.proto -.. _osi_datarecording.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_datarecording.proto -.. _osi_datarecording.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_datarecording.proto -.. _osi_datarecording.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_datarecording.proto -.. _osi_datarecording.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_datarecording.proto -.. _osi_datarecording.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_datarecording.proto -.. _osi_datarecording.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_datarecording.proto -.. _osi_datarecording.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_datarecording.proto -.. _osi_datarecording.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_datarecording.proto -.. _osi_datarecording.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_datarecording.proto -.. _osi_datarecording.proto: https://github.com/OpenSimulationInterface/open-simulation-interface/blob/master/osi_datarecording.proto diff --git a/doc/reference.rst b/doc/reference.rst deleted file mode 100644 index 97da88908..000000000 --- a/doc/reference.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. OSI Reference -.. =============== - -.. .. WARNING:: - -.. Currently this reference is work in progress to port the doxygen documentation completely to the sphinx documentation. For the official reference see the current `OSI reference documentation <https://opensimulationinterface.github.io/open-simulation-interface/annotated.html>`_. - -.. Base Moving -.. ----------------------- - -.. .. doxygenstruct:: osi3::BaseMoving -.. :project: open-simulation-interface -.. :members: - -.. Detected Traffic Light -.. ----------------------- - -.. .. doxygenstruct:: osi3::DetectedTrafficLight -.. :project: open-simulation-interface -.. :members: - -.. General -.. -------- - -.. .. doxygenindex:: -.. :project: open-simulation-interface \ No newline at end of file diff --git a/doc/releases.rst b/doc/releases.rst deleted file mode 100644 index a5b708829..000000000 --- a/doc/releases.rst +++ /dev/null @@ -1,13 +0,0 @@ -Releases -========= - -.. toctree:: - :maxdepth: 1 - :caption: Release History: - - releases/v02.00 - releases/v02.01 - releases/v02.02 - releases/v03.00 - releases/v03.01 - releases/v03.02 diff --git a/doc/releases/compatibility.adoc b/doc/releases/compatibility.adoc new file mode 100644 index 000000000..c81058eb7 --- /dev/null +++ b/doc/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. \ No newline at end of file diff --git a/doc/releases/releases.adoc b/doc/releases/releases.adoc new file mode 100644 index 000000000..3985840ee --- /dev/null +++ b/doc/releases/releases.adoc @@ -0,0 +1,11 @@ += Releases + +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. \ No newline at end of file diff --git a/doc/releases/versioning.adoc b/doc/releases/versioning.adoc new file mode 100644 index 000000000..b45d386c6 --- /dev/null +++ b/doc/releases/versioning.adoc @@ -0,0 +1,11 @@ += Versioning + +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. \ No newline at end of file diff --git a/doc/setup/including_osi_dev_projects.adoc b/doc/setup/including_osi_dev_projects.adoc new file mode 100644 index 000000000..551972c37 --- /dev/null +++ b/doc/setup/including_osi_dev_projects.adoc @@ -0,0 +1,10 @@ += Including OSI in development projects + +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. \ No newline at end of file diff --git a/doc/setup/installing_linux.adoc b/doc/setup/installing_linux.adoc new file mode 100644 index 000000000..dafb8c50a --- /dev/null +++ b/doc/setup/installing_linux.adoc @@ -0,0 +1,11 @@ += Installing OSI on Linux + +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. \ No newline at end of file diff --git a/doc/setup/installing_macos.adoc b/doc/setup/installing_macos.adoc new file mode 100644 index 000000000..84e70b499 --- /dev/null +++ b/doc/setup/installing_macos.adoc @@ -0,0 +1,10 @@ += Installing OSI on MacOS + +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. \ No newline at end of file diff --git a/doc/setup/installing_windows.adoc b/doc/setup/installing_windows.adoc new file mode 100644 index 000000000..156c4984c --- /dev/null +++ b/doc/setup/installing_windows.adoc @@ -0,0 +1,10 @@ += Installing OSI on Windows + +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. \ No newline at end of file diff --git a/doc/setup/using_osi_support_tools.adoc b/doc/setup/using_osi_support_tools.adoc new file mode 100644 index 000000000..9f598ee25 --- /dev/null +++ b/doc/setup/using_osi_support_tools.adoc @@ -0,0 +1,9 @@ += Using OSI supporting tools + +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. \ No newline at end of file diff --git a/doc/usecases/benchmark_integration_gpu_radar.adoc b/doc/usecases/benchmark_integration_gpu_radar.adoc new file mode 100644 index 000000000..6b460386f --- /dev/null +++ b/doc/usecases/benchmark_integration_gpu_radar.adoc @@ -0,0 +1,12 @@ += Benchmarking and integration: OSI-GPU-radar + +TODO: Clarify content of this use case and make title more clear + +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. \ No newline at end of file diff --git a/doc/usecases/fusing_sensor_outputs.adoc b/doc/usecases/fusing_sensor_outputs.adoc new file mode 100644 index 000000000..e88e63d69 --- /dev/null +++ b/doc/usecases/fusing_sensor_outputs.adoc @@ -0,0 +1,10 @@ += Fusing sensor outputs + +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. \ No newline at end of file diff --git a/doc/usecases/generating_osi_traces.adoc b/doc/usecases/generating_osi_traces.adoc new file mode 100644 index 000000000..768094df0 --- /dev/null +++ b/doc/usecases/generating_osi_traces.adoc @@ -0,0 +1,9 @@ += Generating OSI traces + +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. \ No newline at end of file diff --git a/doc/usecases/injecting_faults.adoc b/doc/usecases/injecting_faults.adoc new file mode 100644 index 000000000..2a3696151 --- /dev/null +++ b/doc/usecases/injecting_faults.adoc @@ -0,0 +1,10 @@ += Injecting faults + +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. \ No newline at end of file diff --git a/doc/usecases/modeling_camera_electronics.adoc b/doc/usecases/modeling_camera_electronics.adoc new file mode 100644 index 000000000..c74269338 --- /dev/null +++ b/doc/usecases/modeling_camera_electronics.adoc @@ -0,0 +1,10 @@ += Modeling camera electronics + +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. \ No newline at end of file diff --git a/doc/usecases/modeling_lidar_sensor.adoc b/doc/usecases/modeling_lidar_sensor.adoc new file mode 100644 index 000000000..55e41fac5 --- /dev/null +++ b/doc/usecases/modeling_lidar_sensor.adoc @@ -0,0 +1,10 @@ += Modeling a LIDAR sensor + +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. \ No newline at end of file diff --git a/doc/usecases/modeling_traffic_participant.adoc b/doc/usecases/modeling_traffic_participant.adoc new file mode 100644 index 000000000..c987101b8 --- /dev/null +++ b/doc/usecases/modeling_traffic_participant.adoc @@ -0,0 +1,10 @@ += Modeling a traffic participant + +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. \ No newline at end of file diff --git a/doc/versioning.rst b/doc/versioning.rst deleted file mode 100644 index 87bec6068..000000000 --- a/doc/versioning.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _versioning: - -Versioning -============= - -The version number is defined in ``InterfaceVersion::version_number`` in ``osi_common.proto`` as the field's default value. - -`Link to Semantic Versioning <https://semver.org/>`_ - -**Major**: A change of the major version results in an incompatibility of code and recorded proto messages. - -- An existing field with a number changes its meaning ``optional double field = 1;`` -> ``repeated double field = 1;`` Changing the definition of units or interpretation of a field -- Deleting a field and reusing the field number -- Changing the technology ProtoBuffer -> FlatBuffer - -**Minor**: A change of the minor version indicates remaining compatibility to previously recorded files. The code on the other hand needs fixing. - -- Renaming of a field without changing the field number -- Changing the names of messages -- Adding a new field in a message without changing the numbering of other fields - -**Patch**: The compatibility of both recorded files and code remains. - -- File or folder structure which does not affect including the code in other projects -- Changing or adding comments -- Clarification of text passages explaining the message content - diff --git a/doc/windows.rst b/doc/windows.rst deleted file mode 100644 index 960769d1d..000000000 --- a/doc/windows.rst +++ /dev/null @@ -1,63 +0,0 @@ -Windows -======= -C++ ------- -All the following steps are to be executed with admin rights: - -1. Install cmake (v3.7 or higher required): - -- Go to the `cmake download page <https://cmake.org/download/>`_ -- Download and install `cmake 3.8.0 <https://cmake.org/files/v3.8/cmake-3.8.0-rc2-win64-x64.msi>`_ - -2. Install Protobuf (v2.6.1 or higher required): - -- Go to the `ProtoBuffer Download Page <https://github.com/protocolbuffers/protobuf/releases/tag/v2.6.1>`_ -- Download and unzip `protobuf-2.6.1.zip <https://github.com/google/protobuf/releases/download/v2.6.1/protobuf-2.6.1.zip>`_ -- Open the ``protobuf.sln`` file in the unzipped ``protobuf-2.6.1\vsprojects`` with Visual Studio -- Build ``libprotobuf``, ``libprotobuf-lite`` , ``libprotoc and protoc`` -- Set the environmental variables: - - - ``PATH += path-to-the-directory-containing-the-just-created-protoc.exe-file`` - - ``PROTOBUF = path-to-the-unzipped-protobuf-2.6.1-directory`` - - ``PROTOBUF_SRC_ROOT_FOLDER = %PROTOBUF%`` - - ``CMAKE_INCLUDE_PATH = path-to-the-directory-protobuf-2.6.1\src-containing-the-folder-google`` - - ``CMAKE_LIBRARY_PATH = path-to-the-directory-containing-the-three-created-library-files`` - -3. Now you are ready to build and install OSI (v2.1.1 or higher required): - -- Clone `open simulation interface <https://github.com/OpenSimulationInterface/open-simulation-interface>`_ from GitHub and navigate to this directory using a terminal. -- Create a new directory ``build`` and navigate into it using the following command:`` mkdir build & cd build`` -- Generate a Visual Studio solution file suitable for your version and set the ``CMAKE_INSTALL_PREFIX`` to a directory where the OSI library and headers should be installed. - - - When no generator is mentioned: cmake would opt for the newest version of Visual Studio available. To see all supported generators please run: ``cmake -–help``. - - To build a 64-bit OSI library, please add to the generator name the desired target platform Win64. In this case please make sure that the ``protoc.exe`` executable and protobuf libraries are also 64-bit and set the environmental variables to the appropriate paths. - - When ``CMAKE_INSTALL_PREFIX`` is not set: cmake would opt for the configured default install directory. - -.. code-block:: shell - - cmake .. [-G <generator>] [-DCMAKE_INSTALL_PREFIX=<osi-install-directory>] - -Example using Visual Studio 12 2013 and C:/Libraries/open_simulation_interface as an install directory: - -.. code-block:: shell - - cmake .. -G "Visual Studio 12 2013" -DCMAKE_INSTALL_PREFIX=C:/Libraries/open_simulation_interface - -Now you can build and install OSI using the following commands: - -.. code-block:: shell - - cmake --build . [--config Release] - cmake --build . --target install - -As an alternative way you can use Visual Studio to build and install OSI. -P.S.: If you build in a Release configuration, please make sure that the protobuf libraries and executable are also compiled with release settings. - -Python ------------ - -1. Go to the python download page and download the executable installer. -2. Run the installer (with admin rights). -3. In the first step of the installer check ‘Add Python 3.6 to PATH’, then finish installation. -4. Clone open simulation interface from GitHub and navigate to this directory using a terminal. -5. Run the following command: python setup.py install