
STEREO_DISPARITY
***************************************************************************************************************************
***************************************************************************************************************************

This program shows an example of a StereoRig class and how stereo images can be rectified and undistorted by means of 
OpenCV functions. In addition, a dense disparity map is also computed by means of the OpenCV disparity block 
matching algorithm. The StereoRig class has several methods that can be of interest for stereo based applications, such
as: uncertainty estimation, disparity map representation with different color spaces, etc.

It accepts images from a rectified or unrectified stereo pair.

***************************************************************************************************************************
***************************************************************************************************************************

Library Dependencies Installation
---------------------------------------------------------------------------------------------------------------------------
The program only requires that OpenCV is correctly installed in your computer.
Latest OpenCV libraries are very easy to install if you have cmake. If not, I strongly recommend you to install cmake. That
will make your life much easier.

In addition, the library also requires TooN, which is a header library for linear algebra.

The TooN library is written by members of the Cambridge Machine Intelligence lab and are licensed under the LGPL.

The latest version of TooN can be obtained via CVS and ssh:
# export CVS_RSH=ssh
# cvs -z3 -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/toon co TooN

Then, follow the instructions to install TooN. Since it is a bunch of header files you should have no problem about 
installing TooN ok.

The code was developed on x86/x86-64 Linux.

***************************************************************************************************************************
***************************************************************************************************************************

Compiling the program
---------------------------------------------------------------------------------------------------------------------------
In the program folder please type:
cmake .
make

The CMakeLists.txt file only has dependencies with respect to OpenCV and TooN 
libraries. You should edit this file in case your libraries are not installed in
common default paths.

***************************************************************************************************************************
***************************************************************************************************************************

Running the program
---------------------------------------------------------------------------------------------------------------------------
The program accepts command line arguments. By default, the input arguments are:
./stereo_disparity /left_images_path /right_images_path calibration_file.txt

stereo_disparity is the name of the program.

/left_images_path and /right_images_path are the folders that contain the images for
the left and right views of the stereo rig. By default, the base name of these images
is image%05d.pgm. But of course, you can change that in main.cpp and use a different
name

calibration_file.txt is a txt file that contains all the parameters of the stereo rig calibration.
Below, I explain in more detail the format of the calibration file

***************************************************************************************************************************
***************************************************************************************************************************

Format of the calibration file
---------------------------------------------------------------------------------------------------------------------------
The calibration file comprises of several rows with information regarding the stereo rig.
You can check the calibration_file.txt example that is included in the folder. You can obtain the calibration parameters of
the stereo rig using OpenCV or other calibration tools such as Matlab camera calibration toolbox.

Notice that if the calibration parameters correspond the a rectified and undistorted stereo rig, the camera intrinsics are
the same for the left and right cameras. In addition, the rotation matrix is the identity, and the translation vector just
contains a non-zero value.

If the stereo images are already rectified, please set the flag IS_RECTIFIED = true in the global_types.h file.
Otherwise, set this flag to false.

The first row is a description about the calibration and the stereo rig. It is just for informative purposes.

The rest of the rows have the following meaning:
Image Width
Image Height
Left Camera Fx 
Left Camera Fy
Left Camera u0
Left Camera v0
Right Camera Fx 
Right Camera Fy
Right Camera u0
Right Camera v0
R11
R12
R13
R21
R22
R23
R31
R32
R33
Tx
Ty
Tz
Left kc1
Left kc2
Left kc3
Left kc4
Right kc1
Right kc2
Right kc3
Right kc4

kc is a vector that contains the radial and tangential distortion parameters. For more information, please check:
http://www.vision.caltech.edu/bouguetj/calib_doc/htmls/parameters.html

***************************************************************************************************************************
***************************************************************************************************************************

Usage Example
---------------------------------------------------------------------------------------------------------------------------
In the code sample you have a folder named input_images that contains a sample of a recorded stereo sequence. Then, from 
the command line you can type:

./stereo_disparity ./input_images/left/ ./input_images/right/ ./calibration_file.txt 

And you should be able to observe three images: the rectified left and right images and the dense disparity map image

If you want to save the output images, please set the flag SAVE_OUPUT_IMAGES to true in the global_types.h file. In this
case, the rectified and disparity images will be saved in the out_images folder

You can change the main parameters of the stereo disparity block matching algorithm by modyfing the file global_types.h
Basically, these are the default parameters for the disparity computation:
const int PREFILTER_SIZE = 11;
const int PREFILTER_CAP = 31;
const int SAD_WINDOW_SIZE = 15;
const int MIN_DISPARITY = 0;
const int MAX_DISPARITY = 32*2;
const int UNIQUENESS_RATIO = 10;
const int TEXTURE_THRESHOLD = 10;
const int SPECKLE_WINDOW_SIZE = 0;
const int SPECKLE_RANGE = 15;

Those parameters at the beginning of the StereoRig.cpp file, allow to consider different noise measurements for the
stereo uncertainty computation and different color maps for the disparity representation
const static double noise_std1 = 1.0; // Left image measurement errors 
const static double noise_std2 = 1.0; // Right image measurement erros
const int colormap = 4; // 0->gray, 1->autumn, 2->cool, 3->copper, 4->hot, 5->spring, 6->summer, 7->winter	
const bool use_log = 1; // 0->Linear scale for disparity visualization, 1-> Logarithmic scale

***************************************************************************************************************************
***************************************************************************************************************************

More Info
---------------------------------------------------------------------------------------------------------------------------
Name: stereo_disparity
Author: Pablo F. Alcantarilla
Date: 02 / 11 / 2011

For further questions, please contact me at:
Contact: pablo.alcantarilla@depeca.uah.es



