1 package org.djutils.draw.line;
2
3 import java.io.Serializable;
4
5 import org.djutils.draw.DrawRuntimeException;
6 import org.djutils.draw.Drawable;
7 import org.djutils.draw.point.Point;
8 import org.djutils.exceptions.Throw;
9
10 /**
11 * LineSegment is the interface for a line segment bound by 2 end points. A line segment stores the order in which it has been
12 * created, so the end points are known as 'start' and 'end'.
13 * <p>
14 * Copyright (c) 2020-2022 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
15 * BSD-style license. See <a href="https://djutils.org/docs/current/djutils/licenses.html">DJUTILS License</a>.
16 * </p>
17 * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
18 * @author <a href="https://www.tudelft.nl/pknoppers">Peter Knoppers</a>
19 * @param <P> The point type (2d or 3d)
20 * @param <R> The ray type (2d or 3d)
21 */
22 public interface LineSegment<P extends Point<P>, R extends Ray<R, P>>
23 extends Drawable<P>, Serializable, Project<P>
24 {
25 /**
26 * Get the start point of this LineSegment.
27 * @return P; the start point of the LineSegment
28 */
29 P getStartPoint();
30
31 /**
32 * Get the end point of this LineSegment.
33 * @return P; the end point of the LineSegment
34 */
35 P getEndPoint();
36
37 /**
38 * Get the length (distance from start point to end point) of this LineSegment.
39 * @return double; (distance from start point to end point) of this LineSegment
40 */
41 double getLength();
42
43 /**
44 * Project a Point on this LineSegment. If the the projected points lies outside the line segment, the nearest end point of
45 * the line segment is returned. Otherwise the returned point lies between the end points of the line segment. <br>
46 * Adapted from <a href="http://paulbourke.net/geometry/pointlineplane/DistancePoint.java">example code provided by Paul
47 * Bourke</a>.
48 * @param point P; the point to project onto the segment
49 * @return P; either the start point, or the end point of the segment or a Point that lies somewhere in between those two.
50 * @throws NullPointerException when point is null
51 */
52 P closestPointOnSegment(P point) throws NullPointerException;
53
54 /**
55 * Create a Ray on a specified point on this LineSegment.
56 * @param position double; the distance from the start point of this LineSegment.
57 * @return R; a ray beginning at the specified position
58 * @throws DrawRuntimeException when position is NaN, < 0 or > length of this LineSegment
59 */
60 default R getLocation(double position) throws DrawRuntimeException
61 {
62 Throw.when(position < 0 || position > getLength(), DrawRuntimeException.class,
63 "position must be positive and less than the length of this LineSegment");
64 return getLocationExtended(position);
65 }
66
67 /**
68 * Create a Ray on a specified point on this LineSegment.
69 * @param position double; the distance from the start point of this LineSegment.
70 * @return R; a ray beginning at the specified position
71 * @throws DrawRuntimeException when position is NaN or infinite
72 */
73 R getLocationExtended(double position) throws DrawRuntimeException;
74
75 /**
76 * Convert this PolyLine to something that MS-Excel can plot.
77 * @return String MS-excel XY, or XYZ plottable output
78 */
79 String toExcel();
80
81 }