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 <[email protected]> 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);
