|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object vclip.PolyTree
A hierarchically organized collection of
convex polyhedra and the primary class for
invoking vclip
.
The convex decomposition of
a non-convex polyhedron can be represented as a PolyTree.
A PolyTree is either atomic or compound. An atomic
PolyTree is composed of a single convex polyhedron, which can
be obtained using the getPolyhedron
method.
A compound PolyTree consists of one of more PolyTree components,
plus a convex polyhedron which acts as a bounding hull
for the components. For compound PolyTrees,
getPolyhedron
returns the bounding hull.
The number of components in a compound PolyTree is returned
by numComponents
. The number of nodes
is the total number of PolyTrees in the hierarchy, and is returned
by numNodes
. The number of leaves is the total
number of atomic PolyTrees in the hierarchy, and is returned by
numLeaves
.
Each PolyTree has a local coordinate frame with respect
to which components are attached and polyhedron vertices are represented.
All components within a PolyTree also share a common reference
frame, with respect to which vclip
is called.
The transformation from the local frame to the reference frame
call be obtained using the method
getTransform
, and can be changed
using setTransform
.
When a PolyTree is added to another as a component (see
addComponent
), the
component's reference frame is changed to that of the parent
PolyTree.
The distance, and associated closest points and features,
between a pair of PolyTrees is determined using vclip
,
which is based on Brian Mirtich's Vclip algorithm, published as
``V-Clip: Fast and Robust Polyhedral Collision Detection'',
ACM Transactions on Graphics, July, 1997.
A PolyTree can be created by reading information in from a
stream, specified either in a constructor or in a method
such as scan
.
A whole collection of PolyTrees can be read into a Map
using the scanLibrary
method.
An atomic PolyTree can
also be constructed directly from a ConvexPolyhedron
, and compound PolyTrees can be created
explictly using the method addComponent
and then calling buildBoundingHull
.
More information on PolyTree creation, and bounding hulls,
can be found in the vclip
package documentation.
Mass and volume properties are computed automatically
for the polyhedron associated with a PolyTree, and can be
obtained using the methods
volume
,
firstMomentOfVolume
,
secondMomentOfVolume
,
productOfVolume
, and
radius
.
These quantities are computed using algorithms described in Brian Mirtich,
``Fast and Accurate Computation of Polyhedral
Mass Properties'', Journal of Graphics Tools, Volume 1,
Number 2, 1996.
Assuming a uniform mass density, they can be used to determine
the center-of-mass and the inertia tensor,
which for a mass of unity, can be obtained using
centerOfMass
and
inertiaTensor
.
All of these quantities are computed with
respect to the PolyTree's local coordinate frame.
Field Summary | |
static int |
CONVEX_HULL
Bounding hull is a convex hull. |
static int |
CUSTOM_HULL
Bounding hull is a custom polyhedron, specified with setPolyhedron . |
static int |
NO_HULL
There is no bounding hull. |
static int |
OBB_HULL
Bounding hull is an oriented-bounding box. |
Constructor Summary | |
PolyTree(java.lang.String name)
Creates an empty PolyTree. |
|
PolyTree(java.lang.String name,
ConvexPolyhedron poly)
Creates an atomic PolyTree from a convex polyhedron. |
|
PolyTree(java.lang.String name,
java.util.Map library,
java.lang.String origName)
Creates a PolyTree by copying one from a PolyTree library. |
|
PolyTree(java.lang.String name,
PolyTree ptree)
Creates a PolyTree by copying another. |
Method Summary | |
void |
addComponent(java.lang.String name,
PolyTree orig)
Adds a component to this PolyTree. |
void |
addComponent(java.lang.String name,
PolyTree orig,
javax.vecmath.Matrix4d Xrl)
Adds a component to this PolyTree. |
void |
buildAllBoundingHulls(int type)
Recursively builds a bounding hull of a prescribed type for this PolyTree and every compound component PolyTree in the hierarchy. |
void |
buildBoundingHull()
Builds a bounding hull for this PolyTree, using the default bounding hull type. |
void |
buildBoundingHull(int type)
Builds a bounding hull of a prescribed type for this PolyTree. |
void |
centerOfMass(javax.vecmath.Vector3d com)
Returns the center of mass of this PolyTree's polyhedron (assuming a uniform mass density), with respect to the local frame. |
void |
clearComponents()
Clear all the components in this PolyTree, and set the bounding hull type to NO_HULL . |
static PolyTree |
createBox(java.lang.String name,
double wx,
double wy,
double wz)
|
static PolyTree |
createCone(java.lang.String name,
double rtop,
double rbot,
double h,
int nsides)
|
static PolyTree |
createCylinder(java.lang.String name,
double r,
double h,
int nsides)
|
static PolyTree |
createPrism(java.lang.String name,
double[] xy,
double h)
|
static PolyTree |
createPrism(java.lang.String name,
double[] xyTop,
double[] xyBot,
double h)
|
static PolyTree |
createRoundedCylinder(java.lang.String name,
double r,
double h,
int nslices)
|
static PolyTree |
createSphere(java.lang.String name,
double r,
int nslices)
|
javax.vecmath.Vector3d |
firstMomentOfVolume()
Returns the first moment of volume for this PolyTree's polyhedron, with respect to the local frame. |
int |
getBoundingHullType()
Gets the type of this PolyTree's bounding hull. |
java.util.Iterator |
getComponents()
Returns the components associated with this PolyTree. |
static int |
getDefaultBoundingHullType()
Returns the default bounding hull type. |
java.lang.String |
getName()
Gets the name of this PolyTree. |
ConvexPolyhedron |
getPolyhedron()
Returns the polyhedron associated with this PolyTree. |
javax.vecmath.Matrix4d |
getTransform()
Returns the transformation from this PolyTree's local frame to its reference frame. |
void |
inertiaTensor(javax.vecmath.Matrix3d J)
Returns the inertia tensor of this PolyTree's polyhedron assuming a uniform mass density and a mass of 1. |
boolean |
isAtomic()
Returns true if this PolyTree is atomic (i.e., is represented by only one polyhedron, and has no subcomponents). |
boolean |
isCompound()
Returns true if this PolyTree is compound (i.e., is composed of one or more PolyTree subcomponents). |
int |
numComponents()
Returns the number of PolyTree components which are direct children of this PolyTree. |
int |
numLeaves()
Returns the total number of atomic PolyTrees located in the hierarchy under this PolyTree. |
int |
numNodes()
Returns the total number of PolyTrees located in the hierarchy under this PolyTree. |
javax.vecmath.Vector3d |
productOfVolume()
Returns the product of volume for this PolyTree's polyhedron, with respect to the local frame. |
double |
radius()
Returns the ``radius'' of the PolyTree, relative to the center of volume. |
void |
scan(java.io.Reader reader,
java.util.Map library,
boolean updateLibrary,
boolean namedFormat)
Reads in a PolyTree from a Reader. |
void |
scan(java.io.StreamTokenizer stok,
java.util.Map library,
boolean updateLibrary,
boolean namedFormat)
Reads in a PolyTree from a StreamTokenizer. |
static void |
scanLibrary(java.io.StreamTokenizer stok,
java.util.Map library,
boolean namedFormat)
Reads a library of PolyTrees from a StreamTokenizer. |
static void |
scanLibrary(java.lang.String fileName,
java.util.Map library,
boolean namedFormat)
Reads a library of PolyTrees from a file. |
javax.vecmath.Vector3d |
secondMomentOfVolume()
Returns the second moment of volume for this PolyTree's polyhedron, with respect to the local frame. |
void |
set(PolyTree ptree)
Sets this PolyTree to a copy of another PolyTree. |
static void |
setDefaultBoundingHullType(int type)
Sets the default bounding hull type, which will be used when the bounding hull is created automatically (such as when a PolyTree is created using scan ). |
void |
setName(java.lang.String name)
Sets the name for this PolyTree. |
void |
setPolyhedron(ConvexPolyhedron poly)
Sets the convex polyhedron associated with the PolyTree. |
void |
setTransform(javax.vecmath.Matrix4d Xlr)
Sets the local-to-reference frame transform of this PolyTree. |
java.lang.String |
toString()
Returns a string representation of this PolyTree. |
double |
vclip(DistanceReport rep,
PolyTree ptree2,
javax.vecmath.Matrix4d Xr2r1,
double distLimit,
ClosestFeaturesHT ht)
|
double |
vclip(DistanceReport rep,
PolyTree ptree2,
javax.vecmath.Matrix4d Xr2r1,
double distLimit,
ClosestFeaturesHT ht,
FeaturePair startFeatures)
Computes the distance between this PolyTree and a second PolyTree. |
double |
volume()
Returns the volume of this PolyTree's polyhedron. |
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
public static final int NO_HULL
public static final int OBB_HULL
public static final int CONVEX_HULL
public static final int CUSTOM_HULL
setPolyhedron
.
Constructor Detail |
public PolyTree(java.lang.String name)
name
- name of the PolyTree (optional;
can be set to null
).public PolyTree(java.lang.String name, PolyTree ptree)
name
- name for the new PolyTree (optional;
can be set to null
).ptree
- the PolyTree to be copiedpublic PolyTree(java.lang.String name, ConvexPolyhedron poly)
name
- name of the PolyTree (optional;
can be set to null
).poly
- the polyhedronpublic PolyTree(java.lang.String name, java.util.Map library, java.lang.String origName) throws java.lang.IllegalArgumentException
name
- name of the PolyTree (optional;
can be set to null
).library
- PolyTree library (a map of string names
to PolyTrees).origName
- name of the original PolyTree in the libary
java.lang.IllegalArgumentException
- if the original PolyTree
is not found in the library.Method Detail |
public static void setDefaultBoundingHullType(int type)
scan
).
type
- default bounding hull type. Must be either
OBB_HULL
or CONVEX_HULL
java.lang.IllegalArgumentException
- if an illegal type is specifiedgetDefaultBoundingHullType()
public static int getDefaultBoundingHullType()
setDefaultBoundingHullType(int)
public int getBoundingHullType()
NO_HULL
, OBB_HULL
,
CONVEX_HULL
,
or CUSTOM_HULL
)public void buildBoundingHull()
getDefaultBoundingHullType()
,
buildBoundingHull(int)
public void buildBoundingHull(int type)
type
- type of bounding hull to build. Must be either
OBB_HULL
or CONVEX_HULL
getBoundingHullType()
public void buildAllBoundingHulls(int type)
type
- type of bounding hull to build. Must be either
OBB_HULL
or CONVEX_HULL
getBoundingHullType()
public void setPolyhedron(ConvexPolyhedron poly)
CUSTOM_HULL
).
Note that the polyhedron is not copied.
poly
- convex polyhedronpublic void setName(java.lang.String name)
name
- for this PolyTreepublic java.lang.String getName()
public boolean isCompound()
public boolean isAtomic()
public void set(PolyTree ptree)
ptree
- the other PolyTreepublic void addComponent(java.lang.String name, PolyTree orig)
Adding a component will automically turn this PolyTree into a compound PolyTree, and any polyhedron presently associated with this PolyTree will become (by default) the bounding hull polyhedron.
name
- optional name for the component PolyTreeorig
- PolyTree that is copied to form the componentpublic void addComponent(java.lang.String name, PolyTree orig, javax.vecmath.Matrix4d Xrl)
Xrl
.
Adding a component will automically turn this PolyTree into a compound PolyTree, and any polyhedron presently associated with this PolyTree will become (by default) the bounding hull polyhedron.
name
- optional name for the component PolyTreeorig
- PolyTree that is copied to form the componentXrl
- transform from the reference frame of the
original PolyTree to the local frame of this PolyTreepublic void clearComponents()
NO_HULL
.
Any existing polyhedron will not be changed.
public java.util.Iterator getComponents()
public final void setTransform(javax.vecmath.Matrix4d Xlr)
Xlr
- new local-to-reference frame transformationpublic final javax.vecmath.Matrix4d getTransform()
public final ConvexPolyhedron getPolyhedron()
The vertex coordinates of this polyhedron are defined with respect to the PolyTree's local frame.
public final int numComponents()
public final int numNodes()
public final int numLeaves()
public final java.lang.String toString()
public final double volume()
public final javax.vecmath.Vector3d firstMomentOfVolume()
public final javax.vecmath.Vector3d secondMomentOfVolume()
public final javax.vecmath.Vector3d productOfVolume()
public final double radius()
public final void centerOfMass(javax.vecmath.Vector3d com)
com
- returns the center of masspublic final void inertiaTensor(javax.vecmath.Matrix3d J)
J
- returns the inertia tensorpublic final double vclip(DistanceReport rep, PolyTree ptree2, javax.vecmath.Matrix4d Xr2r1, double distLimit, ClosestFeaturesHT ht)
public final double vclip(DistanceReport rep, PolyTree ptree2, javax.vecmath.Matrix4d Xr2r1, double distLimit, ClosestFeaturesHT ht, FeaturePair startFeatures)
In particular, this minimum distance in generally the
minimum distance over all pairs of convex polyhedra
associated with the two PolyTrees. However, if the
argument distLimit
is non-negative, and the bounding
hull for a compound component A is determined to be at least
distLimit
away from another component B, then
the bounding hull distance is used instead as the
distance between A and B and the components of A are
not examined. This speeds up computations for PolyTrees
which are more than a certain distance from each other,
but also means that the real distance between two PolyTrees
may in fact be larger than the returned value.
If there is a collision between the two PolyTrees, then a non-positive distance value is returned.
The
closest points and features associated with the minimum
distance are returned in an optional DistanceReport
object. If distLimit
is
active, then these points and features may belong to the
bounding hull of a compound component, rather than the
polyhedron of an atomic PolyTree. In case of a collision,
the associated closest points and features may not be that
meaningfull.
The distance report may also return the closest
point pairs between atomic PolyTrees that are within
a certain maximum distance. See the DistanceReport
documentation
for details.
vclip
computations are often much faster
if the closest features between pairs of PolyTrees
are stored and then used as an initial guess
in subsequent computations. The optional argument
ht
supplies a
ClosestFeaturesHT
for storing
such information.
rep
- (optional) returns
information about the closest pairs of points and features
between the two PolyTrees.ptree2
- the second PolyTreeXr2r1
- transformation from the reference frame
of the second PolyTree to the reference frame of the firstdistLimit
- if non-negative, tells vclip
to not consider distances to a PolyTree's components
if the distance to its bounding hull
equals or exceeds distLimit
ht
- (optional) record of the most recent feature pairs
computed between different PolyTrees
DistanceReport
public void scan(java.io.Reader reader, java.util.Map library, boolean updateLibrary, boolean namedFormat) throws java.io.IOException
atomic name polyhedronwhere name is an identifier naming the PolyTree, and polyhedron is a specification for a polyhedron (which should take the form specified in either
ConvexPolyhedron.scanNamedFormat(Reader)
or
ConvexPolyhedron.scan(Reader)
, depending
on whether nameFormat
is true
).
A compound PolyTree is specified by giving a list of
its component PolyTrees between square brackets, as in
compound name [ transform PolyTree transform PolyTree ... ]name is an identifier naming the PolyTree.
transform specifies a transformation from the reference frame of the component to this PolyTree's local frame, and PolyTree is either a specification for a PolyTree (as described here), or a string identifier naming a PolyTree that can copied from the supplied library.
A transform specification consists of a series of translation and rotation terms listed between square brackets, as in:
[ trans 1 2 3 rotx 30 roty 20 ],which describes a translation along (1,2,3), followed by a rotation of 30 degrees about the x axis, followed by a rotation of 20 degrees about the y axis.
Succesive translations and rotations are accumulated from left to right. The terms that can be specified are:
trans x y z
rotx deg
roty deg
rotz deg
rot ux uy uz deg
A simple example of a compound PolyTree specification is
compound two-cubes [ [trans -1 0 0] unit-cube [trans +1 0 0] unit-cube ]which creates a compound PolyTree named
two-cubes
,
with two components, each a copy of a PolyTree named
unit-cube
, translated by -1 and
1 (respectively) along the x axis.
reader
- the Reader which supplies the inputlibrary
- an optional library from which to look up referenced
PolyTrees. The library is simply a map of string names
onto PolyTree objects.updateLibrary
- if true
, then
the input PolyTree will be inserted
into the supplied library (assuming library
is
not null
)namedFormat
- if true
, then
polyhedra will be read in using the named format
used by ConvexPolyhedron.scanNamedFormat
.
Otherwise, the .obj
format of
ConvexPolyhedron.scan
will be used
java.io.IOException
- if an I/O or format error occursscan(StreamTokenizer,Map,boolean,boolean)
public void scan(java.io.StreamTokenizer stok, java.util.Map library, boolean updateLibrary, boolean namedFormat) throws java.io.IOException
scan(Reader,Map,boolean,boolean)
.
stok
- StreamTokenizer which supplies the inputlibrary
- an optional library from which to look up referenced
PolyTrees.updateLibrary
- if true
, then
the input PolyTree will be inserted
into the supplied librarynamedFormat
- if true
, then
polyhedra will be read in using the named format
used by ConvexPolyhedron.scanNamedFormat
.
Otherwise, the .obj
format of
ConvexPolyhedron.scan
will be used
java.io.IOException
- if an I/O or format error occursscan(Reader,Map,boolean,boolean)
public static void scanLibrary(java.lang.String fileName, java.util.Map library, boolean namedFormat) throws java.io.IOException
fileName
- name of the filelibrary
- library into which the PolyTrees read from
the file will be placed. The library is simply
a map of names onto PolyTree objects.namedFormat
- if true
, then
polyhedra will be read in using the named format
used by ConvexPolyhedron.scanNamedFormat
.
Otherwise, the .obj
format of
ConvexPolyhedron.scan
will be used
java.io.IOException
- if an I/O or format error occursscanLibrary(StreamTokenizer,Map,boolean)
public static void scanLibrary(java.io.StreamTokenizer stok, java.util.Map library, boolean namedFormat) throws java.io.IOException
stok
- tokenizer from which to read librarylibrary
- library into which the PolyTrees read from
the file will be placed. The library is simply
a map of names onto PolyTree objects.namedFormat
- if true
, then
polyhedra will be read in using the named format
used by ConvexPolyhedron.scanNamedFormat
.
Otherwise, the .obj
format of
ConvexPolyhedron.scan
will be used
java.io.IOException
- if an I/O or format error occursscanLibrary(String,Map,boolean)
public static PolyTree createBox(java.lang.String name, double wx, double wy, double wz)
public static PolyTree createCylinder(java.lang.String name, double r, double h, int nsides)
public static PolyTree createSphere(java.lang.String name, double r, int nslices)
public static PolyTree createRoundedCylinder(java.lang.String name, double r, double h, int nslices)
public static PolyTree createCone(java.lang.String name, double rtop, double rbot, double h, int nsides)
public static PolyTree createPrism(java.lang.String name, double[] xyTop, double[] xyBot, double h)
public static PolyTree createPrism(java.lang.String name, double[] xy, double h)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |