Class Plane
- 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 anormal
and anorigin 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)\)
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 bygetOrigin()
), is computed as \(-d \vec{n}\).Instances of this class are guaranteed to be immutable.
- See Also:
Planes
-
-
Field Summary
Fields Modifier and Type Field Description private Vector3D.Unit
normal
Plane normal.private double
originOffset
Offset of the origin with respect to the plane.
-
Constructor Summary
Constructors Constructor Description Plane(Vector3D.Unit normal, double originOffset, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Construct a plane from its component parts.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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, 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.boolean
equals(java.lang.Object obj)
EmbeddingPlane
getEmbedding()
Return anEmbeddingPlane
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)
Get the offset (oriented distance) of a point with respect to this instance.Line3D
project(Line3D line)
Project a 3D line onto the plane.Vector3D
project(Vector3D point)
Project a point onto this instance.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)
Return true if this instance has a similar orientation to the given hyperplane, meaning that they point in generally the same direction.PlaneConvexSubset
span()
Return aHyperplaneConvexSubset
spanning this entire hyperplane.java.lang.String
toString()
Plane
transform(Transform<Vector3D> transform)
Transform this instance using the givenTransform
.Plane
translate(Vector3D translation)
Translate the plane by the specified amount.-
Methods inherited from class org.apache.commons.geometry.core.partitioning.AbstractHyperplane
classify, getPrecision
-
-
-
-
Field Detail
-
normal
private final Vector3D.Unit normal
Plane normal.
-
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 vectororiginOffset
- offset of the origin with respect to the planeprecision
- 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 anEmbeddingPlane
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 interfaceHyperplane<Vector3D>
- Overrides:
contains
in classAbstractHyperplane<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 aHyperplaneConvexSubset
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 productn1 x n2
, wheren1
is the normal of the current instance andn2
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 givenTransform
.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 centerrotation
- 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 planeorigins
andnormals
.- Parameters:
other
- the point to compare withprecision
- 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 classjava.lang.Object
-
equals
public boolean equals(java.lang.Object obj)
- Overrides:
equals
in classjava.lang.Object
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.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 plane1plane2
- second plane2plane3
- third plane2- Returns:
- intersection point of the three planes or null if no unique intersection point exists
-
-