DARDet

PyTorch implementation of "DARDet: A Dense Anchor-free Rotated Object Detector in Aerial Images", [pdf].

Highlights:

1. We develop a new dense anchor-free rotated object detection architecture (DARDet), which directly predicts five parameters of OBB at each spatial location.

2. Our DARDet significantly achieve state-of-the-art performance on the DOTA, UCAS-AOD, and HRSC2016 datasets with high efficiency..

Benchmark and model zoo, with extracting code nudt.

Installation

Prerequisites

• Linux or macOS (Windows is in experimental support)
• Python 3.6+
• PyTorch 1.3+
• CUDA 9.2+ (If you build PyTorch from source, CUDA 9.0 is also compatible)
• GCC 5+
• MMCV

The compatible MMDetection and MMCV versions are as below. Please install the correct version of MMCV to avoid installation issues.

Note: You need to run pip uninstall mmcv first if you have mmcv installed. If mmcv and mmcv-full are both installed, there will be ModuleNotFoundError.

Installation

0. You can simply install mmdetection with the following commands: pip install mmdet

1. Create a conda virtual environment and activate it.

   conda create -n open-mmlab python=3.7 -y
   conda activate open-mmlab

2. Install PyTorch and torchvision following the official instructions, e.g.,

   conda install pytorch torchvision -c pytorch

   Note: Make sure that your compilation CUDA version and runtime CUDA version match. You can check the supported CUDA version for precompiled packages on the PyTorch website.

   E.g.1 If you have CUDA 10.1 installed under /usr/local/cuda and would like to install PyTorch 1.5, you need to install the prebuilt PyTorch with CUDA 10.1.

   conda install pytorch cudatoolkit=10.1 torchvision -c pytorch

3. Install mmcv-full, we recommend you to install the pre-build package as below.

   pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/{cu_version}/{torch_version}/index.html

   Please replace {cu_version} and {torch_version} in the url to your desired one. For example, to install the latest mmcv-full with CUDA 11 and PyTorch 1.7.0, use the following command:

   pip install mmcv-full -f https://download.openmmlab.com/mmcv/dist/cu110/torch1.7.0/index.html

   See here for different versions of MMCV compatible to different PyTorch and CUDA versions. Optionally you can choose to compile mmcv from source by the following command

   git clone https://github.com/open-mmlab/mmcv.git
   cd mmcv
   MMCV_WITH_OPS=1 pip install -e .  # package mmcv-full will be installed after this step
   cd ..

   Or directly run

   pip install mmcv-full

4. Clone the DARDet repository.

   cd DARDet

5. Install build requirements and then install DARDet

   pip install -r requirements/build.txt
   pip install -v -e .  # or "python setup.py develop"
   

6. Install DOTA_devkit

   sudo apt-get install swig
   cd DOTA_devkit/polyiou
   swig -c++ -python csrc/polyiou.i
   python setup.py build_ext --inplace
   

Prepare DOTA dataset.

It is recommended to symlink the dataset root to `ReDet/data`.

Here, we give an example for single scale data preparation of DOTA-v1.5.

First, make sure your initial data are in the following structure.
```
data/dota15
├── train
│   ├──images
│   └── labelTxt
├── val
│   ├── images
│   └── labelTxt
└── test
    └── images
```
Split the original images and create COCO format json. 
```
python DOTA_devkit/prepare_dota1_5.py --srcpath path_to_dota --dstpath path_to_split_1024
```
Then you will get data in the following structure
```
dota15_1024
├── test1024
│   ├── DOTA_test1024.json
│   └── images
└── trainval1024
    ├── DOTA_trainval1024.json
     └── images
```
For data preparation with data augmentation, refer to "DOTA_devkit/prepare_dota1_5_v2.py"

Examples:

Assume that you have already downloaded the checkpoints to work_dirs/DARDet_r50_fpn_1x/.

• Test DARDet on DOTA.

python tools/test.py configs/DARDet/dardet_r50_fpn_1x_dcn_val.py \
    work_dirs/dardet_r50_fpn_1x_dcn_val/epoch_12.pth \ 
    --out work_dirs/dardet_r50_fpn_1x_dcn_val/res.pkl

*If you want to evaluate the result on DOTA test-dev, zip the files in work_dirs/dardet_r50_fpn_1x_dcn_val/result_after_nms and submit it to the evaluation server.

Inference

To inference multiple images in a folder, you can run:

python demo/demo_inference.py ${CONFIG_FILE} ${CHECKPOINT} ${IMG_DIR} ${OUTPUT_DIR}

Train a model

MMDetection implements distributed training and non-distributed training, which uses MMDistributedDataParallel and MMDataParallel respectively.

All outputs (log files and checkpoints) will be saved to the working directory, which is specified by work_dir in the config file.

*Important*: The default learning rate in config files is for 8 GPUs and 2 img/gpu (batch size = 8*2 = 16). According to the Linear Scaling Rule, you need to set the learning rate proportional to the batch size if you use different GPUs or images per GPU, e.g., lr=0.01 for 4 GPUs * 2 img/gpu and lr=0.08 for 16 GPUs * 4 img/gpu.

Train with a single GPU

python tools/train.py ${CONFIG_FILE}

If you want to specify the working directory in the command, you can add an argument --work_dir ${YOUR_WORK_DIR}.

Train with multiple GPUs

./tools/dist_train.sh ${CONFIG_FILE} ${GPU_NUM} [optional arguments]

Optional arguments are:

• --validate (strongly recommended): Perform evaluation at every k (default value is 1, which can be modified like this) epochs during the training.
• --work_dir ${WORK_DIR}: Override the working directory specified in the config file.
• --resume_from ${CHECKPOINT_FILE}: Resume from a previous checkpoint file.

Difference between resume_from and load_from: resume_from loads both the model weights and optimizer status, and the epoch is also inherited from the specified checkpoint. It is usually used for resuming the training process that is interrupted accidentally. load_from only loads the model weights and the training epoch starts from 0. It is usually used for finetuning.

Train with multiple machines

If you run MMDetection on a cluster managed with slurm, you can use the script slurm_train.sh.

./tools/slurm_train.sh ${PARTITION} ${JOB_NAME} ${CONFIG_FILE} ${WORK_DIR} [${GPUS}]

Here is an example of using 16 GPUs to train Mask R-CNN on the dev partition.

./tools/slurm_train.sh dev mask_r50_1x configs/mask_rcnn_r50_fpn_1x.py /nfs/xxxx/mask_rcnn_r50_fpn_1x 16

You can check slurm_train.sh for full arguments and environment variables.

If you have just multiple machines connected with ethernet, you can refer to pytorch launch utility. Usually it is slow if you do not have high speed networking like infiniband.

Contact

Any question regarding this work can be addressed to [email protected].