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 * https://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
18 /*
19 * This is not the original file distributed by the Apache Software Foundation
20 * It has been modified by the Hipparchus project
21 */
22 package org.hipparchus.geometry.partitioning;
23
24 import org.hipparchus.geometry.Space;
25
26 /** This interface represents the remaining parts of an hyperplane after
27 * other parts have been chopped off.
28
29 * <p>sub-hyperplanes are obtained when parts of an {@link
30 * Hyperplane hyperplane} are chopped off by other hyperplanes that
31 * intersect it. The remaining part is a convex region. Such objects
32 * appear in {@link BSPTree BSP trees} as the intersection of a cut
33 * hyperplane with the convex region which it splits, the chopping
34 * hyperplanes are the cut hyperplanes closer to the tree root.</p>
35
36 * <p>
37 * Note that this interface is <em>not</em> intended to be implemented
38 * by Hipparchus users, it is only intended to be implemented
39 * within the library itself. New methods may be added even for minor
40 * versions, which breaks compatibility for external implementations.
41 * </p>
42
43 * @param <S> Type of the embedding space.
44
45 */
46 public interface SubHyperplane<S extends Space> {
47
48 /** Copy the instance.
49 * <p>The instance created is completely independent of the original
50 * one. A deep copy is used, none of the underlying objects are
51 * shared (except for the nodes attributes and immutable
52 * objects).</p>
53 * @return a new sub-hyperplane, copy of the instance
54 */
55 SubHyperplane<S> copySelf();
56
57 /** Get the underlying hyperplane.
58 * @return underlying hyperplane
59 */
60 Hyperplane<S> getHyperplane();
61
62 /** Check if the instance is empty.
63 * @return true if the instance is empty
64 */
65 boolean isEmpty();
66
67 /** Get the size of the instance.
68 * @return the size of the instance (this is a length in 1D, an area
69 * in 2D, a volume in 3D ...)
70 */
71 double getSize();
72
73 /** Split the instance in two parts by an hyperplane.
74 * @param hyperplane splitting hyperplane
75 * @return an object containing both the part of the instance
76 * on the plus side of the hyperplane and the part of the
77 * instance on the minus side of the hyperplane
78 */
79 SplitSubHyperplane<S> split(Hyperplane<S> hyperplane);
80
81 /** Compute the union of the instance and another sub-hyperplane.
82 * @param other other sub-hyperplane to union (<em>must</em> be in the
83 * same hyperplane as the instance)
84 * @return a new sub-hyperplane, union of the instance and other
85 */
86 SubHyperplane<S> reunite(SubHyperplane<S> other);
87
88 /** Class holding the results of the {@link #split split} method.
89 * @param <U> Type of the embedding space.
90 */
91 class SplitSubHyperplane<U extends Space> {
92
93 /** Part of the sub-hyperplane on the plus side of the splitting hyperplane. */
94 private final SubHyperplane<U> plus;
95
96 /** Part of the sub-hyperplane on the minus side of the splitting hyperplane. */
97 private final SubHyperplane<U> minus;
98
99 /** Build a SplitSubHyperplane from its parts.
100 * @param plus part of the sub-hyperplane on the plus side of the
101 * splitting hyperplane
102 * @param minus part of the sub-hyperplane on the minus side of the
103 * splitting hyperplane
104 */
105 public SplitSubHyperplane(final SubHyperplane<U> plus,
106 final SubHyperplane<U> minus) {
107 this.plus = plus;
108 this.minus = minus;
109 }
110
111 /** Get the part of the sub-hyperplane on the plus side of the splitting hyperplane.
112 * @return part of the sub-hyperplane on the plus side of the splitting hyperplane
113 */
114 public SubHyperplane<U> getPlus() {
115 return plus;
116 }
117
118 /** Get the part of the sub-hyperplane on the minus side of the splitting hyperplane.
119 * @return part of the sub-hyperplane on the minus side of the splitting hyperplane
120 */
121 public SubHyperplane<U> getMinus() {
122 return minus;
123 }
124
125 /** Get the side of the split sub-hyperplane with respect to its splitter.
126 * @return {@link Side#PLUS} if only {@link #getPlus()} is neither null nor empty,
127 * {@link Side#MINUS} if only {@link #getMinus()} is neither null nor empty,
128 * {@link Side#BOTH} if both {@link #getPlus()} and {@link #getMinus()}
129 * are neither null nor empty or {@link Side#HYPER} if both {@link #getPlus()} and
130 * {@link #getMinus()} are either null or empty
131 */
132 public Side getSide() {
133 if (plus != null && !plus.isEmpty()) {
134 if (minus != null && !minus.isEmpty()) {
135 return Side.BOTH;
136 } else {
137 return Side.PLUS;
138 }
139 } else if (minus != null && !minus.isEmpty()) {
140 return Side.MINUS;
141 } else {
142 return Side.HYPER;
143 }
144 }
145
146 }
147
148 }