Point-GNN README批注
Point-GNN README批注
- 1. Point-GNN
-
- 1.1 Getting Started
-
- 1.1.1 Prerequisites
- 1.1.2 KITTI Dataset
- 1.1.3 Download Point-GNN
- 1.2 Inference
-
- 1.2.1 Run a checkpoint
- 1.2.2 Performance
- 1.3 Training
- 1.4 License
- 1.5 工程中文件夹
- 1.6 术语解释
本文件在原作者基础上进行修改并添加了一些说明，以更适合初学者阅读。
1. 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}
}
1.1 Getting Started
1.1.1 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
1.1.2 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
└── ...
注：
3DOP_splits中的txt文件中存储了实际在训练中或者测试中使用的文件名称，也就是KITTI原始的文件不是直接被利用，是经过重新划分之后再使用的。
KITTI数据集官网在中国大陆可能已经无法访问，即便使用一般的虚拟专用网络也访问不了，但是可以尝试在手机上使用虚拟专用网络进行访问或者PC使用全局虚拟专用网络模式进行访问。然后拷贝对应文件链接所在地址，并将地址使用下载工具进行下载（如：迅雷，支持断点序传）
1.1.3 Download Point-GNN
Clone the repository recursively:
git clone https://github.com/WeijingShi/Point-GNN.git --recursive
1.2 Inference
1.2.1 Run a checkpoint
本工程自带了已经预先训练的神经网络检查点（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
1.2.2 Performance
上一步生成了结果数据，这一步可以使用kitti_native_evaluation进行本地评估，评估标准与KITTI官方评估标准相同。
Install kitti_native_evaluation offline evaluation:
cd kitti_native_evaluation
cmake ./
make
但是由于KITTI只给出了训练集的标注信息，没给出测试集（官方评估用，不对公众开放）训练信息，所以只能在从训练集分出的验证集上进行评估，Evaluate output results on the validation split:
evaluate_object_offline DATASET_ROOT_DIR/labels/training/label_2/ DIR_TO_SAVE_RESULTS
注：
kitti_native_evaluation是一个第三方开源库，用于本地评估神经网络的在KITTI数据集上的表现，该指令使用时，路径中的空格需要使用转义符号“\”，如下所示
./evaluate_object_offline '/media/bit202/TOSHIBA\ EXT/数据集/KITTI/object/labels/training/label_2' '/media/bit202/TOSHIBA\ EXT/数据集/KITTI/test_model/data'
1.3 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
1.4 License
This project is licensed under the MIT License - see the LICENSE file for details
1.5 工程中文件夹
Point-GNN
├── configs #存储train.py, run.py和eval.py所需要的配置信息，使用json格式书写，
│ ├── *_config #存储了MLP的配置参数等
│ ├── *_train_config #存储了环境的相关配置，如GPU等
│ ├── *_trainval_config #存储了MLP的配置参数等
│ └── *_eval_config #应该是评估函数eval.py的配置信息
├── dataset #
│ └── kitti_dataset.py #数据集处理函数程序
├── models #GNN模型的相关程序
│ ├── preprocess.py #1.前处理函数，增强附加信息s
│ └── crop_aug.py #2.调用1中的函数，进行数据增强（Data Augmentation）
├── util
│ └── config_util.py #处理配置文件的相关函数，调用json库处理
│
注：
json快速入门参考此视频，几乎够用了。
1.6 术语解释
BatchSize：一次训练迭代所选取的样本数；
loss weights：损失权重，用来计算损失函数总的loss的权重；
SGD：随机梯度下降；
learning rate decay：学习率衰减；
stair-case learning-rate decay：阶梯式学习率衰减；
Ablation Study：消融实验；
KITTI Easy, Moderate, Hard：根据目标像素、遮挡和截断情况进行的难易等级分类；