Add example on how to load external URDF or SDF model and their resources

[traversaro]

(I am not sure if this is the right place where to file this issue, feel free to move it somewhere else if it make sense to do so).

For users that use drake as any other library in their own plain cmake/ROS1/ROS2 project (or robot manufactures that provide models of their robot, as in our case for https://github.com/robotology/icub-models), it would be convenient to have a small example on how to load a URDF or SDF that is not part of drake's provided resources. However, Drake's docs typically just cover the case of loading a file that is present inside Drake, see for example https://drake.mit.edu/doxygen_cxx/classdrake_1_1multibody_1_1_multibody_plant.html#sdf_loading . By inspecting https://drake.mit.edu/doxygen_cxx/classdrake_1_1multibody_1_1_package_map.html and https://drake.mit.edu/doxygen_cxx/classdrake_1_1multibody_1_1_parser.html it seems that it should be sufficient to have the following snippets.

Load external URDF

To load a URDF file installed by ROS (if ROS_PACKAGE_PATH is properly defined in the environment):

drake::systems::DiagramBuilder<double> builder;
auto [plant, scene_graph] = drake::multibody::AddMultibodyPlantSceneGraph(&builder, 0.0);
auto parser = drake::multibody::Parser(&plant, &scene_graph);
parser.package_map().PopulateFromEnvironment("ROS_PACKAGE_PATH");
auto model_instance = parser.AddModelFromFile(<urdf_file_absolute_path>);

Load external SDF

To load a SDF model contained in a repo structured as documented in http://gazebosim.org/tutorials?tut=model_structure, for example https://bitbucket.org/osrf/gazebo_models/src/default/

drake::systems::DiagramBuilder<double> builder;
auto [plant, scene_graph] = drake::multibody::AddMultibodyPlantSceneGraph(&builder, 0.0);
auto parser = drake::multibody::Parser(&plant, &scene_graph);
// <sdf_model_directory_name> is the name used after model:// in SDF's URIs 
// <sdf_model_directory_abs_location> is the actual location of the SDF directory
parser.package_map().Add(<sdf_model_directory_name>);
auto model_instance = parser.AddModelFromFile(<sdf_file_absolute_path>, <sdf_model_directory_abs_location>);

However I did not tested directly this snippets of code, so it is possible that they are wrong.

[jwnimmer-tri]

\CC @IanTheEngineer

[traversaro]

This upstream issue seems to be related: RobotLocomotion/drake#10531 .

[jwnimmer-tri]

FYI an update on current best practice: the parser now offers AddModelsFromUrl so users can pass a package:// URL directly to the parser (after adding the package to the PackageMap).