How zhulf0804/pointpillars works
Project Type and Purpose
• This is a specialized open-source Python/C++ library implementing the PointPillars 3D LiDAR object-detection pipeline on the KITTI dataset.
• It’s neither a full-stack web app nor a microservice suite but a machine learning framework: it ingests raw point clouds, preprocesses them into voxels (“pillars”), runs a PyTorch model with custom CUDA/C++ extensions, and produces detections and visualizations.
High-Level File-Structure Analysis
Top-level scripts & config:
• setup.py / requirements.txt – builds and installs the package (including C++/CUDA ops).
• train.py, test.py, evaluate.py, pre_process_kitti.py – entry points for preprocessing, training, inference, evaluation.
Core package (pointpillars/):
• dataset/ – dataset definitions, data augmentation, loader, KITTI I/O, demo data.
• model/ – network definition (pillar encoder, backbone, detection head, anchors).
• loss/ – loss‐calculation module.
• ops/ – custom C++/CUDA extensions (voxelization, 3D‐IoU).
• utils/ – I/O, processing, visualization.
Artifacts:
• pretrained/ – saved checkpoints & TensorBoard logs.
• figures/, misc/ – docs, logs, demos.
Extracted Key Architecture Insights from README
• Single‐model focus: PointPillars only.
• Dependencies: PyTorch, NumPy, Open3D (for visualization), plus the custom compiled ops.
• Two major pipelines:
a) Preprocessing (“pre_process_kitti.py”) – reduces raw velodyne .bin to “velodyne_reduced”, builds info pickles and DB samples.
b) Model execution: training (train.py), evaluation (evaluate.py), test/inference (test.py).
Main Components & Their Relationships
A. Data Layer
1) KITTI raw files (.bin, .txt, .png)
2) pre_process_kitti.py → generates reduced point clouds + metadata (info .pkl, GT DB)
3) dataset module: data_aug.py, kitti.py, dataloader.py → produces batched tensors of voxel features + coordinates + batch indices
B. Computation Layer
1) ops/voxel_module & ops/voxelization → Python wrappers call C++/CUDA to voxelize points into pillars
2) model/pointpillars.py & anchors.py → encode pillars, apply backbone (CNN) & detection head
3) loss/loss.py → compute classification + regression losses
C. Control Layer (Entry-Point Scripts)
• train.py – orchestrates DataLoader, model, loss, optimizer, checkpointing
• evaluate.py – loads checkpoint, runs validation, computes mAP
• test.py – loads checkpoint, runs inference on demo or full data, calls utils/vis_o3d.py for visualization
D. Persistence & Artifacts
• pretrained/epoch_*.pth – model weights
• summary/events.out.tfevents.* – TensorBoard logs
Important Architectural Patterns & Principles
• Modular package structure: clean separation of dataset, model, ops, loss, utils.
• Extension of Python by custom C++/CUDA modules for performance‐critical voxelization and IoU computations.
• Script-based control layer (no REST/API) – standalone CLI tools.
• Use of PyTorch’snn.Module and DataLoader abstractions.