From 3c5c3a744ebc7b9278b7577c4818d2284f580dff Mon Sep 17 00:00:00 2001 From: Reinhard Biegel Date: Thu, 7 Jul 2022 12:35:33 +0200 Subject: [PATCH 1/9] Adapt ReferenceLine ST definition to avoid tranformation ambiguity and discontinuities Also-by: Weiss David Signed-off-by: Reinhard Biegel --- doc/images/OSI_ReferenceLine1.svg | 444 +++++++++++++++++++----------- osi_referenceline.proto | 100 ++++--- 2 files changed, 336 insertions(+), 208 deletions(-) diff --git a/doc/images/OSI_ReferenceLine1.svg b/doc/images/OSI_ReferenceLine1.svg index dcd7bc7ea..abc3ba1ec 100644 --- a/doc/images/OSI_ReferenceLine1.svg +++ b/doc/images/OSI_ReferenceLine1.svg @@ -2,36 +2,63 @@ + inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)" + sodipodi:docname="s-t-calculation.svg" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns="http://www.w3.org/2000/svg" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:dc="http://purl.org/dc/elements/1.1/"> + + + + + + + id="path4938" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + style="fill:#005621;fill-opacity:1;fill-rule:evenodd;stroke:#005621;stroke-width:1pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,5.92,0.8)" /> + style="fill:#000f88;fill-opacity:1;fill-rule:evenodd;stroke:#000f88;stroke-width:1pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,5.92,0.8)" /> + + + + + + + id="path4598" + d="m -2.5,-1 c 0,2.76 -2.24,5 -5,5 -2.76,0 -5,-2.24 -5,-5 0,-2.76 2.24,-5 5,-5 2.76,0 5,2.24 5,5 z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1pt;stroke-opacity:1" + transform="matrix(0.4,0,0,0.4,2.96,0.4)" /> + inkscape:window-maximized="1" + inkscape:pagecheckerboard="0" + inkscape:snap-global="true" + showguides="false" + fit-margin-top="5" + fit-margin-left="5" + fit-margin-right="5" + fit-margin-bottom="5" + inkscape:snap-text-baseline="false"> + + + + + + + @@ -90,7 +191,6 @@ image/svg+xml - @@ -98,159 +198,177 @@ inkscape:label="Ebene 1" inkscape:groupmode="layer" id="layer1" - transform="translate(4.3233347,-69.350064)"> + transform="translate(-8.60074,-63.836733)"> + - - - + style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" + d="M 132.54847,226.9366 33.44512,70.237989" + id="path3725" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + P2 + id="tspan5178" + x="73.119087" + y="246.23586" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;stroke-width:0.264583">P1 P3 + id="tspan5182" + x="97.160507" + y="209.23372" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;stroke-width:0.264583">P2 P1 - - + id="tspan5204" + x="38.95602" + y="75.694221" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;stroke-width:0.264583">I P4 - + id="tspan5208" + x="67.295532" + y="222.46956" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">P1proj P5 - - - P2proj + - + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:4.23333px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583" + x="37.249924" + y="233.90164" + id="text7745">R0 + R1 + R2 + Reference line + t axis (R1) + t axis (R0) diff --git a/osi_referenceline.proto b/osi_referenceline.proto index 46a31f695..5419809ad 100644 --- a/osi_referenceline.proto +++ b/osi_referenceline.proto @@ -7,9 +7,9 @@ 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. // // Notes on design decisions: @@ -43,10 +43,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 +76,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,31 +87,33 @@ 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. - // - // 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. + // is added. T is the signed 2D distance between the point to describe (P) + // and a projected point (P_proj) on the polyline. 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). 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, resulting in all points on a single T + // axis having the same S coordinate. + // + // \note The ST coordinate system shall be defined in 2D only. When + // referencing any points (including the reference line), their projection + // onto the XY plane shall be considered (but notes on OpenDRIVE compatibility + // below should be considered). // // ## 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 + // 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 nearest point is at the edge between line segments, then the + // 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 @@ -121,23 +123,23 @@ message ReferenceLine // 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. + // \image html OSI_ReferenceLine1.svg "S, T calculation" + // + // This shows a reference line (consisting of three points R0, R1 and R2) + // and two points (P1 and P2) not part of the reference line. + // + // Calculation of ST for P1: + // - Calculate the instersection point I of the T axes of R0 and R1. + // - As P1 lies in the sector defined by these T axes it is considered part + // of the reference line section between R0 and R1. + // - The point P1 is projected onto the line segment [R0, R1] via the + // straight line through I (by calculating the intersection of the line + // segment and the projection axis), resulting in point P1_proj. + // If the T axes are parallel, a simple orthogonal projection is used. + // - The S coordinate of P1 is the S coordinate of P1_proj + // - The T coordinate of P1 is the signed Euclidean distance to P1_proj. + // + // Calculation of P2 follows the same pattern. // // The sampling of the polyline must be chosen such that the error // when converting coordinates is "small enough". The exact needed @@ -158,7 +160,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 +204,14 @@ 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. + // + optional double t_axis_yaw = 3; } } - From fb0e2cfb92acd9f4c71dd09c88ca2cf5191399f9 Mon Sep 17 00:00:00 2001 From: Reinhard Biegel Date: Tue, 19 Jul 2022 22:50:51 +0200 Subject: [PATCH 2/9] Clarify T coordinate definition in case of missing T axes intersection Signed-off-by: Reinhard Biegel --- osi_referenceline.proto | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/osi_referenceline.proto b/osi_referenceline.proto index 5419809ad..961549458 100644 --- a/osi_referenceline.proto +++ b/osi_referenceline.proto @@ -91,8 +91,11 @@ message ReferenceLine // and a projected point (P_proj) on the polyline. 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). The T - // coordinate of the point in question is then defined as + // ReferenceLinePoints (see example and image below for illustration). If + // both T axes of the neighboring ReferenceLinePoint are parallel (so no + // intersection point exists), the resulting T axis direction is equal to + // the T axis of these ReferenceLinePoints. + // 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 @@ -129,13 +132,14 @@ message ReferenceLine // and two points (P1 and P2) not part of the reference line. // // Calculation of ST for P1: - // - Calculate the instersection point I of the T axes of R0 and R1. + // - Calculate the intersection point I of the T axes of R0 and R1. // - As P1 lies in the sector defined by these T axes it is considered part // of the reference line section between R0 and R1. // - The point P1 is projected onto the line segment [R0, R1] via the // straight line through I (by calculating the intersection of the line // segment and the projection axis), resulting in point P1_proj. - // If the T axes are parallel, a simple orthogonal projection is used. + // If the T axes are parallel, projection is applied in the direction of + // these axes. // - The S coordinate of P1 is the S coordinate of P1_proj // - The T coordinate of P1 is the signed Euclidean distance to P1_proj. // From 57c4226aef907afed9945744bac2a822ba0120f5 Mon Sep 17 00:00:00 2001 From: Reinhard Biegel Date: Wed, 20 Jul 2022 10:59:36 +0200 Subject: [PATCH 3/9] Re-add formatting markers Signed-off-by: Reinhard Biegel --- osi_referenceline.proto | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/osi_referenceline.proto b/osi_referenceline.proto index 961549458..0d1d4dad5 100644 --- a/osi_referenceline.proto +++ b/osi_referenceline.proto @@ -128,22 +128,22 @@ message ReferenceLine // Example: // \image html OSI_ReferenceLine1.svg "S, T calculation" // - // This shows a reference line (consisting of three points R0, R1 and R2) - // and two points (P1 and P2) not part of the reference line. - // - // Calculation of ST for P1: - // - Calculate the intersection point I of the T axes of R0 and R1. - // - As P1 lies in the sector defined by these T axes it is considered part - // of the reference line section between R0 and R1. - // - The point P1 is projected onto the line segment [R0, R1] via the - // straight line through I (by calculating the intersection of the line - // segment and the projection axis), resulting in point P1_proj. + // 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 P1 is the S coordinate of P1_proj - // - The T coordinate of P1 is the signed Euclidean distance to P1_proj. + // - 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 P2 follows the same pattern. + // Calculation of \c P2 follows the same pattern. // // The sampling of the polyline must be chosen such that the error // when converting coordinates is "small enough". The exact needed From c3fb715b4bd21511cb34561acf4189c557cc063d Mon Sep 17 00:00:00 2001 From: Reinhard Biegel Date: Fri, 30 Sep 2022 16:04:01 +0200 Subject: [PATCH 4/9] Clarify contraints on T axis Also-by: Weiss David Signed-off-by: Reinhard Biegel --- osi_referenceline.proto | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/osi_referenceline.proto b/osi_referenceline.proto index 0d1d4dad5..d0f907dd2 100644 --- a/osi_referenceline.proto +++ b/osi_referenceline.proto @@ -109,6 +109,18 @@ message ReferenceLine // onto the XY plane shall be considered (but notes on OpenDRIVE compatibility // below should be considered). // + // ## 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. + // // ## Defining angles // // Sometimes an angle to a reference line is needed. This shall be defined From 72778b4accd2722a6bb07021dd425d65f2a69bbb Mon Sep 17 00:00:00 2001 From: Weiss David Date: Wed, 19 Oct 2022 09:58:01 +0200 Subject: [PATCH 5/9] Introduce reference line type enum The type of a reference line will determine how S and T coordinates have to be calculated. Type POLYLINE is equal to the previous ST definition. A new type POLYLINE_WITH_T_AXIS is introduced for improved ST handling. Signed-off-by: Weiss David Signed-off-by: Reinhard Biegel --- osi_referenceline.proto | 40 +++++++++++++++++++++++++++++++++------- 1 file changed, 33 insertions(+), 7 deletions(-) diff --git a/osi_referenceline.proto b/osi_referenceline.proto index d0f907dd2..7fd64513d 100644 --- a/osi_referenceline.proto +++ b/osi_referenceline.proto @@ -31,6 +31,21 @@ message ReferenceLine // optional Identifier id = 1; + optional Type type = 3; + + enum Type + { + // ReferenceLine is a polyline, where the coordinates of points are + // calculated by projection onto the nearest point on the line. + // + POLYLINE = 0; + + // ReferenceLine is a polyline, where the coordinates of points are + // calculated using the t axis definition. + // + POLYLINE_WITH_T_AXIS = 1; + } + // Points comprising the polyline. // // At least 2 points must be given. @@ -88,13 +103,22 @@ message ReferenceLine // // To describe points that are not directly on the polyline, a T coordinate // is added. T is the signed 2D distance between the point to describe (P) - // and a projected point (P_proj) on the polyline. 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). If - // both T axes of the neighboring ReferenceLinePoint are parallel (so no - // intersection point exists), the resulting T axis direction is equal to - // the T axis of these ReferenceLinePoints. + // and a projected point (P_proj) on the polyline. There are two ways of + // defining this point, depending on the ReferenceLine type. + // + // ## 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). + // + // ## T axis definition (Type POLYLINE_WITH_T_AXIS) + // + // 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). If both T axes of the neighboring + // ReferenceLinePoint are parallel (so no intersection point exists), the + // resulting T axis direction is equal to the T axis of these ReferenceLinePoints. // 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. @@ -228,6 +252,8 @@ message ReferenceLine // // 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 POLYLINE_WITH_T_AXIS. + // optional double t_axis_yaw = 3; } } From 6ec28c49cc51dc6d4bb8d515ddcfea4500a21767 Mon Sep 17 00:00:00 2001 From: Reinhard Biegel Date: Wed, 19 Oct 2022 10:08:55 +0200 Subject: [PATCH 6/9] Missing enum member TYPE prefix Signed-off-by: Reinhard Biegel --- osi_referenceline.proto | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/osi_referenceline.proto b/osi_referenceline.proto index 7fd64513d..45e234944 100644 --- a/osi_referenceline.proto +++ b/osi_referenceline.proto @@ -38,12 +38,12 @@ message ReferenceLine // ReferenceLine is a polyline, where the coordinates of points are // calculated by projection onto the nearest point on the line. // - POLYLINE = 0; + TYPE_POLYLINE = 0; // ReferenceLine is a polyline, where the coordinates of points are // calculated using the t axis definition. // - POLYLINE_WITH_T_AXIS = 1; + TYPE_POLYLINE_WITH_T_AXIS = 1; } // Points comprising the polyline. @@ -106,12 +106,12 @@ message ReferenceLine // and a projected point (P_proj) on the polyline. There are two ways of // defining this point, depending on the ReferenceLine type. // - // ## Nearest point (Type 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). // - // ## T axis definition (Type POLYLINE_WITH_T_AXIS) + // ## T axis definition (TYPE_POLYLINE_WITH_T_AXIS) // // The T axis (projecting axis) is the line going through P and the // intersection point (I). I is defined as the intersection of both @@ -252,7 +252,7 @@ message ReferenceLine // // 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 POLYLINE_WITH_T_AXIS. + // \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; } From dd9aa844d21db1a41ed9574374c50111d844e67e Mon Sep 17 00:00:00 2001 From: Reinhard Biegel Date: Wed, 19 Oct 2022 10:18:04 +0200 Subject: [PATCH 7/9] Add ReferenceLine Type documantation Signed-off-by: Reinhard Biegel --- osi_referenceline.proto | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/osi_referenceline.proto b/osi_referenceline.proto index 45e234944..d714ff970 100644 --- a/osi_referenceline.proto +++ b/osi_referenceline.proto @@ -31,8 +31,17 @@ message ReferenceLine // optional Identifier id = 1; + // The type of the reference line. + // optional Type type = 3; + // ReferenceLine types + // + // ReferenceLinePoints might be interpreted diffrently depending on the type + // of the ReferenceLine. + // + // See also: "Adding T coordinates" + // enum Type { // ReferenceLine is a polyline, where the coordinates of points are From 28e0b65fb36aba7eeb2a80f53234552a611be0b3 Mon Sep 17 00:00:00 2001 From: Reinhard Biegel Date: Mon, 7 Nov 2022 17:25:50 +0100 Subject: [PATCH 8/9] New ST calculation method cleanups Also-by: Weiss David Signed-off-by: Reinhard Biegel --- doc/images/OSI_ReferenceLine1.svg | 444 +++++++++++------------------- doc/images/OSI_ReferenceLine2.svg | 374 +++++++++++++++++++++++++ osi_referenceline.proto | 120 +++++--- 3 files changed, 619 insertions(+), 319 deletions(-) create mode 100644 doc/images/OSI_ReferenceLine2.svg diff --git a/doc/images/OSI_ReferenceLine1.svg b/doc/images/OSI_ReferenceLine1.svg index abc3ba1ec..dcd7bc7ea 100644 --- a/doc/images/OSI_ReferenceLine1.svg +++ b/doc/images/OSI_ReferenceLine1.svg @@ -2,63 +2,36 @@ + inkscape:version="0.92.3 (2405546, 2018-03-11)" + sodipodi:docname="OSI_ReferenceLine1.svg"> - - - - - - + id="path820" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> - - - - - - + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(0.8,0,0,0.8,5.92,0.8)" + inkscape:connector-curvature="0" /> + id="path820-8" + d="M 0,0 5,-5 -12.5,0 5,5 Z" + style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#000000;stroke-width:1.00000003pt;stroke-opacity:1" + transform="matrix(-0.8,0,0,-0.8,-10,0)" + inkscape:connector-curvature="0" /> - - - - - - - + inkscape:window-maximized="1" /> @@ -191,6 +90,7 @@ image/svg+xml + @@ -198,177 +98,159 @@ inkscape:label="Ebene 1" inkscape:groupmode="layer" id="layer1" - transform="translate(-8.60074,-63.836733)"> + transform="translate(4.3233347,-69.350064)"> - + + + - + style="fill:none;fill-rule:evenodd;stroke:#ff0000;stroke-width:0.39687496;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.79374994, 0.79374994;stroke-dashoffset:0;stroke-opacity:1" + d="m 98.49004,130.44497 -4.508408,-27.6934" + id="path3290" + inkscape:connector-curvature="0" /> P1 - P2 - I - P1proj - P2proj + id="tspan3660" + x="94.481003" + y="77.926521" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.8791666px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:0.39687496px">P2 R0 + id="tspan3664" + x="86.2771" + y="133.75755" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.8791666px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:0.39687496px">P3 R1 - R2 + id="tspan3668" + x="36.349869" + y="81.133736" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.8791666px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:0.39687496px">P1 + + Reference line + id="tspan3664-1" + x="103.64107" + y="129.40108" + style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:6.8791666px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;stroke-width:0.39687496px">P4 + t axis (R1) - P5 + + + t axis (R0) + id="flowRoot8069" + style="fill:black;stroke:none;stroke-opacity:1;stroke-width:1px;stroke-linejoin:miter;stroke-linecap:butt;fill-opacity:1;font-family:'Courier 10 Pitch';font-style:normal;font-weight:normal;font-size:20px;line-height:125%;letter-spacing:0px;word-spacing:0px;-inkscape-font-specification:'Courier 10 Pitch, Normal';font-stretch:normal;font-variant:normal;text-anchor:start;text-align:start;writing-mode:lr"> + 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 d714ff970..83a47d931 100644 --- a/osi_referenceline.proto +++ b/osi_referenceline.proto @@ -37,7 +37,7 @@ message ReferenceLine // ReferenceLine types // - // ReferenceLinePoints might be interpreted diffrently depending on the type + // ReferenceLinePoints might be interpreted differently depending on the type // of the ReferenceLine. // // See also: "Adding T coordinates" @@ -47,19 +47,25 @@ message ReferenceLine // 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. + // 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 // @@ -113,34 +119,68 @@ message ReferenceLine // To describe points that are not directly on the polyline, a T coordinate // 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. + // 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 + // 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. + // + // Example: + // \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. + // + // - 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. + // // ## 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). If both T axes of the neighboring - // ReferenceLinePoint are parallel (so no intersection point exists), the - // resulting T axis direction is equal to the T axis of these ReferenceLinePoints. - // 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, resulting in all points on a single T - // axis having the same S coordinate. + // image below for illustration). // - // \note The ST coordinate system shall be defined in 2D only. When - // referencing any points (including the reference line), their projection - // onto the XY plane shall be considered (but notes on OpenDRIVE compatibility - // below should be considered). + // 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 // @@ -153,25 +193,12 @@ message ReferenceLine // - 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. - // - // ## 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 a ST coordinate, but not necessarily a unique ST - // coordinate. + // - 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_ReferenceLine1.svg "S, T calculation" + // \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. @@ -190,6 +217,22 @@ message ReferenceLine // // 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 @@ -261,7 +304,8 @@ message ReferenceLine // // 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. + // \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; } From 79e3994ca4230bf8dd0637ee07093f0c141c00d8 Mon Sep 17 00:00:00 2001 From: Reinhard Biegel Date: Wed, 9 Nov 2022 10:19:46 +0100 Subject: [PATCH 9/9] Note on ST coordinates to avoid confusion with other standards Also-by: Weiss David Signed-off-by: Reinhard Biegel --- osi_referenceline.proto | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/osi_referenceline.proto b/osi_referenceline.proto index 83a47d931..b6b3bc5e4 100644 --- a/osi_referenceline.proto +++ b/osi_referenceline.proto @@ -12,6 +12,11 @@ package osi3; // 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,