Relation Networks for Object Detection

The major contributors of this repository include Dazhi Cheng, Jiayuan Gu, Han Hu and Zheng Zhang.

Introduction

Relation Networks for Object Detection is described in an CVPR 2018 oral paper.

Disclaimer

This is an official implementation for Relation Networks for Object Detection based on MXNet. It is worth noting that:

• This repository is tested on official MXNet v1.1.0@(commit 629bb6). You should be able to use it with any version of MXNET that contains required operators like Deformable Convolution.
• We trained our model based on the ImageNet pre-trained ResNet-v1-101 using a model converter. The converted model produces slightly lower accuracy (Top-1 Error on ImageNet val: 24.0% v.s. 23.6%).
• This repository is based on Deformable ConvNets.

License

© Microsoft, 2018. Licensed under an MIT license.

Citing Relation Networks for Object Detection

If you find Relation Networks for Object Detection useful in your research, please consider citing:

@article{hu2017relation,
  title={Relation Networks for Object Detection},
  author={Hu, Han and Gu, Jiayuan and Zhang, Zheng and Dai, Jifeng and Wei, Yichen},
  journal={arXiv preprint arXiv:1711.11575},
  year={2017}
} 

Main Results

Faster RCNN

Deformable Faster RCNN

FPN

Running time is counted on a single Maxwell Titan X GPU (mini-batch size is 1 in inference).

Requirements: Software

1. MXNet from the offical repository. We tested our code on MXNet v1.1.0@(commit 629bb6). Due to the rapid development of MXNet, it is recommended to checkout this version if you encounter any issues. We may maintain this repository periodically if MXNet adds important feature in future release.

2. Python 2.7. We recommend using Anaconda2 as it already includes many common packages. We do not support Python 3 yet, if you want to use Python 3 you need to modify the code to make it work.

3. The following Python packages:

Cython
EasyDict
mxnet-cu80
opencv-python >= 3.2.0

Requirements: Hardware

Any NVIDIA GPUs with at least 6GB memory should be OK.

Installation

1. Clone the Relation Networks for Object Detection repository.

git clone https://github.com/msracver/Relation-Networks-for-Object-Detection.git
cd Relation-Networks-for-Object-Detection

2. Run sh ./init.sh. The scripts will build cython module automatically and create some folders.

3. Install MXNet:

Quick start

3.1 Install MXNet and all dependencies by

pip install -r requirements.txt

If there is no other error message, MXNet should be installed successfully.

Build from source (alternative way)

3.2 Clone MXNet v1.1.0 by

git clone -b v1.1.0 --recursive https://github.com/apache/incubator-mxnet.git

3.3 Compile MXNet

cd ${MXNET_ROOT}
make -j $(nproc) USE_OPENCV=1 USE_BLAS=openblas USE_CUDA=1 USE_CUDA_PATH=/usr/local/cuda USE_CUDNN=1

3.4 Install the MXNet Python binding by

Note: If you will actively switch between different versions of MXNet, please follow 3.5 instead of 3.4

cd python
sudo python setup.py install

3.5 For advanced users, you may put your Python packge into ./external/mxnet/$(YOUR_MXNET_PACKAGE)/mxnet, and modify MXNET_VERSION in ./experiments/relation_rcnn/cfgs/*.yaml to $(YOUR_MXNET_PACKAGE). Thus you can switch among different versions of MXNet quickly.

Preparation for Training & Testing

1. Please download COCO datasets, and make sure it looks like this:

./data/coco/

2. Please download ImageNet-pretrained ResNet-v1-101 backbone model and Faster RCNN ResNet-v1-101 model manually from OneDrive or Baiduyun (password:pech), and put it under folder ./model/pretrained_model. Make sure it looks like this:

./model/pretrained_model/resnet_v1_101-0000.params

We use a pretrained Faster RCNN and fix its params when training Faster RCNN with Learn NMS head. If you are trying to conduct such experiments, please also include the pretrained Faster RCNN model from OneDrive and put it under folder ./model/pretrained_model. Make sure it looks like this:

./model/pretrained_model/coco_resnet_v1_101_rcnn-0008.params

3. For FPN related experiments, we use proposals generated by a pretrained RPN to speed up our experiments. Please download the proposals from OneDrive or Baiduyun (due to its size constraint) part1 (password:g24u) part2 (password:ipa8) and put it under folder ./proposal/resnet_v1_101_fpn/rpn_data. Make sure it looks like this:

   ./proposal/resnet_v1_101_fpn/rpn_data/COCO_minival2014_rpn.pkl
   ./proposal/resnet_v1_101_fpn/rpn_data/COCO_train2014_rpn.pkl
   ./proposal/resnet_v1_101_fpn/rpn_data/COCO_valminusminival2014_rpn.pkl
   

Demo Models

We provide trained relation network models, covering all settings in the above Main Results table.

1. To try out our pre-trained relation network models, please download manually from OneDrive or Baiduyun (password:9q6i), and put it under folder output/.

   Make sure it looks like this:

   ./output/rcnn/coco/resnet_v1_101_coco_trainvalminus_rcnn_end2end_8epoch/train2014_valminusminival2014/rcnn_coco-0008.params
   ./output/rcnn/coco/resnet_v1_101_coco_trainvalminus_rcnn_end2end_relation_8epoch/train2014_valminusminival2014/rcnn_coco-0008.params
   ./output/rcnn/coco/resnet_v1_101_coco_trainvalminus_rcnn_end2end_learn_nms_3epoch/train2014_valminusminival2014/rcnn_coco-0003.params
   ./output/rcnn/coco/resnet_v1_101_coco_trainvalminus_rcnn_end2end_relation_learn_nms_8epoch/train2014_valminusminival2014/rcnn_coco-0008.params
   ./output/rcnn/coco/resnet_v1_101_coco_trainvalminus_rcnn_dcn_end2end_8epoch/train2014_valminusminival2014/rcnn_coco-0008.params
   ./output/rcnn/coco/resnet_v1_101_coco_trainvalminus_rcnn_dcn_end2end_relation_learn_nms_8epoch/train2014_valminusminival2014/rcnn_coco-0008.params
   ./output/rcnn/coco/resnet_v1_101_coco_trainvalminus_rcnn_fpn_8epoch/train2014_valminusminival2014/rcnn_fpn_coco-0008.params
   ./output/rcnn/coco/resnet_v1_101_coco_trainvalminus_rcnn_fpn_relation_learn_nms_8epoch/train2014_valminusminival2014/rcnn_fpn_coco-0008.params
   

2. To run the Faster RCNN with Relation Module and Learn NMS model, run

   python experiments/relation_rcnn/rcnn_test.py --cfg experiments/relation_rcnn/cfgs/resnet_v1_101_coco_trainvalminus_rcnn_end2end_relation_learn_nms_8epoch.yaml --ignore_cache
   

   If you want to try other models, just change the config files. There are ten config files in ./experiments/relation_rcnn/cfg folder, eight of which are provided with pretrained models.

Usage

1. All of our experiment settings (GPU #, dataset, etc.) are kept in yaml config files at folder ./experiments/relation_rcnn/cfgs.

2. Ten config files have been provided so far, namely, Faster RCNN, Deformable Faster RCNN and FPN with 2FC head, 2FC + Relation Head and 2FC + Relation + Learn NMS(e2e), and an additional Faster RCNN with 2FC + Learn NMS head. We use 4 GPUs to train our models.

3. To perform experiments, run the python scripts with the corresponding config file as input. For example, to train and test Faster RCNN with Relation Module and Learn NMS(e2e), use the following command:

   python experiments\relation_rcnn\rcnn_end2end_train_test.py --cfg experiments/relation_rcnn/cfgs/resnet_v1_101_coco_trainvalminus_rcnn_end2end_relation_learn_nms_8epoch.yaml
   

   A cache folder would be created automatically to save the model and the log under output/rcnn/.

   The rcnn_end2end_train_test.py script is for Faster RCNN and Deformable Faster RCNN experiments that train RPN together with RCNN. To train and test FPN which use previously generated proposals, use the following command:

   python experiments\relation_rcnn\rcnn_train_test.py --cfg experiments/relation_rcnn/cfgs/resnet_v1_101_coco_trainvalminus_fpn_relation_learn_nms_8epoch.yaml
   

4. Please find more details in config files and in our code.

FAQ

Q: I encounter segment fault at the beginning.

A: A compatibility issue has been identified between MXNet and opencv-python 3.0+. We suggest that you always import cv2 first before import mxnet in the entry script.