PARP Research Group University of Murcia, Spain


Starting guide

Framework setup

This guide is supposed to help in the installation and configuration of the QVision on a new system. It also includes instructions to get a first "hands-on", not so simple "kind-of-hello-world" QVision sample application running.

Package and program dependencies

Right now, QVision needs the following libraries and programs to be installed. The framework will be a modular library in a future, so you will be able to compile the core features without unnecessary functionality:

If you are planning to install QVision on a Ubuntu, Debian or any other distribution with a package management system based on apt-get, synaptic, or adept, you can directly install the following packages:

  • Packages for Qt library: libqt4-core, libqt4-debug, libqt4-dev, libqt4-gui, libqt4-qt3support, qt4-designer, qt4-dev-tools and qt4-doc.
    Version 4.3.2-0ubuntu3.1 of these packages was tested and worked correctly for current version of QVision.
  • Packages for QWT library: libqwt5-qt4 and libqwt5-qt4-dev.
    Version 5.0.1-2 of these packages was tested and worked correctly for current version of QVision.
  • Packages for MPlayer: mencoder and mplayer.
    Version 2:1.0 was tested and worked correctly for current version of QVision.
  • Packages for GSL and scientific calculus: lapack3, lapack3-dev, libgsl0 and libgsl0-dev.
    Version 1.9-3 for the GSL library was tested and worked correctly for current version of QVision.
  • Packages for Intel's IPP: there are no packages available in apt-get for that library. A free (consult conditions here) version is available for Linux platforms. You can download it from Intel's IPP homepage. Version 5.3 of this library was tested and worked correctly for current version of QVision.
  • Package for g++: Qt uses this compiler to built programs, but is not generally included with Ubuntu's base install. It should be included with the package g++.

Downloading the framework.

Latest release and older versions can be downloaded from the following url:

http://forja.rediris.es/frs/?group_id=321

Configuring.

Once you have the tar file for QVision, named QVision.<version>.tgz, copy it to your home directory (or a temporary location for compiling), and untar-it using this line:

	# tar xzvf QVision.<version>.tgz

Then you should copy the file QVision/config.pri.example to a file in the same directory, QVision, named config.pri. It has some performance and system configuration parameters inside used to compile QVision library. Change the content of the variables INSTALL_PATH, IPP_DIR, QWT_INCLUDE, QWT_LIB_DIRECTORY, and QWT_LIB_NAME, according to the specifications found in the config.pri.example file about them. They contain information about the location of the QWT and Intel's IPP libraries, and the install path for the QVision library.

Beside system and directories configuration, you can also tune performance and debugging options in the 'config.pri' file. You may uncomment the line

	CONFIG += release

to compile a faster version of the library, or else the library will compile in debug mode, including debug and error checking at execution time code. You can also uncomment the line:

	DEFINES += QT_NO_DEBUG_OUTPUT

if you don't want lots of debug information to be printed while the program is running when compiling in debug mode, heavily decreasing the execution time.

Compilation and Install.

Once customized your config.pri file, type the following in a terminal:

	# cd QVision
	# qmake
	# make

This will compile the library. When compilation is done, you should install it in your system. This will copy some files in the directory specified in the variable 'INSTALL_PATH'. If that route is in your home directory, or other place you have permissions to write, you should simply do the following:

	# make install

Otherwise, you should use sudo console command, to copy the files as a super-user:

	# sudo make install

If you need to uninstall the library, simply compile again, and use the following line:

	# sudo make uninstall

This will erase QVision's library files from the directory where you installed it previously.

First application under the QVision

QVision projects

In Qt applications are created inside projects. Therefore, to create a QVision application you should first create a Qt project. This is done creating a Qt project file. This is simply a text file with .pro extension, which includes the required information to compile the project using the qmake tool.

But do not worry, the .pro file format is really simple, specificly when it comes to QVision standard applications. 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/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

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 independent processing block, is an object created with the class PlayerWorker. As explained in the Block programming 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. When you become a regular user of the QVision framework, you will notice that this method will always contain the really important part of any new QVision programming block; the rest of the code in the example follows a rather repetitive and relatively easy to catch programming pattern.

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 a widget capable of displaying 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 of capital importance in the application. It must be the first object created by the main function in a QVision application, it must be a singleton -it should only be created once- and it will exist through the whole life of the application. After some needed objects creation and initialization, the exec() method on the created QVApplication will launch the involved worker(s) and start event processing. The exec method will only return when the application finishes. This class -which, by the way, directly inherits from the well known Qt QApplication class; but you don't even need to care about this for now- manages the GUI widgets, the signals and events behind the dynamic property links, and initializes many more aspects of the application. This object also processes the user command line parameters, which can stablish starting input values for the parameters of the algorithms.

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[])
        {
        // Incorrect: using a QApplication 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.
        }
If needed, you should instead use pointers to these objects like this:
int main(int argc, char *argv[])
        {
        // Correct: using a 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 QVApplication::exec() function.
        }
The QVDefaultGUI object, just as the QVApplication object, should only be created once before calling the QVApplication::exec method. A QVision application could also work without it, though you usually will want a GUI interface for it, won't you? :-D. If included, it will automatically create a window containing several widgets that offer several levels of control on different aspects of the execution of the application. For example, the user can change the values of the parameters of the application algorithms at execution time, and control the execution of the different processing blocks and the flow of the different video sources opened by the application. He or she will be able to stop, resume, advance the flow of the input video streams opened by the application, and stop, resume or advance one iteration for any worker -i.e., processing block- instantiated by the application.

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

This should create the binary executable example. The following command line will launch the application:

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

A user control window QVision default GUI and an image displayer widget Image canvas for Test image are created in its graphical user interface:

first-example-gui.png
first-example-imagecanvas.png

The application reads input frames from the video sequence stored in the video file http://perception.inf.um.es/public_data/videos/misc/minuto.avi, and shows them on the image displayer widget. 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. Section Video source identifier URL formats reviews the different inputs and formats allowed to specify an input video source in the command line parameter.

You can also tune other command line configuration parameters such as the size of the image (parameters Cols and Rows), amongst others. For further information about the possible command line parameters see section Command line parameters in QVision applications, but the reading of the next section is highly recommended before that.




QVision framework. PARP research group, copyright 2007, 2008.