Top Description Fields Constructors Methods
org.apache.commons.math3.geometry.euclidean.threed

public Class Plane

extends Object
implements Hyperplane<Euclidean3D>, Embedding<Euclidean3D, Euclidean2D>
Class Inheritance
All Implemented Interfaces
org.apache.commons.math3.geometry.partitioning.Embedding, org.apache.commons.math3.geometry.partitioning.Hyperplane
Imports
org.apache.commons.math3.exception.MathArithmeticException, org.apache.commons.math3.exception.util.LocalizedFormats, org.apache.commons.math3.geometry.Point, .Vector, org.apache.commons.math3.geometry.euclidean.oned.Euclidean1D, .Vector1D, org.apache.commons.math3.geometry.euclidean.twod.Euclidean2D, .PolygonsSet, .Vector2D, org.apache.commons.math3.geometry.partitioning.Embedding, .Hyperplane, org.apache.commons.math3.util.FastMath

The class represent planes in a three dimensional space.
Since
3.0

Field Summary

Modifier and TypeField and Description
private static final double
DEFAULT_TOLERANCE

Default value for tolerance.

private Vector3D
origin

Origin of the plane frame.

private double
originOffset

Offset of the origin with respect to the plane.

private final double
tolerance

Tolerance below which points are considered identical.

private Vector3D
u

First vector of the plane frame (in plane).

private Vector3D
v

Second vector of the plane frame (in plane).

private Vector3D
w

Third vector of the plane frame (plane normal).

Constructor Summary

AccessConstructor and Description
public
Plane(final Vector3D
normal direction to the plane
normal
,
final double
tolerance below which points are considered identical
tolerance
)

Build a plane normal to a given direction and containing the origin.

public
Plane(final Vector3D
point belonging to the plane
p
,
final Vector3D
normal direction to the plane
normal
,
final double
tolerance below which points are considered identical
tolerance
)

Build a plane from a point and a normal.

public
Plane(final Vector3D
first point belonging to the plane
p1
,
final Vector3D
second point belonging to the plane
p2
,
final Vector3D
third point belonging to the plane
p3
,
final double
tolerance below which points are considered identical
tolerance
)

Build a plane from three points.

public
Plane(final Vector3D
normal direction to the plane
normal
)
Deprecated as of 3.3, replaced with Plane(Vector3D, double)

Build a plane normal to a given direction and containing the origin.

public
Plane(final Vector3D
point belonging to the plane
p
,
final Vector3D
normal direction to the plane
normal
)
Deprecated as of 3.3, replaced with Plane(Vector3D, Vector3D, double)

Build a plane from a point and a normal.

public
Plane(final Vector3D
first point belonging to the plane
p1
,
final Vector3D
second point belonging to the plane
p2
,
final Vector3D
third point belonging to the plane
p3
)
Deprecated as of 3.3, replaced with Plane(Vector3D, Vector3D, Vector3D, double)

Build a plane from three points.

public
Plane(final Plane
plane to copy
plane
)

Copy constructor.

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

true if p belongs to the plane
contains
(final Vector3D
point to check
p
)

Check if the instance contains a point.

public Plane

Returns:

a new hyperplane, copy of the instance
copySelf
()

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.copySelf.

Copy the instance.

public Vector3D

Returns:

normalized normal vector
getNormal
()

Get the normalized normal vector.

public double

Returns:

offset of the plane
getOffset
(final Plane
plane to check
plane
)

Get the offset (oriented distance) of a parallel plane.

public double

Returns:

offset of the vector
getOffset
(Vector<Euclidean3D>
vector to check
vector
)

Get the offset (oriented distance) of a vector.

public double

Returns:

offset of the point
getOffset
(final Point<Euclidean3D>
point to check
point
)

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.getOffset.

Get the offset (oriented distance) of a point.

public Vector3D

Returns:

the origin point of the plane frame (point closest to the 3D-space origin)
getOrigin
()

Get the origin point of the plane frame.

public Vector3D

Returns:

one point in the 3D-space, with given coordinates and offset relative to the plane
getPointAt
(final Vector2D
desired in-plane coordinates for the point in the plane
inPlane
,
final double
desired offset for the point
offset
)

Get one point from the 3D-space.

public double
getTolerance()

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.getTolerance.

Get the tolerance below which points are considered to belong to the hyperplane.

public Vector3D

Returns:

normalized first canonical vector
getU
()

Get the plane first canonical vector.

public Vector3D

Returns:

normalized second canonical vector
getV
()

Get the plane second canonical vector.

public Vector3D

Returns:

intersection point between between the line and the instance (null if the line is parallel to the instance)
intersection
(final Line
line intersecting the instance
line
)

Get the intersection of a line with the instance.

public Line

Returns:

line at the intersection of the instance and the other plane (really a Line instance)
intersection
(final Plane
other plane
other
)

Build the line shared by the instance and another plane.

public static Vector3D

Returns:

intersection point of three planes, null if some planes are parallel
intersection
(final Plane
first plane1
plane1
,
final Plane
second plane2
plane2
,
final Plane
third plane2
plane3
)

Get the intersection point of three planes.

public boolean

Returns:

true if the planes are similar
isSimilarTo
(final Plane
plane to which the instance is compared
plane
)

Check if the instance is similar to another plane.

public Point<Euclidean3D>
project(Point<Euclidean3D>
point to project
point
)

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.project.

Project a point to the hyperplane.

public void
reset(final Vector3D
point belonging to the plane
p
,
final Vector3D
normal direction to the plane
normal
)

Reset the instance as if built from a point and a normal.

public void
reset(final Plane
plane to reset from
original
)

Reset the instance from another one.

public void
revertSelf()

Revert the plane.

public Plane

Returns:

a new plane
rotate
(final Vector3D
rotation center
center
,
final Rotation
vectorial rotation operator
rotation
)

Rotate the plane around the specified point.

public boolean

Returns:

true if the instance and the other hyperplane have the same orientation
sameOrientationAs
(final Hyperplane<Euclidean3D>
other hyperplane to check against the instance
other
)

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.sameOrientationAs.

Check if the instance has the same orientation as another hyperplane.

private void
setFrame()

Reset the plane frame.

private void
setNormal(final Vector3D
normal direction to the plane (will be copied)
normal
)

Set the normal vactor.

public Vector3D

Returns:

n-dimension point of the space corresponding to the specified sub-space point
toSpace
(Vector<Euclidean2D>
(n-1)-dimension point of the sub-space
vector
)

Transform a sub-space point into a space point.

public Vector3D

Returns:

3D space point (really a Vector3D instance)
toSpace
(final Point<Euclidean2D>
in-plane point (must be a Vector2D instance)
point
)

Implements org.apache.commons.math3.geometry.partitioning.Embedding.toSpace.

Transform an in-plane point into a 3D space point.

public Vector2D

Returns:

(n-1)-dimension point of the sub-space corresponding to the specified space point
toSubSpace
(Vector<Euclidean3D>
n-dimension point of the space
vector
)

Transform a space point into a sub-space point.

public Vector2D

Returns:

in-plane point (really a Vector2D instance)
toSubSpace
(final Point<Euclidean3D>
point of the space (must be a Vector3D instance)
point
)

Implements org.apache.commons.math3.geometry.partitioning.Embedding.toSubSpace.

Transform a 3D space point into an in-plane point.

public Plane

Returns:

a new plane
translate
(final Vector3D
translation to apply
translation
)

Translate the plane by the specified amount.

public SubPlane

Returns:

a region covering the whole hyperplane
wholeHyperplane
()

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.wholeHyperplane.

Build a region covering the whole hyperplane.

public PolyhedronsSet

Returns:

a region containing the instance (really a PolyhedronsSet instance)
wholeSpace
()

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.wholeSpace.

Build a region covering the whole space.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

DEFAULT_TOLERANCEback to summary
private static final double DEFAULT_TOLERANCE

Default value for tolerance.

originback to summary
private Vector3D origin

Origin of the plane frame.

originOffsetback to summary
private double originOffset

Offset of the origin with respect to the plane.

toleranceback to summary
private final double tolerance

Tolerance below which points are considered identical.

uback to summary
private Vector3D u

First vector of the plane frame (in plane).

vback to summary
private Vector3D v

Second vector of the plane frame (in plane).

wback to summary
private Vector3D w

Third vector of the plane frame (plane normal).

Constructor Detail

Planeback to summary
public Plane(final Vector3D normal, final double tolerance) throws MathArithmeticException

Build a plane normal to a given direction and containing the origin.

Parameters
normal:Vector3D

normal direction to the plane

tolerance:double

tolerance below which points are considered identical

Exceptions
MathArithmeticException:
if the normal norm is too small
Since
3.3
Planeback to summary
public Plane(final Vector3D p, final Vector3D normal, final double tolerance) throws MathArithmeticException

Build a plane from a point and a normal.

Parameters
p:Vector3D

point belonging to the plane

normal:Vector3D

normal direction to the plane

tolerance:double

tolerance below which points are considered identical

Exceptions
MathArithmeticException:
if the normal norm is too small
Since
3.3
Planeback to summary
public Plane(final Vector3D p1, final Vector3D p2, final Vector3D p3, final double tolerance) throws MathArithmeticException

Build a plane from three points.

The plane is oriented in the direction of (p2-p1) ^ (p3-p1)

Parameters
p1:Vector3D

first point belonging to the plane

p2:Vector3D

second point belonging to the plane

p3:Vector3D

third point belonging to the plane

tolerance:double

tolerance below which points are considered identical

Exceptions
MathArithmeticException:
if the points do not constitute a plane
Since
3.3
Planeback to summary
public Plane(final Vector3D normal) throws MathArithmeticException

Deprecated

as of 3.3, replaced with Plane(Vector3D, double)

Build a plane normal to a given direction and containing the origin.

Parameters
normal:Vector3D

normal direction to the plane

Annotations
@Deprecated
Exceptions
MathArithmeticException:
if the normal norm is too small
Planeback to summary
public Plane(final Vector3D p, final Vector3D normal) throws MathArithmeticException

Deprecated

as of 3.3, replaced with Plane(Vector3D, Vector3D, double)

Build a plane from a point and a normal.

Parameters
p:Vector3D

point belonging to the plane

normal:Vector3D

normal direction to the plane

Annotations
@Deprecated
Exceptions
MathArithmeticException:
if the normal norm is too small
Planeback to summary
public Plane(final Vector3D p1, final Vector3D p2, final Vector3D p3) throws MathArithmeticException

Deprecated

as of 3.3, replaced with Plane(Vector3D, Vector3D, Vector3D, double)

Build a plane from three points.

The plane is oriented in the direction of (p2-p1) ^ (p3-p1)

Parameters
p1:Vector3D

first point belonging to the plane

p2:Vector3D

second point belonging to the plane

p3:Vector3D

third point belonging to the plane

Annotations
@Deprecated
Exceptions
MathArithmeticException:
if the points do not constitute a plane
Planeback to summary
public Plane(final Plane plane)

Copy constructor.

The instance created is completely independant of the original one. A deep copy is used, none of the underlying object are shared.

Parameters
plane:Plane

plane to copy

Method Detail

containsback to summary
public boolean contains(final Vector3D p)

Check if the instance contains a point.

Parameters
p:Vector3D

point to check

Returns:boolean

true if p belongs to the plane

copySelfback to summary
public Plane copySelf()

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.copySelf.

Copy the instance.

The instance created is completely independant of the original one. A deep copy is used, none of the underlying objects are shared (except for immutable objects).

Returns:Plane

a new hyperplane, copy of the instance

getNormalback to summary
public Vector3D getNormal()

Get the normalized normal vector.

The frame defined by (getU, getV, getNormal) is a rigth-handed orthonormalized frame).

Returns:Vector3D

normalized normal vector

See Also
getU, getV
getOffsetback to summary
public double getOffset(final Plane plane)

Get the offset (oriented distance) of a parallel plane.

This method should be called only for parallel planes otherwise the result is not meaningful.

The offset is 0 if both planes are the same, it is positive if the plane is on the plus side of the instance and negative if it is on the minus side, according to its natural orientation.

Parameters
plane:Plane

plane to check

Returns:double

offset of the plane

getOffsetback to summary
public double getOffset(Vector<Euclidean3D> vector)

Get the offset (oriented distance) of a vector.

Parameters
vector:Vector<Euclidean3D>

vector to check

Returns:double

offset of the vector

getOffsetback to summary
public double getOffset(final Point<Euclidean3D> point)

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.getOffset.

Get the offset (oriented distance) of a point.

The offset is 0 if the point is on the underlying hyperplane, it is positive if the point is on one particular side of the hyperplane, and it is negative if the point is on the other side, according to the hyperplane natural orientation.

Parameters
point:Point<Euclidean3D>

point to check

Returns:double

offset of the point

getOriginback to summary
public Vector3D getOrigin()

Get the origin point of the plane frame.

The point returned is the orthogonal projection of the 3D-space origin in the plane.

Returns:Vector3D

the origin point of the plane frame (point closest to the 3D-space origin)

getPointAtback to summary
public Vector3D getPointAt(final Vector2D inPlane, final double offset)

Get one point from the 3D-space.

Parameters
inPlane:Vector2D

desired in-plane coordinates for the point in the plane

offset:double

desired offset for the point

Returns:Vector3D

one point in the 3D-space, with given coordinates and offset relative to the plane

getToleranceback to summary
public double getTolerance()

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.getTolerance.

Doc from org.apache.commons.math3.geometry.partitioning.Hyperplane.getTolerance.

Get the tolerance below which points are considered to belong to the hyperplane.

Returns:double

tolerance below which points are considered to belong to the hyperplane

Since
3.3
getUback to summary
public Vector3D getU()

Get the plane first canonical vector.

The frame defined by (getU, getV, getNormal) is a rigth-handed orthonormalized frame).

Returns:Vector3D

normalized first canonical vector

See Also
getV, getNormal
getVback to summary
public Vector3D getV()

Get the plane second canonical vector.

The frame defined by (getU, getV, getNormal) is a rigth-handed orthonormalized frame).

Returns:Vector3D

normalized second canonical vector

See Also
getU, getNormal
intersectionback to summary
public Vector3D intersection(final Line line)

Get the intersection of a line with the instance.

Parameters
line:Line

line intersecting the instance

Returns:Vector3D

intersection point between between the line and the instance (null if the line is parallel to the instance)

intersectionback to summary
public Line intersection(final Plane other)

Build the line shared by the instance and another plane.

Parameters
other:Plane

other plane

Returns:Line

line at the intersection of the instance and the other plane (really a Line instance)

intersectionback to summary
public static Vector3D intersection(final Plane plane1, final Plane plane2, final Plane plane3)

Get the intersection point of three planes.

Parameters
plane1:Plane

first plane1

plane2:Plane

second plane2

plane3:Plane

third plane2

Returns:Vector3D

intersection point of three planes, null if some planes are parallel

isSimilarToback to summary
public boolean isSimilarTo(final Plane plane)

Check if the instance is similar to 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

plane to which the instance is compared

Returns:boolean

true if the planes are similar

projectback to summary
public Point<Euclidean3D> project(Point<Euclidean3D> point)

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.project.

Doc from org.apache.commons.math3.geometry.partitioning.Hyperplane.project.

Project a point to the hyperplane.

Parameters
point:Point<Euclidean3D>

point to project

Returns:Point<Euclidean3D>

projected point

Since
3.3
resetback to summary
public void reset(final Vector3D p, final Vector3D normal) throws MathArithmeticException

Reset the instance as if built from a point and a normal.

Parameters
p:Vector3D

point belonging to the plane

normal:Vector3D

normal direction to the plane

Exceptions
MathArithmeticException:
if the normal norm is too small
resetback to summary
public void reset(final Plane original)

Reset the instance from another one.

The updated instance is completely independant of the original one. A deep reset is used none of the underlying object is shared.

Parameters
original:Plane

plane to reset from

revertSelfback to summary
public void revertSelf()

Revert the plane.

Replace the instance by a similar plane with opposite orientation.

The new plane frame is chosen in such a way that a 3D point that had (x, y) in-plane coordinates and z offset with respect to the plane and is unaffected by the change will have (y, x) in-plane coordinates and -z offset with respect to the new plane. This means that the u and v vectors returned by the getU and getV methods are exchanged, and the w vector returned by the getNormal method is reversed.

rotateback to summary
public Plane rotate(final Vector3D center, final Rotation rotation)

Rotate the plane around the specified point.

The instance is not modified, a new instance is created.

Parameters
center:Vector3D

rotation center

rotation:Rotation

vectorial rotation operator

Returns:Plane

a new plane

sameOrientationAsback to summary
public boolean sameOrientationAs(final Hyperplane<Euclidean3D> other)

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.sameOrientationAs.

Check if the instance has the same orientation as another hyperplane.

Parameters
other:Hyperplane<Euclidean3D>

other hyperplane to check against the instance

Returns:boolean

true if the instance and the other hyperplane have the same orientation

setFrameback to summary
private void setFrame()

Reset the plane frame.

setNormalback to summary
private void setNormal(final Vector3D normal) throws MathArithmeticException

Set the normal vactor.

Parameters
normal:Vector3D

normal direction to the plane (will be copied)

Exceptions
MathArithmeticException:
if the normal norm is too small
toSpaceback to summary
public Vector3D toSpace(Vector<Euclidean2D> vector)

Transform a sub-space point into a space point.

Parameters
vector:Vector<Euclidean2D>

(n-1)-dimension point of the sub-space

Returns:Vector3D

n-dimension point of the space corresponding to the specified sub-space point

toSpaceback to summary
public Vector3D toSpace(final Point<Euclidean2D> point)

Implements org.apache.commons.math3.geometry.partitioning.Embedding.toSpace.

Transform an in-plane point into a 3D space point.

Parameters
point:Point<Euclidean2D>

in-plane point (must be a Vector2D instance)

Returns:Vector3D

3D space point (really a Vector3D instance)

See Also
toSubSpace
toSubSpaceback to summary
public Vector2D toSubSpace(Vector<Euclidean3D> vector)

Transform a space point into a sub-space point.

Parameters
vector:Vector<Euclidean3D>

n-dimension point of the space

Returns:Vector2D

(n-1)-dimension point of the sub-space corresponding to the specified space point

toSubSpaceback to summary
public Vector2D toSubSpace(final Point<Euclidean3D> point)

Implements org.apache.commons.math3.geometry.partitioning.Embedding.toSubSpace.

Transform a 3D space point into an in-plane point.

Parameters
point:Point<Euclidean3D>

point of the space (must be a Vector3D instance)

Returns:Vector2D

in-plane point (really a Vector2D instance)

See Also
toSpace
translateback to summary
public Plane translate(final Vector3D translation)

Translate the plane by the specified amount.

The instance is not modified, a new instance is created.

Parameters
translation:Vector3D

translation to apply

Returns:Plane

a new plane

wholeHyperplaneback to summary
public SubPlane wholeHyperplane()

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.wholeHyperplane.

Build a region covering the whole hyperplane.

Returns:SubPlane

a region covering the whole hyperplane

wholeSpaceback to summary
public PolyhedronsSet wholeSpace()

Implements org.apache.commons.math3.geometry.partitioning.Hyperplane.wholeSpace.

Build a region covering the whole space.

Returns:PolyhedronsSet

a region containing the instance (really a PolyhedronsSet instance)