Package org.djutils.draw.point
Class Point2d
- java.lang.Object
-
- org.djutils.draw.point.Point2d
-
- All Implemented Interfaces:
Serializable
,Drawable<Point2d>
,Drawable2d
,Point<Point2d>
- Direct Known Subclasses:
OrientedPoint2d
,Ray2d
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-2023 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
-
-
Constructor Summary
Constructors Constructor Description Point2d(double[] xy)
Create a new Point with just an x and y coordinate, stored with double precision.Point2d(double x, double y)
Create a new Point with just an x and y coordinate, stored with double precision.Point2d(Point2D point)
Create an immutable point with just two values, x and y, stored with double precision from an AWT Point2D.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description Point2d
abs()
Return a new Point with absolute coordinate values.static List<Point2d>
circleIntersections(Point2d center1, double radius1, Point2d center2, double radius2)
Return the zero, one or two intersections between two circles.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.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 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 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.Iterator<? extends Point2d>
getPoints()
Retrieve, or generate all points that make up the object.double
getX()
Return the x-coordinate.double
getY()
Return the y-coordinate.int
hashCode()
Point2d
interpolate(Point2d point, 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.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 an AWT 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 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 delta-x, delta-y and delta-z.-
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
-
-
-
-
Constructor Detail
-
Point2d
public Point2d(double x, double y) throws IllegalArgumentException
Create a new Point with just an x and y coordinate, stored with double precision.- Parameters:
x
- double; the x coordinatey
- double; the y coordinate- Throws:
IllegalArgumentException
- when x or y is NaN
-
Point2d
public Point2d(double[] xy) throws NullPointerException, IllegalArgumentException
Create a new Point with just an x and y coordinate, stored with double precision.- Parameters:
xy
- double[]; the x and y coordinate- Throws:
NullPointerException
- when xy is nullIllegalArgumentException
- when the dimension of xy is not 2, or a coordinate is NaN
-
Point2d
public Point2d(Point2D point) throws NullPointerException, IllegalArgumentException
Create an immutable point with just two values, x and y, stored with double precision from an AWT Point2D.- Parameters:
point
- Point2D; an AWT Point2D- Throws:
NullPointerException
- when point is nullIllegalArgumentException
- when point has a NaN coordinate
-
-
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.
-
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.
-
distance
public double distance(Point2d otherPoint)
Return the distance to another point.
-
distanceSquared
public double distanceSquared(Point2d otherPoint) throws NullPointerException
Return the squared distance between this point and the provided point.- Specified by:
distanceSquared
in interfacePoint<Point2d>
- Parameters:
otherPoint
- P; the other point- Returns:
- double; the squared distance between this point and the other point
- Throws:
NullPointerException
- when otherPoint is null
-
size
public int size()
Retrieve the number of points that make up the object.
-
getPoints
public Iterator<? extends Point2d> getPoints()
Retrieve, or generate all points that make up the object.
-
translate
public Point2d translate(double dx, double dy)
Return a new Point with a translation by the provided dx and dy.- Parameters:
dx
- double; the horizontal translationdy
- double; the vertical translation- Returns:
- P; 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 delta-x, delta-y and delta-z. 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
- double; the x translationdy
- double; the y translationdz
- double; the z translation- Returns:
- Point2d; a new point with the translated coordinates
- Throws:
IllegalArgumentException
- when dx, dy, or dz is NaN
-
scale
public Point2d scale(double factor)
Return a new Point with the coordinates of this point scaled by the provided factor.
-
neg
public Point2d neg()
Return a new Point with negated coordinate values.
-
abs
public Point2d abs()
Return a new Point with absolute coordinate values.
-
normalize
public Point2d normalize() throws DrawRuntimeException
Return a new Point with a distance of 1 to the origin.- Specified by:
normalize
in interfacePoint<Point2d>
- Returns:
- Point; the normalized point
- Throws:
DrawRuntimeException
- when point is the origin, and no length can be established for scaling
-
interpolate
public Point2d interpolate(Point2d 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 interfacePoint<Point2d>
- Parameters:
point
- P; the other pointfraction
- 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. Iffraction
is 0;this
Point is returned; iffraction
is 1, the otherpoint
is returned- Returns:
- P; the point that is
fraction
away on the line between this point and the other point
-
epsilonEquals
public boolean epsilonEquals(Point2d 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 interfacePoint<Point2d>
- Parameters:
other
- P; the point to compare withepsilon
- 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 Bounds2d getBounds()
Retrieve the bounding rectangle of the object.- Specified by:
getBounds
in interfaceDrawable2d
- Returns:
- Bounds2d; 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) throws DrawRuntimeException
Compute the 2D intersection of two lines. Both lines are defined by two points (that should be distinct).- Parameters:
line1P1X
- double; x-coordinate of start point of line 1line1P1Y
- double; y-coordinate of start point of line 1line1P2X
- double; x-coordinate of end point of line 1line1P2Y
- double; y-coordinate of end point of line 1lowLimitLine1
- boolean; if true; the intersection may not lie before the start point of line 1highLimitLine1
- boolean; if true; the intersection may not lie beyond the end point of line 1line2P1X
- double; x-coordinate of start point of line 2line2P1Y
- double; y-coordinate of start point of line 2line2P2X
- double; x-coordinate of end point of line 2line2P2Y
- double; y-coordinate of end point of line 2lowLimitLine2
- boolean; if true; the intersection may not lie before the start point of line 2highLimitLine2
- boolean; if true; the intersection may not lie beyond the end point of line 2- Returns:
- Point2d; the intersection of the two lines, or null if the lines are (almost) parallel, or the intersection point lies outside the permitted range
- Throws:
DrawRuntimeException
- 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) throws DrawRuntimeException
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
- double; x-coordinate of start point of line segment 1l1P1Y
- double; y-coordinate of start point of line segment 1l1P2X
- double; x-coordinate of end point of line segment 1l1P2Y
- double; y-coordinate of end point of line segment 1l2P1X
- double; x-coordinate of start point of line segment 2l2P1Y
- double; y-coordinate of start point of line segment 2l2P2X
- double; x-coordinate of end point of line segment 2l2P2Y
- double; y-coordinate of end point of line segment 2- Returns:
- Point2d; the intersection of the two lines, or null if the lines are (almost) parallel
- Throws:
DrawRuntimeException
- when any of the parameters is NaN
-
intersectionOfLines
public static Point2d intersectionOfLines(Point2d line1P1, Point2d line1P2, Point2d line2P1, Point2d line2P2) throws NullPointerException
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
- Point2d; first point of line 1line1P2
- Point2d; second point of line 1line2P1
- Point2d; first point of line 2line2P2
- Point2d; second point of line 2- Returns:
- Point2d; 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) throws NullPointerException, DrawRuntimeException
Compute the 2D intersection of two line segments. Both line segments are defined by two points (that should be distinct).- Parameters:
line1P1
- Point2d; first point of line segment 1line1P2
- Point2d; second point of line segment 1line2P1
- Point2d; first point of line segment 2line2P2
- Point2d; second point of line segment 2- Returns:
- Point2d; 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 nullDrawRuntimeException
- 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) throws DrawRuntimeException
Compute the 2D intersection of two line segments. Both line segments are defined by two points (that should be distinct).- Parameters:
line1P1X
- double; x coordinate of start point of first line segmentline1P1Y
- double; y coordinate of start point of first line segmentline1P2X
- double; x coordinate of end point of first line segmentline1P2Y
- double; y coordinate of end point of first line segmentline2P1X
- double; x coordinate of start point of second line segmentline2P1Y
- double; y coordinate of start point of second line segmentline2P2X
- double; x coordinate of end point of second line segmentline2P2Y
- double; y coordinate of end point of second line segment- Returns:
- Point2d; the intersection of the two line segments, or null if the lines are parallel (within rounding error), or do not intersect
- Throws:
DrawRuntimeException
- 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
- LineSegment; the first line segmentsegment2
- LineSegment; the other line segment- Returns:
- Point2d; the intersection of the line segments, or null if the line segments do not intersect
-
closestPointOnSegment
public Point2d closestPointOnSegment(Point2d segmentPoint1, Point2d 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 interfacePoint<Point2d>
- Parameters:
segmentPoint1
- P; start of line segmentsegmentPoint2
- P; end of line segment- Returns:
- P; 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) 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 linep1Y
- double; the y coordinate of the first point on the linep2X
- double; the x coordinate of the second point on the linep2Y
- double; the y coordinate of the second point on the linelowLimitHandling
- 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 linehighLimitHandling
- 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:
- Point2d; 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 p2X, double p2Y, 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 linep1Y
- double; the y coordinate of the first point on the linep2X
- double; the x coordinate of the second point on the linep2Y
- double; the y coordinate of the second point on the linelowLimitHandling
- 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 returnedhighLimitHandling
- 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 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
- double; the x coordinate of the start point of the line segmentp1Y
- double; the y coordinate of the start point of the line segmentp2X
- double; the x coordinate of the end point of the line segmentp2Y
- 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.
-
closestPointOnLine
public Point2d closestPointOnLine(Point2d linePoint1, Point2d linePoint2) throws NullPointerException, DrawRuntimeException
Project a point on a line.
Adapted from example code provided by Paul Bourke.- Specified by:
closestPointOnLine
in interfacePoint<Point2d>
- Parameters:
linePoint1
- P; point on the linelinePoint2
- 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 nullDrawRuntimeException
- when linePoint1 is at the same location as linePoint2
-
closestPointOnLine
public final Point2d closestPointOnLine(double p1X, double p1Y, double p2X, double p2Y) 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 segmentp1Y
- double; the y coordinate of a point of the line segmentp2X
- double; the x coordinate of another point of the line segmentp2Y
- double; the y coordinate of another point of the line segment- Returns:
- Point2d; a point on the line that goes through the points
- Throws:
DrawRuntimeException
- 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, DrawRuntimeException
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
- Point2d; the center of circle 1radius1
- double; the radius of circle 1center2
- Point2d; the center of circle 2radius2
- double; the radius of circle 2- Returns:
- List<Point2d> a list of zero, one or two points
- Throws:
NullPointerException
- when center1 or center2 is nullDrawRuntimeException
- when the two circles are identical, or radius1 < 0 or radius2 < 0
-
directionTo
public double directionTo(Point2d otherPoint)
Return the direction to another Point2d.- Parameters:
otherPoint
- Point2d; the other point- Returns:
- double; 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 an AWT Point2D.Double object.- Returns:
- Point2D; the coordinates as an AWT Point2D.Double object
-
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.
-
toString
public String toString(String doubleFormat, boolean doNotIncludeClassName)
Produce a String describing the Drawable.- Specified by:
toString
in interfaceDrawable<Point2d>
- 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
-
-