First application with the QVision

QVision projects

In Qt, applications are created inside projects, so to create a QVision application, first you should create a Qt's project. It is done creating a Qt's project file. It is a text file with the .pro extension, including the required information to compile the project using the qmake tool.

The .pro file should list all the source and header files (*.cpp and *.h files respectively) of the project, and any other flag or configuration option required to compile it, like the path to a third-party library, or the debug flags.

We will show an example of .pro file, which we can use to create our first QVision application. It should have the following three lines:

include(/usr/local/QVision.0.1.0/qvproject.pri)
TARGET = example
SOURCES = example.cpp

The include directive is used to load the configuration contained in other project files. Every QVision project should include the file qvproject.pri, located in the QVision installation directory, which contains the proper configuration to compile QVision applications.

The TARGET variable must be set to the name of the target executable file for the application. The SOURCES variable must contain a list of the names of the source files in the project. In our example, the project will have only one file, named example.cpp.

The first program with QVision

We can store the previous project file with the name example.pro. Inside the same directory we can store the example.cpp source file, containing the following code:

#include <QVMPlayerCamera>
#include <QVApplication>
#include <QVWorker>
#include <QVDefaultGUI>

class PlayerWorker: public QVWorker
        {
        public:
                PlayerWorker(QString name): QVWorker(name)
                        {
                        addProperty< QVImage<uChar,1> >("Input image", inputFlag|outputFlag);
                        addProperty< QVImage<uChar,1> >("Output image", outputFlag);
                        }

                void iterate()
                        {
                        QVImage<uChar,1> image = getPropertyValue< QVImage<uChar,1> >("Input image");

                        // image processing / computer vision code should go here

                        setPropertyValue< QVImage<uChar,1> >("Output image", image); 
                        }
        };

int main(int argc, char *argv[])
        {
        // QVApplication object
        QVApplication app(argc, argv, "Example program for QVision library. Play a video on a canvas window.");

        QVMPlayerCamera camera("Video");        // QVCamera object
        PlayerWorker worker("Player worker");   // QVWorker object
        camera.link(&worker,"Input image");

        // GUI object
        QVDefaultGUI interface;

        // Video/image output object
        QVImageCanvas imageCanvas("Test image");
        imageCanvas.linkProperty(worker,"Output image");

        return app.exec();
        }

This application creates a single processing block in the main function, named the Player worker. It just reads the input frames from a video sequence, and sends them to a video output widget. The worker, or processing block is an object created with the class PlayerWorker. As is already explained in the Dynamic properties section, that object is a property container, which reads the input frames from the dynamic property Input image using the method getPropertyValue, and stores the result (in this case the same unmodified input image frames) in the dynamic property Output image. This is performed in the iterate method.

A QVMPlayerCamera object is connected to the player object using the QVMPlayerCamera::link method, to feed in the dynamic property Input image new input images. It is an implementation of an object capable of reading from a wide set of input video sources, like video files, webcams, or remote streams, based on the MPlayer application.

The QVImageCanvas object named Test image is an output widget that can show output images coming from a worker. It is connected using the method linkProperty to the Output image dynamic property to show incoming image frames from that worker.

The QVApplication object is capital in the application. It must be the first object created by the main function in a QVision application. It manages the GUI widgets, the signals and events behind the dynamic property linkings, and initializes many more aspects of the application.

Warning:
Because the exec() function is not virtual in the QApplication class, make sure you call the exec() function from the QVApplication class, not from the QApplication class, in a QVision application. Basically, avoid creating and using QVApplication objects like this:
int main(int argc, char *argv[])
        {
        // QVApplication object
        QApplication *app = new QVApplication(argc, argv, "Example program for QVision library. Play a video on a canvas window.");

        [...}

        return app->exec();     // this will execute QApplication::exec() function, not QVApplication::exec() function.
        }

You should instead use these objects like this:

int main(int argc, char *argv[])
        {
        // QVApplication object
        QVApplication *app = new QVApplication(argc, argv, "Example program for QVision library. Play a video on a canvas window.");

        [...}

        return app->exec();     // this will execute QApplication::exec() function, not QVApplication::exec() function.
        }

Compiling and executing the program

Once files example.cpp and example.pro are created and stored in the same directory, you can compile the application using the qmake and the make tools:

	# qmake
	# make

Creating the binary example. The following command line will launch the application:

# ./example --URL=http://perception.inf.um.es/public_data/videos/misc/minuto.avi

The image below shows the user interface of the application:

exampleminuto.png

The QVImageCanvas and the QVDefaultGUI objects create an image displayer widget and a control widget respectively. These user interface objects will be discussed with other in the following sections.

Every camera or worker created in a QVision application specifies some command line input parameters. For example, the --URL parameter from the command line is a camera parameter which can be set to the video source to be used by the camera.

You can get the list and usage of every command line input parameter of a QVision application using the parameter --help. Once compiled, the following command line:

# ./example --help

Will make the application print the following usage and parameters list:

Usage: ./example [OPTIONS]
Example program for QVision library. Play a video on a canvas window.

Input parameters for Video:
--Rows=[int] (def. 0) .............................. Rows to open the camera. 
--Cols=[int] (def. 0) ........................... Columns to open the camera. 
--RealTime=[true,false](def. false)  If the camera should be opened in real time mode. 
--Deinterlaced=[true,false](def. false)  If the camera should be opened in deinterlaced mode. 
--NoLoop=[true,false](def. false)  If the camera should be opened in no loop mode. 
--RGBMEncoder=[true,false](def. false)  If the camera should be opened in RGB using mencoder. 
--URL=[text] ............................ URL of the video source (see doc.). 

Input parameters for Player worker:
--print stats=[true,false](def. false)  Enables realtime stats console output for worker.</pre>

You can change the input video source, changing the value for the URL command line parameter, so the example program reads from a video file different than the file minuto.avi, as well as other video input configuration parameters such as the size of the image (parameters Cols and Rows), amongst others. For example:

# ./example --URL=http://perception.inf.um.es/public_data/videos/misc/penguin.dv

Or:

# ./example --URL=http://perception.inf.um.es/public_data/videos/misc/penguin.dv --Rows=240 --Cols=320

Section Video source identifier URL formats reviews the different inputs and formats allowed to specify in that command line parameter.