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