YARP  2.3.70.2
Yet Another Robot Platform
The ResourceFinder Class (advanced)
Author
Lorenzo Natale and Elena Ceseracciu

In this tutorial we show more details of how to use the yarp::os::ResourceFinder to locate files.

Introduction

In a previous tutorial (The ResourceFinder Class (basic)) we showed how to use the ResourceFinder to organize modules parameters in files and place them in what we called context directories in a directory inside the home of the user (e.g. in Linux this was: $HOME/.local/share/yarp/contexts).

We show here that the ResourceFinder is also useful to handle access to all files needed by a module.

In this example our (hypothetical) module performs object recognition on images. It accepts the following parameters:

--robot name: the name of the robot, used for connecting to a port that streams images
--model filename: a ppm file that stores a template image

Similarly to the previous tutorial we prepare a file that stores the initialization parameters of our module.

or.ini:

robot robby
model bottle.ppm

we place this file together with the template bottle.ppm in a directory called 'orBottle' in $YARP_DATA_HOME/contexts .

The main function will be something like:

ResourceFinder rf;
rf.setVerbose();
rf.setDefaultConfigFile("or.ini");
rf.configure(argc, argv);

This creates an instance of the ResourceFinder, and configures it from data from the command line.

This code shows how to query the value of the parameters:

ConstString robotName=rf.find("robot").asString();

Now we can read the file specified in the parameter 'model' by calling:

ConstString model=rf.findFile("model");

RF searches the file 'bottle.ppm' in the current initialization context. If successful "model" is a string that contains the full path to the file. Otherwise the string is empty.

if (model=="")
{
cout<<"Sorry no model was found, check config parameters"<<endl;
return -1;
}
cout << "Using object model: " << model.c_str() << endl;
// we can now read the image from disk using full path name
...
...

Simply run:

tutorial_rf_advanced --context orBottle

It is quite easy to change configuration files (and model) by switching the initialization context of the module:

tutorial_rf_advanced --context orCup

Discussion

We have shown how to use the ResourceFinder class to pass not only parameters but also binary files to a module. We have seen that it is again easy to re-configure a module simply by switching its initialization context.

From these tutorials you might have had the feeling it is better to create a new directory for each new configuration file for a module. This is not always the case. For simple modules (i.e. modules that require only a limited set of parameters to run) it will be much better to just use one context and separate configuration files. The name of the configuration file used by the ResourceFinder is determined by the line:

rf.setDefaultConfigFile("or.ini");

this is the default name, but it can be modified at runtime by running the module with the parameter –from, as exaplained in the previous tutorial:

tutorial_rf_advanced --context orBottle --from or2.ini

In other cases, especially when a module uses several resource files, it is more appropriate to duplicate all files in a different context directory. What solution is more appropriate depends on the specific case.

You should now read the tutorial How to install files for the ResourceFinder which describes how to use CMake to configure your build so that configuration files are automatically installed. It also links to the documentation of the yarp-config tool, that helps to manage context directories (inspecting the system for all the existing contexts, copying and removing them to/from the user home).

See also the yarp::os::ResourceFinder class documentation.

Code

See code in: example/resourceFinder/tutorial_rf_advanced.cpp