# holmes-alan/pufm architecture

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

- Interactive diagram: https://gitdiagram.com/holmes-alan/pufm
- Repository: https://github.com/holmes-alan/pufm

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        CLI["train_pufm.py"]:::pythonModule
        Eval["eval_pufm.py"]:::pythonModule
        Test1["test_pufm.py"]:::pythonModule
        Test2["test_pufm_arbitrary.py"]:::pythonModule
        Notebook["PUFM_test.ipynb"]:::pythonModule
    end

    %% Configuration Utilities
    subgraph "Configuration"
        ArgParse["pufm_args.py"]:::pythonModule
        ArgsUtil["utils.py"]:::pythonModule
    end

    %% Dataset Preparation Module
    subgraph "Dataset Preparation"
        Prepare["prepare_data.py"]:::pythonModule
        DataLoader["dataset.py"]:::pythonModule
        DataUtils["utils.py"]:::pythonModule
    end

    %% EMD Pre-alignment
    subgraph "EMD Pre-alignment"
        EMDWrapper["emd_module.py"]:::pythonModule
        EMDcpp["emd.cpp"]:::compiledExt
        EMDcu["emd_cuda.cu"]:::compiledExt
        EMDSetup["setup.py"]:::pythonModule
    end

    %% Midpoint Interpolation (Chamfer)
    subgraph "Midpoint Interpolation"
        ChamferPy["dist_chamfer_3D.py"]:::pythonModule
        ChamferCPP["chamfer_cuda.cpp"]:::compiledExt
        ChamferCU["chamfer3D.cu"]:::compiledExt
        ChamferSetup["setup.py"]:::pythonModule
    end

    %% PUFM Model Core
    subgraph "PUFM Model Core"
        Diffusion["diffusion.py"]:::pythonModule
        PointNet["pointnet2_util.py"]:::pythonModule
        ModelUtils["utils.py"]:::pythonModule
    end

    %% PointOps Extension
    subgraph "PointOps Extension"
        POInterface["pointops.py"]:::pythonModule
        POSetup["setup.py"]:::pythonModule
    end

    %% Pretrained Weights Store
    Store1["pufm.pth"]:::dataStore
    Store2["pufm_w_attn.pth"]:::dataStore

    %% Output & Evaluation
    subgraph "Output & Evaluation"
        Output["Upsampled Point Clouds"]:::dataStore
    end

    %% External Libraries
    subgraph "External Libraries"
        Open3D["Open3D"]:::externalLib
        NumPy["NumPy"]:::externalLib
        PyTorch["PyTorch"]:::externalLib
        Einops["einops"]:::externalLib
        SKlearn["scikit-learn"]:::externalLib
        H5py["h5py"]:::externalLib
    end

    %% GPU Compute Node
    GPU["GPU Compute"]:::gpuOutline

    %% Data Flows and Dependencies
    CLI -->|"uses args"| ArgParse
    Eval -->|"uses args"| ArgParse
    Test1 -->|"uses args"| ArgParse
    Test2 -->|"uses args"| ArgParse
    CLI --> ArgsUtil
    Eval --> ArgsUtil
    Test1 --> ArgsUtil
    Test2 --> ArgsUtil

    CLI --> Prepare
    Notebook --> Prepare
    Prepare --> DataLoader
    DataLoader --> EMDWrapper
    DataUtils --> Prepare
    EMDcpp --> EMDWrapper
    EMDcu --> EMDWrapper
    EMDWrapper --> ChamferPy
    ChamferCPP --> ChamferPy
    ChamferCU --> ChamferPy
    ChamferPy --> Diffusion
    Diffusion --> GPU
    PointNet --> GPU
    POInterface --> Diffusion
    POInterface --> GPU

    Store1 --> Diffusion
    Store2 --> Diffusion

    Diffusion --> Output
    Test1 --> Output
    Test2 --> Output
    Eval --> Output

    Open3D --> DataLoader
    H5py --> DataLoader
    NumPy --> Prepare
    PyTorch --> Diffusion
    Einops --> Diffusion
    SKlearn --> DataUtils

    %% Click Events
    click CLI "https://github.com/holmes-alan/pufm/blob/main/train_pufm.py"
    click Eval "https://github.com/holmes-alan/pufm/blob/main/eval_pufm.py"
    click Test1 "https://github.com/holmes-alan/pufm/blob/main/test_pufm.py"
    click Test2 "https://github.com/holmes-alan/pufm/blob/main/test_pufm_arbitrary.py"
    click Notebook "https://github.com/holmes-alan/pufm/blob/main/PUFM_test.ipynb"
    click ArgParse "https://github.com/holmes-alan/pufm/blob/main/args/pufm_args.py"
    click ArgsUtil "https://github.com/holmes-alan/pufm/blob/main/args/utils.py"
    click Prepare "https://github.com/holmes-alan/pufm/blob/main/dataset/prepare_data.py"
    click DataLoader "https://github.com/holmes-alan/pufm/blob/main/dataset/dataset.py"
    click DataUtils "https://github.com/holmes-alan/pufm/blob/main/dataset/utils.py"
    click EMDWrapper "https://github.com/holmes-alan/pufm/blob/main/emd_assignment/emd_module.py"
    click EMDcpp "https://github.com/holmes-alan/pufm/blob/main/emd_assignment/emd_assignment/emd.cpp"
    click EMDcu "https://github.com/holmes-alan/pufm/blob/main/emd_assignment/emd_assignment/emd_cuda.cu"
    click EMDSetup "https://github.com/holmes-alan/pufm/blob/main/emd_assignment/setup.py"
    click ChamferPy "https://github.com/holmes-alan/pufm/blob/main/Chamfer3D/dist_chamfer_3D.py"
    click ChamferCPP "https://github.com/holmes-alan/pufm/blob/main/Chamfer3D/chamfer_cuda.cpp"
    click ChamferCU "https://github.com/holmes-alan/pufm/blob/main/Chamfer3D/chamfer3D.cu"
    click ChamferSetup "https://github.com/holmes-alan/pufm/blob/main/Chamfer3D/setup.py"
    click Diffusion "https://github.com/holmes-alan/pufm/blob/main/models/diffusion.py"
    click PointNet "https://github.com/holmes-alan/pufm/blob/main/models/pointnet2_util.py"
    click ModelUtils "https://github.com/holmes-alan/pufm/blob/main/models/utils.py"
    click POInterface "https://github.com/holmes-alan/pufm/blob/main/models/pointops/functions/pointops.py"
    click POSetup "https://github.com/holmes-alan/pufm/blob/main/models/pointops/setup.py"
    click Store1 "https://github.com/holmes-alan/pufm/blob/main/pretrained_model/pufm.pth"
    click Store2 "https://github.com/holmes-alan/pufm/blob/main/pretrained_model/pufm_w_attn.pth"

    %% Styles
    classDef pythonModule fill:#cfe2f3,stroke:#333,stroke-width:1px
    classDef compiledExt fill:#f8d7da,stroke:#900,stroke-width:1px
    classDef dataStore fill:#fff3cd,stroke:#995500,stroke-width:1px
    classDef externalLib fill:#d1e7dd,stroke:#0a3,stroke-width:1px
    classDef gpuOutline fill:none,stroke:#000,stroke-width:2px,stroke-dasharray: 5 5
```
