update readme

Luo-Chang · Dec 23, 2017 · e695fc1 · e695fc1
1 parent 6e7b4d2
commit e695fc1
Showing 1 changed file with 37 additions and 32 deletions.
diff --git a/README.MD b/README.MD
@@ -1,46 +1,46 @@
-# A Pythonic, Extensible and Minimal Implemention of Faster RCNN Without Harming Performance
+# A Pythonic, Simple and Fast Implementation of Faster RCNN
 
 ##  Introduction
 
 This project is a **Simplified** Faster RCNN implementation based on [chainercv](https://github.com/chainer/chainercv) and other [projects](#Acknowledgement) . It aims to:
 
 - Simplify the code (*Simple is better than complex*)
-- Make the code more straight forward (*Flat is better than nested*)
+- Make the code more straightforward (*Flat is better than nested*)
 - Match the performance reported in [ origin paper](https://arxiv.org/abs/1506.01497) (*Speed Counts and mAP Matters*)
 
 ##  Performance
 
-- mAP
+### mAP
 
 VGG16 train on `trainval` and test on `test` split. 
 
-**Note**: the training shows great randomness, you may need to train more epoch to reach the highest mAP. However, it should be easy to reach the lowerboud. 
+**Note**: the training shows great randomness, you may need to train more epoch and a bit of luck to reach the highest mAP. However, it should be easy to surpass the lower bound. 
 
 |              Implementation              |     mAP     |
 | :--------------------------------------: | :---------: |
 | [origin paper](https://arxiv.org/abs/1506.01497) |    0.699    |
-| using caffe pretrained model (enable with`--caffe-pretrain`) | 0.702-0.712 |
-|    using torchvision pretrained model    | 0.693-0.701 |
+|    train with caffe pretrained model     | 0.701-0.712 |
+| train with torchvision pretrained model  | 0.685-0.701 |
 | model converted from [chainercv](https://github.com/chainer/chainercv/tree/master/examples/faster_rcnn) (reported 0.706) |   0.7053    |
 
+### Speed
 
-- Speed
+|              Implementation              |   GPU    |  Inference  | Trainining  |
+| :--------------------------------------: | :------: | :---------: | :---------: |
+| [origin paper](https://arxiv.org/abs/1506.01497) |   K40    |    5 fps    |     NA      |
+|                   This                   | TITAN Xp | 12 fps [^1] | 5-6 fps[^2] |
+| [pytorch-faster-rcnn](https://github.com/ruotianluo/pytorch-faster-rcnn) | TITAN Xp |     NA      |   5-6fps    |
 
-|              Implementation              |   GPU    | Inference | Trainining |
-| :--------------------------------------: | :------: | :-------: | :--------: |
-| [origin paper](https://arxiv.org/abs/1506.01497) |   K40    |   5 fps   |     NA     |
-|                   This                   | TITAN Xp | 12 fps^*^ |  5-6 fps   |
-| [pytorch-faster-rcnn](https://github.com/ruotianluo/pytorch-faster-rcnn) | TITAN Xp |    NA     | 5-6fps^**^ |
+[^1]: include reading images from disk, preprocessing, etc. see `eval` in `train.py` for more detail.
+[^2]: it depends on the e
 
-\* include reading images from disk, preprocessing, etc. see `eval` in `train.py` for more detail.
+**NOTE** you should make sure you install cupy correctly to reach the benchmark.
 
-** it depends on the environment.
+## Install dependencies
 
-**NOTE ** you should make sure you install cupy correctly to reach the benchmark.
+requires python3 and PyTorch 0.3
 
-## Install denpendencies
-
-- install PyTorch >=0.3 with GPU (code are gpu-only), refer to [official website](http://pytorch.org)
+- install PyTorch >=0.3 with GPU (code are GPU-only), refer to [official website](http://pytorch.org)
 - install cupy, you can install via `pip install` but it's better to read the [docs](https://docs-cupy.chainer.org/en/latest/install.html#install-cupy-with-cudnn-and-nccl) and make sure the environ is correctly set
 
 
@@ -53,7 +53,7 @@ VGG16 train on `trainval` and test on `test` split.
 nohup python3 -m visdom.server &
 ```
 
-If you're in China and have encounter problem with visdom (i.e. timeout, blank screen), you may refer to [visdom issue](https://github.com/facebookresearch/visdom/issues/111#issuecomment-321743890), ~~and a temporay solution provided by me~~
+If you're in China and have encounter problem with visdom (i.e. timeout, blank screen), you may refer to [visdom issue](https://github.com/facebookresearch/visdom/issues/111#issuecomment-321743890), ~~and a temporary solution provided by me~~
 
 ## Demo
 
@@ -101,38 +101,42 @@ TBD
 
 ### preprare caffe-pretrained vgg16
 
-If you want to use caffe-pretrain model as initial weight, you can run below to get vgg16 weights converte from caffe, which is the same as the origin paper use.
+If you want to use caffe-pretrain model as initial weight, you can run below to get vgg16 weights converted from caffe, which is the same as the origin paper use.
 
 ````
 python misc/convert_caffe_pretrain.py
 ````
 
-Then you should speicified where caffe-pretraind model `vgg16_caffe.pth` stored in `config.py` by setting `caffe_pretrain_path`
+This would download pretrained model and converted it to the format compatible with torchvision. 
+
+Then you should specify where caffe-pretraind model `vgg16_caffe.pth` stored in `config.py` by setting `caffe_pretrain_path`
 
 If you want to use torchvision pretrained model, you may skip this step.
 
-**NOTE that**, caffe pretrained model has showed slight better performance.
+**NOTE**, caffe pretrained model has shown slight better performance.
 
-### begin traininig
+**NOTE**: caffe model require images in BGR 0-255, while torchvision model requires images in RGB and 0-1. See `data/dataset.py`for more detail.
+
+### begin training
 
 ```Bash
 make checkpoints/ # make dir for storing snapshots
 ```
 
 ```bash
-python3 train.py train --env='fasterrcnn-caffe' --plot-every=100 --caffe-pretrain	
+python3 train.py train --env='fasterrcnn-caffe' --plot-every=100 --caffe-pretrain    
 ```
 
 you may refer to `config.py` for more argument.
 
 Some Key arguments:
 
 - `--caffe-pretrain`=True: use caffe pretrain model  or use torchvision pretrained model (Default: torchvison)
-- `--plot-every=n`: visulize predict, loss etc every n batches.
-- `--env`: visdom env for visulization
+- `--plot-every=n`: visualize predict, loss etc every n batches.
+- `--env`: visdom env for visualization
 - `--voc_data_dir`: where the VOC data stored
-- `--use-drop`: use dropout in roi head, default without dropout
-- `--use-adam`: use adam instead of SGD, default SGD. (You need set a very low `lr` for Adam)
+- `--use-drop`: use dropout in ROI head, default without dropout
+- `--use-Adam`: use Adam instead of SGD, default SGD. (You need set a very low `lr` for Adam)
 - `--load-path`: pretrained model path, default `None`, if it's specified, the pretrained model would be loaded.
 
 ## Troubleshooting
@@ -145,17 +149,18 @@ TODO: make it clear
 - vgg
 
 ## TODO
-- [] training on coco
-- [] resnet
-- [] replace cupy with THTensor+cffi?
+
+- [ ] training on coco
+- [ ] resnet
+- [ ] replace cupy with THTensor+cffi?
 
 ## Acknowledge
 This work builds on many excellent works, which include:
 
 - [Yusuke Niitani's ChainerCV](https://github.com/chainer/chainercv) (mainly)
 - [Ruotian Luo's pytorch-faster-rcnn](https://github.com/ruotianluo/pytorch-faster-rcnn) which based on [ Xinlei Chen's tf-faster-rcnn](https://github.com/endernewton/tf-faster-rcnn)
 - [faster-rcnn.pytorch by Jianwei Yang and Jiasen Lu](https://github.com/jwyang/faster-rcnn.pytorch).It's mainly based on [longcw's faster_rcnn_pytorch](https://github.com/longcw/faster_rcnn_pytorch)
-- All the above Repositories  have refer to [py-faster-rcnn by Ross Girshick and Sean Bell](https://github.com/rbgirshick/py-faster-rcnn)  either directly or indirectly. 
+- All the above Repositories have referred to [py-faster-rcnn by Ross Girshick and Sean Bell](https://github.com/rbgirshick/py-faster-rcnn)  either directly or indirectly. 
 
 ## LICENSE