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 }