vclip
Class ConvexPolyhedron

java.lang.Object
  vclip.ConvexPolyhedron

public class ConvexPolyhedron

extends java.lang.Object

A convex polyhedron.

Author:

Brian Mirtich (C++ version), Eddy Boxerman, John E. Lloyd (Java port)

See Also:

Copyright information

Constructor Summary

ConvexPolyhedron()
Creates an empty ConvexPolyhedron, which should then be initialized (such as with a call to scan).

ConvexPolyhedron(double[] coords, int[][] faceIndices)
Constructs a polyhedron given a list of vertices and a list of face indices.

ConvexPolyhedron(javax.vecmath.Point3d[] vlist, int[][] faceIndices)
Constructs a polyhedron given a list of vertices and a list of face indices.

ConvexPolyhedron(java.io.Reader reader, boolean namedFormat)
Constructs a ConvexPolyhedron by reading information from the supplied reader.

ConvexPolyhedron(java.io.StreamTokenizer stok, boolean namedFormat)
Constructs a ConvexPolyhedron by reading information from a StreamTokenizer.

Method Summary

static ConvexPolyhedron	createBox(double wx, double wy, double wz)
static ConvexPolyhedron	createCone(double rtop, double rbot, double h, int nsides)
static ConvexPolyhedron	createCylinder(double r, double h, int nsides)
static ConvexPolyhedron	createPrism(double[] xy, double h)
static ConvexPolyhedron	createPrism(double[] xyTop, double[] xyBot, double h)
static ConvexPolyhedron	createRoundedCylinder(double r, double h, int nslices)
static ConvexPolyhedron	createSphere(double r, int nslices)
Feature	findFeature(java.lang.String name)
Edge	getEdge(int vidx1, int vidx2)
Edge[]	getEdges() Returns the edge features for this polyhedron.
Face	getFace(int idx)
Face[]	getFaces() Returns the face features for this polyhedron.
Vertex	getVert(int idx)
Vertex[]	getVerts() Returns the vertex features for this polyhedron.
void	hideEdges(int[] elist)
void	hideFaces(int[] flist)
void	hidePrismFace(int fi)
void	hideVerts(int[] vlist)
int	numFeatures() Returns the total number of features (vertices, edges, faces) on this polyhedron.
void	scan(java.io.Reader reader) Sets the polyhedron using information obtained from a reader.
void	scan(java.io.StreamTokenizer stok) Sets the polyhedron using information obtained from a StreamTokenizer.
void	scanNamedFormat(java.io.Reader reader) Sets the polyhedron using information obtained from a reader.
void	scanNamedFormat(java.io.StreamTokenizer stok) Sets the polyhedron using information obtained from a StreamTokenizer.
void	set(double[] coords, int[][] faceIndices) Sets this polyhedron given a list of vertices and a list of face indices.
void	set(javax.vecmath.Point3d[] vlist, int[][] faceIndices) Sets this polyhedron given a list of vertices and a list of face indices.
java.lang.String	sprintf() Outputs a string representation of this polyhedron, using the format used by scan(Reader).
java.lang.String	sprintfNamedFormat() Outputs a string representation of this polyhedron, using the format used by scanNamedFormat(Reader).
java.lang.String	toString() Generates a string representation of this polyhedron, using sprintfNamedFormat().
double	vclip(ClosestPointPair cpair, ConvexPolyhedron poly2, javax.vecmath.Matrix4d X12, javax.vecmath.Matrix4d X21) Computes the distance, along with the closest points and features, between this polyhedron and a second one.

Methods inherited from class java.lang.Object

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

Constructor Detail

ConvexPolyhedron

public ConvexPolyhedron()

Creates an empty ConvexPolyhedron, which should then be initialized (such as with a call to scan).

ConvexPolyhedron

public ConvexPolyhedron(javax.vecmath.Point3d[] vlist,
                        int[][] faceIndices)

Constructs a polyhedron given a list of vertices and a list of face indices. Each face is represented by an integer array listing its vertex indices in counter-clockwise order. The index of a vertex gives its location within the vertex list.

Parameters:

vlist - vertices for the polyhedron

faceIndices - face index arrays

Throws:

java.lang.IllegalArgumentException - if the vertex and face information does not describe a proper convex polyhedron

ConvexPolyhedron

public ConvexPolyhedron(double[] coords,
                        int[][] faceIndices)

Constructs a polyhedron given a list of vertices and a list of face indices. Each face is represented by an integer array listing its vertex indices in counter-clockwise order. The index of a vertex gives its location within the coordinate list.

Parameters:

coords - coordinates of the polyhedron vertices, giving the x, y, and z values of each vertex, in order. The length of this array will be three times the number of vertices.

faceIndices - face index arrays

Throws:

java.lang.IllegalArgumentException - if the vertex and face information does not describe a proper convex polyhedron

ConvexPolyhedron

public ConvexPolyhedron(java.io.Reader reader,
                        boolean namedFormat)
                 throws java.io.IOException

Constructs a ConvexPolyhedron by reading information from the supplied reader.

Parameters:

reader - supplies the information used to define the polyhedron.

namedFormat - if true, then the polyhedron will be read using the named format used by scanNamedFormat. Otherwise, the .obj format of scan will be used

Throws:

java.io.IOException - if an I/O or format error occured

See Also:

scanNamedFormat(Reader), scan(Reader)

ConvexPolyhedron

public ConvexPolyhedron(java.io.StreamTokenizer stok,
                        boolean namedFormat)
                 throws java.io.IOException

Constructs a ConvexPolyhedron by reading information from a StreamTokenizer.

Parameters:

stok - supplies the information used to define the polyhedron.

namedFormat - if true, then the polyhedron will be read using the named format used by scanNamedFormat. Otherwise, the .obj format of scan will be used

Throws:

java.io.IOException - if an I/O or format error occured

See Also:

scanNamedFormat(Reader), scan(Reader)

Method Detail

findFeature

public Feature findFeature(java.lang.String name)

set

public void set(javax.vecmath.Point3d[] vlist,
                int[][] faceIndices)

Sets this polyhedron given a list of vertices and a list of face indices. Each face is represented by an integer array listing its vertex indices in counter-clockwise order. The index of a vertex gives its location within the vertex list.

Parameters:

vlist - vertices for the polyhedron

faceIndices - face index arrays

Throws:

java.lang.IllegalArgumentException - if the vertex and face information does not describe a proper convex polyhedron

set

public void set(double[] coords,
                int[][] faceIndices)

Sets this polyhedron given a list of vertices and a list of face indices. Each face is represented by an integer array listing its vertex indices in counter-clockwise order. The index of a vertex gives its location within the coordinate list.

Parameters:

coords - coordinates of the polyhedron vertices, giving the x, y, and z values of each vertex, in order. The length of this array will be three times the number of vertices.

faceIndices - face index arrays

Throws:

java.lang.IllegalArgumentException - if the vertex and face information does not describe a proper convex polyhedron

scanNamedFormat

public void scanNamedFormat(java.io.Reader reader)
                     throws java.io.IOException

Sets the polyhedron using information obtained from a reader. This information should be supplied according the named format used in Brian Mirtich's original V-Clip implementation:

First, the vertices of the polyhedra are listed, each with a name, followed by three numbers giving the coordinates. If the vertex name is given as -, then a name of the form vn will be automatically generated, where n denotes the number of the vertex. The character * is used to terminate the vertex list.

Second, the faces are listed, each with a name, followed by a list (on the same line) of the names of the vertices (in counter-clockwise order). If the face name is given as -, then a name of the form fn will be generated, where n is the number of the face. The character * is used to terminate the face list.

A simple example defining a tetrahedron is

 origin 0 0 0
 x      1 0 0
 y      0 1 0
 z      0 0 1
 *
 xy	origin y x
 yz	origin z y
 zx	origin x z
 base	x y z
 

Using automatic naming, the same example would look like

 - 0 0 0
 - 1 0 0
 - 0 1 0
 - 0 0 1
 *
 - v0 v2 v1
 - v0 v3 v2
 - v0 v1 v3
 - v1 v2 v3
 

Parameters:

reader - supplies the information used to describe the polyhedron.

Throws:

java.io.IOException - if an I/O or format error occured

scanNamedFormat

public void scanNamedFormat(java.io.StreamTokenizer stok)
                     throws java.io.IOException

Sets the polyhedron using information obtained from a StreamTokenizer. Otherwise identical to scanNamedFormat(Reader).

Parameters:

stok - supplies the information used to describe the polyhedron.

Throws:

java.io.IOException - if an I/O or format error occured

See Also:

scanNamedFormat(Reader)

scan

public void scan(java.io.StreamTokenizer stok)
          throws java.io.IOException

Sets the polyhedron using information obtained from a StreamTokenizer. Otherwise identical to scan(Reader).

Parameters:

stok - supplies the information used to describe the polyhedron.

Throws:

java.io.IOException - if an I/O or format error occured

See Also:

scan(Reader)

scan

public void scan(java.io.Reader reader)
          throws java.io.IOException

Sets the polyhedron using information obtained from a reader. This information should be supplied in an Alias Wavefront .obj format:

First, the vertices of the polyhedra are listed, each preceded with the character v, followed by three numbers giving the coordinates.

Second, the faces are listed, each preceded by the character f, followed by a counter-clockwise list of the vertex indices. Each index refers to the vertex's location within the vertex list, with the first vertex numbered as 1. The keyword end is used to terminate the face list.

A simple example defining a tetrahedron is

 v 0.0 0.0 0.0
 v 1.0 0.0 0.0
 v 0.0 1.0 0.0
 v 0.0 0.0 1.0
 f 0 2 1
 f 0 3 2
 f 0 1 3
 f 1 2 3
 end
 

Parameters:

reader - supplies the information used to describe the polyhedron.

Throws:

java.io.IOException - if an I/O or format error occured

getVerts

public final Vertex[] getVerts()

Returns the vertex features for this polyhedron.

Returns:

vertex feature array

getVert

public final Vertex getVert(int idx)

getEdges

public final Edge[] getEdges()

Returns the edge features for this polyhedron.

Returns:

edge feature array

getEdge

public final Edge getEdge(int vidx1,
                          int vidx2)

getFaces

public final Face[] getFaces()

Returns the face features for this polyhedron.

Returns:

face feature array

getFace

public final Face getFace(int idx)

numFeatures

public final int numFeatures()

Returns the total number of features (vertices, edges, faces) on this polyhedron.

Returns:

number of features

sprintf

public java.lang.String sprintf()

Outputs a string representation of this polyhedron, using the format used by scan(Reader).

Returns:

.obj representation of this polyhedron

sprintfNamedFormat

public java.lang.String sprintfNamedFormat()

Outputs a string representation of this polyhedron, using the format used by scanNamedFormat(Reader).

Returns:

named format representation of this polyhedron

toString

public java.lang.String toString()

Generates a string representation of this polyhedron, using sprintfNamedFormat().

Returns:

named format representation of this polyhedron

See Also:

sprintfNamedFormat()

vclip

public double vclip(ClosestPointPair cpair,
                    ConvexPolyhedron poly2,
                    javax.vecmath.Matrix4d X12,
                    javax.vecmath.Matrix4d X21)

Computes the distance, along with the closest points and features, between this polyhedron and a second one. The cpair parameter is used to return the closest point and feature information. To facilitate fast computation, this parameter should also be initialized with a guess of the closest features between the two polyhedra (using ClosestPointPair.setFeatures). This guess is usually just the features that were determined the last time vclip was called for this pair of polyhedra. If no feature guess is given, then vclip starts with the first vertex of each polyhedron.

If the two polyhedra are interpenetrating, the routine returns a non-positive number giving a roughstimate of the interpenetration distance. The closest feature information in this case is not particularly useful.

Parameters:

cpair - returns closest point pair information, and supplies an initial guess of the closest features.

poly2 - the second polyhedron

X12 - spatial transform from the reference frame of the first polyhedron to the reference frame of the second

X21 - spatial transform from the reference frame of the second polyhedron to the reference frame of the first

Returns:

distance between the two polyhedra, or a number <= 0 if the two polyhedra are interpenetrating.

createBox

public static ConvexPolyhedron createBox(double wx,
                                         double wy,
                                         double wz)

createCylinder

public static ConvexPolyhedron createCylinder(double r,
                                              double h,
                                              int nsides)

createSphere

public static ConvexPolyhedron createSphere(double r,
                                            int nslices)

createRoundedCylinder

public static ConvexPolyhedron createRoundedCylinder(double r,
                                                     double h,
                                                     int nslices)

createCone

public static ConvexPolyhedron createCone(double rtop,
                                          double rbot,
                                          double h,
                                          int nsides)

createPrism

public static ConvexPolyhedron createPrism(double[] xy,
                                           double h)

createPrism

public static ConvexPolyhedron createPrism(double[] xyTop,
                                           double[] xyBot,
                                           double h)

hideVerts

public void hideVerts(int[] vlist)

hideFaces

public void hideFaces(int[] flist)

hideEdges

public void hideEdges(int[] elist)

hidePrismFace

public void hidePrismFace(int fi)