The protoComponent Example
From David Vernon's Wiki
Contents
protoComponent.h
/** @file protoComponent.h Interface file for the example DREAM component
*
* Version 1.0
*
* 20/8/2014
*
*
* \defgroup DREAM_protoComponent protoComponent
*
* This application demonstates the use of the protoComponent module.
* This is a simple example to illustrate a component that is compliant with
* mandatory DREAM software standards for
*
* 1. File organization
* 2. Internal source code documentation
* 3. Component functionality
*
* as well as recommended DREAM software standards for
*
* 4. Programming style
* 5. Programming practice
*
* These standards are documented in Appendices A-E of Deliverable 3.2
*
* Overall, the standards address the 4 Cs of component-based software engineering:
*
* - configuration
* - coordination
* - computation
* - computation
*
* Functionally, the module just reads an input image from an input port,
* converts it to a binary image based on the supplied threshold,
* and writes it to an output port
*
* The module also reads a configuration file containing the intrinsic
* parameters of the robot's two cameras as an example of more advanced parsing
* techniques.
*
* A complete tutorial for this example is available on the DREAM wiki
*
*
* \section lib_sec Libraries
*
* YARP.
*
* \section parameters_sec Parameters
*
* Command-line Parameters
*
* The following key-value pairs can be specified as command-line parameters
* by prefixing \c -- to the key e.g. \c --from file.ini.
* The value part can be changed to suit your needs; the default values are
* shown below.
*
* - \c from \c protoComponent.ini \n
* specifies the configuration file
*
* - \c context \c protoComponent/configuration \n
* specifies the sub-path from \c $DREAM_ROOT/protoComponent/configuration
* to the configuration file
*
* - \c name \c protoComponent \n
* specifies the name of the module (used to form the stem of module port names)
*
*
* Configuration File Parameters
*
* The following key-value pairs can be specified as parameters in the configuration file
* (they can also be specified as command-line parameters if you so wish).
* The value part can be changed to suit your needs; the default values are shown below.
*
* - \c myInputPort \c /image:i \n
* specifies the input port name (this string will be prefixed by \c /protoComponent
* or whatever else is specifed by the name parameter
*
* - \c myOutputPort \c /image:o \n
* specifies the output port name (this string will be prefixed by \c /protoComponent
* or whatever else is specifed by the name parameter
*
* - \c cameraConfig \c cameras.ini \n
* specifies the camera configuration file containing the intrinsic parameters of
* the left and right cameras
*
* - \c threshold \c 7 \n
* specifies the threshold value
*
*
* \section portsa_sec Ports Accessed
*
* - None
*
* \section portsc_sec Ports Created
*
* Input ports
*
* - \c /protoComponent \n
* This port is used to change the parameters of the module at run time or stop the module. \n
* The following commands are available
*
* \c help \n
* \c quit \n
* \c set \c thr \c <n> ... set the threshold for binary segmentation of the input RGB image
* (where \c <n> is an integer number)
*
* Note that the name of this port mirrors whatever is provided by the \c --name parameter value
* The port is attached to the terminal so that you can type in commands and receive replies.
* The port can be used by other modules but also interactively by a user through the yarp rpc directive, viz.: \c yarp \c rpc \c /protoComponent
* This opens a connection from a terminal to the port and allows the user to then type in commands and receive replies.
*
* - \c /protoComponent/image:i \n
*
* Output ports
*
* - \c /protoComponent \n
* see above
*
* - \c /protoComponent/image:o \n
*
* Port types
*
* The functional specification only names the ports to be used to communicate with the module
* but doesn't say anything about the data transmitted on the ports. This is defined by the following code.
*
* \c BufferedPort<ImageOf<PixelRgb> > \c myInputPort; \n
* \c BufferedPort<ImageOf<PixelRgb> > \c myOutputPort;
*
* \section in_files_sec Input Data Files
*
* None
*
* \section out_data_sec Output Data Files
*
* None
*
* \section conf_file_sec Configuration Files
*
* \c protoComponent.ini
* \c cameras.ini
*
* \section example_sec Example Instantiation of the Module
*
* protoComponent --name protoComponent --context components/protoComponent/config --from protoComponent.ini
*
* \author
*
* <name of author>, <author institute>
*
* Copyright (C) 2014 DREAM Consortium
*
*/
/*
* Copyright (C) 2014 DREAM Consortium
* FP7 Project 611391 co-funded by the European Commission
*
* Author: <name of author>, <author institute>
* Email: <preferred email address>
* Website: www.dream20202.eu
*
* This program comes with ABSOLUTELY NO WARRANTY
*/
/*
* Audit Trail
* -----------
* 20/08/14 First version validated (David Vernon)
*/
#include <iostream>
#include <string>
#include <yarp/sig/all.h>
#include <yarp/os/all.h>
#include <yarp/os/RFModule.h>
#include <yarp/os/Network.h>
#include <yarp/os/Thread.h>
using namespace std;
using namespace yarp::os;
using namespace yarp::sig;
class ProtoComponentThread : public Thread
{
private:
/* class variables */
int x, y;
PixelRgb rgbPixel;
ImageOf<PixelRgb> *image;
/* thread parameters: they are pointers so that they refer to the original variables in protoComponent */
BufferedPort<ImageOf<PixelRgb> > *imagePortIn;
BufferedPort<ImageOf<PixelRgb> > *imagePortOut;
int *thresholdValue;
public:
/* class methods */
ProtoComponentThread(BufferedPort<ImageOf<PixelRgb> > *imageIn, BufferedPort<ImageOf<PixelRgb> > *imageOut, int *threshold );
bool threadInit();
void threadRelease();
void run();
};
class ProtoComponent:public RFModule
{
/* module parameters */
string moduleName;
string inputPortName;
string outputPortName;
string handlerPortName;
string cameraConfigFilename;
float fxLeft, fyLeft; // focal length
float fxRight, fyRight; // focal length
float cxLeft, cyLeft; // coordinates of the principal point
float cxRight, cyRight; // coordinates of the principal point
int thresholdValue;
/* class variables */
BufferedPort<ImageOf<PixelRgb> > imageIn; //example input port
BufferedPort<ImageOf<PixelRgb> > imageOut; //example output port
Port handlerPort; //a port to handle messages
/* pointer to a new thread to be created and started in configure() and stopped in close() */
ProtoComponentThread *protoComponentThread;
public:
bool configure(yarp::os::ResourceFinder &rf); // configure all the module parameters and return true if successful
bool interruptModule(); // interrupt, e.g., the ports
bool close(); // close and shut down the module
bool respond(const Bottle& command, Bottle& reply);
double getPeriod();
bool updateModule();
};
protoComponentMain.cpp
/*
* Copyright (C) 2014 DREAM Consortium * FP7 Project 611391 co-funded by the European Commission * * Author: <name of author>, <author institute> * Email: <preferred email address> * Website: www.dream20202.eu * * This program comes with ABSOLUTELY NO WARRANTY */
/*
* Audit Trail * ----------- * 20/08/14 First version validated (David Vernon) */
- include "protoComponent.h"
int main(int argc, char * argv[]) {
/* initialize yarp network */
Network yarp;
/* create your module */
ProtoComponent protoComponent;
/* prepare and configure the resource finder */
ResourceFinder rf;
rf.setVerbose(true);
rf.setDefaultConfigFile("protoComponent.ini"); // can be overridden by --from parameter
rf.setDefaultContext("protoComponent/configuration"); // can be overridden by --context parameter
rf.configure("DREAM_ROOT", argc, argv); // environment variable with root of configuration path
/* run the module: runModule() calls configure first and, if successful, it then runs */
protoComponent.runModule(rf);
return 0;
}
