README.md

   1 [Caffe: Convolutional Architecture for Fast Feature Extraction](http://caffe.berkeleyvision.org)
   2
   3 Created by [Yangqing Jia](http://daggerfs.com), UC Berkeley EECS department.
   4 In active development by the Berkeley Vision and Learning Center ([BVLC](http://bvlc.eecs.berkeley.edu/)).
   5
   6 ## Introduction
   7
   8 Caffe aims to provide computer vision scientists with a **clean, modifiable
   9 implementation** of state-of-the-art deep learning algorithms. Network structure
  10 is easily specified in separate config files, with no mess of hard-coded
  11 parameters in the code. Python and Matlab wrappers are provided.
  12
  13 At the same time, Caffe fits industry needs, with blazing fast C++/Cuda code for
  14 GPU computation. Caffe is currently the fastest GPU CNN implementation publicly
  15 available, and is able to process more than **40 million images per day** on a
  16 single NVIDIA K40 GPU (or 20 million per day on a K20)\*.
  17
  18 Caffe also provides **seamless switching between CPU and GPU**, which allows one
  19 to train models with fast GPUs and then deploy them on non-GPU clusters with one
  20 line of code: `Caffe::set_mode(Caffe::CPU)`.
  21
  22 Even in CPU mode, computing predictions on an image takes only 20 ms when images
  23 are processed in batch mode.
  24
  25 * [Caffe introductory presentation](http://berkeleyvision.org/caffe-presentation.pdf)
  26 * [Installation instructions](http://caffe.berkeleyvision.org/installation.html)
  27
  28 \* When measured with the [SuperVision](http://www.image-net.org/challenges/LSVRC/2012/supervision.pdf) model that won the ImageNet Large Scale Visual Recognition Challenge 2012.
  29
  30 ## License
  31
  32 Caffe is BSD 2-Clause licensed (refer to the
  33 [LICENSE](http://caffe.berkeleyvision.org/license.html) for details).
  34
  35 The pretrained models published by the BVLC, such as the
  36 [Caffe reference ImageNet model](https://www.dropbox.com/s/n3jups0gr7uj0dv/caffe_reference_imagenet_model)
  37 are licensed for academic research / non-commercial use only. However, Caffe is
  38 a full toolkit for model training, so start brewing your own Caffe model today!
  39
  40 ## Citing Caffe
  41
  42 Please kindly cite Caffe in your publications if it helps your research:
  43
  44     @misc{Jia13caffe,
  45       Author = {Yangqing Jia},
  46       Title = { {Caffe}: An Open Source Convolutional Architecture for Fast Feature Embedding},
  47       Year  = {2013},
  48       Howpublished = {\url{http://caffe.berkeleyvision.org/}}
  49     }
  50
  51 ## Documentation
  52
  53 Tutorials and general documentation are written in Markdown format in the `docs/` folder.
  54 While the format is quite easy to read directly, you may prefer to view the whole thing as a website.
  55 To do so, simply run `jekyll serve -s docs` and view the documentation website at `http://0.0.0.0:4000` (to get [jekyll](http://jekyllrb.com/), you must have ruby and do `gem install jekyll`).
  56
  57 We strive to provide provide lots of usage examples, and to document all code in docstrings.
  58 We'd appreciate your contribution to this effort!
  59
  60 ## Development
  61
  62 Caffe is developed with active participation of the community by the [Berkeley Vision and Learning Center](http://bvlc.eecs.berkeley.edu/).
  63 We welcome all contributions!
  64
  65 ### The release cycle
  66
  67 - The `dev` branch is for new development, including community contributions. We aim to keep it in a functional state, but large changes may occur and things may get broken every now and then. Use this if you want the "bleeding edge".
  68 - The `master` branch is handled by BVLC, which will integrate changes from `dev` on a roughly monthly schedule, giving it a release tag. Use this if you want more stability.
  69
  70 ### Setting priorities
  71
  72 - Make GitHub Issues for bugs, features you'd like to see, questions, etc.
  73 - Development work is guided by [milestones](https://github.com/BVLC/caffe/issues?milestone=1), which are sets of issues selected for concurrent release (integration from `dev` to `master`).
  74 - Please note that since the core developers are largely researchers, we may work on a feature in isolation from the open-source community for some time before releasing it, so as to claim honest academic contribution. We do release it as soon as a reasonable technical report may be written about the work, and we still aim to inform the community of ongoing development through Issues.
  75
  76 ### Contibuting
  77
  78 - Do new development in [feature branches](https://www.atlassian.com/git/workflows#!workflow-feature-branch) with descriptive names.
  79 - Bring your work up-to-date by [rebasing](http://git-scm.com/book/en/Git-Branching-Rebasing) onto the latest `dev`. (Polish your changes by [interactive rebase](https://help.github.com/articles/interactive-rebase), if you'd like.)
  80 - [Pull request](https://help.github.com/articles/using-pull-requests) your contribution to BVLC/caffe's `dev` branch for discussion and review.
  81   * PRs should live fast, die young, and leave a beautiful merge. Pull request sooner than later so that discussion can guide development.
  82   * Code must be accompanied by documentation and tests at all times.
  83   * Only fast-forward merges will be accepted.
  84
  85 See our [development guidelines](http://caffe.berkeleyvision.org/development.html) for further details–the more closely these are followed, the sooner your work will be merged.
  86
  87 #### [Shelhamer's](https://github.com/shelhamer) “life of a branch in four acts”
  88
  89 Make the `feature` branch off of the latest `bvlc/dev`
  90 ```
  91 git checkout dev
  92 git pull upstream dev
  93 git checkout -b feature
  94 # do your work, make commits
  95 ```
  96
  97 Prepare to merge by rebasing your branch on the latest `bvlc/dev`
  98 ```
  99 # make sure dev is fresh
 100 git checkout dev
 101 git pull upstream dev
 102 # rebase your branch on the tip of dev
 103 git checkout feature
 104 git rebase dev
 105 ```
 106
 107 Push your branch to pull request it into `dev`
 108 ```
 109 git push origin feature
 110 # ...make pull request to dev...
 111 ```
 112
 113 Now make a pull request! You can do this from the command line (`git pull-request -b dev`) if you install [hub](https://github.com/github/hub).
 114
 115 The pull request of `feature` into `dev` will be a clean merge. Applause.