Merge pull request #718 from OpenSimulationInterface/feature/pp/visualization_interface_PR2

Introduce StreamingUpdate Interface

Author: pmai

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})

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 future evolution of OSI will therefore use field numbers equal to or greater than 10000.

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.

doc/images/osi-streaming-principle.PNG

@@ -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]

doc/open-simulation-interface_user_guide.adoc

@@ -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;
+}

osi_streamingupdate.proto

@@ -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',