SubHyperplane.java

  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.  */

  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;

  24. import org.hipparchus.geometry.Point;
  25. import org.hipparchus.geometry.Space;

  27. /** This interface represents the remaining parts of an hyperplane after
  28.  * other parts have been chopped off.

  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>

  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>

  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.

  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>> {

  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();

  64.     /** Get the underlying hyperplane.
  65.      * @return underlying hyperplane
  66.      */
  67.     H getHyperplane();

  69.     /** Check if the instance is empty.
  70.      * @return true if the instance is empty
  71.      */
  72.     boolean isEmpty();

  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();

  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);

  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);

  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();

  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>> {

  109.         /** Part of the sub-hyperplane on the plus side of the splitting hyperplane. */
  110.         private final J plus;

  112.         /** Part of the sub-hyperplane on the minus side of the splitting hyperplane. */
  113.         private final J minus;

  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.         }

  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.         }

  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.         }

  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.         }

  161.     }

  163. }
Created with JaCoCo 0.8.12.202403310830