GEOMETRY-94: adding PlaneConvexSubset additional implementations; GEO…

…METRY-77: adding Bounds2D and Bounds3D classes

commons-geometry-core/src/main/java/org/apache/commons/geometry/core/Region.java

@@ -45,7 +45,7 @@ public interface Region<P extends Point<P>> extends Sized {
     /** Get the barycenter of the region or null if no barycenter exists or
      * one exists but is not unique. A barycenter will not exist for empty or
      * infinite regions.
-     * @return the barycenter of the region or null if none exists
+     * @return the barycenter of the region or null if no unique barycenter exists
      */
     P getBarycenter();
 

commons-geometry-core/src/main/java/org/apache/commons/geometry/core/RegionEmbedding.java

@@ -23,16 +23,7 @@
  * @see Region
  */
 public interface RegionEmbedding<P extends Point<P>, S extends Point<S>>
-    extends Embedding<P, S>, Sized {
-
-    /** Get the size of the instance, which by default is the size of the embedded
-     * subspace region.
-     * @return the size of instance
-     */
-    @Override
-    default double getSize() {
-        return getSubspaceRegion().getSize();
-    }
+    extends Embedding<P, S> {
 
     /** Get the embedded subspace region.
      * @return the embedded subspace region

commons-geometry-core/src/main/java/org/apache/commons/geometry/core/internal/HyperplaneSubsets.java

@@ -0,0 +1,89 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.geometry.core.internal;
+
+import org.apache.commons.geometry.core.Point;
+import org.apache.commons.geometry.core.Region;
+import org.apache.commons.geometry.core.RegionLocation;
+import org.apache.commons.geometry.core.partitioning.EmbeddingHyperplane;
+
+/** Utility methods for {@link org.apache.commons.geometry.core.partitioning.HyperplaneSubset}
+ * implementations.
+ */
+public final class HyperplaneSubsets {
+
+    /** Utility class; no instantiation. */
+    private HyperplaneSubsets() {
+    }
+
+    /** Classify a point against a region embedded in a hyperplane.
+     * @param <P> Point implementation class
+     * @param <S> Subspace point implementation class
+     * @param <H> Hyperplane implementation class
+     * @param <R> Region implementation class
+     * @param pt the point to classify
+     * @param hyperplane hyperplane containing the embedded region
+     * @param embeddedRegion embedded region to classify against
+     * @return the region location of the given point
+     */
+    public static <
+        P extends Point<P>,
+        S extends Point<S>,
+        H extends EmbeddingHyperplane<P, S>,
+        R extends Region<S>> RegionLocation classifyAgainstEmbeddedRegion(final P pt,
+                final H hyperplane, final R embeddedRegion) {
+
+        if (hyperplane.contains(pt)) {
+            final S subPoint = hyperplane.toSubspace(pt);
+
+            return embeddedRegion.classify(subPoint);
+        }
+
+        return RegionLocation.OUTSIDE;
+    }
+
+    /** Return the closest point to a given point in a region embedded in a hyperplane.
+     * @param <P> Point implementation class
+     * @param <S> Subspace point implementation class
+     * @param <H> Hyperplane implementation class
+     * @param <R> Region implementation class
+     * @param pt point to find the closest point to
+     * @param hyperplane hyperplane containing the embedded region
+     * @param embeddedRegion embedded region to find the closest point in
+     * @return the closest point to {@code pt} in the embedded region
+     */
+    public static <
+        P extends Point<P>,
+        S extends Point<S>,
+        H extends EmbeddingHyperplane<P, S>,
+        R extends Region<S>> P closestToEmbeddedRegion(final P pt,
+                final H hyperplane, final R embeddedRegion) {
+
+        final S subPt = hyperplane.toSubspace(pt);
+
+        if (embeddedRegion.contains(subPt)) {
+            return hyperplane.toSpace(subPt);
+        }
+
+        final S subProjected = embeddedRegion.project(subPt);
+        if (subProjected != null) {
+            return hyperplane.toSpace(subProjected);
+        }
+
+        return null;
+    }
+}

commons-geometry-core/src/main/java/org/apache/commons/geometry/core/partitioning/HyperplaneSubset.java

@@ -23,12 +23,26 @@
 import org.apache.commons.geometry.core.Sized;
 import org.apache.commons.geometry.core.Transform;
 
-/** Interface representing a subset of the points lying on a hyperplane. Examples include
+/** Interface representing a subset of the points lying in a hyperplane. Examples include
  * rays and line segments in Euclidean 2D space and triangular facets in Euclidean 3D space.
  * Hyperplane subsets can have finite or infinite size and can represent contiguous regions
  * of the hyperplane (as in the examples aboves); multiple, disjoint regions; or the
  * {@link Hyperplane#span() entire hyperplane}.
  *
+ * <p>This interface is very similar to the {@link org.apache.commons.geometry.core.Region Region}
+ * interface but has slightly different semantics. Whereas {@code Region} instances represent sets
+ * of points that can expand through all of the dimensions of a space, {@code HyperplaneSubset} instances
+ * are constrained to their containing hyperplane and are more accurately defined as {@code Region}s
+ * of the {@code n-1} dimension subspace defined by the hyperplane. This makes the methods of this interface
+ * have slightly different meanings as compared to their {@code Region} counterparts. For example, consider
+ * a triangular facet in Euclidean 3D space. The {@link #getSize()} method of this hyperplane subset does
+ * not return the <em>volume</em> of the instance (which would be {@code 0}) as a regular 3D region would, but
+ * rather returns the <em>area</em> of the 2D polygon defined by the facet. Similarly, the {@link #classify(Point)}
+ * method returns {@link RegionLocation#INSIDE} for points that lie inside of the 2D polygon defined by the
+ * facet, instead of the {@link RegionLocation#BOUNDARY} value that would be expected if the facet was considered
+ * as a true 3D region with zero thickness.
+ * </p>
+ *
  * @param <P> Point implementation type
  * @see Hyperplane
  */
@@ -51,6 +65,13 @@ public interface HyperplaneSubset<P extends Point<P>> extends Splittable<P, Hype
      */
     boolean isEmpty();
 
+    /** Get the barycenter of the hyperplane subset or null if no barycenter exists or
+     * one exists but is not unique. A barycenter will not exist for empty or
+     * infinite hyperplane subsets.
+     * @return the barycenter of the hyperplane subset or null if no unique barycenter exists
+     */
+    P getBarycenter();
+
     /** Classify a point with respect to the subset region. The point is classified as follows:
      * <ul>
      *  <li>{@link RegionLocation#INSIDE INSIDE} - The point lies on the hyperplane
@@ -99,7 +120,9 @@ default boolean contains(P pt) {
      */
     HyperplaneSubset<P> transform(Transform<P> transform);
 
-    /** Convert this instance into a list of convex child subsets.
+    /** Convert this instance into a list of convex child subsets representing the same region.
+     * Implementations are not required to return an optimal convex subdivision of the current
+     * instance. They are free to return whatever subdivision is readily available.
      * @return a list of hyperplane convex subsets representing the same subspace
      *      region as this instance
      */

commons-geometry-core/src/test/java/org/apache/commons/geometry/core/EmbeddingTest.java

@@ -20,10 +20,10 @@
 import java.util.Arrays;
 import java.util.List;
 
-import org.apache.commons.geometry.core.partition.test.PartitionTestUtils;
-import org.apache.commons.geometry.core.partition.test.TestLine;
-import org.apache.commons.geometry.core.partition.test.TestPoint1D;
-import org.apache.commons.geometry.core.partition.test.TestPoint2D;
+import org.apache.commons.geometry.core.partitioning.test.PartitionTestUtils;
+import org.apache.commons.geometry.core.partitioning.test.TestLine;
+import org.apache.commons.geometry.core.partitioning.test.TestPoint1D;
+import org.apache.commons.geometry.core.partitioning.test.TestPoint2D;
 import org.junit.Assert;
 import org.junit.Test;