Plane (Apache Commons Geometry Euclidean 1.0 API)

java.lang.Object
- org.apache.commons.geometry.core.partitioning.AbstractHyperplane<Vector3D>
- - org.apache.commons.geometry.euclidean.threed.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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`contains(Line3D line)` Check if the instance contains a line.
`boolean`	`contains(Plane plane)` Check if the instance contains another plane.
`boolean`	`contains(Vector3D p)` Check if the instance contains a point.
`boolean`	`eq(Plane other, Precision.DoubleEquivalence precision)` Return true if this instance should be considered equivalent to the argument, using the given precision context for comparison.
`boolean`	`equals(Object obj)`
`EmbeddingPlane`	`getEmbedding()` Return an `EmbeddingPlane` instance suitable for embedding 2D geometric objects into this plane.
`Vector3D.Unit`	`getNormal()` Get the plane normal vector.
`Vector3D`	`getOrigin()` Get the orthogonal projection of the 3D-space origin in the plane.
`double`	`getOriginOffset()` Get the offset of the spatial origin (`0, 0, 0`) with respect to the plane.
`int`	`hashCode()`
`Vector3D`	`intersection(Line3D line)` Get the intersection of a line with this plane.
`Line3D`	`intersection(Plane other)` Get the line formed by the intersection of this instance with the given plane.
`static Vector3D`	`intersection(Plane plane1, Plane plane2, Plane plane3)` Get the intersection point of three planes.
`boolean`	`isParallel(Line3D line)` Check if the line is parallel to the instance.
`boolean`	`isParallel(Plane plane)` Check if the plane is parallel to the instance.
`double`	`offset(Line3D line)` Get the offset (oriented distance) of the given line with respect to the plane.
`double`	`offset(Plane plane)` Get the offset (oriented distance) of the given plane with respect to this instance.
`double`	`offset(Vector3D point)`
`Line3D`	`project(Line3D line)` Project a 3D line onto the plane.
`Vector3D`	`project(Vector3D point)`
`Plane`	`reverse()` Build a new reversed version of this plane, with opposite orientation.
`Plane`	`rotate(Vector3D center, QuaternionRotation rotation)` Rotate the plane around the specified point.
`boolean`	`similarOrientation(Hyperplane<Vector3D> other)`
`PlaneConvexSubset`	`span()`
`String`	`toString()`
`Plane`	`transform(Transform<Vector3D> transform)`
`Plane`	`translate(Vector3D translation)` Translate the plane by the specified amount.

Methods inherited from class org.apache.commons.geometry.core.partitioning.AbstractHyperplane
classify, getPrecision

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- 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)
```
  - 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
```
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()
```
  - 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)
```
  - 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 n₁ x n₂, where n₁ is the normal of the current instance and n₂ 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)
```
    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)
 
```
  - 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,
                  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 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

Class Plane

Method Summary

Methods inherited from class org.apache.commons.geometry.core.partitioning.AbstractHyperplane

Methods inherited from class java.lang.Object

Method Detail

getOrigin

getOriginOffset

getNormal

getEmbedding

offset

offset

offset

contains

contains

contains

project

project

span

isParallel

isParallel

similarOrientation

intersection

intersection

reverse

transform

translate

rotate

eq

hashCode

equals

toString

intersection