Package org.djutils.draw.line

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

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

Copyright (c) 2020-2024 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

  • 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.

  • 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 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.
    R
    getLocation(double position)
    Get the location at a position on the line, with its direction.
    R
    getLocationExtended(double position)
    Get the location at a position on the line, with its direction.
    default R
    getLocationFraction(double fraction)
    Get the location at a fraction of the line, with its direction.
    default R
    getLocationFraction(double fraction, double tolerance)
    Get the location at a fraction of the line, with its direction.
    default R
    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(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.
    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.
    String
    toExcel()
    Convert this PolyLine to something that MS-Excel can plot.
    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, getPoints, size, toString, toString, toString, toString

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

    projectOrthogonal, projectOrthogonalExtended, projectOrthogonalFractional, projectOrthogonalFractionalExtended

  • Field Details

    • 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

      L instantiate(List<P> pointList) throws NullPointerException, DrawRuntimeException
      Constructor that can be accessed as a method (used to implement default methods in this interface).
      Parameters:
      pointList - List<P>; a list of points
      Returns:
      L; the new PolyLine
      Throws:
      NullPointerException - when pointList is null
      DrawRuntimeException - 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 - double; the minimum segment length that is not removed
      Returns:
      PolyLine2d; 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:
      double; the length of this line

    • get

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

    • getX

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

    • getY

      double getY(int index) throws IndexOutOfBoundsException
      Return the y-coordinate of a point of this PolyLine.
      Parameters:
      index - int; the index of the requested y-coordinate
      Returns:
      double; 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:
      P; the first point of this line

    • getLast

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

    • getSegment

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

    • lengthAtIndex

      double lengthAtIndex(int index) throws IndexOutOfBoundsException
      Access the internal lengthIndexedLine. Return the cumulative length up to point index of this line
      Parameters:
      index - int; the index
      Returns:
      double; 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:
      L; the new PolyLine

    • extractFractional

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

    • extract

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

    • closestPointOnPolyLine

      P closestPointOnPolyLine(P point) throws NullPointerException
      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 - P; the point to project onto this PolyLine
      Returns:
      P; 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

      R getLocation(double position) throws DrawRuntimeException
      Get the location at a position on the line, with its direction. Position should be between 0.0 and line length.
      Parameters:
      position - double; the position on the line for which to calculate the point on the line
      Returns:
      R; a Ray 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:
      DrawRuntimeException - when position is NaN, less than 0.0, or more than line length.

    • getLocationExtended

      R 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 - double; the position on the line for which to calculate the point on, before, or after the line
      Returns:
      R; a Ray 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 R getLocationFraction(double fraction) throws DrawRuntimeException
      Get the location at a fraction of the line, with its direction. Fraction should be between 0.0 and 1.0.
      Parameters:
      fraction - double; the fraction for which to calculate the point on the line
      Returns:
      R; a Ray 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:
      DrawRuntimeException - when fraction less than 0.0 or more than 1.0.

    • getLocationFraction

      default R getLocationFraction(double fraction, double tolerance) throws DrawRuntimeException
      Get the location at a fraction of the line, with its direction. Fraction should be between 0.0 and 1.0.
      Parameters:
      fraction - double; the fraction for which to calculate the point on the line
      tolerance - double; the delta from 0.0 and 1.0 that will be forgiven
      Returns:
      R; a Ray 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:
      DrawRuntimeException - when fraction less than 0.0 or more than 1.0.

    • getLocationFractionExtended

      default R getLocationFractionExtended(double fraction)
      Get the location at a fraction of the line (or outside the line), with its direction.
      Parameters:
      fraction - double; the fraction for which to calculate the point on the line
      Returns:
      R; a Ray 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) throws DrawRuntimeException
      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 - double; the position along the line where to truncate the line
      Returns:
      L; a new PolyLine that follows this PolyLine, but ends at the position where line.getLength() == lengthSI
      Throws:
      DrawRuntimeException - when position less than 0.0 or more than line length.

    • find

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

    • toExcel

      String toExcel()
      Convert this PolyLine to something that MS-Excel can plot.
      Returns:
      String MS-excel XY, or XYZ plottable output

    • 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 - double; the offset; positive values indicate left of the reference line, negative values indicate right of the reference line
      Returns:
      L; 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) throws IllegalArgumentException, DrawRuntimeException
      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 - double; the offset; positive values indicate left of the reference line, negative values indicate right of the reference line
      circlePrecision - double; 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 - double; noise in the reference line less than this value is always filtered
      offsetMaximumFilterValue - double; noise in the reference line greater than this value is never filtered
      offsetFilterRatio - double; noise in the reference line less than offset / offsetFilterRatio is filtered except when the resulting value exceeds offsetMaximumFilterValue
      minimumOffset - double; an offset value less than this value is treated as 0.0
      Returns:
      L; a PolyLine at the specified offset from the reference line
      Throws:
      IllegalArgumentException - when offset is NaN, or circlePrecision, offsetMinimumFilterValue, offsetMaximumfilterValue, offsetFilterRatio, or minimumOffset is not positive, or NaN, 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) throws IllegalArgumentException, DrawRuntimeException
      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 - double; 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 - double; 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:
      L; a PolyLine at the specified offset from the reference line
      Throws:
      IllegalArgumentException - when offset is NaN, or circlePrecision, offsetMinimumFilterValue, offsetMaximumfilterValue, offsetFilterRatio, or minimumOffset is not positive, or NaN, 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) throws IllegalArgumentException, DrawRuntimeException
      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 - double; 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 - double; 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 - double; 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 - double; noise in the reference line less than this value is always filtered
      offsetMaximumFilterValue - double; noise in the reference line greater than this value is never filtered
      offsetFilterRatio - double; noise in the reference line less than offset / offsetFilterRatio is filtered except when the resulting value exceeds offsetMaximumFilterValue
      minimumOffset - double; an offset value less than this value is treated as 0.0
      Returns:
      L; a PolyLine at the specified offset from the reference line
      Throws:
      IllegalArgumentException - when offset is NaN, or circlePrecision, offsetMinimumFilterValue, offsetMaximumfilterValue, offsetFilterRatio, or minimumOffset is not positive, or NaN, or offsetMinimumFilterValue >= offsetMaximumFilterValue
      DrawRuntimeException - Only if P is PolyLine3d and the line cannot be projected into 2d

    • transitionLine

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