
Description:
****************************************************************************************
This code allow tracking several objects in image sequences


See:
N. Papadakis and A. Bugeau. Tracking with occlusions via graph cuts. IEEE Transactions on Pattern Analysis and Machine Intelligence. Vol 33(1): 144-157, 2011
PAMI.pdf


****************************************************************************************
compilation: 
****************************************************************************************


1)Compile first maxflow (with make in the directory lib/libGC)

2)Then, to compile the main program, just do:  make linux in the src directory



3) If using linux instead of mac), change functions_tracking.cpp and set the Haris executable to fast-Linux-i686 (instead of fast-Darwin-ppc)

Need Megawave functions for manual intialization: ascii2fimage and ll_smallest

****************************************************************************************
Parameters:
****************************************************************************************


Input/Output:
-------------


-seq  : Path of Image data, ex: Image_  
-type : Type of Image data, ex: png
-es   : Number of Images, ex: 4
-ba   : Numerotation basis, ex: 3
-i    : Numero of first image, ex: 0
-t    : Number of images, ex: 10

These parameters correspond to image data with names: Image_000.png, Image_001.png, ..., Image_010.png


-res  : Directory of results
-occ  : Display the occulted part of the objects for output writtinf (1) or only visible part (0)

-init    : Load initialization masks (1), or select manually  curves (0)
-seqin   : Path of initialization masks, ex: Init_
-initype : Type of initialization masks images, ex: pgm

These parameters correspond to the following given initialization masks for two objects:

Init_1.png, Init_2.png

Tracking information:
---------------------

-rep : Continue computation (to use saved manual initialization)
-nb  : Number of tracked objects
-upd : Frequency of histogram update. Standard value: 10

Model parameters:   (IMPORTANT PARAMETERS)
------------------------------------------

The energy is composed of 6 terms, so there is 5 parameters to tune.

-b  : Disparition coefficient. Standard value: 0.4
-a  : Occlusion coefficient. Standard value: 1.0
-g  : Disocclusion/apparition coefficient. Standard value: 0.1


The parameter -a represents the weight of occluded area. If set to infinity, the model will only consider visible areas.
The parameters -g (resp. -b) denotes the appearing (resp. disappearing) areas, if set to infinity, the object size can only decrease (resp. increase).
These three parameters usually take value in the range $[0,3]$.

When the velocity of the object is high, the prediction can be bad, so the appearance parameter -g should be small to allow areas far from the prediction to be segmented.
Another important point is the difference between the values of -g and -b. If -b is bigger than -a, then the model will encourage the disappearance of objects with respect to their occlusions.

One simple example for non deformable objects can finally be detailed. In this case the appearance and disappearance parameters -b and -g can be set to infinity and the object size will remain constant.
The position of the object is then only determined by the prediction that varies with respect to the last parameter -a. If the occlusion parameter -a is also infinite, the object will always be fully visible so the motion model will determine the tracking and no corrections based on the image intensity will be done. In case of occlusions, the tracking of the objects will be lost. On the other hand, if -a is small enough, the model will consider occluded areas and the motion will be computed only on the visible parts, allowing the process to deal with occlusions.


-a2 : Staying in occlusion coefficient. Standard value: 0.0   

This terms was not there when writting the paper. It encourages occluded pixels to stay as occluded, disminuing the occlusion cost -a for the already occluded pixels. It should be \in [0, a].

-r  : Regularization coefficient for visible area.  Standard value: 20.0
-sg : Image gradient variance for visible regularization.  Standard value: 80.0

The regularization weight between two neighbor pixels i and j will be: 1+r exp(-|I(i)-I(j)|/sg)


-r2 : Regularization coefficient for good and bad predictions. Standard value: 1.0



Velocity parameters:
-------------------


-pp   : Exponential influence of difference between measured velocity and object velocity. Standard value: 3
-dyn  : Use a consistent dynamic? 1: yes, 0, no. 
-fil  : Filtering of the motion estimation? 1: yes, 0, no. 
-conf : Confidance in dynamic \in [0;1]. Standard value: 0.5
-si   : Velocity variance for objects. Standard value: 5.0

Harris and KLT parameters:
--------------------------

-n         : Number of scale for KLT computation. Standard value 3
-w         : Size of search windows for KLT. Standard value 5

These  parameter should be increase if the motion is large to reach a resolution where corresponding points in successive images are within a window of size (2w+1)x(2w+1). 
Otherwise, the KLT won't estimate good motion vector.
Another possibility is to increase w value but it slows the process


-s         : Maximum gradient thresholdfor KLT. Standard value: 200.0
-bord      : Bordure in pixel for Harris. Standard value: 10.0
-bord_opt  : Bordure in pixel inside the visible mask for KLT. Standard value: 0.0





****************************************************************************************
Examples to test:
****************************************************************************************



cd bin
./tracking -seq ../data/Wakeboarder/Image_0 -i 1 -t 246  -seqin ../data/Wakeboarder/Init_000 -res ../Results/Wakeboarder  -h  -g 0.1 -r 10.0 -a2 0.0 -a 0.3 -b 0.5  

./tracking -seq ../data/PETS/Image_0 -seqin ../data/PETS/Init_ -nb 4 -i 122 -t 110  -a 1.5 -b 3.0 -g 1.  -r 5.0 -res ../Results/PETS -a2 0.6  -h 
