Skip to content

Commit

Permalink
update readme;add requirements.txt
Browse files Browse the repository at this point in the history
  • Loading branch information
@chenyuntc
chenyuntc committed Dec 22, 2017
1 parent 9c07083 commit 6e7b4d2
Show file tree
Hide file tree
Showing 2 changed files with 51 additions and 33 deletions.
75 changes: 42 additions & 33 deletions README.MD
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
A Pythonic, Extensible and Minimal Implemention of Faster RCNN Without Harming Performance
# A Pythonic, Extensible and Minimal Implemention of Faster RCNN Without Harming Performance

## Introduction

This project is a **Simplified** Faster R-CNN implementation mostly based on [chainercv](https://github.com/chainer/chainercv) and Other [projects](#Acknowledgement) . It aims to:
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*)
Expand All @@ -12,52 +12,55 @@ This project is a **Simplified** Faster R-CNN implementation mostly based on [ch

- mAP

VGG16 train on trainval and test on test, Note, the training show great randomness, you may need to train more epoch to reach the highest mAP. However, it should be easy to reach the lowerboud. It's also reported that train it with more epochs may
VGG16 train on `trainval` and test on `test` split.

| Implementation | mAP |
| :--------------------------------------: | ----------- |
| [origin paper](https://arxiv.org/abs/1506.01497) | 0.699 |
**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.

| 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 |
| model converted from [chainercv](https://github.com/chainer/chainercv/tree/master/examples/faster_rcnn) (reported 0.706) | 0.7053 |
| model converted from [chainercv](https://github.com/chainer/chainercv/tree/master/examples/faster_rcnn) (reported 0.706) | 0.7053 |


- Speed

| 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^**^ |
| 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^**^ |

\* include reading images from disk, preprocessing, etc. see `eval` in `train.py` for more detail.

** it depends on the environment.

**NOTE that** you should make sure you install cupy correctly to reach the benchmark.
**NOTE ** you should make sure you install cupy correctly to reach the benchmark.

## Install Prerequisites
## Install denpendencies

- 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


- install other dependencies: `pip install -r requirements.txt `
- Optional but recommended： build `nms_gpu_post`: `cd model/utils/nmspython3 build.py build_ext --inplace`
- build `nms_gpu_post`: `cd model/utils/nms/; python3 build.py build_ext --inplace`
- start vidom for visualize


```
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 temporay solution provided by me~~

## Demo

download pretrained model from [..............................................]
Download pretrained model from [google drive](https://drive.google.com/open?id=1cQ27LIn-Rig4-Uayzy_gH5-cW-NRGVzY).


see `demo.ipynb` for detail
See [demo.ipynb](https://github.com/chenyuntc/Simplified-FasterRCNN/blob/master/demo.ipynb) for more detail.

## Train

Expand Down Expand Up @@ -90,64 +93,70 @@ see `demo.ipynb` for detail
# ... and several other directories ...
```

4. specifiy the `voc_data_dir` in `config.py`, or pass it to program using argument like '--voc-data-dir=/path/to/VOCdevkit/VOC2007/' .
4. specifiy the `voc_data_dir` in `config.py`, or pass it to program using argument like `--voc-data-dir=/path/to/VOCdevkit/VOC2007/` .

#### COCO

TBD

### preprare caffe-pretrained vgg16

if you want to use caffe-pretrain model, you can run:
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.

````
python misc/convert_caffe_pretrain.py
````

then you should speicified where caffe-pretraind model `vgg16_caffe.pth` stored in `config.py`
Then you should speicified 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.

if you want to use torchvision pretrained model, you may skip this.
**NOTE that**, caffe pretrained model has showed slight better performance.

### begin traininig

```Bash
make checkpoints/ # make dir for storing snapshots
```



```
python3 train.py train --env='fasterrcnn-caffe' --plot-every=100 --caffe-pretrain
```bash
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)
- `--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
- `--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
- `--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

TODO: make it clear

- visdom
- dataloader/ulimit
- cupy
- 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)
- [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 refer to [py-faster-rcnn by Ross Girshick and Sean Bell](https://github.com/rbgirshick/py-faster-rcnn) either directly or indirectly.

## LICENSE

MIT, see the LICENSE for more detail.
9 changes: 9 additions & 0 deletions requirements.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
visdom
torchvision
scikit-image
tqdm
fire
pprint
matplotlib
ipdb
git+https://github.com/pytorch/tnt.git@master

0 comments on commit 6e7b4d2

Please sign in to comment.