DD3D: "Is Pseudo-Lidar needed for Monocular 3D Object detection?"
Install // Datasets // Experiments // Models // License // Reference
Official PyTorch implementation of DD3D: Is Pseudo-Lidar needed for Monocular 3D Object detection? (ICCV 2021), Dennis Park*, Rares Ambrus*, Vitor Guizilini, Jie Li, and Adrien Gaidon.
Installation
We recommend using docker (see nvidia-docker2 instructions) to have a reproducible environment. To setup your environment, type in a terminal (only tested in Ubuntu 18.04):
git clone https://github.com/TRI-ML/dd3d.git
cd dd3d
# If you want to use docker (recommended)
make docker-build # CUDA 10.2
# Alternative docker image for cuda 11.1
# make docker-build DOCKERFILE=Dockerfile-cu111Please check the version of your nvidia driver and cuda compatibility to determine which Dockerfile to use.
We will list below all commands as if run directly inside our container. To run any of the commands in a container, you can either start the container in interactive mode with make docker-dev to land in a shell where you can type those commands, or you can do it in one step:
# single GPU
make docker-run COMMAND="<some-command>"
# multi GPU
make docker-run-mpi COMMAND="<some-command>"If you want to use features related to AWS (for caching the output directory) and Weights & Biases (for experiment management/visualization), then you should create associated accounts and configure your shell with the following environment variables before building the docker image:
export AWS_SECRET_ACCESS_KEY="<something>"
export AWS_ACCESS_KEY_ID="<something>"
export AWS_DEFAULT_REGION="<something>"
export WANDB_ENTITY="<something>"
export WANDB_API_KEY="<something>"You should also enable these features in configuration, such as WANDB.ENABLED and SYNC_OUTPUT_DIR_S3.ENABLED.
Datasets
By default, datasets are assumed to be downloaded in /data/datasets/<dataset-name> (can be a symbolic link). The dataset root is configurable by DATASET_ROOT.
KITTI
The KITTI 3D dataset used in our experiments can be downloaded from the KITTI website. For convenience, we provide the standard splits used in 3DOP for training and evaluation:
# download a standard splits subset of KITTI
curl -s https://tri-ml-public.s3.amazonaws.com/github/dd3d/mv3d_kitti_splits.tar | sudo tar xv -C /data/datasets/KITTI3D
The dataset must be organized as follows:
<DATASET_ROOT>
└── KITTI3D
├── mv3d_kitti_splits
│ ├── test.txt
│ ├── train.txt
│ ├── trainval.txt
│ └── val.txt
├── testing
│ ├── calib
| │ ├── 000000.txt
| │ ├── 000001.txt
| │ └── ...
│ └── image_2
│ ├── 000000.png
│ ├── 000001.png
│ └── ...
└── training
├── calib
│ ├── 000000.txt
│ ├── 000001.txt
│ └── ...
├── image_2
│ ├── 000000.png
│ ├── 000001.png
│ └── ...
└── label_2
├── 000000.txt
├── 000001.txt
└── ..
nuScenes
The nuScenes dataset (v1.0) can be downloaded from the nuScenes website. The dataset must be organized as follows:
<DATASET_ROOT>
└── nuScenes
├── samples
│ ├── CAM_FRONT
│ │ ├── n008-2018-05-21-11-06-59-0400__CAM_FRONT__1526915243012465.jpg
│ │ ├── n008-2018-05-21-11-06-59-0400__CAM_FRONT__1526915243512465.jpg
│ │ ├── ...
│ │
│ ├── CAM_FRONT_LEFT
│ │ ├── n008-2018-05-21-11-06-59-0400__CAM_FRONT_LEFT__1526915243004917.jpg
│ │ ├── n008-2018-05-21-11-06-59-0400__CAM_FRONT_LEFT__1526915243504917.jpg
│ │ ├── ...
│ │
│ ├── ...
│
├── v1.0-trainval
│ ├── attribute.json
│ ├── calibrated_sensor.json
│ ├── category.json
│ ├── ...
│
├── v1.0-test
│ ├── attribute.json
│ ├── calibrated_sensor.json
│ ├── category.json
│ ├── ...
│
├── v1.0-mini
│ ├── attribute.json
│ ├── calibrated_sensor.json
│ ├── category.json
│ ├── ...
Pre-trained DD3D models
The DD3D models pre-trained on dense depth estimation using DDAD15M can be downloaded here:
| backbone | download |
|---|---|
| DLA34 | model |
| V2-99 | model |
(Optional) Eigen-clean subset of KITTI raw.
To train our Pseudo-Lidar detector, we curated a new subset of KITTI (raw) dataset and use it to fine-tune its depth network. This subset can be downloaded here. Each row contains left and right image pairs. The KITTI raw dataset can be download here.
Validating installation
To validate and visualize the dataloader (including data augmentation), run the following:
./scripts/visualize_dataloader.py +experiments=dd3d_kitti_dla34 SOLVER.IMS_PER_BATCH=4To validate the entire training loop (including evaluation and visualization), run the overfit experiment (trained on test set):
./scripts/train.py +experiments=dd3d_kitti_dla34_overfit| experiment | backbone | train mem. (GB) | train time (hr) | train log | Box AP (%) | BEV AP (%) | download |
|---|---|---|---|---|---|---|---|
| config | DLA-34 | 6 | 0.25 | log | 84.54 | 88.83 | model |
Experiments
Configuration
We use hydra to configure experiments, specifically following this pattern to organize and compose configurations. The experiments under configs/experiments describe the delta from the default configuration, and can be run as follows:
# omit the '.yaml' extension from the experiment file.
./scripts/train.py +experiments=<experiment-file> <config-override>The configuration is modularized by various components such as datasets, backbones, evaluators, and visualizers, etc.
Using multiple GPUs
The training script supports (single-node) multi-GPU for training and evaluation via mpirun. This is most conveniently executed by the make docker-run-mpi command (see above).
Internally, IMS_PER_BATCH parameters of the optimizer and the evaluator denote the total size of batch that is sharded across available GPUs while training or evaluating. They are required to be set as a multuple of available GPUs.
Evaluation
One can run only evaluation using the pretrained models:
./scripts/train.py +experiments=<some-experiment> EVAL_ONLY=True MODEL.CKPT=<path-to-pretrained-model>
# use smaller batch size for single-gpu
./scripts/train.py +experiments=<some-experiment> EVAL_ONLY=True MODEL.CKPT=<path-to-pretrained-model> TEST.IMS_PER_BATCH=4Gradient accumulation
If you have insufficient GPU memory for any experiment, you can use gradient accumulation by configuring ACCUMULATE_GRAD_BATCHES, at the cost of longer training time. For instance, if the experiment requires at least 400 of GPU memory (e.g. V2-99, KITTI) and you have only 128 (e.g., 8 x 16G GPUs), then you can update parameters at every 4th step:
# The original batch size is 64.
./scripts/train.py +experiments=dd3d_kitti_v99 SOLVER.IMS_PER_BATCH=16 SOLVER.ACCUMULATE_GRAD_BATCHES=4Models
All experiments here use 8 A100 40G GPUs, and use gradient accumulation when more GPU memory is needed. We subsample nuScenes validation set by a factor of 8 (2Hz ⟶ 0.25Hz) to save training time.
KITTI
| experiment | backbone | train mem. (GB) | train time (hr) | train log | Box AP (%) | BEV AP (%) | download |
|---|---|---|---|---|---|---|---|
| config | DLA-34 | 256 | 4.5 | log | 16.92 | 24.77 | model |
| config | V2-99 | 400 | 9.0 | log | 23.90 | 32.01 | model |
nuScenes
| experiment | backbone | train mem. (GB) | train time (hr) | train log | mAP (%) | NDS | download |
|---|---|---|---|---|---|---|---|
| config | DLA-34 | TBD | TBD | TBD) | TBD | TBD | TBD |
| config | V2-99 | TBD | TBD | TBD | TBD | TBD | TBD |
License
The source code is released under the MIT license. We note that some code in this repository is adapted from the following repositories:
Reference
@inproceedings{park2021dd3d,
author = {Dennis Park and Rares Ambrus and Vitor Guizilini and Jie Li and Adrien Gaidon},
title = {Is Pseudo-Lidar needed for Monocular 3D Object detection?},
booktitle = {IEEE/CVF International Conference on Computer Vision (ICCV)},
primaryClass = {cs.CV},
year = {2021},
}