osi_referenceline.proto

syntax = "proto2";

option optimize_for = SPEED;

import "osi_common.proto";

package osi3;

//
// \brief A reference line for defining a non-euclidean ST coordinate system
//
// A reference line is a 3D polyline, used for generating a non-euclidean
// ST coordinate system.
//
// Notes on design decisions:
// - This is a polyline, and not some more complex curve. The advantage of a
//   polyline is that it is very simple to generate from various map formats,
//   and it is also easy to handle. The downside is that a polyline has no
//   direct curvature, and even the angle is not continuous (only C0 smooth).
//   In the author's experience, the benefits of a polyline outweigh the costs.
//
message ReferenceLine
{
    // The ID of the reference line.
    //
    // \note Note ID is global unique.
    //
    // \rules
    // is_globally_unique
    // \endrules
    //
    optional Identifier id = 1;

    // Points comprising the polyline.
    //
    // At least 2 points must be given.
    // The polyline is defined as the lines between consecutive points.
    // Each point has an S coordinate.
    //
    // ## Rules on the S position
    //
    // There are a few requirements on the S position:
    // - Later points in the list must have strictly larger S coordinates than
    //   earlier points.
    // - For consecutive points, the S difference between them  must be at
    //   least as large as the 2D euclidean distance between the points (2D
    //   distance == euclidean distance between the points taking only X and Y
    //   into account).
    // - The S distance between two points may be larger than the 2D euclidean
    //   distance, but should be not much larger. It is allowed to be larger if
    //   the underlying reference line (e.g. in an OpenDRIVE map) is a curve,
    //   and thus the sampled reference line has a smaller length than the original
    //   curve.
    //
    // Together, these rules allow directly putting OpenDRIVE S coordinates
    // into an OSI ReferenceLine.
    //
    // If the reference line approximates a curve (e.g. a clothoid in
    // OpenDRIVE), the points must be chosen in a way that the lateral distance
    // to the ideal line does not exceed 5cm. As shown in the following image:
    //
    // \image html line_approximation_error.svg "Approximation error"
    // Approximation error green line.
    //
    // Between two ReferenceLinePoints, both the world coordinate and the S
    // coordinate is interpolated linearly. So each S value uniquely describes
    // a point on the polyline.
    //
    // ## Extending the coordinate system infinitely
    //
    // For the purpose of this discussion, let's call the S position of the
    // first point \c sStart, and the S position of the last point \c sEnd.
    //
    // For some purposes, S positions outside the normally defined range (i.e.
    // outside [\c sStart,\c sEnd]) need to be defined. For this purpose, the
    // first line of the polyline is infinitely extended in negative S
    // direction.  Similarly, the last line of the polyline is infinitely
    // extended beyond the last point. The S value of points outside [\c
    // sStart,\c sEnd] is defined by the euclidean 2D distance from the start
    // or end point, respectively.  So if <code>sStart = 15</code>, and a point
    // is on the line extended from the start position, with a 2D euclidean
    // distance of 10 from the first point, then it has an S position of 5.
    //
    // A point is "before" the reference line, if its s coordinate is < \c sStart.
    // A point is "after" the reference line, if its s coordinate is > \c sEnd.
    //
    // ## Adding T coordinates
    //
    // To describe points that are not directly on the polyline, a T coordinate
    // is added. T is the signed 2D distance (i.e. <code>hypot(A.X-B.X,
    // A.Y-B.Y)</code>, if A and B are the two points) between the point to
    // describe and the nearest point on the polyline (this point might either
    // be on a line segment or at an edge between two line segments). The
    // distance is positive if the point is left of the polyline (in definition
    // direction), negative if it is right of it.
    // The S position of such a point outside the reference line is the same as
    // the S value of the nearest point on the polyline.
    //
    // Notes:
    // - The "nearest point on the polyline" is determined in 3D (even if the
    //   resulting T value is only the 2D distance), in order to choose the
    //   correct point for 3D curves (think reference lines for roads in parking
    //   decks).
    // - If there are several "nearest points", the one with the smallest S
    //   coordinate on the polyline is chosen.
    //
    // ## Defining angles
    //
    // Sometimes an angle to a reference line is needed. This shall be defined
    // as follows:
    // First the nearest point on the polyline is determined, as described
    // above. If this point is on a line segment, then the angle is calculated
    // relative to the line segment on which the reference point lays.
    // If the nearest point is at the edge between line segments, then the
    // angle of the following line shall be chosen.
    //
    // ## Converting between world coordinates and ST coordinates
    //
    // The above rules define an ST coordinate system across the whole XY plane.
    // Every XY position has a ST coordinate, but not necessarily a unique ST
    // coordinate.
    //
    // Example:
    // \image html OSI_ReferenceLine1.svg
    //
    // This shows a reference line (consisting of three points), and five points
    // not on the reference line.
    //
    // - For \c P1, the situation is clear, since there is exactly one nearest
    //   point on the polyline. The resulting ST coordinate uniquely maps back
    //   to \c P1.
    // - \c P2 has multiple points "nearest points" on the polyline.
    //   As can be seen here, two  ST coordinates map to \c P2 (red and grey
    //   dotted line).  Following the rules above, the one with the smallest S
    //   value is chosen (the red dotted line).
    // - \c P3 has a unique "nearest point" on the polyline. However, multiple
    //   points map to the same ST coordinate as that of \c P3, e.g. \c P4
    //   (drawn in grey).
    // - Finally, \c P5 shows how the reference line is extended infinitely for
    //   points that are "outside" the reference line.
    //
    // The sampling of the polyline must be chosen such that the error
    // when converting coordinates is "small enough". The exact needed
    // precision is defined for each user, where the reference line is
    // referenced.
    //
    // ## Creating reference lines
    //
    // When OSI is generated from OpenDRIVE, typically the reference lines will
    // be taken directly from the road reference lines in OpenDRIVE, and
    // sampled according to the accuracy requirements outlined above.
    //
    // Other map formats may not have reference lines, so they will have to be
    // synthesized by the tool generating OSI data. A few guidelines on this
    // process:
    //
    // - The reference line should follow the road
    // - It is preferable to have the reference line in the center of the road
    //   (e.g. on a highway, it should be in the middle between the two driving
    //   directions). Rationale: this makes S differences better approximate
    //   euclidean distances, compared to having the reference line at one side
    //   of a curvy road.
    //
    // ## Various notes
    //
    // Notes on OpenDRIVE compatibility:
    // Ideally, one would want the polyline to be fully compatible with
    // OpenDRIVE, so that calculations done for OpenDRIVE directly match those
    // in OSI. There are a few difficulties with this:
    // - The T coordinate is nearly the same as for OpenDRIVE, but
    //   unfortunately not perfectly. In OpenDRIVE, if the road is tilted using
    //   superElevation, then the t coordinate system is tilted along, so the T
    //   coordinate is no longer calculated in the XY plane (as proposed for
    //   OSI). It doesn't seem feasable to implement the same tilting for OSI,
    //   so simulation tools will have to consider superElevation and convert
    //   the T coordinate accordingly: <code>t_OSI = t_OpenDRIVE *
    //   cos(alpha)</code>, where alpha is the superelevation angle.
    // - The angle will not be perfectly the same, due to the use of line
    //   segments in OSI, and curves in OpenDRIVE. In the authors opinion, the
    //   difference will be negligible if the #poly_line is suitably sampled.
    //
    // Notes on design decisions:
    // - The S coordinate is included directly, both for OpenDRIVE
    //   compatibility, and to speed up calculations.
    // - The rules on S coordinates (e.g. the calculation in 2D space) are
    //   there to ensure OpenDRIVE compatibility.
    // - The rules on T coordinates are there to ensure OpenDRIVE compatibility
    //   for lanes without superelevation, and to make it easier to convert
    //   between OSI and OpenDRIVE in case superelevation is present.
    //
    repeated ReferenceLinePoint poly_line = 2;

    //
    // \brief A point on the reference line
    //
    message ReferenceLinePoint
    {
        // A world position
        //
        optional Vector3d world_position = 1;

        // S position on the reference line
        //
        optional double s_position = 2;
    }
}