Point-GNN

本仓库包含我们论文 Point-GNN: 用于点云中3D目标检测的图神经网络 的参考实现，该论文发表于CVPR 2020。

如果您在研究中使用了此代码，请考虑引用我们的工作：

@InProceedings{Point-GNN,
author = {Shi, Weijing and Rajkumar, Ragunathan (Raj)},
title = {Point-GNN: 图神经网络用于点云中的3D目标检测},
booktitle = {IEEE计算机视觉与模式识别会议（CVPR）},
month = {6月},
year = {2020}
}

快速入门

前置条件

我们在此实现中使用TensorFlow 1.15。如果您需要GPU支持，请先安装CUDA。

pip3 install --user tensorflow-gpu==1.15.0

安装其他依赖项：

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数据集

我们使用KITTI 3D目标检测数据集。请从KITTI官网下载数据集，并同时下载3DOP训练/验证划分文件这里。我们在splits/目录下提供了按类别划分的额外文件。建议采用以下文件结构：

DATASET_ROOT_DIR
├── image                    # 左侧彩色图像
│   ├── training
|   |   └── image_2            
│   └── testing
|       └── image_2 
├── velodyne                 # Velodyne点云文件
│   ├── training
|   |   └── velodyne            
│   └── testing
|       └── velodyne 
├── calib                    # 校准文件
│   ├── training
|   |   └──calib            
│   └── testing
|       └── calib 
├── labels                   # 训练标签
│   └── training
|       └── label_2
└── 3DOP_splits              # 划分文件。
    ├── train.txt
    ├── train_car.txt
    └── ...

下载Point-GNN

递归克隆仓库：

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

推理

运行检查点

在验证集上测试：

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

在测试集上测试：

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 在 KITTI 数据集上的推理

位置参数:
  checkpoint_path       检查点路径

可选参数:
  -h, --help            显示帮助信息并退出
  -l LEVEL, --level LEVEL
                        可视化级别，0表示禁用，1表示非阻塞可视化，2表示阻塞。默认=0
  --test                启用测试模型
  --no-box-merge        禁用边界框合并
  --no-box-score        禁用边界框得分
  --dataset_root_dir DATASET_ROOT_DIR
                        KITTI 数据集路径。默认="../dataset/kitti/"
  --dataset_split_file DATASET_SPLIT_FILE
                        KITTI 数据集划分文件路径。默认="DATASET_ROOT_DIR/3DOP_splits/val.txt"
  --output_dir OUTPUT_DIR
                        保存检测结果的路径。默认="CHECKPOINT_PATH/eval/"

性能

安装Kitti原生离线评估工具：

cd kitti_native_evaluation
cmake ./
make

在验证集上评估输出结果：

evaluate_object_offline DATASET_ROOT_DIR/labels/training/label_2/ DIR_TO_SAVE_RESULTS

训练

我们将训练参数放在一个train_config文件中。要开始训练，我们需要train_config和config文件。

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

PointGNN 的训练

位置参数:
  train_config_path     训练配置文件路径
  config_path           配置文件路径

可选参数:
  -h, --help            显示帮助信息并退出
  --dataset_root_dir DATASET_ROOT_DIR
                        KITTI 数据集路径。默认="../dataset/kitti/"
  --dataset_split_file DATASET_SPLIT_FILE
                        KITTI 数据集划分文件路径。默认="DATASET_ROOT_DIR/3DOP_splits/train_config["train_dataset"]"

例如：

python3 train.py configs/car_auto_T3_train_train_config configs/car_auto_T3_train_config

我们强烈建议读者在开始训练前查看train_config文件。一些您可能需要首先调整的常见参数如下：

train_dir     存储检查点和日志的目录。
train_dataset 用于训练的数据集划分文件。
NUM_GPU       使用的GPU数量。我们在参考模型中使用了两块GPU。
              如果您只想使用单块GPU，可能还需要将批量大小减半以节省显存。
              同样地，如果您希望利用更多GPU，可以适当增加批量大小。
              具体细节请参阅train.py文件。

我们还提供了一个评估脚本，用于定期评估检查点。例如：

python3 eval.py configs/car_auto_T3_train_eval_config 

您可以使用TensorBoard查看训练和评估状态：

tensorboard --logdir=./train_dir

许可证

本项目采用MIT许可证授权 - 详情请参阅LICENSE文件。

Point-GNN 快速上手指南

Point-GNN 是一个基于图神经网络（Graph Neural Network）的 3D 点云目标检测模型，发表于 CVPR 2020。本指南帮助中国开发者快速完成环境配置、安装及基础推理与训练。

环境准备

本项目基于 TensorFlow 1.15 开发，需确保系统满足以下要求：

• 操作系统: Linux (推荐 Ubuntu 16.04/18.04)
• Python: Python 3.x
• GPU 支持: 如需使用 GPU 加速，请预先安装 CUDA 10.0 及对应的 cuDNN。
  • CUDA 下载：NVIDIA CUDA Toolkit Archive
• 编译工具: 训练评估脚本需要 cmake 和 make。

安装步骤

1. 克隆项目

递归克隆仓库以获取所有子模块：

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

2. 安装 Python 依赖

建议先配置国内 pip 源（如清华源）以加速下载：

pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple --user tensorflow-gpu==1.15.0
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple --user opencv-python
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple --user open3d-python==0.7.0.0
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple --user scikit-learn
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple --user tqdm
pip3 install -i https://pypi.tuna.tsinghua.edu.cn/simple --user shapely

3. 准备数据集 (KITTI)

本项目使用 KITTI 3D 目标检测数据集。请下载原始数据及 3DOP 划分文件，并按以下结构组织目录：

DATASET_ROOT_DIR
├── image                    # 左侧彩色图像
│   ├── training/image_2            
│   └── testing/image_2 
├── velodyne                 # Velodyne 点云文件
│   ├── training/velodyne            
│   └── testing/velodyne 
├── calib                    # 标定文件
│   ├── training/calib            
│   └── testing/calib 
├── labels                   # 训练标签
│   └── training/label_2
└── 3DOP_splits              # 数据集划分文件 (train.txt, val.txt 等)
    ├── train.txt
    ├── train_car.txt
    └── ...

• 数据集下载：KITTI Official Website
• 3DOP 划分文件下载：imagesets.tar.gz

4. 编译评估工具 (可选)

如需进行离线精度评估，需编译原生评估代码：

cd kitti_native_evaluation
cmake ./
make
cd ..

基本使用

推理 (Inference)

使用预训练权重在验证集或测试集上运行检测。

在验证集上测试：

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

在测试集上测试：

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

注：请将 DATASET_ROOT_DIR 替换为你的数据集根目录路径，DIR_TO_SAVE_RESULTS 替换为结果保存路径。

训练 (Training)

启动训练需要指定训练配置文件 (train_config) 和模型配置文件 (config)。

开始训练示例：

python3 train.py configs/car_auto_T3_train_train_config configs/car_auto_T3_train_config

关键参数调整建议： 在修改配置文件前，请注意以下参数：

• train_dir: 检查点和日志的保存目录。
• NUM_GPU: 使用的 GPU 数量。参考模型使用了 2 张 GPU。
  • 若仅使用 单张 GPU，建议将 batch size 减半以避免显存溢出。
  • 若使用更多 GPU，可相应增加 batch size。

监控训练过程： 使用 TensorBoard 查看训练状态和评估指标：

tensorboard --logdir=./train_dir

定期评估检查点：

python3 eval.py configs/car_auto_T3_train_eval_config