# zhulf0804/pointpillars architecture

> Architecture diagram of the GitHub repository zhulf0804/pointpillars, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhulf0804/pointpillars
- Repository: https://github.com/zhulf0804/pointpillars

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawKITTI["Raw KITTI Files (.bin, .txt, .png)"]:::data
        Preprocess["pre_process_kitti.py"]:::script
        VeloReduced["velodyne_reduced + info .pkl"]:::data
        Dataset["pointpillars/dataset/"]:::data
        DataAug["data_aug.py"]:::data
        KittiIO["kitti.py"]:::data
        DataLoader["dataloader.py"]:::data
        DemoData["demo_data/"]:::data
    end

    RawKITTI -->|"raw files"| Preprocess
    Preprocess -->|"reduced + metadata"| VeloReduced
    VeloReduced -->|"info .pkl"| Dataset
    Dataset --> DataAug
    Dataset --> KittiIO
    Dataset --> DataLoader
    Dataset --> DemoData

    %% Ops Layer
    subgraph "Ops (C++/CUDA Extensions)"
        direction TB
        VoxelModule["voxel_module.py"]:::ops
        VoxelizationOps["voxelization/"]:::ops
        IoU3dModule["iou3d_module.py"]:::ops
        IoU3dOps["iou3d/"]:::ops
    end

    DataLoader -->|"points → pillars"| VoxelModule
    VoxelModule --> VoxelizationOps
    DataLoader -->|"for eval"| IoU3dModule
    IoU3dModule --> IoU3dOps

    %% Model Pipeline
    subgraph "Model Pipeline"
        direction TB
        PillarNet["pointpillars.py"]:::model
        Anchors["anchors.py"]:::model
        LossModule["loss.py"]:::model
    end

    VoxelModule -->|"pillars tensor"| PillarNet
    PillarNet --> Anchors
    PillarNet --> LossModule
    IoU3dModule --> LossModule

    %% Control Layer
    subgraph "Control Layer"
        direction TB
        Train["train.py"]:::script
        Evaluate["evaluate.py"]:::script
        Test["test.py"]:::script
        VisO3D["vis_o3d.py"]:::data
    end

    Train -->|"load data"| DataLoader
    Train -->|"model & loss"| PillarNet
    Train --> LossModule
    Train -->|"checkpoint"| Pretrained
    Evaluate -->|"load data"| DataLoader
    Evaluate --> PillarNet
    Evaluate --> IoU3dModule
    Evaluate -->|"mAP"| Logs
    Test --> PillarNet
    Test --> DemoData
    Test --> VisO3D
    Test --> Figures

    %% Artifacts
    subgraph "Artifacts"
        direction TB
        Pretrained["pretrained/"]:::storage
        Figures["figures/"]:::storage
        Logs["misc/"]:::storage
    end

    %% Click Events
    click Preprocess "https://github.com/zhulf0804/pointpillars/blob/main/pre_process_kitti.py"
    click Dataset "https://github.com/zhulf0804/pointpillars/tree/main/pointpillars/dataset/"
    click DataAug "https://github.com/zhulf0804/pointpillars/blob/main/pointpillars/dataset/data_aug.py"
    click KittiIO "https://github.com/zhulf0804/pointpillars/blob/main/pointpillars/dataset/kitti.py"
    click DataLoader "https://github.com/zhulf0804/pointpillars/blob/main/pointpillars/dataset/dataloader.py"
    click DemoData "https://github.com/zhulf0804/pointpillars/tree/main/pointpillars/dataset/demo_data/"
    click VoxelizationOps "https://github.com/zhulf0804/pointpillars/tree/main/pointpillars/ops/voxelization/"
    click VoxelModule "https://github.com/zhulf0804/pointpillars/blob/main/pointpillars/ops/voxel_module.py"
    click IoU3dOps "https://github.com/zhulf0804/pointpillars/tree/main/pointpillars/ops/iou3d/"
    click IoU3dModule "https://github.com/zhulf0804/pointpillars/blob/main/pointpillars/ops/iou3d_module.py"
    click PillarNet "https://github.com/zhulf0804/pointpillars/blob/main/pointpillars/model/pointpillars.py"
    click Anchors "https://github.com/zhulf0804/pointpillars/blob/main/pointpillars/model/anchors.py"
    click LossModule "https://github.com/zhulf0804/pointpillars/blob/main/pointpillars/loss/loss.py"
    click VisO3D "https://github.com/zhulf0804/pointpillars/blob/main/pointpillars/utils/vis_o3d.py"
    click Train "https://github.com/zhulf0804/pointpillars/blob/main/train.py"
    click Test "https://github.com/zhulf0804/pointpillars/blob/main/test.py"
    click Evaluate "https://github.com/zhulf0804/pointpillars/blob/main/evaluate.py"
    click Pretrained "https://github.com/zhulf0804/pointpillars/tree/main/pretrained/"
    click Figures "https://github.com/zhulf0804/pointpillars/tree/main/figures/"
    click Logs "https://github.com/zhulf0804/pointpillars/tree/main/misc/"

    %% Styling
    classDef data fill:#cce5ff,stroke:#004085,color:#004085
    classDef model fill:#d4edda,stroke:#155724,color:#155724
    classDef ops fill:#fff3cd,stroke:#856404,color:#856404
    classDef script fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef storage fill:#f8d7da,stroke:#721c24,color:#721c24
```
