================================================================================ FHLIB - MULTISCALE FEATURE HIERARCHY LIBRARY ================================================================================ RELEASE : 8 (2008/09/04) AUTHOR : Jim Mutch HOMEPAGE: www.jimmutch.com ================================================================================ Contents ================================================================================ 1. License 2. Overview 3. Requirements 4. Installation 5. Documentation 6. Getting Updates / Fixes 7. Revision History ================================================================================ 1. License ================================================================================ Copyright (C) 2008 Jim Mutch This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . ================================================================================ 2. Overview ================================================================================ This archive contains MATLAB/C++ source code used in the experiments described in: Jim Mutch and David G. Lowe. Multiclass Object Recognition with Sparse, Localized Features. CVPR, pages 11-18, New York, June 2006 The code is organized as a parameter-driven library capable of supporting a class of models. The model described in our paper is one instance. All functions are designed to be called from MATLAB. For speed, many of these MATLAB functions in turn call C++ methods (for which source code is also provided). Code is included for: - configuring the hierarchy (number of levels, filters used at each level, pooling ranges, etc.), - learning features, computing response vectors, and tracing the locations of computed features, and - the final SVM classification stage (except the feature selection step). The following is *not* currently included: - neighborhood suppression code for localization. There are two demo scripts, and every function also has fairly comprehensive MATLAB help. At this point there is no *internal* documentation. For example, the library has been designed to make it relatively easy to program new kinds of filters, however there are currently no instructions on how to do this. ================================================================================ 3. Requirements ================================================================================ MATLAB, and the MATLAB image processing toolbox, are required. MATLAB's "mex" command must have been correctly configured to call a C++ compiler. All recent testing has been done using MATLAB 7.6.0.324 (R2008a), running under Linux. There are no known problems running the software under Windows. ================================================================================ 4. Installation ================================================================================ Note: Linux commands are given in steps (1) and (2). If you are not using Linux, please substitute equivalent commands. (1) Untar the archive with the command "tar -xf ???.tar", where "???" is replaced by the name of the archive. This will create an "FHLib" directory. You can move this directory to anyplace you like. (2) Add the command "run ???/FHLib/GLSetPath" to your MATLAB "startup.m" file, where "???" is replaced by the path leading to the "FHLib" directory. (3) Run MATLAB. Make sure you see a message stating that "FHLib" has been added to the MATLAB path. (4) Type "GLCompile" to compile all the C++ components. (5) Type "FHDemo" to run the basic demo script. (6) Type "help FHLib" to display the main help page. (7) If you are going to run the full Caltech 101 demo script (see Documentation, below), you will need to install the Statistical Pattern Recognition Toolbox for MATLAB, available at the following link. Note that the demo script was most recently tested using version 2.04 of the Toolbox. http://cmp.felk.cvut.cz/cmp/software/stprtool ================================================================================ 5. Documentation ================================================================================ There are two demo scripts: FHDemo - Illustrates basic usage of the FH library. FHDemo_CVPR06_Cal101 - Performs multiclass classification. Aside from these scripts, all the documentation is in the form of MATLAB help. Typing "help FHLib" will show you the main help page. This leads to other help pages. Every function has help that can be displayed via "help ???", where "???" is replaced by the function name. There is also a special "FHHelp" command that provides information on how to configure each of the different kinds of filters (max, grbf, etc.) ================================================================================ 6. Getting Updates / Fixes ================================================================================ If you would like to be notified regarding the release of additional code, documentation, or bugfixes, please email the author to be put on a mailing list. A disclaimer: this code has been cleaned up substantially since our CVPR '06 submission. Recent test runs have successfully reproduced our main results; however, any significant code cleanup exercise runs the risks of introducing a bug or two. If you find one, please contact the author. ================================================================================ 7. Revision History ================================================================================ 1 2006/11/27 Pre-release. 2 2007/01/08 First full release. A few minor bug fixes. 3 2007/05/03 Filters moved to separate directories under FH/filters. Many smaller changes. (Repository version 63.) 4 2007/05/21 Added FHConfig_* functions. Fixes for 64-bit compilation. (Repository version 75.) 5 2007/07/13 Fixes for compilation under Windows. Upgraded license to GPLv3. (Repository version 77.) 6 2007/09/22 Added FHDemo_CVPR06_Cal101. (Repository version 84.) 7 2008/08/03 Updated FHConfig_PNAS07. (Repository version 96.) 8 2008/09/04 Simplified the contents of the "filters" directory to make it easier to define new filter classes. (Repository version 104.)