Package org.djutils.draw.line

Interface PolyLine<L extends PolyLine<L,P,R,D,LS>,P extends Point<P>,R extends Ray<R,D,P>,D extends Directed<D>,LS extends LineSegment<P,D>>

Type Parameters:
L - the PolyLine type (2d or 3d)
P - The matching Point type (2d or 3d)
D - The matching Directed type (2d or 3d)
R - The matching Ray type (2d or 3d)
LS - The matching LineSegment type (2d or 3d)
All Superinterfaces:
Drawable<P>, Iterable<P>, Project<P>, Serializable
All Known Implementing Classes:
Polygon2d, Polygon3d, PolyLine2d, PolyLine3d
public interface PolyLine<L extends PolyLine<L,P,R,D,LS>,P extends Point<P>,R extends Ray<R,D,P>,D extends Directed<D>,LS extends LineSegment<P,D>> extends Drawable<P>, Project<P>
PolyLine is the interface for PolyLine2d and PolyLine3d implementations.

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

Author:
Alexander Verbraeck, Peter Knoppers, Wouter Schakel

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    PolyLine.TransitionFunction
    Interface for transition function.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    DEFAULT_CIRCLE_PRECISION
    Default precision of approximation of arcs in the offsetLine method.
    static final double
    DEFAULT_OFFSET_FILTER_RATIO
    By default, noise in the reference line of the offsetLineMethod less than offset / offsetFilterRatio is filtered except when the resulting value exceeds offsetMaximumFilterValue.
    static final double
    DEFAULT_OFFSET_MAXIMUM_FILTER_VALUE
    By default, noise in the reference line of the offsetLineMethod greater than this value is never filtered.
    static final double
    DEFAULT_OFFSET_MINIMUM_FILTER_VALUE
    By default, noise in the reference line of the offsetLine method less than this value is always filtered.
    static final double
    DEFAULT_OFFSET_PRECISION
    By default, the offsetLineMethod uses this offset precision.
    static final double
    NO_FILTER
    Use this value for epsilon to disable all filtering.

  • Method Summary

    Modifier and Type
    Method
    Description
    P
    closestPointOnPolyLine(P point)
    Project a Point on this PolyLine.
    L
    extract(double start, double end)
    Create a new PolyLine that covers a sub-section of this PolyLine.
    default L
    extractFractional(double start, double end)
    Construct a new PolyLine covering the indicated fraction of this PolyLine.
    default double[][]
    filterNearDuplicates(double epsilon, double[]... coordinates)
    Filter adjacent points that are (near) duplicates.
    default int
    find(double pos)
    Binary search for a point index on this PolyLine that is at, or the the nearest one before a given position.
    P
    get(int index)
    Return one of the points of this line.
    default P
    getFirst()
    Return the first point of this PolyLine.
    default P
    getLast()
    Return the last point of this PolyLine.
    double
    getLength()
    Return the length of this line.
    D
    getLocation(double position)
    Get the location at a position on the line, with its direction.
    D
    getLocationExtended(double position)
    Get the location at a position on the line, with its direction.
    default D
    getLocationFraction(double fraction)
    Get the location at a fraction of the line, with its direction.
    default D
    getLocationFraction(double fraction, double tolerance)
    Get the location at a fraction of the line, with its direction.
    default D
    getLocationFractionExtended(double fraction)
    Get the location at a fraction of the line (or outside the line), with its direction.
    LS
    getSegment(int index)
    Extract one LineSegment of this PolyLine, or Polygon.
    double
    getX(int index)
    Return the x-coordinate of a point of this PolyLine.
    double
    getY(int index)
    Return the y-coordinate of a point of this PolyLine.
    L
    instantiate(double epsilon, List<P> pointList)
    Constructor that can be accessed as a method (used to implement default methods in this interface).
    default L
    instantiate(List<P> pointList)
    Constructor that can be accessed as a method (used to implement default methods in this interface).
    double
    lengthAtIndex(int index)
    Access the internal lengthIndexedLine.
    L
    noiseFilteredLine(double noiseLevel)
    Construct a new PolyLine that is equal to this line except for segments that are shorter than the noiseLevel.
    default L
    offsetLine(double offset)
    Construct an offset PolyLine.
    L
    offsetLine(double[] relativeFractions, double[] offsets, double offsetMinimumFilterValue)
    Create a line at linearly varying offset from this line.
    default L
    offsetLine(double offsetAtStart, double offsetAtEnd)
    Construct an offset line.
    L
    offsetLine(double offset, double circlePrecision, double offsetMinimumFilterValue, double offsetMaximumFilterValue, double offsetFilterRatio, double minimumOffset)
    Construct an offset line.
    L
    offsetLine(double offsetAtStart, double offsetAtEnd, double circlePrecision, double offsetMinimumFilterValue, double offsetMaximumFilterValue, double offsetFilterRatio, double minimumOffset)
    Construct an offset line.
    default L
    reverse()
    Construct a new PolyLine with all points of this PolyLine in reverse order.
    L
    transitionLine(L endLine, PolyLine.TransitionFunction transition)
    Make a transition line from this PolyLine to another PolyLine using a user specified function.
    L
    truncate(double position)
    Truncate this PolyLine at the given length (less than the length of the line, and larger than zero) and return a new line.

    Methods inherited from interface org.djutils.draw.Drawable

    getDimensions, getPointList, size, toString, toString, toString, toString

    Methods inherited from interface java.lang.Iterable

    forEach, iterator, spliterator

    Methods inherited from interface org.djutils.draw.line.Project

    projectOrthogonal, projectOrthogonalExtended, projectOrthogonalFractional, projectOrthogonalFractionalExtended

  • Field Details

    • NO_FILTER

      static final double NO_FILTER
      Use this value for epsilon to disable all filtering.
      See Also:

    • DEFAULT_CIRCLE_PRECISION

      static final double DEFAULT_CIRCLE_PRECISION
      Default precision of approximation of arcs in the offsetLine method.
      See Also:

    • DEFAULT_OFFSET_MINIMUM_FILTER_VALUE

      static final double DEFAULT_OFFSET_MINIMUM_FILTER_VALUE
      By default, noise in the reference line of the offsetLine method less than this value is always filtered.
      See Also:

    • DEFAULT_OFFSET_MAXIMUM_FILTER_VALUE

      static final double DEFAULT_OFFSET_MAXIMUM_FILTER_VALUE
      By default, noise in the reference line of the offsetLineMethod greater than this value is never filtered.
      See Also:

    • DEFAULT_OFFSET_FILTER_RATIO

      static final double DEFAULT_OFFSET_FILTER_RATIO
      By default, noise in the reference line of the offsetLineMethod less than offset / offsetFilterRatio is filtered except when the resulting value exceeds offsetMaximumFilterValue.
      See Also:

    • DEFAULT_OFFSET_PRECISION

      static final double DEFAULT_OFFSET_PRECISION
      By default, the offsetLineMethod uses this offset precision.
      See Also:

  • Method Details

    • instantiate

      default L instantiate(List<P> pointList)
      Constructor that can be accessed as a method (used to implement default methods in this interface).
      Parameters:
      pointList - a list of points
      Returns:
      the new PolyLine
      Throws:
      NullPointerException - when pointList is null
      IllegalArgumentException - when pointList has fewer than two points or contains successive duplicate points

    • instantiate

      L instantiate(double epsilon, List<P> pointList)
      Constructor that can be accessed as a method (used to implement default methods in this interface).
      Parameters:
      epsilon - minimum distance between points to be considered different (these will not be filtered out)
      pointList - a list of points
      Returns:
      the new PolyLine
      Throws:
      NullPointerException - when pointList is null
      IllegalArgumentException - when pointList has fewer than two points or contains successive duplicate points

    • noiseFilteredLine

      L noiseFilteredLine(double noiseLevel)
      Construct a new PolyLine that is equal to this line except for segments that are shorter than the noiseLevel. The result is guaranteed to start with the first point of this line and end with the last point of this line.
      Parameters:
      noiseLevel - the minimum segment length that is not removed
      Returns:
      the filtered line

    • getLength

      double getLength()
      Return the length of this line. This is not the number of points; it is the sum of the lengths of the segments.
      Returns:
      the length of this line

    • get

      P get(int index)
      Return one of the points of this line.
      Parameters:
      index - the index of the requested point
      Returns:
      the point at the specified index
      Throws:
      IndexOutOfBoundsException - when index < 0, or index ≥ size()

    • getX

      double getX(int index)
      Return the x-coordinate of a point of this PolyLine.
      Parameters:
      index - the index of the requested x-coordinate
      Returns:
      the x-coordinate of the requested point of this PolyLine
      Throws:
      IndexOutOfBoundsException - when index < 0, or index ≥ size()

    • getY

      double getY(int index)
      Return the y-coordinate of a point of this PolyLine.
      Parameters:
      index - the index of the requested y-coordinate
      Returns:
      the y-coordinate of the requested point of this PolyLine
      Throws:
      IndexOutOfBoundsException - when index < 0, or index ≥ size()

    • getFirst

      default P getFirst()
      Return the first point of this PolyLine.
      Returns:
      the first point of this line

    • getLast

      default P getLast()
      Return the last point of this PolyLine.
      Returns:
      the last point of this line

    • getSegment

      LS getSegment(int index)
      Extract one LineSegment of this PolyLine, or Polygon.
      Parameters:
      index - the rank number of the segment; must be in range 0..Size() - 2 for PolyLine, or 0.. Size() - 1 for Polygon.
      Returns:
      the LineSegment that connects point index to point index + 1
      Throws:
      IndexOutOfBoundsException - when index < 0, or index ≥ size() - 1 (in case of a PolyLine, or index ≥ size() in case of a Polygon

    • lengthAtIndex

      double lengthAtIndex(int index)
      Access the internal lengthIndexedLine. Return the cumulative length up to point index of this line
      Parameters:
      index - the index
      Returns:
      the cumulative length of this line up to point index
      Throws:
      IndexOutOfBoundsException - when index < 0, or index ≥ size()

    • reverse

      default L reverse()
      Construct a new PolyLine with all points of this PolyLine in reverse order.
      Returns:
      the new PolyLine

    • extractFractional

      default L extractFractional(double start, double end)
      Construct a new PolyLine covering the indicated fraction of this PolyLine.
      Parameters:
      start - fractional starting position, valid range [0..end)
      end - fractional ending position, valid range (start..1]
      Returns:
      a new PolyLine covering the selected sub-section
      Throws:
      IllegalArgumentException - when start ≥ end, or start < 0, or end > 1

    • extract

      L extract(double start, double end)
      Create a new PolyLine that covers a sub-section of this PolyLine.
      Parameters:
      start - length along this PolyLine where the sub-section starts, valid range [0..end)
      end - length along this PolyLine where the sub-section ends, valid range (start..length (length is the length of this PolyLine)
      Returns:
      a new PolyLine covering the selected sub-section
      Throws:
      IllegalArgumentException - when start ≥ end, or start < 0, or end > length

    • closestPointOnPolyLine

      P closestPointOnPolyLine(P point)
      Project a Point on this PolyLine. If the the projected points lies outside this PolyLine, the nearest end point of this PolyLine is returned. Otherwise the returned point lies between the end points of this PolyLine.
      Parameters:
      point - the point to project onto this PolyLine
      Returns:
      either the start point, or the end point of this PolyLine or a Point that lies somewhere along this PolyLine
      Throws:
      NullPointerException - when point is null

    • getLocation

      D getLocation(double 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 DirectedPoint at the position on the line, pointing in the direction of the line at that position. If the position is at (or very near) a point on this PolyLine, the direction is either the direction before, or the direction after that point
      Throws:
      ArithmeticException - when position is NaN
      IllegalArgumentException - when position < 0.0, or position > getLength().

    • getLocationExtended

      D getLocationExtended(double 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, or after the line
      Returns:
      a DirectedPoint at the position on the line, pointing in the direction of the line at that position. If the position is at (or very near) a point on this PolyLine, the direction is either the direction before, or the direction after that point. If the position is before the start point of this PolyLine, the direction is towards the start point. If the position is beyond the end of this PolyLine, the direction is the direction of the last segment of this PolyLine.

    • getLocationFraction

      default D getLocationFraction(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 DirectedPoint at the position on the line, pointing in the direction of the line at that position. If the position is at (or very near) a point on this PolyLine, the direction is either the direction before, or the direction after that point
      Throws:
      IllegalArgumentException - when fraction < 0.0 or fraction > 1.0

    • getLocationFraction

      default D getLocationFraction(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 DirectedPoint at the position on the line, pointing in the direction of the line at that position. If the position is at (or very near) a point on this PolyLine, the direction is either the direction before, or the direction after that point. If the position is before the start point of this PolyLine, the direction is towards the start point. If the position is beyond the end of this PolyLine, the direction is the direction of the last segment of this PolyLine.
      Throws:
      IllegalArgumentException - when fraction < -tolerance, or fraction > 1.0 + tolerance

    • getLocationFractionExtended

      default D getLocationFractionExtended(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 DirectedPoint at the position on the line, pointing in the direction of the line at that position. If the position is at (or very near) a point on this PolyLine, the direction is either the direction before, or the direction after that point. If the position is before the start point of this PolyLine, the direction is towards the start point. If the position is beyond the end of this PolyLine, the direction is the direction of the last segment of this PolyLine.

    • truncate

      L truncate(double position)
      Truncate this PolyLine at the given length (less than the length of the line, and larger than zero) and return a new line.
      Parameters:
      position - the position along the line where to truncate the line
      Returns:
      a new PolyLine that follows this PolyLine, but ends at the position where line.getLength() == lengthSI
      Throws:
      IllegalArgumentException - when position ≤ 0.0, or position > getLength()

    • find

      default int find(double pos)
      Binary search for a point index on this PolyLine that is at, or the the nearest one before a given position.
      Parameters:
      pos - the position to look for
      Returns:
      the position lies between points[index] and points[index+1]
      Throws:
      DrawRuntimeException - when the point index could not be found (should never happen)

    • offsetLine

      default L offsetLine(double offset) throws DrawRuntimeException
      Construct an offset PolyLine. This is similar to what geographical specialists call buffering, except that this method only construct a new line on one side of the reference line and does not add half disks (or miters) at the end points. This method tries to strike a delicate balance between generating too few and too many points to approximate arcs. Noise in this (the reference line) can cause major artifacts in the offset line. This method calls the underlying method with default values for circlePrecision (DEFAULT_OFFSET), offsetMinimumFilterValue (DEFAULT_OFFSET_MINIMUM_FILTER_VALUE), offsetMaximumFilterValue (DEFAULT_OFFSET_MAXIMUM_FILTER_VALUE), offsetFilterRatio (DEFAULT_OFFSET_FILTER_RATIO), minimumOffset (DEFAULT_OFFSET_PRECISION).
      In the 3D version the offset is parallel to the X-Y plane.
      Parameters:
      offset - the offset; positive values indicate left of the reference line, negative values indicate right of the reference line
      Returns:
      a PolyLine at the specified offset from the this PolyLine
      Throws:
      DrawRuntimeException - Only if P is PolyLine3d and the line cannot be projected into 2d

    • offsetLine

      L offsetLine(double offset, double circlePrecision, double offsetMinimumFilterValue, double offsetMaximumFilterValue, double offsetFilterRatio, double minimumOffset)
      Construct an offset line. This is similar to what geographical specialists call buffering, except that this method only construct a new line on one side of the reference line and does not add half disks (or miters) around the end points. This method tries to strike a delicate balance between generating too few and too many points to approximate arcs. Noise in this (the reference line) can cause major artifacts in the offset line.
      In the 3D version the offset is parallel to the X-Y plane.
      Parameters:
      offset - the offset; positive values indicate left of the reference line, negative values indicate right of the reference line
      circlePrecision - precision of approximation of arcs; the line segments that are used to approximate an arc will not deviate from the exact arc by more than this value
      offsetMinimumFilterValue - noise in the reference line less than this value is always filtered
      offsetMaximumFilterValue - noise in the reference line greater than this value is never filtered
      offsetFilterRatio - noise in the reference line less than offset / offsetFilterRatio is filtered except when the resulting value exceeds offsetMaximumFilterValue
      minimumOffset - an offset value less than this value is treated as 0.0
      Returns:
      a PolyLine at the specified offset from the reference line
      Throws:
      ArithmeticException - when offset, or circlePrecision, offsetMinimumFilterValue, offsetMaximumfilterValue, offsetFilterRatio, or minimumOffset is NaN
      IllegalArgumentException - when circlePrecision, offsetMinimumFilterValue, offsetMaximumfilterValue, offsetFilterRatio, or minimumOffset is not positive, or offsetMinimumFilterValue ≥ offsetMaximumFilterValue
      DrawRuntimeException - Only if P is PolyLine3d and the line cannot be projected into 2d

    • offsetLine

      default L offsetLine(double offsetAtStart, double offsetAtEnd)
      Construct an offset line. This is similar to what geographical specialists call buffering, except that this method only construct a new line on one side of the reference line and does not add half disks (or miters) around the end points. This method tries to strike a delicate balance between generating too few and too many points to approximate arcs. Noise in this (the reference line) can cause major artifacts in the offset line. This method calls the underlying method with default values for circlePrecision (DEFAULT_OFFSET), offsetMinimumFilterValue (DEFAULT_OFFSET_MINIMUM_FILTER_VALUE), offsetMaximumFilterValue (DEFAULT_OFFSET_MAXIMUM_FILTER_VALUE), offsetFilterRatio (DEFAULT_OFFSET_FILTER_RATIO), minimumOffset (DEFAULT_OFFSET_PRECISION).
      In the 3D version the offset is parallel to the X-Y plane.
      Parameters:
      offsetAtStart - the offset at the start of this line; positive values indicate left of the reference line, negative values indicate right of the reference line
      offsetAtEnd - the offset at the end of this line; positive values indicate left of the reference line, negative values indicate right of the reference line
      Returns:
      a PolyLine at the specified offset from the reference line
      Throws:
      ArithmeticException - when offset, or circlePrecision, offsetMinimumFilterValue, offsetMaximumfilterValue, offsetFilterRatio, or minimumOffset is NaN
      IllegalArgumentException - when circlePrecision, offsetMinimumFilterValue, offsetMaximumfilterValue, offsetFilterRatio, or minimumOffset is not positive, or offsetMinimumFilterValue ≥ offsetMaximumFilterValue.
      DrawRuntimeException - Only if P is PolyLine3d and the line cannot be projected into 2d

    • offsetLine

      L offsetLine(double offsetAtStart, double offsetAtEnd, double circlePrecision, double offsetMinimumFilterValue, double offsetMaximumFilterValue, double offsetFilterRatio, double minimumOffset)
      Construct an offset line. This is similar to what geographical specialists call buffering, except that this method only construct a new line on one side of the reference line and does not add half disks (or miters) around the end points. This method tries to strike a delicate balance between generating too few and too many points to approximate arcs. Noise in this (the reference line) can cause major artifacts in the offset line.
      In the 3D version the offset is parallel to the X-Y plane.
      Parameters:
      offsetAtStart - the offset at the start of this line; positive values indicate left of the reference line, negative values indicate right of the reference line
      offsetAtEnd - the offset at the end of this line; positive values indicate left of the reference line, negative values indicate right of the reference line
      circlePrecision - precision of approximation of arcs; the line segments that are used to approximate an arc will not deviate from the exact arc by more than this value
      offsetMinimumFilterValue - noise in the reference line less than this value is always filtered
      offsetMaximumFilterValue - noise in the reference line greater than this value is never filtered
      offsetFilterRatio - noise in the reference line less than offset / offsetFilterRatio is filtered except when the resulting value exceeds offsetMaximumFilterValue
      minimumOffset - an offset value less than this value is treated as 0.0
      Returns:
      a PolyLine at the specified offset from the reference line
      Throws:
      ArithmeticException - when offset, or circlePrecision, offsetMinimumFilterValue, offsetMaximumfilterValue, offsetFilterRatio, or minimumOffset is NaN
      IllegalArgumentException - when circlePrecision, offsetMinimumFilterValue, offsetMaximumfilterValue, offsetFilterRatio, or minimumOffset is not positive, or offsetMinimumFilterValue ≥ offsetMaximumFilterValue
      DrawRuntimeException - Only if P is PolyLine3d and the line cannot be projected into 2d

    • offsetLine

      L offsetLine(double[] relativeFractions, double[] offsets, double offsetMinimumFilterValue)
      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)
      offsetMinimumFilterValue - noise in the reference line less than this value is filtered
      Returns:
      the PolyLine2d of the line at multi-linearly changing offset of the reference line
      Throws:
      DrawRuntimeException - when this method fails to create the offset line
      IllegalArgumentException - when relativeFractions is too short, or differs in length from offsets

    • transitionLine

      L transitionLine(L endLine, PolyLine.TransitionFunction transition)
      Make a transition line from this PolyLine to another PolyLine using a user specified function.
      Parameters:
      endLine - the other PolyLine
      transition - defines how the results changes from this line to the endLine
      Returns:
      a transition between this PolyLine and the other PolyLine
      Throws:
      ArithmeticException - when the transition function returns NaN at some point
      DrawRuntimeException - when construction of some point along the way fails

    • filterNearDuplicates

      default double[][] filterNearDuplicates(double epsilon, double[]... coordinates)
      Filter adjacent points that are (near) duplicates. Works for any number of dimensions.
      Parameters:
      epsilon - minimum distance between points to be considered different (these will not be filtered out). To filter out only exactly identical points, specify 0.0. To disable all filtering, specify a NO_FILTER value for epsilon
      coordinates - double[][] the coordinates of the points. First index is the dimension (0 for x, etc), second index is the rank of the point
      Returns:
      filtered coordinates of the points in the same format as coordinates