Drake
Drake C++ Documentation
Parser Class Referencefinal

Detailed Description

Parses model description input into a MultibodyPlant and (optionally) a SceneGraph.

A variety of input formats are supported, and are recognized by filename suffixes:

File format Filename suffix
URDF ".urdf"
SDFormat ".sdf"
MJCF (Mujoco XML) ".xml"
Drake Model Directives ".dmd.yaml"
Wavefront OBJ ".obj"

The output of parsing is one or more model instances added to the MultibodyPlant provided to the parser at construction.

For an introductory tutorial about parsing, see the Authoring a Multibody Simulation page.

SDFormat files may contain multiple <model> elements. New model instances will be added to plant for each <model> tag in the file.

Note
Adding multiple root-level models, i.e, <model>s directly under <sdf>, is deprecated. If you need multiple models in a single file, please use an SDFormat world tag.

URDF files contain a single <robot> element. Only a single model instance will be added to plant.

MJCF (MuJoCo XML) files typically contain many bodies, they will all be added as a single model instance in the plant.

Drake Model Directives are only available via AddModels or AddModelsFromString. The single-model methods (AddModelFromFile, AddModelFromString) cannot load model directives.

OBJ files will infer a model with a single body from the geometry. The OBJ file must contain a single object (in the OBJ-file sense). The body's mass properties are computed based on uniform distribution of material in the enclosed volume of the mesh (with the approximate density of water: 1000 kg/m³). If the mesh is not a closed manifold, this can produce unexpected results. The spatial inertia of the body is measured at the body frame's origin. The body's frame is coincident and fixed with the frame the mesh's vertices are measured and expressed in. The mesh's vertices are assumed to be measured in units of meters.

The name of the model and body are determined according to the following prioritized protocol:

  • The non-empty model_name, if given (e.g., in AddModelFromFile()).
  • If the object is named in the obj file, that object name is used.
  • Otherwise, the base name of the file name is used (i.e., the file name with the prefixed directory and extension removed).

If the underlying plant is registered with a SceneGraph instance, the mesh will also be used for all three roles: illustration, perception, and proximity.

Warning
AddModelsFromString() cannot be passed OBJ file contents yet.

For more documentation of Drake-specific treatment of these input formats, see Parsing Models for Multibody Dynamics.

When parsing literal quantities, Parser assumes SI units and radians in the absence of units specified by the format itself. This includes the literals in the explicitly specified files as well as referenced files such as OBJ or other data file formats.

MultibodyPlant requires that model instances have unique names. To support loading multiple instances of the same model file(s) into a plant, Parser offers a few different strategies.

Parser has constructors that take a model name prefix, which gets applied to all models loaded with that Parser instance. The resulting workflow makes multiple parsers to build models for a single plant:

Parser left_parser(plant, "left");
Parser right_parser(plant, "right");
left_parser.AddModels(arm_model); // "left::arm"
right_parser.AddModels(arm_model); // "right::arm"
left_parser.AddModels(gripper_model); // "left::gripper"
right_parser.AddModels(gripper_model); // "right::gripper"

For situations where it is convenient to load a model many times, Parser offers optional auto-renaming. When auto-renaming is enabled, name collisions will be resolved by adding a subscript to the name.

Parser parser(plant);
parser.SetAutoRenaming(true);
// Subscripts are compact, and start at 1.
parser.AddModels(rock); // "rock"
parser.AddModels(rock); // "rock_1"
parser.AddModels(rock); // "rock_2"
// Subscripts of different base names are independent.
parser.AddModels(stone); // "stone"
parser.AddModels(stone); // "stone_1"
parser.AddModels(stone); // "stone_2"

(Advanced) In the rare case where the user is parsing into a MultibodyPlant and SceneGraph but has created them one at a time instead of using the more convenient AddMultibodyPlant() or AddMultibodyPlantSceneGraph() functions, the Parser constructors accept an optional SceneGraph pointer to specify which SceneGraph to parse into. If it is provided and non-null and the MultibodyPlant is not registered as a source, the Parser will perform the SceneGraph registration into the given plant. We describe this option only for completeness; we strongly discourage anyone from taking advantage of this feature.

#include <drake/multibody/parsing/parser.h>

Public Member Functions

 Parser (MultibodyPlant< double > *plant, geometry::SceneGraph< double > *scene_graph=nullptr)
 Creates a Parser that adds models to the given plant and (optionally) scene_graph. More...
 
 Parser (MultibodyPlant< double > *plant, geometry::SceneGraph< double > *scene_graph, std::string_view model_name_prefix)
 Creates a Parser that adds models to the given plant and scene_graph. More...
 
 Parser (MultibodyPlant< double > *plant, std::string_view model_name_prefix)
 Creates a Parser that adds models to the given plant and scene_graph. More...
 
MultibodyPlant< double > & plant ()
 Gets a mutable reference to the plant that will be modified by this parser. More...
 
PackageMappackage_map ()
 Gets a mutable reference to the PackageMap used by this parser. More...
 
void SetStrictParsing ()
 Cause all subsequent Add*Model*() operations to use strict parsing; warnings will be treated as errors. More...
 
void SetAutoRenaming (bool value)
 Enable or disable auto-renaming. More...
 
bool GetAutoRenaming () const
 Get the current state of auto-renaming. More...
 
std::vector< ModelInstanceIndexAddModels (const std::filesystem::path &file_name)
 Parses the input file named in file_name and adds all of its model(s) to plant. More...
 
std::vector< ModelInstanceIndexAddModelsFromUrl (const std::string &url)
 Parses the input file named in url and adds all of its model(s) to plant. More...
 
std::vector< ModelInstanceIndexAddModelsFromString (const std::string &file_contents, const std::string &file_type)
 Provides same functionality as AddModels, but instead parses the model description text data via file_contents with format dictated by file_type. More...
 
Does not allow copy, move, or assignment
 Parser (const Parser &)=delete
 
Parseroperator= (const Parser &)=delete
 
 Parser (Parser &&)=delete
 
Parseroperator= (Parser &&)=delete
 

Friends

class internal::CompositeParse
 

Constructor & Destructor Documentation

◆ Parser() [1/5]

Parser ( const Parser )
delete

◆ Parser() [2/5]

Parser ( Parser &&  )
delete

◆ Parser() [3/5]

Parser ( MultibodyPlant< double > *  plant,
geometry::SceneGraph< double > *  scene_graph = nullptr 
)
explicit

Creates a Parser that adds models to the given plant and (optionally) scene_graph.

Parameters
plantA pointer to a mutable MultibodyPlant object to which parsed model(s) will be added; plant->is_finalized() must remain false for as long as the plant is in use by this.
scene_graphA pointer to a mutable SceneGraph object used for geometry registration (either to model visual or contact geometry). May be nullptr.

◆ Parser() [4/5]

Parser ( MultibodyPlant< double > *  plant,
geometry::SceneGraph< double > *  scene_graph,
std::string_view  model_name_prefix 
)

Creates a Parser that adds models to the given plant and scene_graph.

The resulting parser will apply model_name_prefix to the names of any models parsed.

Parameters
plantA pointer to a mutable MultibodyPlant object to which parsed model(s) will be added; plant->is_finalized() must remain false for as long as the plant is in use by this.
scene_graphA pointer to a mutable SceneGraph object used for geometry registration (either to model visual or contact geometry). May be nullptr.
model_name_prefixA string that will be added as a scoped name prefix to the names of any models loaded by this parser; when empty, no scoping will be added.

◆ Parser() [5/5]

Parser ( MultibodyPlant< double > *  plant,
std::string_view  model_name_prefix 
)

Creates a Parser that adds models to the given plant and scene_graph.

The resulting parser will apply model_name_prefix to the names of any models parsed.

Parameters
plantA pointer to a mutable MultibodyPlant object to which parsed model(s) will be added; plant->is_finalized() must remain false for as long as the plant is in use by this.
model_name_prefixA string that will be added as a scoped name prefix to the names of any models loaded by this parser; when empty, no scoping will be added.

Member Function Documentation

◆ AddModels()

std::vector<ModelInstanceIndex> AddModels ( const std::filesystem::path &  file_name)

Parses the input file named in file_name and adds all of its model(s) to plant.

Parameters
file_nameThe name of the file to be parsed. The file type will be inferred from the extension.
Returns
The set of model instance indices for the newly added models, including nested models.
Exceptions
std::exceptionin case of errors.

◆ AddModelsFromString()

std::vector<ModelInstanceIndex> AddModelsFromString ( const std::string &  file_contents,
const std::string &  file_type 
)

Provides same functionality as AddModels, but instead parses the model description text data via file_contents with format dictated by file_type.

Parameters
file_contentsThe model data to be parsed.
file_typeThe data format; must be one of the filename suffixes listed above, without the leading dot (.).
Returns
The set of model instance indices for the newly added models, including nested models.
Exceptions
std::exceptionin case of errors.

◆ AddModelsFromUrl()

std::vector<ModelInstanceIndex> AddModelsFromUrl ( const std::string &  url)

Parses the input file named in url and adds all of its model(s) to plant.

The allowed URL schemes are either file:// for local files or package:// (or model://) to use this Parser's package_map().

Parameters
urlThe file to be parsed. The file type will be inferred from the extension.
Returns
The set of model instance indices for the newly added models, including nested models.
Exceptions
std::exceptionin case of errors.

◆ GetAutoRenaming()

bool GetAutoRenaming ( ) const

Get the current state of auto-renaming.

See also
the Parser class documentation for more detail.

◆ operator=() [1/2]

Parser& operator= ( Parser &&  )
delete

◆ operator=() [2/2]

Parser& operator= ( const Parser )
delete

◆ package_map()

PackageMap& package_map ( )

Gets a mutable reference to the PackageMap used by this parser.

◆ plant()

MultibodyPlant<double>& plant ( )

Gets a mutable reference to the plant that will be modified by this parser.

◆ SetAutoRenaming()

void SetAutoRenaming ( bool  value)

Enable or disable auto-renaming.

It is disabled by default.

See also
the Parser class documentation for more detail.

◆ SetStrictParsing()

void SetStrictParsing ( )

Cause all subsequent Add*Model*() operations to use strict parsing; warnings will be treated as errors.

Friends And Related Function Documentation

◆ internal::CompositeParse

friend class internal::CompositeParse
friend

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