1 package org.djutils.draw.point;
2
3 import java.io.Serializable;
4
5 import org.djutils.draw.DrawRuntimeException;
6 import org.djutils.draw.Drawable;
7
8 /**
9 * Point is the interface for the Point2d and Point3d implementations, standardizing as many of the methods as possible.
10 * <p>
11 * Copyright (c) 2020-2022 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
12 * BSD-style license. See <a href="https://djutils.org/docs/current/djutils/licenses.html">DJUTILS License</a>.
13 * </p>
14 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
15 * @author <a href="https://www.tudelft.nl/pknoppers">Peter Knoppers</a>
16 * @param <P> The point type
17 */
18 public interface Point<P extends Point<P>> extends Drawable<P>, Serializable
19 {
20 /**
21 * Return the x-coordinate. When the point is not in Cartesian space, a calculation to Cartesian space has to be made.
22 * @return double; the x-coordinate
23 */
24 double getX();
25
26 /**
27 * Return the y-coordinate. When the point is not in Cartesian space, a calculation to Cartesian space has to be made.
28 * @return double; the y-coordinate
29 */
30 double getY();
31
32 /**
33 * Return a new Point with the coordinates of this point scaled by the provided factor.
34 * @param factor double; the scale factor
35 * @return Point; a new point with the coordinates of this point scaled by the provided factor
36 * @throws IllegalArgumentException when factor is NaN
37 */
38 P scale(double factor) throws IllegalArgumentException;
39
40 /**
41 * Return a new Point with negated coordinate values.
42 * @return Point; a new point with negated coordinate values
43 */
44 P neg();
45
46 /**
47 * Return a new Point with absolute coordinate values.
48 * @return Point; a new point with absolute coordinate values
49 */
50 P abs();
51
52 /**
53 * Return a new Point with a distance of 1 to the origin.
54 * @return Point; the normalized point
55 * @throws DrawRuntimeException when point is the origin, and no length can be established for scaling
56 */
57 P normalize() throws DrawRuntimeException;
58
59 /**
60 * Return the distance to another point.
61 * @param otherPoint P; P the other point
62 * @return double; the distance (2d or 3d as applicable) to the other point
63 */
64 double distance(P otherPoint);
65
66 /**
67 * Return the squared distance between this point and the provided point.
68 * @param otherPoint P; the other point
69 * @return double; the squared distance between this point and the other point
70 * @throws NullPointerException when otherPoint is null
71 */
72 double distanceSquared(P otherPoint) throws NullPointerException;
73
74 /**
75 * Interpolate towards another Point with a fraction. It is allowed for fraction to be less than zero or larger than 1. In
76 * that case the interpolation turns into an extrapolation.
77 * @param point P; the other point
78 * @param fraction double; the factor for interpolation towards the other point. When <code>fraction</code> is
79 * between 0 and 1, it is an interpolation, otherwise an extrapolation. If <code>fraction</code> is 0;
80 * <code>this</code> Point is returned; if <code>fraction</code> is 1, the other <code>point</code> is returned
81 * @return P; the point that is <code>fraction</code> away on the line between this point and the other point
82 * @throws NullPointerException when point is null
83 * @throws IllegalArgumentException when fraction is NaN
84 */
85 P interpolate(P point, double fraction);
86
87 /**
88 * Project a point on a line segment. If the the projected points lies outside the line segment, the nearest end point of
89 * the line segment is returned. Otherwise the returned point lies between the end points of the line segment. <br>
90 * Adapted from <a href="http://paulbourke.net/geometry/pointlineplane/DistancePoint.java">example code provided by Paul
91 * Bourke</a>.
92 * @param segmentPoint1 P; start of line segment
93 * @param segmentPoint2 P; end of line segment
94 * @return P; either <cite>segmentPoint1</cite>, or <cite>segmentPoint2</cite> or a new Point2d that lies somewhere in
95 * between those two.
96 * @throws NullPointerException when segmentPoint2, or segmentPoint2 is null
97 */
98 P closestPointOnSegment(P segmentPoint1, P segmentPoint2) throws NullPointerException;
99
100 /**
101 * Project a point on a line. <br>
102 * Adapted from <a href="http://paulbourke.net/geometry/pointlineplane/DistancePoint.java">example code provided by Paul
103 * Bourke</a>.
104 * @param linePoint1 P; point on the line
105 * @param linePoint2 P; another point on the line
106 * @return Point2d; a point on the line that goes through <cite>linePoint1</cite> and <cite>linePoint2</cite>
107 * @throws NullPointerException when linePoint1 is null, or linePoint2 is null
108 * @throws DrawRuntimeException when <cite>linePoint1</cite> is at the same location as <cite>linePoint2</cite>
109 */
110 P closestPointOnLine(P linePoint1, P linePoint2) throws NullPointerException, DrawRuntimeException;
111
112 /**
113 * A comparison with another point that returns true of each of the coordinates is less than epsilon apart.
114 * @param other P; the point to compare with
115 * @param epsilon double; the upper bound of difference for one of the coordinates
116 * @return boolean; true if both x, y and z (if a Point3d) are less than epsilon apart, otherwise false
117 * @throws NullPointerException when other is null
118 */
119 boolean epsilonEquals(P other, double epsilon) throws NullPointerException;
120
121 }