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 provideddemo as detectron2 for visualizing the customized input images or videos using pretrained weights.

For visualizing demos:

  1. Pick a model and its config file fromprojects, for example,dino_swin_large_384_4scale_36ep.

  2. Download the pretrained weights fromModel Zoo or theproject’s page (take DINO as an example).

  3. Using the provideddemo.py to demo the input images or videos. Run it as:

cddetrex/pythondemo/demo.py--config-fileprojects/dino/configs/dino_swin_large_384_4scale_36ep.py\--inputinput.jpg\--outputvisualized_results.jpg\--optstrain.init_checkpoint="./dino_swin_large_384_4scale_36ep.pth"

To visualize videos:

cddetrex/pythondemo/demo.py--config-fileprojects/dino/configs/dino_swin_large_384_4scale_36ep.py\--video-input./demo_video.mp4\--outputvisualize_video_results.mp4\--optstrain.init_checkpoint="./dino_swin_large_384_4scale_36ep.pth"

For details of the command line arguments, runpythondemo/demo.py-h or look at its source code to understand its behavior. This demo is modified fromdetectron2 demo. You can also refer todetectron2 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 variableDETECTRON2_DATASETS. Here we provide the tutorials about the preparation forMSCOCO datasets. For more usage of the detectron2 builtin datasets, please refer to the official documentation:Use Builtin Datasets.

Expected dataset structure forCOCO instance

The dataset structure forMSCOCO2017 datasets should be as follows:

$DETECTRON2_DATASETS/coco/annotations/instances_{train,val}2017.jsonperson_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 byexportDETECTRON2_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 providestools/train_net.py for launching training & evaluation task.

Training & Evaluation

Here we takedab-detr as example. To traindab-detr usingtrain_net.py, first setup the correspondingMSCOCO2017 datasets, then run:

cddetrexpythontools/train_net.py\--config-fileprojects/dab_detr/configs/dab_detr_r50_50ep.py

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

cddetrexpythontools/train_net.py\--config-fileprojects/dab_detr/configs/dab_detr_r50_50ep.py\--num-gpus8

To evaluate the model performance, use

pythontools/train_net.py\--config-fileprojects/dab_detr/configs/dab_detr_r50_50ep.py\--eval-onlytrain.init_checkpoint=/path/to/checkpoint

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

cddetrexpythontools/train_net.py\--config-fileprojects/dab_detr/configs/dab_detr_r50_50ep.py\--num-gpus8train.max_iter=30000

which will directly overide thetrain.max_iter in config.

Resume Training

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

pythontools/train_net.py\--config-fileprojects/dab_detr/configs/dab_detr_r50_50ep.py\--num-gpus8\--resume

Fast Debugging

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

To start fast debugging:

pythontools/train_net.py\--config-fileprojects/dab_detr/configs/dab_detr_r50_50ep.py\--num-gpus8\train.fast_dev_run.enabled=True