Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

phSimpleVision Class Reference
[Vision Classes]

#include <phSimpleVision.h>

Inheritance diagram for phSimpleVision:

phMutex phObject List of all members.

Detailed Description

This class creates a simple vision architecture. It has one capture class, one pipeline and up to four displays. The displays consist of two native video windows and two network transfer displays each connected to the capture class and the output of the single pipeline.

The capture class allows the setting of the capture device and the channel setting as well as all the picture settings except the capture format as it is rarely changed for any purposes in normal vision applications. Any conversions can be performed after the image is captured by any of the filters if necessary.

The pipeline can be altered to run different filters through the use of the member functions which have been abstracted to perform certain vision functions (train_color) where necessary.

The displays being used include the NetDisplay (using JPEG output) and a normal X11Display class. The NetDisplay class is intended to be used over lower bandwidth links (such as wireless) to prevent complete saturation using raw data when several people are using the same WAP. There are two of each display for displaying the raw capture output and the pipeline processed output.

The phSimpleVision class encapsulates a very simple vision framework using Phission components. The driving purpose behind this class is to handle many of the mundane details of setting up a vision system in Phission. This allows the phSimpleVision class to require little or no prior vision processing or Phission experience to allow a beginner student to get started with vision processing in as little time as possible.

Phission was initially built to provide the best performance possible for the given hardware on which it is being run. The design of an entire system consists of sources (capturing), sinks (displays) and sink-source (pipelines) objects. Setting up a vision system requires a good deal of setup code which not all users are interested in knowing right away. There is also a good deal of error checking and memory/class allocations to perform, too. The phSimpleVision class performs all these tasks to set up the more common example of a simple vision processing system.

phSimpleVision internal design

Internal to the class there exists one capture class that provides input to two display classes and one pipeline class. The pipeline class supplies input to two display classes, too. The capture class (derived from a phImageCapture class) opens a connection to a device capabale of capturing images and continually captures images to supply to the display and pipeline classes. The pipeline class (phPipeline) allows one to add a series of filter processing classes (derived from phFilter) that will be run on the images that are supplied from the capture device.

The two displays (derived from the phDisplayInterface class) provide the ability to view images either on a local machine or across the network. When one is trying out the phSimpleVision code on a desktop, it makes sense to use facilities which will provide the best display performance locally. For this reason, the X11Display is used to display images when one is running locally. If one desires to run the vision system on a remote machine, for example a robot, the best performance is acheived by compressing the image being displayed and then sending it across the network (as opposed to using the X protocol to remote display uncompressed images). For these reasons, two display classes are provided for each output within the phSimpleVision class: from the capture device and the pipeline class.

phSimpleVision example overview

There are currently 2 phSimpleVision examples. One for use with robots that have Pyro & PTZ capability and the other is a C++ example to demonstrate the features of phSimpleVision. The examples are located in the Phission example directory which can vary depending on where Phission is installed and whether you're using code checked out from CVS. If it is the former of the two, then you'll want to look for the examples in the installation directory: /usr/local/phission/examples/ or /usr/phission/examples/. Otherwise, the examples will be in in the directory 'examples' under the CVS checkout directory. All pyro examples will be located in examples/pyro and the C++ examples will be located in examples/cpp.

Example phSimpleVisionTest

This example is located in phission/examples/cpp/phSimpleVisionTest. If you're working out of a Phission installation you might want to copy this directory to your own private working directory. See the next paragraph for how to copy an example to your own directory. If you own the directory and want to make changes directly in it or just want to run the examples then you can simply 'cd' to that directory. Once you have a working example directory you can run 'make' to build the example. The executable will be placed into the bin/ directory of the current directory.

To copy the phSimpleVisionTest directory to your home directory, the following procedure should be followed.

  1. Copy the example directory completely to your home directory: $ cp -pR /path/to/phission/examples/cpp/phSimpleVisionTest ~
  2. Copy the Makefile.example file that the example's Makefile depends on: $ cp /path/to/phission/examples/cpp/Makefile.example ~/phSimpleVisionTest
  3. Edit the phSimpleVisionTest Makefile and change topdir to be "." instead of ".." so it'll look within its own directory to include the Makefile.example file.

The phSimpleVisionTest has the following command line arguments available for use:

supply the list of arguments

Add a method to add a custom filter into the pipeline

Add a print method to print out what the system looks like

Add the optional parameters to the filter methods to allow control of the filter parameters instead of using just the defaults.


This is a Pyro example that uses a Finite State Machine to control the robot and makes use of the Phission phSimpleVision class for PTZ training and tracking of

To copy the example for your own use: cp -pR /path/to/phission/examples/pyro/brains /home/username/etc

To simply run that example without modification:

$ cd /path/to/phission/examples/pyro/brains

$ pyro -r Aria -b

phSimpleVision API - Display settings:

API Note (Displays):

For all the display methods, 'which' refers to which output the particular display is connected to.

Valid values include:

The short forms:

Performance Note (Displays):

A very useful feature is the ability to enable and disable the displays. A display is really only needed during debug or experimentation time. When it comes time to cut down on the amount of resources the system is using (to get better performance) the displays can all be disabled right before the main loop has been entered and all setup is done.

NetDisplay notes:

The NetDisplay functionality is disabled by default. You must enable it with one of the NetDisplay control methods. The NetDisplay's default port is 44444 for the Capture output and 44445 for the Pipeline output. There is a NetClientTest program availible for monitoring the output from a NetDisplay class and can be located in either "/usr/local" or "/usr" (depending upon installation):


If the executable isn't already built, you can copy the directory to your home directory using the following steps:

mkdir phission_examples
cd /usr/local/phission/examples/cpp
cp -pR NetClientTest ~/phission_examples
cp Makefile.example ~/phission_examples

The example requires the Makefile.example file to be one directory above (unless one wants to edit the Makefile in the NetClientTest directory to point to a different directory).
When the NetClientTest example is built, it can be executed as follows (from the NetClientTest directory):

./bin/NetClientTest 44444

phSimpleVision API - System control methods:

The vision processing system is not always running when an instance of the phSimpleVision class exists. Internal to all the Phission code exist many separate threads of execution to perform the many separate tasks required for image capture, processing and displaying. Before the system can do any processing it must be started and will then run concurrently with the normal application. Data and settings can be altered or retreived most the time while the threads are executing because careful care has been taken in implementing thread-safety within Phission. phSimpleVision takes care of calling the methods that are responsible for starting up the Phission vision processing system in three methods:

phSimpleVision API - Singular filter control methods:

These methods will run the respective filters by themselves within the pipeline. phSimpleVision handles all necessary pipeline accessing to remove the old filters and insert the new one.

phSimpleVision API - Histogram color training methods

phSimpleVision API - Internal object access methods

The following methods will return pointers to instances of internal objects contained in the phSimpleVision class. Sometimes the control methods provided by phSimpleVision just aren't enough and one needs more control. These should only be used if you know how to use the class objects being returned.

The interfaces to the following objects can be found in header files where Phission is installed. This is usually either going to be "/usr/phission/include" or "/usr/local/phission/include". Until the rest of the documentation for these objects is completed, it is suggested you look into the header files. Most the methods are self explainatory and there may be some enlightening comments, if any at all.

phSimpleVision example code

The examples are locate where Phission is installed. This directory will usually be "/usr/phission/examples" or "/usr/local/phission/examples".

phSimpleVision C++ examples

This demos all the singular filters when supplied the '--demo' parameter and will run the 'train' and 'track' filters otherwise. Pass it '--help' or see the source file for more command line switches.

phSimpleVision Pyro examples

This demonstrates a pan/tilt camera tracking a color that is trained on. When using Pyro, the command interface will accept 'self.dotrain = 1' to allow training without needing to press the bumper on the robot. This also demonstrates the use of a State Based brain for color training tracking and searching.

You'll likely want to run this program as such: pyro -r Aria -b

The phSimpleVisionDemo example demonstrates all the singular filter methods of the phSimpleVision class. Closing the display that contains the output of the pipeline will cycle through the filters. This is a very convenient demo because it has two displays side by side to show the original live image and the output image. When using Pyro, the command interface will accept 'self.switchfilter = 1' to cycle through the filters, too.

The phSimpleVisionTest example demonstrates training and tracking functionality of the phSimpleVision class without the robotic requisites. Closing the Pipeline output display will toggle between the train and track methods. When using Pyro, the command interface will accept 'self.switchfilter = 1' to toggle between train and track methods


Make the first parameter (or the only parameter) to each filter method have an operation parameter to detemine whether the filter should be added to the pipeline(default), inserted at the head/tail, replace all filters.

Definition at line 423 of file phSimpleVision.h.

Public Member Functions

 phSimpleVision ()
 ~phSimpleVision ()
int setPath (const char *path)
const char * getPath ()
int setChannel (uint32_t channel)
uint32_t getChannel ()
int enableNetDisplay (int which=-1)
int disableNetDisplay (int which=-1)
int isNetEnabled (int which=-1)
int setPort (uint32_t port)
int enableDisplay (int which=-1)
int disableDisplay (int which=-1)
int isDisplayEnabled (int which=-1)
int start ()
int pause ()
int stop ()
int isStarted ()
int isPaused ()
int isStopped ()
int empty ()
int motion ()
int canny ()
int sobel ()
int gaussian ()
int mean ()
int median ()
int inverse ()
int threshold ()
int add (uint32_t nFrames=2, uint32_t frame_step=1)
int subtract ()
int trainingRGB ()
int trainingHSV ()
int train (int colorspace=-1, int add_or_set=-1)
int trainSet (int colorspace=-1)
int trainAdd (int colorspace=-1)
phColor getColor ()
phColor getThreshold ()
int setColor (phColor color)
int setThreshold (phColor threshold)
int applyTraining (int add_or_set)
int trackingHSV ()
int trackingRGB ()
int track (int colorspace=-1)
uint32_t getBlobCount ()
uint32_t getBlobCount (uint32_t minsize)
phblob getMaxBlob ()
int resetTrackingData ()
blob_FiltergetBlobFilter ()
phBlobDatagetBlobData ()
histogram_FiltergetHistogramFilter ()
phHistogramDatagetHistogramData ()
phSystemgetSystem ()
phImageCapturegetCapture ()
phPipelinegetPipeline ()
phDisplayInterfacegetDisplay (int which)
NetDisplaygetNetDisplay (int which)

Private Member Functions

int stopAndEmptyPipeline ()
int switchToFilters (int *indexes, int count)
int switchToFilter (int index)
int initHistogramSettings ()
int initBlobSettings ()
int private_tracking (int which)
int private_training (int which)

Private Attributes

phDisplayInterface ** m_displays
int * m_displaysEnabled
int m_state
phFilter ** m_filters
int m_emptyIndex
int m_motionIndex
int m_cannyIndex
int m_sobelIndex
int m_gaussianIndex
int m_meanIndex
int m_medianIndex
int m_inverseIndex
int m_thresholdIndex
int m_addIndex
int m_subtractIndex
int m_blobIndex
int m_histIndex
int m_RGBIndex
int m_HSVIndex
phColor m_trainedColor
phColor m_trainedThreshold
phColor m_blobOutcolor
int32_t m_blobMinsize
float m_blobMinPercentage
phblob m_maxBlob

The documentation for this class was generated from the following files:

Copyright (C) 2002 - 2007 Philip D.S. Thoren ( )
University Of Massachusetts at Lowell
Robotics Lab Logo

Generated on Sat Jun 16 02:45:13 2007 for phission by  doxygen 1.4.4