DART  6.10.1
dart::utils::PackageResourceRetriever Class Reference

Retrieve local resources specified by package:// URIs by: (1) resolving the package path and (2) passing the resolved URI to another ResourceRetriever. More...

#include <PackageResourceRetriever.hpp>

Inheritance diagram for dart::utils::PackageResourceRetriever:
dart::common::ResourceRetriever

Public Member Functions

 PackageResourceRetriever (const common::ResourceRetrieverPtr &_localRetriever=nullptr)
 Construct a PackageResourceRetriever that uses the specified _localRetriever to load resolved URIs. More...
 
virtual ~PackageResourceRetriever ()=default
 
void addPackageDirectory (const std::string &_packageName, const std::string &_packageDirectory)
 Specify the directory of a ROS package. More...
 
bool exists (const common::Uri &_uri) override
 Returns whether the resource specified by a URI exists. More...
 
common::ResourcePtr retrieve (const common::Uri &_uri) override
 Returns the resource specified by a URI or nullptr on failure. More...
 
std::string getFilePath (const common::Uri &uri) override
 Returns absolute file path to uri; an empty string if unavailable. More...
 
virtual std::string readAll (const Uri &uri)
 Reads all data from the resource of uri, and returns it as a string. More...
 

Private Member Functions

const std::vector< std::string > & getPackagePaths (const std::string &_packageName) const
 
bool resolvePackageUri (const common::Uri &_uri, std::string &_packageName, std::string &_relativePath) const
 

Private Attributes

common::ResourceRetrieverPtr mLocalRetriever
 
std::unordered_map< std::string, std::vector< std::string > > mPackageMap
 

Detailed Description

Retrieve local resources specified by package:// URIs by: (1) resolving the package path and (2) passing the resolved URI to another ResourceRetriever.

This class uses requires you to manually provide the base URI of every package that you wish to resolve using the addPackageDirectory method.

Constructor & Destructor Documentation

◆ PackageResourceRetriever()

dart::utils::PackageResourceRetriever::PackageResourceRetriever ( const common::ResourceRetrieverPtr _localRetriever = nullptr)
explicit

Construct a PackageResourceRetriever that uses the specified _localRetriever to load resolved URIs.

◆ ~PackageResourceRetriever()

virtual dart::utils::PackageResourceRetriever::~PackageResourceRetriever ( )
virtualdefault

Member Function Documentation

◆ addPackageDirectory()

void dart::utils::PackageResourceRetriever::addPackageDirectory ( const std::string &  _packageName,
const std::string &  _packageDirectory 
)

Specify the directory of a ROS package.

In your URDF files, you may see strings with a package URI pattern such as:

"package://my_robot/meshes/mesh_for_my_robot.stl"
\______/ \______/\___________________________/
| | |
package package file path with respect to
keyword name the package directory

For us to successfully parse a URDF, we need to be told what the path to the package directory is, using addPackageDirectory(). In this case, suppose the path to the my_robot package is /path/to/my_robot. Then you should use addPackageDirectory("my_robot", "/path/to/my_robot"). Altogether, this implies that a file named "/path/to/my_robot/meshes/mesh_for_my_robot.stl" exists. Whatever you specify as the package directory will end up replacing the 'package keyword' and 'package name' components of the URI string.

You can call this method multiple times with the same _packageName to provide multiple candidates for resolution. This is necessarry if your resources are split between the Catkin devel and source spaces. Multiple candidates will be tested in the same order in which they were added.

This class supports arbitrary URIs for _packageDirectory, as long as they are supported by the _localRetriever passed to the constructor.

◆ exists()

bool dart::utils::PackageResourceRetriever::exists ( const common::Uri uri)
overridevirtual

Returns whether the resource specified by a URI exists.

Implements dart::common::ResourceRetriever.

◆ getFilePath()

std::string dart::utils::PackageResourceRetriever::getFilePath ( const common::Uri uri)
overridevirtual

Returns absolute file path to uri; an empty string if unavailable.

This base class returns an empty string by default.

Reimplemented from dart::common::ResourceRetriever.

◆ getPackagePaths()

const std::vector< std::string > & dart::utils::PackageResourceRetriever::getPackagePaths ( const std::string &  _packageName) const
private

◆ readAll()

std::string dart::common::ResourceRetriever::readAll ( const Uri uri)
virtualinherited

Reads all data from the resource of uri, and returns it as a string.

Parameters
[in]uriURI to the resource to be retrieved.
Returns
The string retrieved from the resource.
Exceptions
std::runtime_errorwhen failed to read sucessfully.

◆ resolvePackageUri()

bool dart::utils::PackageResourceRetriever::resolvePackageUri ( const common::Uri _uri,
std::string &  _packageName,
std::string &  _relativePath 
) const
private

◆ retrieve()

common::ResourcePtr dart::utils::PackageResourceRetriever::retrieve ( const common::Uri uri)
overridevirtual

Returns the resource specified by a URI or nullptr on failure.

Implements dart::common::ResourceRetriever.

Member Data Documentation

◆ mLocalRetriever

common::ResourceRetrieverPtr dart::utils::PackageResourceRetriever::mLocalRetriever
private

◆ mPackageMap

std::unordered_map<std::string, std::vector<std::string> > dart::utils::PackageResourceRetriever::mPackageMap
private