java.lang.Object
- org.djutils.draw.point.Point3d

All Implemented Interfaces:

Serializable, Drawable<Point3d>, Drawable3d, Point<Point3d>

Direct Known Subclasses:

OrientedPoint3d, Ray3d
```
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-2021 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See DJUTILS License.

Author:

Alexander Verbraeck, Peter Knoppers

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type Field Description

double x
The x-coordinate.

double y
The y-coordinate.

double z
The z-coordinate.

Constructor Summary

Constructors
Constructor	Description
`Point3d(double[] xyz)`	Create a new Point with just an x, y and z coordinate, stored with double precision.
`Point3d(double x, double y, double z)`	Create a new Point with just an x, y and z coordinate, stored with double precision.
`Point3d(Point2D point, double z)`	Create an immutable point with just three values, x, y and z, stored with double precision from an AWT Point2D and z.
`Point3d(Point2d point, double z)`	Create an immutable point with just three values, x, y and z, stored with double precision from a Point2d and z.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`Point3d`	`abs()`	Return a new Point with absolute coordinate values.
`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.
`Point3d`	`closestPointOnLine(Point3d linePoint1, Point3d linePoint2)`	Project a point on a line.
`Point3d`	`closestPointOnSegment(double p1X, double p1Y, double p1Z, double p2X, double p2Y, double p2Z)`	Project a point on a line segment.
`Point3d`	`closestPointOnSegment(Point3d segmentPoint1, Point3d segmentPoint2)`	Project a point on a line segment.
`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 other, double epsilon)`	A comparison with another point that returns true 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`	`getBounds()`	Retrieve the bounding box of the object.
`Iterator<? extends Point3d>`	`getPoints()`	Retrieve, or generate all points that make up the object.
`double`	`getX()`	Return the x-coordinate.
`double`	`getY()`	Return the y-coordinate.
`double`	`getZ()`	Return the z-coordinate.
`int`	`hashCode()`
`(package private) double`	`horizontalDirection()`	Return the direction of the point in radians with respect to the origin, ignoring the z-coordinate.
`(package private) double`	`horizontalDirection(Point3d point)`	Return the direction to another point, in radians, ignoring the z-coordinate.
`(package private) double`	`horizontalDistance(Point3d point)`	Return the Euclidean distance between this point and the provided point, ignoring the z-coordinate.
`(package private) double`	`horizontalDistanceSquared(Point3d point)`	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.
`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 Point with a translation by the provided dx and dy.
`Point3d`	`translate(double dx, double dy, double dz)`	Return a new Point3d with a translation by the provided dx, dy and dz.
`(package private) double`	`verticalDirection(Point3d point)`	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
toString, toString

Methods inherited from interface org.djutils.draw.Drawable3d
getDimensions

- Field Detail
  - 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 Detail
  - Point3d
```
public Point3d(double x,
               double y,
               double z)
```
    Create a new Point with just an x, y and z coordinate, stored with double precision.
    
    Parameters:
    
    x - double; the x coordinate
    
    y - double; the y coordinate
    
    z - double; the z coordinate
    
    Throws:
    
    IllegalArgumentException - when x or y is NaN
  - Point3d
```
public Point3d(double[] xyz)
        throws NullPointerException,
               IllegalArgumentException
```
    Create a new Point with just an x, y and z coordinate, stored with double precision.
    
    Parameters:
    
    xyz - double[]; the x, y and z coordinate
    
    Throws:
    
    NullPointerException - when xyz is null
    
    IllegalArgumentException - when the dimension of xyz is not 3, or a coordinate is NaN
  - Point3d
```
public Point3d(Point2d point,
               double z)
        throws NullPointerException,
               IllegalArgumentException
```
    Create an immutable point with just three values, x, y and z, stored with double precision from a Point2d and z.
    
    Parameters:
    
    point - Point2d; a Point2d
    
    z - double; the z coordinate
    
    Throws:
    
    NullPointerException - when point is null
    
    IllegalArgumentException - when z is NaN
  - Point3d
```
public Point3d(Point2D point,
               double z)
        throws NullPointerException,
               IllegalArgumentException
```
    Create an immutable point with just three values, x, y and z, stored with double precision from an AWT Point2D and z.
    
    Parameters:
    
    point - Point2D; an AWT Point2D
    
    z - double; the z coordinate
    
    Throws:
    
    NullPointerException - when point is null
    
    IllegalArgumentException - when point has a NaN coordinate, or z is NaN
- Method Detail
  - getX
```
public final double getX()
```
    Return the x-coordinate. When the point is not in Cartesian space, a calculation to Cartesian space has to be made.
    
    Specified by:
    
    getX in interface Point<Point3d>
    
    Returns:
    
    double; the x-coordinate
  - getY
```
public final double getY()
```
    Return the y-coordinate. When the point is not in Cartesian space, a calculation to Cartesian space has to be made.
    
    Specified by:
    
    getY in interface Point<Point3d>
    
    Returns:
    
    double; the y-coordinate
  - getZ
```
public final double getZ()
```
    Return the z-coordinate.
    
    Returns:
    
    double; the z-coordinate
  - distanceSquared
```
public double distanceSquared(Point3d otherPoint)
                       throws NullPointerException
```
    Return the squared distance between this point and the provided point.
    
    Specified by:
    
    distanceSquared in interface Point<Point3d>
    
    Parameters:
    
    otherPoint - P; the other point
    
    Returns:
    
    double; the squared distance between this point and the other point
    
    Throws:
    
    NullPointerException - when otherPoint is null
  - distance
```
public double distance(Point3d otherPoint)
                throws NullPointerException
```
    Return the distance to another point.
    
    Specified by:
    
    distance in interface Point<Point3d>
    
    Parameters:
    
    otherPoint - P; P the other point
    
    Returns:
    
    double; the distance (2d or 3d as applicable) to the other point
    
    Throws:
    
    NullPointerException
  - 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
  - getPoints
```
public Iterator<? extends 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
  - project
```
public Point2d 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.
  - translate
```
public Point3d translate(double dx,
                         double dy)
                  throws IllegalArgumentException
```
    Return a new Point with a translation by the provided dx and dy.
    
    Parameters:
    
    dx - double; the horizontal translation
    
    dy - double; the vertical translation
    
    Returns:
    
    Point3D; a new point with the translated coordinates
    
    Throws:
    
    IllegalArgumentException - when dx, or dy is NaN
  - translate
```
public Point3d translate(double dx,
                         double dy,
                         double dz)
                  throws IllegalArgumentException
```
    Return a new Point3d with a translation by the provided dx, dy and dz.
    
    Parameters:
    
    dx - double; the x translation
    
    dy - double; the y translation
    
    dz - double; the z translation
    
    Returns:
    
    Point3d; a new point with the translated coordinates
    
    Throws:
    
    IllegalArgumentException - when dx, dy, or dz is NaN
  - scale
```
public Point3d scale(double factor)
              throws IllegalArgumentException
```
    Return a new Point with the coordinates of this point scaled by the provided factor.
    
    Specified by:
    
    scale in interface Point<Point3d>
    
    Parameters:
    
    factor - double; the scale factor
    
    Returns:
    
    Point; a new point with the coordinates of this point scaled by the provided factor
    
    Throws:
    
    IllegalArgumentException - when factor is NaN
  - neg
```
public Point3d neg()
```
    Return a new Point with negated coordinate values.
    
    Specified by:
    
    neg in interface Point<Point3d>
    
    Returns:
    
    Point; a new point with negated coordinate values
  - abs
```
public Point3d abs()
```
    Return a new Point with absolute coordinate values.
    
    Specified by:
    
    abs in interface Point<Point3d>
    
    Returns:
    
    Point; a new point with absolute coordinate values
  - normalize
```
public Point3d normalize()
                  throws DrawRuntimeException
```
    Return a new Point with a distance of 1 to the origin.
    
    Specified by:
    
    normalize in interface Point<Point3d>
    
    Returns:
    
    Point; the normalized point
    
    Throws:
    
    DrawRuntimeException - when point is the origin, and no length can be established for scaling
  - interpolate
```
public Point3d interpolate(Point3d point,
                           double fraction)
```
    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 - P; the other point
    
    fraction - double; 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:
    
    P; the point that is fraction away on the line between this point and the other point
  - epsilonEquals
```
public boolean epsilonEquals(Point3d other,
                             double epsilon)
```
    A comparison with another point that returns true of each of the coordinates is less than epsilon apart.
    
    Specified by:
    
    epsilonEquals in interface Point<Point3d>
    
    Parameters:
    
    other - P; the point to compare with
    
    epsilon - double; 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
  - 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
  - closestPointOnSegment
```
public final Point3d closestPointOnSegment(Point3d segmentPoint1,
                                           Point3d segmentPoint2)
```
    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 - P; start of line segment
    
    segmentPoint2 - P; end of line segment
    
    Returns:
    
    P; 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)
                           throws DrawRuntimeException
```
    Compute the closest point on a line with optional limiting of the result on either end.
    
    Parameters:
    
    p1X - double; the x coordinate of the first point on the line
    
    p1Y - double; the y coordinate of the first point on the line
    
    p1Z - double; the z coordinate of the first point on the line
    
    p2X - double; the x coordinate of the second point on the line
    
    p2Y - double; the y coordinate of the second point on the line
    
    p2Z - double; the z coordinate of the second point on the line
    
    lowLimitHandling - Boolean; 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 - Boolean; 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:
    
    Point3d; the closest point on the line after applying the indicated limit handling; so the result can be null
    
    Throws:
    
    DrawRuntimeException - 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)
                                throws DrawRuntimeException
```
    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 - double; the x coordinate of the first point on the line
    
    p1Y - double; the y coordinate of the first point on the line
    
    p1Z - double; the z coordinate of the first point on the line
    
    p2X - double; the x coordinate of the second point on the line
    
    p2Y - double; the y coordinate of the second point on the line
    
    p2Z - double; the z coordinate of the second point on the line
    
    lowLimitHandling - Boolean; 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 - Boolean; 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:
    
    double; 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:
    
    DrawRuntimeException - when any of the arguments is NaN
  - closestPointOnSegment
```
public final Point3d closestPointOnSegment(double p1X,
                                           double p1Y,
                                           double p1Z,
                                           double p2X,
                                           double p2Y,
                                           double p2Z)
                                    throws DrawRuntimeException
```
    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 - double; the x coordinate of the start point of the line segment
    
    p1Y - double; the y coordinate of the start point of the line segment
    
    p1Z - double; the z coordinate of the start point of the line segment
    
    p2X - double; the x coordinate of the end point of the line segment
    
    p2Y - double; the y coordinate of the end point of the line segment
    
    p2Z - double; the y coordinate of the end point of the line segment
    
    Returns:
    
    P; either segmentPoint1, or segmentPoint2 or a new Point2d that lies somewhere in between those two.
    
    Throws:
    
    DrawRuntimeException - when any of the parameters is NaN
  - closestPointOnLine
```
public final Point3d closestPointOnLine(Point3d linePoint1,
                                        Point3d linePoint2)
                                 throws NullPointerException,
                                        DrawRuntimeException
```
    Project a point on a line.
    Adapted from example code provided by Paul Bourke.
    
    Specified by:
    
    closestPointOnLine in interface Point<Point3d>
    
    Parameters:
    
    linePoint1 - P; point on the line
    
    linePoint2 - P; another point on the line
    
    Returns:
    
    Point2d; a point on the line that goes through linePoint1 and linePoint2
    
    Throws:
    
    NullPointerException - when linePoint1 is null, or linePoint2 is null
    
    DrawRuntimeException - when linePoint1 is at the same location as linePoint2
  - closestPointOnLine
```
public final Point3d closestPointOnLine(double p1X,
                                        double p1Y,
                                        double p1Z,
                                        double p2X,
                                        double p2Y,
                                        double p2Z)
                                 throws DrawRuntimeException
```
    Project a point on a line.
    Adapted from example code provided by Paul Bourke.
    
    Parameters:
    
    p1X - double; the x coordinate of a point of the line
    
    p1Y - double; the y coordinate of a point of the line
    
    p1Z - double; the z coordinate of a point on the line
    
    p2X - double; the x coordinate of another point on the line
    
    p2Y - double; the y coordinate of another point on the line
    
    p2Z - double; the z coordinate of another point on the line
    
    Returns:
    
    Point3d; a point on the line that goes through the points
    
    Throws:
    
    DrawRuntimeException - 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:
    
    double; 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 point)
                          throws NullPointerException
```
    Return the direction to another point, in radians, ignoring the z-coordinate.
    
    Parameters:
    
    point - Point3d; the other point
    
    Returns:
    
    double; the direction of the projection of the point in the x-y plane to another point, in radians
    
    Throws:
    
    NullPointerException - when point is null
  - verticalDirection
```
final double verticalDirection(Point3d point)
                        throws NullPointerException
```
    Return the direction with respect to the Z axis to another point, in radians.
    
    Parameters:
    
    point - Point3d; the other point
    
    Returns:
    
    double; the direction with respect to the Z axis to another point, in radians
    
    Throws:
    
    NullPointerException - when point is null
  - horizontalDistanceSquared
```
final double horizontalDistanceSquared(Point3d point)
```
    Return the squared distance between the coordinates of this point and the provided point, ignoring the z-coordinate.
    
    Parameters:
    
    point - Point3d; the other point
    
    Returns:
    
    double; the squared distance between this point and the other point, ignoring the z-coordinate
    
    Throws:
    
    NullPointerException - when point is null
  - horizontalDistance
```
final double horizontalDistance(Point3d point)
```
    Return the Euclidean distance between this point and the provided point, ignoring the z-coordinate.
    
    Parameters:
    
    point - Point3d; the other point
    
    Returns:
    
    double; the Euclidean distance between this point and the other point, ignoring the z-coordinate
    
    Throws:
    
    NullPointerException - when point is null
  - 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
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object

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

Class Point3d

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.djutils.draw.Drawable

Methods inherited from interface org.djutils.draw.Drawable3d

Field Detail

x

y

z

Constructor Detail

Point3d

Point3d

Point3d

Point3d

Method Detail

getX

getY

getZ

distanceSquared

distance

size

getPoints

project

translate

translate

scale

neg

abs

normalize

interpolate

epsilonEquals

getBounds

closestPointOnSegment

closestPointOnLine

fractionalPositionOnLine

closestPointOnSegment

closestPointOnLine

closestPointOnLine

horizontalDirection

horizontalDirection

verticalDirection

horizontalDistanceSquared

horizontalDistance

toString

toString

hashCode

equals