Package org.djutils.draw.line

Class PolyLine3d

    • Constructor Detail

      • PolyLine3d

        public PolyLine3d​(double x,
                  double y,
                  double z,
                  double phi,
                  double theta)
           throws DrawRuntimeException
        Construct a degenerate PolyLine3d (consisting of only one point).
        Parameters:
        x - double; the x-coordinate
        y - double; the y-coordinate
        z - double; the z-coordinate
        phi - double; the angle from the positive X axis direction in radians.
        theta - double; the angle from the positive Z axis direction in radians
        Throws:
        DrawRuntimeException - when x, y, or heading is NaN, or heading is infinite

      • PolyLine3d

        public PolyLine3d​(Point3d p,
                  double phi,
                  double theta)
           throws NullPointerException,
                  DrawRuntimeException
        Construct a degenerate PolyLine3d (consisting of only one point).
        Parameters:
        p - Point3d; the point of the degenerate PolyLine3d
        phi - double; the angle from the positive X axis direction in radians.
        theta - double; the angle from the positive Z axis direction in radians
        Throws:
        NullPointerException - when p is null
        DrawRuntimeException - when heading is infinite

      • PolyLine3d

        public PolyLine3d​(double[] x,
                  double[] y,
                  double[] z)
           throws NullPointerException,
                  DrawRuntimeException
        Construct a new PolyLine3d from an array of Point2d. This constructor makes a deep copy of the parameters.
        Parameters:
        x - double[]; the x-coordinates of the points
        y - double[]; the y-coordinates of the points
        z - double[]; the z-coordinates of the points
        Throws:
        NullPointerException - when iterator is null
        DrawRuntimeException - when the provided points do not constitute a valid line (too few points or identical adjacent points)

      • PolyLine3d

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

      • PolyLine3d

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

      • PolyLine3d

        public PolyLine3d​(boolean filterDuplicates,
                  Point3d... points)
           throws DrawRuntimeException
        Create a new PolyLine3d, optionally filtering out repeating successive points.
        Parameters:
        filterDuplicates - boolean; if true; filter out successive repeated points; otherwise do not filter
        points - Point3d...; the coordinates of the line as Point2d
        Throws:
        DrawRuntimeException - when number of points < 2

      • PolyLine3d

        public PolyLine3d​(boolean filterDuplicates,
                  List<Point3d> pointList)
           throws DrawRuntimeException
        Create a new PolyLine3d, optionally filtering out repeating successive points.
        Parameters:
        filterDuplicates - boolean; if true; filter out successive repeated points; otherwise do not filter
        pointList - List<Point3d>; list of the coordinates of the line as Point3d; any duplicate points in this list are removed (this method may modify the provided list)
        Throws:
        DrawRuntimeException - when number of non-equal points < 2

    • Method Detail

      • makeArray

        protected static double[] makeArray​(Point3d[] points,
                                    Function<Point3d,​Double> getter)
        Make an array of double an fill it with the appropriate coordinate of points.
        Parameters:
        points - Point3d[]; array of points
        getter - Function<Point3d, Double>; function that obtains the intended coordinate
        Returns:
        double[]; array of double filled with the requested coordinate values

      • cleanPoints

        static Iterator<Point3d> cleanPoints​(boolean filter,
                                     Iterator<Point3d> iterator)
        Return an iterator that optionally skips identical successive points.
        Parameters:
        filter - boolean; if true; filter out itentical successive points; if false; do not filter
        iterator - Iterator<Point3d>; iterator that generates points, potentially with successive duplicates
        Returns:
        Iterator<Point3d>; iterator that skips identical successive points

      • iteratorToList

        static List<Point3d> iteratorToList​(Iterator<Point3d> iterator)
        Build a list from the Point3d objects that an iterator provides.
        Parameters:
        iterator - Iterator<Point3d>; the iterator that will provide the points
        Returns:
        List<Point3d>; a list of the points provided by the iterator

      • size

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

      • getZ

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

      • getSegment

        public LineSegment3d getSegment​(int index)
        Extract one LineSegment of this PolyLine, or Polygon.
        Specified by:
        getSegment in interface PolyLine<PolyLine3d,​Point3d,​Ray3d,​LineSegment3d>
        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

        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<PolyLine3d,​Point3d,​Ray3d,​LineSegment3d>
        Parameters:
        index - int; the index
        Returns:
        double; the cumulative length of this line up to point index

      • getLength

        public 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<PolyLine3d,​Point3d,​Ray3d,​LineSegment3d>
        Returns:
        double; the length of this line

      • getPoints

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

      • getBounds

        public Bounds3d getBounds()
        Retrieve the bounding box of the object.
        Specified by:
        getBounds in interface Drawable3d
        Returns:
        Bounds3d; the bounding box of the object

      • noiseFilteredLine

        public final PolyLine3d 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.
        Specified by:
        noiseFilteredLine in interface PolyLine<PolyLine3d,​Point3d,​Ray3d,​LineSegment3d>
        Parameters:
        noiseLevel - double; the minimum segment length that is not removed
        Returns:
        PolyLine2d; the filtered line

      • concatenate

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

      • concatenate

        public static PolyLine3d concatenate​(double tolerance,
                                     PolyLine3d line1,
                                     PolyLine3d line2)
                              throws DrawRuntimeException
        Concatenate two PolyLine3d 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 - PolyLine3d; first line
        line2 - PolyLine3d; second line
        Returns:
        PolyLine3d; the concatenation of the two lines
        Throws:
        DrawRuntimeException - if zero lines are given, or when there is a gap between consecutive lines

      • concatenate

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

      • project

        public PolyLine2d project()
                   throws DrawRuntimeException
        Project the object onto the z=0 plane.
        Specified by:
        project in interface Drawable3d
        Returns:
        Drawable2d; the projected object
        Throws:
        DrawRuntimeException - when projecting onto the z=0 plane results in an invalid object. E.g. a Line3d that consists of points that all have the exact same x and y coordinates cannot be a line after projecting on the z=0 plane.

      • getLocationExtended

        public final Ray3d 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<PolyLine3d,​Point3d,​Ray3d,​LineSegment3d>
        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.

      • getLocation

        public final Ray3d 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.
        Specified by:
        getLocation in interface PolyLine<PolyLine3d,​Point3d,​Ray3d,​LineSegment3d>
        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.

      • closestPointOnPolyLine

        public Point3d closestPointOnPolyLine​(Point3d 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.
        Specified by:
        closestPointOnPolyLine in interface PolyLine<PolyLine3d,​Point3d,​Ray3d,​LineSegment3d>
        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.

      • projectOrthogonal

        public Point3d projectOrthogonal​(Point3d point)
                          throws NullPointerException
        Project a point onto this object. For PolyLines, there may be multiple valid solutions. In that case the solution that lies on the closest segment is returned. If there is no valid solution on the closest segment, null is returned.
        Specified by:
        projectOrthogonal in interface Project<Point3d>
        Parameters:
        point - P; the point
        Returns:
        P; the projection of the point (may be null if no sensible projection is possible). If the result is not null; the result lies somewhere on this object.
        Throws:
        NullPointerException - when point is null;

      • projectOrthogonalExtended

        public Point3d projectOrthogonalExtended​(Point3d point)
                                  throws NullPointerException
        Project a point onto this object. For PolyLines, there may be multiple valid solutions. In that case the solution that lies on the closest segment is returned.
        Specified by:
        projectOrthogonalExtended in interface Project<Point3d>
        Parameters:
        point - P; the point
        Returns:
        P; the projection of the point. This result cannot be null, but it may not lie on this object, but, in stead, lie on a line, or plane that extends this object
        Throws:
        NullPointerException - when point is null;

      • projectOrthogonalFractional

        public final double projectOrthogonalFractional​(Point3d point)
                                         throws NullPointerException
        Project a point onto this object. For PolyLines, there may be multiple valid solutions. In that case the solution that lies on the closest segment is returned. If there is no valid solution on the closest segment, null is returned.
        Specified by:
        projectOrthogonalFractional in interface Project<Point3d>
        Parameters:
        point - P; the point
        Returns:
        double; the fractional position of the projection of the point (may be NaN if no sensible projection is possible). If the result is not null; the result lies somewhere on this object.
        Throws:
        NullPointerException - when point is null;

      • projectOrthogonalFractionalExtended

        public double projectOrthogonalFractionalExtended​(Point3d point)
                                           throws NullPointerException
        Project a point onto this object. For PolyLines, there may be multiple valid solutions. In that case the solution that lies on the closest segment is returned.
        Specified by:
        projectOrthogonalFractionalExtended in interface Project<Point3d>
        Parameters:
        point - P; the point
        Returns:
        double; the fractional position of the projection of the point. This result cannot be NaN, but it may be outside the range 0.0 .. 1.0.
        Throws:
        NullPointerException - when point is null;

      • extract

        public PolyLine3d extract​(double start,
                          double end)
                   throws DrawRuntimeException
        Create a new PolyLine that covers a sub-section of this PolyLine.
        Specified by:
        extract in interface PolyLine<PolyLine3d,​Point3d,​Ray3d,​LineSegment3d>
        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

      • offsetLine

        public PolyLine3d 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 (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.
        Specified by:
        offsetLine in interface PolyLine<PolyLine3d,​Point3d,​Ray3d,​LineSegment3d>
        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

      • offsetLine

        public PolyLine3d offsetLine​(double offsetAtStart,
                             double offsetAtEnd,
                             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 (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.
        Specified by:
        offsetLine in interface PolyLine<PolyLine3d,​Point3d,​Ray3d,​LineSegment3d>
        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

      • truncate

        public PolyLine3d 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.
        Specified by:
        truncate in interface PolyLine<PolyLine3d,​Point3d,​Ray3d,​LineSegment3d>
        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.

      • toString

        public String toString()
        Produce a string describing the Drawable using default conversion for the (double) coordinate values. Regrettably, it is not allowed to provide a default implementation here.
        Specified by:
        toString in interface Drawable<Point3d>
        Overrides:
        toString in class Object
        Returns:
        String; a string describing the Drawable

      • toString

        public String toString​(String doubleFormat,
                       boolean doNotIncludeClassName)
        Produce a String describing the Drawable.
        Specified by:
        toString in interface Drawable<Point3d>
        Parameters:
        doubleFormat - String; a format string (something like "%6.3f") which will be used to render every coordinate value)
        doNotIncludeClassName - boolean; if true; the output of toString is not prefixed by the class name. This is useful for concatenating the textual representation of lots of Drawables (e.g. an array, or a List).
        Returns:
        String; textual representation of the Drawable

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object