Package org.djutils.draw.point

Class Point2d

java.lang.Object

org.djutils.draw.point.Point2d

All Implemented Interfaces:

Serializable, Iterable<Point2d>, Drawable<Point2d>, Drawable2d, Point<Point2d>

Direct Known Subclasses:

DirectedPoint2d

public class Point2d
extends Object
implements Drawable2d, Point<Point2d>

A Point2d is an immutable Point with an x and y 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

See Also:

• Serialized Form

Field Summary

Fields

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

Constructor Summary

Constructors

Constructor	Description
Point2d(double[] xy)	Create a new Point2d from a x and y coordinates provided as values in a double array.
Point2d(double x, double y)	Create a new Point2d from x and y coordinates provided as double arguments.
Point2d(Point2D point)	Create an new Point2d from x and y obtained from a java.awt.geom.Point2D.

Method Summary

Modifier and Type	Method	Description
Point2d	abs()	Return a new Point with absolute coordinate values.
static final List<Point2d>	circleIntersections(Point2d center1, double radius1, Point2d center2, double radius2)	Return the zero, one or two intersections between two circles.
final Point2d	closestPointOnLine(double p1X, double p1Y, double p2X, double p2Y)	Project a point on a line.
Point2d	closestPointOnLine(double p1X, double p1Y, double p2X, double p2Y, Boolean lowLimitHandling, Boolean highLimitHandling)	Compute the closest point on a line with optional limiting of the result on either end.
Point2d	closestPointOnLine(Point2d linePoint1, Point2d linePoint2)	Project a point on a line.
final Point2d	closestPointOnSegment(double p1X, double p1Y, double p2X, double p2Y)	Project a point on a line segment.
Point2d	closestPointOnSegment(Point2d segmentPoint1, Point2d segmentPoint2)	Project a point on a line segment.
double	directionTo(Point2d otherPoint)	Return the direction to another Point2d.
double	distance(Point2d otherPoint)	Return the distance to another point.
double	distanceSquared(Point2d otherPoint)	Return the squared distance between this point and the provided point.
boolean	epsilonEquals(Point2d 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 p2X, double p2Y, Boolean lowLimitHandling, Boolean highLimitHandling)	Compute the fractional position of the closest point on a line with optional limiting of the result on either end.
Bounds2d	getBounds()	Retrieve the bounding rectangle of the object.
final double	getX()	Return the x-coordinate.
final double	getY()	Return the y-coordinate.
int	hashCode()
Point2d	interpolate(Point2d otherPoint, double fraction)	Interpolate towards another Point with a fraction.
static Point2d	intersectionOfLines(double line1P1X, double line1P1Y, double line1P2X, double line1P2Y, boolean lowLimitLine1, boolean highLimitLine1, double line2P1X, double line2P1Y, double line2P2X, double line2P2Y, boolean lowLimitLine2, boolean highLimitLine2)	Compute the 2D intersection of two lines.
static Point2d	intersectionOfLines(double l1P1X, double l1P1Y, double l1P2X, double l1P2Y, double l2P1X, double l2P1Y, double l2P2X, double l2P2Y)	Compute the 2D intersection of two lines.
static Point2d	intersectionOfLines(Point2d line1P1, Point2d line1P2, Point2d line2P1, Point2d line2P2)	Compute the 2D intersection of two lines.
static Point2d	intersectionOfLineSegments(double line1P1X, double line1P1Y, double line1P2X, double line1P2Y, double line2P1X, double line2P1Y, double line2P2X, double line2P2Y)	Compute the 2D intersection of two line segments.
static Point2d	intersectionOfLineSegments(LineSegment2d segment1, LineSegment2d segment2)	Compute the 2D intersection of two line segments.
static Point2d	intersectionOfLineSegments(Point2d line1P1, Point2d line1P2, Point2d line2P1, Point2d line2P2)	Compute the 2D intersection of two line segments.
Iterator<Point2d>	iterator()
Point2d	neg()	Return a new Point with negated coordinate values.
Point2d	normalize()	Return a new Point with a distance of 1 to the origin.
Point2d	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.
Point2D	toPoint2D()	Return the coordinates as a java.awt.geom.Point2D.Double 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.
Point2d	translate(double dX, double dY)	Return a new Point2d 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.

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.Drawable2d

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.

Constructor Details

Point2d

public Point2d(double x,
 double y)

Create a new Point2d from x and y coordinates provided as double arguments.

Parameters:

x - the x coordinate

y - the y coordinate

Throws:

IllegalArgumentException - when x, or y is NaN

Point2d

public Point2d(double[] xy)

Create a new Point2d from a x and y coordinates provided as values in a double array.

Parameters:

xy - the x and y coordinates

Throws:

NullPointerException - when xy is null

IllegalArgumentException - when the length of xy is not 2

ArithmeticException - when xy contains a NaN value

Point2d

public Point2d(Point2D point)
        throws NullPointerException,
IllegalArgumentException

Create an new Point2d from x and y obtained from a java.awt.geom.Point2D.

Parameters:

point - a java.awt.geom.Point2D

Throws:

NullPointerException - when point is null

IllegalArgumentException - when point has a NaN coordinate

Method Details

getX

public final double getX()

Description copied from interface: Point

Return the x-coordinate.

Specified by:

getX in interface Point<Point2d>

Returns:

the x-coordinate

getY

public final double getY()

Description copied from interface: Point

Return the y-coordinate.

Specified by:

getY in interface Point<Point2d>

Returns:

the y-coordinate

distance

public double distance(Point2d otherPoint)

Description copied from interface: Point

Return the distance to another point.

Specified by:

distance in interface Point<Point2d>

Parameters:

otherPoint - P the other point

Returns:

the distance (2d or 3d as applicable) to the other point

distanceSquared

public double distanceSquared(Point2d 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<Point2d>

Parameters:

otherPoint - the other point

Returns:

the squared distance between this point and the other point

Throws:

NullPointerException - when otherPoint 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<Point2d>

Returns:

the number of points that make up the object

iterator

public Iterator<Point2d> iterator()

Specified by:

iterator in interface Iterable<Point2d>

translate

public Point2d translate(double dX,
 double dY)

Return a new Point2d with a translation by the provided dx and dy.

Parameters:

dX - the x translation

dY - the y translation

Returns:

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)

Return a new Point3d with a translation by the provided dx, dy and dz. If this is an OrientedPoint2d, then the result is an OrientedPoint3d with rotX copied from this and rotY and rotZ are set to 0.0.

Parameters:

dX - the x translation

dY - the y translation

dZ - the z translation

Returns:

a new point with the translated coordinates

Throws:

IllegalArgumentException - when dX, dY, or dZ is NaN

scale

public Point2d 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<Point2d>

Parameters:

factor - the scale factor

Returns:

a new point with the coordinates of this point scaled by the provided factor

neg

public Point2d 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<Point2d>

Returns:

a new point with negated coordinate values

abs

public Point2d 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<Point2d>

Returns:

a new point with absolute coordinate values

normalize

public Point2d normalize()
                  throws DrawRuntimeException

Description copied from interface: Point

Return a new Point with a distance of 1 to the origin.

Specified by:

normalize in interface Point<Point2d>

Returns:

the normalized point

Throws:

DrawRuntimeException - when point is the origin, and no length can be established for scaling

interpolate

public Point2d interpolate(Point2d otherPoint,
 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<Point2d>

Parameters:

otherPoint - 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(Point2d 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<Point2d>

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

getBounds

public Bounds2d getBounds()

Description copied from interface: Drawable2d

Retrieve the bounding rectangle of the object.

Specified by:

getBounds in interface Drawable2d

Returns:

the bounding box of the object

intersectionOfLines

public static Point2d intersectionOfLines(double line1P1X,
 double line1P1Y,
 double line1P2X,
 double line1P2Y,
 boolean lowLimitLine1,
 boolean highLimitLine1,
 double line2P1X,
 double line2P1Y,
 double line2P2X,
 double line2P2Y,
 boolean lowLimitLine2,
 boolean highLimitLine2)

Compute the 2D intersection of two lines. Both lines are defined by two points (that should be distinct).

Parameters:

line1P1X - x-coordinate of start point of line 1

line1P1Y - y-coordinate of start point of line 1

line1P2X - x-coordinate of end point of line 1

line1P2Y - y-coordinate of end point of line 1

lowLimitLine1 - iftrue; the intersection may not lie before the start point of line 1

highLimitLine1 - iftrue; the intersection may not lie beyond the end point of line 1

line2P1X - x-coordinate of start point of line 2

line2P1Y - y-coordinate of start point of line 2

line2P2X - x-coordinate of end point of line 2

line2P2Y - y-coordinate of end point of line 2

lowLimitLine2 - iftrue; the intersection may not lie before the start point of line 2

highLimitLine2 - iftrue; the intersection may not lie beyond the end point of line 2

Returns:

the intersection of the two lines, or null if the lines are (almost) parallel, or the intersection point lies outside the permitted range

Throws:

ArithmeticException - when any of the parameters is NaN

intersectionOfLines

public static Point2d intersectionOfLines(double l1P1X,
 double l1P1Y,
 double l1P2X,
 double l1P2Y,
 double l2P1X,
 double l2P1Y,
 double l2P2X,
 double l2P2Y)

Compute the 2D intersection of two lines. Both lines are defined by two points (that should be distinct). The lines are considered to be infinitely long; so unless the lines are parallel; there is an intersection.

Parameters:

l1P1X - x-coordinate of start point of line segment 1

l1P1Y - y-coordinate of start point of line segment 1

l1P2X - x-coordinate of end point of line segment 1

l1P2Y - y-coordinate of end point of line segment 1

l2P1X - x-coordinate of start point of line segment 2

l2P1Y - y-coordinate of start point of line segment 2

l2P2X - x-coordinate of end point of line segment 2

l2P2Y - y-coordinate of end point of line segment 2

Returns:

the intersection of the two lines, or null if the lines are (almost) parallel

Throws:

ArithmeticException - when any of the parameters is NaN

intersectionOfLines

public static Point2d intersectionOfLines(Point2d line1P1,
 Point2d line1P2,
 Point2d line2P1,
 Point2d line2P2)

Compute the 2D intersection of two lines. Both lines are defined by two points (that should be distinct). The lines are considered to be infinitely long; so unless the lines are parallel; there is an intersection.

Parameters:

line1P1 - first point of line 1

line1P2 - second point of line 1

line2P1 - first point of line 2

line2P2 - second point of line 2

Returns:

the intersection of the two lines, or null if the lines are (almost) parallel

Throws:

NullPointerException - when any of the points is null

intersectionOfLineSegments

public static Point2d intersectionOfLineSegments(Point2d line1P1,
 Point2d line1P2,
 Point2d line2P1,
 Point2d line2P2)

Compute the 2D intersection of two line segments. Both line segments are defined by two points (that should be distinct).

Parameters:

line1P1 - first point of line segment 1

line1P2 - second point of line segment 1

line2P1 - first point of line segment 2

line2P2 - second point of line segment 2

Returns:

the intersection of the two line segments, or null if the lines are parallel (within rounding error), or do not intersect

Throws:

NullPointerException - when any of the points is null

DrawRuntimeException - when any of the line segments is ill-defined (begin point equals end point), or the two line segments are parallel or overlapping

intersectionOfLineSegments

public static Point2d intersectionOfLineSegments(double line1P1X,
 double line1P1Y,
 double line1P2X,
 double line1P2Y,
 double line2P1X,
 double line2P1Y,
 double line2P2X,
 double line2P2Y)

Compute the 2D intersection of two line segments. Both line segments are defined by two points (that should be distinct).

Parameters:

line1P1X - x coordinate of start point of first line segment

line1P1Y - y coordinate of start point of first line segment

line1P2X - x coordinate of end point of first line segment

line1P2Y - y coordinate of end point of first line segment

line2P1X - x coordinate of start point of second line segment

line2P1Y - y coordinate of start point of second line segment

line2P2X - x coordinate of end point of second line segment

line2P2Y - y coordinate of end point of second line segment

Returns:

the intersection of the two line segments, or null if the lines are parallel (within rounding error), or do not intersect

Throws:

ArithmeticException - when any of the values is NaN

intersectionOfLineSegments

public static Point2d intersectionOfLineSegments(LineSegment2d segment1,
 LineSegment2d segment2)

Compute the 2D intersection of two line segments.

Parameters:

segment1 - the first line segment

segment2 - the other line segment

Returns:

the intersection of the line segments, or null if the line segments do not intersect

closestPointOnSegment

public Point2d closestPointOnSegment(Point2d segmentPoint1,
 Point2d 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<Point2d>

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 Point2d closestPointOnLine(double p1X,
 double p1Y,
 double p2X,
 double p2Y,
 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

p2X - the x coordinate of the second point on the line

p2Y - the y 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

DrawRuntimeException - when the line is ill-defined (begin point coincides with end point)

fractionalPositionOnLine

public double fractionalPositionOnLine(double p1X,
 double p1Y,
 double p2X,
 double p2Y,
 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

p2X - the x coordinate of the second point on the line

p2Y - the y 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:

ArithmeticException - when any of the arguments is NaN

DrawRuntimeException - when the line is ill-defined (begin point coincides with end point)

closestPointOnSegment

public final Point2d closestPointOnSegment(double p1X,
 double p1Y,
 double p2X,
 double p2Y)

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

p2X - the x coordinate of the end point of the line segment

p2Y - 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:

DrawRuntimeException - when the line is ill-defined (begin point coincides with end point)

closestPointOnLine

public Point2d closestPointOnLine(Point2d linePoint1,
 Point2d linePoint2)
                           throws NullPointerException,
DrawRuntimeException

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<Point2d>

Parameters:

linePoint1 - point on the line

linePoint2 - another point on the line

Returns:

a point on the line that goes through linePoint1 and linePoint2

Throws:

NullPointerException - when linePoint1 is null, or linePoint2 is null

DrawRuntimeException

closestPointOnLine

public final Point2d closestPointOnLine(double p1X,
 double p1Y,
 double p2X,
 double p2Y)

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 segment

p1Y - the y coordinate of a point of the line segment

p2X - the x coordinate of another point of the line segment

p2Y - the y coordinate of another point of the line segment

Returns:

a point on the line that goes through the points

Throws:

IllegalArgumentException - when the points on the line are identical

circleIntersections

public static final List<Point2d> circleIntersections(Point2d center1,
 double radius1,
 Point2d center2,
 double radius2)
                                               throws NullPointerException,
IllegalArgumentException

Return the zero, one or two intersections between two circles. The circles must be different. Derived from pseudo code by Paul Bourke and C implementation by Tim Voght .

Parameters:

center1 - the center of circle 1

radius1 - the radius of circle 1

center2 - the center of circle 2

radius2 - the radius of circle 2

Returns:

List<Point2d> a list of zero, one or two points

Throws:

NullPointerException - when center1 or center2 is null

IllegalArgumentException - when the two circles are identical, or radius1 < 0.0, or radius2 < 0.0

directionTo

public double directionTo(Point2d otherPoint)

Return the direction to another Point2d.

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.

toPoint2D

public Point2D toPoint2D()

Return the coordinates as a java.awt.geom.Point2D.Double object.

Returns:

java.awt.geom.Point2D; the coordinates as a java.awt.geom.Point2D.Double object

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<Point2d>

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<Point2d>

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