@@ -67,10 +67,213 @@ Compile pycaffe by `make pycaffe`. The module dir caffe/python/caffe should be i
##MATLAB
-The MATLAB interface -- matcaffe -- is the `caffe`mex and its helper m-files in caffe/matlab. Load models, do forward and backward, extract output and read-only model weights, and load the binaryproto format mean as a matrix.
+The MATLAB interface -- matcaffe -- is the `caffe`package in caffe/matlab in which you can integrate Caffe in your Matlab code.
-A MATLAB demo is in caffe/matlab/caffe/matcaffe_demo.m
+In MatCaffe, you can
-Note that MATLAB matrices and memory are in column-major layout counter to Caffe's row-major layout! Double-check your work accordingly.
+* Creating multiple Nets in Matlab
+* Do forward and backward computation
+* Access any layer within a network, and any parameter blob in a layer
+* Get and set data or diff to any blob within a network, not restricting to input blobs or output blobs
+* Save a network's parameters to file, and load parameters from file
+* Reshape a blob and reshape a network
+* Edit network parameter and do network surgery
+* Create multiple Solvers in Matlab for training
+* Resume training from solver snapshots
+* Access train net and test nets in a solver
+* Run for a certain number of iterations and give back control to Matlab
+* Intermingle arbitrary Matlab code with gradient steps
-Compile matcaffe by `make matcaffe`.
+An ILSVRC image classification demo is in caffe/matlab/demo/classification_demo.m (you need to download BVLC CaffeNet from [Model Zoo](http://caffe.berkeleyvision.org/model_zoo.html) to run it).
+
+###Build MatCaffe
+
+Build MatCaffe with `make all matcaffe`. After that, you may test it using `make mattest`.
+
+Common issue: if you run into error messages like `libstdc++.so.6:version 'GLIBCXX_3.4.15' not found` during `make mattest`, then it usually means that your Matlab's runtime libraries do not match your compile-time libraries. You may need to do the following before you start Matlab:
+Or the equivalent based on where things are installed on your system, and do `make mattest` again to see if the issue is fixed. Note: this issue is sometimes more complicated since during its startup Matlab may overwrite your `LD_LIBRARY_PATH` environment variable. You can run `!ldd ./matlab/+caffe/private/caffe_.mexa64` (the mex extension may differ on your system) in Matlab to see its runtime libraries, and preload your compile-time libraries by exporting them to your `LD_PRELOAD` environment variable.
+
+After successful building and testing, add this package to Matlab search PATH by starting `matlab` from caffe root folder and running the following commands in Matlab command window.
+
+ addpath ./matlab
+
+You can save your Matlab search PATH by running `savepath` so that you don't have to run the command above again every time you use MatCaffe.
+
+###Use MatCaffe
+
+MatCaffe is very similar to PyCaffe in usage.
+
+Examples below shows detailed usages and assumes you have downloaded BVLC CaffeNet from [Model Zoo](http://caffe.berkeleyvision.org/model_zoo.html) and started `matlab` from caffe root folder.
+
+ model = './models/bvlc_reference_caffenet/deploy.prototxt';
+**Be aware that since Matlab is 1-indexed and column-major, the usual 4 blob dimensions in Matlab are `[width, height, channels, num]`, and `width` is the fastest dimension. Also be aware that images are in BGR channels.** Also, Caffe uses single-precision float data. If your data is not single, `set_data` will automatically convert it to single.
+
+You also have access to every layer, so you can do network surgery. For example, to multiply conv1 parameters by 10:
+
+ net.params('conv1', 1).set_data(net.params('conv1', 1).get_data() * 10); % set weights
+ net.params('conv1', 2).set_data(net.params('conv1', 2).get_data() * 10); % set bias
+Forward pass can be done using `net.forward` or `net.forward_prefilled`. Function `net.forward` takes in a cell array of N-D arrays containing data of input blob(s) and outputs a cell array containing data from output blob(s). Function `net.forward_prefilled` uses existing data in input blob(s) during forward pass, takes no input and produces no output. After creating some data for input blobs like `data = rand(net.blobs('data').shape);` you can run
+
+ res = net.forward({data});
+ prob = res{1};
+
+Or
+
+ net.blobs('data').set_data(data);
+ net.forward_prefilled();
+ prob = net.blobs('prob').get_data();
+
+Backward is similar using `net.backward` or `net.backward_prefilled` and replacing `get_data` and `set_data` with `get_diff` and `set_diff`. After creating some gradients for output blobs like `prob_diff = rand(net.blobs('prob').shape);` you can run
+
+ res = net.backward({prob_diff});
+ data_diff = res{1};
+
+Or
+
+ net.blobs('prob').set_diff(prob_diff);
+ net.backward_prefilled();
+ data_diff = net.blobs('data').get_diff();
+
+**However, the backward computation above doesn't get correct results, because Caffe decides that the network does not need backward computation. To get correct backward results, you need to set `'force_backward: true'` in your network prototxt.**
+
+After performing forward or backward pass, you can also get the data or diff in internal blobs. For example, to extract pool5 features after forward pass:
+
+ pool5_feat = net.blobs('pool5').get_data();
+
+####Reshape
+
+Assume you want to run 1 image at a time instead of 10:
+Then the whole network is reshaped, and now `net.blobs('prob').shape` should be `[1000 1]`;
+
+####Training
+
+Assume you have created training and validation lmdbs following our [ImageNET Tutorial](http://caffe.berkeleyvision.org/gathered/examples/imagenet.html), to create a solver and train on ILSVRC 2012 classification dataset:
+Or train for only 1000 iterations (so that you can do something to its net before training more iterations)
+
+ solver.step(1000);
+
+To get iteration number:
+
+ iter = solver.iter();
+
+To get its network:
+
+ train_net = solver.net;
+ test_net = solver.test_nets(1);
+
+To resume from a snapshot "your_snapshot.solverstate":
+
+ solver.restore('your_snapshot.solverstate');
+
+####Input and output
+
+`caffe.io` class provides basic input functions `load_image` and `read_mean`. For example, to read ILSVRC 2012 mean file (assume you have downloaded imagenet example auxiliary files by running `./data/ilsvrc12/get_ilsvrc_aux.sh`):
+**Keep in mind that `width` is the fastest dimension and channels are BGR, which is different from the usual way that Matlab stores an image.** If you don't want to use `caffe.io.load_image` and prefer to load an image by yourself, you can do
+ im_data = single(im_data); % convert to single precision
+
+Also, you may take a look at caffe/matlab/demo/classification_demo.m to see how to prepare input by taking crops from an image.
+
+We show in caffe/matlab/hdf5creation how to read and write HDF5 data with Matlab. We do not provide extra functions for data output as Matlab itself is already quite powerful in output.
+
+####Clear nets and solvers
+
+Call `caffe.reset_all()` to clear all solvers and stand-alone nets you have created.
