feat: New OSI message osi_route

CMakeLists.txt

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

osi_hostvehicledata.proto

@@ -4,6 +4,7 @@ option optimize_for = SPEED;
 
 import "osi_version.proto";
 import "osi_common.proto";
+import "osi_route.proto";
 
 package osi3;
 
@@ -91,6 +92,10 @@ message HostVehicleData
     //
     optional VehicleMotion vehicle_motion = 13;
 
+    // Currently planned route of the vehicle
+    //
+    optional Route route = 14;
+
     //
     // \brief Base parameters and overall states of the vehicle.
     //

osi_route.proto

@@ -0,0 +1,134 @@
+syntax = "proto2";
+
+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.
+    //
+    // \note The LogicalLaneSegment allows that start_s > end_s.
+    // If start_s < end_s, then the traffic agent should traverse the
+    // segment in the logical lane's reference line definition direction.
+    // If end_s > start_s, then the traffic agent should traverse the
+    // segment in the opposite of the logical lane's reference line
+    // definition direction.
+    //
+    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
+    // logical lanes of the road network.
+    //
+    // Each time there is a successor-predecessor relation between the logical
+    // lanes along the route (i.e. a logical lane ends, and is continued by another
+    // logical lane, e.g. at a junction border), a new RouteSegment starts. The
+    // RouteSegment then lists the logical lane segments that can be used to
+    // travel through this space of the road.
+    //
+    // Together, the listed logical lane segments should form a continuous area,
+    // where the traffic agent can move freely. These will mostly be parallel
+    // lanes, though lanes may overlap (e.g. if one lane splits into two on a
+    // junction). In general, the logical lane segments in a RouteSegment will
+    // have the same length, though there are exceptions (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 parallel 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 continuous
+        // area.
+        //
+        repeated LogicalLaneSegment lane_segment = 1;
+    }
+}

setup.py

@@ -73,6 +73,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",