001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.commons.math3.geometry.partitioning; 018 019import org.apache.commons.math3.geometry.Point; 020import org.apache.commons.math3.geometry.Space; 021 022/** This interface represents an hyperplane of a space. 023 024 * <p>The most prominent place where hyperplane appears in space 025 * partitioning is as cutters. Each partitioning node in a {@link 026 * BSPTree BSP tree} has a cut {@link SubHyperplane sub-hyperplane} 027 * which is either an hyperplane or a part of an hyperplane. In an 028 * n-dimensions euclidean space, an hyperplane is an (n-1)-dimensions 029 * hyperplane (for example a traditional plane in the 3D euclidean 030 * space). They can be more exotic objects in specific fields, for 031 * example a circle on the surface of the unit sphere.</p> 032 033 * <p> 034 * Note that this interface is <em>not</em> intended to be implemented 035 * by Apache Commons Math users, it is only intended to be implemented 036 * within the library itself. New methods may be added even for minor 037 * versions, which breaks compatibility for external implementations. 038 * </p> 039 040 * @param <S> Type of the space. 041 042 * @since 3.0 043 */ 044public interface Hyperplane<S extends Space> { 045 046 /** Copy the instance. 047 * <p>The instance created is completely independant of the original 048 * one. A deep copy is used, none of the underlying objects are 049 * shared (except for immutable objects).</p> 050 * @return a new hyperplane, copy of the instance 051 */ 052 Hyperplane<S> copySelf(); 053 054 /** Get the offset (oriented distance) of a point. 055 * <p>The offset is 0 if the point is on the underlying hyperplane, 056 * it is positive if the point is on one particular side of the 057 * hyperplane, and it is negative if the point is on the other side, 058 * according to the hyperplane natural orientation.</p> 059 * @param point point to check 060 * @return offset of the point 061 */ 062 double getOffset(Point<S> point); 063 064 /** Project a point to the hyperplane. 065 * @param point point to project 066 * @return projected point 067 * @since 3.3 068 */ 069 Point<S> project(Point<S> point); 070 071 /** Get the tolerance below which points are considered to belong to the hyperplane. 072 * @return tolerance below which points are considered to belong to the hyperplane 073 * @since 3.3 074 */ 075 double getTolerance(); 076 077 /** Check if the instance has the same orientation as another hyperplane. 078 * <p>This method is expected to be called on parallel hyperplanes. The 079 * method should <em>not</em> re-check for parallelism, only for 080 * orientation, typically by testing something like the sign of the 081 * dot-products of normals.</p> 082 * @param other other hyperplane to check against the instance 083 * @return true if the instance and the other hyperplane have 084 * the same orientation 085 */ 086 boolean sameOrientationAs(Hyperplane<S> other); 087 088 /** Build a sub-hyperplane covering the whole hyperplane. 089 * @return a sub-hyperplane covering the whole hyperplane 090 */ 091 SubHyperplane<S> wholeHyperplane(); 092 093 /** Build a region covering the whole space. 094 * @return a region containing the instance 095 */ 096 Region<S> wholeSpace(); 097 098}