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:
  • Field Details

    • normal

      private final Vector3D.Unit normal
      Plane normal.
    • originOffset

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

    • 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 Details

    • 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(Vector3D p)
      Check if the instance contains a point.
      Specified by:
      contains in interface Hyperplane<Vector3D>
      Overrides:
      contains in class AbstractHyperplane<Vector3D>
      Parameters:
      p - point to check
      Returns:
      true if p belongs to the plane
    • 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.
    • span

      public PlaneConvexSubset span()
      Return a HyperplaneConvexSubset spanning this entire hyperplane. The returned subset contains all points lying in this hyperplane and no more.
      Returns:
      a HyperplaneConvexSubset containing all points lying in this hyperplane
    • 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:
    • hashCode

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

      public boolean equals(Object obj)
      Overrides:
      equals in class Object
    • toString

      public String toString()
      Overrides:
      toString in class 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