1. STRUCTURE OF THIS PACKAGE
============================

* bin/
  Directory with the binaries for this problem. All the binaries are for linux
  and were compiled for 32bits and statically linked. That means it should run
  in almost any linux distribution. They were tested in unix.andrew.cmu.edu
  (the place you login to turn in your homework), so in worst case, run the
  binaries there. These are the binaries provided:

  - blackbox
    The inference engine provided. Two command line parameters must be provided:
    gamma and input_file. gamma is a double greater or equal to 0. The
    input_file represents the undirected graph of the superpixels as an
    adjacency matrix. For more information about the format, see section 2. The
    output has n lines, where n is the number of vertices (i.e., number of
    superpixels). The ith line of the output is either "0" or "1" and
    represents, respectively, that the superpixel i-1 is background or
    foreground.

  - compare_segmentation
    Program to compare two segmentation files. It takes two arguments
    representing, respectively, the path to the true segmentation and your
    segmentation. It outputs the score of your segmentation. The score is a
    number from 0 to 1 and the lower the better (i.e., 0 is the perfect score).


  - check_segmentation
    Program to check if your segmentation file respects the format described in
    section 2. It takes one argument, the path to your segmentation file, and it
    outputs either "correct" or an error message.



* data/part2/
  Contains the data for Part 2. There are 10 subdirectories (001-010) and each
  of them contains 5 files (for their formats, see section 2 bellow): the image 
  (.jpg), the superpixel map, the visualization of the superpixel map (.png), 
  the scribble mask and the true segmentation.
  

* data/part3/
  Contains the data for Part 3. There are 10 subdirectories (011-020) and each
  of them contains 4 files: the image (.jpg), the superpixel map and the 
  visualization of the superpixel map (.png).



2. FILE FORMATS
===============

* Image: 
  JPEG files
  
* Superpixel map
  ASCII file in which the first line is "h w S" where h is the height and w is
  the width of the image. S is the total number of superpixels. The file contains
  h more lines and each line has w columns (separated by one blank space each).
  The value at line i and column j represents the superpixel id of the pixel at
  position (i,j). The superpixel id is in {0,...,S-1}. 

* Scribble mask
  Same format as the Superpixel Map, except that S is omitted in the first line
  and the value at position (i,j) is either: 0 for background; 1 for foreground;
  and 2 for unknown.

* True Segmentation
  Same format as the scribble mask, except that the values for each position (i,j)
  can be either 0 or 1.

* Blackbox Input
  ASCII file in which the first line is "n m" where n is the number of vertices
  and m the number of edges in the input graph. The file contains n+m more
  lines. The next n lines contain a single double number per line and the ith
  line in this block of n lines represents P_fg(V_{i-1}) where i-1 is the
  superpixel id.  The next block of the file contains m lines, one for each egde
  of the graph and each line is "x y w" representing an edge between x and y,
  both superpixel ids, with weight w. The weight w must be between [0,1]. The 
  file bin/blackbox_input_example.txt represent the line graph 0 -- 1 -- 2 -- 3.


  

3. HOW TO SUBMIT YOUR DATA AND CODE
===================================

Turn in a tar.gz file (or zip) with the following directory structure:

code/
code/README.txt
comp/
comp/XXX/
comp/XXX/blackbox.input
comp/XXX/segmentation

where XXX is the subdirectory name for each image, i.e., XXX = {010, 011, ..., 020}.
Place your code in the code directory and make sure that you explain how to
compile and run your code in the README.txt file. Every file blackbox.input and
segmentation should follow the specification described in section 2. To double
check if the segmentation file is in the right format, run:
  $ check_segmentation f
where f is your segmentation file. Make sure that the files are in the correct
directory, for instance, the segmentation and blackbox.input for
data/part3/011/69020.jpg should be in the directory comp/011/, etc.


