us.ihmc.euclid.geometry

Class Plane3D

java.lang.Object

us.ihmc.euclid.geometry.Plane3D

All Implemented Interfaces:

us.ihmc.euclid.interfaces.Clearable, us.ihmc.euclid.interfaces.EpsilonComparable<Plane3D>, us.ihmc.euclid.interfaces.GeometricallyComparable<Plane3D>, us.ihmc.euclid.interfaces.GeometryObject<Plane3D>, us.ihmc.euclid.interfaces.Settable<Plane3D>, us.ihmc.euclid.interfaces.Transformable

public class Plane3D
extends java.lang.Object
implements us.ihmc.euclid.interfaces.GeometryObject<Plane3D>

Represents an infinitely wide and long 3D plane defined by a 3D point and a 3D unit-vector.

Constructor Summary

Constructors

Constructor and Description
Plane3D() Default constructor that initializes both point and normal to zero.
Plane3D(double pointOnPlaneX, double pointOnPlaneY, double pointOnPlaneZ, double planeNormalX, double planeNormalY, double planeNormalZ) Initializes this plane to be passing through the given point, with the vector as the normal.
Plane3D(Plane3D other) Creates a new plane 3D and initializes it to other.
Plane3D(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly firstPointOnPlane, us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly secondPointOnPlane, us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly thirdPointOnPlane) Initializes this plane to be passing through the three given points.
Plane3D(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointOnPlane, us.ihmc.euclid.tuple3D.interfaces.Vector3DReadOnly planeNormal) Initializes this plane to be passing through the given point, with the vector as the normal.

Method Summary

Modifier and Type	Method and Description
void	applyInverseTransform(us.ihmc.euclid.transform.interfaces.Transform transform) Transforms this plane using the inverse of the given homogeneous transformation matrix.
void	applyTransform(us.ihmc.euclid.transform.interfaces.Transform transform) Transforms this plane using the given homogeneous transformation matrix.
boolean	containsNaN() Tests if this plane contains Double.NaN.
double	distance(double pointX, double pointY, double pointZ) Computes the minimum distance the given 3D point and this plane.
double	distance(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point) Computes the minimum distance the given 3D point and this plane.
boolean	epsilonEquals(Plane3D other, double epsilon) Tests on a per-component basis on the point and normal if this plane is equal to other with the tolerance epsilon.
boolean	equals(java.lang.Object object) Tests if the given object's class is the same as this, in which case the method returns equals(Plane3D), it returns false otherwise.
boolean	equals(Plane3D other) Tests on a per component basis, if this plane 3D is exactly equal to other.
boolean	geometricallyEquals(Plane3D other, double epsilon) Compares this to other to determine if the two planes are geometrically similar.
us.ihmc.euclid.tuple3D.interfaces.Vector3DReadOnly	getNormal() Gets the read-only reference to the normal of this plane.
void	getNormal(us.ihmc.euclid.tuple3D.interfaces.Vector3DBasics planeNormalToPack) Gets the direction defining this plane by storing its components in the given argument planeNormalToPack.
us.ihmc.euclid.tuple3D.Vector3D	getNormalCopy() Returns a copy of this plane's normal.
double	getNormalX() Gets the x-component of this plane's normal.
double	getNormalY() Gets the y-component of this plane's normal.
double	getNormalZ() Gets the z-component of this plane's normal.
us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly	getPoint() Gets the read-only reference to the point through which this plane is going.
void	getPoint(us.ihmc.euclid.tuple3D.interfaces.Point3DBasics pointOnPlaneToPack) Gets the point defining this plane by storing its coordinates in the given argument pointToPack.
us.ihmc.euclid.tuple3D.Point3D	getPointCopy() Returns a copy of the point defining this plane.
double	getPointX() Gets the x-coordinate of a point this plane goes through.
double	getPointY() Gets the y-coordinate of a point this plane goes through.
double	getPointZ() Gets the z-coordinate of a point this plane goes through.
double	getZOnPlane(double pointX, double pointY) Computes the z-coordinate such that the point at (x, y, z) is located on this plane.
boolean	intersectionWith(Line3DReadOnly line, us.ihmc.euclid.tuple3D.interfaces.Point3DBasics intersectionToPack) Computes the coordinates of the intersection between this plane and an infinitely long 3D line.
boolean	intersectionWith(us.ihmc.euclid.tuple3D.interfaces.Point3DBasics intersectionToPack, us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointOnLine, us.ihmc.euclid.tuple3D.interfaces.Vector3DReadOnly lineDirection) Computes the coordinates of the intersection between this plane and an infinitely long 3D line.
boolean	isCoincident(Plane3D otherPlane, double angleEpsilon, double distanceEpsilon) Tests if this plane and the given plane are coincident: this.normal and otherPlane.normal are collinear given the tolerance angleEpsilon.
boolean	isOnOrAbove(double x, double y, double z) Tests if the query point is located strictly on or above this plane.
boolean	isOnOrAbove(double pointX, double pointY, double pointZ, double epsilon) Tests if the query point is located on or above this plane given the tolerance epsilon.
boolean	isOnOrAbove(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToTest) Tests if the query point is located strictly on or above this plane.
boolean	isOnOrAbove(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToTest, double epsilon) Tests if the query point is located on or above this plane given the tolerance epsilon.
boolean	isOnOrBelow(double pointX, double pointY, double pointZ) Tests if the query point is located strictly on or below this plane.
boolean	isOnOrBelow(double pointX, double pointY, double pointZ, double epsilon) Tests if the query point is located on or below this plane given the tolerance epsilon.
boolean	isOnOrBelow(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToTest) Tests if the query point is located strictly on or below this plane.
boolean	isOnOrBelow(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToTest, double epsilon) Tests if the query point is located on or below this plane given the tolerance epsilon.
boolean	isParallel(Plane3D otherPlane, double angleEpsilon) Tests if the two planes are parallel by testing if their normals are collinear.
boolean	orthogonalProjection(double pointX, double pointY, double pointZ, us.ihmc.euclid.tuple3D.interfaces.Point3DBasics projectionToPack) Computes the orthogonal projection of the given 3D point on this 3D plane.
boolean	orthogonalProjection(us.ihmc.euclid.tuple3D.interfaces.Point3DBasics pointToProject) Computes the orthogonal projection of the given 3D point on this 3D plane.
boolean	orthogonalProjection(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToProject, us.ihmc.euclid.tuple3D.interfaces.Point3DBasics projectionToPack) Computes the orthogonal projection of the given 3D point on this 3D plane.
us.ihmc.euclid.tuple3D.Point3D	orthogonalProjectionCopy(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToProject) Computes the orthogonal projection of the given 3D point on this 3D line.
void	set(double pointOnPlaneX, double pointOnPlaneY, double pointOnPlaneZ, double planeNormalX, double planeNormalY, double planeNormalZ) Redefines this plane with a new point and a new normal.
void	set(Plane3D other) Sets this plane to be the same as the given plane.
void	set(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly firstPointOnPlane, us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly secondPointOnPlane, us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly thirdPointOnPlane) Redefines this plane such that it goes through the three given points.
void	set(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointOnPlane, us.ihmc.euclid.tuple3D.interfaces.Vector3DReadOnly planeNormal) Redefines this plane with a new point and a new normal.
void	setNormal(double normalX, double normalY, double normalZ) Changes the normal of this plane by setting it to the normalized value of the given vector.
void	setNormal(us.ihmc.euclid.tuple3D.interfaces.Vector3DReadOnly planeNormal) Changes the direction of this plane by setting it to the normalized value of the given vector.
void	setPoint(double pointX, double pointY, double pointZ) Changes the point through which this plane has to go.
void	setPoint(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointOnPlane) Changes the point through which this plane has to go.
void	setToNaN() Sets the point and normal of this plane to Double.NaN.
void	setToZero() Sets the point and vector of this plane to zero.
double	signedDistance(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point) Computes the minimum signed distance the given 3D point and this plane.
java.lang.String	toString() Provides a String representation of this plane 3D as follows: Plane 3D: point = (x, y, z), normal = (x, y, z)

Methods inherited from class java.lang.Object

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

Constructor Detail

Plane3D

public Plane3D()

Default constructor that initializes both point and normal to zero. This point and vector have to be set to valid values to make this plane usable.

Plane3D

public Plane3D(double pointOnPlaneX,
               double pointOnPlaneY,
               double pointOnPlaneZ,
               double planeNormalX,
               double planeNormalY,
               double planeNormalZ)

Initializes this plane to be passing through the given point, with the vector as the normal.

Parameters:

pointOnPlaneX - the new x-coordinate of the point on this plane.

pointOnPlaneY - the new y-coordinate of the point on this plane.

pointOnPlaneZ - the new z-coordinate of the point on this plane.

planeNormalX - the new x-component of the normal of this plane.

planeNormalY - the new y-component of the normal of this plane.

planeNormalZ - the new z-component of the normal of this plane.

Throws:

java.lang.RuntimeException - if the new normal is unreasonably small.

Plane3D

public Plane3D(Plane3D other)

Creates a new plane 3D and initializes it to other.

Parameters:

other - the other plane used to initialize this plane. Not modified.

Throws:

java.lang.RuntimeException - if the other plane has not been initialized yet.

Plane3D

public Plane3D(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly firstPointOnPlane,
               us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly secondPointOnPlane,
               us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly thirdPointOnPlane)

Initializes this plane to be passing through the three given points.

Parameters:

firstPointOnPlane - first point on this plane. Not modified.

secondPointOnPlane - second point on this plane. Not modified.

thirdPointOnPlane - second point on this plane. Not modified.

Throws:

java.lang.RuntimeException - if at least two of the given points are exactly equal.

java.lang.RuntimeException - if the plane normal could not be computed from the three given points.

Plane3D

public Plane3D(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointOnPlane,
               us.ihmc.euclid.tuple3D.interfaces.Vector3DReadOnly planeNormal)

Initializes this plane to be passing through the given point, with the vector as the normal.

Parameters:

pointOnPlane - point on this plane. Not modified.

planeNormal - normal of this plane. Not modified.

Throws:

java.lang.RuntimeException - if the new normal is unreasonably small.

Method Detail

applyTransform

public void applyTransform(us.ihmc.euclid.transform.interfaces.Transform transform)

Transforms this plane using the given homogeneous transformation matrix.

Specified by:

applyTransform in interface us.ihmc.euclid.interfaces.Transformable

Parameters:

transform - the transform to apply on this plane's point and normal. Not modified.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

applyInverseTransform

public void applyInverseTransform(us.ihmc.euclid.transform.interfaces.Transform transform)

Transforms this plane using the inverse of the given homogeneous transformation matrix.

Specified by:

applyInverseTransform in interface us.ihmc.euclid.interfaces.Transformable

Parameters:

transform - the transform to apply on this plane's point and normal. Not modified.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

containsNaN

public boolean containsNaN()

Tests if this plane contains Double.NaN.

Specified by:

containsNaN in interface us.ihmc.euclid.interfaces.Clearable

Returns:

true if point and/or normal contains Double.NaN, false otherwise.

distance

public double distance(double pointX,
                       double pointY,
                       double pointZ)

Computes the minimum distance the given 3D point and this plane.

Parameters:

pointX - the x-coordinate of the point to compute the distance from the plane. Not modified.

pointY - the y-coordinate of the point to compute the distance from the plane. Not modified.

pointZ - the z-coordinate of the point to compute the distance from the plane. Not modified.

Returns:

the minimum distance between the 3D point and this 3D plane.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

distance

public double distance(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point)

Computes the minimum distance the given 3D point and this plane.

Parameters:

point - 3D point to compute the distance from the plane. Not modified.

Returns:

the minimum distance between the 3D point and this 3D plane.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

epsilonEquals

public boolean epsilonEquals(Plane3D other,
                             double epsilon)

Tests on a per-component basis on the point and normal if this plane is equal to other with the tolerance epsilon. This method will return false if the two planes are physically the same but either the point or vector of each plane is different. For instance, if this.point == other.point and this.normal == - other.normal, the two planes are physically the same but this method returns false.

Specified by:

epsilonEquals in interface us.ihmc.euclid.interfaces.EpsilonComparable<Plane3D>

Parameters:

other - the query. Not modified.

epsilon - the tolerance to use.

Returns:

true if the two planes are equal, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

equals

public boolean equals(Plane3D other)

Tests on a per component basis, if this plane 3D is exactly equal to other.

Parameters:

other - the other plane 3D to compare against this. Not modified.

Returns:

true if the two planes are exactly equal component-wise, false otherwise.

equals

public boolean equals(java.lang.Object object)

Tests if the given object's class is the same as this, in which case the method returns equals(Plane3D), it returns false otherwise.

Overrides:

equals in class java.lang.Object

Parameters:

object - the object to compare against this. Not modified.

Returns:

true if object and this are exactly equal, false otherwise.

getNormal

public us.ihmc.euclid.tuple3D.interfaces.Vector3DReadOnly getNormal()

Gets the read-only reference to the normal of this plane.

Returns:

the reference to the normal.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

getNormal

public void getNormal(us.ihmc.euclid.tuple3D.interfaces.Vector3DBasics planeNormalToPack)

Gets the direction defining this plane by storing its components in the given argument planeNormalToPack.

Parameters:

planeNormalToPack - vector in which the components of this plane's normal are stored. Modified.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

getNormalCopy

public us.ihmc.euclid.tuple3D.Vector3D getNormalCopy()

Returns a copy of this plane's normal.

WARNING: This method generates garbage.

Returns:

a copy of this plane's normal.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

getNormalX

public double getNormalX()

Gets the x-component of this plane's normal.

Returns:

the x-component of this plane's normal.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

getNormalY

public double getNormalY()

Gets the y-component of this plane's normal.

Returns:

the y-component of this plane's normal.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

getNormalZ

public double getNormalZ()

Gets the z-component of this plane's normal.

Returns:

the z-component of this plane's normal.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

getPoint

public us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly getPoint()

Gets the read-only reference to the point through which this plane is going.

Returns:

the reference to the point.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

getPoint

public void getPoint(us.ihmc.euclid.tuple3D.interfaces.Point3DBasics pointOnPlaneToPack)

Gets the point defining this plane by storing its coordinates in the given argument pointToPack.

Parameters:

pointOnPlaneToPack - point in which the coordinates of this plane's point are stored. Modified.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

getPointCopy

public us.ihmc.euclid.tuple3D.Point3D getPointCopy()

Returns a copy of the point defining this plane.

WARNING: This method generates garbage.

Returns:

a copy of this plane's point.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

getPointX

public double getPointX()

Gets the x-coordinate of a point this plane goes through.

Returns:

the x-coordinate of this plane's point.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

getPointY

public double getPointY()

Gets the y-coordinate of a point this plane goes through.

Returns:

the y-coordinate of this plane's point.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

getPointZ

public double getPointZ()

Gets the z-coordinate of a point this plane goes through.

Returns:

the z-coordinate of this plane's point.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

getZOnPlane

public double getZOnPlane(double pointX,
                          double pointY)

Computes the z-coordinate such that the point at (x, y, z) is located on this plane.

Parameters:

pointX - the x-coordinate of the query.

pointY - the y-coordinate of the query.

Returns:

the z-coordinate of the plane.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

intersectionWith

public boolean intersectionWith(Line3DReadOnly line,
                                us.ihmc.euclid.tuple3D.interfaces.Point3DBasics intersectionToPack)

Computes the coordinates of the intersection between this plane and an infinitely long 3D line.

Edge cases:

• If the line is parallel to the plane, this methods fails and returns false.

Parameters:

line - the line that may intersect this plane. Not modified.

intersectionToPack - point in which the coordinates of the intersection are stored.

Returns:

true if the method succeeds, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

intersectionWith

public boolean intersectionWith(us.ihmc.euclid.tuple3D.interfaces.Point3DBasics intersectionToPack,
                                us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointOnLine,
                                us.ihmc.euclid.tuple3D.interfaces.Vector3DReadOnly lineDirection)

Computes the coordinates of the intersection between this plane and an infinitely long 3D line.

Edge cases:

• If the line is parallel to the plane, this methods fails and returns false.

Parameters:

pointOnLine - a point located on the line. Not modified.

lineDirection - the direction of the line. Not modified.

intersectionToPack - point in which the coordinates of the intersection are stored.

Returns:

true if the method succeeds, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

isCoincident

public boolean isCoincident(Plane3D otherPlane,
                            double angleEpsilon,
                            double distanceEpsilon)

Tests if this plane and the given plane are coincident:

• this.normal and otherPlane.normal are collinear given the tolerance angleEpsilon.
• the distance of otherPlane.point from the this plane is less than distanceEpsilon.

Edge cases:

• if the length of either normal is below 1.0E-7, this method fails and returns false.

Parameters:

otherPlane - the other plane to do the test with. Not modified.

angleEpsilon - tolerance on the angle in radians to determine if the plane normals are collinear.

distanceEpsilon - tolerance on the distance to determine if otherPlane.point belongs to this plane.

Returns:

true if the two planes are coincident, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

isOnOrAbove

public boolean isOnOrAbove(double x,
                           double y,
                           double z)

Tests if the query point is located strictly on or above this plane.

Above is defined as the side of the plane toward which the normal is pointing.

Parameters:

x - the x-coordinate of the query.

y - the y-coordinate of the query.

z - the z-coordinate of the query.

Returns:

true if the query is strictly on or above this plane, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

isOnOrAbove

public boolean isOnOrAbove(double pointX,
                           double pointY,
                           double pointZ,
                           double epsilon)

Tests if the query point is located on or above this plane given the tolerance epsilon.

Above is defined as the side of the plane toward which the normal is pointing.

1. if epsilon == 0, the query has to be either exactly on the plane or strictly above for this method to return true.
2. if epsilon > 0, this method returns true if the query meets the requirements of 1., in addition, this method returns also true if the query is below the plane at a distance less or equal than epsilon.
3. if epsilon < 0, this method returns true only if the query is above the plane and at a distance of at least Math.abs(epsilon).

Parameters:

pointX - the x-coordinate of the query.

pointY - the y-coordinate of the query.

pointZ - the z-coordinate of the query.

epsilon - the tolerance to use for the test.

Returns:

true if the query is considered to be on or above this plane, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

isOnOrAbove

public boolean isOnOrAbove(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToTest)

Tests if the query point is located strictly on or above this plane.

Above is defined as the side of the plane toward which the normal is pointing.

Parameters:

pointToTest - the coordinates of the query. Not modified.

Returns:

true if the query is strictly on or above this plane, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

isOnOrAbove

public boolean isOnOrAbove(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToTest,
                           double epsilon)

Tests if the query point is located on or above this plane given the tolerance epsilon.

Above is defined as the side of the plane toward which the normal is pointing.

1. if epsilon == 0, the query has to be either exactly on the plane or strictly above for this method to return true.
2. if epsilon > 0, this method returns true if the query meets the requirements of 1., in addition, this method returns also true if the query is below the plane at a distance less or equal than epsilon.
3. if epsilon < 0, this method returns true only if the query is above the plane and at a distance of at least Math.abs(epsilon).

Parameters:

pointToTest - the coordinates of the query. Not modified.

epsilon - the tolerance to use for the test.

Returns:

true if the query is considered to be on or above this plane, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

isOnOrBelow

public boolean isOnOrBelow(double pointX,
                           double pointY,
                           double pointZ)

Tests if the query point is located strictly on or below this plane.

Below is defined as the side of the plane which the normal is pointing away from.

Parameters:

pointX - the x-coordinate of the query.

pointY - the y-coordinate of the query.

pointZ - the z-coordinate of the query.

Returns:

true if the query is strictly on or below this plane, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

isOnOrBelow

public boolean isOnOrBelow(double pointX,
                           double pointY,
                           double pointZ,
                           double epsilon)

Tests if the query point is located on or below this plane given the tolerance epsilon.

Below is defined as the side of the plane which the normal is pointing away from.

1. if epsilon == 0, the query has to be either exactly on the plane or strictly below for this method to return true.
2. if epsilon > 0, this method returns true if the query meets the requirements of 1., in addition, this method returns also true if the query is above the plane at a distance less or equal than epsilon.
3. if epsilon < 0, this method returns true only if the query is below the plane and at a distance of at least Math.abs(epsilon).

Parameters:

pointX - the x-coordinate of the query.

pointY - the y-coordinate of the query.

pointZ - the z-coordinate of the query.

epsilon - the tolerance to use for the test.

Returns:

true if the query is considered to be on or below this plane, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

isOnOrBelow

public boolean isOnOrBelow(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToTest)

Tests if the query point is located strictly on or below this plane.

Below is defined as the side of the plane which the normal is pointing away from.

Parameters:

pointToTest - the coordinates of the query. Not modified.

Returns:

true if the query is strictly on or below this plane, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

isOnOrBelow

public boolean isOnOrBelow(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToTest,
                           double epsilon)

Tests if the query point is located on or below this plane given the tolerance epsilon.

Below is defined as the side of the plane which the normal is pointing away from.

1. if epsilon == 0, the query has to be either exactly on the plane or strictly below for this method to return true.
2. if epsilon > 0, this method returns true if the query meets the requirements of 1., in addition, this method returns also true if the query is above the plane at a distance less or equal than epsilon.
3. if epsilon < 0, this method returns true only if the query is below the plane and at a distance of at least Math.abs(epsilon).

Parameters:

pointToTest - the coordinates of the query. Not modified.

epsilon - the tolerance to use for the test.

Returns:

true if the query is considered to be on or below this plane, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

isParallel

public boolean isParallel(Plane3D otherPlane,
                          double angleEpsilon)

Tests if the two planes are parallel by testing if their normals are collinear. The latter is done given a tolerance on the angle between the two normal axes in the range ]0; pi/2[.

Edge cases:

• if the length of either normal is below 1.0E-7, this method fails and returns false.

Parameters:

otherPlane - the other plane to do the test with. Not modified.

angleEpsilon - tolerance on the angle in radians.

Returns:

true if the two planes are parallel, false otherwise.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

orthogonalProjection

public boolean orthogonalProjection(us.ihmc.euclid.tuple3D.interfaces.Point3DBasics pointToProject)

Computes the orthogonal projection of the given 3D point on this 3D plane.

Parameters:

pointToProject - the point to project on this plane. Modified.

Returns:

whether the method succeeded or not.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

orthogonalProjection

public boolean orthogonalProjection(double pointX,
                                    double pointY,
                                    double pointZ,
                                    us.ihmc.euclid.tuple3D.interfaces.Point3DBasics projectionToPack)

Computes the orthogonal projection of the given 3D point on this 3D plane.

Parameters:

pointX - the x-coordinate of the point to compute the projection of.

pointY - the y-coordinate of the point to compute the projection of.

pointZ - the z-coordinate of the point to compute the projection of.

projectionToPack - point in which the projection of the point onto the plane is stored. Modified.

Returns:

whether the method succeeded or not.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

orthogonalProjection

public boolean orthogonalProjection(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToProject,
                                    us.ihmc.euclid.tuple3D.interfaces.Point3DBasics projectionToPack)

Computes the orthogonal projection of the given 3D point on this 3D plane.

Parameters:

pointToProject - the point to compute the projection of. Not modified.

projectionToPack - point in which the projection of the point onto the plane is stored. Modified.

Returns:

whether the method succeeded or not.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

orthogonalProjectionCopy

public us.ihmc.euclid.tuple3D.Point3D orthogonalProjectionCopy(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointToProject)

Computes the orthogonal projection of the given 3D point on this 3D line.

WARNING: This method generates garbage.

Parameters:

pointToProject - the point to compute the projection of. Not modified.

Returns:

the projection of the point onto the plane or null if the method failed.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

set

public void set(double pointOnPlaneX,
                double pointOnPlaneY,
                double pointOnPlaneZ,
                double planeNormalX,
                double planeNormalY,
                double planeNormalZ)

Redefines this plane with a new point and a new normal.

Parameters:

pointOnPlaneX - the new x-coordinate of the point on this plane.

pointOnPlaneY - the new y-coordinate of the point on this plane.

pointOnPlaneZ - the new z-coordinate of the point on this plane.

planeNormalX - the new x-component of the normal of this plane.

planeNormalY - the new y-component of the normal of this plane.

planeNormalZ - the new z-component of the normal of this plane.

Throws:

java.lang.RuntimeException - if the new normal is unreasonably small.

set

public void set(Plane3D other)

Sets this plane to be the same as the given plane.

Specified by:

set in interface us.ihmc.euclid.interfaces.Settable<Plane3D>

Parameters:

other - the other plane to copy. Not modified.

Throws:

java.lang.RuntimeException - if the other plane has not been initialized yet.

set

public void set(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly firstPointOnPlane,
                us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly secondPointOnPlane,
                us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly thirdPointOnPlane)

Redefines this plane such that it goes through the three given points.

Parameters:

firstPointOnPlane - first point on this plane. Not modified.

secondPointOnPlane - second point on this plane. Not modified.

thirdPointOnPlane - second point on this plane. Not modified.

Throws:

java.lang.RuntimeException - if at least two of the given points are exactly equal.

java.lang.RuntimeException - if the plane normal could not be computed from the three given points.

set

public void set(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointOnPlane,
                us.ihmc.euclid.tuple3D.interfaces.Vector3DReadOnly planeNormal)

Redefines this plane with a new point and a new normal.

Parameters:

pointOnPlane - new point on this plane. Not modified.

planeNormal - new normal of this plane. Not modified.

Throws:

java.lang.RuntimeException - if the new normal is unreasonably small.

setNormal

public void setNormal(double normalX,
                      double normalY,
                      double normalZ)

Changes the normal of this plane by setting it to the normalized value of the given vector.

Parameters:

normalX - the new x-component of the normal of this normal.

normalY - the new y-component of the normal of this normal.

normalZ - the new z-component of the normal of this normal.

Throws:

java.lang.RuntimeException - if the new normal is unreasonably small.

setNormal

public void setNormal(us.ihmc.euclid.tuple3D.interfaces.Vector3DReadOnly planeNormal)

Changes the direction of this plane by setting it to the normalized value of the given vector.

Parameters:

planeNormal - new normal of this plane. Not modified.

Throws:

java.lang.RuntimeException - if the new normal is unreasonably small.

setPoint

public void setPoint(double pointX,
                     double pointY,
                     double pointZ)

Changes the point through which this plane has to go.

Parameters:

pointX - the new x-coordinate of the point on this plane.

pointY - the new y-coordinate of the point on this plane.

pointZ - the new z-coordinate of the point on this plane.

setPoint

public void setPoint(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly pointOnPlane)

Changes the point through which this plane has to go.

Parameters:

pointOnPlane - new point on this plane. Not modified.

setToNaN

public void setToNaN()

Sets the point and normal of this plane to Double.NaN. After calling this method, this plane becomes invalid. A new valid point and valid normal will have to be set so this plane is again usable.

Specified by:

setToNaN in interface us.ihmc.euclid.interfaces.Clearable

setToZero

public void setToZero()

Sets the point and vector of this plane to zero. After calling this method, this plane becomes invalid. A new valid point and valid normal will have to be set so this plane is again usable.

Specified by:

setToZero in interface us.ihmc.euclid.interfaces.Clearable

signedDistance

public double signedDistance(us.ihmc.euclid.tuple3D.interfaces.Point3DReadOnly point)

Computes the minimum signed distance the given 3D point and this plane.

The returned value is negative when the query is located below the plane, positive otherwise.

Parameters:

point - 3D point to compute the distance from the plane. Not modified.

Returns:

the signed distance between the point and this plane.

Throws:

java.lang.RuntimeException - if this plane has not been initialized yet.

toString

public java.lang.String toString()

Provides a String representation of this plane 3D as follows:
Plane 3D: point = (x, y, z), normal = (x, y, z)

Overrides:

toString in class java.lang.Object

Returns:

the String representing this plane 3D.

geometricallyEquals

public boolean geometricallyEquals(Plane3D other,
                                   double epsilon)

Compares this to other to determine if the two planes are geometrically similar.

Two planes are considered geometrically equal if they are coincident. Two planes that are geometrically equal can have normals pointing opposite direction.

Specified by:

geometricallyEquals in interface us.ihmc.euclid.interfaces.GeometricallyComparable<Plane3D>

Parameters:

other - the plane to compare to.

epsilon - the tolerance of the comparison.

Returns:

true if the planes are coincident, false otherwise.