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 (oliver.king@umassmed.edu) Documentation updated June 10, 2013. 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 and 12.04 (32 bit) and Macintosh OS X 10.6-10.8. It should also work on Windows XP, and 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 and later (type "which python" at the command prompt to verify), and for Windows it can be downloaded from http://www.python.org. Alternately, the precompiled Windows binary includes the required Python libraries. PRECOMPILED BINARIES: Precompiled versions of RFF and the required OpenCV libraries are available for Windows 7 and Mac OS X 10.6-10.8. The Windows 7 version may also work for Windows XP. Just unzip these folder where-ever you like --- no additional installation should be required. To Uninstall, delete the folder, but not that this will also delete any output images if your output image directory is contained within this directory. Note that because of licensing restrictions, the Mac OpenCV libraries are not compiled with support for FFmpeg, so may not be able to decode as many video formats. The Windows version does not include the OpenCV FFmpeg dll, but should be able to use it if it is present in the same directory as rff-bin.exe (which is called rrwin7 by default). You could try downloading the file libopencv_ffmpeg200.dll (~5MB) at the "view raw file" link at the follwing page, and dragging it into your rffwin7 folder: http://code.google.com/p/imglinearstructures/source/browse/trunk/debug/libopencv_ffmpeg200.dll?spec=svn2&r=2 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 available with Xcode (https://developer.apple.com/xcode/) which is free in the Apple App Store. In recent versions of Xcode (4.3 and up), gcc is part of the command-line tools that are not included by default with Xcode but can be added on the Components tab of the Downloads preferences panel: http://developer.apple.com/library/ios/#documentation/DeveloperTools/Conceptual/WhatsNewXcode/Articles/xcode_4_3.html 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 or Homebrew 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 sometimes 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: For the precompiled Windows version, there is a program rff-gui.exe; double-clicking this should launch the RFF program, and this option should not require that Python be installed. You can create a shortcut to rff-gui.exe and place it elsewhere on your computer if you like, and launch the program by double-clicking on the shortcut. Otherwise, if Python is installed, 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". (Python Launcher is included with some distributions of Python, although not with the version of Python that in pre-installed in OS X). 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. (3a) Update for 2013: Development is halting for the Perian plugin, and it may not have full functionality with OS X 10.8. If your videos are not supported it may be necessary to install FFmpeg and compile RRF from source, or transcode your videos into a format that the OS X natively supports. For example you could try using HandBrake (http://handbrake.fr/) to convert your videos to MPEG4 compression (H264 codec). Note that transcoding will typically result in degradation of video quality so you may want to try adjusing the quality settings or target bit-rates until you get satisfactory results. (4) For the precompiled Mac OS X version of RFF, which uses Apple's image-writing routines, the output images may have an embedded ColorSync profile that makes them appear to have different brightness or contrast than the video iteslf. In this case, as a work-around the output images can be dragged onto the icon for the program /Library/Scripts/ColorSync/Remove.app (which should already be installed on the Mac) to remove the ColorSync profile information. Multiple images can be selected and dragged all at once, but it does not seem to work to drag a folder onto Renove.app. (5) 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)/ (6) For MPEG file formats that do not include index information, OpenCV does not know the length of the 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 frames 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). The slow or auto mode should be used for these videos, rather than the fast mode. (7) 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.