1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.geometry.core.partitioning;
18
19 import java.util.List;
20
21 import org.apache.commons.geometry.core.Point;
22 import org.apache.commons.geometry.core.RegionLocation;
23 import org.apache.commons.geometry.core.Sized;
24 import org.apache.commons.geometry.core.Transform;
25
26 /** Interface representing a subset of the points lying in a hyperplane. Examples include
27 * rays and line segments in Euclidean 2D space and triangular facets in Euclidean 3D space.
28 * Hyperplane subsets can have finite or infinite size and can represent contiguous regions
29 * of the hyperplane (as in the examples above); multiple, disjoint regions; or the
30 * {@link Hyperplane#span() entire hyperplane}.
31 *
32 * <p>This interface is very similar to the {@link org.apache.commons.geometry.core.Region Region}
33 * interface but has slightly different semantics. Whereas {@code Region} instances represent sets
34 * of points that can expand through all of the dimensions of a space, {@code HyperplaneSubset} instances
35 * are constrained to their containing hyperplane and are more accurately defined as {@code Region}s
36 * of the {@code n-1} dimension subspace defined by the hyperplane. This makes the methods of this interface
37 * have slightly different meanings as compared to their {@code Region} counterparts. For example, consider
38 * a triangular facet in Euclidean 3D space. The {@link #getSize()} method of this hyperplane subset does
39 * not return the <em>volume</em> of the instance (which would be {@code 0}) as a regular 3D region would, but
40 * rather returns the <em>area</em> of the 2D polygon defined by the facet. Similarly, the {@link #classify(Point)}
41 * method returns {@link RegionLocation#INSIDE} for points that lie inside of the 2D polygon defined by the
42 * facet, instead of the {@link RegionLocation#BOUNDARY} value that would be expected if the facet was considered
43 * as a true 3D region with zero thickness.
44 * </p>
45 *
46 * @param <P> Point implementation type
47 * @see Hyperplane
48 */
49 public interface HyperplaneSubset<P extends Point<P>> extends Splittable<P, HyperplaneSubset<P>>, Sized {
50
51 /** Get the hyperplane containing this instance.
52 * @return the hyperplane containing this instance
53 */
54 Hyperplane<P> getHyperplane();
55
56 /** Return true if this instance contains all points in the
57 * hyperplane.
58 * @return true if this instance contains all points in the
59 * hyperplane
60 */
61 boolean isFull();
62
63 /** Return true if this instance does not contain any points.
64 * @return true if this instance does not contain any points
65 */
66 boolean isEmpty();
67
68 /** Get the centroid, or geometric center, of the hyperplane subset or null
69 * if no centroid exists or one exists but is not unique. A centroid will not
70 * exist for empty or infinite subsets.
71 *
72 * <p>The centroid of a geometric object is defined as the mean position of
73 * all points in the object, including interior points, vertices, and other points
74 * lying on the boundary. If a physical object has a uniform density, then its center
75 * of mass is the same as its geometric centroid.
76 * </p>
77 * @return the centroid of the hyperplane subset or null if no unique centroid exists
78 * @see <a href="https://en.wikipedia.org/wiki/Centroid">Centroid</a>
79 */
80 P getCentroid();
81
82 /** Classify a point with respect to the subset region. The point is classified as follows:
83 * <ul>
84 * <li>{@link RegionLocation#INSIDE INSIDE} - The point lies on the hyperplane
85 * and inside of the subset region.</li>
86 * <li>{@link RegionLocation#BOUNDARY BOUNDARY} - The point lies on the hyperplane
87 * and is on the boundary of the subset region.</li>
88 * <li>{@link RegionLocation#OUTSIDE OUTSIDE} - The point does not lie on
89 * the hyperplane or it does lie on the hyperplane but is outside of the
90 * subset region.</li>
91 * </ul>
92 * @param pt the point to classify
93 * @return classification of the point with respect to the hyperplane
94 * and subspace region
95 */
96 RegionLocation classify(P pt);
97
98 /** Return true if the hyperplane subset contains the given point, meaning that the point
99 * lies on the hyperplane and is not on the outside of the subset region.
100 * @param pt the point to check
101 * @return true if the point is contained in the hyperplane subset
102 */
103 default boolean contains(final P pt) {
104 final RegionLocation loc = classify(pt);
105 return loc != null && loc != RegionLocation.OUTSIDE;
106 }
107
108 /** Return the closest point to the argument that is contained in the subset
109 * (ie, not classified as {@link RegionLocation#OUTSIDE outside}), or null if no
110 * such point exists.
111 * @param pt the reference point
112 * @return the closest point to the reference point that is contained in the subset,
113 * or null if no such point exists
114 */
115 P closest(P pt);
116
117 /** Return a new hyperplane subset resulting from the application of the given transform.
118 * The current instance is not modified.
119 * @param transform the transform instance to apply
120 * @return new transformed hyperplane subset
121 */
122 HyperplaneSubset<P> transform(Transform<P> transform);
123
124 /** Convert this instance into a list of convex child subsets representing the same region.
125 * Implementations are not required to return an optimal convex subdivision of the current
126 * instance. They are free to return whatever subdivision is readily available.
127 * @return a list of hyperplane convex subsets representing the same subspace
128 * region as this instance
129 */
130 List<? extends HyperplaneConvexSubset<P>> toConvex();
131 }