QVision tutorial

Index

About the library

QVision is an image and computer vision framework, developed by the PARP Computer Perception Research Group, from the University of Murcia, Spain. It's main purpose is to help research for new algorithms in the fields of video and image processing, and Computer Vision. It's open source, so it is oriented to academic and research audience.

Configuring and installing the library

Package and program dependencies of the QVision.

Right now, QVision needs the following libraries and programs to be installed in the system. In a future, it will be a modular library, so you will be able to compile the core, without the parts that use each of these libraries and programs listed, if you don't need the functionality they provide to the QVision:

GSL - GNU Scientific Library. Version 1.9-3 or later.
This library is needed for math computations, on matrices, vectors, and tensors.

If you are planning to install QVision on an Ubuntu or Debian system, you can directly install the following packages using apt-get, synaptic, or adept package managers (or similar packaging system):

For GSL: libgsl0 and libgsl0-dev.
Version 1.9-3 was tested and worked for current version of QVision. Blas and LaPack libraries will be installed too with this library.

Also, some Ubuntu systems may need to install package g++, needed for Qt to compile.

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
shiit 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 to be printed lots of debug information while the program is running when compiling in debug mode, that will heavily decrease the execution time.

Compilation and Install.

Once customized the program, type:

	# cd QVision
	# qmake
	# make

to compile the library. When compilation is done, you should install the library. There will be copied 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 do the following:

	# make install

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

	# sudo make install

to make the installation proceed. If you need to delete the installation, simply compile again, and use the following line:

	# sudo make uninstall

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

Compiling and using programs in QVision

QVision projects

QVision is developed over Qt library, so every program should be compiled inside a Qt project.

To create a Qt project you need to write a .pro file. This is like an advanced Makefile file, were you should specify the source and header files, compilation options, libraries, and other stuff, that you will include or use in your project. With this .pro file you can use the qmake program, which is a tool from the Qt library, to create the specific Makefile for the project, that you can use to finaly compile the program, with the Qt binaries linked correctly, and everything properly configured for your machine.

To make a program based on QVision you should create a Qt project file, that at least references to all the source and header files, and includes the project file for QVision qvproject.pri. That file should be located in the install directory of the QVision, and should be included in the .pro file with this line:

include(<path to QVision>/qvproject.pri)

where <path to QVision> should be the absolute path to QVision install directory. For example:

include(/usr/local/QVision.0.0.5/qvproject.pri)

This line includes in the project all the references to the library binaries, and configurations that require the use of the QVision.

User interface

The program opens some windows and widgets for user input-output. They will be explained latter in detail in the section TheGUI. Below is an image of the look of the interface:

exampleminuto.png

Beside that interface, the user can set initial values for some properties, through comman line parameters. You can check the properties of the example program with the command line parameter help. Every QVision application recognices that parameter, and shows a list of the usage and main properties that you can set through the command line. The output of the program example when invoqued with that parameter:

	# ./example --help

is:

	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.

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

QVision's command line parameter system will be explained in the section TheGUI, along the graphical interface, but it is best recommended to read the following section of this documentation, Programming, to understand how to add and use these parameters.

An advanced programming example

Conceptually, a QVision program haves the following structure:

qvision_application_diagram.png

In witch the items have the next functionality:

Now it is shown an example .pro file for a simple QVision project. For futher info about the qmake tool, and the sintax of .pro files you can check the online manual for QMake.

Here is detailed how to make a simple QVision project, with a .pro file and all the code in just one .cpp source file. Supossing you have installed QVision in the url /usr/local/QVision.0.0.5 you can create a file called example.pro with the following content:

include(/usr/local/QVision.0.0.5/qvproject.pri)
TARGET = example

# Input
SOURCES += example.cpp

If you don't have QVision installed in that directory just change the path in the first line according to what is explained in section QVision projects.

Next, you can create the file example.cpp:

#include <qvcameras/qvmplayercamera.h>
#include <qvcore/qvapplication.h>
#include <qvgui/qvisioninterface.h>

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");
                        setPropertyValue< QVImage<uChar,1> >("Output image", image); 
                        }
        };

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

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

        QVGUI interface;

        QVImageCanvas imageCanvas("Test image");
        imageCanvas.linkProperty(worker,"Output image");

        return app.exec();
        }

Note that the file example.cpp is referenced in the file example.pro, at the line:

SOURCES += example.cpp

Also note that as it is explained in the previous section The first program, the project file also includes the project file for QVision projects:

include(/usr/local/QVision.0.0.5/qvproject.pri)

If both files are in the same directory, you can compile from that location writting these instructions in the command line:

	# qmake
	# make

This will generate the binary example. Note that the name of the executable was specified in the example.pro file, in the line:

TARGET = example

You can execute the example program with this command line:

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

It is just a simple video player, that will show the video in the file pointed by the URL, in a window, with some control widgets.


Generated on Thu Jul 17 17:23:28 2008 for QVision by  doxygen 1.5.3