maspack.matrix

Class Plane

java.lang.Object

maspack.matrix.Plane

All Implemented Interfaces:

java.io.Serializable

public class Plane
extends java.lang.Object
implements java.io.Serializable

Implements a plane in three space, as characterized by the points x which satisfy

  T
 n  x - d = 0
 

where n is the plane normal and d is the offset.

Author:

John Lloyd

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
Vector3d	normal Plane normal
double	offset Plane offset (distance of the origin from the plane)

Constructor Summary

Constructors

Constructor and Description
Plane() Creates a plane initialized to the x-y plane.
Plane(double nx, double ny, double nz, double off) Creates a plane from normal components and the an offset value.
Plane(Plane p) Creates a plane initialized to another plane.
Plane(Point3d p1, Point3d p2, Point3d p3) Constructs a plane given three non-colinear points arranged counter-clockwise around the normal.
Plane(RigidTransform3d TPW) Creates a plane from the x-y plane of the coordinate frame indicated by TPW.
Plane(Vector3d n, double d) Creates a plane with a specified normal and offset.
Plane(Vector3d n, Vector3d p) Creates a plane which passes through a particular point with a specified normal direction.

Method Summary

Modifier and Type	Method and Description
double	distance(Vector3d p) Returns the signed distance between a point and this plane.
boolean	epsilonEquals(Plane plane, double eps)
boolean	equals(Plane plane)
void	fit(java.util.Collection<Point3d> pnts) Fits this plane to a collection of points.
void	fit(Point3d[] pnts, int num) Fits this plane to a set of points.
void	flip()
Vector3d	getNormal() Returns the normal for this plane.
double	getOffset() Returns the offset for this plane.
double	intersectLine(Point3d isect, Vector3d dir, Vector3d pnt) Intersects this plane with a line.
boolean	intersectPlane(Point3d pnt, Vector3d dir, Plane plane) Intersects this plane with another plane.
boolean	intersectRay(Point3d isect, Vector3d dir, Vector3d origin) Intersects this plane with a directed ray.
void	inverseTransform(AffineTransform3dBase X) Applies an inverse affine transformation to this plane, in place.
void	inverseTransform(AffineTransform3dBase X, Plane plane) Applies an inverse affine transformation to a specified plane and places the result in this plane.
void	inverseTransform(RigidTransform3d X) Applies an inverse rigid transformation to this plane, in place.
void	inverseTransform(RigidTransform3d X, Plane plane) Applies an inverse rigid transformation to a specified plane and places the result in this plane.
void	inverseTransform(VectorTransformer3d T) Applies an inverse vector transform to this place.
void	inverseTransform(VectorTransformer3d T, Plane plane) Applies an inverse vector transform to a plane and places the result in this plane.
double	project(Point3d pr, Point3d p1) Projects a point onto this plane, and returns the signed distance of the original point from the plane.
void	projectVector(Vector3d vr, Vector3d v1) Projects a vector onto this plane, by removing any component that is perpendicular to it.
void	reflect(Point3d pr, Point3d p1) Reflects a point about this plane.
void	scale(double s) Scales the units of this plane by the specified scale factor.
void	scan(ReaderTokenizer rtok) Sets the contents of this plane to values read from a ReaderTokenizer.
void	set(double nx, double ny, double nz, double d) Sets the plane to the indicated normal direction and offset.
void	set(Plane p) Sets this plane to the values of another plane.
void	set(Point3d p1, Point3d p2, Point3d p3) Sets this plane to pass through three non-colinear points arranged counter-clockwise around the normal.
void	set(RigidTransform3d X) Sets this plane to the x-y plane defined by a RigidTransformation.
void	set(Vector3d n, double d) Sets the plane to the indicated normal direction and offset.
void	set(Vector3d n, Vector3d p) Sets this plane to pass through a particular point with a specified normal direction.
void	setNormal(Vector3d nrm)
void	setOffset(double o)
void	setRandom()
java.lang.String	toString() Returns a String representation of this Plane, consisting of the x, y, and z components of the normal, followed by the offset.
java.lang.String	toString(NumberFormat fmt) Returns a String representation of this Plane, consisting of the x, y, and z components of the normal, followed by the offset.
java.lang.String	toString(java.lang.String fmtStr) Returns a String representation of this Plane, consisting of the x, y, and z components of the normal, followed by the offset.
void	transform(AffineTransform3dBase X) Applies an affine transformation to this plane, in place.
void	transform(AffineTransform3dBase X, Plane plane) Applies an affine transformation to a specified plane and places the result in this plane.
void	transform(RigidTransform3d X) Applies a rigid transformation to this plane, in place.
void	transform(RigidTransform3d X, Plane plane) Applies a rigid transformation to a specified plane and places the result in this plane.
void	transform(VectorTransformer3d T) Applies a vector transform to this plane.
void	transform(VectorTransformer3d T, Plane plane) Applies a vector transform to a plane and places the result in this plane.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

normal

public Vector3d normal

Plane normal

offset

public double offset

Plane offset (distance of the origin from the plane)

Constructor Detail

Plane

public Plane()

Creates a plane initialized to the x-y plane.

Plane

public Plane(Plane p)

Creates a plane initialized to another plane.

Parameters:

p - plane to copy

Plane

public Plane(RigidTransform3d TPW)

Creates a plane from the x-y plane of the coordinate frame indicated by TPW. The plane passes through the frame origin and its normal is aligned with the frames's z axis.

Parameters:

TPW - transform defining the plane

Plane

public Plane(Vector3d n,
             Vector3d p)

Creates a plane which passes through a particular point with a specified normal direction.

Parameters:

n - normal direction

p - point to pass through

Plane

public Plane(double nx,
             double ny,
             double nz,
             double off)

Creates a plane from normal components and the an offset value.

Parameters:

nx - normal x component

ny - normal y component

nz - normal z component

off - offset value

Plane

public Plane(Vector3d n,
             double d)

Creates a plane with a specified normal and offset.

Parameters:

n - normal direction

d - offset (equal to the dot product of the normal and every point on the plane).

Plane

public Plane(Point3d p1,
             Point3d p2,
             Point3d p3)
      throws java.lang.IllegalArgumentException

Constructs a plane given three non-colinear points arranged counter-clockwise around the normal.

Parameters:

p1 - first point

p2 - second point

p3 - third point

Throws:

java.lang.IllegalArgumentException - if the points are colinear

Method Detail

set

public void set(Plane p)

Sets this plane to the values of another plane.

Parameters:

p - plane to copy

set

public void set(Vector3d n,
                double d)

Sets the plane to the indicated normal direction and offset. The normal will normalized.

Parameters:

n - normal direction

d - offset

set

public void set(double nx,
                double ny,
                double nz,
                double d)

Sets the plane to the indicated normal direction and offset. The normal will normalized.

Parameters:

nx - x component of normal direction

ny - y component of normal direction

nz - z component of normal direction

d - offset

set

public void set(Vector3d n,
                Vector3d p)

Sets this plane to pass through a particular point with a specified normal direction.

Parameters:

n - normal direction

p - point to pass through

set

public void set(RigidTransform3d X)

Sets this plane to the x-y plane defined by a RigidTransformation. The normal is the transformation's z axis, while the point is the transformation's origin.

Parameters:

X - transformation defining the plane

set

public void set(Point3d p1,
                Point3d p2,
                Point3d p3)
         throws java.lang.IllegalArgumentException

Sets this plane to pass through three non-colinear points arranged counter-clockwise around the normal.

Parameters:

p1 - first point

p2 - second point

p3 - third point

Throws:

java.lang.IllegalArgumentException - if the points are colinear

flip

public void flip()

distance

public double distance(Vector3d p)

Returns the signed distance between a point and this plane. The distance is positive if the point is on the same side as the normal.

Parameters:

p - point to compute distance for

Returns:

signed distance to plane

project

public double project(Point3d pr,
                      Point3d p1)

Projects a point onto this plane, and returns the signed distance of the original point from the plane.

Parameters:

pr - projected point

p1 - point to project

Returns:

signed distance of p1

projectVector

public void projectVector(Vector3d vr,
                          Vector3d v1)

Projects a vector onto this plane, by removing any component that is perpendicular to it.

Parameters:

vr - returns the projected vector

v1 - vector to project

reflect

public void reflect(Point3d pr,
                    Point3d p1)

Reflects a point about this plane.

Parameters:

pr - reflected point

p1 - point to reflect

intersectRay

public boolean intersectRay(Point3d isect,
                            Vector3d dir,
                            Vector3d origin)

Intersects this plane with a directed ray.

Parameters:

isect - intersection point

dir - direction of the ray

origin - origin of the ray

Returns:

false if the ray is pointing away from the plane

intersectLine

public double intersectLine(Point3d isect,
                            Vector3d dir,
                            Vector3d pnt)

Intersects this plane with a line. If the line and plane are parallel, then postive infinity is returned.

Parameters:

isect - intersection point (optional)

dir - vector in the direction of the line

pnt - point lying on the line

Returns:

intersection parameter along dir, or +infinity if there is no intersection

intersectPlane

public boolean intersectPlane(Point3d pnt,
                              Vector3d dir,
                              Plane plane)

Intersects this plane with another plane. The result is returned as a point and direction vector describing the resulting line. The point will be the one nearest to the origin. If the planes are parallel, this method returns false and the point and direction are undefined. In that case the offsets should be compared to see if the planes are coincident.

Parameters:

pnt - returns a point on the intersection line.

dir - returns a unit vector in the direction of the intersection line.

plane - plane to intersect

Returns:

true if the planes intersect in a line or false if they are parallel.

toString

public java.lang.String toString()

Returns a String representation of this Plane, consisting of the x, y, and z components of the normal, followed by the offset.

Overrides:

toString in class java.lang.Object

Returns:

String representation

toString

public java.lang.String toString(java.lang.String fmtStr)

Returns a String representation of this Plane, consisting of the x, y, and z components of the normal, followed by the offset. Each element is formatted using a C printf style format string. For a description of the format string syntax, see NumberFormat.

Parameters:

fmtStr - numeric format specification

Returns:

String representation of this vector

toString

public java.lang.String toString(NumberFormat fmt)

Returns a String representation of this Plane, consisting of the x, y, and z components of the normal, followed by the offset. Each element is formatted using a C printf style as decribed by the parameter NumberFormat. When called numerous times, this routine can be more efficient than toString(String), because the NumberFormat does not need to be recreated each time from a specification string.

Parameters:

fmt - numeric format

Returns:

String representation of this vector

transform

public void transform(AffineTransform3dBase X)

Applies an affine transformation to this plane, in place.

Parameters:

X - affine transformation

inverseTransform

public void inverseTransform(AffineTransform3dBase X)

Applies an inverse affine transformation to this plane, in place.

Parameters:

X - affine transformation

transform

public void transform(AffineTransform3dBase X,
                      Plane plane)

Applies an affine transformation to a specified plane and places the result in this plane.

Parameters:

X - affine transformation

plane - plane to transform

transform

public void transform(VectorTransformer3d T)

Applies a vector transform to this plane.

Parameters:

T - vector transformer

transform

public void transform(VectorTransformer3d T,
                      Plane plane)

Applies a vector transform to a plane and places the result in this plane.

Parameters:

T - vector transformer

plane - plane to be transformed

inverseTransform

public void inverseTransform(VectorTransformer3d T,
                             Plane plane)

Applies an inverse vector transform to a plane and places the result in this plane.

Parameters:

T - vector transformer

plane - plane to be transformed

inverseTransform

public void inverseTransform(VectorTransformer3d T)

Applies an inverse vector transform to this place.

Parameters:

T - vector transformer

inverseTransform

public void inverseTransform(AffineTransform3dBase X,
                             Plane plane)

Applies an inverse affine transformation to a specified plane and places the result in this plane.

Parameters:

X - affine transformation

plane - plane to transform

transform

public void transform(RigidTransform3d X)

Applies a rigid transformation to this plane, in place.

Parameters:

X - rigid transformation

inverseTransform

public void inverseTransform(RigidTransform3d X)

Applies an inverse rigid transformation to this plane, in place.

Parameters:

X - rigid transformation

transform

public void transform(RigidTransform3d X,
                      Plane plane)

Applies a rigid transformation to a specified plane and places the result in this plane.

Parameters:

X - rigid transformation

plane - plane to transform

inverseTransform

public void inverseTransform(RigidTransform3d X,
                             Plane plane)

Applies an inverse rigid transformation to a specified plane and places the result in this plane.

Parameters:

X - rigid transformation

plane - plane to transform

scale

public void scale(double s)

Scales the units of this plane by the specified scale factor. This amounts to simply scaling the offset.

Parameters:

s - scale factor by which to scale plane

getNormal

public Vector3d getNormal()

Returns the normal for this plane.

Returns:

normal for the plane

setNormal

public void setNormal(Vector3d nrm)

getOffset

public double getOffset()

Returns the offset for this plane.

Returns:

offset for the plane

setOffset

public void setOffset(double o)

scan

public void scan(ReaderTokenizer rtok)
          throws java.io.IOException

Sets the contents of this plane to values read from a ReaderTokenizer. The input should consist of a sequence of four numbers, separated by white space and optionally surrounded by square brackets [ ].

Parameters:

rtok - Tokenizer from which vector values are read. Number parsing should be enabled.

Throws:

java.io.IOException - if an I/O or formatting error is encountered

fit

public void fit(java.util.Collection<Point3d> pnts)

Fits this plane to a collection of points.

Parameters:

pnts - points to fit

fit

public void fit(Point3d[] pnts,
                int num)

Fits this plane to a set of points.

Parameters:

pnts - points to fit

num - number of points

setRandom

public void setRandom()

equals

public boolean equals(Plane plane)

epsilonEquals

public boolean epsilonEquals(Plane plane,
                             double eps)