Open MMLab Detection Toolbox
mmdetection is an open source object detection toolbox based on PyTorch. It is a part of the open-mmlab project developed by Multimedia Laboratory, CUHK.
One can easily construct a customized object detection framework by combining different components.
Support of multiple frameworks out of box
The toolbox directly supports popular detection frameworks, e.g. Faster RCNN, Mask RCNN, RetinaNet, etc.
All basic bbox and mask operations run on GPUs now. The training speed is about 5% ~ 20% faster than Detectron for different models.
State of the art
This was the codebase of the MMDet team, who won the COCO Detection 2018 challenge.
Apart from mmdetection, we also released a library mmcv for computer vision research, which is heavily depended on by this toolbox.
This project is released under the GPLv3 license.
We provide our baseline results and the comparision with Detectron, the most popular detection projects. Results and models are available in the Model zoo.
a. Install PyTorch 0.4.1 and torchvision following the official instructions.
b. Clone the mmdetection repository.
git clone https://github.com/open-mmlab/mmdetection.git
c. Compile cuda extensions.
cd mmdetection pip install cython # or "conda install cython" if you prefer conda ./compile.sh # or "PYTHON=python3 ./compile.sh" if you use system python3 without virtual environments
d. Install mmdetection (other dependencies will be installed automatically).
python(3) setup.py install # add --user if you want to install it locally # or "pip install ."
Note: You need to run the last step each time you pull updates from github. The git commit id will be written to the version number and also saved in trained models.
It is recommended to symlink the dataset root to
mmdetection ├── mmdet ├── tools ├── configs ├── data │ ├── coco │ │ ├── annotations │ │ ├── train2017 │ │ ├── val2017 │ │ ├── test2017
Here is a script for setting up mmdetection with conda for reference.
We allow to run one or multiple processes on each GPU, e.g. 8 processes on 8 GPU
or 16 processes on 8 GPU. When the GPU workload is not very heavy for a single
process, running multiple processes will accelerate the testing, which is specified
with the argument
To test a dataset and save the results.
python tools/test.py <CONFIG_FILE> <CHECKPOINT_FILE> --gpus <GPU_NUM> --out <OUT_FILE>
To perform evaluation after testing, add
--eval <EVAL_TYPES>. Supported types are:
For example, to evaluate Mask R-CNN with 8 GPUs and save the result as
python tools/test.py configs/mask_rcnn_r50_fpn_1x.py <CHECKPOINT_FILE> --gpus 8 --out results.pkl --eval bbox segm
It is also convenient to visualize the results during testing by adding an argument
python tools/test.py <CONFIG_FILE> <CHECKPOINT_FILE> --show
We provide some high-level apis (experimental) to test an image.
import mmcv from mmcv.runner import load_checkpoint from mmdet.models import build_detector from mmdet.apis import inference_detector, show_result cfg = mmcv.Config.fromfile('configs/faster_rcnn_r50_fpn_1x.py') cfg.model.pretrained = None # construct the model and load checkpoint model = build_detector(cfg.model, test_cfg=cfg.test_cfg) _ = load_checkpoint(model, 'https://s3.ap-northeast-2.amazonaws.com/open-mmlab/mmdetection/models/faster_rcnn_r50_fpn_1x_20181010-3d1b3351.pth') # test a single image img = mmcv.imread('test.jpg') result = inference_detector(model, img, cfg) show_result(img, result) # test a list of images imgs = ['test1.jpg', 'test2.jpg'] for i, result in enumerate(inference_detector(model, imgs, cfg, device='cuda:0')): print(i, imgs[i]) show_result(imgs[i], result)
mmdetection implements distributed training and non-distributed training,
We suggest using distributed training even on a single machine, which is faster, and non-distributed training are left for debugging or other purposes.
mmdetection potentially supports multiple launch methods, e.g., PyTorch’s built-in launch utility, slurm and MPI.
We provide a training script using the launch utility provided by PyTorch.
./tools/dist_train.sh <CONFIG_FILE> <GPU_NUM> [optional arguments]
Supported arguments are:
python tools/train.py <CONFIG_FILE> --gpus <GPU_NUM> --work_dir <WORK_DIR> --validate
Expected results in WORK_DIR:
Some implementation details and project structures are described in the technical details.Share on Twitter Share on Facebook