# stevenygd/pointflow architecture

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

- Interactive diagram: https://gitdiagram.com/stevenygd/pointflow
- Repository: https://github.com/stevenygd/pointflow

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Layer"
        DataStorage[(ShapeNet Point Clouds)]:::data
        Datasets["datasets.py"]:::python
    end
    DataStorage -->|"loads"| Datasets
    Datasets -->|"feeds batches"| Train

    subgraph "Model Layer"
        CNF["models/cnf.py"]:::python
        Flow["models/flow.py"]:::python
        ODEF["models/odefunc.py"]:::python
        DEQL["models/diffeq_layers.py"]:::python
        Nets["models/networks.py"]:::python
        Norm["models/normalization.py"]:::python
    end
    Train -->|"forward/backward"| CNF
    CNF --> Flow
    CNF --> ODEF
    ODEF --> DEQL
    Flow --> Nets
    Nets --> Norm

    subgraph "Training & Orchestration"
        Train["train.py"]:::python
        Args["args.py"]:::python
        Utils["utils.py"]:::python
        Scripts["scripts/*.sh"]:::python
    end
    Datasets --> Train
    Args --> Train
    Utils --> Train
    Scripts --> Train
    Train --> CNF
    Train --> EvalMetrics
    Train -->|"checkpoints & logs"| Checkpoints
    Train -->|"tensorboard"| Tensorboard

    subgraph "Loss & Metrics"
        EvalMetrics["metrics/evaluation_metrics.py"]:::python
        PSrc{{"metrics/pytorch_structural_losses/src"}}:::compiled
        PyBind{{"metrics/pytorch_structural_losses/pybind/bind.cpp"}}:::compiled
        Setup["metrics/pytorch_structural_losses/setup.py"]:::python
    end
    Setup --> PSrc
    Setup --> PyBind
    EvalMetrics --> Train
    PSrc --> Train
    PyBind --> Train

    subgraph "Demo & Visualization"
        DemoScript["demo.py"]:::python
        DemoShell["scripts/shapenet_*_demo.sh"]:::python
        Open3D[(Open3D)]:::external
    end
    DemoScript --> CNF
    DemoScript --> Open3D
    DemoShell --> DemoScript

    subgraph "Persistence & Outputs"
        Env[(env.yaml)]:::external
        Install["install.sh"]:::python
        Docs[(docs/)]:::external
        Checkpoints[(.pth Checkpoints)]:::data
        DemoOut[(demo/ outputs)]:::data
    end
    Install --> PSrc
    Install --> PyBind
    Install --> Setup
    Train --> DemoOut

    subgraph "External Services & Tools"
        Conda[(Conda Env)]:::external
        TBServer[(Tensorboard Server)]:::external
    end
    Env --> Conda
    TBServer --> Utils

    %% Click Events
    click Datasets "https://github.com/stevenygd/pointflow/blob/master/datasets.py"
    click CNF "https://github.com/stevenygd/pointflow/blob/master/models/cnf.py"
    click Flow "https://github.com/stevenygd/pointflow/blob/master/models/flow.py"
    click ODEF "https://github.com/stevenygd/pointflow/blob/master/models/odefunc.py"
    click DEQL "https://github.com/stevenygd/pointflow/blob/master/models/diffeq_layers.py"
    click Nets "https://github.com/stevenygd/pointflow/blob/master/models/networks.py"
    click Norm "https://github.com/stevenygd/pointflow/blob/master/models/normalization.py"
    click Train "https://github.com/stevenygd/pointflow/blob/master/train.py"
    click Args "https://github.com/stevenygd/pointflow/blob/master/args.py"
    click Utils "https://github.com/stevenygd/pointflow/blob/master/utils.py"
    click Scripts "https://github.com/stevenygd/pointflow/blob/master/scripts/*.sh"
    click EvalMetrics "https://github.com/stevenygd/pointflow/blob/master/metrics/evaluation_metrics.py"
    click PSrc "https://github.com/stevenygd/pointflow/tree/master/metrics/pytorch_structural_losses/src"
    click PyBind "https://github.com/stevenygd/pointflow/blob/master/metrics/pytorch_structural_losses/pybind/bind.cpp"
    click Setup "https://github.com/stevenygd/pointflow/blob/master/metrics/pytorch_structural_losses/setup.py"
    click DemoScript "https://github.com/stevenygd/pointflow/blob/master/demo.py"
    click DemoShell "https://github.com/stevenygd/pointflow/blob/master/scripts/shapenet_*_demo.sh"
    click Env "https://github.com/stevenygd/pointflow/blob/master/env.yaml"
    click Install "https://github.com/stevenygd/pointflow/blob/master/install.sh"
    click Docs "https://github.com/stevenygd/pointflow/tree/master/docs/"

    %% Styles
    classDef data fill:#e0f7e9,stroke:#2e7d32,color:#2e7d32;
    classDef python fill:#e3f2fd,stroke:#1565c0,color:#1565c0;
    classDef compiled fill:#ffebee,stroke:#c62828,color:#c62828;
    classDef external fill:#fff3e0,stroke:#ef6c00,color:#ef6c00;
```
