You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by er...@apache.org on 2019/05/20 13:39:19 UTC
[commons-geometry] 06/16: GEOMETRY-29 improves javadoc. Adds tests.
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 8a10b16dd01c69cc1dd5d31dd09bfd93b1ac40b5
Author: Sven Rathgeber <sv...@dfs.de>
AuthorDate: Sun Mar 24 06:24:09 2019 +0100
GEOMETRY-29 improves javadoc. Adds tests.
---
.../commons/geometry/euclidean/threed/Plane.java | 54 +++++++++++++---------
.../geometry/euclidean/threed/Vector3D.java | 2 +-
.../geometry/euclidean/threed/PlaneTest.java | 21 +++++++++
3 files changed, 53 insertions(+), 24 deletions(-)
diff --git a/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/Plane.java b/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/Plane.java
index 45ff084..150e7dc 100644
--- a/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/Plane.java
+++ b/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/Plane.java
@@ -32,49 +32,53 @@ import org.apache.commons.geometry.euclidean.twod.Vector2D;
*/
public final class Plane implements Hyperplane<Vector3D>, Embedding<Vector3D, Vector2D> {
- /** Offset of the origin with respect to the plane. */
- private final double originOffset;
-
- /** orthogonal projection of the 3D-space origin in the plane. */
- private final Vector3D projectedOrigin;
-
- /** First vector of the plane frame (in plane). */
+ /** First normalized vector of the plane frame (in plane). */
private final Vector3D u;
- /** Second vector of the plane frame (in plane). */
+ /** Second normalized vector of the plane frame (in plane). */
private final Vector3D v;
- /** Third vector of the plane frame (normalized plane normal). */
+ /** Normalized plane normal. */
private final Vector3D w;
+ /** Offset of the origin with respect to the plane. */
+ private final double originOffset;
+
+ /** orthogonal projection of the 3D-space origin in the plane. */
+ private final Vector3D projectedOrigin;
+
/** Precision context used to compare floating point numbers. */
private final DoublePrecisionContext precision;
/**
- * Constructor, made private to prevent inheritance.
- *
- * Builds a new plane with the given values.
+ * Constructor to build a new plane with the given values.
+ * Made private to prevent inheritance.
* @param u u vector (on plane)
* @param v v vector (on plane)
* @param w unit normal vector
* @param projectedOrigin orthogonal projection of the 3D-space origin in the plane.
* @param precision precision context used to compare floating point values
- * @param precision the precision context
- * @throws IllegalArgumentException if the provided vectors are coplanar
+ * @throws IllegalArgumentException if the provided vectors are coplanar or not normalized
*/
private Plane(Vector3D u, Vector3D v, Vector3D w, Vector3D projectedOrigin, double originOffset,
DoublePrecisionContext precision) {
this.u = u;
this.v = v;
this.w = w;
+
+ if (!areVectorsNormalized(u, v, w, precision))
+ {
+ throw new IllegalArgumentException("Provided vectors must be normalized.");
+ }
if (Vector3D.areCoplanar(u, v, w, precision))
{
- throw new IllegalArgumentException("Provided vectors must not be a coplanar.");
+ throw new IllegalArgumentException("Provided vectors must not be coplanar.");
}
this.projectedOrigin = projectedOrigin;
this.originOffset = originOffset;
this.precision = precision;
}
+
/**
* Build a plane from a point and two (on plane) vectors.
@@ -84,6 +88,7 @@ public final class Plane implements Hyperplane<Vector3D>, Embedding<Vector3D, Ve
* @param precision precision context used to compare floating point values
* @return a new plane
* @throws IllegalNormException if the norm of the given values is zero, NaN, or infinite.
+ * @throws IllegalArgumentException if the provided vectors are collinear
*/
public static Plane fromPointAndPlaneVectors (Vector3D p, final Vector3D u, final Vector3D v, final DoublePrecisionContext precision)
{
@@ -101,10 +106,9 @@ public final class Plane implements Hyperplane<Vector3D>, Embedding<Vector3D, Ve
* @param normal normal direction to the plane
* @param precision precision context used to compare floating point values
* @return a new plane
- * @exception IllegalArgumentException if the normal norm is too small
+ * @throws IllegalNormException if the norm of the given values is zero, NaN, or infinite.
*/
- public static Plane fromNormal(final Vector3D normal, final DoublePrecisionContext precision)
- throws IllegalArgumentException {
+ public static Plane fromNormal(final Vector3D normal, final DoublePrecisionContext precision){
return fromPointAndNormal(Vector3D.ZERO, normal, precision);
}
@@ -115,10 +119,9 @@ public final class Plane implements Hyperplane<Vector3D>, Embedding<Vector3D, Ve
* @param normal normal direction to the plane
* @param precision precision context used to compare floating point values
* @return a new plane
- * @exception IllegalArgumentException if the normal norm is too small
+ * @throws IllegalNormException if the norm of the given values is zero, NaN, or infinite.
*/
- public static Plane fromPointAndNormal(final Vector3D p, final Vector3D normal, final DoublePrecisionContext precision)
- throws IllegalArgumentException {
+ public static Plane fromPointAndNormal(final Vector3D p, final Vector3D normal, final DoublePrecisionContext precision) {
Vector3D w = normal.normalize();
double originOffset = -p.dot(w);
Vector3D projectedOrigin = calculateOrigin(w, originOffset);
@@ -138,10 +141,10 @@ public final class Plane implements Hyperplane<Vector3D>, Embedding<Vector3D, Ve
* @param p3 third point belonging to the plane
* @param precision precision context used to compare floating point values
* @return a new plane
- * @exception IllegalArgumentException if the points do not constitute a plane
+ * @throws IllegalNormException if the points do not constitute a plane
*/
public static Plane fromPoints(final Vector3D p1, final Vector3D p2, final Vector3D p3,
- final DoublePrecisionContext precision) throws IllegalArgumentException {
+ final DoublePrecisionContext precision) {
return Plane.fromPointAndNormal(p1, p2.subtract(p1).cross(p3.subtract(p1)), precision);
}
@@ -642,4 +645,9 @@ public final class Plane implements Hyperplane<Vector3D>, Embedding<Vector3D, Ve
private static Vector3D calculateOrigin(Vector3D w, double originOffset) {
return w.multiply(-originOffset);
}
+
+ private boolean areVectorsNormalized(Vector3D u, Vector3D v, Vector3D w, DoublePrecisionContext precision) {
+ return precision.eq(u.normSq(), 1) && precision.eq(v.normSq(), 1) && precision.eq(w.normSq(), 1);
+ }
+
}
diff --git a/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/Vector3D.java b/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/Vector3D.java
index afd1e7f..c92c1ac 100644
--- a/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/Vector3D.java
+++ b/commons-geometry-euclidean/src/main/java/org/apache/commons/geometry/euclidean/threed/Vector3D.java
@@ -377,7 +377,7 @@ public class Vector3D extends MultiDimensionalEuclideanVector<Vector3D> {
* @param v second vector
* @param w third vector
* @param precision precision context used to compare floating point values
- * @return true if vectors a coplanar, false otherwise.
+ * @return true if vectors are coplanar, false otherwise.
*/
public static boolean areCoplanar(Vector3D u, Vector3D v, Vector3D w, DoublePrecisionContext precision)
{
diff --git a/commons-geometry-euclidean/src/test/java/org/apache/commons/geometry/euclidean/threed/PlaneTest.java b/commons-geometry-euclidean/src/test/java/org/apache/commons/geometry/euclidean/threed/PlaneTest.java
index bb5f9dc..ac0efae 100644
--- a/commons-geometry-euclidean/src/test/java/org/apache/commons/geometry/euclidean/threed/PlaneTest.java
+++ b/commons-geometry-euclidean/src/test/java/org/apache/commons/geometry/euclidean/threed/PlaneTest.java
@@ -16,6 +16,7 @@
*/
package org.apache.commons.geometry.euclidean.threed;
+import org.apache.commons.geometry.core.exception.IllegalNormException;
import org.apache.commons.geometry.core.precision.DoublePrecisionContext;
import org.apache.commons.geometry.core.precision.EpsilonDoublePrecisionContext;
import org.apache.commons.geometry.euclidean.threed.rotation.QuaternionRotation;
@@ -30,6 +31,26 @@ public class PlaneTest {
private static final DoublePrecisionContext TEST_PRECISION =
new EpsilonDoublePrecisionContext(TEST_EPS);
+ @Test(expected=IllegalArgumentException.class)
+ public void testUAndVAreIdentical() {
+ Plane.fromPointAndPlaneVectors(Vector3D.of(0, 0, 1), Vector3D.of(0, 0, 1), Vector3D.of(0, 0, 1), TEST_PRECISION);
+ }
+
+ @Test(expected=IllegalArgumentException.class)
+ public void testUAndVAreCollinear() {
+ Plane.fromPointAndPlaneVectors(Vector3D.of(0, 0, 1), Vector3D.of(0, 0, 1), Vector3D.of(0, 0, 2), TEST_PRECISION);
+ }
+
+ @Test(expected=IllegalArgumentException.class)
+ public void testUAndVAreCollinear2() {
+ Plane.fromPointAndPlaneVectors(Vector3D.of(0, 0, 1), Vector3D.of(0, 0, 1), Vector3D.of(0, 0, -2), TEST_PRECISION);
+ }
+
+ @Test(expected=IllegalNormException.class)
+ public void testPointsDoNotConstituteAPlane() {
+ Plane.fromPoints(Vector3D.of(0, 0, 1), Vector3D.of(0, 0, 1), Vector3D.of(0, 1, 0), TEST_PRECISION);
+ }
+
@Test
public void testContains() {
Plane p = Plane.fromPointAndNormal(Vector3D.of(0, 0, 1), Vector3D.of(0, 0, 1), TEST_PRECISION);