%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                               READ ME
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% INTRODUCTION

This is the code for the article "Discriminative Clustering for Image 
Co-segmentation" by Armand Joulin, Francis Bach and Jean Ponce.

We aim to segment a given set of images containing objects from the same 
category, simultanously and without prior information.

This is a vanilla version, so if you find a bug, contact Armand Joulin at 
armand.joulin@ens.fr.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% REFERENCES

If you use this code, please refer to:

- Discriminative Clustering for Image Co-segmentation. A. Joulin, 
  F. Bach and J. Ponce. CVPR 2010.
- Low-rank optimization for semidefinite convex problems. M. Journ\'ee, 
  F. Bach, P.-A. Absil and R. Sepulchre. arXiv:0807.4423v1, 2008.
- Diffrac: a discriminative and flexible framework for clustering. F. Bach 
and Z. Harchaoui. NIPS 2007.

___________________________________________________________________________

if you generate sift using our code (in ./feature/generate_sift_descriptors),
please refer to:

-Beyond Bags of Features: Spatial Pyramid Matching for Recognizing Natural 
Scene Categories. S. Lazebnik, C. Schmid, and J. Ponce. CVPR 2006

___________________________________________________________________________

If you use our graphcut (in ./GCmet1.3 -- and use in function 
plot_warm_superpixel.m), please refer to:

-Efficient Approximate Energy Minimization via Graph Cuts. Y. Boykov,
O. Veksler and R. Zabih. PAMI 2001
-What Energy Functions can be Minimized via Graph Cuts?. V. Kolmogorov 
and R. Zabih. PAMI 2004.
-An Experimental Comparison of Min-Cut/Max-Flow Algorithms for Energy 
Minimization in Vision. Y. Boykov and V. Kolmogorov. PAMI 2004.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% HOW TO USE IT?

___________________________________________________________________________

% EXAMPLE

Launch main_example.m for a simple example.
___________________________________________________________________________

% PARAMETERS

All fixed parameters are stored in the file parameters.m (and its subfiles).
Check path_parameters.m to change the input/output pathes...
___________________________________________________________________________

% INPUTS

    % input format

        If you want to use our code on a new set of images (let say "face"), 
you have to create a folder "face/" in the input folder (default: "./input/").

This folder must contain the images. Each image must be named depending on 
the class ("face_001.jpg', "face_002.jpg"...).

The folder "face/" must also contain a folder "descriptor/" in which you 
store your features (check "path_parameters.m" to change the path). 
This folder must contain 3 types of files:
    -a ".mat", called ${name_of_the image}_${descriptor}.mat (ex: 
     "face_001_sift.mat). It contains a structure with fields "x","y" and 
     "data". "x","y" contains the position of each descriptor and "data" 
     the descriptors.
    - the other two files (${name_of_the image}_${descriptor}_data and 
      ${name_of_the image}_${descriptor}_pos) contain the same info as in 
      data and x,y but not in a .mat
    => IMPORTANT: to generate these two files use the function
                  routine_convert_mat.m

The folder "face/" must also contain a folder "superpixel/" containing your
segmentation (we used watershed superpixel which is not a freeware --- if
you need the segmentation used in our paper, they will be soon on Armand
Joulin's page. Meanwhile pleae contact Armand Joulin at armand.joulin@ens.fr).
This folder must contain two types of file:
    -the oversegmented image (named ${name_of_the_image}_mos.png) --- this 
     file is not useful for our code.
    -a file ${name_of_the_image}_Seg.mat in which there are the correspondances 
     between pixels and superpixels. If we give the number s 
     to a certain superpixel (s is an integer >=1), ${name_of_the_image}_Seg.mat
     is a matrix with the same size as the image (for "face1.jpg", it is a 
     128x128 matrix) where each pixel (i,j) in the superpixel s has a value 
     s in this matrix.

Finally the folder "face/" must contains a folder "desc_superpixel" containing 
in which superpixel, a descriptor is. Use the generate_superpixel_descriptors.m
to create those files.



    % generating the inputs

        For the superpixels, you ca use your own code or download the 
superpixels used for our paper (di.ens.fr/~joulin --- if not available 
please contact Armand Joulin -- armand.joulin@ens.fr).
        For the descriptors, you can use your own or generate color/sift 
descriptors using the functions contain in the ./features/ directory. If 
you use our code to generate sift features, please read the References 
section of this README file.
        For the rest, it has been explain in the previous section.
___________________________________________________________________________

% OUTPUT

The main function is low_rank_diffrac.m. It generates a file in the output 
folder. This file contains the result of our algorithm before rounding.
To round this result, use the function rounding_normalized_cut.m which gives
a solution with rank one. 

Note that the graphcut is done during the plotting of our results (in the
file plot_warm_superpixel.m


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% ADDITIONAL CODE

In this code, we have added the possibility of using features at different
scales (which implies some modification of the Laplacian matrix) and the 
possibility of using background images for weakly supervised object
recognition. 
These fonctionality have been used in our paper and might still contain bugs.
For any problem contact Armand Joulin (armand.joulin@ens.fr).














