# edward1997104/wavelet-generation architecture

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

- Interactive diagram: https://gitdiagram.com/edward1997104/wavelet-generation
- Repository: https://github.com/edward1997104/wavelet-generation

## Overview

##### File structure
- Top-level:
– configs/ (config.py, config_highs.py)
– data/ (flip_axis.py, to_manifold.py, sample_sdf.py, convert_wavelet.py)
– external/ (Manifold, mesh_to_sdf)
– wavelet_data/ (storage for generated .npy files)
– trainer/ (trainer.py)
– models/
· module/ (diffusion_network.py, gaussian_diffusion.py, dwt.py, etc.)
· network.py (training entry model)
· network_gen.py (inference entry)
– pretrain/ (pretrained checkpoints)
– utils/ (debugger.py, meter.py, other_utils.py)
– debug/ (output_folder)

##### README for additional insights
- Describes environment setup, dataset preparation steps (ShapeNet → data scripts → wavelet_data), training (`trainer.py` + config), and inference (`network_gen.py` + pretrain).
- External dependencies: PyTorch Wavelets, Manifold, mesh_to_sdf.

##### Main components
A. Raw Dataset (ShapeNet)
B. Data-Processing Pipeline (scripts in data/ plus external libs)
- flip_axis.py → orientation fix
- to_manifold.py → watertight mesh (uses external/Manifold)
- sample_sdf.py → SDF sampling (uses external/mesh_to_sdf)
- convert_wavelet.py → wavelet coefficients → output to wavelet_data/
C. Data Store: wavelet_data/ (coarse & detail .npy)
D. Configuration Layer: configs/config.py & config_highs.py
E. Training Engine: trainer/trainer.py
- Loads .npy via config
- Uses models/network.py & models/module/* to train diffusion & detail predictor
- Outputs checkpoints to pretrain/ or user‐defined folder
F. Model Modules:
- Core building blocks (diffusion, resample, DWT, FP16 utilities)
- network.py (assembles modules)
G. Pretrained Model Store: pretrain/
H. Inference Engine: models/network_gen.py
- Loads checkpoints & config params
- Generates wavelet coefficients → reconstructs mesh → writes to debug/output_folder or user folder
I. Utilities: utils/ (logging, debugging, metrics)
J. External Dependencies:
- pytorch_wavelets, external/Manifold, external/mesh_to_sdf

##### Relationships & interactions
- Utilities are tapped into by both Trainer and Inference for logging/metrics.
- External libs are referenced only by specific data scripts.

##### Architectural patterns & principles
- Modular pipeline separation (Data-Prep ↔ Training ↔ Inference)
- Config-driven workflows decoupling code from hyperparameters
- Plugin-style model modules (easy to swap or extend building blocks)
- CLI orchestration (Python entry scripts in each stage)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data-Processing Pipeline
    subgraph "Data-Processing Pipeline" 
        direction TB
        FA["flip_axis.py"]:::code
        TM["to_manifold.py"]:::code
        SS["sample_sdf.py"]:::code
        CW["convert_wavelet.py"]:::code
    end
    FA -->|uses| MND["Manifold"]:::ext
    TM -->|uses| MND
    SS -->|uses| MSDF["mesh_to_sdf"]:::ext
    CW -->|outputs .npy| WD[(Wavelet Data Store)]:::data

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        CFG1[/configs/config.py/]:::config
        CFG2[/configs/config_highs.py/]:::config
    end

    %% Data Store
    WD

    %% Training Engine
    TE["Training Engine\ntrainer.py"]:::code
    WD -->|.npy files| TE
    CFG1 -->|config| TE
    CFG2 -->|config| TE

    %% Model Components
    subgraph "Model Components" 
        direction TB
        MN["network.py"]:::code
        DN["diffusion_network.py"]:::code
        GD["gaussian_diffusion.py"]:::code
        DWT["dwt.py"]:::code
        DWTU["dwt_utils.py"]:::code
        RS["resample.py"]:::code
        FP["fp16_util.py"]:::code
        NN["nn.py"]:::code
    end
    TE -->|imports| MN
    MN --> DN
    MN --> GD
    MN --> DWT
    MN --> DWTU
    MN --> RS
    MN --> FP
    MN --> NN
    TE -->|logs/metrics| UT["Utilities"]:::code

    %% Pretrained Model Store
    PMS[(Pretrained Model Store)]:::data
    TE -->|checkpoints| PMS

    %% Inference Engine
    IE["Inference Engine\nnetwork_gen.py"]:::code
    PMS -->|loads| IE
    CFG1 -->|config| IE
    CFG2 -->|config| IE
    IE -->|generates mesh| MO["Mesh Outputs"]:::data
    IE -->|logs/metrics| UT

    %% Utilities
    subgraph "Utilities"
        direction TB
        DBG["debugger.py"]:::code
        MTR["meter.py"]:::code
        OUT["other_utils.py"]:::code
    end
    UT --> DBG
    UT --> MTR
    UT --> OUT

    %% Click events
    click FA "https://github.com/edward1997104/wavelet-generation/blob/main/data/flip_axis.py"
    click TM "https://github.com/edward1997104/wavelet-generation/blob/main/data/to_manifold.py"
    click SS "https://github.com/edward1997104/wavelet-generation/blob/main/data/sample_sdf.py"
    click CW "https://github.com/edward1997104/wavelet-generation/blob/main/data/convert_wavelet.py"
    click WD "https://github.com/edward1997104/wavelet-generation/tree/main/wavelet_data/"
    click CFG1 "https://github.com/edward1997104/wavelet-generation/blob/main/configs/config.py"
    click CFG2 "https://github.com/edward1997104/wavelet-generation/blob/main/configs/config_highs.py"
    click TE "https://github.com/edward1997104/wavelet-generation/blob/main/trainer/trainer.py"
    click MN "https://github.com/edward1997104/wavelet-generation/blob/main/models/network.py"
    click DN "https://github.com/edward1997104/wavelet-generation/blob/main/models/module/diffusion_network.py"
    click GD "https://github.com/edward1997104/wavelet-generation/blob/main/models/module/gaussian_diffusion.py"
    click DWT "https://github.com/edward1997104/wavelet-generation/blob/main/models/module/dwt.py"
    click DWTU "https://github.com/edward1997104/wavelet-generation/blob/main/models/module/dwt_utils.py"
    click RS "https://github.com/edward1997104/wavelet-generation/blob/main/models/module/resample.py"
    click FP "https://github.com/edward1997104/wavelet-generation/blob/main/models/module/fp16_util.py"
    click NN "https://github.com/edward1997104/wavelet-generation/blob/main/models/module/nn.py"
    click PMS "https://github.com/edward1997104/wavelet-generation/tree/main/pretrain/"
    click IE "https://github.com/edward1997104/wavelet-generation/blob/main/models/network_gen.py"
    click DBG "https://github.com/edward1997104/wavelet-generation/blob/main/utils/debugger.py"
    click MTR "https://github.com/edward1997104/wavelet-generation/blob/main/utils/meter.py"
    click OUT "https://github.com/edward1997104/wavelet-generation/blob/main/utils/other_utils.py"

    %% Styles
    classDef code fill:#D0E6FF,stroke:#0366D6,color:#0366D6
    classDef data fill:#DFFFE0,stroke:#2A9D8F,color:#2A9D8F
    classDef ext fill:#FFF4D0,stroke:#E76F51,color:#E76F51
    classDef config fill:#FFF8DC,stroke:#E9C46A,color:#E9C46A
```
