1 package org.djutils.draw.bounds;
2
3 import org.djutils.draw.Drawable;
4 import org.djutils.draw.point.Point;
5
6 /**
7 * Bounds is the generic tagging interface that indicates the bounds for an object, where the simplest implementation is minX,
8 * minY, maxX and maxY for 2D, and minX, minY, minZ and maxX, maxY and maxZ for 3D. Other bounds such as a BoundingCircle,
9 * BoundingSphere or BoundingPolytope could also be defined.
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 <B> The bounds type (2d or 3d)
17 * @param <P> The point type (2d or 3d)
18 * @param <D> The Drawable type (2d or 3d)
19 */
20 public interface Bounds<B extends Bounds<B, P, D>, P extends Point<P>, D extends Drawable<P>>
21 {
22 /**
23 * Return the absolute lower bound for x.
24 * @return double; the absolute lower bound for x
25 */
26 double getMinX();
27
28 /**
29 * Return the absolute upper bound for x.
30 * @return double; the absolute upper bound for x
31 */
32 double getMaxX();
33
34 /**
35 * Return the absolute lower bound for y.
36 * @return double; the absolute lower bound for y
37 */
38 double getMinY();
39
40 /**
41 * Return the absolute upper bound for y.
42 * @return double; the absolute upper bound for y
43 */
44 double getMaxY();
45
46 /**
47 * Return the extent of this Bounds2d in the x-direction.
48 * @return double; the extent of this Bounds2d in the x-direction
49 */
50 default double getDeltaX()
51 {
52 return getMaxX() - getMinX();
53 }
54
55 /**
56 * Return the extent of this Bounds2d in the y-direction.
57 * @return double; the extent of this Bounds2d in the y-direction
58 */
59 default double getDeltaY()
60 {
61 return getMaxY() - getMinY();
62 }
63
64 /**
65 * Return the mid point of this Bounds object.
66 * @return P; the mid point of this Bounds object
67 */
68 P midPoint();
69
70 /**
71 * Check if a point is contained in this Bounds.
72 * @param point P; the point
73 * @return boolean; true if the point is within this Bounds; false if the point is not within this Bounds, or on an edge of
74 * this Bounds
75 * @throws NullPointerException when point is null
76 */
77 boolean contains(P point) throws NullPointerException;
78
79 /**
80 * Check if this Bounds completely contains a Drawable. If any point of the Drawable lies on an edge (2d) or surface (3d) of
81 * this Bounds, this method returns false.
82 * @param drawable D; the object for which to check if it is completely contained within this Bounds.
83 * @return boolean; false if any point of D is on or outside one of the borders of this Bounds; true when all points of D
84 * are contained within this Bounds.
85 * @throws NullPointerException when drawable2d is null
86 */
87 boolean contains(D drawable) throws NullPointerException;
88
89 /**
90 * Check if this Bounds covers or touches a point.
91 * @param point P; the Point for which to check if it is covered/touched by this Bounds
92 * @return boolean; whether this Bounds covers or touches the point
93 * @throws NullPointerException when point is null
94 */
95 boolean covers(P point) throws NullPointerException;
96
97 /**
98 * Check if no part of a Drawable is outside this Bounds. The edges/surfaces of this Bounds are considered inside.
99 * @param drawable D; the Drawable for which to check if it is contained within this Bounds
100 * @return boolean; whether this Bounds contains the provided Bounds, including overlapping borders
101 * @throws NullPointerException when otherBounds is null
102 */
103 boolean covers(D drawable) throws NullPointerException;
104
105 /**
106 * Return whether a Drawable is disjoint from this Bounds. Only touching at an edge is considered disjoint. A Drawable that
107 * completely surrounds this Drawable is <b>not</b> disjoint.
108 * @param drawable D; the drawable
109 * @return boolean; true if the drawable is disjoint from this Bounds, or only touches an edge; false if any point of the
110 * drawable is inside this Bounds, or the drawable surrounds this Bounds
111 * @throws NullPointerException when bounds is null
112 */
113 boolean disjoint(D drawable) throws NullPointerException;
114
115 /**
116 * Return whether this Bounds intersects another Bounds. Only touching at an edge is not seen as intersecting.
117 * @param otherBounds B; the other Bounds
118 * @return boolean; whether this bounding box/rectangle intersects the other Bounds
119 * @throws NullPointerException when otherBounds is null
120 */
121 boolean intersects(B otherBounds);
122
123 /**
124 * Return the intersecting Bounds of this Bounds and another Bounds. Touching at the edge is not seen as intersecting. In
125 * case there is no intersection, null is returned.
126 * @param otherBounds B; the other Bounds
127 * @return Bounds; the intersecting Bounds of this Bounds and another Bounds. Touching at the edge is not seen as
128 * intersecting. If not intersecting; null is returned
129 * @throws NullPointerException when otherBounds is null
130 */
131 B intersection(B otherBounds);
132
133 }