Package org.djutils.draw.line

Class PolyLine3d

java.lang.Object
org.djutils.draw.line.PolyLine3d
All Implemented Interfaces:
Serializable, Iterable<Point3d>, Drawable<Point3d>, Drawable3d, PolyLine<PolyLine3d,Point3d,Ray3d,DirectedPoint3d,LineSegment3d>, Project<Point3d>
Direct Known Subclasses:
Polygon3d
public class PolyLine3d extends Object implements Drawable3d, PolyLine<PolyLine3d,Point3d,Ray3d,DirectedPoint3d,LineSegment3d>
Implementation of PolyLine for 3D space.

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
See Also:

  • Constructor Details

    • PolyLine3d

      public PolyLine3d(double x, double y, double z, double dirY, double dirZ)
      Construct a degenerate PolyLine3d (consisting of only one point).
      Parameters:
      x - the x-coordinate
      y - the y-coordinate
      z - the z-coordinate
      dirY - the angle from the positive Z axis direction in radians
      dirZ - the angle from the positive X axis direction in radians.
      Throws:
      ArithmeticException - when x, y, z, or dirY, or dirZ is NaN
      IllegalArgumentException - when dirY, or dirZ is infinite

    • PolyLine3d

      public PolyLine3d(Point3d p, double dirY, double dirZ)
      Construct a degenerate PolyLine3d (consisting of only one point).
      Parameters:
      p - the point of the degenerate PolyLine3d
      dirY - the angle from the positive Z axis direction in radians
      dirZ - the angle from the positive X axis direction in the XY plane in radians.
      Throws:
      NullPointerException - when p is null
      ArithmeticException - when dirY, or dirZ is NaN
      IllegalArgumentException - when dirY, or dirZ is infinite

    • PolyLine3d

      public PolyLine3d(DirectedPoint3d directedPoint3d) throws NullPointerException, IllegalArgumentException
      Construct a degenerate PolyLine3d (consisting of only one point).
      Parameters:
      directedPoint3d - point, dirY and dirZ of the degenerate PolyLine3d
      Throws:
      NullPointerException - when p is null
      IllegalArgumentException - when dirY or dirZ is infinite (should not be possible)

    • PolyLine3d

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

    • PolyLine3d

      public PolyLine3d(double epsilon, double[] x, double[] y, double[] z)
      Construct a new PolyLine3d from an array of Point2d. This constructor makes a deep copy of the parameters.
      Parameters:
      epsilon - minimum distance between points to be considered different (these will not be filtered out)
      x - the x-coordinates of the points
      y - the y-coordinates of the points
      z - the z-coordinates of the points
      Throws:
      NullPointerException - when x, y, or z is null
      IllegalArgumentException - when the provided coordinate values do not constitute a valid line (too few points or identical adjacent points, or the arrays are not the same length)

    • PolyLine3d

      public PolyLine3d(Point3d[] points)
      Construct a new PolyLine3d from an array of Point3d.
      Parameters:
      points - the array of points to construct this PolyLine3d from.
      Throws:
      NullPointerException - when the points array is null
      IllegalArgumentException - when the provided points do not constitute a valid line (too few points or identical adjacent points)

    • PolyLine3d

      public PolyLine3d(double epsilon, Point3d[] points)
      Construct a new PolyLine3d from an array of Point3d.
      Parameters:
      epsilon - minimum distance between points to be considered different (these will not be filtered out)
      points - the array of points to construct this PolyLine3d from.
      Throws:
      NullPointerException - when the points array is null
      IllegalArgumentException - 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)
      Construct a new PolyLine3d from two or more Point3d arguments.
      Parameters:
      point1 - starting point of the PolyLine3d
      point2 - second point of the PolyLine3d
      otherPoints - additional points of the PolyLine3d (may be null, or have zero length)
      Throws:
      NullPointerException - when point1, or point2 is null, or otherPoints contains a null value
      IllegalArgumentException - when the provided points do not constitute a valid line (too few points or identical adjacent points)

    • PolyLine3d

      public PolyLine3d(double epsilon, Point3d point1, Point3d point2, Point3d... otherPoints)
      Construct a new PolyLine3d from two or more Point3d arguments.
      Parameters:
      epsilon - minimum distance between points to be considered different (these will not be filtered out)
      point1 - starting point of the PolyLine3d
      point2 - second point of the PolyLine3d
      otherPoints - additional points of the PolyLine3d (may be null, or have zero length)
      Throws:
      NullPointerException - when point1, or point2 is null, or otherPoints contains a null value
      IllegalArgumentException - when the provided points do not constitute a valid line (too few points or identical adjacent points)

    • PolyLine3d

      public PolyLine3d(Iterator<Point3d> iterator)
      Construct a new PolyLine3d from an iterator that yields Point3d objects.
      Parameters:
      iterator - iterator that will provide all points that constitute the new PolyLine3d
      Throws:
      NullPointerException - when iterator is null, or yields a null value
      IllegalArgumentException - when the iterator provides too few points, or some adjacent identical points)

    • PolyLine3d

      public PolyLine3d(double epsilon, Iterator<Point3d> iterator)
      Construct a new PolyLine3d from an iterator that yields Point3d objects.
      Parameters:
      epsilon - minimum distance between points to be considered different (these will not be filtered out)
      iterator - iterator that will provide all points that constitute the new PolyLine3d
      Throws:
      NullPointerException - when iterator is null, or yields a null value
      IllegalArgumentException - when the iterator provides too few points, or some adjacent identical points)

    • PolyLine3d

      public PolyLine3d(List<Point3d> pointList)
      Construct a new PolyLine3d from a List<Point3d>.
      Parameters:
      pointList - the list of points to construct the new PolyLine3d from.
      Throws:
      NullPointerException - when pointList is null, or contains a null value
      IllegalArgumentException - when the provided points do not constitute a valid line (too few points or identical adjacent points)

    • PolyLine3d

      public PolyLine3d(double epsilon, List<Point3d> pointList)
      Construct a new PolyLine3d from a List<Point3d>.
      Parameters:
      epsilon - minimum distance between points to be considered different (these will not be filtered out)
      pointList - the list of points to construct the new PolyLine3d from.
      Throws:
      NullPointerException - when pointList is null, or contains a null value
      IllegalArgumentException - when the provided points do not constitute a valid line (too few points or identical adjacent points)

    • PolyLine3d

      public PolyLine3d(PolyLine3d polyLine)
      Construct a new PolyLine3d from an existing one. This constructor is primarily intended for use in extending classes.
      Parameters:
      polyLine - the existing PolyLine3d.
      Throws:
      NullPointerException - when polyLine is null

  • Method Details

    • 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 - array of points
      getter - function that obtains the intended coordinate
      Returns:
      array of double values filled with the requested coordinate values

    • instantiate

      public PolyLine3d instantiate(double epsilon, List<Point3d> pointList)
      Description copied from interface: PolyLine
      Constructor that can be accessed as a method (used to implement default methods in this interface).
      Specified by:
      instantiate in interface PolyLine<PolyLine3d,Point3d,Ray3d,DirectedPoint3d,LineSegment3d>
      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

    • iteratorToList

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

    • size

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

    • get

      public final Point3d get(int i) throws IndexOutOfBoundsException
      Description copied from interface: PolyLine
      Return one of the points of this line.
      Specified by:
      get in interface PolyLine<PolyLine3d,Point3d,Ray3d,DirectedPoint3d,LineSegment3d>
      Parameters:
      i - the index of the requested point
      Returns:
      the point at the specified index
      Throws:
      IndexOutOfBoundsException - when index < 0, or index ≥ size()

    • getX

      public final double getX(int i) throws IndexOutOfBoundsException
      Description copied from interface: PolyLine
      Return the x-coordinate of a point of this PolyLine.
      Specified by:
      getX in interface PolyLine<PolyLine3d,Point3d,Ray3d,DirectedPoint3d,LineSegment3d>
      Parameters:
      i - 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

      public final double getY(int i) throws IndexOutOfBoundsException
      Description copied from interface: PolyLine
      Return the y-coordinate of a point of this PolyLine.
      Specified by:
      getY in interface PolyLine<PolyLine3d,Point3d,Ray3d,DirectedPoint3d,LineSegment3d>
      Parameters:
      i - 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()

    • getZ

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

    • getSegment

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

    • lengthAtIndex

      public final double lengthAtIndex(int index)
      Description copied from interface: PolyLine
      Access the internal lengthIndexedLine. Return the cumulative length up to point index of this line
      Specified by:
      lengthAtIndex in interface PolyLine<PolyLine3d,Point3d,Ray3d,DirectedPoint3d,LineSegment3d>
      Parameters:
      index - the index
      Returns:
      the cumulative length of this line up to point index

    • getLength

      public double getLength()
      Description copied from interface: PolyLine
      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,DirectedPoint3d,LineSegment3d>
      Returns:
      the length of this line

    • iterator

      public Iterator<Point3d> iterator()
      Specified by:
      iterator in interface Iterable<Point3d>

    • getBounds

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

    • noiseFilteredLine

      public final PolyLine3d noiseFilteredLine(double noiseLevel)
      Description copied from interface: PolyLine
      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,DirectedPoint3d,LineSegment3d>
      Parameters:
      noiseLevel - the minimum segment length that is not removed
      Returns:
      the filtered line

    • concatenate

      public static PolyLine3d concatenate(PolyLine3d... lines)
      Concatenate several PolyLine3d instances.
      Parameters:
      lines - one or more PolyLine3d. The last point of the first <strong>must</strong> match the first of the second, etc.
      Returns:
      PolyLine3d
      Throws:
      NullPointerException - when lines is null, or contains a null value
      IllegalArgumentException - 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)
      Concatenate two PolyLine3d instances. This method is separate for efficiency reasons.
      Parameters:
      tolerance - the tolerance between the end point of a line and the first point of the next line
      line1 - first line
      line2 - second line
      Returns:
      the concatenation of the two lines
      Throws:
      NullPointerException - when line1, or line2 is null
      IllegalArgumentException - when there is a gap between the lines

    • concatenate

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

    • project

      public PolyLine2d project()
      Description copied from interface: Drawable3d
      Project the object onto the z=0 plane.
      Specified by:
      project in interface Drawable3d
      Returns:
      the projected object

    • getLocationExtended

      public final DirectedPoint3d getLocationExtended(double position)
      Description copied from interface: PolyLine
      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,DirectedPoint3d,LineSegment3d>
      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.

    • getLocation

      public final DirectedPoint3d getLocation(double position)
      Description copied from interface: PolyLine
      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,DirectedPoint3d,LineSegment3d>
      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

    • closestPointOnPolyLine

      public Point3d closestPointOnPolyLine(Point3d point)
      Description copied from interface: PolyLine
      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,DirectedPoint3d,LineSegment3d>
      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

    • projectOrthogonal

      public Point3d projectOrthogonal(Point3d point)
      Description copied from interface: Project
      Project a point onto this object. For PolyLines and Polygons, 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 - the point
      Returns:
      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.

    • projectOrthogonalExtended

      public Point3d projectOrthogonalExtended(Point3d point)
      Description copied from interface: Project
      Project a point onto this object. For PolyLines and Polygons, 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 - the point
      Returns:
      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

    • projectOrthogonalFractional

      public final double projectOrthogonalFractional(Point3d point)
      Description copied from interface: Project
      Project a point onto this object. For PolyLines and Polygons, 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, NaN is returned.
      Specified by:
      projectOrthogonalFractional in interface Project<Point3d>
      Parameters:
      point - the point
      Returns:
      the fractional position of the projection of the point (may be NaN if no sensible projection is possible). If the result is not NaN; the result lies somewhere on this object.

    • projectOrthogonalFractionalExtended

      public double projectOrthogonalFractionalExtended(Point3d point)
      Description copied from interface: Project
      Project a point onto this object. For PolyLines and Polygons, 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 - the point
      Returns:
      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.

    • extract

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

    • offsetLine

      public PolyLine3d offsetLine(double offset, double circlePrecision, double offsetMinimumFilterValue, double offsetMaximumFilterValue, double offsetFilterRatio, double minimumOffset)
      Description copied from interface: PolyLine
      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,DirectedPoint3d,LineSegment3d>
      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

    • offsetLine

      public PolyLine3d offsetLine(double[] relativeFractions, double[] offsets, double offsetMinimumFilterValue)
      Description copied from interface: PolyLine
      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.
      Specified by:
      offsetLine in interface PolyLine<PolyLine3d,Point3d,Ray3d,DirectedPoint3d,LineSegment3d>
      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

    • offsetLine

      public PolyLine3d offsetLine(double offsetAtStart, double offsetAtEnd, double circlePrecision, double offsetMinimumFilterValue, double offsetMaximumFilterValue, double offsetFilterRatio, double minimumOffset)
      Description copied from interface: PolyLine
      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,DirectedPoint3d,LineSegment3d>
      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

    • transitionLine

      public PolyLine3d transitionLine(PolyLine3d endLine, PolyLine.TransitionFunction transition)
      Description copied from interface: PolyLine
      Make a transition line from this PolyLine to another PolyLine using a user specified function.
      Specified by:
      transitionLine in interface PolyLine<PolyLine3d,Point3d,Ray3d,DirectedPoint3d,LineSegment3d>
      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

    • truncate

      public PolyLine3d truncate(double position)
      Description copied from interface: PolyLine
      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,DirectedPoint3d,LineSegment3d>
      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

    • toString

      public String toString()
      Description copied from interface: Drawable
      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:
      a string describing the Drawable

    • toString

      public String toString(String doubleFormat, boolean doNotIncludeClassName)
      Description copied from interface: Drawable
      Produce a String describing the Drawable.
      Specified by:
      toString in interface Drawable<Point3d>
      Parameters:
      doubleFormat - a format string (something like "%6.3f") which will be used to render every coordinate value)
      doNotIncludeClassName - 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:
      textual representation of the Drawable

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object