Tips and frequently asked questions

How do command-line options work?

For a general introduction without which the details below may be difficult to understand, see here.

Command-line options use a shared namespace and are all defined in ModelOptionDef.C. See here for an explanation of why that is. The general behavior is as follows: only ModelParam<T> data members from ModelComponent objects may be exported as command-line options; each ModelComponent requests to the ModelManager that some or all of its ModelParam<T> data members be exported to the command-line; the ModelManager is in charge of parsing the command-line, and will set the ModelParam<T> value to the parsed command-line value for each ModelComponent that requested the corresponding command-line option. The process is entirely dynamic: if no ModelComponent requested a given option, it will not be available (and will not show up in the --help page); if parsing an option and setting the corresponding ModelParam<T> values triggers new options to be exported, they will become available immediately (see below for more detailed explanations of how to add command-line options that depend upon previously parsed command-line option values).

Typically, things go as follows:

What if I want to hide options from the user except for a couple?

If you need to be more specific than the general export classes defined for ModelComponent::exportOptions() with OPTEXP_XXX in ModelOptionDef.H, you will need to manually request the options using ModelComponent::doRequestOption() on your ModelComponent objects.

An example of this is provided in the implementation of RadioDecoder::exportOptions() in RadioDecoder.C. Radiodecoder has an AudioGrabber subcomponent; we would like to let the users choose the device file name for the grabber, but we don't want them to change the audio recording frequency, otherwise the radio decoding will not work. So we explicitly block recursion in the call to exportOptions() at the level of the RadioDecoder, and manually export the device name option of the AudioGrabber subcomponent.

Another possible approach is to make a very conservative call to ModelComponent::exportOptions(), for example, exporting nothing, and then to explicitly export some select options by calling ModelComponent::doRequestOption(), on the manager (which will propagate to all components of the model), or on some model components.

How do I use my own custom option values instead of those provided in ModelOptionDef.C?

There are several ways of doing that. You can change an option value using ModelManager::setOptionValString() before you parse the command line, to set a new default value. See how this is used in bmcvfigs.C for an example.

Another approach is that you may want to change a bunch of default values depending on the type of derivation of an object which you will instantiate on a given run of your model. Furthermore, in such case, typically the object type initially is not known, and becomes known only while parsing the command-line. An example of that is for FrameGrabber objects; we would like to set the defaults that are most likely to work for either a V4Lgrabber or an IEEE1394grabber, but both sets of defaults differ substantially. To solve this, first, we use a FrameGrabberConfigurator to select the type of FrameGrabber derivative to use (see definition in FrameGrabber.H). Then, in FrameGrabber::exportOptions(), we instruct the ModelManager to use our current ModelParam values as option defaults, rather than the global defaults in ModelOptionDef.C; this is achieved by setting the third argument of the ModelManager::requestOption() calls to true (it is false by default). Finally, in the constructors of V4Lgrabber (see V4Lgrabber.C) and IEEE1394grabber (see IEEE1394grabber.C), we set our custom defaults. So as a V4Lgrabber or an IEEE1394grabber gets instantiated and gets a chance to exportOptions(), the correct defaults are being pushed into the ModelManager. Be careful with this, typically you would want to use this technique only if you expect to have only one object of the type in question in your model.

Ok, that sounds cool, but what if I have several instances of a given object but want to have different options for each instance?

In this kind of case, you typically will set the parameters that differentiate your objects by hand, and then will export by hand only those options which may be shared by your objects.

An example of that is in test-stereo.C, which uses two IEEE1394grabber objects, for the left and right eyes. The first grabber is manually configured to use FrameGrabber subchannel 0 using ModelComponent::setModelParamVal(), and the second one to use subchannel 1. Clearly, it hence does not make sense for this setup to export a command-line option to set the subchannel. So instead, we export no option through the standard ModelManager::exportOptions() call. Then we only export a few options like image size and grab mode, by hand, calling ModelComponent::doRequestOption() on the manager. This will recurse and both grabbers will request the option since we have registered both with the manager, and when command-line options are parsed, they will affect both grabbers equally.

How do I replace one of my regular internal parameters by a ModelParam<T>?

How do I set the FOA radius?

That's a good one. Once you have called ModelComponent::start() on your manager, you can't change option values anymore (that's to prevent people from changing, e.g., the number of orientations in an OrientationChannel while a simulation is running). But you need to start the model and load the first input image in order to get its dims and compute the FOA radius. We solve this in two ways:

Generated on Sun May 8 08:43:02 2011 for iLab Neuromorphic Vision Toolkit by  doxygen 1.6.3