The protoComponent Example

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();
};