This is an automated email from the ASF dual-hosted git repository.
erans pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-geometry.git
commit 1b97c16a2513470c5adf4436b44edacb3afc3682
Author: Matt Juntunen <matt.juntu...@hotmail.com>
AuthorDate: Wed Jan 15 22:44:20 2020 -0500
GEOMETRY-85: adding user guide entry for the enclosing module
---
commons-geometry-enclosing/pom.xml | 9 +++
.../enclosing/DocumentationExamplesTest.java | 65 ++++++++++++++++++++++
.../geometry/hull/DocumentationExamplesTest.java | 3 +
src/site/site.xml | 1 +
src/site/xdoc/userguide/index.xml | 57 +++++++++++++++++++
5 files changed, 135 insertions(+)
diff --git a/commons-geometry-enclosing/pom.xml
b/commons-geometry-enclosing/pom.xml
index 0a33c22..c0efa07 100644
--- a/commons-geometry-enclosing/pom.xml
+++ b/commons-geometry-enclosing/pom.xml
@@ -71,6 +71,15 @@
<dependency>
<groupId>org.apache.commons</groupId>
+ <artifactId>commons-geometry-euclidean</artifactId>
+ <version>${project.version}</version>
+ <classifier>tests</classifier>
+ <type>test-jar</type>
+ <scope>test</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.commons</groupId>
<artifactId>commons-rng-client-api</artifactId>
<scope>test</scope>
</dependency>
diff --git
a/commons-geometry-enclosing/src/test/java/org/apache/commons/geometry/enclosing/DocumentationExamplesTest.java
b/commons-geometry-enclosing/src/test/java/org/apache/commons/geometry/enclosing/DocumentationExamplesTest.java
new file mode 100644
index 0000000..e453984
--- /dev/null
+++
b/commons-geometry-enclosing/src/test/java/org/apache/commons/geometry/enclosing/DocumentationExamplesTest.java
@@ -0,0 +1,65 @@
+/*
+ * 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.enclosing;
+
+import java.util.Arrays;
+import java.util.List;
+
+import org.apache.commons.geometry.core.precision.DoublePrecisionContext;
+import
org.apache.commons.geometry.core.precision.EpsilonDoublePrecisionContext;
+import org.apache.commons.geometry.enclosing.euclidean.threed.WelzlEncloser3D;
+import org.apache.commons.geometry.euclidean.EuclideanTestUtils;
+import org.apache.commons.geometry.euclidean.threed.Vector3D;
+import org.junit.Assert;
+import org.junit.Test;
+
+/** This class contains code listed as examples in the user guide and other
documentation.
+ * If any portion of this code changes, the corresponding examples in the
documentation <em>must</em> be updated.
+ */
+public class DocumentationExamplesTest {
+
+ private static final double TEST_EPS = 1e-10;
+
+ @Test
+ public void testWelzlEncloser3DExample() {
+ DoublePrecisionContext precision = new
EpsilonDoublePrecisionContext(1e-10);
+
+ List<Vector3D> points = Arrays.asList(
+ Vector3D.of(0, 0, 1),
+ Vector3D.of(0.75, 0, 1),
+ Vector3D.of(2, 0, 1),
+ Vector3D.of(1, 0, 2)
+ );
+
+ // compute the enclosing ball
+ WelzlEncloser3D encloser = new WelzlEncloser3D(precision);
+
+ EnclosingBall<Vector3D> sphere = encloser.enclose(points);
+
+ // check the generated ball
+ Vector3D center = sphere.getCenter(); // (1, 0, 1)
+ double radius = sphere.getRadius(); // 1.0
+ boolean containsCenter = sphere.contains(center); // true
+ boolean containsOrigin = sphere.contains(Vector3D.ZERO); // false
+
+ // ----------
+ EuclideanTestUtils.assertCoordinatesEqual(Vector3D.of(1, 0, 1),
center, TEST_EPS);
+ Assert.assertEquals(1.0, radius, TEST_EPS);
+ Assert.assertTrue(containsCenter);
+ Assert.assertFalse(containsOrigin);
+ }
+}
diff --git
a/commons-geometry-hull/src/test/java/org/apache/commons/geometry/hull/DocumentationExamplesTest.java
b/commons-geometry-hull/src/test/java/org/apache/commons/geometry/hull/DocumentationExamplesTest.java
index 5df2d86..725bc76 100644
---
a/commons-geometry-hull/src/test/java/org/apache/commons/geometry/hull/DocumentationExamplesTest.java
+++
b/commons-geometry-hull/src/test/java/org/apache/commons/geometry/hull/DocumentationExamplesTest.java
@@ -29,6 +29,9 @@ import
org.apache.commons.geometry.hull.euclidean.twod.MonotoneChain;
import org.junit.Assert;
import org.junit.Test;
+/** This class contains code listed as examples in the user guide and other
documentation.
+ * If any portion of this code changes, the corresponding examples in the
documentation <em>must</em> be updated.
+ */
public class DocumentationExamplesTest {
private static final double TEST_EPS = 1e-15;
diff --git a/src/site/site.xml b/src/site/site.xml
index 237ef41..d845328 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -76,6 +76,7 @@
<item name="Euclidean Space" href="/userguide/index.html#euclidean"/>
<item name="Spherical Space" href="/userguide/index.html#spherical"/>
<item name="Convex Hull" href="/userguide/index.html#hull"/>
+ <item name="Enclosing" href="/userguide/index.html#enclosing"/>
</menu>
</body>
diff --git a/src/site/xdoc/userguide/index.xml
b/src/site/xdoc/userguide/index.xml
index 1ddfe22..6a06a1d 100644
--- a/src/site/xdoc/userguide/index.xml
+++ b/src/site/xdoc/userguide/index.xml
@@ -84,6 +84,9 @@
</li>
</ul>
</li>
+ <li>
+ <a href="#enclosing">Enclosing</a>
+ </li>
</ul>
</section>
@@ -1110,6 +1113,60 @@ boolean containsAll =
pts.stream().allMatch(region::contains); // true - region
</subsection>
</section>
+ <section name="Enclosing" id="enclosing">
+ <p>
+ The <a href="https://en.wikipedia.org/wiki/Bounding_sphere";>smallest
enclosing ball problem</a> is the
+ mathematical problem of locating the n-sphere with the smallest radius
that encloses a given set of points.
+ This module contains implementations of algorithms for solving this
problem.
+ </p>
+
+ <h4>Primary Classes</h4>
+ <ul>
+ <li>
+ <a class="code"
href="../commons-geometry-enclosing/apidocs/org/apache/commons/geometry/enclosing/Encloser.html">Encloser</a>
-
+ Interface for classes that solve the smallest enclosing ball problem.
+ </li>
+ <li>
+ <a class="code"
href="../commons-geometry-enclosing/apidocs/org/apache/commons/geometry/enclosing/EnclosingBall.html">EnclosingBall</a>
-
+ Class containing the result of smallest enclosing ball computation.
+ </li>
+ <li>
+ <a class="code"
href="../commons-geometry-enclosing/apidocs/org/apache/commons/geometry/enclosing/WelzlEncloser.html">WelzlEncloser</a>
-
+ Class implementing a space-independent version of
+ <a
href="http://www.inf.ethz.ch/personal/emo/PublFiles/SmallEnclDisk_LNCS555_91.pdf";>Emo
Welzl's algorithm</a>
+ for computing the smallest enclosing ball of a set of points.
Specialized classes exist for Euclidean 2D space
+ (<a class="code"
href="../commons-geometry-enclosing/apidocs/org/apache/commons/geometry/enclosing/euclidean/twod/WelzlEncloser2D.html">WelzlEncloser2D</a>)
+ and Euclidean 3D space
+ (<a class="code"
href="../commons-geometry-enclosing/apidocs/org/apache/commons/geometry/enclosing/euclidean/threed/WelzlEncloser3D.html">WelzlEncloser3D</a>).
+ </li>
+ </ul>
+
+ <h4>Examples</h4>
+
+ <h5>WelzlEncloser3D</h5>
+ <source>
+DoublePrecisionContext precision = new EpsilonDoublePrecisionContext(1e-10);
+
+List<Vector3D> points = Arrays.asList(
+ Vector3D.of(0, 0, 1),
+ Vector3D.of(0.75, 0, 1),
+ Vector3D.of(2, 0, 1),
+ Vector3D.of(1, 0, 2)
+ );
+
+// compute the enclosing ball
+WelzlEncloser3D encloser = new WelzlEncloser3D(precision);
+
+EnclosingBall<Vector3D> sphere = encloser.enclose(points);
+
+// check the generated ball
+Vector3D center = sphere.getCenter(); // (1, 0, 1)
+double radius = sphere.getRadius(); // 1.0
+boolean containsCenter = sphere.contains(center); // true
+boolean containsOrigin = sphere.contains(Vector3D.ZERO); // false
+ </source>
+ </section>
+
</body>
</document>
