Definition of a convex surface mesh.
This shape is not the mesh contained in the file named by filename
. It is the convex hull of that mesh. As such, the only contents of the mesh file that matter are the vertex positions. All other data is ignored. This includes materials, textures, normals etc. This is true for all roles. Its appearance in an illustration or perception role, will be a faceted polytope whose color is defined by its assigned properties (or by the geometry consumer's defaults).
Because Drake computes the convex hull, the named mesh file need not be convex.
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.
#include <drake/geometry/shape_specification.h>
Public Member Functions | |
Convex (const std::filesystem::path &filename, double scale=1.0) | |
Constructs a convex shape specification from the file located at the given file path. More... | |
Convex (InMemoryMesh mesh_data, double scale=1.0) | |
Constructs a convex shape specification from the contents of a Drake-supported mesh file type. More... | |
Convex (MeshSource source, double scale=1.0) | |
Constructs a convex shape specification from the given source . More... | |
~Convex () final | |
const MeshSource & | source () const |
Returns the source for this specification's mesh data. More... | |
std::string | filename () const |
Returns the filename passed to the constructor. More... | |
const std::string & | extension () const |
Returns the extension of the underlying input mesh – all lower case and including the dot. More... | |
double | scale () const |
const PolygonSurfaceMesh< double > & | GetConvexHull () const |
Reports the convex hull of the named mesh. More... | |
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable | |
Convex (const Convex &)=default | |
Convex & | operator= (const Convex &)=default |
Convex (Convex &&)=default | |
Convex & | operator= (Convex &&)=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 . More... | |
std::unique_ptr< Shape > | Clone () const |
Creates a unique copy of this shape. More... | |
std::string_view | type_name () const |
Returns the (unqualified) type name of this Shape, e.g., "Box". More... | |
std::string | to_string () const |
Returns a string representation of this shape. More... | |
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. More... | |
Additional Inherited Members | |
Protected Types inherited from Shape | |
using | VariantShapeConstPtr = std::variant< const Box *, const Capsule *, const Convex *, const Cylinder *, const Ellipsoid *, const HalfSpace *, const Mesh *, const MeshcatCone *, const Sphere * > |
(Internal use only) All concrete subclasses, as const pointers. More... | |
Protected Member Functions inherited from Shape | |
Shape () | |
(Internal use only) Constructor for use by derived classes. More... | |
Shape (const Shape &)=default | |
(Internal use only) For derived classes. More... | |
Shape & | operator= (const Shape &)=default |
(Internal use only) For derived classes. More... | |
Shape (Shape &&)=default | |
(Internal use only) For derived classes. More... | |
Shape & | operator= (Shape &&)=default |
(Internal use only) For derived classes. More... | |
Constructs a convex shape specification from the file located at the given file path.
Optionally uniformly scaled by the given scale factor.
The mesh file referenced can be an .obj, .gltf, or a tetrahedral .vtk.
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. |
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. |
|
explicit |
Constructs a convex 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
. For Convex, the only supporting files required are those necessary to define vertex positions (e.g., a glTF's .bin file); material and texture files, if provided, are ignored and are therefore unnecessary.
mesh_data | The in-memory file contents that define the vertex data for this shape. |
scale | An optional scale to coordinates. |
|
explicit |
Constructs a convex shape specification from the given source
.
source | The source for the mesh data. |
scale | An optional scale to coordinates. |
|
final |
const std::string& extension | ( | ) | const |
Returns the extension of the underlying input mesh – 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.
std::string filename | ( | ) | const |
Returns the filename passed to the constructor.
std::exception | if this Convex was constructed using in-memory file contents. |
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.
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. |
double scale | ( | ) | const |
const MeshSource& source | ( | ) | const |
Returns the source for this specification's mesh data.
When working with Convex, this API should only be used for introspection. The contract for Convex is that the convex hull is always used in place of whatever underlying mesh declaration is provided. For all functional geometric usage, exclusively use the convex hull returned by GetConvexHull().