diff --git a/doc/architecture/architecture_overview.adoc b/doc/architecture/architecture_overview.adoc new file mode 100644 index 000000000..b7938a906 --- /dev/null +++ b/doc/architecture/architecture_overview.adoc @@ -0,0 +1,36 @@ += Overview of OSI architecture + +OSI contains an object-based environment description using the message format of the https://github.com/protocolbuffers/protobuf/wiki[Protocol Buffer] library developed and maintained by Google. +OSI defines top-level messages that are used to exchange data between separate models. +Top-level messages define the ``GroundTruth`` interface, the ``SensorData`` interface and, since OSI version 3.0.0, the ``SensorView``, ``SensorViewConfiguration`` and ``FeatureData`` interfaces. + +The following figure shows the interfaces and models involved in modeling a sensor. + +.Open Simulation Interface overview +image::osi-context.png[1100] + + +OSI also defines interfaces for traffic participant models. +These interfaces allow to send commands to traffic participant models and to receive their updated state. +The following figure shows the interfaces of a generic traffic participant. + +.Interface of a traffic participant +image::osi-traffic-participant-principle.png[1100] + +Traffic participant models may use other OSI interfaces internally, for example, to model autonomous vehicles. +The following figure shows a more advanced use case for traffic participants. + +.Traffic participant with sensor models, AD function, and dynamic model +image::osi-traffic-participant-advanced.png[1100] + +OSI currently provides only limited support for data structures describing measured internal states of the traffic participant. +Actuator intentions are currently not covered by OSI and must be handled with a different data description format. + +All fields in an 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 via custom fields. +Therefore, no future evolution of OSI will use field numbers of 10000 or above. \ 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..a27bc026e --- /dev/null +++ b/doc/architecture/environmental_effect_model.adoc @@ -0,0 +1,9 @@ += Environmental effect model + +Environmental effect models consume sensor-view data and produce sensor-view data. +Environmental effect models may, for example, include the following: + +* Shadows and oclusion +* Weather effects +* Physics of a sensor +* Pre-processing of raw sensor data diff --git a/doc/architecture/feature_data.adoc b/doc/architecture/feature_data.adoc new file mode 100644 index 000000000..f739be7d8 --- /dev/null +++ b/doc/architecture/feature_data.adoc @@ -0,0 +1,5 @@ += Feature data + +Feature data contains detected features in the reference frame of a sensor. +Feature data is generated from ground-truth data. +It serves, for example, as input for sensor models simulating object detection or feature fusion models. diff --git a/doc/architecture/formatting_scripts.adoc b/doc/architecture/formatting_scripts.adoc new file mode 100644 index 000000000..fde9bac4f --- /dev/null +++ b/doc/architecture/formatting_scripts.adoc @@ -0,0 +1,48 @@ +# Trace-file formatting scripts + +OSI provides Python scripts for converting trace files from one format to the other. +The formatting scripts are stored in `open-simulation-interface/format/` + +**txt2osi.py** + +`txt2osi.py` converts plain-text trace files to binary `.osi` trace files. +This script takes the following parameters: + +`--data`, `-d`:: +String containing the path to the file with serialized data. + +`--type`, `-t`:: +Optional string containing the name of the type used to serialize data. +Allowed values are `'SensorView'`, `'GroundTruth'`, and `'SensorData'`. +The default value is `'SensorView'`. + +`--output`, `-o`:: +Optional string containing the name of the output file., +The default value is `'converted.osi'`. + +`--compress`, `-c`:: +Optional boolean controlling whether to compress the output to a lzma file.. +Allowed values are `True`, and `False`. +The default value is `False`. + +**osi2read.py** + +`osi2read.py` converts trace files to human-readable `.txth` trace files. +This script takes the following parameters: + +`--data`, `-d`:: +String containing the path to the file with serialized data. + +`--type`, `-t`:: +Optional string containing the name of the type used to serialize data. +Allowed values are `'SensorView'`, `'GroundTruth'`, and `'SensorData'`. +The default value is `'SensorView'`. + +`--output`, `-o`:: +Optional string containing the name of the output file., +The default value is `'converted.txth'`. + +`--format`, `-f`:: +Optional string containing the format type of the trace. +Allowed values are `'separated'`, and `None`. +The default value is `None`. \ No newline at end of file diff --git a/doc/architecture/ground_truth.adoc b/doc/architecture/ground_truth.adoc new file mode 100644 index 000000000..7ae617f47 --- /dev/null +++ b/doc/architecture/ground_truth.adoc @@ -0,0 +1,5 @@ += Ground truth + +Ground truth describes the simulated environment around all simulated objects in the global coordinate system. +It is based on data available to the simulation environment and published to external subscribers. +Depending on the external subscriber, ground-truth data may be individually restricted to reduce the data to be exchanged. diff --git a/doc/architecture/logical_model.adoc b/doc/architecture/logical_model.adoc new file mode 100644 index 000000000..cdfe0d5b9 --- /dev/null +++ b/doc/architecture/logical_model.adoc @@ -0,0 +1,6 @@ += Logical model + +Logical models consume sensor-data data and produce sensor-data data. + +An example of a logical model is a sensor-fusion model, which fuses the output of multiple sensor models. +Another use case is the injection of faults after the sensor model. 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_coordinate_systems.adoc b/doc/architecture/reference_points_coordinate_systems.adoc new file mode 100644 index 000000000..08d72cb2a --- /dev/null +++ b/doc/architecture/reference_points_coordinate_systems.adoc @@ -0,0 +1,26 @@ += Reference points and coordinate systems + +With Open Simulation Interface, an object's position coordinates refer to the center of the object's bounding box. +This reference point is not necessarily identical to the origin of the respective coordinate systems. +OSI uses DIN ISO 8855:2013-11 for coordinate systems and transformations between coordinate systems. + +OSI uses three coordinate systems: + +World coordinate system:: +Coordinate system for all quantities which are part of ground truth. +The world coordinate system is an inertial x/y/z-coordinate system. + +Sensor coordinate system:: +Coordinate system for all quantities which are part of sensor data. +The origin is the mounting position of the physical sensor or a virtual mounting position, depending on the technology. + +Object coordinate system:: +Coordinate system for local object coordinates, for example, vehicle coordinates. +For vehicles, the origin is the middle of the rear axle projected onto the ground. +Other objects may use different origins. + +The following image shows an example of the differents coordinate systems. +It also shows that the reference point of the vehicle is located in the center of its bounding box whereas the origin of the vehicle coordinate system is the middle of rear axle projected onto the ground. +In this example, the virtual mounting position coincides with the origin of the vehicle coordinate system. + +image::{imagedir}/osi_coordinate_systems.png[] \ 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..bcef34070 --- /dev/null +++ b/doc/architecture/sensor_data.adoc @@ -0,0 +1,6 @@ += Sensor data + +Sensor data imitates the output of real sensors. +It is generated from ground-truth data, sensor-view data, feature data or from sensor data. +All information regarding the environment is given with respect to the virtual sensor coordinate system, except for feature data, which is given with respect to the physical sensor coordinate system. +Sensor data can be used as input for an automated driving function, a sensor model simulating limited perception, or a sensor fusion model. diff --git a/doc/architecture/sensor_model.adoc b/doc/architecture/sensor_model.adoc new file mode 100644 index 000000000..b2c373774 --- /dev/null +++ b/doc/architecture/sensor_model.adoc @@ -0,0 +1,6 @@ += Sensor model + +Sensor models consume sensor-view data and produce sensor-data data. +Those models can be based on physics or phenomenological. + +Sensor-model output does not represent raw data, but detected features or classified objects. \ 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..54f8fdd85 --- /dev/null +++ b/doc/architecture/sensor_view.adoc @@ -0,0 +1,8 @@ += Sensor view + +Sensor view imitates the input of sensors. +Sensor-view data is derived from ground-truth data. +All information regarding the environment is given with respect to the virtual sensor coordinate system, with two exceptions: + +* Physical technology-specific data, given with respect to the physical sensor coordinate system specified in the corresponding physical sensor’s mounting position. +* Ground-truth data, given in the global coordinate system. \ No newline at end of file diff --git a/doc/architecture/sensor_view_configuration.adoc b/doc/architecture/sensor_view_configuration.adoc new file mode 100644 index 000000000..cde42c688 --- /dev/null +++ b/doc/architecture/sensor_view_configuration.adoc @@ -0,0 +1,11 @@ += Sensor view configuration + +The sensor view configuration configures the sensor view. +It is provided by the environment simulation. +Sensor view configuration data is intended for the automatic configuration of an environment simulation in order to supply the necessary input to a sensor model. +Sensor view configuration data is not intended to provide parameters to a generic sensor model. + +Sensor view configuration data can also be provided by the sensor model to the environment simulation. +In that case, it describes the input configuration that is desired by the sensor model. +In response the environment simulation will configure the input and provide a new message which describes the actual configuration. +These two messages may differ, when the environment simulation does not support a given requested configuration or when the requested configuration allowed is ambiguous. 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..9831b8834 --- /dev/null +++ b/doc/architecture/trace_file_formats.adoc @@ -0,0 +1,18 @@ += OSI trace file formats + +There are multiple formats for storing multiple serialized OSI messages into one trace file + +*.osi:: +Binary trace file. +Messages are separated by a length specifications before each message. +The length is represented by a four-byte, little-endian, unsigned integer. +The length does not include the integer itself. + +*.txt:: +Plain-text trace file. +Messages are separated by `$$__$$`. + +*.txth:: +Human-readable plain-text trace file. +Messages are separated by newlines. +Such a filen may be used for manual checks. diff --git a/doc/architecture/trace_file_naming.adoc b/doc/architecture/trace_file_naming.adoc new file mode 100644 index 000000000..dcd20e497 --- /dev/null +++ b/doc/architecture/trace_file_naming.adoc @@ -0,0 +1,21 @@ += OSI trace file naming conventions + +**Name format** + +Names of OSI trace files should have the following format: + +[source] +---- +____.osi +---- + +**Types** + +`sd`:: +Trace file contains sensor-data messages. + +`sv`:: +Trace file contains sensor-view messages. + +`gt`:: +Trace file contains ground-truth messages. diff --git a/doc/architecture/traffic_command.adoc b/doc/architecture/traffic_command.adoc new file mode 100644 index 000000000..6e70b6bd4 --- /dev/null +++ b/doc/architecture/traffic_command.adoc @@ -0,0 +1,3 @@ += Traffic command + +Traffic commands contain control commands from the scenario engine to traffic participant models. \ 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..f6bed48b3 --- /dev/null +++ b/doc/architecture/traffic_participant.adoc @@ -0,0 +1,31 @@ += 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. + +.Interface of a traffic participant +image::osi-traffic-participant-principle.png[1100] + +Traffic participant models may use other OSI interfaces internally, for example, to model autonomous vehicles. +The following figure shows a more advanced use case for traffic participants. + +.Traffic participant using other OSI interfaces internally +image::osi-traffic-participant-advanced.png.png[1100] + +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/traffic_update.adoc b/doc/architecture/traffic_update.adoc new file mode 100644 index 000000000..b8795e645 --- /dev/null +++ b/doc/architecture/traffic_update.adoc @@ -0,0 +1,4 @@ += Traffic update + +Traffic updates are provided by traffic participants. +They provide updates of the position, state and future trajectory of a traffic participant back to the simulation environment. \ No newline at end of file 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/images/osi-context.png b/doc/images/osi-context.png new file mode 100644 index 000000000..0738c3831 Binary files /dev/null and b/doc/images/osi-context.png differ diff --git a/doc/images/osi-traffic-participant-advanced.png b/doc/images/osi-traffic-participant-advanced.png new file mode 100644 index 000000000..451e4b32b Binary files /dev/null and b/doc/images/osi-traffic-participant-advanced.png differ diff --git a/doc/images/osi-traffic-participant-principle.png b/doc/images/osi-traffic-participant-principle.png new file mode 100644 index 000000000..45e886360 Binary files /dev/null and b/doc/images/osi-traffic-participant-principle.png differ diff --git a/doc/images/osi_coordinate_systems.png b/doc/images/osi_coordinate_systems.png new file mode 100644 index 000000000..84ac55d30 Binary files /dev/null and b/doc/images/osi_coordinate_systems.png differ 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..36f83a1ef --- /dev/null +++ b/doc/misc/osi_reference.adoc @@ -0,0 +1,5 @@ += Reference documentation + +The reference documentation for OSI is generated with Doxygen. +It is available at: +https://opensimulationinterface.github.io/open-simulation-interface/annotated.html 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..fff969b0c --- /dev/null +++ b/doc/open-simulation-interface_user_guide.adoc @@ -0,0 +1,144 @@ += Open simulation interface +:revnumber: v.v.v +:revdate: dd.mm.yyyy +:toc: left +:toclevels: 2 +:sectnums: + +:topicdir: topics +:reusedir: reuse +:imagedir: images + +// 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] + +include::./architecture/traffic_command.adoc[leveloffset=+3] + +include::./architecture/traffic_update.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 (level 3) + +include::./architecture/reference_points_coordinate_systems.adoc[leveloffset=+2] + +//=== 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_cpp.adoc[leveloffset=+2] + +include::./setup/installing_linux_python.adoc[leveloffset=+2] + +include::./setup/installing_windows_cpp.adoc[leveloffset=+2] + +include::./setup/installing_windows_python.adoc[leveloffset=+2] + +include::./setup/installing_macos.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] + +include::./usecases/transforming_coordinate_systems.adoc[leveloffset=+2] + +//== Improving performance + +//TODO: Define topics and issues regarding performance. + +include::./misc/osi_reference.adoc[leveloffset=+1] + +== Releases and compatibility + +include::./releases/versioning.adoc[leveloffset=+2] + +include::./releases/releases.adoc[leveloffset=+2] + +include::./releases/v02.00.adoc[leveloffset=+3] + +include::./releases/v02.01.adoc[leveloffset=+3] + +include::./releases/v02.02.adoc[leveloffset=+3] + +include::./releases/v03.00.adoc[leveloffset=+3] + +include::./releases/v03.01.adoc[leveloffset=+3] + +include::./releases/v03.02.adoc[leveloffset=+3] + +include::./releases/v03.03.adoc[leveloffset=+3] + +//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 092524a9f..000000000 --- a/doc/releases.rst +++ /dev/null @@ -1,14 +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 - releases/v03.03 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..1dab61829 --- /dev/null +++ b/doc/releases/releases.adoc @@ -0,0 +1,3 @@ += Releases + +ss \ No newline at end of file diff --git a/doc/releases/v02.00.rst b/doc/releases/v02.00.adoc similarity index 81% rename from doc/releases/v02.00.rst rename to doc/releases/v02.00.adoc index a05d1dc29..8d8bffa7e 100644 --- a/doc/releases/v02.00.rst +++ b/doc/releases/v02.00.adoc @@ -1,25 +1,25 @@ -`v2.0.0 - OSI Initial Commit <https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.0.0>`_ -============================ += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.0.0[v2.0.0 - OSI Initial Commit] + This is the initial version of the Open Simulation Interface (OSI). -Overview: ------------ +== Overview + OSI is a generic interface for the environmental perception of automated driving functions in virtual scenarios. It is primarily conceived to enable easy and straightforward compatibility between automated driving functions and the variety of driving simulation frameworks available. The data description has been derived from the perspective of sensor modeling for automated test and validation of highly automated driving functions. -Implementation: ----------------- -OSI primarily contains an object based environment description using the message format of the protocol buffers library developed and maintained by Google. +== Implementation -Detailed description: ---------------------- +OSI primarily contains an object based environment description using the message format of the protocol buffers library developed and maintained by Google. -**Top level interfaces**: -OSI consists of two individual top level interfaces for object data: The ``OSI::GroundTruth`` and the ``OSI::SensorData`` interface. +== Detailed description -- The ``OSI::GroundTruth`` interface provides an exact view on the simulated objects in a global coordinate system. This message is populated using the internally available data of the used (driving)-simulation framework and is afterwards published to external subscribers with an exporter plugin. -- The ``OSI::SensorData`` interface describes the objects in the reference frame of a sensor for environmental perception. It is generated from a ``OSI::GroundTruth`` message and can either be used to directly connect to an automated driving function using ideal simulated data, or may serve as input for a sensor model simulating limited perception as a replication of real world sensor behavior. +Top level interfaces:: +OSI consists of two individual top level interfaces for object data: The ``OSI::GroundTruth`` and the ``OSI::SensorData`` interface. ++ +* The ``OSI::GroundTruth`` interface provides an exact view on the simulated objects in a global coordinate system. This message is populated using the internally available data of the used (driving)-simulation framework and is afterwards published to external subscribers with an exporter plugin. +* The ``OSI::SensorData`` interface describes the objects in the reference frame of a sensor for environmental perception. It is generated from a ``OSI::GroundTruth`` message and can either be used to directly connect to an automated driving function using ideal simulated data, or may serve as input for a sensor model simulating limited perception as a replication of real world sensor behavior. -**Low level interfaces**: +Low level interfaces:: ++ Additionally to the two top level interfaces, OSI contains an ``OSI::LowLevelData`` message. This message describes the output of a (physical) model of the measurement process before tracking and object hypothesis. It does not deal with object data, but may comprise the geometrical influence of 3D simulations e.g. generating Lidar point clouds with a ray-tracer plugin. In addition this message supports generic radar reflection lists and will be extended to supporting low level camera data in the future. diff --git a/doc/releases/v02.01.adoc b/doc/releases/v02.01.adoc new file mode 100644 index 000000000..005e4e1ac --- /dev/null +++ b/doc/releases/v02.01.adoc @@ -0,0 +1,12 @@ += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.1.0[v2.1.0 - OSI "Agile Andretti"] + +== Purpose + +This is the initial BASE VERSION for Tool Development. + +https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/1?closed=1[Content/Changes] + +== Remarks + +We will now release the versions using the name of a https://en.wikipedia.org/wiki/List_of_Formula_One_drivers[Formula 1 driver]! +Naming convention: "adjective + last name driver" -> Alliteration necessary! \ No newline at end of file diff --git a/doc/releases/v02.01.rst b/doc/releases/v02.01.rst deleted file mode 100644 index d49efb46a..000000000 --- a/doc/releases/v02.01.rst +++ /dev/null @@ -1,14 +0,0 @@ -`v2.1.0 - OSI "Agile Andretti" <https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.1.0>`_ -=============================== - -Purpose: ----------- -This is the initial BASE VERSION for Tool Development. - -`Content/Changes <https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/1?closed=1>`_: ------------------------------------------------------------------------------------------------------------------ - -Remarks: ------------ -We will now release the versions using the name of a `Formula 1 driver <https://en.wikipedia.org/wiki/List_of_Formula_One_drivers>`_! -Naming convention: "adjective + last name driver" -> Alliteration necessary! \ No newline at end of file diff --git a/doc/releases/v02.02.adoc b/doc/releases/v02.02.adoc new file mode 100644 index 000000000..a0ef709e7 --- /dev/null +++ b/doc/releases/v02.02.adoc @@ -0,0 +1,26 @@ += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.0[v2.2.0 - OSI "Brave Brabham"] + +== Purpose + +This release focuses on optimizing the build process and documentation. + +== https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/2?closed=1[Content/Changes] + +* Added a shared library target to the CMake build script. +* Generated a proper doxygen documentation. +* Placed the version number in one file (VERSION). +* Added unit testing mechanism including style guide checking. +* Redefined precipitation and added a fog definition to the environmental conditions message. +* Added layer id to low level point cloud data. +* Reworked large parts of the build instructions in the WIKI. + += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.1[v2.2.1 - OSI "Brave Brabham", Update 1] + +== Purpose + +This release focuses on optimizing the build process and ensures the proper installation of different versions of OSI on a single system. + +== https://github.com/OpenSimulationInterface/open-simulation-interface/compare/maintenance/v2.2.x[Content/Changes] + +* Allowing several OSI versions on the same computer. +* Improves CI builds to also test the installation cmake targets for proper completion. diff --git a/doc/releases/v02.02.rst b/doc/releases/v02.02.rst deleted file mode 100644 index 1fadf92e2..000000000 --- a/doc/releases/v02.02.rst +++ /dev/null @@ -1,30 +0,0 @@ -`v2.2.0 - OSI "Brave Brabham" <https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.0>`_ -============================== - -Purpose: ---------- -This release focuses on optimizing the build process and documentation. - -`Content/Changes <https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/2?closed=1>`_: ------------------------------------------------------------------------------------------------------------------------ - -- Added a shared library target to the CMake build script. -- Generated a proper doxygen documentation. -- Placed the version number in one file (VERSION). -- Added unit testing mechanism including style guide checking. -- Redefined precipitation and added a fog definition to the environmental conditions message. -- Added layer id to low level point cloud data. -- Reworked large parts of the build instructions in the WIKI. - -`v2.2.1 - OSI "Brave Brabham", Update 1 <https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v2.2.1>`_ -======================================== - -Purpose: ---------- -This release focuses on optimizing the build process and ensures the proper installation of different versions of OSI on a single system. - -`Content/Changes <https://github.com/OpenSimulationInterface/open-simulation-interface/compare/maintenance/v2.2.x>`_: ------------------------------------------------------------------------------------------------------------------------ - -- Allowing several OSI versions on the same computer. -- Improves CI builds to also test the installation cmake targets for proper completion. diff --git a/doc/releases/v03.00.adoc b/doc/releases/v03.00.adoc new file mode 100644 index 000000000..c9b0b85db --- /dev/null +++ b/doc/releases/v03.00.adoc @@ -0,0 +1,56 @@ += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.0[v3.0.0 - OSI "Cosmic Coulthard"] + +== Purpose + +This release is a complete rework including the feedback from many OSI users. Thank you! +We are aligned with the ongoing discussions for the upcoming ISO 23150 standard for hardware sensor outputs in order to bring simulation and the hardware in the car closer together. + +https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.0[Content/Changes] + +* Added major version to package label (osi3), allowing concurrent use of OSI 2.x and OSI 3.x in one process. +* Added new top-level messages (new concept SensorView (Configuration),etc.). +** GroundTruth. +** SensorView. +** SensorData / FeatureData. +** SensorViewConfiguration (used for auto-configuration of SensorView). +* Added technology-specific SensorView sub-messages to aid physical models. +* Introduced conceptual separation of “SensorModels” and “LogicModels”. +* Extended enumerations (e.g. traffic sign Type according to StVO, vehicle Type, etc.). +* Improved messages and definitions (additional RoadConditions, country code in GT, AmbientIllumination, etc.). +* Use ISO 8855 coordinate systems (incompatible with earlier OSI versions). +* Redefined DetectedXXX messages. +* Introduced DetectedStationaryObjects. +* Merged MovingObjects and Vehicle messages. +* Redefined Lane messages (with separated lane boundary messages and intersections). +* Redefined TrafficLight messages. +* Redefined TrafficSigns (1 x MainSign + n x SupplementarySign inclusive BaseStationary). +* New FeatureData messages (rework of previous LowLevelData message) - aligned with an upcoming standard ISO 23150. +* FeatureData usable for fusion units. +* Extension and clarification of the existing doxygen documentation. +* Improved doxygen collaboration diagrams. +* Build process improvements, added install targets. +* Made proto definitions compatible with proto3 restrictions to allow concurrent use with proto3-only implementations in the future. +* Fixed version-checking of transmitted data. +* AND MUCH MORE ENJOY!!! + +https://github.com/OpenSimulationInterface/open-simulation-interface/files/2297162/osi_overview_v2.2_vs_v3.0.pdf>[See for more information the `changelog`] + += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.1[v3.0.1 - OSI "Cosmic Coulthard", Update 1] + +https://www.youtube.com/watch?v=yG0oBPtyNb0[Summertime :)] + +== Purpose + +This release is a patch reworking parts of the documentation in order to avoid ambiguities and improving the build/installation process of OSI. + +https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.1[Content/Changes] + +* Added script to automatically convert the messages from proto2 to proto3 with on the wire compatibility +* cmake enhancements to enable multi-version support of OSI 2 and OSI 3 +* Added Python 3 support +* Clarification of multiple comments +* Added explanatory images in the documentation +* centerline definition improved +* signal_strength definition in LidarSensorView corrected +* FeatureData::ambiguity_id definition clarified +* RadarSensorViewConfiguration::AntennaDiagram::response definition clarified diff --git a/doc/releases/v03.00.rst b/doc/releases/v03.00.rst deleted file mode 100644 index 7f4706549..000000000 --- a/doc/releases/v03.00.rst +++ /dev/null @@ -1,60 +0,0 @@ -`v3.0.0 - OSI "Cosmic Coulthard" <https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.0>`_ -================================= - -Purpose: ---------- -This release is a complete rework including the feedback from many OSI users. Thank you! -We are aligned with the ongoing discussions for the upcoming ISO 23150 standard for hardware sensor outputs in order to bring simulation and the hardware in the car closer together. - -`Content/Changes <https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.0>`_: ---------------------------------------------------------------------------------------------------------------------------------------------------- - -- Added major version to package label (osi3), allowing concurrent use of OSI 2.x and OSI 3.x in one process. -- Added new top-level messages (new concept SensorView (Configuration),etc.). - - GroundTruth. - - SensorView. - - SensorData / FeatureData. - - SensorViewConfiguration (used for auto-configuration of SensorView). -- Added technology-specific SensorView sub-messages to aid physical models. -- Introduced conceptual separation of “SensorModels” and “LogicModels”. -- Extended enumerations (e.g. traffic sign Type according to StVO, vehicle Type, etc.). -- Improved messages and definitions (additional RoadConditions, country code in GT, AmbientIllumination, etc.). -- Use ISO 8855 coordinate systems (incompatible with earlier OSI versions). -- Redefined DetectedXXX messages. -- Introduced DetectedStationaryObjects. -- Merged MovingObjects and Vehicle messages. -- Redefined Lane messages (with separated lane boundary messages and intersections). -- Redefined TrafficLight messages. -- Redefined TrafficSigns (1 x MainSign + n x SupplementarySign inclusive BaseStationary). -- New FeatureData messages (rework of previous LowLevelData message) - aligned with an upcoming standard ISO 23150. -- FeatureData usable for fusion units. -- Extension and clarification of the existing doxygen documentation. -- Improved doxygen collaboration diagrams. -- Build process improvements, added install targets. -- Made proto definitions compatible with proto3 restrictions to allow concurrent use with proto3-only implementations in the future. -- Fixed version-checking of transmitted data. -- AND MUCH MORE ENJOY!!! - -See for more information the `changelog <https://github.com/OpenSimulationInterface/open-simulation-interface/files/2297162/osi_overview_v2.2_vs_v3.0.pdf>`_. - -`v3.0.1 - OSI "Cosmic Coulthard", Update 1 <https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.0.1>`_ -========================================== - -`Summertime :) <https://www.youtube.com/watch?v=yG0oBPtyNb0>`_ - -Purpose: ---------- -This release is a patch reworking parts of the documentation in order to avoid ambiguities and improving the build/installation process of OSI. - -`Content/Changes <https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?page=1&q=is%3Apr+is%3Aclosed+milestone%3Av3.0.1>`_: ---------------------------------------------------------------------------------------------------------------------------------------------------- - -- Added script to automatically convert the messages from proto2 to proto3 with on the wire compatibility -- cmake enhancements to enable multi-version support of OSI 2 and OSI 3 -- Added Python 3 support -- Clarification of multiple comments -- Added explanatory images in the documentation -- centerline definition improved -- signal_strength definition in LidarSensorView corrected -- FeatureData::ambiguity_id definition clarified -- RadarSensorViewConfiguration::AntennaDiagram::response definition clarified diff --git a/doc/releases/v03.01.adoc b/doc/releases/v03.01.adoc new file mode 100644 index 000000000..5f1487925 --- /dev/null +++ b/doc/releases/v03.01.adoc @@ -0,0 +1,33 @@ += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.0[v3.1.0 - OSI "Dynamic Duncan"] + +https://www.youtube.com/watch?v=fu3uA8K6ApQ>[(O SI)lent night] + +== Purpose + +This time of the year Santa comes with presents and has also thought about the sensor modelers of this planet. We introduce the current state of the ISO 23150 discussions including Ultrasonic and Camera Detections. The traffic signs have been reworked and the documentation has been extended for a perfect user experience. Trust me - it's amazing! + +== https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.0>[Content/Changes] + +* Complete rework of traffic signs including images in documentation. +* Added Camera Detections in osi_featuredata.proto. +* Added Ultrasonic Detections in osi_featuredata.proto. +* Introduced light states for emergency and service vehicles. +* Added orientation_acceleration and updated formulas. +* Extended documentation with svg images. +* Added model_reference for static and moving objects. +* Added map_reference in ground truth. +* Added proj4 string for coordinate transformations. +* Introduced raster_lidar_proposal from innoviz. +* Improved documentation with HTML tables and images for all traffic signs. + += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.1[v3.1.1 - OSI "Dynamic Duncan", Update 1] + +== https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.1[Content/Changes] + +* **Bug Fix**: Changed open_simulation_interface target back from being a static library to a shared library, as before (this reverts an inadvertent change in v3.1.0 from previous releases). v3.1.0 breaks all users of the shared library (i.e. everyone building on Linux/Unix systems, and even some using the DLL on Windows). + += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.2[v3.1.2 - OSI "Dynamic Duncan", Update 2] + +== https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.2[Content/Changes] + +* **Bugfix**: The version number is now correct in the VERSION file. diff --git a/doc/releases/v03.01.rst b/doc/releases/v03.01.rst deleted file mode 100644 index 149663d97..000000000 --- a/doc/releases/v03.01.rst +++ /dev/null @@ -1,37 +0,0 @@ -`v3.1.0 - OSI "Dynamic Duncan" <https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.0>`_ -============================== - -`(O SI)lent night <https://www.youtube.com/watch?v=fu3uA8K6ApQ>`_ - -Purpose: ---------- -This time of the year Santa comes with presents and has also thought about the sensor modelers of this planet. We introduce the current state of the ISO 23150 discussions including Ultrasonic and Camera Detections. The traffic signs have been reworked and the documentation has been extended for a perfect user experience. Trust me - it's amazing! - -`Content/Changes <https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.0>`_: ---------------------------------------------------------------------------------------------------------------------------------------------- - -- Complete rework of traffic signs including images in documentation. -- Added Camera Detections in osi_featuredata.proto. -- Added Ultrasonic Detections in osi_featuredata.proto. -- Introduced light states for emergency and service vehicles. -- Added orientation_acceleration and updated formulas. -- Extended documentation with svg images. -- Added model_reference for static and moving objects. -- Added map_reference in ground truth. -- Added proj4 string for coordinate transformations. -- Introduced raster_lidar_proposal from innoviz. -- Improved documentation with HTML tables and images for all traffic signs. - -`v3.1.1 - OSI "Dynamic Duncan", Update 1 <https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.1>`_ -========================================== - -`Content/Changes <https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.1>`_: ---------------------------------------------------------------------------------------------------------------------------------------------- -- **Bug Fix**: Changed open_simulation_interface target back from being a static library to a shared library, as before (this reverts an inadvertent change in v3.1.0 from previous releases). v3.1.0 breaks all users of the shared library (i.e. everyone building on Linux/Unix systems, and even some using the DLL on Windows). - -`v3.1.2 - OSI "Dynamic Duncan", Update 2 <https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.1.2>`_ -========================================== - -`Content/Changes <https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.1.2>`_: ------------------ -- **Bugfix**: The version number is now correct in the VERSION file. diff --git a/doc/releases/v03.02.adoc b/doc/releases/v03.02.adoc new file mode 100644 index 000000000..02b6abf01 --- /dev/null +++ b/doc/releases/v03.02.adoc @@ -0,0 +1,42 @@ += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.2.0[v3.2.0 - OSI "Editorial Eaton"] + +https://www.youtube.com/watch?v=SJUhlRoBL8M[Think p(OSI)tive!] + + + +== Purpose + +The work on the OSI project was until now mainly organized by the BMW AG. In order to enable as many interested parties as possible to +contribute to the success of the Open Simulation Interface the project has been transferred to the https://www.asam.net/[ASAM e.V.] +which has been made public in the https://www.asam.net/news-media/news/detail/news/bmw-transfers-open-simulation-interface-osi-to-asam/[ASAM press release]. +A new chapter in the development of OSI is now opened with the https://www.asam.net/conferences-events/detail/asam-osi-kick-off-workshop/[kickoff workshop] +leading to hopefully many project proposals streamlining the efficient future development of the interface. +Due to this we decided to focus on the improvement of processes and documentation with this release. + +== https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.2.0[Content/Changes] + + +* Updated README according to K(eep) I(t) S(imply) S(tupid) principle +* Added Issue and Pullrequest templates +* Travis CI updated +** Update to bionic 18.04 +** Added tests for building protobuf 2.6 and 3.0 in parallel +** Bugfixed the display of doubled documentation +* Fixed several typos in the comments +* Added a centralized documentation in https://github.com/OpenSimulationInterface/osi-documentation[OSI-Documentation] +** Added contributors guidelines +** Added commenting style guidelines +** Added uniform citation style according to APA +** Updated installation guides for osi in Linux and Windows +** Added a reference in sphinx based on the generated doxygen documentation +* Added rules to the comments in order to enforce osi message validation with the https://github.com/OpenSimulationInterface/osi-validation[OSI-Validator] +* Added the rule definitions in the rules.yml +* Modularized testing of commenting style into python unit tests +* Defined a standardazied a file format for reading trace files (*.osi) +* Defined naming conventions of osi files +* Added a *.txt to *.osi file converter for backward compatibility +* Added a script to make traces readable for plausibility checks +* Corrected the citing style for OSI Bibtex +* Corrected unit specifications and references according to DIN (e.g. removed Unit: []) +* Added timestamp in osi_environment +* Added is_out_of_service bool to traffic light / traffic sign diff --git a/doc/releases/v03.02.rst b/doc/releases/v03.02.rst deleted file mode 100644 index b0342fbb3..000000000 --- a/doc/releases/v03.02.rst +++ /dev/null @@ -1,44 +0,0 @@ -`v3.2.0 - OSI "Editorial Eaton" <https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.2.0>`_ -============================== - -`Think p(OSI)tive! <https://www.youtube.com/watch?v=SJUhlRoBL8M>`_ - -Purpose: ---------- -The work on the OSI project was until now mainly organized by the BMW AG. In order to enable as many interested parties as possible to -contribute to the success of the Open Simulation Interface the project has been transferred to the `ASAM e.V. <https://www.asam.net/>`_ -which has been made public in the `ASAM press release <https://www.asam.net/news-media/news/detail/news/bmw-transfers-open-simulation-interface-osi-to-asam/>`_. -A new chapter in the development of OSI is now opened with the `kickoff workshop <https://www.asam.net/conferences-events/detail/asam-osi-kick-off-workshop/>`_ -leading to hopefully many project proposals streamlining the efficient future development of the interface. -Due to this we decided to focus on the improvement of processes and documentation with this release. - -`Content/Changes <https://github.com/OpenSimulationInterface/open-simulation-interface/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av3.2.0>`_: ---------------------------------------------------------------------------------------------------------------------------------------------- - -- Updated README according to K(eep) I(t) S(imply) S(tupid) principle -- Added Issue and Pullrequest templates -- Travis CI updated - - Update to bionic 18.04 - - Added tests for building protobuf 2.6 and 3.0 in parallel - - Bugfixed the display of doubled documentation -- Fixed several typos in the comments - -- Added a centralized documentation in `OSI-Documentation <https://github.com/OpenSimulationInterface/osi-documentation>`_ - - Added contributors guidelines - - Added commenting style guidelines - - Added uniform citation style according to APA - - Updated installation guides for osi in Linux and Windows - - Added a reference in sphinx based on the generated doxygen documentation - -- Added rules to the comments in order to enforce osi message validation with the `OSI-Validator <https://github.com/OpenSimulationInterface/osi-validation>`_ -- Added the rule definitions in the rules.yml -- Modularized testing of commenting style into python unit tests -- Defined a standardazied a file format for reading trace files (*.osi) -- Defined naming conventions of osi files -- Added a *.txt to *.osi file converter for backward compatibility -- Added a script to make traces readable for plausibility checks -- Corrected the citing style for OSI Bibtex -- Corrected unit specifications and references according to DIN (e.g. removed Unit: []) - -- Added timestamp in osi_environment -- Added is_out_of_service bool to traffic light / traffic sign diff --git a/doc/releases/v03.03.adoc b/doc/releases/v03.03.adoc new file mode 100644 index 000000000..8e46a2627 --- /dev/null +++ b/doc/releases/v03.03.adoc @@ -0,0 +1,40 @@ += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.0[v3.3.0 - OSI "Fabulous Fangio"] + +Stay p(OSI)tive! + +== Purpose + +As a part of the increasing adoption of OSI in the industry, and its movement to ASAM as its home, +several new use cases and extensions for OSI have been identified. +This minor release highlights the work that has been done on several working packages including +the introduction of brand new top level messages which extend OSI's scope beyond the specialized world of sensor modeling. + +== https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/13?closed=1[Content/Changes] + +* Introduced the TrafficCommand top-level message which enables event-based control of traffic participant models, e.g. with regard to a scenario specification. +* Introduced the TrafficUpdate top-level message to send updated properties of traffic participant models. +* Add new LogicalDetectionData message to SensorData, which provides detection data with respect to the reference frame of the logical/virtual sensor. +* Added a new submessage to further specify wheel data. +* Added a new field to support future trajectories of moving objects. +* Added a new subtype message to osi_lane to better align with OpenDrive's lane type information and enable traffic participant models to identify lanes on which they are supposed to move. +* Extended traffic lights and signs messages to include the model_references attribute that can be used to point out to a 3D-model. +* Add global model reference to ground truth that can be used to specify the 3D model representing the environment. +* Extended the camera sensor view configuration to better support the configuration of the simulation environment. +* Added a new field to describe the position of the steering wheel. +* Added a message MovingObjectClassification for classify-able attributes that are shared between different moving object types. Introduced the assigned lane id and the assigned lane percentage of a moving object there. + +* Updated to checklist for pull requests to provide clearer orientation for all users. +* Updated the documentation of centerline and lane boundaries (ordering of the points, describing those lines). +* Updated the documentation of 3D bounding boxes. +* Update the documentation of ground clearance. + +* Make handling of enums in rules check more robust, especially ones. +* Set the default compiler to C++ 11 to support protobuf>3.6. + += https://github.com/OpenSimulationInterface/open-simulation-interface/releases/tag/v3.3.1[v3.3.1 - OSI "Fabulous Fangio", Update 1] + +== https://github.com/OpenSimulationInterface/open-simulation-interface/milestone/18?closed=1[Content/Changes] + + +* **Bug Fix**: Fixed outdated version information in VERSION file in 3.3.0. This lead to wrong versioning in proto definitions and Doxygen documentation. +* **Bug Fix**: Removed outdated picture in README.md. diff --git a/doc/releases/versioning.adoc b/doc/releases/versioning.adoc new file mode 100644 index 000000000..1e38c71f6 --- /dev/null +++ b/doc/releases/versioning.adoc @@ -0,0 +1,35 @@ += Versioning + +The version number is defined in `InterfaceVersion::version_number` in `osi_common.proto` as the field’s default value. + +OSI uses https://semver.org/[Semantic Versioning]. + +Major:: +A change of the major version results in an incompatibility of code and recorded proto messages. ++ +Major changes include: ++ +* An existing field with a number changes its meaning. +Example: `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. ++ +Minor changes include: ++ +* Renaming 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. ++ +Patches include: ++ +* 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/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_cpp.adoc b/doc/setup/installing_linux_cpp.adoc new file mode 100644 index 000000000..590d1667d --- /dev/null +++ b/doc/setup/installing_linux_cpp.adoc @@ -0,0 +1,61 @@ += Installing OSI for C++ on Linux + +**Prerequisites** + +* You have _cmake_ installed. +* You have installed _protobuf_. +* You must have super user privileges. + +**Steps** + +. Open a terminal. +. Clone the Open Simulation repository. ++ +[source] +---- +git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git +---- ++ +. Change into the repository directory. ++ +[source] +---- +cd open-simulation-interface +---- ++ +. Create a new directory for the build. ++ +[source] +---- +mkdir build +---- ++ +. Change into the new directory. ++ +[source] +---- +cd build +---- ++ +. Run cmake. + To build a 32-bit target under 64-bit linux, add `-DCMAKE_CXX_FLAGS="-m32"` to the cmake command. + In this case, protobuf must be in 32-bit mode too. ++ +[source] +---- +cmake .. +---- ++ +. Run make. ++ +[source] +---- +make +---- ++ +. Install Open Simulation Interface. ++ +[source] +---- +sudo make install +---- diff --git a/doc/setup/installing_linux_python.adoc b/doc/setup/installing_linux_python.adoc new file mode 100644 index 000000000..8b753aba8 --- /dev/null +++ b/doc/setup/installing_linux_python.adoc @@ -0,0 +1,43 @@ += Installing OSI for Python on Linux + +**Prerequisites** + +* You have installed _pip3_. +* You have installed _python-setuptools_. +* You have installed _protobuf_. +* For local installation, you have installed _virtualenv_. + +**Steps** + +. Open a terminal. +. Clone the Open Simulation repository. ++ +[source] +---- +git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git +---- ++ +. Change into the repository directory. ++ +[source] +---- +cd open-simulation-interface +---- ++ +. Create a new virtual environment. ++ +[source] +---- +virtualenv -p python3 venv +---- ++ +. Activate the virtual environment. ++ +[source] +---- +source venv/bin/activate +---- ++ +. Install Open Simulation Interface. +Local installation:: `pip3 install .` +Global installation:: `sudo pip3 install .` 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_cpp.adoc b/doc/setup/installing_windows_cpp.adoc new file mode 100644 index 000000000..93ad4c9d3 --- /dev/null +++ b/doc/setup/installing_windows_cpp.adoc @@ -0,0 +1,54 @@ += Installing OSI for C++ on Windows + +**Prerequisites** + +* You have installed _cmake_ as administrator. +* You have installed _protobuf_ as administrator. + +**Steps** + +. Open a terminal as administrator. +. Clone the Open Simulation repository. ++ +[source] +---- +git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git +---- ++ +. Change into the repository directory. ++ +[source] +---- +cd open-simulation-interface +---- ++ +. Create a new directory for the build. ++ +[source] +---- +mkdir build +---- ++ +. Change into the new directory. ++ +[source] +---- +cd build +---- ++ +. Run cmake. + To build a 64-bit target, add `Win64` to the generator name. + In this case, protobuf and protoc.exe must be in 64-bit mode too. ++ +[source] +---- +cmake .. [-G <generator>] [-DCMAKE_INSTALL_PREFIX=<osi-install-directory>] +---- ++ +. Build and install OSI. ++ +[source] +---- +cmake --build . [--config Release] +cmake --build . --target install +---- diff --git a/doc/setup/installing_windows_python.adoc b/doc/setup/installing_windows_python.adoc new file mode 100644 index 000000000..f1b0640e3 --- /dev/null +++ b/doc/setup/installing_windows_python.adoc @@ -0,0 +1,30 @@ += Installing OSI for Python on Windows + +**Prerequisites** + +* You have installed _Python_ with administrator rights. +* Make sure _Python_ is added to `PATH`. + +**Steps** + +. Open a terminal. +. Clone the Open Simulation repository. ++ +[source] +---- +git clone https://github.com/OpenSimulationInterface/open-simulation-interface.git +---- ++ +. Change into the repository directory. ++ +[source] +---- +cd open-simulation-interface +---- ++ +. Run the setup script. ++ +[source] +---- +python setup.py install +---- 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/usecases/transforming_coordinate_systems.adoc b/doc/usecases/transforming_coordinate_systems.adoc new file mode 100644 index 000000000..1342bf87a --- /dev/null +++ b/doc/usecases/transforming_coordinate_systems.adoc @@ -0,0 +1,22 @@ += Transforming coordinate systems + +Transforming coordinates for a specific vehicle or sensor is a common task when running simulations. +OSI uses DIN ISO 8855:2013-11 for coordinate systems and transformations between coordinate systems. + +//TODO: Should we add one or more sentences about the mathematical operations involved? + +**Corresponding messages** + +``GroundTruth::moving_object::base::position``:: +Defines the position of the vehicle’s reference point. + +``GroundTruth::moving_object::base::orientation``:: +Defines the orientation of the vehicle’s reference point. + +``GroundTruth::moving_object::vehicle_attributes::bbcenter_to_rear``:: +The vector pointing from the vehicle’s reference point to the middle of the rear axle under neutral load conditions in vehicle coordinates. +The middle of the rear axle is + +``SensorData::mounting_position``:: +Defines the sensor’s position and orientation and thereby the origin of the sensor coordinate system. +The mounting position is given in the vehicle coordinate system. \ 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