Merge branch 'master' into bugfix/osi_object

Author: 0815-code

README.md

@@ -12,7 +12,7 @@ In this context, OSI defines generic interfaces to ensure modularity, integrabil
 
 For more information on OSI see the [official documentation](https://opensimulationinterface.github.io/osi-documentation/) or the [official reference documentation](https://opensimulationinterface.github.io/open-simulation-interface/) for defined protobuf messages. 
 
-[[1]](https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/) *A generic interface for the environment perception of automated driving functions in virtual scenarios.(Dated 03.02.2017) T. Hanke, N. Hirsenkorn, C. van-Driesten, P. Garcia-Ramos, M. Schiementz, S. Schneider, E. Biebl*
+[1] Hanke, T., Hirsenkorn, N., van-Driesten, C., Garcia-Ramos, P., Schiementz, M., Schneider, S. & Biebl, E. (2017, February 03). *A generic interface for the environment perception of automated driving functions in virtual scenarios.* Retrieved January 25, 2020, from https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/ 
 
 ## Usage
 ##### Example of writing and reading an OSI message in `Python`

VERSION

@@ -1,3 +1,3 @@
 VERSION_MAJOR = 3
-VERSION_MINOR = 1
-VERSION_PATCH = 2
+VERSION_MINOR = 2
+VERSION_PATCH = 0

doc/commenting.rst

@@ -7,9 +7,8 @@ During the building process of open simulation interface (using the `proto2cpp <
 
 For any additional comment styles see `list <http://www.doxygen.nl/manual/commands.html>`_ of doxygen commands.
 
-Reference for writing values and units: ISO 80000-1: 2009, Quantities and units – Part 1: General
-Nice summary: [Rohde & Schwarz: Der korrekte Umgang mit Größen, Einheiten und Gleichungen ](https://karriere.rohde-schwarz.de/fileadmin/customer/downloads/PDF/Der_korrekte_Umgang_mit_Groessen_Einheiten_und_Gleichungen_bro_de_01.pdf
-)
+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 <https://karriere.rohde-schwarz.de/fileadmin/customer/downloads/PDF/Der_korrekte_Umgang_mit_Groessen_Einheiten_und_Gleichungen_bro_de_01.pdf>`_
 
 
 Commenting with block syntax
@@ -150,7 +149,7 @@ Then you describe the field by adding an explanation.
     //
     message EnvironmentalConditions
     {
-        // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 Pa).
+        // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa).
         //
         optional double atmospheric_pressure = 1;
     }
@@ -169,7 +168,7 @@ Next you decide the unit of the field.
     //
     message EnvironmentalConditions
     {
-        // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 Pa).
+        // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa).
         //
         // Unit: Pa
         //
@@ -190,7 +189,7 @@ You can optionally add a note to the field to describe the field better.
     //
     message EnvironmentalConditions
     {
-        // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 Pa).
+        // Atmospheric pressure in Pascal at z = 0.0 m in world frame (about 101325 Pa).
         //
         // Unit: Pa
         //
@@ -199,7 +198,40 @@ You can optionally add a note to the field to describe the field better.
         optional double atmospheric_pressure = 1;
     }
 
-If you want to provide a reference to a DIN or to web page which helps in understanding the field you can add a reference.
+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" <https://apastyle.apa.org/>`_ 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 <em>title</em>.
+- 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 <surname>, <initial(s)> like Authorname, A. A.
+- Editor names are written as <initial(s)> <surname> 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 <https://apastyle.apa.org/style-grammar-guidelines/references/examples>`_ and in existing entries.
+- The scheme of popular sources for the reference list is as follows (replace tags with corresponding values):
+
+1. <author1>, <author2>, <author3> & <author4>. (<year>). Contribution in a compilation title. <em><Compilation Title></em>. <edition>. <page(s)>. <publisher>. <location>. <doi>. <page(s)>.
+
+2. <author1>, <author2> & <author3>. (<year>). <em><book (monograph) title></em>. <edition>. <publisher>. <doi>. <page(s)>.
+
+3. <author1> & <author2>. (<year>). <book chapter title>. In <editor1> & <editor2> (Eds.), <em><book title></em> (<page(s)>). <publisher>. <doi>. <page(s)>.
+
+4. <author1> & <author2>. (<year>). <journal article title>. <em><journal title></em>. <page(s)>. <location>. <doi>. <page(s)>.
+
+5. <author>. (<year>). <em><Phd thesis title></em>. Phd. thesis. <location>. <university>. <doi or url>. <page(s)>.
+
+6. <author>. (<year>, <month> <day>). <em><internet article title></em>. Retrieved <month> <day>, <year>, from <url>.
+
+7. <standarding organisation>. (<year>). <em><title of the standard></em>. (<standard identifier>). <location>.
+
+8. <author>. (<year>). <em><patent title and id></em>. <location>. <organisation>.
+
+
 
 .. code-block:: protobuf
 
@@ -213,14 +245,15 @@ If you want to provide a reference to a DIN or to web page which helps in unders
     //
     message EnvironmentalConditions
     {
-        // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 Pa).
+        // 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 Reference:
-        // - [1] [Definition atmospheric pressure](https://en.wikipedia.org/wiki/Atmospheric_pressure)
+        // \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;
     }
@@ -239,14 +272,15 @@ Finally you can provide a set of rules which this field needs to be followed. Th
     //
     message EnvironmentalConditions
     {
-        // Atmospheric pressure in Pascal at z=0.0 in world frame (about 101325 Pa).
+        // 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 Reference:
-        // - [1] [Definition atmospheric pressure](https://en.wikipedia.org/wiki/Atmospheric_pressure)
+        // \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
@@ -262,45 +296,21 @@ The rule definition must follow the syntax which is defined by a regex search wh
 
 .. code-block:: python
     
-    'is_greater_than':              r'\b(is_greater_than)\b: \d+(\.\d+)?'                                                   # is_greater_than: 1
-    'is_greater_than_or_equal_to':  r'\b(is_greater_than_or_equal_to)\b: \d+(\.\d+)?'                                       # is_greater_than_or_equal_to: 1
-    'is_less_than_or_equal_to':     r'\b(is_less_than_or_equal_to)\b: \d+(\.\d+)?'                                          # is_less_than_or_equal_to: 10
-    'is_less_than':                 r'\b(is_less_than)\b: \d+(\.\d+)?'                                                      # is_less_than: 2
-    'is_equal':                     r'\b(is_equal)\b: \d+(\.\d+)?'                                                          # is_equal: 1
-    'is_different':                 r'\b(is_different)\b: \d+(\.\d+)?'                                                      # is_different: 2
-    'is_global_unique':             r'\b(is_global_unique)\b'                                                               # is_global_unique
-    'refers':                       r'\b(refers)\b'                                                                         # refers
-    'is_iso_country_code':          r'\b(is_iso_country_code)\b'                                                            # is_iso_country_code
-    'first_element':                r'\b(first_element)\b: \{.*: \d+\.\d+\}'                                                # first_element: {is_equal: 0.13, is_greater_than: 0.13}
-    'last_element':                 r'\b(last_element)\b: \{.*: \d+\.\d+\}'                                                 # last_element: {is_equal: 0.13, is_greater_than: 0.13}
-    'is_optional':                  r'\b(is_optional)\b'                                                                    # is_optional
-    'check_if':                     r'\b(check_if)\b: \[\{.*: \d+(\.\d+)?, target: .*}, \{do_check: \{.*: \d+(\.\d+)?}}]'   # check_if: [{is_equal: 2, is_greater_than: 3, target: this.y}, {do_check: {is_equal: 1, is_less_than: 3}}]
-
-You can check the correctness of these regular expression on `regex101 <https://regex101.com/r/6tomm6/16>`_.
-
-
-.. is_greater_than: 2
-.. is_greater_than: 2.23
-.. is_greater_than_or_equal_to: 1
-.. is_greater_than_or_equal_to: 1.12
-.. is_less_than_or_equal_to: 10
-.. is_less_than_or_equal_to: 10.123
-.. is_less_than: 2
-.. is_less_than: 2.321
-.. is_equal: 1
-.. is_equal: 1.312
-.. is_different: 2
-.. is_different: 2.2122
-.. is_global_unique
-.. refers
-.. is_iso_country_code
-.. first_element: {is_equal: 3, is_greater: 2}
-.. first_element: {is_equal: 0.13, is_greater: 0.13}
-.. last_element: {is_equal: 3, is_greater: 2}
-.. last_element: {is_equal: 0.13, is_greater: 0.13}
-.. check_if: [{is_equal: 2, is_greater_than: 3, target: this.y}, {do_check: {is_equal: 1, is_less_than: 3}}]
-.. is_set
- 
+    '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
 ------------------------------------
@@ -318,8 +328,8 @@ If you want to reference message fields and enums add '#' to the enum/field name
 
     // A reference to a enum e.g. \c #COLOR_GREEN.
 
-Commenting with links
-----------------------
+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

doc/description.rst

@@ -15,6 +15,10 @@ 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
 -------------
 

doc/fileformat.rst

@@ -36,6 +36,33 @@ In summary we have currently three types of formats:
 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:
@@ -47,7 +74,7 @@ If you want to generate a valid OSI trace file which can be used as an input for
 
     def main():
         """Initialize SensorView"""
-        f = open("test_trace.osi", "ab")
+        f = open("sv_312_320_10_movingobject.osi", "ab")
         sensorview = SensorView()
 
         sv_ground_truth = sensorview.global_ground_truth
@@ -95,5 +122,5 @@ In the script we initialize the type we want to use for the messages. Here we us
 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 ``test_trace.osi``. 
-After finishing the loop we now have a ``test_trace.osi`` file which can be `validated <https://github.com/OpenSimulationInterface/osi-validation>`_ and `visualized <https://github.com/OpenSimulationInterface/osi-visualizer>`_.
+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>`_.