Point-GNN README批注

Point-GNN README批注

• Point-GNN
• • Getting Started
  • • Prerequisites
    • KITTI Dataset
    • Download Point-GNN
  • Inference
  • • Run a checkpoint
    • Performance
  • Training
  • License

本文件在原作者基础上进行修改，以更适合初学者阅读

Point-GNN

This repository contains a reference implementation of our Point-GNN: Graph Neural Network for 3D Object Detection in a Point Cloud, CVPR 2020.

If you find this code useful in your research, please consider citing our work:

@InProceedings{Point-GNN,
author = {Shi, Weijing and Rajkumar, Ragunathan (Raj)},
title = {Point-GNN: Graph Neural Network for 3D Object Detection in a Point Cloud},
booktitle = {The IEEE Conference on Computer Vision and Pattern Recognition (CVPR)},
month = {June},
year = {2020}
}

Getting Started Prerequisites

We use Tensorflow 1.15 for this implementation. Please install CUDA if you want GPU support.

pip3 install --user tensorflow-gpu==1.15.0

To install other dependencies:

pip3 install --user opencv-python
pip3 install --user open3d-python==0.7.0.0
pip3 install --user scikit-learn
pip3 install --user tqdm
pip3 install --user shapely

KITTI Dataset

We use the KITTI 3D Object Detection dataset. Please download the dataset from the KITTI website and also download the 3DOP train/val split here. We provide extra split files for seperated classes in splits/. We recommand the following file structure:

DATASET_ROOT_DIR
├── image                    #  Left color images
│   ├── training
|   |   └── image_2            
│   └── testing
|       └── image_2 
├── velodyne                 # Velodyne point cloud files
│   ├── training
|   |   └── velodyne            
│   └── testing
|       └── velodyne 
├── calib                    # Calibration files
│   ├── training
|   |   └──calib            
│   └── testing
|       └── calib 
├── labels                   # Training labels
│   └── training
|       └── label_2
└── 3DOP_splits              # split files.
    ├── train.txt
    ├── train_car.txt
    └── ...

注：KITTI数据集官网在中国大陆可能已经无法访问，即便使用一般的虚拟专用网络也访问不了，但是可以尝试在手机上使用虚拟专用网络进行访问或者PC使用全局虚拟专用网络模式进行访问。

然后拷贝对应文件链接所在地址，并将地址使用下载工具进行下载（如：迅雷，支持断点序传）

Download Point-GNN

Clone the repository recursively:

git clone https://github.com/WeijingShi/Point-GNN.git --recursive

Inference Run a checkpoint

Test on the validation split:

python3 run.py checkpoints/car_auto_T3_train/ --dataset_root_dir DATASET_ROOT_DIR --output_dir DIR_TO_SAVE_RESULTS

Test on the test dataset:

python3 run.py checkpoints/car_auto_T3_trainval/ --test --dataset_root_dir DATASET_ROOT_DIR --output_dir DIR_TO_SAVE_RESULTS

usage: run.py [-h] [-l LEVEL] [--test] [--no-box-merge] [--no-box-score]
              [--dataset_root_dir DATASET_ROOT_DIR]
              [--dataset_split_file DATASET_SPLIT_FILE]
              [--output_dir OUTPUT_DIR]
              checkpoint_path

Point-GNN inference on KITTI

positional arguments:
  checkpoint_path       Path to checkpoint

optional arguments:
  -h, --help            show this help message and exit
  -l LEVEL, --level LEVEL
                        Visualization level, 0 to disable,1 to nonblocking
                        visualization, 2 to block.Default=0
  --test                Enable test model
  --no-box-merge        Disable box merge.
  --no-box-score        Disable box score.
  --dataset_root_dir DATASET_ROOT_DIR
                        Path to KITTI dataset. Default="../dataset/kitti/"
  --dataset_split_file DATASET_SPLIT_FILE
                        Path to KITTI dataset split
                        file.Default="DATASET_ROOT_DIR/3DOP_splits/val.txt"
  --output_dir OUTPUT_DIR
                        Path to save the detection
                        resultsDefault="CHECKPOINT_PATH/eval/"

注：
DATASET_ROOT_DIR是指的本地KITTI的数据路径，直接将对应的文件夹托入终端中替换该字段即可；DIR_TO_SAVE_RESULTS指本地将要存放结果的文件夹路径，托入希望存入的文件夹即可。

另外，如果希望可视化识别结果需要使用关键字“–level”，如其help打印信息所示：0-不使能可视化，1-非阻塞模式可视化（连续显示帧序列的识别结果），2-阻塞模式（每识别一帧都将停下等待 *** 作）。

若设置为1则需在第一帧显示的点云画面上拖动鼠标调整号视角，然后按“q”，则设置好了观察视角，程序将会可视化点云序列。

例如：以上文件指令在本地计算机器上，并且设置非阻塞可视化，可以使用如下指令代替：

python3 run.py checkpoints/car_auto_T3_train/ --dataset_root_dir '/media/bit202/TOSHIBA EXT/数据集/KITTI/object' --output_dir '/media/bit202/TOSHIBA EXT/数据集/KITTI' --level 1

或者

python3 run.py checkpoints/car_auto_T3_trainval/ --test --dataset_root_dir '/media/bit202/TOSHIBA EXT/数据集/KITTI/object'  --output_dir '/media/bit202/TOSHIBA EXT/数据集/KITTI'  --level 1

Performance

Install kitti_native_evaluation offline evaluation:

cd kitti_native_evaluation
cmake ./
make

Evaluate output results on the validation split:

evaluate_object_offline DATASET_ROOT_DIR/labels/training/label_2/ DIR_TO_SAVE_RESULTS

注：<\br>
该指令使用时，路径中的空格需要使用转义符号“\”，如下所示

./evaluate_object_offline '/media/bit202/TOSHIBA\ EXT/数据集/KITTI/object/labels/training/label_2' '/media/bit202/TOSHIBA\ EXT/数据集/KITTI/test_model/data' 

Training

We put training parameters in a train_config file. To start training, we need both the train_config and config.
注：“train_config”和“config”的写法是简写，

例如：“car_auto_T2_train_train_config”和“car_auto_T3_train_config”两个文件就是“car_auto_T3_train”的train_config”和“config”文件。

usage: train.py [-h] [--dataset_root_dir DATASET_ROOT_DIR]
                [--dataset_split_file DATASET_SPLIT_FILE]
                train_config_path config_path

Training of PointGNN

positional arguments:
  train_config_path     Path to train_config
  config_path           Path to config

optional arguments:
  -h, --help            show this help message and exit
  --dataset_root_dir DATASET_ROOT_DIR
                        Path to KITTI dataset. Default="../dataset/kitti/"
  --dataset_split_file DATASET_SPLIT_FILE
                        Path to KITTI dataset split file.Default="DATASET_ROOT
                        _DIR/3DOP_splits/train_config["train_dataset"]"

For example:

python3 train.py configs/car_auto_T3_train_train_config configs/car_auto_T3_train_config

注：按照train.py的帮助文件描述，若路径不是默认路径，我们还需指定–dataset_root_dir和–dataset_split_file两个字段的路径。

另外需要注意DATASET_SPLIT_FILE的默认路径帮助文件没有更新，git下来的工程中文件存放在“splits/train_car.txt”中。

故在本地计算机上可以使用下面指令运行

python3 train.py --dataset_root_dir '/media/bit202/TOSHIBA EXT/数据集/KITTI/object' --dataset_split_file '/home/bit202/Programs/Point-GNN/splits/train_car.txt'  configs/car_auto_T3_train_train_config configs/car_auto_T3_train_config

We strongly recommand readers to view the train_config before starting the training.
Some common parameters which you might want to change first:

train_dir     The directory where checkpoints and logs are stored.
train_dataset The dataset split file for training. 
NUM_GPU       The number of GPUs to use. We used two GPUs for the reference model. 
              If you want to use a single GPU, you might also need to reduce the batch size by half to save GPU memory.
              Similarly, you might want to increase the batch size if you want to utilize more GPUs. 
              Check the train.py for details.               

We also provide an evaluation script to evaluate the checkpoints periodically. For example:

python3 eval.py configs/car_auto_T3_train_eval_config 

注：

此处同样由于数据集不在默认路径，故需要指定数据集，可以使用如下指令

python3 eval.py --dataset_root_dir '/media/bit202/TOSHIBA EXT/数据集/KITTI/object' configs/car_auto_T3_train_eval_config 

You can use tensorboard to view the training and evaluation status.

tensorboard --logdir=./train_dir

注：

“logdir”是指tensorflow的tfevents存储路径，如需使用，该路径默认位置为工程下的“checkpoints”文件夹上，例如可以使用如下指令，且不可将文件夹拖拽进入终端，因为该指令不能识别“'”符号。

tensorboard --logdir=./checkpoints/car_auto_T3_train

License

This project is licensed under the MIT License - see the LICENSE file for details