-
Notifications
You must be signed in to change notification settings - Fork 1
Software Development Guide
This guide explains how to set up a project in the DREAM/working/ directory so that you can compile your own components and run applications in exactly the same way as the component in the DREAM/release/ directory (see Software Installation Guide).
It also describes in detail two examples of how to develop a YARP-based component that is compliant with the DREAM standards for software engineering. The first example, protoComponent, implements some very simple image processing and analysis (binary segmentation using a supplied threshold and then count the number of foreground pixels). The second example, protoComponentGUI, explains how to write a component that implements a simple graphic user interface. The examples are accompanied by a demonstration application, again adhering to the DREAM standards. Both examples – the component code and the demonstration applications – are in the DREAM/release/ directory (see Software Installation Guide). For convenience, you can also review the code here:
- The protoComponent Example
- The protoComponentTEST Example
- The protoComponentGUI Example
- The protoComponentGUITEST Example
The first step in developing software in DREAM is the create a new project in the working directory associated with your organization, i.e. in DREAM/working/ ( e.g. DREAM/working/HIS).
Setting Up a Working Directory explains in detail how to do this.
When setting up a new project in your working directory, you will have noticed that each component comprises a number of files. It is important that you are familiar with the way these files are organized and what each one does.
Component Files explains the organization and function of each file in a typical DREAM component.
The key point is that the functionality of a component is split into three classes
- Component configuration and coordination
- Component computation and communication
The next two sections explain how this functionality is implemented in a component using YARP helper classes.
We begin with the functionality associated with configuration and coordination, i.e. with the protoComponentConfiguration.cpp and protoComponent.h files. This functionality revolves around the RFModule class. The protoComponentGUIConfiguration.cpp and protoComponentGUI.h files have essentially the same structure.
This section also deals with the main() function, i.e. with the protoComponentApplication.cpp file. It shows how to instantiate a module derived from the RFModule class, set the default configuration file and path for the resource finder, and run the module. This allows the component to be configured using the resource finder.
Once this is done, the derived module then instantiates a Thread or a RateThread object and launches it, passing to it as arguments all the relevant resources (e.g. port names and parameter values) located by the resource finder.
Finally, it is also responsible for shutting down the thread gracefully by stopping the thread, interrupting any port communications, and closing the ports.
Component Configuration and Coordination - The RFModule Class explains these implementation issues in detail.
We next address the functionality associated with computation and communication, i.e. with the protoComponentComputation.cpp and protoComponent.h files. This functionality revolves around the Thread and RateThread classes: how to access the parameters passed to it from the derived RFModule object and how to perform some useful work.
Component Computation and Communication - the Thread and RateThread Classes explains these implementation issues in detail.
We now show how you can write your own graphic user interface for the protoComponent component. This will be implemented as a separate stand-along component protoComponentGUI. As noted above, the functionality associated with configuration and coordination, i.e. with the protoComponentGUIConfiguration.cpp and protoComponentGUI.h files, is essentially the same as for the protoComponent example. Again, this functionality revolves around the RFModule class.
Instead, this section addresses the functionality associated with computation and communication, i.e. with the protoComponentGUIComputation.cpp and protoComponent.h files. Again, the functionality revolves around the Thread and RateThread classes but here we explain how to configure the graphic user interface with the _FLTK _ and _guiUtilities _ libraries.
GUI Component Computation and Communication - the FLTK and guiUtilities Libraries explains these issues in detail.
We adopt a convention for naming ports to avoid name pollution but still provide unique port names that as short as possible.
Details are in Guidelines for Naming Ports.
This section describes two test applications. The first test application shows how to configure and run a simple application to use the protoComponent by connecting it to other components that provide input images and display the output images. This application uses yarpview modules to view the images. The threshold is modified online by sending commands to protoComponent from the command line in a terminal window.
The second test application shows how to configure and run a simple application to use protoComponent and protoComponentGUI together. In this case, the images are displayed in the GUI rather than yarpview displays and the threshold is modified interactively using the GUI controls.
Test Applications describes these two test applications in detail.
Finally, note that DREAM follows a set of mandatory and recommended software engineering standards as set out in Deliverable D3.2.
The mandatory standards are contained in Appendices A, B, and C (File Organization, Internal Documentation, and Component Functionality, respectively), as well as Section 4 on Testing.
The recommended standards are contained in Appendices D and E (Programming Style and Programming Practice, respectively).
For easy reference, these standards are also described on the DREAM wiki, as follows.
- Mandatory Standards for File Organization
- Mandatory Standards for Internal Documentation
- Mandatory Standards for Component Functionality
- Mandatory Standards for Testing
- Recommended Standards for Programming Style
- Recommended Standards for Programming Practice
Please take the time to read through these documents as all components to be included in the standard DREAM release version have to comply with the mandatory standards.