vclip
Class DistanceReport

java.lang.Object
  vclip.DistanceReport

public class DistanceReport

extends java.lang.Object

Used by vclip to return distance information.

This information includes the closest point pair between the two objects (obtained using getClosestPair). It also includes, optionally, a list of close point pairs whose distance is within a threshold prescribed by setMaxPairDistance. Up to one such close point pair may be generated for each pair of convex polyhedra associated with the two objects.

Author:

John E. Lloyd

Field Summary

static double

DEFAULT_PROMOTION_TOL

Constructor Summary

DistanceReport()
Creates a DistanceReport which does not report close point pairs.

DistanceReport(DistanceReport rep)
Creates a DistanceReport by copying an existing one.

DistanceReport(int maxClosePairs)
Creates a DistanceReport with room for reporting a maximum number of close point pairs.

Method Summary

void	clear() Clears the information in this report.
ClosestPointPair[]	getClosePairs() Gets the close point pairs in this report.
double	getClosestDistance() Gets the closest distance associated with this report.
ClosestPointPair	getClosestPair() Gets the closest point pairs in this report.
int	getMaxClosePairs() Returns the maximum number of close point pairs that can be reported by this report.
double	getMaxPairDistance() Gets the maximum close point pair distance for this report.
double	getPromotionTolerance() Returns the angular tolerance used to promote features.
int	numClosePairs() Returns the number of close point pairs in this report.
boolean	promotionEnabled() Queries whether or not feature promotion is enabled.
void	set(DistanceReport rep) Sets this distance report to a copy of the supplied one.
void	setFeaturePromotion(boolean enable, double angtol) Enables or disables feature promotion.
void	setMaxClosePairs(int maxClosePairs) Sets the maximum number of close point pairs that can be reported by this report.
void	setMaxPairDistance(double dist) Sets the maximum close point pair distance for this report.
void	transformFirstPoints(javax.vecmath.Matrix4d T1R) Transforms the first point, as well as the normals, of each point pair in this distance report into a new coordinate frame (typically that associated with the second points).
void	transformSecondPoints(javax.vecmath.Matrix4d T2R) Transforms the second point of each point pair in this distance report into a new coordinate frame (typically that associated with the first points).

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_PROMOTION_TOL

public static final double DEFAULT_PROMOTION_TOL

See Also:

Constant Field Values

Constructor Detail

DistanceReport

public DistanceReport(int maxClosePairs)

Creates a DistanceReport with room for reporting a maximum number of close point pairs.

Parameters:

maxClosePairs - maximum number of close point pairs which can be reported

DistanceReport

public DistanceReport()

Creates a DistanceReport which does not report close point pairs.

DistanceReport

public DistanceReport(DistanceReport rep)

Creates a DistanceReport by copying an existing one.

Parameters:

rep - distance report to copy

Method Detail

set

public void set(DistanceReport rep)

Sets this distance report to a copy of the supplied one.

Parameters:

rep - distance report to copy

clear

public void clear()

Clears the information in this report.

numClosePairs

public int numClosePairs()

Returns the number of close point pairs in this report.

Returns:

number of close point pairs

getMaxClosePairs

public int getMaxClosePairs()

Returns the maximum number of close point pairs that can be reported by this report.

Returns:

maximum number of close point pairs

setMaxClosePairs

public void setMaxClosePairs(int maxClosePairs)

Sets the maximum number of close point pairs that can be reported by this report. This clears any existing close pair information.

Parameters:

maxClosePairs - maximum number of close point pairs

getClosePairs

public ClosestPointPair[] getClosePairs()

Gets the close point pairs in this report. Note that only the number returned by numClosePairs will be valid.

Returns:

close point pairs

See Also:

numClosePairs()

getClosestPair

public ClosestPointPair getClosestPair()

Gets the closest point pairs in this report.

Returns:

closest point pair

setMaxPairDistance

public void setMaxPairDistance(double dist)

Sets the maximum close point pair distance for this report. When vclip is called, point pairs whose distance is less than this value will be added to the report, up to a maximum prescribed by getMaxClosePairs.

Parameters:

dist - maximum distance for reporting close point pairs.

See Also:

getMaxPairDistance(), getMaxClosePairs()

getMaxPairDistance

public double getMaxPairDistance()

Gets the maximum close point pair distance for this report.

Returns:

maximum distance for reporting close point pairs.

See Also:

setMaxPairDistance(double)

getClosestDistance

public double getClosestDistance()

Gets the closest distance associated with this report. This is the same value returned by the call to vclip that created this report, and a distance <= 0 indicates a collison.

Returns:

closest distance

transformFirstPoints

public void transformFirstPoints(javax.vecmath.Matrix4d T1R)

Transforms the first point, as well as the normals, of each point pair in this distance report into a new coordinate frame (typically that associated with the second points).

Parameters:

T1R - transformation into the new reference frame.

transformSecondPoints

public void transformSecondPoints(javax.vecmath.Matrix4d T2R)

Transforms the second point of each point pair in this distance report into a new coordinate frame (typically that associated with the first points).

Parameters:

T2R - transformation into the new reference frame.

setFeaturePromotion

public void setFeaturePromotion(boolean enable,
                                double angtol)

Enables or disables feature promotion. If enabled, then features that lie within the distance specified by setMaxPairDistance are ``promoted'', where possible, to the feature which has the highest dimension. Faces have dimension 2, edges have dimenion 1, and vertices have dimension 0. In the most extreme case, a vertex-vertex contact could be promoted to a face-face contact.

Feature promotion is determined by seeing whether adjacent features of higher dimension are within angtol radians of being perpendicular to the contact normal.

Feature promotion may cause more contact pairs to be generated. For example, an edge-face contact is generally associated with two contact pairs, associated with the endpoints of the projection of the edge onto the face. Likewise, a face-face contact will be associated with several contact pairs, each associated with a vertex of the polygon formed by projected one face onto the other.

The extra contact pairs generated by feature promotion are simply added to the set of close point pairs returned by getClosePairs.

Parameters:

enable - set true to enable feature promotion

angtol - angular tolerance (in radians). If negative, then DEFAULT_PROMOTION_TOL is used

See Also:

promotionEnabled(), getPromotionTolerance()

promotionEnabled

public boolean promotionEnabled()

Queries whether or not feature promotion is enabled.

Returns:

true if feature promotion is enabled.

See Also:

setFeaturePromotion(boolean, double)

getPromotionTolerance

public double getPromotionTolerance()

Returns the angular tolerance used to promote features.

Returns:

promotion tolerance (in radians)

See Also:

setFeaturePromotion(boolean, double)