How holmes-alan/pufm works
Project type and purpose
• PUFM is a deep-learning research codebase: a full-stack Python/C++ point-cloud upsampling framework.
• It implements “Efficient Point cloud Upsampling via Flow matching” with custom CUDA/C++ modules for performance.
File structure
• Top-level:
• Chamfer3D/ – Custom chamfer-distance C++/CUDA extension
• args/ – Command-line argument parsers and utilities
• dataset/ – Data-preparation, point-cloud loading, mesh-to-point preprocessing
• emd_assignment/ – Earth Mover’s Distance (EMD) pre-alignment extension
• models/ – PyTorch network definitions + pointops extension library
• pretrained_model/ – Stored .pth model weights
• train_pufm.py, eval_pufm.py, test_pufm*.py – Training & inference scripts
• PUFM_test.ipynb – Colab notebook demo
• Three custom extension builds in models/pointops, Chamfer3D, emd_assignment.
README for additional insights
• The README spells out two preprocessing steps: midpoint interpolation and EMD pre-alignment.
• The core network is implemented in models/diffusion.py and relies on pointops utilities.
• Dependencies: Python 3.9, PyTorch 1.13, Open3D, NumPy, einops, scikit-learn, h5py.
1. User-facing CLI/Notebook layer
2. Dataset Preparation module
3. EMD pre-alignment service (emd_assignment)
4. Midpoint interpolation logic (in dist_chamfer_3D.py and dataset utils)
5. PUFM Model core (models/diffusion.py + pointnet2_util.py)
6. Custom extensions:
• PointOps CUDA kernels (models/pointops/)
• Chamfer3D CUDA modules
7. PyTorch runtime + GPU execution environment
8. Pretrained weights store
9. Output generation & evaluation scripts
b. Relationships & interactions:
• CLI/Notebook invokes dataset/prepare_data → produces point clouds
• Prepared data flows into EMD pre-alignment (emd_assignment) → aligned sparse/dense pairs
• Aligned data is fed to midpoint interpolation → intermediate trajectories
• Result passed to PyTorch training/inference pipeline (train_pufm.py, test_pufm.py)
• The network forward pass calls pointops & Chamfer3D extensions for neighbor search, sampling, and loss
• Pretrained weights load into the PUFM model block
• Outputs (upsampled point clouds) written to disk or visualized in notebook
c. Architectural patterns & principles:
• Modular extension pattern: Python core + compiled C++/CUDA kernels
• Clear separation: data-prep → prealignment → model → output
• Reusable utilities in args/ for configuration management
• Leverages external libs (Open3D for IO, H5py for storage)
d. Key technologies/frameworks:
• Python 3.9, PyTorch 1.13
• CUDA/C++ for performance (PointOps, Chamfer, EMD)
• Open3D, NumPy, einops, scikit-learn