This is a bundle of code for training the model used in: 

    Data-Driven 3D Primitives for Single Image Understanding
    David F. Fouhey, Abhinav Gupta, and Martial Hebert
    At ICCV 2013

This will produce a model that can be used by the inference only version of the
code. Please note that we cannot provide support and this code comes with no
guarantees.

This release contains two folders. Each has their own readme, since they're 
orthogonal tasks (setting up the data and learning the model). Once you've
trained the model, you'll need to do a very small bit of file shuffling to let the 
inference code (supplied separately) read it.

setupDataset/
    This contains a script to download, extract, and process the NYU v2 dataset
    in the way that the training code expects it to be in. 

trainCode/
    This contains the code that trains the model. You'll need to set a few
    variables and then the code will run.
    
    You will also need the natural world / outdoor dataset downloaded and unzipped
    somewhere accessible via the training code.

**********************
* Training Procedure *
**********************

1) Follow the instructions in setupDataset. You'll need ~20 GB of disk space
2) Follow the instructions in trainCode. You'll probably need ~100GB of disk 
   space for scratch data.
3) Construct a valid folder for the inference code to use. This requires moving
   a few files, and is explained below.


*****************************************
* Hooking it up with the inference code *
*****************************************

The inference code expects a folder of the form (where / is the root of the
folder):

    /Clusters/ --   this is the folder produce by the training procedure
                    (i.e., patchesTarget in globals.m in trainCode/).
    /normalData/ -- this is the normals data that will be used in dense
                    transfer. You need to copy the reduced normals produced
                    in setting up the dataset here. Specifically,
                    copy ${datasetLocation}/normalsR4/* to /normalData/.

                    where ${datasetLocation} is set in globals.m in 
                    setupDataset.

After this, your tree should look like this.

    /Clusters/
    /Clusters/clusters/...
    /Clusters/detectors/...
    /Clusters/metadata/...
    /normalData/nm_000001.mat
    /normalData/nm_000002.mat
    ....


Your inference code should be able to read this. If you downloaded
the inference code before the training code was released, it'll
look in the wrong directory. You can either manually update 
3DP/loadRankedClusters.m in the inference code or download a new version.  

**********
* Bibtex *
**********

If you use this code in a publication, please cite:

@inproceedings{Fouhey13,
    title = {Data-Driven {3D} Primitives for Single Image Understanding},
    author = {Fouhey, David F. and Gupta, Abhinav and Hebert, Martial},
    booktitle = {ICCV},
    year = {2013},
}


