diff --git a/CMakeLists.txt b/CMakeLists.txt index 8c9626321..6057fddf8 100644 --- a/CMakeLists.txt +++ b/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 diff --git a/doc/images/OSI_Planned_Route.png b/doc/images/OSI_Planned_Route.png new file mode 100644 index 000000000..17e490ced Binary files /dev/null and b/doc/images/OSI_Planned_Route.png differ diff --git a/doc/images/OSI_Route_Segment.png b/doc/images/OSI_Route_Segment.png new file mode 100644 index 000000000..be13b5672 Binary files /dev/null and b/doc/images/OSI_Route_Segment.png differ diff --git a/osi_hostvehicledata.proto b/osi_hostvehicledata.proto index cdd723118..9467b72a8 100644 --- a/osi_hostvehicledata.proto +++ b/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. // diff --git a/osi_route.proto b/osi_route.proto new file mode 100644 index 000000000..b7e519330 --- /dev/null +++ b/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; + } +} diff --git a/setup.py b/setup.py index 36672287e..cad557993 100644 --- a/setup.py +++ b/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",