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 (systems::DiagramBuilder< double > builder, MultibodyPlant< double > plant=nullptr, geometry::SceneGraph< double > *scene_graph=nullptr, std::string_view model_name_prefix={})
	Create a Parser given a DiagramBuilder (and optionally plant and scene_graph). More...

	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...

	~Parser ()

systems::DiagramBuilder< double > *	builder ()
	Gets a mutable pointer to the DiagramBuilder that will be modified by this parser, or nullptr if this parser does not have a DiagramBuilder. More...

MultibodyPlant< double > &	plant ()
	Gets a mutable reference to the plant that will be modified by this parser. More...

geometry::SceneGraph< double > *	scene_graph ()
	Gets a mutable pointer to the SceneGraph that will be modified by this parser, or nullptr if this parser does not have a SceneGraph. More...

PackageMap &	package_map ()
	Gets a mutable reference to the PackageMap used by this parser. More...

void	SetStrictParsing ()
	Cause all subsequent AddModel() 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...

CollisionFilterGroups	GetCollisionFilterGroups () const
	Gets the accumulated set of collision filter definitions seen by this parser. More...

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`. More...

std::vector< ModelInstanceIndex >	AddModelsFromUrl (const std::string &url)
	Parses the input file named in `url` and adds all of its model(s) to `plant`. More...

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`. More...

Does not allow copy, move, or assignment
	Parser (const Parser &)=delete

Parser &	operator= (const Parser &)=delete

	Parser (Parser &&)=delete

Parser &	operator= (Parser &&)=delete

Friends
class	internal::CompositeParse

Constructor & Destructor Documentation

◆ Parser() [1/6]

Parser ( const Parser & )

delete

◆ Parser() [2/6]

Parser ( Parser && )

delete

◆ Parser() [3/6]

Parser	(	systems::DiagramBuilder< double > *	builder,
		MultibodyPlant< double > *	plant = `nullptr`,
		geometry::SceneGraph< double > *	scene_graph = `nullptr`,
		std::string_view	model_name_prefix = `{}`
	)

explicit

Create a Parser given a DiagramBuilder (and optionally plant and scene_graph).

If specified, the resulting parser will apply model_name_prefix to the names of any models parsed. builder may be nullptr, but then you must specify a plant.

Precondition: Either the given builder contains a MultibodyPlant system named "plant" or else the provided plant is non-null.; If both builder and plant are specified, then plant ∈ builder.GetSystems()

Parameters

scene_graph A pointer to a mutable SceneGraph object used for geometry registration (either to model visual or contact geometry). May be nullptr.

Precondition: If both builder and scene_graph are specified, then scene_graph ∈ builder.GetSystems().

◆ Parser() [4/6]

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

plant	A 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_graph	A pointer to a mutable SceneGraph object used for geometry registration (either to model visual or contact geometry). May be nullptr.

◆ Parser() [5/6]

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

plant	A 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_graph	A pointer to a mutable SceneGraph object used for geometry registration (either to model visual or contact geometry). May be nullptr.
model_name_prefix	A 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() [6/6]

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

plant	A 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_prefix	A 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()

~Parser ( )

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_name The 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::exception in 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_contents	The model data to be parsed.
file_type	The 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::exception in 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

url	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::exception in case of errors.

◆ builder()

systems::DiagramBuilder<double>* builder ( )

Gets a mutable pointer to the DiagramBuilder that will be modified by this parser, or nullptr if this parser does not have a DiagramBuilder.

◆ GetAutoRenaming()

bool GetAutoRenaming ( ) const

Get the current state of auto-renaming.

See also: the Parser class documentation for more detail.

◆ GetCollisionFilterGroups()

CollisionFilterGroups GetCollisionFilterGroups ( ) const

Gets the accumulated set of collision filter definitions seen by this parser.

There are two kinds of names in the returned data: group names and body names. Both may occur within scoped names indicating the model instance where they are defined. Note that the model instance names used in the returned data will reflect the current names in plant() at the time this accessor is called (see MultibodyPlant::RenameModelInstance()), but the local group and body names will be the names seen during parsing.

◆ 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.

◆ scene_graph()

geometry::SceneGraph<double>* scene_graph ( )

Gets a mutable pointer to the SceneGraph that will be modified by this parser, or nullptr if this parser does not have a SceneGraph.

◆ 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:

drake/multibody/parsing/parser.h

Detailed Description

Public Member Functions

Friends

Constructor & Destructor Documentation

◆ Parser() [1/6]

◆ Parser() [2/6]

◆ Parser() [3/6]

◆ Parser() [4/6]

◆ Parser() [5/6]

◆ Parser() [6/6]

◆ ~Parser()

Member Function Documentation

◆ AddModels()

◆ AddModelsFromString()

◆ AddModelsFromUrl()

◆ builder()

◆ GetAutoRenaming()

◆ GetCollisionFilterGroups()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ package_map()

◆ plant()

◆ scene_graph()

◆ SetAutoRenaming()

◆ SetStrictParsing()

Friends And Related Function Documentation

◆ internal::CompositeParse