diff --git a/README.md b/README.md index 6b5858a859054851668e7177bd57f94b66dec591..527ce295dd9af2f1f425d4e414c35909948678a2 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ popular detection projects. Results and models are available in the [Model zoo]( ## Installation -Requirements: +### Requirements - Linux (tested on Ubuntu 16.04 and CentOS 7.2) - Python 2.7+ or 3.4+ @@ -49,29 +49,34 @@ Requirements: > Note: Though mmdetection is compatible with Python 2/3, python 3 is recommended and we do not promise future support for Python 2. -Clone the Detectron repository. +### Install mmdetection + +a. Install PyTorch 0.4.1 and torchvision following the [official instructions](https://pytorch.org/). + +b. Clone the Detectron repository. ```shell git clone https://github.com/open-mmlab/mmdetection.git ``` -Compile cuda extensions. +c. Compile cuda extensions. ```shell cd mmdetection ./compile.sh # or "PYTHON=python3 ./compile.sh" if you use system python3 without virtual environments ``` -Install mmdetection (other dependencies will be installed automatically). +d. Install mmdetection (other dependencies will be installed automatically). ```shell python(3) setup.py install # add --user if you want to install it locally # or "pip install ." ``` -> Note: You need to run the installing step each time you pull updates from github. Git commit id will be written to the version number and also saved in trained models. +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. -Prepare COCO dataset +### Prepare COCO dataset. It is recommended to symlink the dataset root to `$MMDETECTION/data`. @@ -92,6 +97,18 @@ mmdetection ## Inference with pretrained models +### Test a dataset + +- [x] single GPU testing +- [x] multiple GPU testing +- [x] visualize detection results + +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 `--proc_per_gpu <PROCESS_NUM>`. + + To test a dataset and save the results. ```shell @@ -112,14 +129,41 @@ For example, to evaluate Mask R-CNN with 8 GPUs and save the result as `results. python tools/test.py configs/mask_rcnn_r50_fpn_1x.py <CHECKPOINT_FILE> --gpus 8 --out results.pkl --eval bbox segm ``` -Note: Multiple GPU testing cannot achieve linear acceleration. - It is also convenient to visualize the results during testing by adding an argument `--show`. ```shell python tools/test.py <CONFIG_FILE> <CHECKPOINT_FILE> --show ``` +### Test image(s) + +We provide some high-level apis (experimental) to test an image. + +```python +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) +``` + ## Train a model @@ -157,8 +201,6 @@ Expected results in WORK_DIR: - a symbol link to the latest checkpoint -## High-level APIs +## Technical details -We are working on a set of high-level APIs to make it more convenient to -integrate mmdetection into other projects or act as a hands-on tool for -beginners. +Some implementation details and project structures are described in the [technical details](TECHNICAL_DETAILS.md). \ No newline at end of file