Mesh Class Reference

Detailed Description

Definition of a general (possibly non-convex) mesh.

The mesh may be a triangular surface mesh or a tetrahedral volume mesh, depending on how it used.

Meshes can be used with all three roles but, currently, the support for the proximity role is limited. Where a general mesh is not supported, the mesh is replaced by its convex hull. See the documentation of QueryObject's proximity queries for more details. The notable cases where the actual mesh topology is used includes:

• Computing signed distances from the Mesh to query points (when it references a .obj file or a tetrahedral .vtk file).
• Specifying the Mesh as rigid hydroelastic (when it references a triangle .obj file or a tetrahedral .vtk file).
• Specifying the Mesh as compliant hydroelastic (when it references a tetrahedral .vtk file).
• Specifying the Mesh as deformable (when it references a tetrahedral .vtk file).

This convex-hull substitution is a regrettable stop-gap solution until we fully support general, non-convex meshes throughout proximity queries.

For visual roles (illustration and perception), the specified mesh file is used as directly as possible.

The mesh is defined in a canonical frame C, implicit in the file parsed. Upon loading it in SceneGraph it can be scaled around the origin of C by a given scale amount.

Note: a negative scale can be applied. This can be useful in mirroring the geometry (e.g., using a right hand mesh for a left hand). Mirroring the geometry will typically change the "winding" of the mesh elements. By convention, Drake looks at the ordering of the vertices that form mesh elements (triangles and tetrahedra) and derives the notion of "inside" and "outside" relative to that element. In order to preserve the input mesh's definition of "inside" and "outside", when the mesh gets mirrored Drake may perturb the ordering of the vertex indices. For example, a triangle originally referencing vertices [0 1 2], when mirrored may change to [2 1 0], so don't be surprised if you introspect the details of the loaded mesh and you see such a change. An analogous change can affect the vertex ordering of tetrahedra in a volume mesh (i.e., a perturbation of the original vertex index list [0 1 2 3] to [2 1 0 3]).

#include <drake/geometry/shape_specification.h>

Public Member Functions
	Mesh (const std::filesystem::path &filename, double scale=1.0)
	Constructs a mesh shape specification from the mesh file located at the given file path.
	Mesh (const std::filesystem::path &filename, const Vector3< double > &scale3)
	Mesh-file variant that allows for specification of non-uniform scale.
	Mesh (InMemoryMesh mesh_data, double scale=1.0)
	Constructs a mesh shape specification from the contents of a Drake-supported mesh file type.
	Mesh (InMemoryMesh mesh_data, const Vector3< double > &scale3)
	Mesh-contents variant that allows for specification of non-uniform scale.
	Mesh (MeshSource source, double scale=1.0)
	Constructs a mesh shape specification from the given source.
	Mesh (MeshSource source, const Vector3< double > &scale3)
	Mesh-source variant that allows for specification of non-uniform scale.
	~Mesh () final
const MeshSource &	source () const
	Returns the source for this specification's mesh data.
const std::string &	extension () const
	Returns the extension of the mesh type – all lower case and including the dot.
double	scale () const
	Returns a single scale representing the uniform scale factor.
const Vector3< double > &	scale3 () const
	Returns general scale factors for this mesh.
const PolygonSurfaceMesh< double > &	GetConvexHull () const
	Reports the convex hull of the named mesh.
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
	Mesh (const Mesh &)=default
Mesh &	operator= (const Mesh &)=default
	Mesh (Mesh &&)=default
Mesh &	operator= (Mesh &&)=default
Public Member Functions inherited from Shape
virtual	~Shape ()
void	Reify (ShapeReifier *reifier, void *user_data=nullptr) const
	Causes this description to be reified in the given reifier.
std::unique_ptr< Shape >	Clone () const
	Creates a unique copy of this shape.
std::string_view	type_name () const
	Returns the (unqualified) type name of this Shape, e.g., "Box".
std::string	to_string () const
	Returns a string representation of this shape.
template<typename ReturnType = void, typename Visitor>
decltype(auto)	Visit (Visitor &&visitor) const
	Calls the given visitor function with *this as the sole argument, but with *this downcast to be the shape's concrete subclass.

Additional Inherited Members
Protected Types inherited from Shape
using	VariantShapeConstPtr
	(Internal use only) All concrete subclasses, as const pointers.
Protected Member Functions inherited from Shape
	Shape ()
	(Internal use only) Constructor for use by derived classes.
	Shape (const Shape &)=default
	(Internal use only) For derived classes.
Shape &	operator= (const Shape &)=default
	(Internal use only) For derived classes.
	Shape (Shape &&)=default
	(Internal use only) For derived classes.
Shape &	operator= (Shape &&)=default
	(Internal use only) For derived classes.

Constructor & Destructor Documentation

Mesh() [1/8]

Mesh ( const Mesh & )

default

Mesh() [2/8]

Mesh ( Mesh && )

default

Mesh() [3/8]

Mesh ( const std::filesystem::path & filename, double scale = 1.0 )

explicit

Constructs a mesh shape specification from the mesh file located at the given file path.

Optionally uniformly scaled by the given scale factor.

The mesh file referenced can be an .obj, a volume mesh in a .vtk, or a .gltf file. However, not all file formats are appropriate for all roles. (E.g., a tetrahedral .vtk file should not be assigned a perception role.)

Parameters

filename	The file name; if it is not absolute, it will be interpreted relative to the current working directory.
scale	An optional scale to coordinates.

Exceptions

std::exception

if |scale| < 1e-8. Note that a negative scale is considered valid. We want to preclude scales near zero but recognise that scale is a convenience tool for "tweaking" models. 8 orders of magnitude should be plenty without considering revisiting the model itself.

Mesh() [4/8]

Mesh	(	const std::filesystem::path &	filename,
		const Vector3< double > &	scale3 )

Mesh-file variant that allows for specification of non-uniform scale.

Mesh() [5/8]

Mesh ( InMemoryMesh mesh_data, double scale = 1.0 )

explicit

Constructs a mesh shape specification from the contents of a Drake-supported mesh file type.

The mesh is defined by the contents of a mesh file format supported by Drake. Those contents are passed in as mesh_data. The mesh data should include the main mesh file's contents as well as any supporting file contents as needed. See InMemoryMesh.

Parameters

mesh_data	The in-memory file contents that define the mesh data for this shape.
scale	An optional scale to coordinates.

Mesh() [6/8]

Mesh	(	InMemoryMesh	mesh_data,
		const Vector3< double > &	scale3 )

Mesh-contents variant that allows for specification of non-uniform scale.

Mesh() [7/8]

Mesh ( MeshSource source, double scale = 1.0 )

explicit

Constructs a mesh shape specification from the given source.

Parameters

source	The source for the mesh data.
scale	An optional scale to coordinates.

Mesh() [8/8]

Mesh	(	MeshSource	source,
		const Vector3< double > &	scale3 )

Mesh-source variant that allows for specification of non-uniform scale.

~Mesh()

~Mesh ( )

final

Member Function Documentation

extension()

const std::string & extension

(

)

const

Returns the extension of the mesh type – all lower case and including the dot.

If this is constructed from a file path, the extension is extracted from the path. I.e., /foo/bar/mesh.obj and /foo/bar/mesh.OBJ would both report the ".obj" extension. The "extension" portion of the filename is defined as in std::filesystem::path::extension().

If this is constructed using in-memory file contents, it is the extension of the MemoryFile passed to the constructor.

GetConvexHull()

const PolygonSurfaceMesh< double > & GetConvexHull

(

)

const

Reports the convex hull of the named mesh.

Note: the convex hull is computed on demand on the first invocation. All subsequent invocations should have an O(1) cost.

Exceptions

if	the referenced mesh data cannot be read or is degenerate (insufficient number of vertices, co-linear or coincident vertices, etc.) All of the vertices lying on a plane is not considered degenerate.

operator=() [1/2]

Mesh & operator= ( const Mesh & )

default

operator=() [2/2]

Mesh & operator= ( Mesh && )

default

scale()

double scale

(

)

const

Returns a single scale representing the uniform scale factor.

Exceptions

if	the scale is not uniform in all directions.

scale3()

const Vector3< double > & scale3

(

)

const

Returns general scale factors for this mesh.

source()

const MeshSource & source

(

)

const

Returns the source for this specification's mesh data.

---

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

• drake/geometry/shape_specification.h