HMAX Package for CNS

Author:Jim Mutch
Homepage:http://cbcl.mit.edu/jmutch/cns

Description

This is a CNS package that can be used to instantiate a broad class of feedforward object recognition models. The package includes demo scripts to build and run the specific models described in these papers:

Installation

See the instructions for installing packages in the CNS manual. (CNS itself must be installed first.)

Once the package has been installed, make sure it's working by running the following demo script (described in more detail below): 

>> hmax_cvpr06_run_simple
The script should output the following lines. The CNS manual contains a troubleshooting section if you encounter problems.

sampled 2048 "s2" features from "image_0010.jpg"
computed feature vector for "image_0002.jpg" (??? sec)

Introduction

Each of the feedforward recognition models described in the above papers computes a hierarchy of increasingly complex features that are increasingly invariant to position and scale. This is done in interleaved stages that perform either tuning or pooling. Tuning stages are named "S1", "S2", etc. and pooling stages are named "C1", "C2", etc. Each stage is computed at multiple resolutions (scales), i.e. each stage is a scale pyramid. (This is best illustrated in figure 2 of this paper.)

In this hmax package, each of these stages is represented as a CNS group, composed of multiple CNS layers, one layer per scale. This allows all the scales of a group to share common parameters and (if applicable) a common feature dictionary. All the units or cells in a group are of the same type (dot product, max pooling, etc.)

Under the directory hmax/demo there are several demo scripts.

hmax_cvpr06_run_simple
hmax_pnas07_run_simple
These demo scripts illustrate the overall process of instantiating a model, learning a feature dictionary, and computing feature vectors for images. When you start looking into the code, look at hmax_cvpr06_run_simple first.

hmax_cvpr06_run_cal101
hmax_cvpr06_run_uiuc
More extensive demo scripts that perform some of the experiments in the above papers.

hmax_cvpr06_params_base
hmax_cvpr06_params_full
hmax_pnas07_params
Each of these contains a compact set of parameters that defines a particular feedforward model (number of "S" and "C" stages, the particular cell type of each stage, its parameters, pooling ranges, etc.) The meaning of these parameters is documented in each cell type's "Construct" method, found in the file hmax_type.m; for example, you can read about "C" cell parameters in the file hmax_c.m.

The hmax package itself consists of the file hmax.m plus many pairs of files named hmax_type.m and hmax_type.h, each of which defines a different cell type. Some of the ".m" files also contain useful methods, many of which you will have seen used in the above demo scripts.

Additional Documentation

Documentation for this hmax package currently consists of:

Revision History

Rev# Date Changes
r1 2011-02-25 Reorganized & renamed from "fhpkg" (Feature Hierarchy package).
r20 2012-04-10 Tested under CUDA 4.1.