Rodent Face Finder (RFF)
Version 0.1.7, July 7, 2011.

Copyright (c) 2011 Boston Biomedical Research Institute (BBRI)
Authors: Peng Wei and Oliver D. King (king@bbri.org) 

See LICENSE.TXT for RFF license details, 
and OPENCV-LICENSE.TXT for OpenCV license details.  

--------------------------------
INSTALLATION INSTRUCTIONS:

RFF has been installed and tested on Windows 7 (64 bit), 
Ubuntu 10.10 (32 bit) and Macintosh OS X 10.6.
It may work on other platforms but has not been tried.

RFF requires OpenCV libraries (http://opencv.willowgarage.com).
By itself OpenCv can decode a limited set of video formats
(http://opencv.willowgarage.com/wiki/VideoCodecs), but 
it can decode more video formats using FFmpeg 
(http://www.ffmpeg.org/), or for Mac OS X using QuickTime 
plug-ins such as Perian (http://perian.org/). 

The GUI requires Python. Python should already be installed 
under Ubuntu and Mac OS X 10.6 (type "which python" at the 
command prompt to verify), and for Windows it can be 
downloaded from http://www.python.org.


PRECOMPILED BINARIES:

Precompiled versions of RFF and the required OpenCV libraries 
are available for Windows 7 and Mac OS X 10.6. 
Just unzip these folder where-ever you like --- no additional
installation should be required. To Uninstall, delete the
folder.

Note that because of licensing restrictions, the OpenCV libraries 
are not compiled with support for FFmpeg, so may not be able 
to decode as many video formats.  


COMPILING FROM SOURCE:

The compile RFF from the source-code you will need a C++ compiler. 

For Ubuntu, gcc should already be installed. 

For Mac OS X, gcc is included with Xcode. Xcode 3.0 used 
to be (and perhaps still is) free with registration from 
http://developer.apple.com/xcode. Xcode 4.0 is available 
for $5 from the Apple App Store. Note that Xcode is a 
large download (over 4GB).

For Windows, gcc is included with MinGW (http://www.mingw.org).
Instructions for installing MinGW, including changing the
environment variable for the path, are given at
http://www.mingw.org/wiki/InstallationHOWTOforMinGW

See http://opencv.willowgarage.com/wiki/ for instructions
on installing OpenCV and FFmpeg from source using CMake. 
You can also try using apt-get to install OpenCV on Ubuntu 
or MacPorts to install OpenCV for OS X. RFF should work 
with version 2.0 or later of OpenCV. 

After installing OpenCV, the simplest way to compile 
cross-platform programs that link to the OpenCV libraries 
should be by using CMake. We have had problems with 
CMake auto-detecting the location of the OpenCV libraries, 
though, so below give instructions for compiling RFF by 
invoking gcc at the command line, with explicit flags 
for the locations of the headers and libraries.
You will need to know where the opencv headers are 
located, and also where the opencv library are 
located (e.g. at /usr/local/include and /usr/local/bin 
for Ubuntu or OS X, or at C:\OpenCV\include\opencv  
and C:\OpenCV\lib for Windows.)

Also, the names of the libraries themselves has changed 
between OpenCV2.1 and OpenCV2.2, and they sometimes have 
the version number included in the filenames and sometimes 
not, so these should be adjusted as needed.

Examples: (Each command should be a single line --- 
they are split into two lines here (separated by \) 
for readability. Also, if a directory name contain 
spaces it should be enclosed in quotes.)


Ubuntu or OS X, OpenCV 2.2
g++ -o rff-bin rffmain.cpp -I/usr/local/include/opencv -L/usr/local/lib \
  -lopencv_core -lopencv_highgui -lopencv_ml -lopencv_objdetect -lopencv_imgproc

Ubuntu or OS X, OpenCV 2.1 
g++ -o rff-bin  rffmain.cpp -I/usr/local/include/opencv -L/usr/local/lib \
   -lcxcore -lcv -lml -lhighgui 

Windows 7, OpenCV 2.0
g++ -o rff-bin.exe rffmain.cpp -I C:\OpenCV\include\opencv -L C:\OpenCV\lib \
   -lcxcore200 -lcv200 -lml200 -lhighgui200 


----------------------------------------------------------------
USAGE INSTRUCTIONS:

Launch the program rff-gui.py. 

This can be done in several ways, depending on your platform and file associations.

(1) Using the Terminal, cd to the directory containing rff-gui.py, 
   and type the command
      python rff-gui.py 
   If rff-gui has permissions as an executable file, just typing
      ./rff-gui.py  
   may also work (provided the current directory includes the file). 

(2) Double-clicking on the rff-gui.py file might work for you, 
    or right-clicking on rff-gui.py, and selecting an option 
    like "Open with -> Python Launcher".  
    
This will open a GUI which lets you configure options, and which 
has usage information accessible from the menu-bar. 

The program rff-bin can also be invoked directly from the command-line,
with configuration options given as command-line flags, but we suggest 
using the GUI instead. The GUI will create necessary output directories 
and warn about possible over-writing of output files, whereas 
rff-bin will not.

----------------------------------------------------------------

KNOWN ISSUES: 

(1) RFF has not yet been trained or tested for mice or rats with 
coat colors other than white, so is currently not suitable for 
non-white rodents.

(2) OpenCV does not automatically detect when a video uses non-square 
pixels (see http://en.wikipedia.org/wiki/Pixel_aspect_ratio). 
Consequently videos with non-square pixels can appear to be too 
narrow. This can be over-ridden by setting the video aspect-ratio 
manually.

(3) For Mac OS X without FFmpeg, the Perian Quicktime add-ons 
(http://perian.org/) may allow more video formats to be 
decoded. However, in this case videos with non-square pixels
may appear to be skewed diagonally, and this cannot currently
be over-ridden manually.

(4) For Mac OS X 10.6 on computers with 32-bit processors
(http://support.apple.com/kb/ht3696), FFmpeg may not compile 
correctly (https://trac.macports.org/ticket/20938). Also, to 
link to QuickTime on 64-bits processors, the OpenCV libraries
may have to be compiled in 32-bit mode  
(http://tech.groups.yahoo.com/group/OpenCV/message/65895)/

(5) For MPEG file formats that do not include index information,
OpenCV does not know the length of movie, so the Trackbar
at the top of the window will not correctly indicate the progress 
of the of the playback. Also, in these cases directly accessing 
arbitrary does not work, so all frames must be decoded, even 
if one wishes to skip over many consecutive frames (e.g. with 
a long gap length).   

(6) For some OS X versions, the video window does not have 
height added to it to accommodate the Trackbar at the top. 
Rather, the video window is squashed a bit vertically to make 
room for the Trackbar. This does not affect the output images, 
however.


