hmin: A Minimal HMAX Implementation

Titlehmin: A Minimal HMAX Implementation
Publication TypeCode
Year of Publication2010
AuthorsMutch, J
Date Published01/2010
Abstract

This is a simple reference implementation of HMAX, meant for illustration. It is a single-threaded, CPU-based, pure C++ implementation (but still called via MATLAB’s “mex” interface).

The package contains C++ classes for layers and filters, and a main program that assembles them to implement one specific model.

See Full Text below for more information and to download.
Citation Key382
Full Text

hmin: A Minimal HMAX Implementation

Description

hmin is a simple reference implementation of HMAX, which is a class of feedforward object recognition models inspired by the primate ventral visual pathway. Some recent papers describing HMAX models include:

  • T. Serre, A. Oliva and T. Poggio. A feedforward architecture accounts for rapid categorization. Proceedings of the National Academy of Science, 104(15), pp. 6424-6429, April 2007. [pdf]
  • Jim Mutch and David G. Lowe. Object class recognition and localization using sparse features with limited receptive fields. International Journal of Computer Vision (IJCV), 80(1), pp. 45-57, October 2008. [pdf]

hmin is an alternative to the full HMAX package, which is the implementation under active use in CBCL. While being much slower and less flexible than hmax, hmin is easier to understand. It is a single-threaded, CPU-based, pure C++ implementation. Although still written to be called from MATLAB, all the code that computes the feature hierarchy is written in C++.

hmin consists of:

  1. A minimal set of filter classes, representing some of HMAX's template matching and pooling operations, and a layer class, used to hold the input and the outputs of filtering operations. These classes can be configured and arranged to make many different models.
  2. A single example model, defined using the above classes.
  3. A feature dictionary suitable for use with the example model.
  4. Some wrapper code that computes the example model's output for an image. This will be a high-dimensional feature vector suitable for use in a classifier.

To Install and Run

  1. Download the hmin.tar archive.
  2. Unpack the archive file and move the hmin directory to wherever you will be using it.
  3. In MATLAB, change into the hmin directory.
  4. Create an executable for the example model using the command:
    mex example.cpp

    Note: if this doesn't work, you probably don't have MATLAB properly configured to call your C++ compiler (or you don't have a C++ compiler). For the former problem, try the MATLAB command "mex -setup".

  5. Run the example model on an image like this:
    out = example_run(im);

    where im contains an image, or the path of an image. If the im argument is omitted, an example image will be used.

Files

example_run.m Wrapper code that runs the example model for an image.
example.cpp Main C++ function that computes the feature hierarchy for the example model. Sets up the model structure, loads the feature dictionary, loads the input image, computes the feature hierarchy, and retrieves the results. Contains many hard-coded parameter values specific to the example model. Must be compiled; see the installation instructions above.
classes/ Directory containing all of hmin's C++ class definitions.
  main.h #includes all the header files listed below. This is the only file that a .cpp file must directly #include.
  layer.h Defines the Layer class, which holds the input and the outputs of filtering operations.
  filter.h Defines the abstract Filter class. Filters take one or more Layers as input and produce one Layer as output.
  gaborfilter.h
  maxfilter.h
  grbffilter.h
  gmaxfilter.h		 Specific Filter subclasses that implement the various operations: gabor filter, local max, gaussian radial basis function, and global max.
data/ Directory containing example data.
  s2dict.mat A feature dictionary suitable for the example model's "S2" layer, containing 4,075 features learned from natural images (using the full HMAX package).
  ketch_0010.jpg An example image.
more/ Directory containing additional resources.
  example_generate.m Script that was used to generate sections of example.cpp.
  example_hmax.m Contains a set of parameters that would be used to describe the example model under the full HMAX package.

 

Additional Documentation

Documentation for hmin currently consists of:

  • this page
  • MATLAB function help
  • comments in source files

Revision History

Rev# Date Changes
r6 2010-10-04 s2dict.mat is now saved in MATLAB's uncompressed -V6 format.
r7 2010-10-09 example_run.m now converts "unknown" values to zero in the output vector.
r8 2010-10-14 more/example_generate.m shows how the layer sizes and common retinal coordinates in example.cpp were generated -- without relying on the full hmax package.
r15 2011-02-25 Common coordinate system is now [-128 128]. Updated to reference latest "hmax" package.

Research Area: 

CBMM Relationship: 

  • CBMM Related