[models] adding zoo readme; caffenet, alexnet, and rcnn models in zoo…

… format

.gitignore

@@ -51,8 +51,8 @@ Makefile.config
 # 1. reference, and not casually committed
 # 2. custom, and live on their own unless they're deliberated contributed
 data/*
-*model
-*_iter_*
+models/*
+*.caffemodel
 *.solverstate
 *.binaryproto
 *leveldb

docs/getting_pretrained_models.md

@@ -5,30 +5,12 @@ layout: default
 # Pre-trained models
 
 [BVLC](http://bvlc.eecs.berkeley.edu) aims to provide a variety of high quality pre-trained models.
-Note that unlike Caffe itself, these models are licensed for **academic research / non-commercial use only**.
-If you have any questions, please get in touch with us.
+Note that unlike Caffe itself, these models usually have licenses **academic research / non-commercial use only**.
 
-*UPDATE* July 2014: we are actively working on a service for hosting user-uploaded model definition and trained weight files.
-Soon, the community will be able to easily contribute different architectures!
+## TODO
 
-### ImageNet
+Write something about the model zoo.
 
-**Caffe Reference ImageNet Model**: Our reference implementation of an ImageNet model trained on ILSVRC-2012 can be downloaded (232.6MB) by running `examples/imagenet/get_caffe_reference_imagenet_model.sh` from the Caffe root directory.
-
-- The bundled model is the iteration 310,000 snapshot.
-- The best validation performance during training was iteration 313,000 with
-  validation accuracy 57.412% and loss 1.82328.
-- This model obtains a top-1 accuracy 57.4% and a top-5 accuracy 80.4% on the validation set, using just the center crop. (Using the average of 10 crops, (4 + 1 center) * 2 mirror, should obtain a bit higher accuracy)
-
-**AlexNet**: Our training of the Krizhevsky architecture, which differs from the paper's methodology by (1) not training with the relighting data-augmentation and (2) initializing non-zero biases to 0.1 instead of 1. (2) was found necessary for training, as initialization to 1 gave flat loss. Download the model (243.9MB) by running `examples/imagenet/get_caffe_alexnet_model.sh` from the Caffe root directory.
-
-- The bundled model is the iteration 360,000 snapshot.
-- The best validation performance during training was iteration 358,000 with
-  validation accuracy 57.258% and loss 1.83948.
-- This model obtains a top-1 accuracy 57.1% and a top-5 accuracy 80.2% on the validation set, using just the center crop. (Using the average of 10 crops, (4 + 1 center) * 2 mirror, should obtain a bit higher accuracy)
-
-**R-CNN (ILSVRC13)**: The pure Caffe instantiation of the [R-CNN](https://github.com/rbgirshick/rcnn) model for ILSVRC13 detection. Download the model (230.8MB) by running `examples/imagenet/get_caffe_rcnn_imagenet_model.sh` from the Caffe root directory. This model was made by transplanting the R-CNN SVM classifiers into a `fc-rcnn` classification layer, provided here as an off-the-shelf Caffe detector. Try the [detection example](http://nbviewer.ipython.org/github/BVLC/caffe/blob/master/examples/detection.ipynb) to see it in action. For the full details, refer to the R-CNN site. *N.B. For research purposes, make use of the official R-CNN package and not this example.*
-
-### Auxiliary Data
+## Auxiliary Data
 
 Additionally, you will probably eventually need some auxiliary data (mean image, synset list, etc.): run `data/ilsvrc12/get_ilsvrc_aux.sh` from the root directory to obtain it.

docs/model_zoo.md

@@ -0,0 +1,31 @@
+# Caffe Model Zoo
+
+A caffe model is distributed as a directory containing:
+- solver/model prototxt(s)
+- model binary file, with .caffemodel extension
+- readme.md, containing:
+  - YAML header:
+    - model file URL or (torrent magnet link) and MD5 hash
+    - Caffe commit hash use to train this model
+    - [optional] github gist id
+    - license type or text
+  - main body: free-form description/details
+- helpful scripts
+
+It is up to the user where to host the model file.
+Dropbox or their own server are both fine.
+
+We provide scripts:
+
+- publish_model_as_gist.sh: uploads non-binary files in the model directory as a Github Gist and returns the id. If gist id is already part of the readme, then updates existing gist.
+- download_model_from_gist.sh <gist_id>: downloads the non-binary files from a Gist.
+- download_model_binary.py: downloads the .caffemodel from the URL specified in readme.
+
+The Gist is a good format for distribution because it can contain multiple files, is versionable, and has in-browser syntax highlighting and markdown rendering.
+
+The existing models distributed with Caffe can stay bundled with Caffe, so I am re-working them all into this format.
+All relevant examples will be updated to start with `cd models/model_of_interest && ../scripts/download_model_binary.sh`.
+
+## Tasks
+
+- get the imagenet example to work with the new prototxt location

examples/imagenet/readme.md

@@ -6,18 +6,16 @@ include_in_docs: true
 priority: 1
 ---
 
-Yangqing's Recipe on Brewing ImageNet
-=====================================
+Brewing ImageNet
+================
 
-    "All your braincells are belong to us."
-        - Caffeine
-
-We are going to describe a reference implementation for the approach first proposed by Krizhevsky, Sutskever, and Hinton in their [NIPS 2012 paper](http://books.nips.cc/papers/files/nips25/NIPS2012_0534.pdf). Since training the whole model takes some time and energy, we provide a model, trained in the same way as we describe here, to help fight global warming. If you would like to simply use the pretrained model, check out the [Pretrained ImageNet](../../getting_pretrained_models.html) page. *Note that the pretrained model is for academic research / non-commercial use only*.
+We are going to describe a reference implementation for the approach first proposed by Krizhevsky, Sutskever, and Hinton in their [NIPS 2012 paper](http://books.nips.cc/papers/files/nips25/NIPS2012_0534.pdf).
+Since training the whole model takes some time and energy, we provide a model, trained in the same way as we describe here, to help fight global warming.
+If you would like to simply use the pretrained model, check out the [Pretrained ImageNet](../../getting_pretrained_models.html) page.
+*Note that the pretrained model is for academic research / non-commercial use only*.
 
 To clarify, by ImageNet we actually mean the ILSVRC12 challenge, but you can easily train on the whole of ImageNet as well, just with more disk space, and a little longer training time.
 
-(If you don't get the quote, visit [Yann LeCun's fun page](http://yann.lecun.com/ex/fun/).
-
 Data Preparation
 ----------------
 
@@ -100,11 +98,13 @@ We all experience times when the power goes out, or we feel like rewarding ourse
 
     ./resume_training.sh
 
-where in the script `caffe_imagenet_train_1000.solverstate` is the solver state snapshot that stores all necessary information to recover the exact solver state (including the parameters, momentum history, etc).
+where in the script `imagenet_train_1000.solverstate` is the solver state snapshot that stores all necessary information to recover the exact solver state (including the parameters, momentum history, etc).
 
 Parting Words
 -------------
 
-Hope you liked this recipe! Many researchers have gone further since the ILSVRC 2012 challenge, changing the network architecture and/or finetuning the various parameters in the network. The recent ILSVRC 2013 challenge suggests that there are quite some room for improvement. **Caffe allows one to explore different network choices  more easily, by simply writing different prototxt files** - isn't that exciting?
+Hope you liked this recipe!
+Many researchers have gone further since the ILSVRC 2012 challenge, changing the network architecture and/or finetuning the various parameters in the network.
+**Caffe allows one to explore different network choices  more easily, by simply writing different prototxt files** - isn't that exciting?
 
-And since now you have a trained network, check out how to use it: [Running Pretrained ImageNet](../../getting_pretrained_models.html). This time we will use Python, but if you have wrappers for other languages, please kindly send a pull request!
+And since now you have a trained network, check out how to use it with the Python interface: [Running Pretrained ImageNet](../../getting_pretrained_models.html).

examples/imagenet/alexnet_solver.prototxt → models/bvlc_alexnet/alexnet_solver.prototxt

@@ -1,4 +1,4 @@
-net: "examples/imagenet/alexnet_train_val.prototxt"
+net: "models/bvlc_alexnet/alexnet_train_val.prototxt"
 test_iter: 1000
 test_interval: 1000
 base_lr: 0.01
@@ -10,5 +10,5 @@ max_iter: 450000
 momentum: 0.9
 weight_decay: 0.0005
 snapshot: 10000
-snapshot_prefix: "examples/imagenet/caffe_alexnet"
+snapshot_prefix: "models/bvlc_alexnet/caffe_alexnet_train"
 solver_mode: GPU