Merge pull request #452 from OpenSimulationInterface/feature/tp/had-output

Feature/tp/had output

Author: pmai

.gitignore

@@ -40,3 +40,6 @@ githooks/pre-commit
 # PyCharm specific files
 .idea
 .vscode/settings.json
+
+# Local build tool output
+local_build_tools/*.html

CMakeLists.txt

@@ -77,6 +77,7 @@ set(OSI_PROTO_FILES
     osi_environment.proto
     osi_groundtruth.proto
     osi_hostvehicledata.proto
+    osi_motionrequest.proto
     osi_trafficsign.proto
     osi_trafficlight.proto
     osi_trafficupdate.proto

doc/_config.adoc

@@ -2,14 +2,11 @@
 // This file contains AsciiDoc attributes that shall be used in every AsciiDoc file.
 // NOTE: Its content is only applied for Asciidoctor!
 // If the same attribute is defined in the antora.yml (without @), the antora.yml definition takes precedence for Antora.
-
 ifndef::root-path[:root-path: ./]
-
 :partials-path: {root-path}../_additional_content
 :asciidoc-resources: ../../../asciidoc-resources
 :appendix-caption: Annex
 :page-feedbackurl: https://github.com/OpenSimulationInterface/open-simulation-interface/issues/new
-
 // ifndef::use-antora-rules,include-only-once[]
 ifndef::include-only-once[]
 :GLO_VAR_STA_ASAM_OpenCRG: ASAM OpenCRG
@@ -27,13 +24,14 @@ ifndef::include-only-once[]
 // Replace PLACEHOLDER with the name of your standard, e.g. OpenDRIVE
 :THIS_STANDARD: {GLO_VAR_STA_ASAM_OSI}
 :asam-terminology: https://code.asam.net/common/asam-terminology/-/raw/main/terms_and_definitions_opendrive.adoc
-:imagesdir: {root-path}/images
+:imagesdir: {root-path}images
 :include-only-once: true
 :topicdir: topics
 :reusedir: reuse
 :toclevels: 3
 :xrefstyle: full
-:images_open_simulation_interface: {imagesdir}
+:images_open_simulation_interface: ../images
+:data-uri:
 // :images_osi-sensor-model-packaging: ./osi-sensor-model-packaging/doc/images
 :doc_open_simulation_interface: ../../open-simulation-interface/doc/
 :doc_osi-sensor-model-packaging: ../../osi-sensor-model-packaging/doc/
@@ -43,13 +41,10 @@ ifndef::include-only-once[]
 // Please note that this variable has to used in all image includes. Includes here have to use "image::./images..."
 // :images_osi_sensor_model_packaging: ./osi-sensor-model-packaging/doc/images  // example
 :imagesoutdir: ./images/generated_images
-
 endif::[]
-
 ifndef::use-antora-rules[]
 include::{asciidoc-resources}/preamble.adoc[]
 endif::[]
-
 ifdef::env-gitlab[]
 :relfilesuffix: .adoc
 endif::[]

doc/architecture/architecture_overview.adoc

@@ -34,7 +34,7 @@ image::{images_open_simulation_interface}/osi-traffic-participant-advanced.png[1
 
 The `HostVehicleData` interface describes the measured internal states of a traffic participant.
 OSI currently provides only limited support for data structures that describe measured internal states of traffic participants.
-Actuator intentions are currently not covered by OSI and must be handled using a different data description format.
+One example would be the `MotionRequest` interface that can be used to communicate the results of the behavior planning to the dynamic model.
 
 NOTE: OSI uses singular instead of plural for `repeated` field names.
 

doc/architecture/motion_request.adoc

@@ -0,0 +1,8 @@
+ifndef::include-only-once[]
+:root-path: ../
+include::{root-path}_config.adoc[]
+endif::[]
+= Motion Request
+
+`MotionRequest` messages are traffic participant internal messages.
+They function as a interface between a motion/behavior planning model and a dynamics model including, for example, controllers and vehicle kinematics.

doc/architecture/traffic_participant.adoc

@@ -22,8 +22,8 @@ The following figure shows the interface of a traffic participant.
 .Interface of a traffic participant
 image::{images_open_simulation_interface}/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 models may use other OSI interfaces, for example, the `SensorData` and `MotionRequest` message, internally.
+The following figure shows a more advanced use case for traffic participants, that can, for example, be used to model an autonomous vehicle.
 
 [#fig-traffic-participant-other-osi-interfaces]
 .Traffic participant using other OSI interfaces internally

doc/images/osi-traffic-participant-advanced.png

@@ -25,6 +25,8 @@ include::./architecture/sensor_data.adoc[leveloffset=+3]
 
 include::./architecture/traffic_command.adoc[leveloffset=+3]
 
+include::./architecture/motion_request.adoc[leveloffset=+3]
+
 include::./architecture/traffic_update.adoc[leveloffset=+3]
 
 === Model types

doc/images/osi-traffic-participant-principle.png

@@ -28,8 +28,7 @@ The following figure shows a traffic participant with separately modeled behavio
 image::{images_open_simulation_interface}/osi-traffic-participant-use-case-2.png[1100]
 
 OSI currently provides only limited support for data structures that describe measured internal states of the traffic participant.
-OSI does not currently cover actuator intentions.
-These must be handled with a different data description format.
+An example for a traffic participant internal interface is the `MotionRequest` message that can be used to communicate planned behaviors from a behavior planning model to a dynamics model including, for example motion controllers and vehicle dynamics.
 
 The following figure shows a more complex traffic participant.
 
@@ -41,7 +40,6 @@ This use case will probably be relevant for modeling the ego vehicle, which incl
 The traffic participant includes an arbitrary number of sensor models.
 The sensor models consume sensor view and produce sensor data.
 The AD function consumes sensor data and produces input for the dynamics model.
-OSI currently does not support data flow to dynamics models.
 The loop to the environment simulation is closed via traffic update.
 
 The following figure shows a cooperative use case with both an AD function and a human driver.
@@ -54,4 +52,4 @@ It is possible to model a traffic participant with an AD function in the loop, b
 This type of cooperative use case is, for example, relevant to studies on human-machine interaction.
 In this example, a virtual on-screen representation of the scenario, or mock-up, is added after the AD function.
 The driver-in-the-loop interacts with the dynamics model via this mock-up.
-OSI's limitations regarding dynamics-model input apply in this example as well.
+OSI currently provides only limited interfaces for data flow between the driver and the dynamics model. 

doc/images/osi-traffic-participant-use-case-1.png

@@ -5,4 +5,4 @@ services:
     image: asciidoctor/docker-asciidoctor
     volumes:
       - ../:/documents
-    entrypoint: asciidoctor --failure-level WARN -r asciidoctor-kroki -a mathjax -r asciidoctor-bibtex --trace content/index.adoc -o local_build_tools/HTML_content_local_build.html
+    entrypoint: asciidoctor -r asciidoctor-kroki -a mathjax --trace doc/open-simulation-interface_user_guide.adoc -o local_build_tools/HTML_content_local_build.html

doc/images/osi-traffic-participant-use-case-2.png

@@ -592,7 +592,8 @@ message StatePoint
     // Position in the global coordinate system.
     //
     // \note Remark: The definition of the reference point follows the
-    // specification of the \c BaseMoving message.
+    // specification of the \c BaseMoving message, if not specified otherwise
+    // in the message the StatePoint is used in.
     //
     optional Vector3d position = 2;
 

doc/images/osi-traffic-participant-use-case-3.png

@@ -0,0 +1,117 @@
+syntax = "proto2";
+
+option optimize_for = SPEED;
+
+import "osi_common.proto";
+import "osi_version.proto";
+
+package osi3;
+
+//
+// \brief This message is intended as an interface between a
+// motion-planning function and the actuator management.
+// The motion-planning function can thereby be a representation of a 
+// highly-automated driving function, a human driving behavior model, etc.
+//
+// The motion-planning function can either send a desired future trajectory or a desired
+// future state. The message can be defined by an additional variable.
+//
+// \note The coordinate system is defined as right-handed.
+// All coordinates and orientations are relative to the global coordinate system.
+// The reference point of the vehicle is the middle of the rear axis.
+// Units are m for positions, m/s for velocities, and m/s^2 for accelerations.
+//
+message MotionRequest
+{
+    // The interface version used by the sender (simulation environment).
+    //
+    optional InterfaceVersion version = 1;
+
+    // The data timestamp of the simulation environment.
+    // A reference to \c Timestamp message.
+    //
+    optional Timestamp timestamp = 2;
+
+    // Define the type that is used to specify the motion request.
+    // This must be set. Additionally, the field corresponding to the specified 
+    // option must be set.
+    //
+    optional MotionRequestType motion_request_type = 3;
+
+    // Defines a desired state.
+    // If the output option is set to DESIRED_STATE, this field must be set.
+    //
+    optional DesiredState desired_state = 4;
+
+    // Defines a desired trajectory.
+    // If the output option is set to DESIRED_TRAJECTORY, this field must be set.
+    //
+    optional DesiredTrajectory desired_trajectory = 5;
+
+    // Define different options for function output.
+    // Each option corresponds to a field in the message.
+    //
+    enum MotionRequestType
+    {
+        // Desired state calculated by the function.
+        //
+        MOTION_REQUEST_TYPE_DESIRED_STATE = 0;
+
+        // Desired trajectory calculated by the function.
+        //
+        MOTION_REQUEST_TYPE_TRAJECTORY = 1;
+    }
+
+    // \brief The desired state is calculated by the function as a result of
+    // the motion planning stack.
+    //
+    // The actuator management is supposed to reach the desired state at the
+    // specified time.
+    //
+    message DesiredState
+    {
+        // A reference to \c Timestamp message.
+        //
+        optional Timestamp timestamp = 1;
+
+        // Intended position to be reached in in x-, y-, and z-direction.
+        //
+        optional Vector3d position = 2;
+
+        // Intended orientation to be reached containing yaw, pitch and roll angle.
+        //
+        optional Orientation3d orientation = 3;
+
+        // Intended velocity to be reached in in x-, y-, and z-direction.
+        //
+        // Unit: m/s
+        //
+        optional Vector3d velocity = 4;
+
+        // Intended acceleration to be reached in x-, y-, and z-direction.
+        //
+        // Unit: m/s^2
+        //
+        optional Vector3d acceleration = 5;
+    }
+
+    // \brief Defined trajectory desired by the function.
+    //
+    // This trajectory is the result of the trajectory planning step in the function.
+    // The task of the actuator management is to follow this trajectory as closely as possible.
+    // The timestamps inside the trajectory must be defined in global simulation time.
+    //
+    // \note The trajectory is kept as a separate message for future extensions.
+    //
+    message DesiredTrajectory
+    {
+        // The trajectory consists of intended position (x, y, and z) and
+        // orientation (yaw, pitch and roll) of intended state to be reached.
+        // A reference to \c StatePoint message.
+        //
+        // \note The position within the trajectory point references to the 
+        // middle point of the rear axis.
+        //
+        repeated StatePoint trajectory_point = 1;
+    }
+}

doc/open-simulation-interface_user_guide.adoc

@@ -449,8 +449,8 @@ message MovingObject
     // realistic simulation of traffic participants that are not under test.
     // This information should not be made available to the stack under test.
     //
-    // \note Moving objects are not required to stick to this trajectory, it is
-    // indicative, and equivalent to the output of a perception + prediction
+    // \note Moving objects are not required to stick to this trajectory. It is
+    // indicative and equivalent to the output of a perception and prediction
     // system.
     //
     repeated StatePoint future_trajectory = 8;

doc/usecases/modeling_traffic_participant.adoc

@@ -60,6 +60,7 @@ def find_protoc():
         'osi_lane.proto',
         'osi_logicaldetectiondata.proto',
         'osi_logicallane.proto',
+        'osi_motionrequest.proto',
         'osi_object.proto',
         'osi_occupant.proto',
         'osi_referenceline.proto',