%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
PHOTO POPUP README
Derek Hoiem (dhoiem@cs.cmu.edu)
10/08/05
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


The photoPopup application was compiled from matlab code using mcc and runs
only under Linux currently.

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

LICENSE:

Copyright (C) 2005 Derek Hoiem, Carnegie Mellon University

This software is available for non-commercial use only.  Contact Rob Conway 
(rconway@andrew.cmu.edu), the Tech Transfer manager, with questions regarding commercial licensing.

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

How to RUN:

photoPopup [fnData] [fnImage] [extSuperpixelImage] [outdir]
fnData: filename for .mat file containing classifier data
fnImage: filename for original RGB image
extSuperpixelImage: filename extension for superpixel image
outdir: directory to output results
 
Examples of usage:
photoPopup ./classifiers_08_22_2005 ../images/103_0354.jpg pnm ../results 

Type photoPopup (no args) to get a message similar to this.  See notes below
on how to get superpixel image.  See Install instructions below for how to
set environment variables.  photoPopup must be run from the same directory, 
or environment variables must be set to allow it to find the .ctf file.  If the 
image is in the current directory, it must be preceded by "./".  


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

How to INSTALL (Linux Only):


Step 1: Copy photoPopup and photoPopup.ctf to the directory from which you 
        will run photoPopup.

Step 2:

  CASE I: YOU HAVE MATLAB 7 SP 3
    Set your LD_LIBRARY_PATH and XAPPLRESDIR as below.  Use the appropriate 
    path for your computer for MATLABROOT.

    setenv MATLABROOT /usr/local/lib/matlab7

    setenv LD_LIBRARY_PATH $MATLABROOT/sys/os/glnx86:$MATLABROOT/bin/glnx86:$MATLABROOT/sys/java/jre/glnx86/jre1.5.0/lib/i386/native_threads:$MATLABROOT/sys/java/jre/glnx86/jre1.5.0/lib/i386/client:$MATLABROOT/sys/java/jre/glnx86/jre1.5.0/lib/i386

    setenv XAPPLRESDIR $MATLABROOT/X11/app-defaults

   Done!

  
  CASE II: YOU DO NOT HAVE MATLAB 7 SP 3

    Copy MCRInstaller.zip (~100MB!!) as well and follow directions below:
 
    Directions for installing on Linux machine (from MATLAB help): 

    a. Install the MCR by unzipping MCRInstaller.zip in a directory, for 
       example, /home/<user>/MCR. You may choose any directory except 
       <matlabroot> or any directory below <matlabroot>. 
	 Note: This book uses <mcr_root> to refer to the directory where these 
	 MCR library archive files are installed on your machine. 

    b. Copy the executable and CTF archive to your application root directory,
       for example, /home/<user>/approot

    c. Add the following platform-specific directories to your dynamic library 
       path. 
	 Note For readability, the following commands appear on separate lines,
	 but you must enter each setenv command on one line. 

 
       setenv LD_LIBRARY_PATH
	 <mcr_root>/<ver>/runtime/glnx86:
	 <mcr_root>/<ver>/sys/os/glnx86:
	 <mcr_root>/<ver>/sys/java/jre/glnx86/jre1.5.0/lib/i386/native_threads:
	 <mcr_root>/<ver>/sys/java/jre/glnx86/jre1.5.0/lib/i386/client:
	 <mcr_root>/<ver>/sys/java/jre/glnx86/jre1.5.0/lib/i386:
         <mcr_root>/bin/glnx86
       setenv XAPPLRESDIR <mcr_root>/<ver>/X11/app-defaults
       

    Done!

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

NOTES:

  Superpixels:
  I use the segmentation code provided by Felzenszwalb and Huttenlocher
  at people.cs.uchicago.edu/~pff/segment/ to create the superpixels in my
  experiments.  The first three arguments (sigma, k, min) that I use are 
  0.8 100 100.  You can also use a different program to create the superpixel
  image.  That image should have a different RGB color for each segment
  without drawn boundaries between segments.  

  Windows:
  A separate executable and separate instructions are available for Windows.

  Comments, Bugs:
  If you have any comments or suggestions please e-mail them to 
  dhoiem@cs.cmu.edu.  If you re-write any of the code in C and MEX it
  or make the algorithm faster in another way, I would appreciate if you
  send the revised code to me so that I can make it publicly available
  (with acknowledgement of the revision author).  


(C) Derek Hoiem, Carnegie Mellon University, 2005