D2Go - Use Detectron2 on mobile devices

D2Go is a production-ready software system from FacebookResearch, which supports end-to-end model training and deployment for mobile platforms.
D2Go
D2Go is a production-ready software system from FacebookResearch, which supports end-to-end model training and deployment for mobile platforms. D2Go provides both built-in command-line tools and an API. This README will walk you through how you can use both the CLI and API to:
- Training a custom model
- Exporting a model to Torchscript
- Quantization-aware Training
Installation
Install PyTorch Nightly (use CUDA 10.2 as an example, see details at PyTorch Website):
Install Detectron2 (other installation options at Detectron2):
Install mobile_cv:
Install d2go:
For more information, check out the installation section of the D2Go README.
Command-line
Inference with a pre-trained model
To run inference with a pre-trained model, navigate into the demo directory, choose a model from model_zoo, e.g. faster_rcnn_fbnetv3a_C4.yaml
, and then run the demo.py
script.
Example usage:
Training a custom model
The CLI also supports training and evaluating custom models, but as far as I know, it only supports the built-in data-sets, including:
- COCO
- LVIS Instance Segmentation
- Cityscapes
- ...
Before training, you need to set up the built-in data-sets. For more information, please follow the instructions on the 'Use Builtin Datasets' page.
To train a model run:
To evaluate a model checkpoint run:
Note: If you want to train on your custom data-set, I highly recommend using the API instead of the CLI.
Exporting to Torchscript & Int8 Model
You can export a trained model to Torchscript using the d2go.exporter
.
Example usage:
The exporter also supports post-training quantization:
Quantization-aware Training
To run quantization-aware training, you need to add the QUANTIZATION
section to your model configuration.
API
D2Go also provides an API, which allows you to use, train and export your models with a syntax very similar to plain Detectron2. As with Detectron2, I recommend using Google Colab for training the model as Google Colab makes it super simple to get setup and start coding.
Inference with a pre-trained model
To use a pre-trained model for inference, load it from the model_zoo using the get
method and create a DemoPredictor
.
The predictions can be displayed using the Visualizer
.
You can find all the available models on the "D2Go Model Zoo and Baselines" site.
Training a custom model
Training a custom model with D2Go is almost identical to using plain Detectron2. First, we need to register the data-set, following the detectron2 custom dataset tutorial.
For the ballon segmentation data-set this looks as follows:
To verify the data loading is correct, let's visualize the annotations of randomly selected samples in the training set:
After verifying that the data loaded correctly, we can fine-tune a COCO-pretrained FBNetV3A Mask R-CNN model on the balloon dataset. For this, we need to modify the default faster_rcnn_fbnetv3a_C4.yaml
config to work with the balloon data-set.
Now that we have created a config for the ballon data-set, we can create a model and start training.
Exporting to Torchscript & Int8 Model
To export the trained model, we need to call the convert_and_export_predictor
method, passing it the config, model, and a dataloader.
After converting the model, we can test it out by creating a predictor.
Deploying model on Android
D2Go can be used on Android using the native torchvision Ops library. The D2Go team provides a D2Go Android demo app that shows how to prepare and use D2Go models on Android. The code is based on a previous PyTorch Android Object Detection demo app that uses a pre-trained YOLOv5 model, with modified pre-processing and post-processing code required by the D2Go model.
Below I'll walk you through the needed steps to get the Android demo work. This is very similar to the README from the demo itself, but it contains a few changes I needed to make to get the demo to work on my machine.
Note: I couldn't get the demo to work on my Windows machine, but it worked on Linux without any problems.
-
Install PyTorch 1.8.0 and torchvision 0.9.0, for example:
-
Install Detectron2, mobile_cv, and D2Go
-
Create the D2Go model
This will create the quantized D2Go model and save it at
android-demo-app/D2Go/ObjectDetection/app/src/main/assets/d2go.pt
.The size of the quantized D2Go model is only 2.6MB.
-
Build and run the D2GO
In Android Studio, openandroid-demo-app/D2Go
(notandroid-demo-app/D2Go/ObjectDetection
). If an error "Gradle’s dependency may be corrupt" occurs, go to Android Studio - File - Project Structure... , change the Android Gradle Plugin Version to 4.0.1, and the Gradle Version to 4.10.1.After selecting the correct Gradle version, the project should build without any errors. Once the build is done, you can deploy the model on your Android device or create an Android emulator.
Result:
Deploying a custom model
To use a custom model with the Android demo, the model first needs to br converted, as shown inside the create_d2go.py file.
Now that the model was converted and saved as d2go.pt
, you need to replace the d2go.pt
file inside the android-demo-app/D2Go/ObjectDetection/app/src/main/assets/
folder with your custom model and modify the classes.txt file to contain your custom classes.