Package org.djutils.draw.line

Class PolyLine2d

    • Field Detail

      • DEFAULT_CIRCLE_PRECISION

        public 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

        public 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

        public 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

        public 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

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

    • Constructor Detail

      • PolyLine2d

        public PolyLine2d​(Point2d point1,
                  Point2d point2,
                  Point2d... otherPoints)
           throws NullPointerException,
                  DrawRuntimeException
        Construct a new PolyLine2d from an array of Point2d.
        Parameters:
        point1 - Point2d; starting point of the PolyLine2d
        point2 - Point2d; second point of the PolyLine2d
        otherPoints - Point2d...; additional points of the PolyLine2d
        Throws:
        NullPointerException - when iterator is null
        DrawRuntimeException - when the provided points do not constitute a valid line (too few points or identical adjacent points)

      • PolyLine2d

        public PolyLine2d​(Iterator<Point2d> iterator)
           throws NullPointerException,
                  DrawException
        Construct a new Line2d and initialize its length indexed line, bounds, centroid and length.
        Parameters:
        iterator - Iterator<Point2d>; iterator that will provide all points that constitute the new Line2d
        Throws:
        NullPointerException - when iterator is null
        DrawException - when the iterator provides too few points, or some adjacent identical points)

      • PolyLine2d

        public PolyLine2d​(List<Point2d> pointList)
           throws DrawRuntimeException
        Construct a new Line2d from a List<Point2d>.
        Parameters:
        pointList - List<Point2d>; the list of points to construct this Line2d from.
        Throws:
        DrawRuntimeException - when the provided points do not constitute a valid line (too few points or identical adjacent points)

      • PolyLine2d

        public PolyLine2d​(Path2D path)
           throws DrawException
        Construct a new Line2d (closed shape) from a Path2D.
        Parameters:
        path - Path2D; the Path2D to construct this Line2d from.
        Throws:
        DrawException - when the provided points do not constitute a valid line (too few points or identical adjacent points)

    • Method Detail

      • size

        public int size()
        Retrieve the number of points that make up the object.
        Specified by:
        size in interface Drawable<Point2d,​Space2d>
        Returns:
        int; the number of points that make up the object

      • lengthAtIndex

        public final double lengthAtIndex​(int index)
        Access the internal lengthIndexedLine. Return the cumulative length up to point index of this line
        Specified by:
        lengthAtIndex in interface PolyLine<PolyLine2d,​Point2d,​Space2d,​Ray2d>
        Parameters:
        index - int; the index
        Returns:
        double; the cumulative length of this line up to point index

      • getLength

        public final 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.
        Specified by:
        getLength in interface PolyLine<PolyLine2d,​Point2d,​Space2d,​Ray2d>
        Returns:
        double; the length of this line

      • getPoints

        public Iterator<Point2d> getPoints()
        Retrieve, or generate all points that make up the object.
        Specified by:
        getPoints in interface Drawable<Point2d,​Space2d>
        Returns:
        Iterable<Point2d>; an iterator that generates all points that make up the object

      • getBounds

        public Bounds2d getBounds()
        Retrieve the bounding rectangle of the object.
        Specified by:
        getBounds in interface Drawable2d
        Returns:
        Bounds2d; the bounding box of the object

      • noiseFilteredLine

        public final PolyLine2d noiseFilteredLine​(double noiseLevel)
        Construct a new Line2d 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:
        Line2d; the filtered line

      • concatenate

        public static PolyLine2d concatenate​(PolyLine2d... lines)
                              throws DrawException
        Concatenate several Line2d instances.
        Parameters:
        lines - PolyLine2d...; Line2d... one or more Line2d. The last point of the first <strong>must</strong> match the first of the second, etc.
        Returns:
        Line2d
        Throws:
        DrawException - if zero lines are given, or when there is a gap between consecutive lines

      • concatenate

        public static PolyLine2d concatenate​(double tolerance,
                                     PolyLine2d line1,
                                     PolyLine2d line2)
                              throws DrawException
        Concatenate two Line2d instances. This method is separate for efficiency reasons.
        Parameters:
        tolerance - double; the tolerance between the end point of a line and the first point of the next line
        line1 - PolyLine2d; first line
        line2 - PolyLine2d; second line
        Returns:
        Line2d; the concatenation of the two lines
        Throws:
        DrawException - if zero lines are given, or when there is a gap between consecutive lines

      • concatenate

        public static PolyLine2d concatenate​(double tolerance,
                                     PolyLine2d... lines)
                              throws DrawException
        Concatenate several Line2d instances.
        Parameters:
        tolerance - double; the tolerance between the end point of a line and the first point of the next line
        lines - PolyLine2d...; Line2d... one or more Line2d. The last point of the first <strong>must</strong> match the first of the second, etc.
        Returns:
        Line2d; the concatenation of the lines
        Throws:
        DrawException - if zero lines are given, or when there is a gap between consecutive lines

      • createAndCleanPolyLine2d

        public static PolyLine2d createAndCleanPolyLine2d​(Point2d... points)
                                           throws DrawException
        Create a new Line2d, filtering out repeating successive points.
        Parameters:
        points - Point2d...; the coordinates of the line as Point2d
        Returns:
        the line
        Throws:
        DrawException - when number of points < 2

      • createAndCleanPolyLine2d

        public static PolyLine2d createAndCleanPolyLine2d​(List<Point2d> pointList)
                                           throws DrawException
        Create an Line2d, while filtering out repeating successive points.
        Parameters:
        pointList - List<Point2d>; list of the coordinates of the line as Point2d; any duplicate points in this list are removed (this method may modify the provided list)
        Returns:
        Line2d; the line
        Throws:
        DrawException - when number of non-equal points < 2

      • getLocationExtended

        public final Ray2d 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.
        Specified by:
        getLocationExtended in interface PolyLine<PolyLine2d,​Point2d,​Space2d,​Ray2d>
        Parameters:
        position - double; the position on the line for which to calculate the point on, before, or after the line
        Returns:
        OP; an oriented point

      • getLocation

        public final Ray2d getLocation​(double position)
                        throws DrawException
        Get the location at a position on the line, with its direction. Position should be between 0.0 and line length.
        Specified by:
        getLocation in interface PolyLine<PolyLine2d,​Point2d,​Space2d,​Ray2d>
        Parameters:
        position - double; the position on the line for which to calculate the point on the line
        Returns:
        OP; an oriented point
        Throws:
        DrawException - when position less than 0.0 or more than line length.

      • projectOrthogonal

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

      • projectOrthogonal

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

      • extract

        public PolyLine2d extract​(double start,
                          double end)
                   throws DrawException
        Create a new L that covers a sub-section of this L.
        Specified by:
        extract in interface PolyLine<PolyLine2d,​Point2d,​Space2d,​Ray2d>
        Parameters:
        start - double; length along this Line3d where the sub-section starts, valid range [0..end)
        end - double; length along this Line3d where the sub-section ends, valid range (start..length (length is the length of this L)
        Returns:
        L; the selected sub-section
        Throws:
        DrawException - when start >= end, or start < 0, or end > length

      • truncate

        public PolyLine2d truncate​(double position)
                    throws DrawException
        Truncate this Line at the given length (less than the length of the line, and larger than zero) and return a new line.
        Specified by:
        truncate in interface PolyLine<PolyLine2d,​Point2d,​Space2d,​Ray2d>
        Parameters:
        position - double; the position along the line where to truncate the line
        Returns:
        L; a new Line that follows this line, but ends at the position where line.getLength() == lengthSI
        Throws:
        DrawException - when position less than 0.0 or more than line length.

      • offsetLine

        public PolyLine2d offsetLine​(double offset)
        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 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).
        Parameters:
        offset - double; the offset; positive values indicate left of the reference line, negative values indicate right of the reference line
        Returns:
        PolyLine2d; a line at the specified offset from the reference line

      • offsetLine

        public PolyLine2d offsetLine​(double offset,
                             double circlePrecision,
                             double offsetMinimumFilterValue,
                             double offsetMaximumFilterValue,
                             double offsetFilterRatio,
                             double minimumOffset)
                      throws IllegalArgumentException
        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 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.
        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:
        PolyLine2d; a line 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

      • projectRay

        public double projectRay​(Ray2d orientedPoint)
                  throws NullPointerException
        Find a location on this PolyLine2d that is a reasonable projection of a DirectedPoint on this line. The result (if not NaN) lies on a line perpendicular to the direction of the DirectedPoint and on some segment of this PolyLine. This method attempts to give continuous results for continuous changes of the DirectedPoint that must be projected. There are cases where this is simply impossible, or the optimal result is ambiguous. In these cases this method will return something that is hopefully good enough.
        Parameters:
        orientedPoint - Ray2d; the DirectedPoint
        Returns:
        double; length along this PolyLine (some value between 0 and the length of this PolyLine) where directedPoint projects, or NaN if there is no solution
        Throws:
        NullPointerException - when directedPoint is null

      • toExcel

        public final String toExcel()
        Convert this PolyLine2d to something that MS-Excel can plot.
        Returns:
        excel XY plottable output

      • toPlot

        public final String toPlot()
        Convert this PolyLine3D to Peter's plot format.
        Returns:
        Peter's format plot output

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object