readme.txt

mean-shift. pointer sample

This package provides a C++ implementation of the algorithm described
in the following article:

A Topological Approach to Hierarchical Segmentation using Mean Shift
Sylvain Paris and Fr閐o Durand
Proceedings of the IEEE conference on Computer Vision and Pattern Recognition
2007
http://people.csail.mit.edu/sparis/#cvpr07


Most of the code is released under the MIT license. Some old files are
under the BSD license.

The code have been developed and tested under Linux using GCC. We
provide a simple makefile that compiles everything. No optimization
options beyond "-O3" have been included to prevent portability
problems. We use the GNU Scientific Library to compute PCA:
http://www.gnu.org/software/gsl/






* How to use the program?
*************************

It is a command line program with following arguments:

mean_shift file_name range_sigma time_sigma space_sigma persistence_threshold

- file_name: To segment images, provide the file name of the input
  picture. Only PPM files are supported. To segment a video, provide
  the name of a file with the following syntax:
  . the first line contains the path to the frame files
    (e.g. /home/user/movie/)
  . the following lines contain the file names of the frames, one name
    per line, only PPM format (e.g. frame000.ppm)

- range_sigma: The Gaussian parameter used on the color axes. We use
  the CIE-Lab color space. The L values range between 0 and 100. Try
  values between 5 and 10 for this parameter.

- time_sigma: The Gaussian parameter used on the time axis. Available
  only when segmenting videos. Try values between 5 and 15 for this parameter.

- space_sigma: The Gaussian parameter used on the x and y axes. Try
  values between 4 and 256 for this parameter.

- persistence_threshold: See our article for this parameter. Try
  values between 0 and 5.


  
  
The program prints statistics and timings in the terminal. It also
creates the following files:

- partial.ppm: The segmentation obtained only by classifying the grid
  nodes. Black pixels are still unlabeled.

- full.ppm: The final segmentation with color-coded clusters.

- boundaries.ppm: The boundaries of the final segmentation. The
  boundary persistence is coded with gray values (dark is low, bright
  is high).




    

* How to set up the program?
****************************

Before compiling the program, you can choose between:
- segmenting images or videos,
- comparing intensities or CIE-Lab colors,
- using a regular array, a sparse array, or mixed strategy,
- and applying PCA or not.

These settings are available though the "config.h" file. Here are a
few notes:

- To ensure a strict hierarchical cluster structure, you need to
  comment lines 62 and 71.

- To get the full hierarchy up to the persistence level specified on
  the command line, uncomment line 75. The cluster IDs are coded on
  three bytes: red-green-blue. The finest level is output. The file
  "hierarchy.txt" indicates in which order to merge the segments,
  e.g. "3 --> 10" means "cluster 3 has to be merged with cluster 10,
  3 disappears".

- If your feature space is large, choose a sparse data structure
  (line 52) and consider using PCA (lines 57 and 58).