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-2026 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)
      Constructor from points.
      Parameters:
      points - array of points

    • OtsLine2d

      public OtsLine2d(PolyLine2d line2d)
      Constructor based on 2d line.
      Parameters:
      line2d - 2d line

    • OtsLine2d

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

    • OtsLine2d

      public OtsLine2d(List<Point2d> pointList)
      Constructor based on a List<Point2d>.
      Parameters:
      pointList - list of points

  • Method Details

    • offsetLine

      public 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 this reference line

    • offsetLine

      public 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:
      line with linear offset

    • offsetLine

      public 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:
      line with profiled offset

    • 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:
      concatenated line

    • 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:
      concatenated line

    • 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 must match the first of the second, etc.
      Returns:
      concatenated line

    • reverse

      public OtsLine2d reverse()
      Returns a reversed instance of this line.
      Specified by:
      reverse in interface PolyLine<PolyLine2d,Point2d,Ray2d,DirectedPoint2d,LineSegment2d>
      Returns:
      reversed line

    • extractFractional

      public OtsLine2d extractFractional(double start, double end)
      Create a new line covering the indicated fraction of this line.
      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:
      extracted line

    • extract

      public OtsLine2d extract(org.djunits.value.vdouble.scalar.Length start, org.djunits.value.vdouble.scalar.Length end)
      Create a new line that covers a sub-section of this line.
      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 line)
      Returns:
      extracted line

    • extract

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

    • getTypedLength

      public org.djunits.value.vdouble.scalar.Length getTypedLength()
      Return the length of this line.
      Returns:
      length of the line

    • getLocationExtended

      public DirectedPoint2d getLocationExtended(org.djunits.value.vdouble.scalar.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

    • getLocation

      public DirectedPoint2d getLocation(org.djunits.value.vdouble.scalar.Length position)
      Get the location at a position on the line, with its direction. Position should be in [0..length].
      Parameters:
      position - the position on the line for which to calculate the point on the line
      Returns:
      a directed point

    • truncate

      public OtsLine2d truncate(double lengthSI)
      Truncate line at the given length in range (0..length).
      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:
      truncated line

    • projectOrthogonalSnapAt

      public double projectOrthogonalSnapAt(double x, double y)
      Orthogonally project a point onto this polyline. If the perpendicular foot on the closest segment falls outside that segment, this method snaps to the nearest vertex of that segment. The result is returned as a fraction along the entire polyline. The returned fraction is clamped to [0..1].
      Parameters:
      x - x-coordinate of the point to project
      y - y-coordinate of the point to project
      Returns:
      fraction along the line in [0..1]

    • projectOrthogonalSnapAt

      public double projectOrthogonalSnapAt(double x, double y, boolean clampToDomain)
      Orthogonally project a point onto this polyline. If the perpendicular foot on the closest segment falls outside that segment, this method snaps to the nearest vertex of that segment. The result is returned as a fraction along the entire polyline.

      If clampToDomain is true, the returned fraction is clamped to [0..1]. If false, the fraction may be negative (before the start of the line) or larger than 1 (beyond the end of the line) when the closest point is the first or last vertex, respectively.

      Parameters:
      x - x-coordinate of the point to project
      y - y-coordinate of the point to project
      clampToDomain - whether to clamp the resulting fraction to [0..1]
      Returns:
      fraction along the line; in [0..1] when clampToDomain is true; otherwise possibly <0 or >1

    • projectFractionalAt

      public double projectFractionalAt(org.djunits.value.vdouble.scalar.Direction start, org.djunits.value.vdouble.scalar.Direction end, double x, double y, FractionalProjectionHelper.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

    • radiusAtFraction

      public Optional<org.djunits.value.vdouble.scalar.Length> radiusAtFraction(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; empty if there is no radius as two segments have the same direction
      Throws:
      IllegalArgumentException - fraction out of bounds

    • radiusAtVertex

      public Optional<org.djunits.value.vdouble.scalar.Length> radiusAtVertex(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, empty if there is no radius as two segments have the same direction
      Throws:
      IndexOutOfBoundsException - if the index is out of bounds

    • vertexFraction

      public double vertexFraction(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

    • getRelativeBounds

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

    • getLocation

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