Simbody  3.5
SimTK::ContactGeometry::TriangleMesh Class Reference

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 Vec3getVertexPosition (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 UnitVec3getFaceNormal (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...
 
ContactGeometryoperator= (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 FunctiongetImplicitFunction () 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 PlanegetPlane () 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 GeodesicgetGeodP () const
 Get the geodesic for access by visualizer. More...
 
const GeodesicgetGeodQ () 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 TriangleMeshgetAs (const ContactGeometry &geo)
 Cast the supplied ContactGeometry object to a const triangle mesh. More...
 
static TriangleMeshupdAs (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
verticesThe positions of all vertices in the mesh.
faceIndicesThe 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.
smoothIf 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
meshThe PolygonalMesh from which to construct a triangle mesh.
smoothIf 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
indexThe 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
faceThe index of the face.
edgeThe 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
faceThe index of the face.
vertexThe 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
edgeThe index of the edge.
faceThe 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
edgeThe index of the edge.
vertexThe 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
vertexThe index of the vertex.
edgesThe 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
faceThe index of the face.
Real SimTK::ContactGeometry::TriangleMesh::getFaceArea ( int  face) const

Get the area of a face.

Parameters
faceThe 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
faceThe index of the face containing the point.
uvThe 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
faceThe 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
faceThe index of the face containing the point.
uvThe 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
positionThe point in question.
insideOn exit, this is set to true if the specified point is inside this object, false otherwise.
normalOn 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
positionThe point in question.
insideOn exit, this is set to true if the specified point is inside this object, false otherwise.
faceOn exit, this contains the index of the face containing the returned point.
uvOn 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
positionThe point in question.
faceThe face to be examined.
uvOn 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
originThe position at which the ray begins.
directionThe ray direction.
distanceIf an intersection is found, the distance from the ray origin to the intersection point is stored in this. Otherwise, it is left unchanged.
normalIf 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
originThe position at which the ray begins.
directionThe ray direction.
distanceIf an intersection is found, the distance from the ray origin to the intersection point is stored in this. Otherwise, it is left unchanged.
faceIf an intersection is found, the index of the face hit by the ray is stored in this. Otherwise, it is left unchanged.
uvIf 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.

Internal use only.

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

Internal use only.


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