feat: New OSI message osi_route

The new message allows sending route information to a traffic
agent in the simulation. The route information can then be used by the
agent to traverse the road network.

Signed-off-by: Fabian Pfeuffer <[email protected]>

Author: Fabian Pfeuffer

CMakeLists.txt

@@ -83,6 +83,7 @@ set(OSI_PROTO_FILES
     osi_trafficcommand.proto
     osi_referenceline.proto
     osi_roadmarking.proto
+    osi_route.proto
     osi_lane.proto
     osi_logicallane.proto
     osi_featuredata.proto

doc/images/OSI_Planned_Route.png

@@ -4,6 +4,7 @@ option optimize_for = SPEED;
 
 import "osi_version.proto";
 import "osi_common.proto";
+import "osi_route.proto";
 
 package osi3;
 
@@ -87,6 +88,10 @@ message HostVehicleData
     //
     repeated VehicleAutomatedDrivingFunction vehicle_automated_driving_function = 12;
 
+    // Currently planned route of the vehicle
+    //
+    optional Route route = 13;
+
     //
     // \brief Base parameters and overall states of the vehicle.
     //

doc/images/OSI_Route_Segment.png

@@ -0,0 +1,123 @@
+syntax = "proto3";
+
+option optimize_for = SPEED;
+
+import "osi_common.proto";
+
+package osi3;
+
+//
+// \brief A route in the road network
+//
+// A route is an e.g. planned or suggested path for an agent to travel from one
+// location to another within the road network. It is composed of a list of route
+// segments, which form a continuous path through the road network and should be
+// traversed in the order they are listed.
+// The route allows the simulation environment to provide agents with high level
+// path information, similar to that of a map or a navigation system, without the
+// need for the agent model to perform complex path planning on its own. This
+// allows for an efficient control of the agent's general direction, while
+// simultaneously giving it enough freedom on how to traverse the path.
+//
+// ## Example
+//
+// The example below shows the \link Route route\endlink of a vehicle.
+//
+// \image html OSI_Planned_Route.png "Route" width=850px
+//
+// The route is composed of three \link RouteSegment route segments\endlink RS1-3,
+// each indicated by a yellow outline. Two of the route segments
+// (RS2 and RS3) only contain a single \link LogicalLaneSegment logical lane segment\endlink
+// (highlighted in blue), while RS1 is composed of three
+// logical lane segments (green, blue and red).
+//
+message Route
+{
+
+    // The unique id of the route.
+    //
+    // \note This field is mandatory.
+    //
+    // \note This id must be unique within all route messages exchanged with
+    // one traffic participant.
+    //
+    optional Identifier route_id = 1;
+
+    // Route segments that form the route of an agent.
+    //
+    // Consecutive segments should be connected without gaps, meaning that the
+    // two of them should form a continuous area.
+    //
+    repeated RouteSegment route_segment = 2;
+
+    //
+    // \brief A segment of a logical lane.
+    //
+    message LogicalLaneSegment
+    {
+        // The ID of the logical lane this segment belongs to.
+        //
+        // \rules
+        // refers_to: LogicalLane
+        // \endrules
+        //
+        optional Identifier logical_lane_id = 1;
+
+        // S position on the logical lane where the segment starts.
+        //
+        optional double start_s = 2;
+
+        // S position on the logical lane where the segment ends.
+        //
+        optional double end_s = 3;
+    }
+
+    //
+    // \brief A segment of a route.
+    //
+    // A route segment describes a segment of a traffic agent's route through the
+    // road network. The route segment is composed of a list of logical lanes
+    // segments that indicate the agent which logical lanes it should use in a
+    // given interval, so that it will eventually reach its destination.
+    // In general, only lanes should be listed that are parallel to each
+    // other, though some may have different lengths (e.g. if a lane widening
+    // occurs, the newly appearing lane will have a shorter length).
+    //
+    // Typically a route segment will be either
+    // - a set of lanes between two junctions, or
+    // - parallel lanes on an intersection with the same driving direction
+    //
+    // ## Example
+    //
+    // Consider the \link RouteSegment route segment\endlink between two intersections,
+    // shown in the image below.
+    //
+    // \image html OSI_Route_Segment.png "RouteSegment" width=850px
+    //
+    // In the example, a single route segment RS with three
+    // \link LogicalLaneSegment logical lane segments\endlink LL1, LL2 and LL3 is
+    // shown. The segments are indicated by the green, blue and red highlighted areas,
+    // one for each underlying logical lane The starting
+    // s-position of each segment is indicated by the yellow dotted line and the s- prefix
+    // (note that the start of LL2 lies further to the left, outside of the image),
+    // while the ending s-position of all segments is shown by the yellow dotted line e-RS.
+    //
+    // As it can be seen in the example, all logical lane segments are parallel,
+    // but two of them are opening at a later position, so their starting
+    // s-positions will be different.
+    //
+    message RouteSegment
+    {
+
+        // Logical lane segments that form a route segment.
+        //
+        // The logical lane segments of a route segment should be connected without
+        // gaps, meaning that, together, the lane segments should form a
+        // continous area.
+        //
+        repeated LogicalLaneSegment lane_segment = 1;
+
+    }
+
+
+}

osi_hostvehicledata.proto

@@ -64,6 +64,7 @@ def find_protoc():
         'osi_occupant.proto',
         'osi_referenceline.proto',
         'osi_roadmarking.proto',
+        'osi_route.proto',
         'osi_sensordata.proto',
         'osi_sensorspecific.proto',
         'osi_sensorview.proto',