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-2021 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 double DEFAULT_CIRCLE_PRECISION
      Default precision of approximation of arcs in the offsetLine method.
      static 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 double DEFAULT_OFFSET_MAXIMUM_FILTER_VALUE
      By default, noise in the reference line of the offsetLineMethod greater than this value is never filtered.
      static 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 double DEFAULT_OFFSET_PRECISION
      By default, the offsetLineMethod uses this offset precision.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      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.

    • Field Detail

      • DEFAULT_CIRCLE_PRECISION

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

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • DEFAULT_OFFSET_PRECISION

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

    • Method Detail

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