SaliencyToolbox 2.2 - documentation


Installation
Quick Start
Mex file compilation

m-file documentation
C++ source documentation
Bug reports

License
official SaliencyToolbox web page

Installation

Unpacking the code creates a directory structure under SaliencyToolbox. Simply add the SaliencyToolbox directory including its subdirectories to your Matlab path:

addpath(genpath('<your SaliencyToolbox path>'));

If you want to have access to the toolbox everytime you start Matlab, then place the above command into your startup.m file, which is located in ~/matlab/startup.m for Linux, Mac OS X and other Unix flavors, and in the "Start in" directory for your Matlab desktop shortcut under MS Windows.


Quick Start

Okay, now that installation was so simple, you have some time left for a test drive, right? Version 2.0 sports a new graphical user interface (GUI) version of the saliency code. In Matlab, change to the SaliencyToolbox directory, then type:

guiSaliency('img/balloons.png');

Hit "Start" to start the saliency computation. Everything else should be fairly intuitive.

There is also the command-line version of the program:

runSaliency('img/balloons.png');

After a few moments, you should see four figure windows with various intermediate results, and in the Matlab window you will see details about the most salient location, which is also marked in the image. You can now hit Return to go to the next most salient location and so forth. To quit, simply enter 'q' and press Return.

If you want to compute the saliency maps and fixations for several images in batch mode, then check out batchSaliency.

If you receive a fatal error "MEX file xxx could not be found." and you are sure that you have set the paths correctly, then you might need to compile the mex files for your system.

The SaliencyToolbox/img directory contains a few example images for you to play with. The guiSaliency, runSaliency, and batchSaliency functions also takes an optional second argument, a saliencyParams structure. Start exploring the documentation for runSaliency, batchSaliency, defaultSaliencyParams, and dataStructures to get an idea of what is happening. It may be a good idea to make a copy of runSaliency and start dissecting and adapting it for your purpose.

If you want to get more feedback on what is happening at each time step, then try switching debugging messages on in the GUI version. In the command-line version, you can do the following:

declareGlobal;
DEBUG_FID = 1;
runSaliency('img/balloons.png');

See the documentations for initializeGlobal, declareGlobal, and debugMsg for what is happening here.


Compilation

Most users don't need to compile the mex files. Binaries for the most common architectures are included with the toolbox. Compilation may become necessary, if the binaries for your operating system and CPU combination are not in the SaliencyToolbox/bin directory yet. In this case, please send me a note once you have successfully compiled your mex files, and I may include the binaries for your system in the next release. Compilation is also necessary, of course, if you modify the C++ code of the mex files.

 

Linux, Mac OS X, other Unix flavors

You need the GNU gcc compiler, version 3.2.3, if possible. The compiler should be named "gcc-3" and its C++ equivalent "g++-3". Create an alias or link if your compiler is called differently. Check by typing:

gcc-3 --version

The 3.3 variants in Fedora Core and OS X work as well. Gcc 3.4.x definitely does NOT work for mex files, they won't link correctly at Matlab runtime because of a known compiler bug. Gcc versions before 3.0 won't work either, because they don't fully implement the standard template library. Gcc 4 seems to work, at least on some architectures. Please let me know if you have some other experiences with the various compiler versions.

The mex shell script that comes with Matlab needs to be in your executable path. The mex scripts of Matlab releases 13 and earlier don't understand the '-cxx' option to signal C++ code, release 14 requires it. Hence, if your Matlab version is R13 or older, you need to edit two lines around line 23 of your SaliencyToolbox/src/Makefile to this:

#MEXFLAGS := -cxx
MEXFLAGS :=

With all this out of the way, you can now change into directory SaliencyToolbox/src and type:

make

This will create the binaries for your operating system in SaliencyToolbox/bin. If you get a message saying that nothing needs to be done, but you are sure that you need to recompile the code, then use this command:

make clean all


Microsoft Windows (32 bit)

To compile the code under Windows, you will need to install MinGW (minimalistic GNU for Windows) and MSYS (Minimalistic SYStem). This is free software in the public domain. Follow these steps to install a working environment for compiling mex files (all downloads are available at http://www.mingw.org/old/download.shtml):

  1. Download mingw-runtime-3.8.tar.gz and unpack into a new folder c:\mingw.
  2. Download binutils-2.15.91-20040904-1.tar.gz and unpack into c:\mingw.
  3. Download gcc-3.2.3-20030504-1.tar.gz and unpack into c:\mingw. If you are asked if you wish to overwrite some existing files, click on 'yes to all'.
  4. Download w32api-3.3.tar.gz and unpack into c:\mingw.
  5. Download MSYS-1.0.10.exe and run the installer, install into c:\msys.
  6. During the postinstall, answer y on the question if you have mingw, then enter /c/mingw as its installation path.

(Note: Of course, you can also choose different installation paths and more recent packages. However, I have tested the above configuration, and it works for sure.)

Start you newly installed Msys environment, which will give you a Unix-like shell, and change the directory to SaliencyToolbox/src. Make sure that the global environment variable MATLABROOT is set to the Matlab installation directory, either by adding it to your Windows environment variables (My Computer, right click, properties, Advanced, Environment Variables, New), or by typing in Msys:

export MATLABROOT="C:\\Program Files\\MATLAB\\R2008a"

You can also place this line into your .profile file in your Msys home directory. Now you can compile the code by typing:

make

which creates the Windows .mexw32 files in SaliencyToolbox/bin. If you get a message saying that nothing needs to be done, but you are sure that you need to recompile the code, use this command:

make clean all

Note for older Matlab versions: The mex files for 32 bit Windows have the extension mexw32. Matlab versions before 7.1 (R14SP3) used the extension dll. The toolbox recognizes this and automatically renames the mexw32 files into dll files on older Matlab versions during the first call to initializeGlobal.

 

Microsoft Vista, 64 bit

Unfortunately, there is so far no POSIX compatible compilation environment for 64 bit Vista. Mostafa Jabarouti Moghaddam has managed to compile the mex routines for 64 bit Vista using Visual Studio. With his permission, I am including the compiled mex files (with the extension .mexw64) in the distribution. Here are Mostafa's notes on how to do the compilation:

CompileWin64.pdf - a description of the compilation process
saliencyToolboxMex.rar - the compilation environment and auxiliary files
mexw64.rar - the compiled mexw64 files

Thanks, Mostafa!

 

Generating the documentation

In order to re-create the documentation for the C++ source code for the mex files, you need to have doxygen and graphviz (for the dot command) installed and in your executable path. Then change to the SaliencyToolbox/mex directory and type:

make doc

This will create the documentation in SaliencyToolbox/doc/mexdoc.

The documentation for the m-files is generated from within Matlab, using the m2html toolbox. Make sure that m2html is in your Matlab path, then change to the SaliencyToolbox base directory and type:

STBgenerateDoc;

And you'll have the documentation for the m-files in SaliencyToolbox/doc/mdoc.


Bug reports

Please submit any bugs, feature requests and support requests to:

walther@saliencytoolbox.net


SaliencyToolbox homepage
last modified: 25 September, 2008