Getting Started with detrex

This document provides a brief intro of the usage of builtin command-line tools in detrex.

Inference Demo with Pre-trained Models

We’ve provided demo as detectron2 for visualizing the customized input images or videos using pretrained weights.

For visualizing demos:

Pick a model and its config file from projects, for example, dino_swin_large_384_4scale_36ep.
Download the pretrained weights from Model Zoo or the project’s page (take DINO as an example).
Using the provided demo.py to demo the input images or videos. Run it as:

cd detrex/
python demo/demo.py --config-file projects/dino/configs/dino_swin_large_384_4scale_36ep.py \
                    --input input.jpg \
                    --output visualized_results.jpg \
                    --opts train.init_checkpoint="./dino_swin_large_384_4scale_36ep.pth"

To visualize videos:

cd detrex/
python demo/demo.py --config-file projects/dino/configs/dino_swin_large_384_4scale_36ep.py \
                    --video-input ./demo_video.mp4 \
                    --output visualize_video_results.mp4 \
                    --opts train.init_checkpoint="./dino_swin_large_384_4scale_36ep.pth"

For details of the command line arguments, run python demo/demo.py -h or look at its source code to understand its behavior. This demo is modified from detectron2 demo. You can also refer to detectron2 demo documentation for more details.

Data Preparation

In detrex, we use the builtin coco datasets borrowed from detectron2, which has builtin support for a few datasets. The datasets are assumed to exist in a directory specified by the environment variable DETECTRON2_DATASETS. Here we provide the tutorials about the preparation for MSCOCO datasets. For more usage of the detectron2 builtin datasets, please refer to the official documentation: Use Builtin Datasets.

Expected dataset structure for COCO instance 

The dataset structure for MSCOCO 2017 datasets should be as follows:

$DETECTRON2_DATASETS/
  coco/
    annotations/
      instances_{train,val}2017.json
      person_keypoints_{train,val}2017.json
    {train,val}2017/
    # image files that are mentioned in the corresponding json

You can set the location for builtin datasets by export DETECTRON2_DATASETS=/path/to/datasets. If left unset, the default is ./datasets relative to the current working directory.

Training & Evaluation in Command Line

In detrex, we provides tools/train_net.py for launching training & evaluation task.

Training & Evaluation

Here we take dab-detr as example. To train dab-detr using train_net.py, first setup the corresponding MSCOCO 2017 datasets, then run:

cd detrex
python tools/train_net.py \
    --config-file projects/dab_detr/configs/dab_detr_r50_50ep.py

To train on 8 GPUs, you can set --num-gpus 8 as follows:

cd detrex
python tools/train_net.py \
    --config-file projects/dab_detr/configs/dab_detr_r50_50ep.py \
    --num-gpus 8

To evaluate the model performance, use

python tools/train_net.py \
    --config-file projects/dab_detr/configs/dab_detr_r50_50ep.py \
    --eval-only train.init_checkpoint=/path/to/checkpoint

Note: you can directly modify the config in command line like:

cd detrex
python tools/train_net.py \
    --config-file projects/dab_detr/configs/dab_detr_r50_50ep.py \
    --num-gpus 8 train.max_iter=30000

which will directly overide the train.max_iter in config.

Resume Training

If the training is interrupted unexpectly, you can set --resume in command line which will automatically resume training from train.output_dir:

python tools/train_net.py \
    --config-file projects/dab_detr/configs/dab_detr_r50_50ep.py \
    --num-gpus 8 \
    --resume

Fast Debugging

We have set an additional configuration for fast debugging named train.fast_dev_run=bool, which is False by default. if user enables this configuration, we perform it in a straightforward manner by setting train.max_iter=20, train.eval_period=10, train.log_period=1.

To start fast debugging:

python tools/train_net.py \
    --config-file projects/dab_detr/configs/dab_detr_r50_50ep.py \
    --num-gpus 8 \
    train.fast_dev_run.enabled=True