Class Plane

  • All Implemented Interfaces:
    Hyperplane<Vector3D>
    Direct Known Subclasses:
    EmbeddingPlane

    public class Plane
    extends AbstractHyperplane<Vector3D>
    Class representing a plane in 3 dimensional Euclidean space. Each plane is defined by a normal and an origin offset. If \(\vec{n}\) is the plane normal, \(d\) is the origin offset, and \(p\) and \(q\) are any points in the plane, then the following are true:
    • \(\lVert \vec{n} \rVert\) = 1
    • \(\vec{n} \cdot (p - q) = 0\)
    • \(d = - (\vec{n} \cdot q)\)
    In other words, the normal is a unit vector such that the dot product of the normal and the difference of any two points in the plane is always equal to \(0\). Similarly, the origin offset is equal to the negation of the dot product of the normal and any point in the plane. The projection of the origin onto the plane (given by getOrigin()), is computed as \(-d \vec{n}\).

    Instances of this class are guaranteed to be immutable.

    See Also:
    Planes
    • Field Detail

      • originOffset

        private final double originOffset
        Offset of the origin with respect to the plane.
    • Constructor Detail

      • Plane

        Plane​(Vector3D.Unit normal,
              double originOffset,
              org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Construct a plane from its component parts.
        Parameters:
        normal - unit normal vector
        originOffset - offset of the origin with respect to the plane
        precision - precision context used to compare floating point values
    • Method Detail

      • getOrigin

        public Vector3D getOrigin()
        Get the orthogonal projection of the 3D-space origin in the plane.
        Returns:
        the origin point of the plane frame (point closest to the 3D-space origin)
      • getOriginOffset

        public double getOriginOffset()
        Get the offset of the spatial origin (0, 0, 0) with respect to the plane.
        Returns:
        the offset of the origin with respect to the plane.
      • getNormal

        public Vector3D.Unit getNormal()
        Get the plane normal vector.
        Returns:
        plane normal vector
      • getEmbedding

        public EmbeddingPlane getEmbedding()
        Return an EmbeddingPlane instance suitable for embedding 2D geometric objects into this plane. Returned instances are guaranteed to be equal between invocations.
        Returns:
        a plane instance suitable for embedding 2D subspaces
      • offset

        public double offset​(Vector3D point)
        Get the offset (oriented distance) of a point with respect to this instance. Points with an offset of zero lie on the hyperplane itself.
        Parameters:
        point - the point to compute the offset for
        Returns:
        the offset of the point
      • offset

        public double offset​(Line3D line)
        Get the offset (oriented distance) of the given line with respect to the plane. The value closest to zero is returned, which will always be zero if the line is not parallel to the plane.
        Parameters:
        line - line to calculate the offset of
        Returns:
        the offset of the line with respect to the plane or 0.0 if the line is not parallel to the plane.
      • offset

        public double offset​(Plane plane)
        Get the offset (oriented distance) of the given plane with respect to this instance. The value closest to zero is returned, which will always be zero if the planes are not parallel.
        Parameters:
        plane - plane to calculate the offset of
        Returns:
        the offset of the plane with respect to this instance or 0.0 if the planes are not parallel.
      • contains

        public boolean contains​(Line3D line)
        Check if the instance contains a line.
        Parameters:
        line - line to check
        Returns:
        true if line is contained in this plane
      • contains

        public boolean contains​(Plane plane)
        Check if the instance contains another plane. Planes are considered similar if they contain the same points. This does not mean they are equal since they can have opposite normals.
        Parameters:
        plane - plane to which the instance is compared
        Returns:
        true if the planes are similar
      • project

        public Vector3D project​(Vector3D point)
        Project a point onto this instance.
        Parameters:
        point - the point to project
        Returns:
        the projection of the point onto this instance. The returned point lies on the hyperplane.
      • project

        public Line3D project​(Line3D line)
        Project a 3D line onto the plane.
        Parameters:
        line - the line to project
        Returns:
        the projection of the given line onto the plane.
      • isParallel

        public boolean isParallel​(Line3D line)
        Check if the line is parallel to the instance.
        Parameters:
        line - line to check.
        Returns:
        true if the line is parallel to the instance, false otherwise.
      • isParallel

        public boolean isParallel​(Plane plane)
        Check if the plane is parallel to the instance.
        Parameters:
        plane - plane to check.
        Returns:
        true if the plane is parallel to the instance, false otherwise.
      • similarOrientation

        public boolean similarOrientation​(Hyperplane<Vector3D> other)
        Return true if this instance has a similar orientation to the given hyperplane, meaning that they point in generally the same direction. This method is not used to determine exact equality of hyperplanes, but rather to determine whether two hyperplanes that contain the same points are parallel (point in the same direction) or anti-parallel (point in opposite directions).
        Parameters:
        other - the hyperplane to compare with
        Returns:
        true if the hyperplanes point in generally the same direction and could possibly be parallel
      • intersection

        public Vector3D intersection​(Line3D line)
        Get the intersection of a line with this plane.
        Parameters:
        line - line intersecting the instance
        Returns:
        intersection point between between the line and the instance (null if the line is parallel to the instance)
      • intersection

        public Line3D intersection​(Plane other)
        Get the line formed by the intersection of this instance with the given plane. The returned line lies in both planes and points in the direction of the cross product n1 x n2, where n1 is the normal of the current instance and n2 is the normal of the argument.

        Null is returned if the planes are parallel.

        Parameters:
        other - other plane
        Returns:
        line at the intersection of the instance and the other plane, or null if no such line exists
      • reverse

        public Plane reverse()
        Build a new reversed version of this plane, with opposite orientation.
        Returns:
        a new reversed plane
      • transform

        public Plane transform​(Transform<Vector3D> transform)
        Transform this instance using the given Transform.

        Instances are transformed by selecting 3 representative points from the plane, transforming them, and constructing a new plane from the transformed points. Since the normal is not transformed directly, but rather is constructed new from the transformed points, the relative orientations of points in the plane are preserved, even for transforms that do not preserve orientation. The example below shows a plane being transformed by a non-orientation-preserving transform. The normal of the transformed plane retains its counterclockwise relationship to the points in the plane, in contrast with the normal that is transformed directly by the transform.

         // construct a plane from 3 points; the normal will be selected such that the
         // points are ordered counterclockwise when looking down the plane normal.
         Vector3D p1 = Vector3D.of(0, 0, 0);
         Vector3D p2 = Vector3D.of(+1, 0, 0);
         Vector3D p3 = Vector3D.of(0, +1, 0);
        
         Plane plane = Planes.fromPoints(p1, p2, p3, precision); // normal is (0, 0, +1)
        
         // create a transform that negates all x-values; this transform does not
         // preserve orientation, i.e. it will convert a right-handed system into a left-handed
         // system and vice versa
         AffineTransformMatrix3D transform = AffineTransformMatrix3D.createScale(-1, 1,  1);
        
         // transform the plane
         Plane transformedPlane = plane.transform(transform);
        
         // the plane normal is oriented such that transformed points are still ordered
         // counterclockwise when looking down the plane normal; since the point (1, 0, 0) has
         // now become (-1, 0, 0), the normal has flipped to (0, 0, -1)
         transformedPlane.getNormal();
        
         // directly transform the original plane normal; the normal is unchanged by the transform
         // since the target space of the transform is left-handed
         AffineTransformMatrix3D normalTransform = transform.normalTransform();
         Vector3D directlyTransformedNormal = normalTransform.apply(plane.getNormal()); // (0, 0, +1)
         
        Parameters:
        transform - object to transform this instance with
        Returns:
        a new, transformed hyperplane
      • translate

        public Plane translate​(Vector3D translation)
        Translate the plane by the specified amount.
        Parameters:
        translation - translation to apply
        Returns:
        a new plane
      • rotate

        public Plane rotate​(Vector3D center,
                            QuaternionRotation rotation)
        Rotate the plane around the specified point.
        Parameters:
        center - rotation center
        rotation - 3-dimensional rotation
        Returns:
        a new plane
      • eq

        public boolean eq​(Plane other,
                          org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return true if this instance should be considered equivalent to the argument, using the given precision context for comparison. Instances are considered equivalent if they contain the same points, which is determined by comparing the plane origins and normals.
        Parameters:
        other - the point to compare with
        precision - precision context to use for the comparison
        Returns:
        true if this instance should be considered equivalent to the argument
        See Also:
        Vector3D.eq(Vector3D, Precision.DoubleEquivalence)
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • intersection

        public static Vector3D intersection​(Plane plane1,
                                            Plane plane2,
                                            Plane plane3)
        Get the intersection point of three planes. Returns null if no unique intersection point exists (ie, there are no intersection points or an infinite number).
        Parameters:
        plane1 - first plane1
        plane2 - second plane2
        plane3 - third plane2
        Returns:
        intersection point of the three planes or null if no unique intersection point exists