Package org.djutils.draw.point

Class Point3d

java.lang.Object
org.djutils.draw.point.Point3d
All Implemented Interfaces:
Iterable<Point3d>, Drawable<Point3d>, Drawable3d, Point<Point3d>
Direct Known Subclasses:
DirectedPoint3d
public class Point3d extends Object implements Drawable3d, Point<Point3d>
A Point3d is an immutable point with an x, y, and z coordinate, stored with double precision. It differs from many Point implementations by being immutable.

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

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final double
    x
    The x-coordinate.
    final double
    y
    The y-coordinate.
    final double
    z
    The z-coordinate.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Point3d(double[] xyz)
    Create a new Point3d from x, y and z coordinates provided as values in a double array.
    Point3d(double x, double y, double z)
    Create a new Point from x, y and z coordinates provided as double arguments.
    Point3d(Point2D point, double z)
    Create an immutable point from x, y obtained from a AWT Point2D and double z.
    Point3d(Point2d point, double z)
    Create a new Point3d from x, y stored in a java.awt.geom.Point2D and double z.

  • Method Summary

    Modifier and Type
    Method
    Description
    Point3d
    abs()
    Return a new Point with absolute coordinate values.
    final Point3d
    closestPointOnLine(double p1X, double p1Y, double p1Z, double p2X, double p2Y, double p2Z)
    Project a point on a line.
    Point3d
    closestPointOnLine(double p1X, double p1Y, double p1Z, double p2X, double p2Y, double p2Z, Boolean lowLimitHandling, Boolean highLimitHandling)
    Compute the closest point on a line with optional limiting of the result on either end.
    final Point3d
    closestPointOnLine(Point3d linePoint1, Point3d linePoint2)
    Project a point on a line.
    final Point3d
    closestPointOnSegment(double p1X, double p1Y, double p1Z, double p2X, double p2Y, double p2Z)
    Project a point on a line segment.
    final Point3d
    closestPointOnSegment(Point3d segmentPoint1, Point3d segmentPoint2)
    Project a point on a line segment.
    Direction3d
    directionTo(Point3d otherPoint)
    Return the direction to another Point3d.
    double
    distance(Point3d otherPoint)
    Return the distance to another point.
    double
    distanceSquared(Point3d otherPoint)
    Return the squared distance between this point and the provided point.
    boolean
    epsilonEquals(Point3d otherPoint, double epsilon)
    A comparison with another point that returnstrue of each of the coordinates is less than epsilon apart.
    boolean
    equals(Object obj)
     
    double
    fractionalPositionOnLine(double p1X, double p1Y, double p1Z, double p2X, double p2Y, double p2Z, Boolean lowLimitHandling, Boolean highLimitHandling)
    Compute the fractional position of the closest point on a line with optional limiting of the result on either end.
    Bounds3d
    getAbsoluteBounds()
    Retrieve the bounding box of the object in absolute coordinates.
    final double
    getX()
    Return the x-coordinate.
    final double
    getY()
    Return the y-coordinate.
    final double
    getZ()
    Return the z-coordinate.
    int
    hashCode()
     
    (package private) final double
    horizontalDirection()
    Return the direction of the point in radians with respect to the origin, ignoring the z-coordinate.
    (package private) final double
    horizontalDirection(Point3d otherPoint)
    Return the direction to another point, in radians, ignoring the z-coordinate.
    (package private) final double
    horizontalDistance(Point3d otherPoint)
    Return the Euclidean distance between this point and the provided point, ignoring the z-coordinate.
    (package private) final double
    horizontalDistanceSquared(Point3d otherPoint)
    Return the squared distance between the coordinates of this point and the provided point, ignoring the z-coordinate.
    Point3d
    interpolate(Point3d point, double fraction)
    Interpolate towards another Point with a fraction.
    Iterator<Point3d>
    iterator()
     
    Point3d
    neg()
    Return a new Point with negated coordinate values.
    Point3d
    normalize()
    Return a new Point with a distance of 1 to the origin.
    Point2d
    project()
    Project the object onto the z=0 plane.
    Point3d
    scale(double factor)
    Return a new Point with the coordinates of this point scaled by the provided factor.
    int
    size()
    Retrieve the number of points that make up the object.
    String
    toString()
    Produce a string describing the Drawable using default conversion for the (double) coordinate values.
    String
    toString(String doubleFormat, boolean doNotIncludeClassName)
    Produce a String describing the Drawable.
    Point3d
    translate(double dX, double dY)
    Return a new Point3d with a translation by the provided dX and dY and preserved z value.
    Point3d
    translate(double dX, double dY, double dZ)
    Return a new Point3d with a translation by the provided dx, dy and dz.
    (package private) final double
    verticalDirection(Point3d otherPoint)
    Return the direction with respect to the Z axis to another point, in radians.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    Methods inherited from interface org.djutils.draw.Drawable

    getPointList, toString, toString

    Methods inherited from interface org.djutils.draw.Drawable3d

    getDimensions

    Methods inherited from interface java.lang.Iterable

    forEach, spliterator

  • Field Details

    • x

      public final double x
      The x-coordinate.

    • y

      public final double y
      The y-coordinate.

    • z

      public final double z
      The z-coordinate.

  • Constructor Details

    • Point3d

      public Point3d(double x, double y, double z)
      Create a new Point from x, y and z coordinates provided as double arguments.
      Parameters:
      x - the x coordinate
      y - the y coordinate
      z - the z coordinate
      Throws:
      ArithmeticException - when x or y or z is NaN

    • Point3d

      public Point3d(double[] xyz) throws NullPointerException, IllegalArgumentException
      Create a new Point3d from x, y and z coordinates provided as values in a double array.
      Parameters:
      xyz - the x, y and z coordinates
      Throws:
      NullPointerException - when xyz is null
      IllegalArgumentException - when the length of xyz is not 3
      ArithmeticException - when xyz contains a NaN value

    • Point3d

      public Point3d(Point2d point, double z)
      Create a new Point3d from x, y stored in a java.awt.geom.Point2D and double z.
      Parameters:
      point - a java.awt.geom.Point2D
      z - the z coordinate
      Throws:
      NullPointerException - when point is null
      ArithmeticException - when z is NaN

    • Point3d

      public Point3d(Point2D point, double z)
      Create an immutable point from x, y obtained from a AWT Point2D and double z.
      Parameters:
      point - a java.awt.geom.Point2D
      z - the z coordinate
      Throws:
      NullPointerException - when point is null
      ArithmeticException - when point has a NaN coordinate, or z is NaN

  • Method Details

    • getX

      public final double getX()
      Description copied from interface: Point
      Return the x-coordinate.
      Specified by:
      getX in interface Point<Point3d>
      Returns:
      the x-coordinate

    • getY

      public final double getY()
      Description copied from interface: Point
      Return the y-coordinate.
      Specified by:
      getY in interface Point<Point3d>
      Returns:
      the y-coordinate

    • getZ

      public final double getZ()
      Return the z-coordinate.
      Returns:
      the z-coordinate

    • distanceSquared

      public double distanceSquared(Point3d otherPoint) throws NullPointerException
      Description copied from interface: Point
      Return the squared distance between this point and the provided point.
      Specified by:
      distanceSquared in interface Point<Point3d>
      Parameters:
      otherPoint - the other point
      Returns:
      the squared distance between this point and the other point
      Throws:
      NullPointerException - when otherPoint is null

    • distance

      public double distance(Point3d otherPoint) throws NullPointerException
      Description copied from interface: Point
      Return the distance to another point.
      Specified by:
      distance in interface Point<Point3d>
      Parameters:
      otherPoint - P the other point
      Returns:
      the distance (2d or 3d as applicable) to the other point
      Throws:
      NullPointerException

    • 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

    • iterator

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

    • project

      public Point2d project() throws InvalidProjectionException
      Description copied from interface: Drawable3d
      Project the object onto the z=0 plane.
      Specified by:
      project in interface Drawable3d
      Returns:
      the projected object
      Throws:
      InvalidProjectionException - 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.

    • translate

      public Point3d translate(double dX, double dY) throws ArithmeticException
      Return a new Point3d with a translation by the provided dX and dY and preserved z value.
      Parameters:
      dX - the x translation
      dY - the y translation
      Returns:
      a new point with the translated coordinates and the same z value
      Throws:
      ArithmeticException - when dX, or dY is NaN

    • translate

      public Point3d translate(double dX, double dY, double dZ)
      Return a new Point3d with a translation by the provided dx, dy and dz.
      Parameters:
      dX - the x translation
      dY - the y translation
      dZ - the z translation
      Returns:
      a new point with the translated coordinates
      Throws:
      ArithmeticException - when dX, dY, or dZ is NaN

    • scale

      public Point3d scale(double factor)
      Description copied from interface: Point
      Return a new Point with the coordinates of this point scaled by the provided factor.
      Specified by:
      scale in interface Point<Point3d>
      Parameters:
      factor - the scale factor
      Returns:
      a new point with the coordinates of this point scaled by the provided factor

    • neg

      public Point3d neg()
      Description copied from interface: Point
      Return a new Point with negated coordinate values. If this is a DirectedPoint, dirY (in case this is a DirectedPoint3d and dirZ are negated.
      Specified by:
      neg in interface Point<Point3d>
      Returns:
      a new point with negated coordinate values

    • abs

      public Point3d abs()
      Description copied from interface: Point
      Return a new Point with absolute coordinate values. If this is a DirectedPoint, dirY (in case this is a DirectedPoint3d and dirZ are copied unchanged.
      Specified by:
      abs in interface Point<Point3d>
      Returns:
      a new point with absolute coordinate values

    • normalize

      public Point3d normalize() throws IllegalArgumentException
      Description copied from interface: Point
      Return a new Point with a distance of 1 to the origin.
      Specified by:
      normalize in interface Point<Point3d>
      Returns:
      the normalized point
      Throws:
      IllegalArgumentException - when point is the origin, and no length can be established for scaling

    • interpolate

      public Point3d interpolate(Point3d point, double fraction)
      Description copied from interface: Point
      Interpolate towards another Point with a fraction. It is allowed for fraction to be less than zero or larger than 1. In that case the interpolation turns into an extrapolation.
      Specified by:
      interpolate in interface Point<Point3d>
      Parameters:
      point - the other point
      fraction - the factor for interpolation towards the other point. When <code>fraction</code> is between 0 and 1, it is an interpolation, otherwise an extrapolation. If fraction is 0; this Point is returned; if fraction is 1, the other point is returned
      Returns:
      the point that is fraction away on the line between this point and the other point

    • epsilonEquals

      public boolean epsilonEquals(Point3d otherPoint, double epsilon)
      Description copied from interface: Point
      A comparison with another point that returnstrue of each of the coordinates is less than epsilon apart.
      Specified by:
      epsilonEquals in interface Point<Point3d>
      Parameters:
      otherPoint - the point to compare with
      epsilon - the upper bound of difference for one of the coordinates
      Returns:
      boolean;true if both x, y and z (if a Point3d) are less than epsilon apart, otherwise false

    • getAbsoluteBounds

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

    • directionTo

      public Direction3d directionTo(Point3d otherPoint)
      Return the direction to another Point3d.
      Parameters:
      otherPoint - the other point
      Returns:
      the direction to the other point in Radians (towards infinite X is 0; towards infinite Y is π / 2; etc.). If the points are identical; this method returns NaN.

    • closestPointOnSegment

      public final Point3d closestPointOnSegment(Point3d segmentPoint1, Point3d segmentPoint2)
      Description copied from interface: Point
      Project a point on a line segment. If the the projected points lies outside the line segment, the nearest end point of the line segment is returned. Otherwise the returned point lies between the end points of the line segment.
      Adapted from example code provided by Paul Bourke.
      Specified by:
      closestPointOnSegment in interface Point<Point3d>
      Parameters:
      segmentPoint1 - start of line segment
      segmentPoint2 - end of line segment
      Returns:
      either segmentPoint1, or segmentPoint2 or a new Point2d that lies somewhere in between those two.

    • closestPointOnLine

      public Point3d closestPointOnLine(double p1X, double p1Y, double p1Z, double p2X, double p2Y, double p2Z, Boolean lowLimitHandling, Boolean highLimitHandling)
      Compute the closest point on a line with optional limiting of the result on either end.
      Parameters:
      p1X - the x coordinate of the first point on the line
      p1Y - the y coordinate of the first point on the line
      p1Z - the z coordinate of the first point on the line
      p2X - the x coordinate of the second point on the line
      p2Y - the y coordinate of the second point on the line
      p2Z - the z coordinate of the second point on the line
      lowLimitHandling - controls handling of results that lie before the first point of the line. If null; this method returns null; else if true; this method returns (p1X,p1Y); else (lowLimitHandling is false); this method will return the closest point on the line
      highLimitHandling - controls the handling of results that lie beyond the second point of the line. If null; this method returns null; else if true; this method returns (p2X,p2Y); else (highLimitHandling is false); this method will return the closest point on the line
      Returns:
      the closest point on the line after applying the indicated limit handling; so the result can be null
      Throws:
      ArithmeticException - when any of the arguments is NaN

    • fractionalPositionOnLine

      public double fractionalPositionOnLine(double p1X, double p1Y, double p1Z, double p2X, double p2Y, double p2Z, Boolean lowLimitHandling, Boolean highLimitHandling)
      Compute the fractional position of the closest point on a line with optional limiting of the result on either end. If the line has length 0; this method returns 0.0.
      Parameters:
      p1X - the x coordinate of the first point on the line
      p1Y - the y coordinate of the first point on the line
      p1Z - the z coordinate of the first point on the line
      p2X - the x coordinate of the second point on the line
      p2Y - the y coordinate of the second point on the line
      p2Z - the z coordinate of the second point on the line
      lowLimitHandling - controls handling of results that lie before the first point of the line. If null; this method returns NaN; else if true; this method returns 0.0; else (lowLimitHandling is false); this results < 0.0 are returned
      highLimitHandling - controls the handling of results that lie beyond the second point of the line. If null; this method returns NaN; else if true; this method returns 1.0; else (highLimitHandling is false); results > 1.0 are returned
      Returns:
      the fractional position of the closest point on the line. Results within the range 0.0 .. 1.0 are always returned as is.. A result < 0.0 is subject to lowLimitHandling. A result > 1.0 is subject to highLimitHandling
      Throws:
      IllegalArgumentException - when any of the arguments is NaN

    • closestPointOnSegment

      public final Point3d closestPointOnSegment(double p1X, double p1Y, double p1Z, double p2X, double p2Y, double p2Z)
      Project a point on a line segment. If the the projected points lies outside the line segment, the nearest end point of the line segment is returned. Otherwise the returned point lies between the end points of the line segment.
      Adapted from example code provided by Paul Bourke.
      Parameters:
      p1X - the x coordinate of the start point of the line segment
      p1Y - the y coordinate of the start point of the line segment
      p1Z - the z coordinate of the start point of the line segment
      p2X - the x coordinate of the end point of the line segment
      p2Y - the y coordinate of the end point of the line segment
      p2Z - the y coordinate of the end point of the line segment
      Returns:
      either segmentPoint1, or segmentPoint2 or a new Point2d that lies somewhere in between those two.
      Throws:
      ArithmeticException - when any of the parameters is NaN

    • closestPointOnLine

      public final Point3d closestPointOnLine(Point3d linePoint1, Point3d linePoint2)
      Description copied from interface: Point
      Project a point on a line.
      Adapted from example code provided by Paul Bourke.
      Specified by:
      closestPointOnLine in interface Point<Point3d>
      Parameters:
      linePoint1 - point on the line
      linePoint2 - another point on the line
      Returns:
      a point on the line that goes through linePoint1 and linePoint2

    • closestPointOnLine

      public final Point3d closestPointOnLine(double p1X, double p1Y, double p1Z, double p2X, double p2Y, double p2Z)
      Project a point on a line.
      Adapted from example code provided by Paul Bourke.
      Parameters:
      p1X - the x coordinate of a point of the line
      p1Y - the y coordinate of a point of the line
      p1Z - the z coordinate of a point on the line
      p2X - the x coordinate of another point on the line
      p2Y - the y coordinate of another point on the line
      p2Z - the z coordinate of another point on the line
      Returns:
      a point on the line that goes through the points
      Throws:
      IllegalArgumentException - when the points on the line are identical

    • horizontalDirection

      final double horizontalDirection()
      Return the direction of the point in radians with respect to the origin, ignoring the z-coordinate.
      Returns:
      the direction of the projection of the point in the x-y plane with respect to the origin, in radians

    • horizontalDirection

      final double horizontalDirection(Point3d otherPoint)
      Return the direction to another point, in radians, ignoring the z-coordinate.
      Parameters:
      otherPoint - the other point
      Returns:
      the direction of the projection of the point in the x-y plane to another point, in radians
      Throws:
      NullPointerException - when otherPoint is null

    • verticalDirection

      final double verticalDirection(Point3d otherPoint)
      Return the direction with respect to the Z axis to another point, in radians.
      Parameters:
      otherPoint - the other point
      Returns:
      the direction with respect to the Z axis to another point, in radians
      Throws:
      NullPointerException - when otherPoint is null

    • horizontalDistanceSquared

      final double horizontalDistanceSquared(Point3d otherPoint)
      Return the squared distance between the coordinates of this point and the provided point, ignoring the z-coordinate.
      Parameters:
      otherPoint - the other point
      Returns:
      the squared distance between this point and the other point, ignoring the z-coordinate
      Throws:
      NullPointerException - when otherPoint is null

    • horizontalDistance

      final double horizontalDistance(Point3d otherPoint)
      Return the Euclidean distance between this point and the provided point, ignoring the z-coordinate.
      Parameters:
      otherPoint - the other point
      Returns:
      the Euclidean distance between this point and the other point, ignoring the z-coordinate
      Throws:
      NullPointerException - when otherPoint is null

    • 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