pengsun / MexConv3D

Matlab mex implementation of the basic operations for 3D (volume) Convolutional Neural Network

MexConv3D

Matlab mex implementation (with both CPU and GPU version) of the basic operations for 3D (volume) ConvNet. Potential use: video, volume data (CT, MR), etc. The APIs and conventions are consistent with matconvnet.

Overview

mex_conv3d.m is provided for 3D convoluation, while mex_maxpool3d.m for 3D max pooling. Their calling conventions are consistent with vl_nnconv.m and vl_nnpool.m in matconvnet, respectively.

In this project only the most basic building blocks are provided. For a ready-to-use 3D ConvNet in Matlab, one needs a high-level wrapper like the vl_simplenn.m in matconvnet or MatConvDAG

Install

Step by step:

• Run make_all.m in root directory to make the mex files
  • CUDA toolkit needed if enabling GPU
• Run setup_path.m in root directory to add path
• (Optional) CD to folder unittest and run run_all.m to verify everything works well

MexConv3D has been tested in the following environment:

• Matlab R2014a + Windows 8.1 + Visual Studio 2012 + CUDA Toolkit 6.5 (if enabling GPU)
• Matlab R2014a + Ubuntu 12.04 + GCC 4.8.2 + CUDA Toolkit 6.5 (if enabling GPU)

Usage

For 3D Convolution:

%% data
szX = [9,8,5, 5,9];  % input size: 3D volume + #feature maps + #instances
szF = [3,3,3, 5,4];  % filter size: 3D volume + #input feature maps + #output feature maps
szB = [1, szF(end)]; % bias size: #output feature maps
X = gpuArray.rand(szX, 'single');
F = gpuArray.rand(szF, 'single');
B = gpuArray.rand(szB, 'single');

pad    = [1,2, 2,1, 3,4]; % 3D higher/lower padding
stride = [2,3,5];         % 3D stride
%% fprop
Y = mex_conv3d(X,F,B, 'pad', pad, 'stride',stride);
%% bprop
dZdY = rand(size(Y), 'like', Y);
[dZdX,dZdF,dZdB] = mex_conv3d(X,F,B, dZdY, 'pad',pad, 'stride',stride);

For 3D Max Pooling:

%% data
sz = [7,8,5, 5,9]; % size for 3D volume + #feature maps + #instances
pool   = [3,2,4];          % 3D pooling window size
stride = [2,1,2];          % 3D stride 
pad    = [1,1,  0,0, 2,1]; % 3D higher/lower padding
x = gpuArray.rand(sz, 'single'); % Input data/feature maps
%% fprop
[y, ind] = mex_maxpool3d(x,...
  'pool',pool, 'stride',stride, 'pad',pad);
%% bprop
dzdy = rand(size(y),'like',y);
xx = mex_maxpool3d(dzdy,ind,size(x),...
  'pool',pool, 'stride',stride, 'pad',pad);

Example

See more scripts in directory example. Type help mex_conv3d or help mex_maxpool3d for doc. See README.md in each folder (if any) to understand the folder layout and the purpose.

See example/example_simplenet for an example of doing fprop/bprop over a simple 3D convnet (which is based on the code of Sushma Rudra).