LogicalLaneBoundary: reference LaneBoundary, and add PassingRule

The previous definition was incomplete, since it couldn't handle cases
where two lanes were separated by multiple physical lane boundaries (e.g.
a solid-broken marker). Solve this be referencing 0..N physical lane
boundaries, and adding a PassingRule, so agent models don't have to look
at the physical lane boundaries to determine the lane change rules.

Also clarify some of the descriptions.

Author: tbleher

osi_logicallane.proto

@@ -140,7 +140,19 @@ message ReferenceLine
     }
 }
 
-// Like a LaneBoundary, but with a reference and ST positions.
+// Similar to a LaneBoundary, but with a reference and ST positions.
+//
+// A logical lane boundary describes the boundary between two logical lanes. As
+// such, there will always be exactly one logical lane boundary between two
+// lanes at a given S position. Contrary to that, there can be 0 to N physical
+// lane boundaries (i.e.  type LaneBoundary) between two logical lanes at a
+// given S position.
+//
+// If there are multiple physical lane boundaries at one S position between two
+// lanes (think of a solid-broken marking, which would be described by two
+// LaneBoundary objects, one for the solid lane marking, one for the broken lane
+// marking), then the single LogicalLaneBoundary describing the boundary between
+// two logical lanes should be between the physical boundaries.
 //
 // Notes on design decisions:
 // - The LogicalLaneBoundary has ST coordinates, and is thus a separate type
@@ -164,10 +176,6 @@ message ReferenceLine
 //   This information can be gotten from the physical lane referenced in the
 //   LogicalLane, if needed.
 //
-// TODO To Discuss: It would be entirely possible to add ST coordinates also to
-// LaneBoundary. Then no separate type would be needed. However, it is unclear if
-// the additional overhead is acceptable for sensor models.
-//
 message LogicalLaneBoundary
 {
     // The ID of the lane boundary.
@@ -214,18 +222,58 @@ message LogicalLaneBoundary
     // All points of this LogicalLaneBoundary must have S coordinates in the
     // range [sStart,sEnd].
     //
-    // The reference line should roughly have the same shape as the boundary, so
-    // that S coordinates continually increase along the lane.
+    // The reference line should roughly have the same shape as the boundary (so
+    // roughly parallel to the lane middle), so that S coordinates continually
+    // increase along the boundary.
     //
     // \rules
     // refers_to: ReferenceLine
     // \endrules
     //
     optional Identifier reference_line_id = 3;
 
-    // The classification of the lane boundary.
+    // Reference to the physical lane boundary or boundaries that make up this
+    // logical boundary.
+    //
+    // Rules and notes:
+    // - This list is empty if there are no physical lane boundaries to delimit
+    //   a lane.
+    // - In the common case, this will contain one physical boundary.
+    // - This list contains several lane boundaries if there are several physical
+    //   lane boundaries at one S position (e.g. both a broken and a solid
+    //   line).
+    // - If there are several lane boundaries, they must be listed in increasing
+    //   T order (i.e. from right to left in reference line direction).
+    //   Rationale: this makes it easier to determine e.g. rules on lane
+    //   changes, which depend on the T order of the lanes.
+    // - Whenever physical lane boundaries begin or end, or switch their T
+    //   position (if there are multiple physical lane boundaries), a new
+    //   LogicalLaneBoundary must be created.
+    // - The referenced LaneBoundary objects may be longer than the
+    //   LogicalLaneBoundary which references them, but must never be shorter.
+    //
+    // Example:
+    //      Lane 1
+    // --------a------------------ - - - -c- - - -
+    // - - - -b- - - -
+    //      Lane 2
+    //
+    // This shows the boundary between lane 1 and lane 2. First there is a
+    // solid-broken line (a and b), then there is only a solid line (a), then
+    // there is a broken line (c). There would be three LogicalLaneBoundary
+    // objects between Lane1 and Lane2: the first would reference a and b, the
+    // second would reference only a, and the third would reference c.
+    //
+    // \rules
+    // refers_to: LaneBoundary
+    // \endrules
+    //
+    repeated Identifier physical_boundary_id = 4;
+
+    // The passing rules, insomuch as they can be determined just from road
+    // markings.
     //
-    optional LaneBoundary.Classification classification = 4;
+    optional PassingRule passing_rule = 5;
 
     // Optional external reference to the lane boundary source.
     //
@@ -239,7 +287,7 @@ message LogicalLaneBoundary
     //       from more than one origin source, for example, from a scenario file
     //       and from sensors.
     //
-    repeated ExternalReference source_reference = 5;
+    repeated ExternalReference source_reference = 6;
 
     // A point on the boundary
     //
@@ -259,6 +307,39 @@ message LogicalLaneBoundary
         //
         optional double t_position = 3;
     }
+
+    // Passing rule of the LogicalLaneBoundary.
+    //
+    // This describes how vehicles may move across the LogicalLaneBoundary. The
+    // PassingRule is determined solely based on the road, not on any signs
+    // (i.e. it may be overridden by signs).
+    //
+    enum PassingRule {
+        // Passing rule cannot be determined, e.g. because it depends on the
+        // agent type.
+        //
+        CANNOT_BE_DETERMINED = 0;
+
+        // No passing is allowed (neither from left to right nor from right to
+        // left).
+        //
+        NONE_ALLOWED = 1;
+
+        // Only passing from left to right (in definition direction, so in
+        // decreasing T direction) is allowed.
+        //
+        LEFT_TO_RIGHT = 2;
+
+        // Only passing from right to left (in definition direction, so in
+        // increasing T direction) is allowed.
+        //
+        RIGHT_TO_LEFT = 3;
+
+        // Passing is allowed in both directions (left to right and right to
+        // left).
+        //
+        BOTH_ALLOWD = 4;
+    }
 }
 
 //
@@ -272,6 +353,11 @@ message LogicalLaneBoundary
 // driving path is one LogicalLane, but the whole area is one \c Lane of type
 // \c #TYPE_INTERSECTION.
 //
+// Outside of junctions, logical lanes are constructed such that each point on
+// the road belongs to at least one (typically: exactly one) logical lane. So
+// there are no gaps between logical lanes, and no areas that don't belong to a
+// logical lane.
+//
 // If OSI is generated from OpenDRIVE, then LogicalLanes map directly to
 // OpenDRIVE lanes. However, it is allowed to merge multiple consecutive
 // OpenDRIVE lanes with the same type into one OSI LogicalLane: if an OpenDRIVE
@@ -400,13 +486,31 @@ message LogicalLane
     // have smaller T coordinates.
     // Entries must be ordered: first by start_s, then by end_s.
     //
+    // The XY positions of the polyline generated by the LogicalLaneBoundaries
+    // of adjacent lanes must match up to a small error (5cm).
+    // Typically adjacent lanes will share a LogicalLaneBoundary, but this will
+    // not always be true. Examples: on intersections, it might be hard to generate
+    // data such that lanes that are adjacent for a short length share a
+    // LogicalLaneBoundary for this length; also different LogicalLaneBoundaries
+    // are needed if the lanes have different heights at their boundaries (e.g.
+    // road adjacent to a sidewalk).
+    //
     repeated LaneRelation right_adjacent_lane = 9;
 
     // Lanes that are directly left of this lane, without gap or overlap.
     // "Left" is in definition direction (not driving direction), so left lanes
     // have larger T coordinates.
     // Entries must be ordered: first by start_s, then by end_s.
     //
+    // The XY positions of the polyline generated by the LogicalLaneBoundaries
+    // of adjacent lanes must match up to a small error (5cm).
+    // Typically adjacent lanes will share a LogicalLaneBoundary, but this will
+    // not always be true. Examples: on intersections, it might be hard to generate
+    // data such that lanes that are adjacent for a short length share a
+    // LogicalLaneBoundary for this length; also different LogicalLaneBoundaries
+    // are needed if the lanes have different heights at their boundaries (e.g.
+    // road adjacent to a sidewalk).
+    //
     repeated LaneRelation left_adjacent_lane = 10;
 
     // Lanes that partially or completely overlap this lane. Only overlaps