diff --git a/.gitignore b/.gitignore index ea4c2867a..26cc62ce5 100644 --- a/.gitignore +++ b/.gitignore @@ -40,3 +40,6 @@ githooks/pre-commit # PyCharm specific files .idea .vscode/settings.json + +# Local build tool output +local_build_tools/*.html diff --git a/CMakeLists.txt b/CMakeLists.txt index de03a73bd..7f37803ff 100644 --- a/CMakeLists.txt +++ b/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 diff --git a/doc/_config.adoc b/doc/_config.adoc index 513261341..89bae37f6 100644 --- a/doc/_config.adoc +++ b/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::[] diff --git a/doc/architecture/architecture_overview.adoc b/doc/architecture/architecture_overview.adoc index 498427b40..4fadeb8eb 100644 --- a/doc/architecture/architecture_overview.adoc +++ b/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. diff --git a/doc/architecture/motion_request.adoc b/doc/architecture/motion_request.adoc new file mode 100644 index 000000000..e24a43608 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/architecture/traffic_participant.adoc b/doc/architecture/traffic_participant.adoc index 3418cc11f..a1088d29a 100644 --- a/doc/architecture/traffic_participant.adoc +++ b/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 diff --git a/doc/images/osi-traffic-participant-advanced.png b/doc/images/osi-traffic-participant-advanced.png index 451e4b32b..eac33e24c 100644 Binary files a/doc/images/osi-traffic-participant-advanced.png 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 index 45e886360..232563511 100644 Binary files a/doc/images/osi-traffic-participant-principle.png and b/doc/images/osi-traffic-participant-principle.png differ diff --git a/doc/images/osi-traffic-participant-use-case-1.png b/doc/images/osi-traffic-participant-use-case-1.png index f79fb5cd2..6dfc05dcc 100644 Binary files a/doc/images/osi-traffic-participant-use-case-1.png and b/doc/images/osi-traffic-participant-use-case-1.png differ diff --git a/doc/images/osi-traffic-participant-use-case-2.png b/doc/images/osi-traffic-participant-use-case-2.png index 121f04d57..c7a6dd280 100644 Binary files a/doc/images/osi-traffic-participant-use-case-2.png and b/doc/images/osi-traffic-participant-use-case-2.png differ diff --git a/doc/images/osi-traffic-participant-use-case-3.png b/doc/images/osi-traffic-participant-use-case-3.png index 53eb19a66..bc7659282 100644 Binary files a/doc/images/osi-traffic-participant-use-case-3.png and b/doc/images/osi-traffic-participant-use-case-3.png differ diff --git a/doc/open-simulation-interface_user_guide.adoc b/doc/open-simulation-interface_user_guide.adoc index 8a6673db0..4c4583ad0 100644 --- a/doc/open-simulation-interface_user_guide.adoc +++ b/doc/open-simulation-interface_user_guide.adoc @@ -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 diff --git a/doc/usecases/modeling_traffic_participant.adoc b/doc/usecases/modeling_traffic_participant.adoc index 4754a85d3..66fdbaf6b 100644 --- a/doc/usecases/modeling_traffic_participant.adoc +++ b/doc/usecases/modeling_traffic_participant.adoc @@ -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. \ No newline at end of file +OSI currently provides only limited interfaces for data flow between the driver and the dynamics model. \ No newline at end of file diff --git a/local_build_tools/compose.yml b/local_build_tools/compose.yml index a37849c18..120d2b504 100644 --- a/local_build_tools/compose.yml +++ b/local_build_tools/compose.yml @@ -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 \ No newline at end of file + entrypoint: asciidoctor -r asciidoctor-kroki -a mathjax --trace doc/open-simulation-interface_user_guide.adoc -o local_build_tools/HTML_content_local_build.html \ No newline at end of file diff --git a/osi_common.proto b/osi_common.proto index 3243a37a7..ec84ed522 100644 --- a/osi_common.proto +++ b/osi_common.proto @@ -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; diff --git a/osi_motionrequest.proto b/osi_motionrequest.proto new file mode 100644 index 000000000..82560c8e6 --- /dev/null +++ b/osi_motionrequest.proto @@ -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; + } +} diff --git a/osi_object.proto b/osi_object.proto index 2cacb0d49..d49e86a09 100644 --- a/osi_object.proto +++ b/osi_object.proto @@ -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; diff --git a/setup.py b/setup.py index 44ba7ba10..22b179acc 100644 --- a/setup.py +++ b/setup.py @@ -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',