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 */
017 package org.apache.commons.math3.geometry.partitioning;
018
019 import 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 * @param <S> Type of the embedding space.
032
033 * @version $Id: SubHyperplane.java 1416643 2012-12-03 19:37:14Z tn $
034 * @since 3.0
035 */
036 public interface SubHyperplane<S extends Space> {
037
038 /** Copy the instance.
039 * <p>The instance created is completely independent of the original
040 * one. A deep copy is used, none of the underlying objects are
041 * shared (except for the nodes attributes and immutable
042 * objects).</p>
043 * @return a new sub-hyperplane, copy of the instance
044 */
045 SubHyperplane<S> copySelf();
046
047 /** Get the underlying hyperplane.
048 * @return underlying hyperplane
049 */
050 Hyperplane<S> getHyperplane();
051
052 /** Check if the instance is empty.
053 * @return true if the instance is empty
054 */
055 boolean isEmpty();
056
057 /** Get the size of the instance.
058 * @return the size of the instance (this is a length in 1D, an area
059 * in 2D, a volume in 3D ...)
060 */
061 double getSize();
062
063 /** Compute the relative position of the instance with respect
064 * to an hyperplane.
065 * @param hyperplane hyperplane to check instance against
066 * @return one of {@link Side#PLUS}, {@link Side#MINUS}, {@link Side#BOTH},
067 * {@link Side#HYPER}
068 */
069 Side side(Hyperplane<S> hyperplane);
070
071 /** Split the instance in two parts by an hyperplane.
072 * @param hyperplane splitting hyperplane
073 * @return an object containing both the part of the instance
074 * on the plus side of the instance and the part of the
075 * instance on the minus side of the instance
076 */
077 SplitSubHyperplane<S> split(Hyperplane<S> hyperplane);
078
079 /** Compute the union of the instance and another sub-hyperplane.
080 * @param other other sub-hyperplane to union (<em>must</em> be in the
081 * same hyperplane as the instance)
082 * @return a new sub-hyperplane, union of the instance and other
083 */
084 SubHyperplane<S> reunite(SubHyperplane<S> other);
085
086 /** Class holding the results of the {@link #split split} method.
087 * @param <U> Type of the embedding space.
088 */
089 public static class SplitSubHyperplane<U extends Space> {
090
091 /** Part of the sub-hyperplane on the plus side of the splitting hyperplane. */
092 private final SubHyperplane<U> plus;
093
094 /** Part of the sub-hyperplane on the minus side of the splitting hyperplane. */
095 private final SubHyperplane<U> minus;
096
097 /** Build a SplitSubHyperplane from its parts.
098 * @param plus part of the sub-hyperplane on the plus side of the
099 * splitting hyperplane
100 * @param minus part of the sub-hyperplane on the minus side of the
101 * splitting hyperplane
102 */
103 public SplitSubHyperplane(final SubHyperplane<U> plus,
104 final SubHyperplane<U> minus) {
105 this.plus = plus;
106 this.minus = minus;
107 }
108
109 /** Get the part of the sub-hyperplane on the plus side of the splitting hyperplane.
110 * @return part of the sub-hyperplane on the plus side of the splitting hyperplane
111 */
112 public SubHyperplane<U> getPlus() {
113 return plus;
114 }
115
116 /** Get the part of the sub-hyperplane on the minus side of the splitting hyperplane.
117 * @return part of the sub-hyperplane on the minus side of the splitting hyperplane
118 */
119 public SubHyperplane<U> getMinus() {
120 return minus;
121 }
122
123 }
124
125 }