Point-GNN README批注
本文件在原作者基础上进行修改并添加了一些说明，以更适合初学者阅读。
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. Getting Started
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.2 KITTI Dataset
We use the KITTI 3D Object Detection dataset. Please download the dataset from the KITTI website and also download the 3DOP/Mono3D/MV3D KITTI 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/Mono3D/MV3D KITTI train/val split下载下来里面一共四个文件：
test.txt中包含KITTI中所有的test文件名7518个trainval.txt中包含KITTI所有的train文件名，是train.txt+val.txt并集共7481个train.txt中包含KITTI train中挑选的一些文件名作为训练集共3712个val.txt中包含KITTI train中挑选的一些文件名作为验证集共3769个
3DOP_splits中的.txt文件中存储了实际在训练中或者测试中使用的文件名称，也就是KITTI原始的文件不是直接被利用，是经过重新划分之后再使用的。
工程中splits/路径下有四个文件， train_car.txt和train_pedestrian_cyclist.txt互相包含对方没有的文件名，即他俩不是子集关系，同理trainval_car.txt与trainval_pedestrian_cyclist.txt也不是子集关系：
train_car.txt包含3260个文件名称，区间在[0, 7479]，是3DOP/Mono3D/MV3D KITTI train/val split中train.txt的子集占其87.82%，占KITTI train集的43.58%，是trainval_car.txt的子集；train_pedestrian_cyclist.txt包含1210个文件名称，区间在[0, 7476]，是3DOP/Mono3D/MV3D KITTI train/val split中train.txt的子集占其32.60%，占KITTI train集的16.17%，是trainval_pedestrian_cyclist.txt的子集；trainval_car.txt包含6684个文件名称，区间在[1, 7480]，是3DOP/Mono3D/MV3D KITTI train/val split中trainval.txt的子集占其89.35%，占KITTI train集的89.35%；trainval_pedestrian_cyclist.txt包含2486个文件名称，区间在[0, 7480]，是3DOP/Mono3D/MV3D KITTI train/val split中trainval.txt的子集占其33.23%，是将其中包含Pedestrian或Cyclist关键字的文件名提取出来得到的，占KITTI train集的33.23%；
KITTI数据集官网在中国大陆可能已经无法访问，即便使用一般的虚拟专用网络也访问不了，但是可以尝试在手机上使用虚拟专用网络进行访问或者PC使用全局虚拟专用网络模式进行访问。然后拷贝对应文件链接所在地址，并将地址使用下载工具进行下载（如：迅雷，支持断点序传）
1.3 Download Point-GNN
Clone the repository recursively:
git clone https://github.com/WeijingShi/Point-GNN.git --recursive
2. Inference
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
另外，如果你的虚拟环境中没有python 2，则上述指令如果使用python3开头的话有可能会报错找不到模块，此时换为python开头即可。
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/包含data'
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
注：
此处同样由于数据集不在默认路径，故需要指定数据集，可以使用如下指令。同时此程序按照作者原配置每60秒检查一次模型是否更新，故其使用方法是在train.py运行过程中，同时运行此程序，作用是对train.py过程中保存的每个模型进行验证集的验证并生成一个验证TensorBoard文件。
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
4. License
This project is licensed under the MIT License - see the LICENSE file for details
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快速入门参考此视频，几乎够用了。
6. 术语解释
BatchSize：一次训练迭代所选取的样本数；
loss weights：损失权重，用来计算损失函数总的loss的权重；
SGD：随机梯度下降；
learning rate decay：学习率衰减；
stair-case learning-rate decay：阶梯式学习率衰减；
Ablation Study：消融实验；
KITTI Easy, Moderate, Hard：根据目标像素、遮挡和截断情况进行的难易等级分类；
842
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
