Package org.apache.commons.math3.geometry.euclidean.threed

Class Plane

java.lang.Object

org.apache.commons.math3.geometry.euclidean.threed.Plane

All Implemented Interfaces:

Embedding<Euclidean3D,Euclidean2D>, Hyperplane<Euclidean3D>

public class Plane
extends java.lang.Object
implements Hyperplane<Euclidean3D>, Embedding<Euclidean3D,Euclidean2D>

The class represent planes in a three dimensional space.

Since:

3.0

Field Summary

Fields

Modifier and Type	Field	Description
private static 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 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

Constructors

Constructor	Description
Plane(Plane plane)	Copy constructor.
Plane(Vector3D normal)	Deprecated. as of 3.3, replaced with Plane(Vector3D, double)
Plane(Vector3D normal, double tolerance)	Build a plane normal to a given direction and containing the origin.
Plane(Vector3D p, Vector3D normal)	Deprecated. as of 3.3, replaced with Plane(Vector3D, Vector3D, double)
Plane(Vector3D p, Vector3D normal, double tolerance)	Build a plane from a point and a normal.
Plane(Vector3D p1, Vector3D p2, Vector3D p3)	Deprecated. as of 3.3, replaced with Plane(Vector3D, Vector3D, Vector3D, double)
Plane(Vector3D p1, Vector3D p2, Vector3D p3, double tolerance)	Build a plane from three points.

Method Summary

Modifier and Type	Method	Description
boolean	contains(Vector3D p)	Check if the instance contains a point.
Plane	copySelf()	Copy the instance.
Vector3D	getNormal()	Get the normalized normal vector.
double	getOffset(Plane plane)	Get the offset (oriented distance) of a parallel plane.
double	getOffset(Point<Euclidean3D> point)	Get the offset (oriented distance) of a point.
double	getOffset(Vector<Euclidean3D> vector)	Get the offset (oriented distance) of a vector.
Vector3D	getOrigin()	Get the origin point of the plane frame.
Vector3D	getPointAt(Vector2D inPlane, double offset)	Get one point from the 3D-space.
double	getTolerance()	Get the tolerance below which points are considered to belong to the hyperplane.
Vector3D	getU()	Get the plane first canonical vector.
Vector3D	getV()	Get the plane second canonical vector.
Vector3D	intersection(Line line)	Get the intersection of a line with the instance.
Line	intersection(Plane other)	Build the line shared by the instance and another plane.
static Vector3D	intersection(Plane plane1, Plane plane2, Plane plane3)	Get the intersection point of three planes.
boolean	isSimilarTo(Plane plane)	Check if the instance is similar to another plane.
Point<Euclidean3D>	project(Point<Euclidean3D> point)	Project a point to the hyperplane.
void	reset(Plane original)	Reset the instance from another one.
void	reset(Vector3D p, Vector3D normal)	Reset the instance as if built from a point and a normal.
void	revertSelf()	Revert the plane.
Plane	rotate(Vector3D center, Rotation rotation)	Rotate the plane around the specified point.
boolean	sameOrientationAs(Hyperplane<Euclidean3D> other)	Check if the instance has the same orientation as another hyperplane.
private void	setFrame()	Reset the plane frame.
private void	setNormal(Vector3D normal)	Set the normal vactor.
Vector3D	toSpace(Point<Euclidean2D> point)	Transform an in-plane point into a 3D space point.
Vector3D	toSpace(Vector<Euclidean2D> vector)	Transform a sub-space point into a space point.
Vector2D	toSubSpace(Point<Euclidean3D> point)	Transform a 3D space point into an in-plane point.
Vector2D	toSubSpace(Vector<Euclidean3D> vector)	Transform a space point into a sub-space point.
Plane	translate(Vector3D translation)	Translate the plane by the specified amount.
SubPlane	wholeHyperplane()	Build a region covering the whole hyperplane.
PolyhedronsSet	wholeSpace()	Build a region covering the whole space.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_TOLERANCE

private static final double DEFAULT_TOLERANCE

Default value for tolerance.

See Also:

Constant Field Values

originOffset

private double originOffset

Offset of the origin with respect to the plane.

origin

private Vector3D origin

Origin of the plane frame.

u

private Vector3D u

First vector of the plane frame (in plane).

v

private Vector3D v

Second vector of the plane frame (in plane).

w

private Vector3D w

Third vector of the plane frame (plane normal).

tolerance

private final double tolerance

Tolerance below which points are considered identical.

Constructor Detail

Plane

public Plane(Vector3D normal,
             double tolerance)
      throws MathArithmeticException

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

Parameters:

normal - normal direction to the plane

tolerance - tolerance below which points are considered identical

Throws:

MathArithmeticException - if the normal norm is too small

Since:

3.3

Plane

public Plane(Vector3D p,
             Vector3D normal,
             double tolerance)
      throws MathArithmeticException

Build a plane from a point and a normal.

Parameters:

p - point belonging to the plane

normal - normal direction to the plane

tolerance - tolerance below which points are considered identical

Throws:

MathArithmeticException - if the normal norm is too small

Since:

3.3

Plane

public Plane(Vector3D p1,
             Vector3D p2,
             Vector3D p3,
             double tolerance)
      throws MathArithmeticException

Build a plane from three points.

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

Parameters:

p1 - first point belonging to the plane

p2 - second point belonging to the plane

p3 - third point belonging to the plane

tolerance - tolerance below which points are considered identical

Throws:

MathArithmeticException - if the points do not constitute a plane

Since:

3.3

Plane

@Deprecated
public Plane(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 - normal direction to the plane

Throws:

MathArithmeticException - if the normal norm is too small

Plane

@Deprecated
public Plane(Vector3D p,
             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 - point belonging to the plane

normal - normal direction to the plane

Throws:

MathArithmeticException - if the normal norm is too small

Plane

@Deprecated
public Plane(Vector3D p1,
             Vector3D p2,
             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 - first point belonging to the plane

p2 - second point belonging to the plane

p3 - third point belonging to the plane

Throws:

MathArithmeticException - if the points do not constitute a plane

Plane

public Plane(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 to copy

Method Detail

copySelf

public Plane 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).

Specified by:

copySelf in interface Hyperplane<Euclidean3D>

Returns:

a new hyperplane, copy of the instance

reset

public void reset(Vector3D p,
                  Vector3D normal)
           throws MathArithmeticException

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

Parameters:

p - point belonging to the plane

normal - normal direction to the plane

Throws:

MathArithmeticException - if the normal norm is too small

reset

public void reset(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 to reset from

setNormal

private void setNormal(Vector3D normal)
                throws MathArithmeticException

Set the normal vactor.

Parameters:

normal - normal direction to the plane (will be copied)

Throws:

MathArithmeticException - if the normal norm is too small

setFrame

private void setFrame()

Reset the plane frame.

getOrigin

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:

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

getNormal

public Vector3D getNormal()

Get the normalized normal vector.

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

Returns:

normalized normal vector

See Also:

getU(), getV()

getU

public Vector3D getU()

Get the plane first canonical vector.

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

Returns:

normalized first canonical vector

See Also:

getV(), getNormal()

getV

public Vector3D getV()

Get the plane second canonical vector.

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

Returns:

normalized second canonical vector

See Also:

getU(), getNormal()

project

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

Project a point to the hyperplane.

Specified by:

project in interface Hyperplane<Euclidean3D>

Parameters:

point - point to project

Returns:

projected point

Since:

3.3

getTolerance

public double getTolerance()

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

Specified by:

getTolerance in interface Hyperplane<Euclidean3D>

Returns:

tolerance below which points are considered to belong to the hyperplane

Since:

3.3

revertSelf

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.

toSubSpace

public Vector2D toSubSpace(Vector<Euclidean3D> vector)

Transform a space point into a sub-space point.

Parameters:

vector - n-dimension point of the space

Returns:

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

toSpace

public Vector3D toSpace(Vector<Euclidean2D> vector)

Transform a sub-space point into a space point.

Parameters:

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

Returns:

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

toSubSpace

public Vector2D toSubSpace(Point<Euclidean3D> point)

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

Specified by:

toSubSpace in interface Embedding<Euclidean3D,Euclidean2D>

Parameters:

point - point of the space (must be a Vector3D instance)

Returns:

in-plane point (really a Vector2D instance)

See Also:

toSpace(org.apache.commons.math3.geometry.Vector<org.apache.commons.math3.geometry.euclidean.twod.Euclidean2D>)

toSpace

public Vector3D toSpace(Point<Euclidean2D> point)

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

Specified by:

toSpace in interface Embedding<Euclidean3D,Euclidean2D>

Parameters:

point - in-plane point (must be a Vector2D instance)

Returns:

3D space point (really a Vector3D instance)

See Also:

toSubSpace(org.apache.commons.math3.geometry.Vector<org.apache.commons.math3.geometry.euclidean.threed.Euclidean3D>)

getPointAt

public Vector3D getPointAt(Vector2D inPlane,
                           double offset)

Get one point from the 3D-space.

Parameters:

inPlane - desired in-plane coordinates for the point in the plane

offset - desired offset for the point

Returns:

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

isSimilarTo

public boolean isSimilarTo(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 to which the instance is compared

Returns:

true if the planes are similar

rotate

public Plane rotate(Vector3D center,
                    Rotation rotation)

Rotate the plane around the specified point.

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

Parameters:

center - rotation center

rotation - vectorial rotation operator

Returns:

a new plane

translate

public Plane translate(Vector3D translation)

Translate the plane by the specified amount.

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

Parameters:

translation - translation to apply

Returns:

a new plane

intersection

public Vector3D intersection(Line line)

Get the intersection of a line with the instance.

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 Line intersection(Plane other)

Build the line shared by the instance and another plane.

Parameters:

other - other plane

Returns:

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

intersection

public static Vector3D intersection(Plane plane1,
                                    Plane plane2,
                                    Plane plane3)

Get the intersection point of three planes.

Parameters:

plane1 - first plane1

plane2 - second plane2

plane3 - third plane2

Returns:

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

wholeHyperplane

public SubPlane wholeHyperplane()

Build a region covering the whole hyperplane.

Specified by:

wholeHyperplane in interface Hyperplane<Euclidean3D>

Returns:

a region covering the whole hyperplane

wholeSpace

public PolyhedronsSet wholeSpace()

Build a region covering the whole space.

Specified by:

wholeSpace in interface Hyperplane<Euclidean3D>

Returns:

a region containing the instance (really a PolyhedronsSet instance)

contains

public boolean contains(Vector3D p)

Check if the instance contains a point.

Parameters:

p - point to check

Returns:

true if p belongs to the plane

getOffset

public double getOffset(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 to check

Returns:

offset of the plane

getOffset

public double getOffset(Vector<Euclidean3D> vector)

Get the offset (oriented distance) of a vector.

Parameters:

vector - vector to check

Returns:

offset of the vector

getOffset

public double getOffset(Point<Euclidean3D> point)

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.

Specified by:

getOffset in interface Hyperplane<Euclidean3D>

Parameters:

point - point to check

Returns:

offset of the point

sameOrientationAs

public boolean sameOrientationAs(Hyperplane<Euclidean3D> other)

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

Specified by:

sameOrientationAs in interface Hyperplane<Euclidean3D>

Parameters:

other - other hyperplane to check against the instance

Returns:

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