This ContactGeometry subclass represents an arbitrary shape described by a mesh of triangular faces. More...

Inheritance diagram for SimTK::ContactGeometry::TriangleMesh:

Classes
class	OBBTreeNode
	This class represents a node in the Oriented Bounding Box Tree for a TriangleMesh. More...

Public Member Functions
	TriangleMesh (const ArrayViewConst_< Vec3 > &vertices, const ArrayViewConst_< int > &faceIndices, bool smooth=false)
	Create a TriangleMesh. More...

	TriangleMesh (const PolygonalMesh &mesh, bool smooth=false)
	Create a TriangleMesh based on a PolygonalMesh object. More...

int	getNumEdges () const
	Get the number of edges in the mesh. More...

int	getNumFaces () const
	Get the number of faces in the mesh. More...

int	getNumVertices () const
	Get the number of vertices in the mesh. More...

const Vec3 &	getVertexPosition (int index) const
	Get the position of a vertex in the mesh. More...

int	getFaceEdge (int face, int edge) const
	Get the index of one of the edges of a face. More...

int	getFaceVertex (int face, int vertex) const
	Get the index of one of the vertices of a face. More...

int	getEdgeFace (int edge, int face) const
	Get the index of one of the faces shared by an edge. More...

int	getEdgeVertex (int edge, int vertex) const
	Get the index of one of the vertices shared by an edge. More...

void	findVertexEdges (int vertex, Array_< int > &edges) const
	Find all edges that intersect a vertex. More...

const UnitVec3 &	getFaceNormal (int face) const
	Get the normal vector for a face. More...

Real	getFaceArea (int face) const
	Get the area of a face. More...

Vec3	findPoint (int face, const Vec2 &uv) const
	Calculate the location of a point on the surface, in the local frame of the TriangleMesh. More...

Vec3	findCentroid (int face) const
	Calculate the location of a face's centroid, that is, the point uv=(1/3,1/3) which is the average of the three vertex locations. More...

UnitVec3	findNormalAtPoint (int face, const Vec2 &uv) const
	Calculate the normal vector at a point on the surface. More...

Vec3	findNearestPoint (const Vec3 &position, bool &inside, UnitVec3 &normal) const
	Given a point, find the nearest point on the surface of this object. More...

Vec3	findNearestPoint (const Vec3 &position, bool &inside, int &face, Vec2 &uv) const
	Given a point, find the nearest point on the surface of this object. More...

Vec3	findNearestPointToFace (const Vec3 &position, int face, Vec2 &uv) const
	Given a point and a face of this object, find the point of the face that is nearest the given point. More...

bool	intersectsRay (const Vec3 &origin, const UnitVec3 &direction, Real &distance, UnitVec3 &normal) const
	Determine whether this mesh intersects a ray, and if so, find the intersection point. More...

bool	intersectsRay (const Vec3 &origin, const UnitVec3 &direction, Real &distance, int &face, Vec2 &uv) const
	Determine whether this mesh intersects a ray, and if so, find what face it hit. More...

OBBTreeNode	getOBBTreeNode () const
	Get the OBBTreeNode which forms the root of this mesh's Oriented Bounding Box Tree. More...

PolygonalMesh	createPolygonalMesh () const
	Generate a PolygonalMesh from this TriangleMesh; useful mostly for debugging because you can create a DecorativeMesh from this and then look at it. More...

const Impl &	getImpl () const
	Internal use only. More...

Impl &	updImpl ()
	Internal use only. More...

Public Member Functions inherited from SimTK::ContactGeometry
	ContactGeometry ()
	Base class default constructor creates an empty handle. More...

	ContactGeometry (const ContactGeometry &src)
	Copy constructor makes a deep copy. More...

ContactGeometry &	operator= (const ContactGeometry &src)
	Copy assignment makes a deep copy. More...

	~ContactGeometry ()
	Base class destructor deletes the implementation object. Note that this is not virtual; handles should consist of just a pointer to the implementation. More...

DecorativeGeometry	createDecorativeGeometry () const
	Generate a DecorativeGeometry that matches the shape of this ContactGeometry. More...

Vec3	findNearestPoint (const Vec3 &position, bool &inside, UnitVec3 &normal) const
	Given a point, find the nearest point on the surface of this object. More...

Vec3	projectDownhillToNearestPoint (const Vec3 &pointQ) const
	Given a query point Q, find the nearest point P on the surface of this object, looking only down the local gradient. More...

bool	trackSeparationFromLine (const Vec3 &pointOnLine, const UnitVec3 &directionOfLine, const Vec3 &startingGuessForClosestPoint, Vec3 &newClosestPointOnSurface, Vec3 &closestPointOnLine, Real &height) const
	Track the closest point between this implicit surface and a given line, or the point of deepest penetration if the line intersects the surface. More...

bool	intersectsRay (const Vec3 &origin, const UnitVec3 &direction, Real &distance, UnitVec3 &normal) const
	Determine whether this object intersects a ray, and if so, find the intersection point. More...

void	getBoundingSphere (Vec3 &center, Real &radius) const
	Get a bounding sphere which completely encloses this object. More...

bool	isSmooth () const
	Returns `true` if this is a smooth surface, meaning that it can provide meaningful curvature information and continuous derivatives with respect to its parameterization. More...

void	calcCurvature (const Vec3 &point, Vec2 &curvature, Rotation &orientation) const
	Compute the principal curvatures and their directions, and the surface normal, at a given point on a smooth surface. More...

const Function &	getImplicitFunction () const
	Our smooth surfaces define a function f(P)=0 that provides an implicit representation of the surface. More...

Real	calcSurfaceValue (const Vec3 &point) const
	Calculate the value of the implicit surface function, at a given point. More...

UnitVec3	calcSurfaceUnitNormal (const Vec3 &point) const
	Calculate the implicit surface outward facing unit normal at the given point. More...

Vec3	calcSurfaceGradient (const Vec3 &point) const
	Calculate the gradient of the implicit surface function, at a given point. More...

Mat33	calcSurfaceHessian (const Vec3 &point) const
	Calculate the hessian of the implicit surface function, at a given point. More...

Real	calcGaussianCurvature (const Vec3 &gradient, const Mat33 &Hessian) const
	For an implicit surface, return the Gaussian curvature at the point p whose implicit surface function gradient g(p) and Hessian H(p) are supplied. More...

Real	calcGaussianCurvature (const Vec3 &point) const
	This signature is for convenience; use the other one to save time if you already have the gradient and Hessian available for this point. More...

Real	calcSurfaceCurvatureInDirection (const Vec3 &point, const UnitVec3 &direction) const
	For an implicit surface, return the curvature k of the surface at a given point p in a given direction tp. More...

void	calcSurfacePrincipalCurvatures (const Vec3 &point, Vec2 &curvature, Rotation &R_SP) const
	For an implicit surface at a given point p, return the principal curvatures and principal curvature directions, using only the implicit function and its derivatives. More...

bool	isConvex () const
	Returns `true` if this surface is known to be convex. More...

Vec3	calcSupportPoint (UnitVec3 direction) const
	Given a direction expressed in the surface's frame S, return the point P on the surface that is the furthest in that direction (or one of those points if there is more than one). More...

ContactGeometryTypeId	getTypeId () const
	ContactTrackerSubsystem uses this id for fast identification of specific surface shapes. More...

	ContactGeometry (ContactGeometryImpl *impl)
	Internal use only. More...

bool	isOwnerHandle () const
	Internal use only. More...

bool	isEmptyHandle () const
	Internal use only. More...

bool	hasImpl () const
	Internal use only. More...

const ContactGeometryImpl &	getImpl () const
	Internal use only. More...

ContactGeometryImpl &	updImpl ()
	Internal use only. More...

void	initGeodesic (const Vec3 &xP, const Vec3 &xQ, const Vec3 &xSP, const GeodesicOptions &options, Geodesic &geod) const
	Given two points, find a geodesic curve connecting them. More...

void	continueGeodesic (const Vec3 &xP, const Vec3 &xQ, const Geodesic &prevGeod, const GeodesicOptions &options, Geodesic &geod) const
	Given the current positions of two points P and Q moving on this surface, and the previous geodesic curve G' connecting prior locations P' and Q' of those same two points, return the geodesic G between P and Q that is closest in length to the previous one. More...

void	makeStraightLineGeodesic (const Vec3 &xP, const Vec3 &xQ, const UnitVec3 &defaultDirectionIfNeeded, const GeodesicOptions &options, Geodesic &geod) const
	Produce a straight-line approximation to the (presumably short) geodesic between two points on this implicit surface. More...

void	shootGeodesicInDirectionUntilLengthReached (const Vec3 &xP, const UnitVec3 &tP, const Real &terminatingLength, const GeodesicOptions &options, Geodesic &geod) const
	Compute a geodesic curve starting at the given point, starting in the given direction, and terminating at the given length. More...

void	calcGeodesicReverseSensitivity (Geodesic &geodesic, const Vec2 &initSensitivity=Vec2(0, 1)) const
	Given an already-calculated geodesic on this surface connecting points P and Q, fill in the sensitivity of point P with respect to a change of tangent direction at Q. More...

void	shootGeodesicInDirectionUntilPlaneHit (const Vec3 &xP, const UnitVec3 &tP, const Plane &terminatingPlane, const GeodesicOptions &options, Geodesic &geod) const
	Compute a geodesic curve starting at the given point, starting in the given direction, and terminating when it hits the given plane. More...

void	calcGeodesic (const Vec3 &xP, const Vec3 &xQ, const Vec3 &tPhint, const Vec3 &tQhint, Geodesic &geod) const
	Utility method to find geodesic between P and Q using split geodesic method with initial shooting directions tPhint and -tQhint. More...

void	calcGeodesicUsingOrthogonalMethod (const Vec3 &xP, const Vec3 &xQ, const Vec3 &tPhint, Real lengthHint, Geodesic &geod) const
	Utility method to find geodesic between P and Q using the orthogonal method, with initial direction tPhint and initial length lengthHint. More...

void	calcGeodesicUsingOrthogonalMethod (const Vec3 &xP, const Vec3 &xQ, Geodesic &geod) const
	This signature makes a guess at the initial direction and length and then calls the other signature. More...

Vec2	calcSplitGeodError (const Vec3 &P, const Vec3 &Q, const UnitVec3 &tP, const UnitVec3 &tQ, Geodesic *geod=0) const
	Utility method to calculate the "geodesic error" between one geodesic shot from P in the direction tP and another geodesic shot from Q in the direction tQ. More...

void	shootGeodesicInDirectionUntilLengthReachedAnalytical (const Vec3 &xP, const UnitVec3 &tP, const Real &terminatingLength, const GeodesicOptions &options, Geodesic &geod) const
	Analytically compute a geodesic curve starting at the given point, starting in the given direction, and terminating at the given length. More...

void	shootGeodesicInDirectionUntilPlaneHitAnalytical (const Vec3 &xP, const UnitVec3 &tP, const Plane &terminatingPlane, const GeodesicOptions &options, Geodesic &geod) const
	Analytically compute a geodesic curve starting at the given point, starting in the given direction, and terminating when it hits the given plane. More...

void	calcGeodesicAnalytical (const Vec3 &xP, const Vec3 &xQ, const Vec3 &tPhint, const Vec3 &tQhint, Geodesic &geod) const
	Utility method to analytically find geodesic between P and Q with initial shooting directions tPhint and tQhint. More...

Vec2	calcSplitGeodErrorAnalytical (const Vec3 &P, const Vec3 &Q, const UnitVec3 &tP, const UnitVec3 &tQ, Geodesic *geod=0) const
	Utility method to analytically calculate the "geodesic error" between one geodesic shot from P in the direction tP and another geodesic shot from Q in the direction tQ. More...

const Plane &	getPlane () const
	Get the plane associated with the geodesic hit plane event handler. More...

void	setPlane (const Plane &plane) const
	Set the plane associated with the geodesic hit plane event handler. More...

const Geodesic &	getGeodP () const
	Get the geodesic for access by visualizer. More...

const Geodesic &	getGeodQ () const
	Get the geodesic for access by visualizer. More...

const int	getNumGeodesicsShot () const
	Get the plane associated with the geodesic hit plane event handler. More...

void	addVizReporter (ScheduledEventReporter *reporter) const
	Get the plane associated with the geodesic hit plane event handler. More...

Static Public Member Functions
static bool	isInstance (const ContactGeometry &geo)
	Return true if the supplied ContactGeometry object is a triangle mesh. More...

static const TriangleMesh &	getAs (const ContactGeometry &geo)
	Cast the supplied ContactGeometry object to a const triangle mesh. More...

static TriangleMesh &	updAs (ContactGeometry &geo)
	Cast the supplied ContactGeometry object to a writable triangle mesh. More...

static ContactGeometryTypeId	classTypeId ()
	Obtain the unique id for TriangleMesh contact geometry. More...

Static Public Member Functions inherited from SimTK::ContactGeometry
static Vec2	evalParametricCurvature (const Vec3 &P, const UnitVec3 &nn, const Vec3 &dPdu, const Vec3 &dPdv, const Vec3 &d2Pdu2, const Vec3 &d2Pdv2, const Vec3 &d2Pdudv, Transform &X_EP)
	Calculate surface curvature at a point using differential geometry as suggested by Harris 2006, "Curvature of ellipsoids and other surfaces" Ophthal. More...

static void	combineParaboloids (const Rotation &R_SP1, const Vec2 &k1, const UnitVec3 &x2, const Vec2 &k2, Rotation &R_SP, Vec2 &k)
	This utility method is useful for characterizing the relative geometry of two locally-smooth surfaces in contact, in a way that is useful for later application of Hertz compliant contact theory for generating forces. More...

static void	combineParaboloids (const Rotation &R_SP1, const Vec2 &k1, const UnitVec3 &x2, const Vec2 &k2, Vec2 &k)
	This is a much faster version of combineParaboloids() for when you just need the curvatures of the difference paraboloid, but not the directions of those curvatures. More...

Additional Inherited Members
Protected Attributes inherited from SimTK::ContactGeometry
ContactGeometryImpl *	impl
	Internal use only. More...

Detailed Description

This ContactGeometry subclass represents an arbitrary shape described by a mesh of triangular faces.

The mesh surface must satisfy the following requirements:

It must be closed, so that any point can unambiguously be classified as either inside or outside.
It may not intersect itself anywhere, even at a single point.
It must be an oriented manifold.
The vertices for each face must be ordered counter-clockwise when viewed from the outside. That is, if v0, v1, and v2 are the locations of the three vertices for a face, the cross product (v1-v0)%(v2-v0) must point outward.
The length of every edge must be non-zero.

It is your responsibility to ensure that any mesh you create meets these requirements. The constructor will detect many incorrect meshes and signal them by throwing an exception, but it is not guaranteed to detect all possible problems. If a mesh fails to satisfy any of these requirements, the results of calculations performed with it are undefined. For example, collisions involving it might fail to be detected, or contact forces on it might be calculated incorrectly.

Constructor & Destructor Documentation

SimTK::ContactGeometry::TriangleMesh::TriangleMesh	(	const ArrayViewConst_< Vec3 > &	vertices,
		const ArrayViewConst_< int > &	faceIndices,
		bool	smooth = `false`
	)

Create a TriangleMesh.

Parameters

vertices	The positions of all vertices in the mesh.
faceIndices	The indices of the vertices that make up each face. The first three elements are the vertices in the first face, the next three elements are the vertices in the second face, etc.
smooth	If true, the mesh will be treated as a smooth surface, and normal vectors will be smoothly interpolated between vertices. If false, it will be treated as a faceted mesh with a constant normal vector over each face.

SimTK::ContactGeometry::TriangleMesh::TriangleMesh	(	const PolygonalMesh &	mesh,
		bool	smooth = `false`
	)

explicit

Create a TriangleMesh based on a PolygonalMesh object.

If any faces of the PolygonalMesh have more than three vertices, they are automatically triangulated.

Parameters

mesh	The PolygonalMesh from which to construct a triangle mesh.
smooth	If true, the mesh will be treated as a smooth surface, and normal vectors will be smoothly interpolated between vertices. If false, it will be treated as a faceted mesh with a constant normal vector over each face.

Member Function Documentation

int SimTK::ContactGeometry::TriangleMesh::getNumEdges ( ) const

Get the number of edges in the mesh.

int SimTK::ContactGeometry::TriangleMesh::getNumFaces ( ) const

Get the number of faces in the mesh.

int SimTK::ContactGeometry::TriangleMesh::getNumVertices ( ) const

Get the number of vertices in the mesh.

const Vec3& SimTK::ContactGeometry::TriangleMesh::getVertexPosition ( int index ) const

Get the position of a vertex in the mesh.

Parameters

index The index of the vertex to get.

Returns: The position of the specified vertex.

int SimTK::ContactGeometry::TriangleMesh::getFaceEdge	(	int	face,
		int	edge
	)		const

Get the index of one of the edges of a face.

Edge 0 connects vertices 0 and 1. Edge 1 connects vertices 1 and 2. Edge 2 connects vertices 0 and 2.

Parameters

face	The index of the face.
edge	The index of the edge within the face (0, 1, or 2).

Returns: The index of the specified edge.

int SimTK::ContactGeometry::TriangleMesh::getFaceVertex	(	int	face,
		int	vertex
	)		const

Get the index of one of the vertices of a face.

Parameters

face	The index of the face.
vertex	The index of the vertex within the face (0, 1, or 2).

Returns: The index of the specified vertex.

int SimTK::ContactGeometry::TriangleMesh::getEdgeFace	(	int	edge,
		int	face
	)		const

Get the index of one of the faces shared by an edge.

Parameters

edge	The index of the edge.
face	The index of the face within the edge (0 or 1).

Returns: The index of the specified face.

int SimTK::ContactGeometry::TriangleMesh::getEdgeVertex	(	int	edge,
		int	vertex
	)		const

Get the index of one of the vertices shared by an edge.

Parameters

edge	The index of the edge.
vertex	The index of the vertex within the edge (0 or 1).

Returns: The index of the specified vertex.

void SimTK::ContactGeometry::TriangleMesh::findVertexEdges	(	int	vertex,
		Array_< int > &	edges
	)		const

Find all edges that intersect a vertex.

Parameters

vertex	The index of the vertex.
edges	The indices of all edges intersecting the vertex will be added to this.

const UnitVec3& SimTK::ContactGeometry::TriangleMesh::getFaceNormal ( int face ) const

Get the normal vector for a face.

This points outward from the mesh.

Parameters

face	The index of the face.

Real SimTK::ContactGeometry::TriangleMesh::getFaceArea ( int face ) const

Get the area of a face.

Parameters

face	The index of the face.

Vec3 SimTK::ContactGeometry::TriangleMesh::findPoint	(	int	face,
		const Vec2 &	uv
	)		const

Calculate the location of a point on the surface, in the local frame of the TriangleMesh.

Cost is 11 flops.

Parameters

face	The index of the face containing the point.
uv	The point within the face, specified by its barycentric uv coordinates.

Vec3 SimTK::ContactGeometry::TriangleMesh::findCentroid ( int face ) const

Calculate the location of a face's centroid, that is, the point uv=(1/3,1/3) which is the average of the three vertex locations.

This is a common special case of findPoint() that can be calculated more quickly (7 flops).

Parameters

face	The index of the face whose centroid is of interest.

UnitVec3 SimTK::ContactGeometry::TriangleMesh::findNormalAtPoint	(	int	face,
		const Vec2 &	uv
	)		const

Calculate the normal vector at a point on the surface.

Parameters

face	The index of the face containing the point.
uv	The point within the face, specified by its barycentric uv coordinates.

Vec3 SimTK::ContactGeometry::TriangleMesh::findNearestPoint	(	const Vec3 &	position,
		bool &	inside,
		UnitVec3 &	normal
	)		const

Given a point, find the nearest point on the surface of this object.

If multiple points on the surface are equally close to the specified point, this may return any of them.

Parameters

position	The point in question.
inside	On exit, this is set to true if the specified point is inside this object, false otherwise.
normal	On exit, this contains the surface normal at the returned point.

Returns: The point on the surface of the object which is closest to the specified point.

Vec3 SimTK::ContactGeometry::TriangleMesh::findNearestPoint	(	const Vec3 &	position,
		bool &	inside,
		int &	face,
		Vec2 &	uv
	)		const

Given a point, find the nearest point on the surface of this object.

If multiple points on the surface are equally close to the specified point, this may return any of them.

Parameters

position	The point in question.
inside	On exit, this is set to true if the specified point is inside this object, false otherwise.
face	On exit, this contains the index of the face containing the returned point.
uv	On exit, this contains the barycentric coordinates (u and v) of the returned point within its face.

Returns: The point on the surface of the object which is closest to the specified point.

Vec3 SimTK::ContactGeometry::TriangleMesh::findNearestPointToFace	(	const Vec3 &	position,
		int	face,
		Vec2 &	uv
	)		const

Given a point and a face of this object, find the point of the face that is nearest the given point.

If multiple points on the face are equally close to the specified point, this may return any of them.

Parameters

position	The point in question.
face	The face to be examined.
uv	On exit, this contains the barycentric coordinates (u and v) of the returned point within the face.

Returns: The face point, in the surface's frame, that is closest to the specified point.

bool SimTK::ContactGeometry::TriangleMesh::intersectsRay	(	const Vec3 &	origin,
		const UnitVec3 &	direction,
		Real &	distance,
		UnitVec3 &	normal
	)		const

Determine whether this mesh intersects a ray, and if so, find the intersection point.

Parameters

origin	The position at which the ray begins.
direction	The ray direction.
distance	If an intersection is found, the distance from the ray origin to the intersection point is stored in this. Otherwise, it is left unchanged.
normal	If an intersection is found, the surface normal of the intersection point is stored in this. Otherwise, it is left unchanged.

Returns: true if an intersection is found, false otherwise.

bool SimTK::ContactGeometry::TriangleMesh::intersectsRay	(	const Vec3 &	origin,
		const UnitVec3 &	direction,
		Real &	distance,
		int &	face,
		Vec2 &	uv
	)		const

Determine whether this mesh intersects a ray, and if so, find what face it hit.

Parameters

origin	The position at which the ray begins.
direction	The ray direction.
distance	If an intersection is found, the distance from the ray origin to the intersection point is stored in this. Otherwise, it is left unchanged.
face	If an intersection is found, the index of the face hit by the ray is stored in this. Otherwise, it is left unchanged.
uv	If an intersection is found, the barycentric coordinates (u and v) of the intersection point within the hit face are stored in this. Otherwise, it is left unchanged.

Returns: true if an intersection is found, false otherwise.

OBBTreeNode SimTK::ContactGeometry::TriangleMesh::getOBBTreeNode ( ) const

Get the OBBTreeNode which forms the root of this mesh's Oriented Bounding Box Tree.

PolygonalMesh SimTK::ContactGeometry::TriangleMesh::createPolygonalMesh ( ) const

Generate a PolygonalMesh from this TriangleMesh; useful mostly for debugging because you can create a DecorativeMesh from this and then look at it.

static bool SimTK::ContactGeometry::TriangleMesh::isInstance ( const ContactGeometry & geo )

inlinestatic

Return true if the supplied ContactGeometry object is a triangle mesh.

static const TriangleMesh& SimTK::ContactGeometry::TriangleMesh::getAs ( const ContactGeometry & geo )

inlinestatic

Cast the supplied ContactGeometry object to a const triangle mesh.

static TriangleMesh& SimTK::ContactGeometry::TriangleMesh::updAs ( ContactGeometry & geo )

inlinestatic

Cast the supplied ContactGeometry object to a writable triangle mesh.

static ContactGeometryTypeId SimTK::ContactGeometry::TriangleMesh::classTypeId ( )

static

Obtain the unique id for TriangleMesh contact geometry.

const Impl& SimTK::ContactGeometry::TriangleMesh::getImpl ( ) const

Internal use only.

Impl& SimTK::ContactGeometry::TriangleMesh::updImpl ( )

Internal use only.

The documentation for this class was generated from the following file:

ContactGeometry.h

Classes

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation