diff --git a/doc/images/OSI_ReferenceLine2.svg b/doc/images/OSI_ReferenceLine2.svg new file mode 100644 index 000000000..abc3ba1ec --- /dev/null +++ b/doc/images/OSI_ReferenceLine2.svg @@ -0,0 +1,374 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + P1 + P2 + I + P1proj + P2proj + R0 + R1 + R2 + Reference line + t axis (R1) + t axis (R0) + + diff --git a/osi_referenceline.proto b/osi_referenceline.proto index 46a31f695..b6b3bc5e4 100644 --- a/osi_referenceline.proto +++ b/osi_referenceline.proto @@ -7,11 +7,16 @@ import "osi_common.proto"; package osi3; // -// \brief A reference line for defining a non-euclidean ST coordinate system +// \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 +// A reference line is a 3D polyline, used for generating a non-Euclidean // ST coordinate system. // +// \note This ST coordinate system is specific to OSI and not to be confused with +// similar definitions in other standards like OpenDRIVE or OpenSCENARIO 1.x. +// Nevertheless the goal of this definition is to approximate the source +// coordinates (e.g. OpenDRIVE). +// // 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, @@ -31,11 +36,41 @@ message ReferenceLine // optional Identifier id = 1; + // The type of the reference line. + // + optional Type type = 3; + + // ReferenceLine types + // + // ReferenceLinePoints might be interpreted differently depending on the type + // of the ReferenceLine. + // + // See also: "Adding T coordinates" + // + enum Type + { + // ReferenceLine is a polyline, where the coordinates of points are + // calculated by projection onto the nearest point on the line. + // + // \attention DEPRECATED: Due to the shortcomings documenten below, this + // type will be removed in 4.0.0. + // + TYPE_POLYLINE = 0; + + // ReferenceLine is a polyline, where the coordinates of points are + // calculated using the T axis definition. + // + // \note If this type is used, ReferenceLinePoint::t_axis_yaw must be set. + // + TYPE_POLYLINE_WITH_T_AXIS = 1; + } + // Points comprising the polyline. // - // At least 2 points must be given. + // At least two points must be given. // The polyline is defined as the lines between consecutive points. - // Each point has an S coordinate. + // Each point has an S coordinate. Other attributes might be set, depending + // on the type of the polyline (see Type). // // ## Rules on the S position // @@ -43,10 +78,10 @@ message ReferenceLine // - 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 + // 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 + // - 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 @@ -76,9 +111,9 @@ message ReferenceLine // 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 + // sStart,\c sEnd] is defined by the Euclidean 2D distance from the start // or end point, respectively. So if sStart = 15, and a point - // is on the line extended from the start position, with a 2D euclidean + // 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. @@ -87,14 +122,22 @@ message ReferenceLine // ## 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. hypot(A.X-B.X, - // A.Y-B.Y), 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. + // is added. T is the signed 2D distance between the point to describe (P) + // and a projected point (P_proj) on the polyline. There are two ways of + // defining this point, depending on the ReferenceLine::Type (see below). + // + // The T coordinate of the point in question is then defined as + // hypot(P.X-P_proj.X,P.Y-P_proj.Y). The projected point P_proj + // 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 + // projected point on the polyline. + // + // ## Nearest point (TYPE_POLYLINE) + // + // The projection point is the nearest point on the polyline (this point might + // either be on a line segment or at an edge between two line segments). // // Notes: // - The "nearest point on the polyline" is determined in 3D (even if the @@ -104,24 +147,8 @@ message ReferenceLine // - 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 + // \image html OSI_ReferenceLine1.svg "S, T calculation using nearest point" // // This shows a reference line (consisting of three points), and five points // not on the reference line. @@ -139,6 +166,78 @@ message ReferenceLine // - Finally, \c P5 shows how the reference line is extended infinitely for // points that are "outside" the reference line. // + // ## T axis definition (TYPE_POLYLINE_WITH_T_AXIS) + // + // The T axes of the two ReferenceLinePoints of each ReferenceLine segment + // define a sector (or strip if parallel) of the plane. A point is associated + // with the segment if it lies within this sector. For points being + // associated with multiple segments, the actual segment to consider is + // determined by the shortest 3D Euclidean distance between the point and the + // segments in question. + // + // The T axis (projecting axis) is the line going through P and the + // intersection point (I). I is defined as the intersection of both + // T axes of two consecutive ReferenceLinePoints (see example and + // image below for illustration). + // + // Special cases: + // 1. If both T axes of the consecutive ReferenceLinePoint are parallel (so + // no intersection point exists), the resulting T axis orientation is equal + // to the T axis of these ReferenceLinePoints. + // 2. For the extended lines outside the defined range the projection axis is + // parallel to the T axis of the respective end point. + // + // ## Rules on the T axis + // + // For the T axis at a specific ReferenceLinePoint the following rules apply: + // - The T axis shall be close to the angle bisector (to the left in S + // direction) of the neighboring ReferenceLine segments. + // - Small deviations from the angle bisector are allowed (e.g. to represent + // the T axis of OpenDRIVE, which is perpendicular to the OpenDRIVE + // reference line). + // - The T axis must be located inside the sectors spanned by rotating the + // normal of one neighboring ReferenceLine segment into the normal of the + // other ReferenceLine segment on the shortest way. + // - The T axis in the first and the last point of a ReferenceLine has to be + // perpendicular to the first and last segment of the ReferenceLine, + // respectively. + // + // Example: + // \image html OSI_ReferenceLine2.svg "S, T calculation using T axis" + // + // This shows a reference line (consisting of three points \c R0, \c R1 and + // \c R2) and two points (\c P1 and \c P2) not part of the reference line. + // + // Calculation of ST for \c P1: + // - Calculate the intersection point \c I of the T axes of \c R0 and \c R1. + // - As \c P1 lies in the sector defined by these T axes it is considered part + // of the reference line section between \c R0 and \c R1. + // - The point \c P1 is projected onto the line segment [\c R0, \c R1] via the + // straight line through \c I (by calculating the intersection of the line + // segment and the projection axis), resulting in point \c P1_proj. + // If the T axes are parallel, projection is applied in the direction of + // these axes. + // - The S coordinate of \c P1 is the S coordinate of \c P1_proj + // - The T coordinate of \c P1 is the signed Euclidean distance to \c P1_proj. + // + // Calculation of \c P2 follows the same pattern. + // + // ## Defining angles + // + // Sometimes an angle to a reference line is needed. This shall be defined + // as follows: + // First the projected point on the polyline is determined, as described + // below. 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 projected 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 an ST coordinate, but not necessarily a unique ST + // coordinate. + // // 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 @@ -158,7 +257,7 @@ message ReferenceLine // - 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 + // Euclidean distances, compared to having the reference line at one side // of a curvy road. // // ## Various notes @@ -202,6 +301,17 @@ message ReferenceLine // S position on the reference line // optional double s_position = 2; + + // Yaw angle of the T axis in the world coordinate system + // + // When converting from formats like OpenDRIVE, the yaw angle is equal to + // the angle of the normal to the reference line in the sampled point. + // + // Also see image "S, T coordinates" at #poly_line for reference. + // + // \note This field is only set if the type of the reference line is + // TYPE_POLYLINE_WITH_T_AXIS. + // + optional double t_axis_yaw = 3; } } -