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.Space; 020 021/** This interface represents the remaining parts of an hyperplane after 022 * other parts have been chopped off. 023 024 * <p>sub-hyperplanes are obtained when parts of an {@link 025 * Hyperplane hyperplane} are chopped off by other hyperplanes that 026 * intersect it. The remaining part is a convex region. Such objects 027 * appear in {@link BSPTree BSP trees} as the intersection of a cut 028 * hyperplane with the convex region which it splits, the chopping 029 * hyperplanes are the cut hyperplanes closer to the tree root.</p> 030 031 * <p> 032 * Note that this interface is <em>not</em> intended to be implemented 033 * by Apache Commons Math users, it is only intended to be implemented 034 * within the library itself. New methods may be added even for minor 035 * versions, which breaks compatibility for external implementations. 036 * </p> 037 038 * @param <S> Type of the embedding space. 039 040 * @since 3.0 041 */ 042public interface SubHyperplane<S extends Space> { 043 044 /** Copy the instance. 045 * <p>The instance created is completely independent of the original 046 * one. A deep copy is used, none of the underlying objects are 047 * shared (except for the nodes attributes and immutable 048 * objects).</p> 049 * @return a new sub-hyperplane, copy of the instance 050 */ 051 SubHyperplane<S> copySelf(); 052 053 /** Get the underlying hyperplane. 054 * @return underlying hyperplane 055 */ 056 Hyperplane<S> getHyperplane(); 057 058 /** Check if the instance is empty. 059 * @return true if the instance is empty 060 */ 061 boolean isEmpty(); 062 063 /** Get the size of the instance. 064 * @return the size of the instance (this is a length in 1D, an area 065 * in 2D, a volume in 3D ...) 066 */ 067 double getSize(); 068 069 /** Compute the relative position of the instance with respect 070 * to an hyperplane. 071 * @param hyperplane hyperplane to check instance against 072 * @return one of {@link Side#PLUS}, {@link Side#MINUS}, {@link Side#BOTH}, 073 * {@link Side#HYPER} 074 * @deprecated as of 3.6, replaced with {@link #split(Hyperplane)}.{@link SplitSubHyperplane#getSide()} 075 */ 076 @Deprecated 077 Side side(Hyperplane<S> hyperplane); 078 079 /** Split the instance in two parts by an hyperplane. 080 * @param hyperplane splitting hyperplane 081 * @return an object containing both the part of the instance 082 * on the plus side of the hyperplane and the part of the 083 * instance on the minus side of the hyperplane 084 */ 085 SplitSubHyperplane<S> split(Hyperplane<S> hyperplane); 086 087 /** Compute the union of the instance and another sub-hyperplane. 088 * @param other other sub-hyperplane to union (<em>must</em> be in the 089 * same hyperplane as the instance) 090 * @return a new sub-hyperplane, union of the instance and other 091 */ 092 SubHyperplane<S> reunite(SubHyperplane<S> other); 093 094 /** Class holding the results of the {@link #split split} method. 095 * @param <U> Type of the embedding space. 096 */ 097 class SplitSubHyperplane<U extends Space> { 098 099 /** Part of the sub-hyperplane on the plus side of the splitting hyperplane. */ 100 private final SubHyperplane<U> plus; 101 102 /** Part of the sub-hyperplane on the minus side of the splitting hyperplane. */ 103 private final SubHyperplane<U> minus; 104 105 /** Build a SplitSubHyperplane from its parts. 106 * @param plus part of the sub-hyperplane on the plus side of the 107 * splitting hyperplane 108 * @param minus part of the sub-hyperplane on the minus side of the 109 * splitting hyperplane 110 */ 111 public SplitSubHyperplane(final SubHyperplane<U> plus, 112 final SubHyperplane<U> minus) { 113 this.plus = plus; 114 this.minus = minus; 115 } 116 117 /** Get the part of the sub-hyperplane on the plus side of the splitting hyperplane. 118 * @return part of the sub-hyperplane on the plus side of the splitting hyperplane 119 */ 120 public SubHyperplane<U> getPlus() { 121 return plus; 122 } 123 124 /** Get the part of the sub-hyperplane on the minus side of the splitting hyperplane. 125 * @return part of the sub-hyperplane on the minus side of the splitting hyperplane 126 */ 127 public SubHyperplane<U> getMinus() { 128 return minus; 129 } 130 131 /** Get the side of the split sub-hyperplane with respect to its splitter. 132 * @return {@link Side#PLUS} if only {@link #getPlus()} is neither null nor empty, 133 * {@link Side#MINUS} if only {@link #getMinus()} is neither null nor empty, 134 * {@link Side#BOTH} if both {@link #getPlus()} and {@link #getMinus()} 135 * are neither null nor empty or {@link Side#HYPER} if both {@link #getPlus()} and 136 * {@link #getMinus()} are either null or empty 137 * @since 3.6 138 */ 139 public Side getSide() { 140 if (plus != null && !plus.isEmpty()) { 141 if (minus != null && !minus.isEmpty()) { 142 return Side.BOTH; 143 } else { 144 return Side.PLUS; 145 } 146 } else if (minus != null && !minus.isEmpty()) { 147 return Side.MINUS; 148 } else { 149 return Side.HYPER; 150 } 151 } 152 153 } 154 155}