DeconvNetToolbox
Documentation for Deconvolutional Network Toolbox
This toolbox includes code that implements an Adaptive Deconvolutional Network as described in the paper Adaptive Deconvolutional Networks for Mid and High Level Feature Learning. It may also be used to implement a Deconvolutional Network as described in the paper Deconvolutional Networks though this is not longer the recommended method. This has a function to train a Deconvolutional Network, to visualize the learned filters, and to recsontruct a new image from a trained model. Also, there are files that can be used to make descriptors that can be used with Svetlana Lazebnik's Spatial Pyramid Matching code with a few minor modifications. The Deconvolutional Network Toolbox also works with (and now includes) the IPP Convolutions Toolbox which drastically improves performance (just ensure the IPP Convolutions Toolbox files are in your MATLAB path in order to use it with this toolbox and that they are compiled with your IPP libraries.).


Follow these instructions to setup the toolbox:

  • Download and unzip this toolbox in the location of choice.
  • To setup this toolbox, simply open matlab, cd to this directory, and type "setupDeconvNetToolbox" (without the quotes) in the command window. This sets up your path to include the required directories (you may want to add these paths into your startup.m file as well however) and opens complete documentation for this toolbox.
  • Next you need to compile the pooling functinos in the PoolingToolbox folder using the included compilemex.m function there. You may need to change the paths for you system however. These compiled version are MUCH faster then any MATLAB version and only require openMP libraries for compilation. Some functions won't actually work unless these are compiled.
  • You may also want to compile the IPPConvToolbox files if you have IPP libraries installed on your system as they are much faster than the MATLAB versions. There is a compilemex script in the IPPConvsToolbox folder to compile all the necessary functions but you will likely need to set the paths within it correctly.
  • Also, there are GPUmat capable files included in the zip. You must copy the "mdz" directory in the included zip's /modules/ directory to your GPUmat/modules directory. You must type "make install" in each of those module directories from within MATLAB to ensure the necessary files are installed in GPUmat's top directory correctly.
  • After everything is installed properly (or you just want to use the default CPU implementation) then you can just type "gui" at the command line to configure the settings of the deconvolutional network as you wish. However, you MUST set the paths at the top of the gui.m file to reflect your desired setup. Alternatively, you can modify parameters within /Defaults/set_defaults_here.m which allows you to manually set the model struct that the gui would create.
  • Run any of the main scripts listed below (it is recommended to RUN THEM FROM THIS DIRECTORY as the results will be added to ./Results/ by default).

Running this setupDeconvNetToolbox.m file will add the required directories to the MATLAB path and open the included html documentation for the toolbox.

If you find it slow to train or reconstruct, set model.PLOT_RESULTS=0 and model.DISPLAY_ERRORS = 0.

If you don't have the GPU setup or the IPP libraries it may print many warning messages about compiling the IPP libraries. You can turn these messages off setting model.SUPPRES_WARNINGS=1.

The parameters are set within /Defaults/set_defaults_here.m.

The main scripts to run are:

  • gui.m opens a gui to set parameters before running any of the following scripts. See detailed documentation of gui.m for more information.
  • trainAll.m trains a Deconvoltuional Network using specified parameters.
  • reconAll.m reconstructs input images using a previously trained Deconvolutional Network.
  • top_down_select.m loads previously trained top layer (and all layers below) and visualizes the top layer's filters in pixel space.

The main folders included in the Toolbox are as follows:

  • AllLayers helper functions for going between layers and initializing variables.
  • Connectivity_Matrices define the structure of connections between each layer.
  • Datasets some sample images to train/reconstruct with.
  • Defaults contains the file set_defaults_here.m where you set all the parameters for each experiment.
  • GPU helper functions for GPUmat implementation
  • GUI files related to the gui that sets the parameters (this is where the gui saves to as well).
  • Helper various tools needed for plotting, file manipulation, normalizing, etc.
  • Image_Functions files for the preprocessing of the images
  • Inference functions for inferring z and z0 feautre maps.
  • IPPConvsToolbox the faster IPP convolutions toolbox from my webiste (needs compiling to use the IPP versions).
  • Learn_Filters functions for updating the filters.
  • moules GPUmat modules for convolutions, pooling, and other stuff.
  • PoolingToolbox the optimized pooling functions toolbox from my website.
  • Reconstructing the main high level function for reconstructing an image from a trained model.
  • SPM code to make descriptors for classification (based on Svetlana Lazebnik's Spatial Pyramid Matching code).
  • Top_Down functions for visualizing upper layer filters in pixel space.
  • Training the main high level functions for training the model.
License:
Permission is granted for anyone to copy, use, modify, or distribute this program and accompanying programs and documents for any purpose, provided this copyright notice is retained and prominently displayed, along with a note saying that the original programs are available from our web page. The programs and documents are distributed without any warranty, express or implied. As the programs were written for research purposes only, they have not been tested to the degree that would be advisable in any important application. All use of these programs is entirely at the user's own risk.
Bug:
Please report any bugs to [email protected].
Previous Versions:
  • 2.1.0 - Fixed some minor compilation bugs, improved commenting throughout the package, improved gui commenting, added defaults for the gui to reset back to standard settings, and other minor bug fixes.
  • 2.0.0 - A major release of the toolbox with significant performance improvements, addition of pooling between layers, and reconstruction down to the input image (implements algorithm in the ICCV2011 paper "Adaptive Deconvolutional Networks for Mid and High Level Feature Learning".) Also GPUmat support was added for GPU computation (much faster).
  • 1.0.2 - fixed issues with grayscale image inputs. Adjused sizes of the top down visualizations of filters in the pixel space to be more accurate. Added video capturing (frame-by-frame) for filters. Cleaned up plotting methods. Adjust normalization between layers.
  • 1.0.1 - A few bugs were fixed with plotting and saving figures. Also, the MATLABCentral convnfft.m file is now supported for enhanced performance during training (though not included with this package).
  • 1.0.0 - This is the initial release of this toolbox and may contain unkown bugs.
 All Files Functions Variables Typedefs Enumerations Enumerator Defines