SourceXtractorPlusPlus
0.14
Please provide a description of the project.
|
The structure of this tutorial is identical to that of the HowTo add a new source property computation and readers are assumed to have a good knowledge of this previous tutorial. The main difference is the introduction of a configuration class, through which user inputs can be entered into the property computation. To mark the similarities (and the differences), the same class names are used with a WithConf post-fix. We continue to walk-trough a kind of munimum example. The standard directory structure (already described here) is assumed.
Note that not much effort is made here to make a smart example. It is only thought for illustration purposes.
Below is our minimum ExamplePropertyWithConf class.
This class is fully analogous to the previous ExampleProperty and we refer to it for explanation. This property has two member variables and two getters, but there is nothing related to the configuration yet.
Below is the (new) configuration class. After include and namespace comes the definition of the argument names. The anonymous namespace enclosing these variables limits their visibility to the current file (identical to a static declaration).
The somewhat strange class name should read "example configuration for a plugin with configuration". It extends a Configuration base class which defined to-be-implemented interfaces. getProgramOptions() will be called by the system to get the options specific to this plugin. The syntax follows that of the Boost program_options library. The first field is the option name, the second one the option type, with a default value (if any) and the third one is a longer help text. The initialize method allows to retrieve the options and stored them in local variable. Finally getters are defined to provide means to read the configuration information after initialization. The choice of two configuration item is again only dictated by illustration purposes.
In this example, default values are provided for the two options. This make their run-time specification (though command -line arguments for example) optional. It is also possible not to give any default values, but then, the case where the arguments are missing has to be dealt with in the code. What to do if not arguments are provided? It may lead to a stop with the generation of an exception for missing arguments or to a continuation without argument values. See next tutorial for another example of optional configuration.
Below is the ExampleSourceTaskWithConf example analogous to the ExampleSourceTask. The main method is again computeProperties(source), but now there are two member variables (they were none before), which will be filled through a constructor call with information coming from the configuration. There is however no directed connection between the task and the configuration classes. Things will be tied together through the task factory (see next section).
The pixel mean calculation is identical to the previous case, but the configuration-provided information is used to create the property. Remember that source.setProperty<ExamplePropertyWithConf>() is first calling the property constructor (i.e., ExamplePropertyWithConf(m_name_option, m_scaling_factor_option * mean_value), before attaching the property to the source.
The purpose of the task factory now becomes clearer. As it can be seen in the below ExampleTaskFactoryWithConf example, the configuration object and its members are retrieved through the configuration manager (and the getters). They are then stored in local variable before being channeled to the factory method which create the task. The task factory uses the configuration to initialized the task and in this way, it connects user inputs to the property computation.
The reportConfigDependencies(...) method must be implemented to declare configuration dependencies. Here, there is no other dependency than the ExampleConfWithConf itself.
The below plugin is almost identical to that of the previous ExamplePlugin example. The only difference is the registration of two output columns (from the same property).
Last but not least, the following statement must appear in the plugin .cpp file. It registers our example plugin as a static plugin (i.e., which must be compiled with SExtractor). Other types of plugin will be described later.