Geometry utility to deal with offsets, widths and lane connections

[WJSchakel]

The current geometry implementations have several issues:

• Geometry logic is scattered over various classes, using various local thresholds and number of points for a line.
• CrossSectionElement forces the first and last line segment in the direction of the node. This is done with a point at 1/3rd along the way to the next shape point, or at most at a distance equal to the element width. This creates very inconsistent shapes between elements on one link.
• Offset artefacts (see issue #70).
• When translating a network format to OTS that has lane geometry defined, this needs to be translated to widths and offsets as CrossSectionElement cannot be specified with geometry directly.
• CrossSectionElement offsets are used to fix what is in essence a shift of the link design line, purely because it is then desired to let a link design line start at the from node and end in the end node. This occurs especially at merges/diverges where link design lines that are e.g. on the right-hand side of a cross-section will not meet up otherwise. This can create complicated and strange situations, e.g. an arc link where all lanes shift from from negative to positive offset. Aa a result, none of the lanes is an arc, and the lane contours will not connect neatly to the previous or next link.
• The way in which links are defined (arc, straight, clothoid) is not consistent. Only for Bezier is the node direction actually used. Only for arcs is offset used.

To overcome these issues the following principles are designed:

1. Geometry utils (one in ots-core and one in ots-road) will be the central places that define geometry logic.
2. All CrossSectionElement will simply receive a design line and shape. No internal (and obscure logic) will change this.
3. Nodes have a direction, that links and lanes need to obey.
4. Node direction is not strict for the links and lanes; the first and last line segments may deviate in their direction within bounds. (E.g. a circle arc may divide a 90° corner in 90 segments, causing the first and last segments to deviate from the node direction by 1°.)
5. Both design lines and edge lines need to start/stop on the line through the node, perpendicular to the node direction.
6. These start and end points need to at their offset on the perpendicular line. Note that this may cause slight narrowing of the first or last line segment.
7. Link design lines are somewhere within the width of a road cross section, although this is not strict.
8. Offset at link level is used to connect lanes appropriately where links merge or diverge. (For macroscopic purposes, this offset may be ignored.)
9. Offset of the entire cross-section on a link is used to connect successive links using road layouts with different locations of the link design line.
10. Offset of individual lanes and lines is used if this changes over the length of the link.

Rule 4 allows that shapes can be true to their design, and no awkward and complicating additional segments are required at the start and end. Rules 5 and 6 make sure that lanes from connected links connect neatly. The bounds of angle deviation in rule 4 are such that when the first/last point is placed on the perpendicular line through the node, at the correct offset, a clean line still results. The angle deviation may not be such that the first point in the inside of the bend at the node is placed beyond the second point due to an offset, e.g. taper lanes.

[WJSchakel]

Quite a lot of changes have been made in a first big iteration to tackle the above issues.

• CrossSectionElement, and its subclasses Lane, Stripe and Shoulder, now gets an OtsLine3d and OtsShape as center line and contour. These are no longer determined internally.
• Hence, no additional points are added to the center line regarding node direction.
• Also methods fixLateralOffset() and fixTightInnerCurve() have been removed.
• Many constructors, with different offset and width combinations, have been removed.
• In ots-core class ContinuousLine, and its subclasses ContinuousArc, ContinuousBezierCubic, ContinuousClothoid, ContinuousStraight and ContinuousPolyLine have been added. These classes define a design line continuously, and can be used to return a flattened OtsLine3d of itself, or an offset line. All these lines obey the start and end directions.
• Bezier now has a method cubicControlPoints() that returns 4 control points using the regular logic of a shape factor and whether to use weighted points. This is used in ContinuousBezierCubic. Method Bn has been made package-private for the same reason.
• Logic to determine a clothoid based on two directed points has been moved from Clothoid to ContinuousClothoid.
• All demos, unit tests and xml files have been updated accordingly.

[WJSchakel]

Added class FractionalLengthData which stores 1-dimensional data along the length of a curve. This class is used for variable offsets, and also delivered by LaneGeometryUtil to deliver center/left/right offsets. The class can return interpolated values.

[WJSchakel]

Methods offset and flatten with input 'number of segments' or 'max deviation and angle' have been removed from ContinuousLine and all subclasses.

A new interface Flattener has been introduced. It is input in two new methods in ContinuousLine and all subclasses:

• flatten(Flattener)
• flattenOffset(FractionalLengthData, Flattener)

Subclasses of ContinuousLine can implement these methods either using, or ignoring, the flattener. For example, ContinuousStraight is flattened to just two points. ContinuousBezierCubic implements the offset procedure of before, splitting the Bezier in C-shaped Bezier segments. These segments are then used to provide information to the flattener.

A Flattener expects input in the form of a FlattableLine. This has methods Point2d get(double fraction) and double getDirection(double fraction), for use in the various flattening procedures. Each ContinuousLine subclass that uses the flattener, must present itself (or an offset of itself) as a FlattableLine. This occurs using light-weight anonymous classes that can find points and directions, accounting for a possible variable offset. In most cases this is straightforward, especially if the relevant information has been pre-calculated (e.g. for a Clothoid).

There are 4 standard implementations of Flattener, defined as classes as they require specification of input:

• Flattener.NumSegments based on a number of segments.
• Flattener.MaxDeviation based on a maximum spatial deviation. This implements the procedure in Bezier in djutils.
• Flattener.MaxAngle based on a maximum angle between the continuous line, and a resulting polyline segment.
• Flattener.MaxDeviationAndAngle which combines the two above in a single procedure.