diff --git a/CMakeLists.txt b/CMakeLists.txt index 8cb07187e..dc99bbadb 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -94,6 +94,7 @@ set(OSI_PROTO_FILES osi_sensorviewconfiguration.proto osi_sensorspecific.proto osi_sensorview.proto + osi_streamingupdate.proto ) protobuf_generate_cpp(PROTO_SRCS PROTO_HEADERS ${OSI_PROTO_FILES}) diff --git a/doc/architecture/architecture_overview.adoc b/doc/architecture/architecture_overview.adoc index 4fadeb8eb..6ef5b76ee 100644 --- a/doc/architecture/architecture_overview.adoc +++ b/doc/architecture/architecture_overview.adoc @@ -36,6 +36,12 @@ The `HostVehicleData` interface describes the measured internal states of a traf OSI currently provides only limited support for data structures that describe measured internal states of traffic participants. One example would be the `MotionRequest` interface that can be used to communicate the results of the behavior planning to the dynamic model. +The `StreamingUpdate` interface enables partial ground truth updates to modules that favor performance, especially latency, over data completeness/consistency (e.g. visualization applications) or that do not require complete data in the first place (e.g. logging applications). + +[#fig-interface-streaming] +.Interface for partial ground truth updates +image::{images_open_simulation_interface}/osi-streaming-principle.png[1100] + NOTE: OSI uses singular instead of plural for `repeated` field names. NOTE: All fields in an interface are set to `optional`. @@ -48,4 +54,4 @@ However, this does not mean that it is optional to fill the field. 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. NOTE: All field numbers equal to or greater than 10000 are available for user-specific extensions via custom fields. -No future evolution of OSI will therefore use field numbers equal to or greater than 10000. \ No newline at end of file +No future evolution of OSI will therefore use field numbers equal to or greater than 10000. diff --git a/doc/architecture/streaming_update.adoc b/doc/architecture/streaming_update.adoc new file mode 100644 index 000000000..1bf661948 --- /dev/null +++ b/doc/architecture/streaming_update.adoc @@ -0,0 +1,10 @@ +ifndef::include-only-once[] +:root-path: ../ +include::{root-path}_config.adoc[] +endif::[] += Streaming update + +The `StreamingUpdate` message provides an interface to transmit a subset of ground truth and/or vehicle internal data. +This interface mainly addresses applications with low latency requirements and no need for highly consistent and complete data, e.g. visualization applications. +Static and/or non-relevant objects can be omitted as required for the specific use case. +Note that the receiver of partial updates can only rely on the most up-to-date information at the corresponding timestamp. E.g. omitting objects does not indicate static behaviour but it may be sufficient for the use case to update certain objects at a later point in time. \ No newline at end of file diff --git a/doc/images/osi-streaming-principle.PNG b/doc/images/osi-streaming-principle.PNG new file mode 100644 index 000000000..4ed874b57 Binary files /dev/null and b/doc/images/osi-streaming-principle.PNG differ diff --git a/doc/open-simulation-interface_user_guide.adoc b/doc/open-simulation-interface_user_guide.adoc index 90b288a6f..b9864441e 100644 --- a/doc/open-simulation-interface_user_guide.adoc +++ b/doc/open-simulation-interface_user_guide.adoc @@ -29,6 +29,8 @@ include::./architecture/motion_request.adoc[leveloffset=+3] include::./architecture/traffic_update.adoc[leveloffset=+3] +include::./architecture/streaming_update.adoc[leveloffset=+3] + === Model types include::./architecture/environmental_effect_model.adoc[leveloffset=+3] diff --git a/osi_streamingupdate.proto b/osi_streamingupdate.proto new file mode 100644 index 000000000..b1ad1121a --- /dev/null +++ b/osi_streamingupdate.proto @@ -0,0 +1,80 @@ +syntax = "proto2"; + +option optimize_for = SPEED; + +import "osi_version.proto"; +import "osi_common.proto"; +import "osi_environment.proto"; +import "osi_object.proto"; +import "osi_trafficsign.proto"; +import "osi_trafficlight.proto"; +import "osi_hostvehicledata.proto"; + +package osi3; + +// +// \brief The streaming update interface enables simulation entities to send +// partial updates to other modules that favor performance (especially latency) +// over data completeness/consistency (e.g. visualization applications). +// +// Static and/or non-relevant objects can be omitted as required for the +// specific use case. Adding an object's unique id to the repeated field \c +// obsolete_id indicates that it will no longer be updated from then on. +// +// \note The receiver of partial streaming update messages can only rely on the +// most up-to-date information at the corresponding timestamp. E.g. omitting +// objects does not indicate static behaviour but it may be sufficient for the +// use case to update certain objects at a later point in time. +// +message StreamingUpdate +{ + // The interface version used by the sender. + // + optional InterfaceVersion version = 1; + + // The data timestamp where the information of contained objects is calculated. + // + // 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; + + // The list of stationary objects (excluding traffic signs and traffic + // lights). + // + repeated StationaryObject stationary_object_update = 3; + + // The list of moving objects. + // + repeated MovingObject moving_object_update = 4; + + // The list of traffic signs. + // + repeated TrafficSign traffic_sign_update = 5; + + // The list of traffic lights. + // + repeated TrafficLight traffic_light_update = 6; + + // Conditions of the environment. + // + optional EnvironmentalConditions environmental_conditions_update = 7; + + // Host vehicle data. + // + // Host vehicle data is data that the host vehicle knows about itself, + // e.g. from location sensors, internal sensors and ECU bus data, etc., + // that is made available to sensors as input. + // + // The ID inside this message allows an association to moving object data. + // + repeated HostVehicleData host_vehicle_data_update = 8; + + // Entities that will no longer be updated, because they are considered + // obsolete by the sender. + // + // \note IDs are globally unique. + // + repeated Identifier obsolete_id = 9; +} diff --git a/setup.py b/setup.py index 22b179acc..435207aeb 100644 --- a/setup.py +++ b/setup.py @@ -69,6 +69,7 @@ def find_protoc(): 'osi_sensorspecific.proto', 'osi_sensorview.proto', 'osi_sensorviewconfiguration.proto', + 'osi_streamingupdate.proto', 'osi_trafficcommand.proto', 'osi_trafficcommandupdate.proto', 'osi_trafficlight.proto',