How stevenygd/pointflow works
Project Type & Purpose
• PointFlow is a research-oriented PyTorch codebase for 3D point-cloud generation using continuous normalizing flows (CNFs).
• It provides data ingestion, model definition, training loops, custom metrics (including CUDA/C++ extensions), and demo/visualization scripts.
High-Level File-Structure Analysis
• Root scripts:
– train.py, demo.py, test.py drive training, inference & evaluation.
– args.py / utils.py handle CLI parsing and helper routines.
• models/: CNF, flow and network definitions (odefunc.py, cnf.py, flow.py, networks.py, normalization.py, diffeq_layers.py)
• metrics/: pure‐Python evaluation_metrics + a PyTorch C++/CUDA structural-loss extension (pybind, .cu/.cpp)
• datasets.py: data loader & preprocessing for ShapeNet point clouds
• scripts/: shell wrappers to launch single/multi-GPU training, testing & demos
Important Dependencies (from README)
– Python 3.6, PyTorch ≥1.0.1, torchdiffeq, CUDA10.0, G++/GCC5+, Open3D (for demo), Tensorboard (optional)
– Conda env.yaml, install.sh to compile C++/CUDA metric kernels
Main Components & Their Interactions
A. Data Layer
– ShapeNet Point Clouds (Data Storage)
→ datasets.py / PyTorch DataLoader
→ feeds batches of point sets to the Trainer
B. Model Layer
– Continuous Normalizing Flow modules (models/cnf.py, flow.py)
– ODE function wrappers (models/odefunc.py, diffeq_layers.py)
– Neural network architectures (models/networks.py)
– Normalization utilities (models/normalization.py)
These sub-components are wired together inside the Trainer.
C. Training & Orchestration
– train.py: main training loop (forward, loss, backward)
– args.py: CLI parameter parsing
– utils.py: logging, checkpoint I/O, Tensorboard hooks
– scripts/*.sh: wrapper scripts that set CUDA_VISIBLE_DEVICES, GPUs, checkpoints paths
D. Loss & Metrics
– evaluation_metrics.py: Python implementations of EMD/CD and other metrics
– pytorch_structural_losses (pybind C++/CUDA): high-performance Earth-Mover and Chamfer distance kernels
– install.sh + setup.py compile these into a PyTorch extension
→ Trainer calls both pure-Python and compiled metrics for loss and evaluation
E. Demo & Visualization
– demo.py + scripts/shapenet_*_demo.sh
→ torch model inference (sampling via CNF inverse)
→ outputs to disk and visualizes via Open3D
F. Persistence & Outputs
– Model checkpoints (.pth)
– Logs & Tensorboard summaries
– Demo point cloud files under demo/
G. External Services & Tools
– Conda environment (env.yaml)
– Tensorboard server for training curves
– Open3D for demo visualization
Architectural Patterns & Design Principles
– Modular layering: Data / Model / Training / Metrics / Demo separated into folders
– Plugin-style extension: C++/CUDA metrics compiled via pybind for performance
– Pipeline pattern: linear flow from data ingestion → model → loss → update → evaluation
– Script orchestration: reusable shell scripts to manage multi-GPU setups