Programmer notes

The iLab Neuromorphic Vision C++ Toolkit - Copyright (C) 2001-2005 by the University of Southern California (USC) and iLab at USC.

Major portions of the iLab Neuromorphic Vision C++ Toolkit are protected under the U.S. patent ``Computation of Intrinsic Perceptual Saliency in Visual Environments, and Applications'' by Christof Koch and Laurent Itti, California Institute of Technology, 2001 (patent pending; application number 09/912,225 filed July 23, 2001; see for current status)

This file is part of the iLab Neuromorphic Vision C++ Toolkit.

The iLab Neuromorphic Vision C++ Toolkit is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

The iLab Neuromorphic Vision C++ Toolkit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the iLab Neuromorphic Vision C++ Toolkit; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

Table of contents:


1.1. Purpose and Objectives

This toolkit provides a number of C++ classes to assist you in developing neuromorphic vision algorithms. Neuromorphic algorithms are motivated by and closely follow the architecture of biological brains.

Originally, this toolkit was developed to implement our model of bottom-up, saliency-based visual attention, as described in the following scientific articles (all available in PDF format from

L. Itti, C. Koch, E. Niebur, A Model of Saliency-Based Visual Attention for Rapid Scene Analysis, IEEE Transactions on Pattern Analysis and Machine Intelligence, Vol. 20, No. 11, pp. 1254-1259, Nov 1998.

L. Itti, Models of Bottom-Up and Top-Down Visual Attention, California Institute of Technology, Jan 2000. [Ph.D. Thesis]

L. Itti, C. Koch, A saliency-based search mechanism for overt and covert shifts of visual attention, Vision Research, Vol. 40, No. 10-12, pp. 1489-1506, May 2000.

L. Itti, C. Koch, Computational Modeling of Visual Attention, Nature Reviews Neuroscience, Vol. 2, No. 3, pp. 194-203, Mar 2001.

and many others (see web site, under 'publications').

The model takes an input color image or video sequence and predicts which locations in this image will attract our visual attention (that is, are conspicuous, or 'salient'). It replicates processing in posterior parietal cortex and other brain areas along the dorsal visual stream in the primate brain. The model includes a bottom-up (image-based) computation of low-level color, intensity, orientation and motion features, as well as a non-linear spatial competition which enhances salient locations in each of these feature channels. All feature channels feed into a unique scalar ``saliency map'' which controls where to next focus attention onto. Because it includes a detailed low-level vision front-end, the model has been applied not only to laboratory stimuli, but also to a wide variety of natural scenes. In addition to predicting a wealth of psychophysical experiments, the model demonstrates remarkable performance at detecting salient objects in outdoors imagery --- sometimes exceeding human performance --- despite wide variations in imaging conditions, targets to be detected, and environments.

1.2. Classes included in the package

1.3. Basic features of the programming environment

The toolkit makes use of a number of advanced C++ programming techniques, which are intended to make use of its various components easier and more flexible to the knowledgeable programmer. While this brings many advantages described below, one drawback is that some of the constructs and techniques employed may be unfamiliar to the inexperienced programmer. If you are only moderately familiar with C++, we urge you to very carefully read the book "The C++ Programming Language" (Third Edition or Special Edition), by Bjarne Stroustrup Addison-Wesley, ISBN 0-201-88954-4 or 0-201-70073-5. See for details.

To get started, please see the online documentation at (use the same username/pass as you used to obtain this code). Make sure you read all of the introductory pages (links to them are both on the front page and on the side bar, under "Related pages"). Once you have read those, a good way to get accustomed to the code base is to browse through the class hierarchy and click on the name of any highlighted entity you may not be familiar with. Also, be sure to check the online repository browser, which will allow you to check the full edit history of every source file, at

(same username/pass as for the documentation).

Also, a wrapper to "man" is provided and named saliency/bin/mn; once you have saliency/bin in you path, you can use it just like "man" to view documentation about a class or file as a man page; for example:

     mn lcd
     mn FrameGrabber.H

and so on. The actual man pages reside in saliency/doc/man and are created when you type "make doc" from within saliency/src/.


2.1. Subversion (SVN)

The easiest way to obtain the latest revision of the source code is from our Subversion repository. Subversion (abbreviated SVN, homepage is a version control system designed as a new-and-improved replacement for CVS.

There is an excellent O'Reilly book about Subversion, which is available, for free, in its entirety, here:
(Make sure that you click on links for the latest version of the book -- currently there are 1.0 and 1.1 versions, and (obviously) 1.1 is the more recent version).
If you have a question about subversion that isn't answered in this README, your next source should be the svn book online.

Subversion allows several programmers to simultaneously work on the same code and that will keep track of all changes made; to achieve that, the master copy of the source code is maintained in a central database, and the various programmers download a working copy of the code to their various machines and home directories. After they have modified the code and the modifications work, they post their changes back to the master repository for everyone to enjoy.

You can see the contents of our neuromorphic vision toolkit subversion repository through a web interface at:

(Be assured that although the URL contains 'viewcvs', you are indeed looking at a subversion (svn) repository, not a cvs one. The 'viewcvs' web interface works with both CVS and svn repositories).

This will allow you to see the various revisions, who made them and when, and to highlight differences between various versions of the code. You should not use this to download the code; rather follow these instructions:

2.2. Using svn

Go to the directory where you want to install the source code. Then type:

        svn checkout svn://

this will download the entire source tree.

You can now start editing the code (see below for the various subdirectories). Once you have made changes and have tested that everything compiles fine and works ok, you can check which files you have modified locally by typing:

        svn status
CVS USERS SEE NOTE BELOW REGARDING 'svn status' and 'svn update'

Once you are satisfied that your changes are ready for the world to see, you can post them by issuing (from the directory where you have made changes):

        svn commit -m"short message describing what you did"

If someone else has modified the same source code as you have, svn will refuse to commit your changes and ask you to first update your source to the latest subversion repository revision; you do that by typing:

        svn update
NOTE TO CVS USERS: Unlike in CVS, you should NOT use 'svn update' to quickly check which files you have modified locally. Instead you should use 'svn status', and here's why.
In fact CVS has a 'cvs status' command that would give you information about local changes, but its output is so verbose that nobody ever uses it; everyone uses 'cvs update' instead. Of course there are two problems with that: (1) it might bring in new modifications from the repository, which you don't necessarily want, and (2) it requires significant network bandwidth to communicate with the CVS repository and determine what changes you have made. In svn, the situation is much nicer. For one thing, the output of 'svn status' is now compact, just like the output of 'cvs update' was. For another thing, 'svn status' requires no network traffic -- subversion keeps pristine copies of the unmodified files tucked away inside the various .svn directories in your working copy. Therefore you can do 'svn status' or 'svn diff' to examine local changes without having to wait for the network, and without placing undue load on the svn server.

When you do 'svn update', subversion will try to merge other people's into your own working copy. Usually this is fully automatic, unless you have been editing exactly the same lines in a file as someone else has (you should then talk to that person to figure out why both of you are editing the same code, since usually different people will work on different parts of the code!). In this case, subversion will notify you that there has been a conflict by printing a 'C' next to the offending file's name during your 'svn update'. Subversion's approach to conflicts is more user-friendly than CVS's approach -- in particular, it won't let you commit a file containing those pesky >>>>>>>> conflict markers by accident. With subversion, you must explicitly notify svn after you've resolved the conflict, by using the 'svn resolved' command.

If there has been a conflict, subversion puts three extra files in your working copy:

  filename.mine     [contains just your local modifications]
  filename.r5000    [the base file against which you made local mods]
  filename.r5001    [the latest version on the server]

where '5000' is the revision against which you had made local modifications, and '5001' is the latest revision on the server.

You can do one of three things to fix the conflict:

Once you are done fixing the conflict, you must inform svn of this by doing 'svn resolved <filename>'.

Then, you can commit any remaining changes in <filename> to the server with another 'svn commit', BUT... be sure to first run 'svn diff' on the file in question, to make sure you really know which changes you have added.

Subversion will safely ignore all files that have not been explicitly added to the repository; these include your .o files, editor backups, and so on. So it is not necessary to clean up those files before doing a 'svn commit'.

In summary, the recommended strategy for smooth interaction with the source tree is:

However, note that in subversion, unlike CVS, commits are atomic -- everything that happens in a single 'svn commit' command is stored as a single revision in the server, and bumps the global revision number only once. Therefore, it is sub-optimal (though not catastrophic) to use more than one 'svn commit' for a set of changes that really belong together in a single unit.
And so on. You can do an 'svn status' after each step to see which files remain to commit. Using this simple behavior, you will avoid committing changes you did not wish to commit.

2.3. Advanced svn techniques


To add a new file to the repository, you need to tell svn by doing:

        svn add newfile

this will schedule the file for addition; it will actually be added when you next commit.

To remove a file from the repository, do

        svn delete file

and it will be deleted when you next commit. Deleted files aren't really gone forever; they can still be retrieved by doing an 'svn checkout' with an older date or revision number.

To add a new subdirectory

        svn mkdir newdir
        svn commit -m"created newdir"

To remove a directory: unlike in CVS, this is actually possible in subversion. It's the same as deleting a file:

        svn delete somedir

To rename a file or directory: this is another thing that was not possible in CVS, but is trivial in subversion:

        svn move name1 name2

2.4. About svn properties

The most important thing about this section -- if you are going to commit code to the subversion repository, you should modify your ~/.subversion/config file so that the svn:keywords property gets set automatically on any files that you add to the repo. See the "svn:keywords" section below.

Subversion allows you to use arbitrarily-named properties to associate any user-specified content with versioned files (can be text, or other MIME types... so e.g. it's possible to put images into an svn property). Changes to properties are versioned just like changes to file contents.

The main subcommands associated with properties are the following:

	svn proplist -v <filename>
	svn propset <property-name> <property-value> <filename>
	svn propget <property-name> <filename>
	svn propedit <property-name> <filename>
	svn propdel <property-name> <filename>
In order to use 'svn propedit', you need to set at least one of the SVN_EDITOR, VISUAL, or EDITOR environment variables. If you haven't done that, you'll get an error like the following:
          svn: None of the environment variables SVN_EDITOR, VISUAL or
          EDITOR is set, and no 'editor-cmd' run-time configuration
          option was found
To set one of the env vars, just do
          export SVN_EDITOR="emacs -nw"    (in sh or bash)


          setenv SVN_EDITOR "emacs -nw"    (in csh or tcsh)
and if you want to make that change permanent, add the line somewhere in your ~/.bashrc or ~/.cshrc.

For example:

  cd /path/to/saliency
  svn propedit svn:ignore .  (brings up an emacs window for editing the property)
  svn proplist -v .
  -->  Properties on '.':
         svn:ignore : Makefile

(The svn:ignore property is equivalent to the old .cvsignore files.)

  svn proplist -v src/Image/Image.H
  -->  Properties on 'src/Image/Image.H':
         svn:keywords : Author Date Id Revision
         svn:eol-style : native
  svn proplist -v devscripts/extract_templates.tcl
  -->  Properties on 'devscripts/extract_templates.tcl':
         svn:executable : *
         svn:keywords : Author Date Id Revision
         svn:eol-style : native

Properties can have any name; for example you could associate copyright information with a file like this:

  svn propset copyright 'Copyright (2005)...' foofile

But there are also some 'magic' properties that start with the svn: prefix, and these have a special meaning to svn...


The full tree contains the following (you may not get all of this):

README        this file

src/          source code (historical note [2005-06-12]: the current src/
              directory was renamed from src3/, which itself was a
              descendent of earlier src2/ and src/ directories, all of
              which are available from earlier revisions of the
              subversion repository)

              as of 2005-06, we are currently undergoing a transition
              to split the source code into subdirectories consisting
              of logically related modules

notes/        various (mostly obsolete) documentation and research notes;
              don't worry too much about it, everything you need is in
              the present README;

devscripts/   shell scripts and other resources used in the course of
              maintaining the source code repository, see
              devscripts/README for more details

doc/          if you do 'make doc', then the resulting output will go
              in doc/html, doc/latex, doc/man, doc/rtf

bin/          executables; this is where the results of your compilation will
              be; everything that remains there after a 'make clean'
              is a shell or perl script that was written to do various
              batch processing;

params/       learning parameters for specialization of the system to one
              given visual search task (e.g., detecting traffic

tests/        a test suite consisting of blackbox and whitebox tests
              to verify the behavior of different components of our
              toolkit; to run, do 'cd tests; ./run_test_suite.tcl'
              (takes ~30 seconds on a 2.8GHz Xeon), or do 'cd tests;
              ./run_testlong_suite.tcl' (takes ~300 seconds)

matlab/       some Matlab code for the new version of the oriented filters
              (under development; to be used in conjunction with
              Roberto Manduchi's steerable-scalable filter
              optimization code).


4.1. Basic compilation

Use the following steps to build the executables from source:

  cd saliency         ### switch to the source code's directory

  ./configure --help  ### to see a list of possible configuration options

  ./configure         ### run the configure script with optional options
                      ### e.g. ./configure --prefix=/usr/local
                      ###  or  ./configure --enable-mmx --enable-sse
                      ###  or  ./configure --enable-mem-debug


  make test           ### optional test if you want to run the test suite

  make testlong       ### optional more stringent tests, takes long time

will compile the core executables (see below) and place them in the bin/ subdirectory of the installation location you chose with the configure script (default will be saliency/bin/ in your working saliency directory). You should have zero errors and zero warnings.

  make core           ### just a few core programs if you get some errors
                      ### about missing libs when you just type "make".
                      ### The core programs should not require
                      ### unusual or exotics libs (like FireWire, etc)

  make all            ### build everything

If you run 'make test', be aware that some of the tests unfortunately rely on the specific way that Intel processors do floating-point computations; so if you're running on a different processor, you may see some test failures due to this fact.

There are additional targets for make, which will require some nonstandard software packages to compile. These include:

  make                -> only builds the base executables (into saliency/bin/)
  make base           -> same as above
  make core           -> builds only core programs that don't need funny libs
  make bot            -> builds beobot-related executables
  make mex            -> builds Matlab MEX files
  make gtk            -> builds GTK-dependent executables
  make sdl            -> builds SDL-dependent executables
  make qt             -> builds Qt-dependent executables
  make mpeg           -> builds MPEG-related executables
  make tprogs         -> builds test programs
  make all            -> builds everything except for mex
  make xml            -> builds all Xerces-C XML library dependent stuff
  make doc            -> builds the doxygen documentation into ../doc
  make doc-latex      -> builds the doxygen LaTeX doc into ../doc

See for the current list of possible targets.

On SMP machines, you may use the provided "mk" script (in saliency/bin/) to enable parallel compilation. For example (assuming that saliency/bin/ is in your path), typing:

  mk all

on a dual-CPU machine will make everything, running two jobs in parallel throughout the build process. On an n-CPU machine it will run n compilation jobs in parallel. mk passes all its arguments to make, so it has the same syntax.

4.2. Architecture & Operating System Issues

We use an autoconf-controlled build system (see the 4.5. Using autoconf to control the build process section below) to detect and handle OS differences, but currently most things are heavily aimed at Linux, and may not work at all under different systems (although with the configure script you should at least expect some message hinting at the reason for the failure). Most of the code should compile on other Unix architectures, including Mac OS X (10.2 or greater) and the Cygwin environment under Windows.

If you run into problems building the software on a non-Linux system, you might try the following types of modifications:

If you are able to tweak things to get the software to build under a new system, please consider moving those tweaks into the template script and contributing your changes back to our subversion repository, so that others with similar systems can benefit from your changes.

4.2.1 Building under Linux

The operating system principally used for development of the iLab Neuromorphic Vision C++ Toolkit is Mandriva Linux.

Under Mandriva, make sure that you setup the following media sources:

Then you can use the uprmi system to download and install additional packages and their dependencies automatically.

As of Mandriva 2009.1, the following packages should be installed (for a 64-bit distribution, you can easily guess the corresponding names for 32-bit):

  urpmi emacs
  urpmi tcl-devel
  urpmi tk-devel
  urpmi popt-devel
  urpmi bzip2-devel
  urpmi ffmpeg-devel
  urpmi fftw-devel
  urpmi gsl-devel
  urpmi blas-devel
  urpmi lapack-devel
  urpmi avc1394-devel

  # pick one, as they conflict...
  urpmi dc1394-devel
  urpmi lib64dc1394_22-devel

  urpmi raw1394-utils
  urpmi SDL-devel
  urpmi SDL_gfx-devel
  urpmi SDL_mixer-devel
  urpmi SDL_image-devel
  urpmi openmpi
  urpmi gd-devel
  urpmi readline-devel
  urpmi termcap-devel
  urpmi qwt-devel
  urpmi ode-devel
  urpmi cwiimote-devel
  urpmi bluez-devel
  urpmi qt3-devel

  urpmi opencv-devel

  # and don't forget the essentials:
  urpmi xv
  urpmi mencoder
  urpmi mplayer
  urpmi zsh

  # needed for ice 3.3.0 (in
  urpmi db4.6
  urpmi lib64dbcxx4.6
  urpmi openssl (should be installed already)
  urpmi expat (should be installed already)
  rpm -Uvh ice-3.3.0-1.rhel5.noarch.rpm
  # In the command below, first run it without the --nodeps and make
  # sure you only get complaints about libcrypto, libssl and libdb,
  # all of which should be installed already, then
  rpm -Uvh --nodeps ice-c++-devel-3.3.0-1.rhel5.x86_64.rpm

Some packages do not have readily available RPMs for Mandriva. Look in saliency/packages for .spec files to make these RPMs for your system yourself.

4.2.2 Building under Mac OS X

In order to get the most use out of the toolkit under Mac OS X, you will need to do two things:

Here is an example of packages which I installed on a Leopard macbook, at svn revision 11488 of our code, using manual "fink install" commands (I said yes to install all dependencies when asked):

sdl sdl-image sdl-mixer
qt3 qt3-designer

then, if you allow yourself to install unstable fink packages from source, you can also get things like fftw3, a recent gcc compiler, etc

To list all installed Fink packages, do "fink list" from a terminal command line -- installed packages will be shown with a "i" at the beginning of the line. To give you some guidance in selecting packages for installation, one of our Mac OS X (10.3) systems has the following packages installed, and is able to build most of the programs in the toolkit:

anacron                 2.3-4            Periodic command scheduler
apr-ssl-shlibs          0.9.5-15         Apache Portable Runtime
apt                     0.5.4-37         Advanced front-end for dpkg
apt-shlibs              0.5.4-37         Advanced front-end for dpkg
arts                    1.1.4-22         KDE - analog realtime synthesizer
arts-shlibs             1.1.4-22         KDE - arts shared libraries
audiofile               0.2.6-10         Audio File Library *Developement Files*
audiofile-bin           0.2.6-10         Audio File Library *Binaries*
audiofile-shlibs        0.2.6-10         Audio File Library *Shared Libraries*
base-files              1.9.2-1          Directory infrastructure
bzip2                   1.0.2-12         Block-sorting file compressor
bzip2-dev               1.0.2-12         Developer files for bzip2 package
bzip2-shlibs            1.0.2-12         Shared libraries for bzip2 package
cctools                 525-1            [virtual package representing the developer tools]
cctools-extra           1:495-3          Extra software from cctools
cctools-single-module   1.0-1            [virtual package, your dev tools support -single_module]
ctan-other-misc         1.0-1            LaTeX macros from CTAN contrib/other/misc directory
cvs                     1.11.17-1        Version control system
cyrus-sasl2-shlibs      2.1.15-23        Cyrus Simple Authentication and Security Layer Library
daemonic                20010902-2       Interface to daemon init scripts
darwin                  7.9.0-1          [virtual package representing the kernel]
db42-ssl-shlibs         4.2.52-12        Shared Libraries for db42-ssl
debianutils             1.23-11          Misc. utilities specific to Debian (and Fink)
detex                   2.7-2            Filter to strip TeX commands from a .tex file
diffutils               2.8.1-1          Tools to compare files
dosunix                 1.0.13-1         Converts DOS text files to unix text format
dpkg                    1.10.21-202      The Debian package manager
emacs21                 21.2-26          Flexible real-time text editor, v21.2 with X11 support
emacsen-common          1.4.13-2         Common facilities for all emacsen
esound                  0.2.32-4         Enlightened Sound Daemon
esound-bin              0.2.32-4         Enlightened Sound Daemon
esound-common           0.2.32-4         Enlightened Sound Daemon
esound-shlibs           0.2.32-4         Enlightened Sound Daemon
expat-shlibs            1.95.7-1         C library for parsing XML
file                    3.41-1           Determine file type (magic)
fileutils               4.1-4            Common shell commands like ls, touch, chmod
fink                    0.21.3-1         The Fink package manager
fink-mirrors         Mirror infrastructure
fink-prebinding         0.7.1-2          Tools for enabling prebinding in Fink
gawk                    3.1.2-12         The Awk processing language, GNU edition
gcc2                    2.95.2-1         [virtual package representing the gcc 2.95.2 compiler]
gcc2.95                 2.95.2-1         [virtual package representing the gcc 2.95.2 compiler]
gcc3.1                  3.1-1            [virtual package representing the gcc 3.1 compiler]
gcc3.3                  3.3-1            [virtual package representing the gcc 3.3 compiler]
gdbm3-shlibs            1.8.3-1          Shared libraries for gdbm3 package
gettext                 0.10.40-18       Message localization support
gettext-bin             0.10.40-18       Executables for gettext package
gettext-dev             0.10.40-18       Developer files for gettext package
ghostscript             8.00-3           Interpreter for PostScript and PDF
ghostscript-fonts       6.0-3            Standard fonts for Ghostscript
gimp-print-shlibs       4.2.5-1          [virtual package representing Apple's install of Gimp Print]
glib                    1.2.10-18        Common C routines used by Gtk+ and other libs
glib-shlibs             1.2.10-18        Common C routines used by Gtk+ and other libs
glib2-shlibs            2.2.3-2          GTK+ - low-level core libraries
gmp-shlibs              4.1.2-11         Shared libraries for gmp package
gnupg                   1.2.4-1          Gnu privacy guard - A Free PGP replacement
grep                    2.4.2-3          Search text files for patterns
gtk+                    1.2.10-27        The Gimp Toolkit
gtk+-data               1.2.10-27        The Gimp Toolkit
gtk+-shlibs             1.2.10-27        The Gimp Toolkit
gzip                    1.2.4a-6         The gzip file compressor
ifmslide                0.45-4           Powerful presentations with PDFLaTeX and LaTeX
imagemagick             5.5.1-23         Image manipulation tools
kdebase3-ssl            3.1.4-21         KDE - base system
kdebase3-ssl-shlibs     3.1.4-21         KDE - base shared libraries
kdegames3-base          3.1.4-21         KDE - kdegames base package
kdegames3-common        3.1.4-21         KDE - game shared libraries
kdelibs3-ssl            3.1.4-22         KDE - essential libraries
kdelibs3-ssl-shlibs     3.1.4-22         KDE - essential shared libraries
kshisen                 3.1.4-21         KDE - Shisen-So - a Mah Jong-like game
latex2html              2002-2-1-1       Converts LaTeX documents to HTML
lcms-shlibs             1.12-1           Free color management engine in 100K
less                    381-10           Featureful text pager
lesstif-shlibs          1:0.93.18-1      Free implementation of OSF/Motif
libart2-shlibs          2.3.16-2         Library for high-performance 2D graphics
libiconv                1.9.1-11         Character set conversion library
libiconv-bin            1.9.1-11         Executables for libiconv package
libiconv-dev            1.9.1-11         Developer files for libiconv package
libjpeg                 6b-16            JPEG image format handling library
libjpeg-bin             6b-16            Executables for libjpeg package
libjpeg-shlibs          6b-16            Shared libraries for libjpeg package
libmad-shlibs           0.15.0b-2        MPEG audio decoder library
libogg-shlibs           1.1-1            Ogg bitstream shared libraries
libpng3                 1:1.2.5-2        PNG image format handling library
libpng3-shlibs          1:1.2.5-2        Shared libraries for libpng3 package
libtiff                 3.6.1-1          TIFF image format library and tools
libtiff-bin             3.6.1-1          Executables for libtiff package
libtiff-shlibs          3.6.1-1          Shared libraries for libtiff package
libvorbis0-shlibs       1.0.1-1          Vorbis audio codec shared libraries
libwww-bin              5.3.2-4          General-purpose Web API written in C for Unix and Windows
libwww-shlibs           5.3.2-4          General-purpose Web API written in C for Unix and Windows
libxml2-bin             2.6.7-2          XML parsing library, version 2
libxml2-shlibs          2.6.7-2          XML parsing library, version 2
libxslt-shlibs          1.1.4-3          XML stylsheet transformation shared libraries
m4                      1.4-6            Advanced macro processing language
macosx                  10.3.9-1         [virtual package representing the system]
make                    3.79.1-3         Software build tool
ncurses                 5.3-20031018-2   Full-screen ascii drawing library
ncurses-dev             5.3-20031018-2   Development files for ncurses package
ncurses-shlibs          5.3-20031018-2   Shared libraries for ncurses package
neon24-ssl-shlibs       0.24.7-11        HTTP/WebDAV client library with a C API
netpbm-bin              10.12-3          Graphics manipulation programs and libraries
netpbm10                10.12-3          Graphics manipulation programs and libraries
netpbm10-shlibs         10.12-3          Graphics manipulation programs and libraries
nget                    0.23-2           Downloader for binary news postings
openldap-ssl-shlibs     2.1.22-25        Shared libraries for LDAP
openslp-ssl-shlibs      1.0.9a-4         Shared Libraries for OpenSLP + SSL Support
openssh                 3.7.1p1-1        Secure shell (remote login) client and server
openssl                 0.9.6m-11        Secure Sockets Layer and general crypto library
openssl-shlibs          0.9.6m-11        Secure Sockets Layer and general crypto library
openssl097-shlibs       0.9.7d-1         Secure Sockets Layer and general crypto library
patch                   2.5.4-2          Utility to apply patches to source trees
pcre-shlibs             4.2-2            Perl Compatible Regular Expressions Library
pdfscreen               1.5-6            Resize LaTeX-produced pdf to fit on computer screen
popt                    1.7-3            Library for parsing command line options
popt-shlibs             1.7-3            Library for parsing command line options
ppower4                 0.9.4-1          Post-processor for PDF presentations created by pdf(La)TeX
python23                1:2.3.3-23       Interpreted, object-oriented language
python23-shlibs         1:2.3.3-23       Interpreted, object-oriented language
python23-socket         1:2.3.3-23       Socket plugin for python
python23-socket-ssl     1:2.3.3-23       Socket plugin for python (SSL version)
qt3                     3.2.2-12         Cross-Platform GUI application framework
qt3-designer            3.2.2-12         Cross-Platform GUI application framework
qt3-doc                 3.2.2-12         Cross-Platform GUI application framework
qt3-linguist            3.2.2-12         Cross-Platform GUI application framework
qt3-shlibs              3.2.2-12         Cross-Platform GUI application framework
readline                4.3-25           Comfortable terminal input library
readline-shlibs         4.3-25           Comfortable terminal input library
rsync                   2.5.5-1          Synchronize filesystems between hosts
sdl                     1.2.7-1          Cross-platform multimedia library
sdl-image               1.2.3-1          SDL image file loading library
sdl-image-shlibs        1.2.3-1          SDL image file loading library
sdl-mixer               1.2.5-12         SDL multi-channel audio mixer library
sdl-mixer-shlibs        1.2.5-12         SDL multi-channel audio mixer library
sdl-shlibs              1.2.7-1          Cross-platform multimedia library
sed                     4.0.5-1          The stream editor, GNU version
smpeg-shlibs            0.4.4-25         SDL MPEG Player Library
storable-pm             1.0.14-7         Placeholder for versioned Storable packages
swig-shlibs             1.3.20-11        Tool that connects C, C++ programs with high-level languages
system-java             1.4.2-1          [virtual package representing Java 1.4.2]
system-java13           1.3.1-1          [virtual package representing Java 1.3.1]
system-java13-dev       1.3.1-1          [virtual package representing Java 1.3.1 development headers]
system-java14           1.4.2-1          [virtual package representing Java 1.4.2]
system-java14-dev       1.4.2-1          [virtual package representing Java 1.4.2 development headers]
system-perl             5.8.1-1          [virtual package representing perl]
system-xfree86          2:4.3-2          [placeholder for user installed x11]
system-xfree86-dev      2:4.3-2          [placeholder for user installed x11 development tools]
system-xfree86-shlibs   2:4.3-2          [placeholder for user installed x11 shared libraries]
t1lib1-shlibs           1.3.1-2          Shared libs for generating Type 1 Font bitmaps
tar                     1.13.25-12       GNU tar - tape archiver
tcltk                   8.4.1-12         Tool Command Language and the Tk toolkit
tcltk-dev               8.4.1-12         Tool Command Language and the Tk toolkit
tcltk-shlibs            8.4.1-12         Tool Command Language and the Tk toolkit
tetex                   2.0.2-36         Complete distribution of the TeX typesetting system
tetex-base              2.0.2-36         Base programs for a teTeX installation
tetex-shlibs            2.0.2-36         Shared libraries for a teTeX installation
tetex-texmf             2.0.2-2          Main texmf tree for a teTeX installation
tex4ht                  20030412-10      TeX to Hypertext translator
texinfo                 4.7-11           Texinfo documentation system
texpower                0.0.8h-1         Creating dynamic online presentations with LaTeX
type1inst               0.6.1-3          Type 1 PostScript font installation utility
unrar                   3.3.5-21         RAR archive decoder
unzip                   5.50-14          Decompression compatible with pkunzip
wget                    1.8.2-2          Automatic web site retreiver
xfontpath               0.4-12           X font path manager for fink

Once you have the Xcode/Developer Tools and Fink installed, you can build the toolkit from a terminal window (/Applications/Utilities/ using the standard ./configure and make sequence shown in 4.1. Basic compilation.

4.2.3 Building under Windows in the Cygwin environment

In order to build the toolkit under Windows, you will need to install a Cygwin environment (, which provides a unix-style development environment.

To install cygwin, essentially you need to download the program setup.exe from, then run the setup.exe program which will guide you through selecting a set of packages to install. You can always go back and re-run setup.exe if you find you need to install additional packages later on, or if you want to upgrade your packages to the latest version.

To list all installed packages, do "cygcheck -c -d" from a cygwin bash shell. To give you some guidance in selecting packages for installation, one of our Windows systems has the following packages installed, and is able to build most of the programs in the toolkit:

_update-info-dir        00349-1
agetty                  2.1-1
alternatives            1.3.20a-2
apache                  1.3.33-2
apr                     0.9.7-1
apr-util                0.9.7-1
ash                     20040127-3
astyle                  1.15.3-3
atk                     1.9.1-1
atk-devel               1.9.1-1
atk-doc                 1.9.1-1
atk-runtime             1.9.1-1
autoconf                2.59-2
autoconf-devel          2.59-2
autoconf-stable         2.13-6
autoconf2.1             2.13-1
autoconf2.5             2.59-2
automake                1.7.9-2
automake-devel          1.9.2-2
automake-stable         1.4p6-3
automake1.4             1.4p6-2
automake1.9             1.9.6-1
autossh                 1.3-2
base-files              3.7-1
base-passwd             2.2-1
bash                    3.0-14
bc                      1.06-2
binutils                20050610-1
bison                   20030307-1
byacc                   1.9-1
bzip2                   1.0.3-1
c-client                2002e-3
c3270                   3.2.20-1
cabextract              1.1-1
ccache                  2.2-1
ccdoc                   0.8.41-2
ccrypt                  1.7-1
check                   0.9.1-1
chere                   0.6-3
chkconfig               1.2.24h-1
clamav                  0.87.1-1
clear                   1.0-2
clisp                   2.38-1
cmake                   2.2.3-2
cocom                   0.995-1
compface                1.5.2-1
coreutils               5.93-3
cpio                    2.6-5
cppunit                 1.9.14-1
cron                    3.0.1-19
crypt                   1.1-1
ctags                   5.5-4
curl                    7.15.1-1
curl-devel              7.15.1-1
cvs                     1.11.17-1
cygipc                  2.03-2
cygrunsrv               1.12-1
cygutils                1.2.9-1
cygwin                  1.5.19-4
cygwin-doc              1.4-3
cyrus-sasl              2.1.19-3
d                       1.2.0-1
ddd                     3.3.9-1
dejagnu                 20021217-2
desktop-file-utils      0.10-1
diffstat                1.40-1
diffutils               2.8.7-1
distcc                  2.18.3-1
doxygen                 1.4.6-1
dpkg                    1.10.4-2
e2fsimage               0.2.0-2
e2fsprogs               1.35-3
ed                      0.2-1
editrights              1.01-1
ELFIO                   1.0.2-1
emacs                   21.2-13
emacs-el                21.2-13
emacs-X11               21.2-13
esound                  0.2.36-1
expat                   1.95.8-1
expect                  20030128-1
fftw3                   3.0.1-2
fftw3-dev               3.0.1-2
fftw3-doc               3.0.1-2
file                    4.16-1
fileutils               4.1-3
findutils               4.2.27-1
flex                    2.5.4a-3
fltk                    1.1.4-2
fontconfig              2.2.2-1
freeglut                2.2.0-1
freetype2               2.1.9-1
gawk                    3.1.5-2
gcc                     3.4.4-1
gcc-ada                 3.4.4-1
gcc-core                3.4.4-1
gcc-g++                 3.4.4-1
gcc-g77                 3.4.4-1
gcc-gdc                 3.4.4-1
gcc-gpc                 3.3.3-3
gcc-java                3.4.4-1
gcc-mingw               20040810-1
gcc-mingw-ada           20050522-1
gcc-mingw-core          20050522-1
gcc-mingw-g++           20050522-1
gcc-mingw-g77           20050522-1
gcc-mingw-gdc           20050522-1
gcc-mingw-gpc           20040810-1
gcc-mingw-java          20050522-1
gcc-mingw-objc          20050522-1
gcc-objc                3.4.4-1
gdb                     20041228-3
gdbm                    1.8.3-7
gettext                 0.14.5-1
gettext-devel           0.14.5-1
ghostscript             8.15-2
ghostscript-base        8.15-2
ghostscript-x11         8.15-2
glib                    1.2.10-3
glib-devel              1.2.10-3
glib2                   2.6.6-2
glib2-devel             2.6.6-2
glib2-runtime           2.6.6-2
gmp                     4.1.4-2
gnome-common            2.12.0-1
gnome-keyring           0.4.6-1
gnome-mime-data         2.4.2-1
gnupg                   1.4.1-1
gperf                   2.7.2-1
grep                    2.5.1a-2
groff                   1.18.1-2
gtk+-devel              1.2.10-2
gtk-doc                 1.3-1
gtk2-x11                2.6.10-1
gtk2-x11-devel          2.6.10-1
gtk2-x11-doc            2.6.10-1
gtk2-x11-runtime        2.6.10-1
guile                   1.6.7-4
guile-devel             1.6.7-4
guile-doc               1.6.7-4
gzip                    1.3.5-1
help2man                1.35.1-1
indent                  2.2.9-1
inetutils               1.3.2-35
initscripts             0.9-1
intltool                0.33-1
ioperm                  0.4-1
irc                     20010101-3
jasper                  1.701.0-1
jbigkit                 1.5-3
jpeg                    6b-11
lablgtk2                2.4.0-2
lcms                    1.14-1
less                    381-1
lesstif                 0.93.94-2
lftp                    2.6.10-2
libapr0                 0.9.7-1
libaprutil0             0.9.7-1
libart_lgpl             1.4.2-3
libart_lgpl2            2.3.17-1
libaudiofile-devel      0.2.6-2
libaudiofile0           0.2.6-2
libbonobo2              2.10.1-1
libbonobo2-devel        2.10.1-1
libbonobo20             2.10.1-1
libbz2_1                1.0.3-1
libcharset1             1.9.2-2
libcroco06              0.6.0-1
libcurl3                7.15.1-1
libdb4.1                4.1.25-1
libdb4.2                4.2.52-1
libdb4.3                4.3.28-1
libesound-devel         0.2.36-1
libesound0              0.2.36-1
libfontconfig-devel     2.2.2-1
libfontconfig1          2.2.2-1
libfreetype2-devel      2.1.9-1
libfreetype26           2.1.9-1
libgcrypt               1.2.1-1
libgdbm                 1.8.0-5
libgdbm-devel           1.8.3-7
libgdbm3                1.8.3-3
libgdbm4                1.8.3-7
libgettextpo0           0.14.5-1
libglade2               2.5.1-1
libgnomecanvas2         2.10.2-1
libgpg-error            1.1-1
libGraphicsMagick-devel 1.0.6-1
libGraphicsMagick0      1.0.6-1
libguile12              1.6.7-4
libiconv                1.9.2-2
libiconv2               1.9.2-2
libIDL                  0.5.17-2
libIDL2                 0.8.6-1
libintl                 0.10.38-3
libintl1                0.10.40-1
libintl2                0.12.1-3
libintl3                0.14.5-1
libjpeg62               6b-11
libjpeg6b               6b-8
libkpathsea3            2.0.2-15
libkpathsea4            3.0.0-3
libltdl3                1.5.20-2
libltdl6                1.9f_20041024-1
libMagick-devel         6.0.4-1
libMagick6              6.0.4-1
libncurses-devel        5.4-4
libncurses5             5.2-1
libncurses6             5.2-8
libncurses7             5.3-4
libncurses8             5.4-4
libneon24               0.24.7-2
libneon25               0.25.5-1
libnetpbm10             10.30-1
libopenldap2            2.1.25-1
libopenldap2_2_7        2.2.26-2
libpcre                 4.1-2
libpcre0                6.3-1
libpng                  1.2.8-2
libpng12                1.2.8-2
libpng12-devel          1.2.8-2
libpopt0                1.6.4-4
libreadline4            4.1-2
libreadline5            4.3-5
libreadline6            5.1-1
libsasl2                2.1.19-3
libsasl2-devel          2.1.19-3
libsmi                  0.4.2-1
libtiff-devel           3.7.3-1
libtiff4                3.6.0-5
libtiff5                3.7.3-1
libtool                 1.5b-2
libtool-devel           1.5.10-2
libtool-stable          1.4.3-3
libtool1.5              1.5.20-2
libungif                4.1.4-1
libungif4               4.1.4-1
libwnck                 2.8.1-1
libXft                  2.1.6-1
libXft-devel            2.1.6-1
libXft1                 1.0.0-1
libXft2                 2.1.6-1
libxml2                 2.6.22-1
libxml2-devel           2.6.22-1
libxml2-python          2.6.22-1
libxslt                 1.1.15-2
lighttpd                1.4.9-1
login                   1.9-7
m4                      1.4.4-1
make                    3.80-1
man                     1.5p-1
mc                      4.6.1-2
mingw-runtime           3.9-2
minires                 1.00-1
minires-devel           1.00-1
mktemp                  1.5-3
more                    2.11o-2
mt                      2.3.1-1
nano                    1.2.2-1
nasm                    0.98.39-1
ncftp                   3.1.7-1
ncurses                 5.4-4
nedit                   5.5-1
neon                    0.25.5-1
netcat                  1.10-2
netpbm                  10.30-1
ocaml                   3.08.1-1
openjade                1.3.3-1
openldap                2.2.26-2
openldap-devel          2.2.26-2
OpenSP                  1.5.1-1
openssh                 4.2p1-1
openssl                 0.9.8a-1
openssl-devel           0.9.8a-1
openssl097              0.9.7i-1
ORBit2                  2.12.3-1
ORBit2-devel            2.12.3-1
pango                   1.8.1-1
pango-devel             1.8.1-1
pango-doc               1.8.1-1
pango-runtime           1.8.1-1
patch                   2.5.8-8
patchutils              0.2.31-1
pcre                    6.3-1
pcre-devel              6.3-1
pcre-doc                6.3-1
pdksh                   5.2.14-3
perl                    5.8.7-5
perl-libwin32           0.26-1
ping                    1.0-1
pkgconfig               0.17.2-2
popt                    1.6.4-4
postgresql              8.0.4-1
pr3270                  3.2.20-1
procps                  3.2.5-1
proftpd                 1.2.10-1
python                  2.4.1-1
qt3                     3.3.4-2
qt3-bin                 3.3.4-2
qt3-devel               3.3.4-2
qt3-doc                 3.3.4-2
rcs                     5.7-3
readline                5.1-1
rebase                  2.4.2-1
rpm                     4.1-2
rpm-build               4.1-1
rpm-doc                 4.1-1
rsync                   2.6.6-1
ruby                    1.8.4-1
run                     1.1.6-1
rxvt                    2.7.10-6
s3270                   3.2.20-1
sed                     4.1.4-1
setsid                  0.0-3
sh-utils                2.0.15-5
shared-mime-info        0.16-1
sharutils               4.5.3-1
shutdown                1.7-1
splint                  3.1.1-1
startup-notification    0.8-1
stunnel                 4.14-2
subversion              1.2.3-1
subversion-devel        1.2.3-1
suite3270               3.2.20-1
SWI-Prolog              5.2.6-1
swig                    1.3.25-1
sysvinit                2.84-4
t1lib                   5.1.0-1
tar                     1.15.1-3
tcl3270                 3.2.20-1
tcltk                   20030901-1
tcm                     2.20-1
tcp_wrappers            7.6-1
tcsh                    6.14.00-5
termcap                 20050421-1
terminfo                5.4_20041009-1
tetex-base              3.0.0-3
tetex-bin               3.0.0-3
tetex-devel             3.0.0-3
tetex-extra             3.0.0-3
texinfo                 4.8-1
TeXmacs                 1.0.6-1
textutils               2.0.21-2
time                    1.7-1
tin                     1.8.0-1
transfig                3.2.4-2
ttcp                    19980512-1
tzcode                  2005r-2
unison                  2.10.2-4
units                   1.77-1
unzip                   5.50-5
upx                     1.24-1
uw-imap                 2002e-3
vim                     6.4-4
w32api                  3.6-1
which                   1.7-1
whois                   4.7.11-1
WordNet                 2.0-1
X-startup-scripts       1.0.11-1
x3270                   3.2.20-1
Xaw3d                   1.5D-5
xemacs                  21.4.18-2
xemacs-emacs-common     21.4.18-2
xemacs-mule-sumo        2005-12-08-1
xemacs-sumo             2005-12-08-1
xemacs-tags             21.4.18-2
xerces-c-devel          2.5.0-1
XFree86-lib-compat      4.3.0-2
xinetd                  2.3.9-1
xpdf                    3.01-1
xterm                   202-1
zip                     2.3-6
zlib                    1.2.3-1
zsh                     4.2.6-1

Once you have a cygwin environment installed, you can build the toolkit from cygwin shell window using the standard ./configure and make sequence shown in 4.1. Basic compilation.

If you want to use any of the tcl-based apps (e.g., bin/invt), you may get an error like the following:

fatal initialization error (package 'Tcl'):
        Can't find a usable init.tcl in the following directories:

In that case, you need to set the TCL_LIBRARY environment variable, either on the command-line or in your ~/.bashrc, like so:

export TCL_LIBRARY="C:/cygwin/usr/share/tcl8.4"

4.3. Parallel code notes


You need to install PVM (Parallel Virtual Machine), a supercomputing message passing toolkit from Oak Ridge National Laboratory ( for 'pvision' and 'pvision-master' to compile. These two programs implement our model of bottom-up, saliency-based visual attention to run on a cluster of Linux machines connected through a high-speed network. These two programs are rather obsolete as better versions are now available that do not require PVM (pvisionTCP, pvisionTCP2, etc). If you do not wish to install PVM and to compile those two programs, don't try "make pvm".

Note that "make pvm" is implicitly called by "make all" so you will need to have PVM installed for "make all" to work.

4.4. IEEE-1394, SDL, ffmpeg, and other libs code notes

You will need the FireWire development libs for the IEEE1394 code to compile properly. On Mandrake 9.0, that means that you will need to install:


or later versions. That will allow the code to compile. To run it, you will in addition need to (as root):

        mknod -m 777 /dev/raw1394 c 171 0
        mkdir /dev/video1394
        mknod -m 777 /dev/video1394/0 c 171 16

        modprobe ohci1394
        modprobe raw1394
        modprobe video1394

You will need SDL development libs for the SDL-related code to compile, ffmpeg libs to the MPEG-related code, etc. It can be a long and frustrating process to find and install all the packages needed for "make all" to succeed. To help you, please see:

which contains the list of "exotic" packages we have installed on our machines so that "make all" will work.

4.5. Using autoconf to control the build process

4.5.1. If you are just going to build the software

The first thing you'll notice is that there is no Makefile in the subversion repository! This is because we have a configure script that checks various features of the build environment (i.e. your computer), and uses that information to generate a Makefile from a template. In addition, the configure script allows you to toggle additional switches controlling how the build will be done.

To see the list of available configuration options:

  ./configure --help

To run the configure script, just type ./configure. In general, if you don't specify any additional options to ./configure, you'll just get the right default behavior (for old-timers: similar to what we got previously from the old Makefile).

4.5.2. If you need to edit or add to the Makefile

Then the most important thing is DON'T EDIT THE FILE CALLED "Makefile"!!!

(Sorry to yell ;) but I find that that is the hardest part to remember of the entire autoconf process...)

Instead, you should edit "". This is the template file that ./configure uses to generate the Makefile. You'll find that looks very familiar. The main differences are:

      CXX := @CXX@
those are the lines where the configure script substitutes in the information it has garnered from its various checks. You won't need to worry about these unless you're also editing the configure script (then see step 3 below).

4.5.3. If you need to change the configure script

Then, just like the Makefile, DON'T EDIT THE FILE CALLED "configure"!!!

Instead, you should edit "". This file is processed by the autoconf program to generate the configure script.

Next most important, if you change "" and commit changes back to the subversion repository, then AFTERWARDS you MUST also run autoconf again, and then 'svn commit' the generated "configure" script. Here's why:

The file itself is an m4-macroized version of bourne shell code. So you can put any bourne shell code into, as long as its portable (i.e. shouldn't rely on bash-specific extensions). m4 is a macro language, just like the C preprocessor, except on steroids. The autoconf distribution basically consists of a large set of m4 macros that help you do useful tests.

You can read more about autoconf here:

Running autoconf is very simple. You just type "autoconf". It looks for a file named "" (or "", the older deprecated name for the script template), then does its m4-processing business, and writes the results to "configure". If all goes well, you'll see no messages.

Our template requires autoconf 2.53 or later. In particular, it won't work with autoconf 2.13, which is still the default in some distros, although recent distros should at least have autoconf 2.53 available.

BE WARNED: Just because autoconf runs successfully does not mean that your configure script will be syntactically correct bourne shell code. All the autoconf does is run the m4 processor over your template. Therefore you should always try running the generated configure script to make sure there are no shell script syntax errors, before you 'svn commit' changes to "".

Here's a quick overview of what happens in the file:

4.6. Qt3 code notes

We are developing GUI applications for the Toolkit and some of these programs will depend on Qt, a very easy-to-use library that has cross-platform support, includes a powerful visual Designer software, and significantly reduces the amount of code necessary to create user interfaces (less than Xlib or Gtk). Qt has extensive documentation and widespread popularity throughout the open source community. Qt is released under GPL and is available for download from

Also, if you are running KDE, you should have Qt already installed because KDE is a very well-known Qt-based desktop environment.

To code with Qt3, please follow these instructions:

Compile notes for Qt3 applications:

As an example you should look at the simple application test-Qt, which was created almost entirely in Qt Designer and required only about 25 additional lines of code to be written by the programmer. This should demonstrate both the power and the simplicity of Qt.

4.7. Qt4 code notes

The workflow for Qt4 is significantly different than that of Qt3, especially as regards the use of the Qt Designer. Have a look here for porting info:

Here is what you should do to create new Qt4 projects:

  make src/WhereTheUIfileIs/foo.ui.H

which will pass your .ui file through uic and obtain foo.ui.H; you should add it to the svn repo.

Have a look at src/Qt4/test-BeoChipQt.C for an example, with the associated files BeoChipMainForm.qt.C, BeoChipMainForm.qt.H, BeoChipMainForm.ui, and BeoChipMainForm.ui.H, for an example.



Video clips can be processed using ezvision just like series of image frames. Just pass --in=path/to/mymovie.mpg to use a movie for input; likewise you can save your output to movies by using --out=mpeg:path/to/outdir/.

6.1. Grabbing video

The easiest way to grab video is to use some Windoze machine equipped with a framegrabber. Typically, we try to grab at 30 frames/s in 640x480 resolution, RGB555 uncompressed mode. You may use other modes as well, like YV12, as supported by your framegrabber. As you grab, make sure that you don't have any dropped frames and that you grab uncompressed data. Indeed, compression (e.g., MPEG, DivX, etc.) will introduce artifacts, and that will have to be taken into account later when you attempt to process your data and interpret the results; that is, are the results you see due to the genuine contents of the video clip, or to the artifacts created by the compression process? That can be very important if your goal is, for example, to use our model to determine priority regions in a video clip and use those regions in a region-based video compression algorithm. If the data you use had already been compressed before, that will taint your results on how well your new compression algorithm is doing.

So, RGB555 640x480 30fps uncompressed AVI is usually the most desirable setting. If you have options to do deinterlacing, you may or may not want to use them (just make a note of what you did and be consistent over your collection of clips).

6.2. Converting video to .tbz files

The easiest way of doing batch processing on video data is to first convert (in a lossless manner) your movie file into a series of individual PPM frames, and then to create a tar archive with all the frames in it, and to compress this archive using the bzip2 program. Once you have a .tbz file in this format, we have a number of scripts that will be able to run the attention model on those files. You must create your .tbz exactly as described below for these scripts to work.

To convert from a movie to .tbz, use the script in saliency/bin/. The script accepts any input video format that 'mplayer' can deal with: movie1.avi movie2.mpg

will convert all three movies to .tbz format, yielding movie1.tbz, movie2.tbz and movie3.tbz. There are additional options that accepts; have a look at the script itself to see a description of the usage, in the comment block at the top of the script.

If you want to create your .tbz files manually, you can certainly do that too. The .tbz files should contain a series of frames with the file names:


be sure to have a six-digit number, to start at frame zero, and to have no gap in the number sequence. Follow this naming convention, as it is required by the scripts that process .tbz files. Then tar and compress all the frames, such that your tar file contains no directory/subdirectory information (i.e., when it is untarred, the extracted frames should go into the current directory). For example:

        tar cvf - frame*.ppm | bzip2 -9 > mymovie.tbz

or, if you have so many frames that your shell complains that "frame*.ppm" has too many files, you can also use:

        tar cvf - . | bzip2 -9 > mymovie.tbz

in which case your archive will contain files ./frame000000.ppm, ./frame000001.ppm, etc and the leading ./ is okay (note that .tbz files created with this manner will have an additional entry for just "./", so be sure that you know that if you are trying to count the number of frames in a movie by listing the files the .tbz archive contains).

6.3. Processing a .tbz file

To process a .tbz file through ezvision, use the script in saliency/bin/; typically: /path/to/movie.tbz

will unpack the .tbz, process the frames through ezvision, and compress the results into a .mpg file. There are many options that accepts; have a look at the script itself to see a description of the usage, in the comment block at the top of the script. In particular, you can decide on the output format (mpeg, quicktime, divx, tbz, etc) and pass additional options to ezvision too. There are also specialized versions of that are just shorthands which call with a bunch of preset options; for example,,, etc

For to work, you need to have ezvision and several other programs installed and in your path (mpeg_encode, mencoder, etc). Have a look at the script for details.


Before you run parallel code (such as pvisionTCP), make sure that you master the Beowulf administration tools, such as 'brsh,' so that you cleanup after yourself when you are done with the beowulf. For example, if you have started a bunch of pvisionTCP processes, be sure to execute:

        brsh killall -9 pvisionTCP

when you are done. For brsh to work, you need to have a .rhosts file with: itti itti itti itti itti itti itti itti itti itti itti itti itti itti itti itti itti itti itti itti itti itti itti itti itti

in your home directory, except that you replace "itti" by your login name and make sure that your own computer's name also is in the list. Then, brsh will execute the command passed as argument on every node in the beowulf; for example:

        brsh ps aux       #  shows you all processes
        brsh df -h        #  shows you all disk space

Also check out the real time CPU and network load graphs at


Documentation is automatically extracted from the source code and published on the web at:

It is also available in PDF or RTF format.

Please document your code using the doxygen syntax (see Doxygen will extract special comments from your code and organize them along with the class names and methods into some nice web pages. Regular comments will not be used by doxygen, so feel free to use them a lot inside your code. So the idea is that all regular comments are only for people editing the code, and a few special comments are provided for people just wanting to use your classes but not look at the code in detail. So the special comments explain what the class does and what each method does. Typically this means:


Please follow these guidelines when writing new code:

  byte          // for a 8-bit unsigned integer number
  int16         // for a 16-bit signed integer number
  int32         // for a 32-bit signed integer number
  float         // for a 32-bit floating point number
  double        // for a 64-bit floating point number

If you could tolerate that your variable be either a 32 or 64-bit int, then use int.

        void MyClass::getInfo(const int32 zz, float& result1,
                              byte& result2) const;

is a method with 1 read-only parameter, 2 read-write parameters, and which does not modify the internal data members of MyClass;

// in myClass.C:
Image<float> im(100, 100);


// in myClass.H:
// image size:
const int IMWIDTH = 100;
const int IMHEIGHT = 100;

// in myClass.C:
Image<float> im(IMWIDTH, IMHEIGHT);

and try to avoid hardcoded numbers in any case! Use ModelParam<T> parameters instead (see ModelParam.H). Of course do not abuse of that rule: if you implement some math functions you will have lots of numbers; so use your judgment to decide when to define a constant; typically you will do it if you use it several times in several different methods, but not if you just use it once in one method (unless you consider that it is a tunable parameter of your code).


Have a look at the papers and at section 1 for general information and a brief description of what the various classes do. Then check out the online documentation. Then look at the code itself.

Use the online documentation (see above). It is clickable, so that each time you encounter an object type that you don't know, you can just click on it to instantly discover what it is.

A good order in which to get acquainted with the various classes is as follows (look at both the .H and .C) -- NOTE: the list below may be obsolete; the online documentation is the only up-to-date reference (updated nightly):

10.1. Visual attention model

10.2. Contour integration model

10.3. Grabbing & displaying images

10.4. Parallel computing

10.5. Low-level details of parallel computing (should not be needed)

10.6. Audio

10.7. Misc hardware drivers

10.8. Psychophysics displays

Generated on Sun May 8 08:43:02 2011 for iLab Neuromorphic Vision Toolkit by  doxygen 1.6.3