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 org.apache.commons.geometry.core.Point; 20 import org.apache.commons.geometry.core.Transform; 21 22 /** Interface representing a hyperplane, which in a space of dimension {@code n} is 23 * a subspace of dimension {@code n - 1}. (A hyperplane in Euclidean 3D space, 24 * for example, is a 2 dimensional plane.) 25 * 26 * <p> 27 * Hyperplanes partition their surrounding space into 3 distinct sets: (1) points 28 * lying on one side of the hyperplane, (2) points lying on the opposite side, and 29 * (3) points lying on the hyperplane itself. One side of the hyperplane is labeled 30 * as the <em>plus</em> side and the other as the <em>minus</em> side. The 31 * {@link #offset(Point) offset} of a point in relation to a hyperplane is the distance 32 * from the point to the hyperplane combined with the sign of the side that the point 33 * lies on: points lying on the plus side of the hyperplane have a positive offsets, 34 * those on the minus side have a negative offset, and those lying directly on the 35 * hyperplane have an offset of zero. 36 * 37 * @param <P> Point implementation type 38 * @see HyperplaneLocation 39 * @see HyperplaneSubset 40 */ 41 public interface Hyperplane<P extends Point<P>> { 42 43 /** Get the offset (oriented distance) of a point with respect 44 * to this instance. Points with an offset of zero lie on the 45 * hyperplane itself. 46 * @param point the point to compute the offset for 47 * @return the offset of the point 48 */ 49 double offset(P point); 50 51 /** Classify a point with respect to this hyperplane. 52 * @param point the point to classify 53 * @return the relative location of the point with 54 * respect to this instance 55 */ 56 HyperplaneLocation classify(P point); 57 58 /** Return true if the given point lies on the hyperplane. 59 * @param point the point to test 60 * @return true if the point lies on the hyperplane 61 */ 62 boolean contains(P point); 63 64 /** Project a point onto this instance. 65 * @param point the point to project 66 * @return the projection of the point onto this instance. The returned 67 * point lies on the hyperplane. 68 */ 69 P project(P point); 70 71 /** Return a hyperplane that has the opposite orientation as this instance. 72 * That is, the plus side of this instance is the minus side of the returned 73 * instance and vice versa. 74 * @return a hyperplane with the opposite orientation 75 */ 76 Hyperplane<P> reverse(); 77 78 /** Transform this instance using the given {@link Transform}. 79 * @param transform object to transform this instance with 80 * @return a new, transformed hyperplane 81 */ 82 Hyperplane<P> transform(Transform<P> transform); 83 84 /** Return true if this instance has a similar orientation to the given hyperplane, 85 * meaning that they point in generally the same direction. This method is not 86 * used to determine exact equality of hyperplanes, but rather to determine whether 87 * two hyperplanes that contain the same points are parallel (point in the same direction) 88 * or anti-parallel (point in opposite directions). 89 * @param other the hyperplane to compare with 90 * @return true if the hyperplanes point in generally the same direction and could 91 * possibly be parallel 92 */ 93 boolean similarOrientation(Hyperplane<P> other); 94 95 /** Return a {@link HyperplaneConvexSubset} spanning this entire hyperplane. The returned 96 * subset contains all points lying in this hyperplane and no more. 97 * @return a {@link HyperplaneConvexSubset} containing all points lying in this hyperplane 98 */ 99 HyperplaneConvexSubset<P> span(); 100 }