Package org.opentrafficsim.base.geometry

Class OtsLine2d

java.lang.Object
org.djutils.draw.line.PolyLine2d
org.opentrafficsim.base.geometry.OtsLine2d
All Implemented Interfaces:
Iterable<Point2d>, Locatable, Drawable<Point2d>, Drawable2d, PolyLine<PolyLine2d,Point2d,Ray2d,DirectedPoint2d,LineSegment2d>, Project<Point2d>
Direct Known Subclasses:
DirectionalPolyLine
public class OtsLine2d extends PolyLine2d implements Locatable
This class supports fractional projection, radius, and has locatable methods.

Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See OpenTrafficSim License.

Author:
Alexander Verbraeck, Peter Knoppers, Guus Tamminga, Wouter Schakel

  • Constructor Details

    • OtsLine2d

      public OtsLine2d(Point2d... points)
      Construct a new OtsLine2d.
      Parameters:
      points - the array of points to construct this OtsLine2d from.

    • OtsLine2d

      public OtsLine2d(PolyLine2d line2d)
      Creates a new OtsLine2d based on 2d information.
      Parameters:
      line2d - 2d information.

    • OtsLine2d

      public OtsLine2d(Iterator<Point2d> line2d)
      Creates a new OtsLine2d based on point iterator.
      Parameters:
      line2d - point iterator.

    • OtsLine2d

      public OtsLine2d(List<Point2d> pointList)
      Construct a new OtsLine2d from a List<OtsPoint3d>.
      Parameters:
      pointList - the list of points to construct this OtsLine2d from.

  • Method Details

    • offsetLine

      public final OtsLine2d offsetLine(double offset)
      Construct parallel line.
      Specified by:
      offsetLine in interface PolyLine<PolyLine2d,Point2d,Ray2d,DirectedPoint2d,LineSegment2d>
      Parameters:
      offset - offset distance from the reference line; positive is LEFT, negative is RIGHT
      Returns:
      the line that has the specified offset from the reference line

    • offsetLine

      public final OtsLine2d offsetLine(double offsetAtStart, double offsetAtEnd)
      Create a line at linearly varying offset from this line. The offset may change linearly from its initial value at the start of the reference line to its final offset value at the end of the reference line.
      Specified by:
      offsetLine in interface PolyLine<PolyLine2d,Point2d,Ray2d,DirectedPoint2d,LineSegment2d>
      Parameters:
      offsetAtStart - offset at the start of the reference line (positive value is Left, negative value is Right)
      offsetAtEnd - offset at the end of the reference line (positive value is Left, negative value is Right)
      Returns:
      the OtsLine2d of the line at linearly changing offset of the reference line

    • offsetLine

      public final OtsLine2d offsetLine(double[] relativeFractions, double[] offsets)
      Create a line at linearly varying offset from this line. The offset may change linearly from its initial value at the start of the reference line via a number of intermediate offsets at intermediate positions to its final offset value at the end of the reference line.
      Parameters:
      relativeFractions - positional fractions for which the offsets have to be generated
      offsets - offsets at the relative positions (positive value is Left, negative value is Right)
      Returns:
      the Geometry of the line at linearly changing offset of the reference line

    • concatenate

      public static OtsLine2d concatenate(OtsLine2d... lines)
      Concatenate several OtsLine2d instances.
      Parameters:
      lines - OtsLine2d... one or more OtsLine2d. The last point of the first <strong>must</strong> match the first of the second, etc.
      Returns:
      OtsLine2d

    • concatenate

      public static OtsLine2d concatenate(double toleranceSI, OtsLine2d line1, OtsLine2d line2)
      Concatenate two OtsLine2d instances. This method is separate for efficiency reasons.
      Parameters:
      toleranceSI - the tolerance between the end point of a line and the first point of the next line
      line1 - first line
      line2 - second line
      Returns:
      OtsLine2d

    • concatenate

      public static OtsLine2d concatenate(double toleranceSI, OtsLine2d... lines)
      Concatenate several OtsLine2d instances.
      Parameters:
      toleranceSI - the tolerance between the end point of a line and the first point of the next line
      lines - OtsLine2d... one or more OtsLine2d. The last point of the first <strong>must</strong> match the first of the second, etc.
      Returns:
      OtsLine2d

    • reverse

      public final OtsLine2d reverse()
      Construct a new OtsLine2d with all points of this OtsLine2d in reverse order.
      Specified by:
      reverse in interface PolyLine<PolyLine2d,Point2d,Ray2d,DirectedPoint2d,LineSegment2d>
      Returns:
      the new OtsLine2d

    • extractFractional

      public OtsLine2d extractFractional(double start, double end)
      Construct a new OtsLine2d covering the indicated fraction of this OtsLine2d.
      Specified by:
      extractFractional in interface PolyLine<PolyLine2d,Point2d,Ray2d,DirectedPoint2d,LineSegment2d>
      Parameters:
      start - starting point, valid range [0..end)
      end - ending point, valid range (start..1]
      Returns:
      the new OtsLine2d

    • extract

      public final OtsLine2d extract(Length start, Length end)
      Create a new OtsLine2d that covers a sub-section of this OtsLine2d.
      Parameters:
      start - the length along this OtsLine2d where the sub-section starts, valid range [0..end)
      end - length along this OtsLine2d where the sub-section ends, valid range (start..length (length is the length of this OtsLine2d)
      Returns:
      the selected sub-section

    • extract

      public final OtsLine2d extract(double start, double end)
      Create a new OtsLine2d that covers a sub-section of this OtsLine2d.
      Specified by:
      extract in interface PolyLine<PolyLine2d,Point2d,Ray2d,DirectedPoint2d,LineSegment2d>
      Overrides:
      extract in class PolyLine2d
      Parameters:
      start - length along this OtsLine2d where the sub-section starts, valid range [0..end)
      end - length along this OtsLine2d where the sub-section ends, valid range (start..length (length is the length of this OtsLine2d)
      Returns:
      the selected sub-section

    • getTypedLength

      public final Length getTypedLength()
      Return the length of this OtsLine2d in meters. (Assuming that the coordinates of the points constituting this line are expressed in meters.)
      Returns:
      the length of the line

    • getLocationExtended

      public final DirectedPoint2d getLocationExtended(Length position)
      Get the location at a position on the line, with its direction. Position can be below 0 or more than the line length. In that case, the position will be extrapolated in the direction of the line at its start or end.
      Parameters:
      position - the position on the line for which to calculate the point on, before, of after the line
      Returns:
      a directed point

    • getLocationExtendedSI

      public final DirectedPoint2d getLocationExtendedSI(double positionSI)
      Get the location at a position on the line, with its direction. Position can be below 0 or more than the line length. In that case, the position will be extrapolated in the direction of the line at its start or end.
      Parameters:
      positionSI - the position on the line for which to calculate the point on, before, of after the line, in SI units
      Returns:
      a directed point

    • getLocationPointFraction

      public final DirectedPoint2d getLocationPointFraction(double fraction)
      Get the location at a fraction of the line, with its direction. Fraction should be between 0.0 and 1.0.
      Parameters:
      fraction - the fraction for which to calculate the point on the line
      Returns:
      a directed point

    • getLocationPointFraction

      public final DirectedPoint2d getLocationPointFraction(double fraction, double tolerance)
      Get the location at a fraction of the line, with its direction. Fraction should be between 0.0 and 1.0.
      Parameters:
      fraction - the fraction for which to calculate the point on the line
      tolerance - the delta from 0.0 and 1.0 that will be forgiven
      Returns:
      a directed point

    • getLocationPointFractionExtended

      public final DirectedPoint2d getLocationPointFractionExtended(double fraction)
      Get the location at a fraction of the line (or outside the line), with its direction.
      Parameters:
      fraction - the fraction for which to calculate the point on the line
      Returns:
      a directed point

    • getLocation

      public final DirectedPoint2d getLocation(Length position)
      Get the location at a position on the line, with its direction. Position should be between 0.0 and line length.
      Parameters:
      position - the position on the line for which to calculate the point on the line
      Returns:
      a directed point

    • getLocationSI

      public final DirectedPoint2d getLocationSI(double positionSI)
      Get the location at a position on the line, with its direction. Position should be between 0.0 and line length.
      Parameters:
      positionSI - the position on the line for which to calculate the point on the line
      Returns:
      a directed point

    • truncate

      public final OtsLine2d truncate(double lengthSI)
      Truncate a line at the given length (less than the length of the line, and larger than zero) and return a new line.
      Specified by:
      truncate in interface PolyLine<PolyLine2d,Point2d,Ray2d,DirectedPoint2d,LineSegment2d>
      Overrides:
      truncate in class PolyLine2d
      Parameters:
      lengthSI - the location where to truncate the line
      Returns:
      a new OtsLine2d truncated at the exact position where line.getLength() == lengthSI

    • projectOrthogonalSnap

      public final double projectOrthogonalSnap(double x, double y)
      Returns the fractional position along this line of the orthogonal projection of point (x, y) on this line. If the point is not orthogonal to the closest line segment, the nearest point is selected.
      Parameters:
      x - x-coordinate of point to project
      y - y-coordinate of point to project
      Returns:
      fractional position along this line of the orthogonal projection on this line of a point

    • projectFractional

      public final double projectFractional(Direction start, Direction end, double x, double y, OtsLine2d.FractionalFallback fallback)
      Returns the fractional projection of a point to a line. The projection works by taking slices in space per line segment as shown below. A point is always projected to the nearest segment, but not necessarily to the closest point on that segment. The slices in space are analogous to a Voronoi diagram, but for the line segments instead of points. If fractional projection fails, a fallback projection is returned.

      The point 'A' is projected to point 'B' on the 3rd segment of line 'C-D'. The line from 'A' to 'B' extends towards point 'E', which is the intersection of lines 'E-F' and 'E-G'. Line 'E-F' cuts the first bend of the 3rd segment (at point 'H') in half, while the line 'E-G' cuts the second bend of the 3rd segment (at point 'I') in half. 
                  ____________________________     G                   .
 .         |                            |    .                 .
   .       |  . . . .  helper lines     |    .               .
     .     |  _.._.._  projection line  |   I.             .
       .   |____________________________|  _.'._         .       L
        F.                              _.'  .  '-.    .
          ..                       B _.'     .     '-.
           . .                    _.\        .     .  D
            .  .               _.'   :       .   .
     J       .   .          _.'      \       . .
             ..    .     _.'          :      .                M
            .  .     ..-'             \      .
           .    .    /H.               A     .
          .      .  /    .                   .
        C _________/       .                 .
        .          .         .               .
   K   .            .          .             .
      .              .           .           .
     .                .            .         .           N
    .                  .             .       .
   .                    .              .     .
  .                      .               .   .
 .                        .                . .
                           .                 .E
                            .                  .
                             .                   .
                              .                    .
      Fractional projection may fail in three cases.
      1. Numerical difficulties at slight bend, orthogonal projection returns the correct point.
      2. Fractional projection is possible only to segments that aren't the nearest segment(s).
      3. Fractional projection is possible for no segment.
      In the latter two cases the projection is undefined and the provided fallback is used to provide a point.
      Parameters:
      start - direction in first point
      end - direction in last point
      x - x-coordinate of point to project
      y - y-coordinate of point to project
      fallback - fallback method for when fractional projection fails
      Returns:
      fractional position along this line of the fractional projection on that line of a point

    • getProjectedRadius

      public Length getProjectedRadius(double fraction) throws IllegalArgumentException
      Returns the projected directional radius of the line at a given fraction. Negative values reflect right-hand curvature in the design-line direction. The radius is taken as the minimum of the radii at the vertices before and after the given fraction. The radius at a vertex is calculated as the radius of a circle that is equidistant from both edges connected to the vertex. The circle center is on a line perpendicular to the shortest edge, crossing through the middle of the shortest edge. This method ignores Z components.
      Parameters:
      fraction - fraction along the line, between 0.0 and 1.0 (both inclusive)
      Returns:
      radius; the local radius; or si field set to Double.NaN if line is totally straight
      Throws:
      IllegalArgumentException - fraction out of bounds

    • getProjectedVertexRadius

      public Length getProjectedVertexRadius(int index) throws IndexOutOfBoundsException
      Calculates the directional radius at a vertex. Negative values reflect right-hand curvature in the design-line direction. The radius at a vertex is calculated as the radius of a circle that is equidistant from both edges connected to the vertex. The circle center is on a line perpendicular to the shortest edge, crossing through the middle of the shortest edge. This function ignores Z components.
      Parameters:
      index - index of the vertex in range [1 ... size() - 2]
      Returns:
      radius at the vertex
      Throws:
      IndexOutOfBoundsException - if the index is out of bounds

    • getVertexFraction

      public double getVertexFraction(int index) throws IndexOutOfBoundsException
      Returns the length fraction at the vertex.
      Parameters:
      index - index of vertex [0 ... size() - 1]
      Returns:
      length fraction at the vertex
      Throws:
      IndexOutOfBoundsException - if the index is out of bounds

    • getCentroid

      public Point2d getCentroid()
      Retrieve the centroid of this OtsLine2d.
      Returns:
      the centroid of this OtsLine2d

    • getRelativeBounds

      public Bounds<?,?> getRelativeBounds()
      Specified by:
      getRelativeBounds in interface Locatable

    • getLocation

      public Point2d getLocation()
      Specified by:
      getLocation in interface Locatable