1 package org.djutils.draw.line;
2
3 import org.djutils.draw.point.Point;
4
5 /**
6 * Project.java.
7 * <p>
8 * Copyright (c) 2021-2022 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
9 * BSD-style license. See <a href="https://djutils.org/docs/current/djutils/licenses.html">DJUTILS License</a>.
10 * </p>
11 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
12 * @author <a href="https://www.tudelft.nl/pknoppers">Peter Knoppers</a>
13 * @param <P> the point type (2d or 3d)
14 */
15 public interface Project<P extends Point<P>>
16 {
17 /**
18 * Project a point onto this object. For PolyLines, there may be multiple valid solutions. In that case the solution that
19 * lies on the closest segment is returned. If there is no valid solution on the closest segment, null is returned.
20 * @param point P; the point
21 * @return P; the projection of the point (may be null if no sensible projection is possible). If the result is not null;
22 * the result lies somewhere on this object.
23 * @throws NullPointerException when point is null;
24 */
25 P projectOrthogonal(P point) throws NullPointerException;
26
27 /**
28 * Project a point onto this object. For PolyLines, there may be multiple valid solutions. In that case the solution that
29 * lies on the closest segment is returned.
30 * @param point P; the point
31 * @return P; the projection of the point. This result cannot be null, but it may not lie on this object, but, in stead, lie
32 * on a line, or plane that extends this object
33 * @throws NullPointerException when point is null;
34 */
35 P projectOrthogonalExtended(P point) throws NullPointerException;
36
37 /**
38 * Project a point onto this object. For PolyLines, there may be multiple valid solutions. In that case the solution that
39 * lies on the closest segment is returned. If there is no valid solution on the closest segment, null is returned.
40 * @param point P; the point
41 * @return double; the fractional position of the projection of the point (may be NaN if no sensible projection is
42 * possible). If the result is not null; the result lies somewhere on this object.
43 * @throws NullPointerException when point is null;
44 */
45 double projectOrthogonalFractional(P point) throws NullPointerException;
46
47 /**
48 * Project a point onto this object. For PolyLines, there may be multiple valid solutions. In that case the solution that
49 * lies on the closest segment is returned.
50 * @param point P; the point
51 * @return double; the fractional position of the projection of the point. This result cannot be NaN, but it may be outside
52 * the range 0.0 .. 1.0.
53 * @throws NullPointerException when point is null;
54 */
55 double projectOrthogonalFractionalExtended(P point) throws NullPointerException;
56
57 }