# wangyueft/dgcnn architecture

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

- Interactive diagram: https://gitdiagram.com/wangyueft/dgcnn
- Repository: https://github.com/wangyueft/dgcnn

## Overview

##### Project Type and Purpose
- This project implements Dynamic Graph CNN (DGCNN) for learning on point clouds. It provides re-implementations of the original paper using both PyTorch and TensorFlow.
- The project supports multiple high-level tasks such as classification, semantic segmentation, and part segmentation of 3D point clouds.
- That the project structure borrows ideas from the PointNet codebase, which is evident both in the file tree and the README references.

##### Analyzing the File Structure
- There are two primary directories at the top level: “pytorch” and “tensorflow.” Each directory isolates the implementation for the respective deep learning framework.
- The PyTorch directory contains:
- core files like main.py, data.py, model.py, and util.py.
- A “pretrained” folder that includes pretrained model weights.
- The TensorFlow directory’s structure is more segmented:
- High-level scripts (e.g., train.py, provider.py, evaluate.py).
- Specialized subdirectories for tasks such as "part_seg" (part segmentation) and "sem_seg" (semantic segmentation).
- Additional directories including “models” under tensorflow for model definitions (e.g., dgcnn.py, transform_nets.py), “misc” for demos and supporting images, and “utils” for helper functions relating to data preparation, transformation, and point cloud utilities.
- Build/deployment artifacts (e.g., download_data.sh, test scripts, saved checkpoints) are also present primarily within TensorFlow subdirectories.

##### Use of Architectural Patterns
- There is a clear separation between different implementations — one branch for PyTorch and another for TensorFlow. Each branch’s internal structure reflects stages such as data loading, model architecture, training routines, evaluation scripts, and utility functions.
- Within the TensorFlow branch, the segmentation tasks (both semantic and part) have dedicated folders that isolate training routines, model definitions, data handling (e.g., download scripts, meta files), and evaluation.
- The design inherently utilizes modular programming by separating core functionalities into distinct files (for example, model.py vs. util.py in PyTorch, and distinct directories for different segmentation tasks in TensorFlow).

- Main components:
- Frontend/Client layer (if applicable): While this project is primarily focused on research experiments and training pipelines, you might represent the experimental/testing interface as a “User/Experiment” input.
- PyTorch Implementation:
- Data Loader (data.py)
- Model Definition (model.py, util.py)
- Main Training/Inference Engine (main.py)
- Pretrained Model Store (pretrained/)
- TensorFlow Implementation:
- Core Training Scripts (train.py, train_multi_gpu.py)
- Segmentation Modules:
▪ Part Segmentation (part_seg/ directory – including scripts for training, testing, and data download)
▪ Semantic Segmentation (sem_seg/ directory – with training, evaluation, data preparation)
- Model Definitions (models/ directory – containing dgcnn.py and transform_nets.py)
- Utility Functions and Data Handlers (utils/ directory and provider.py)
- Evaluation and Inference Modules (evaluate.py, batch_inference.py)
- External Dependencies & Data:
- Pre-trained models stored in pytorch/pretrained or checkpoints under tensorflow/part_seg/train_results for saving and loading models.
- External data sources referenced in download_data.sh scripts.

- How data flows from external sources (or a data repository) → preprocessing utilities (e.g., data.py, pc_util.py) → into the model architectures.
- Distinct sections for PyTorch and TensorFlow pipelines, noting that they share a high-level common purpose but implement it through different frameworks.
- Interconnections where similar functionalities (e.g., segmentation) follow similar design patterns in both implementations.

##### Important Architectural Patterns and Design Principles
- Modularity: Every major functionality (data handling, model definition, training, evaluation) has its own module.
- Separation of Concerns: Code separation between different tasks (classification, part segmentation, semantic segmentation) is clear.

1. The PyTorch implementation pipeline (highlighting main.py, model.py, data.py, pretrained models).
2. The TensorFlow pipeline with further subdivisions:
▪ A section for part segmentation (part_seg) with training, testing, and checkpoint storage.
▪ A section for semantic segmentation (sem_seg) with training, data meta-information, and evaluation.
3. Shared utility and helper modules (provider.py, utils) that underpin both pipelines.
- External data ingestion points.
- Connections between training routines and model evaluation.
- How utility functions are shared among multiple components.
- Scalability aspects (e.g., multi-GPU support in TensorFlow) and modular design.
- Keep the layout clean and structured so that every component, its label, and interaction is clearly visible.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Interface
    UI["User/Experiment Interface"]:::interface

    %% PyTorch Implementation
    subgraph "PyTorch Implementation"
        PT_Main["PyTorch Main (main.py)"]:::training
        PT_Data["PyTorch Data Loader (data.py)"]:::data
        PT_Model["PyTorch Model Definition (model.py)"]:::model
        PT_Util["PyTorch Utility Functions (util.py)"]:::utility
        PT_Pre["PyTorch Pretrained Model Store"]:::utility
    end

    %% TensorFlow Implementation
    subgraph "TensorFlow Implementation"
        TF_Train["TF Core Training Script (train.py)"]:::training
        TF_Multi["TF Multi-GPU Training (train_multi_gpu.py)"]:::training
        TF_Part["TF Part Segmentation Module"]:::segmentation_part
        TF_Sem["TF Semantic Segmentation Module"]:::segmentation_semantic
        TF_Model["TF Model Definitions"]:::model
        TF_Util["TF Utility Functions & Data Handlers"]:::utility
        TF_Eval["TF Evaluation Module (evaluate.py)"]:::evaluation
    end

    %% Connections from User Interface
    UI -->|"triggers"| PT_Main
    UI -->|"triggers"| TF_Train
    UI -->|"triggers"| TF_Multi

    %% PyTorch Pipeline Flow
    PT_Main -->|"loads"| PT_Data
    PT_Main -->|"invokes"| PT_Model
    PT_Main -->|"utilizes"| PT_Util
    PT_Main -->|"loads"| PT_Pre

    %% TensorFlow Core Flow
    TF_Train -->|"calls"| TF_Model
    TF_Train -->|"calls"| TF_Util
    TF_Train -->|"leads to"| TF_Eval

    %% TensorFlow Multi-GPU and Segmentation Flow
    TF_Multi -->|"trains"| TF_Part
    TF_Util -->|"supplies-data"| TF_Part
    TF_Util -->|"supplies-data"| TF_Sem
    TF_Model -->|"shared-model"| TF_Part
    TF_Model -->|"shared-model"| TF_Sem
    TF_Part -->|"evaluated-by"| TF_Eval
    TF_Sem -->|"evaluated-by"| TF_Eval

    %% Click Events for PyTorch Components
    click PT_Data "https://github.com/wangyueft/dgcnn/blob/master/pytorch/data.py"
    click PT_Model "https://github.com/wangyueft/dgcnn/blob/master/pytorch/model.py"
    click PT_Util "https://github.com/wangyueft/dgcnn/blob/master/pytorch/util.py"
    click PT_Main "https://github.com/wangyueft/dgcnn/blob/master/pytorch/main.py"
    click PT_Pre "https://github.com/wangyueft/dgcnn/tree/master/pytorch/pretrained/"

    %% Click Events for TensorFlow Components
    click TF_Train "https://github.com/wangyueft/dgcnn/blob/master/tensorflow/train.py"
    click TF_Multi "https://github.com/wangyueft/dgcnn/blob/master/tensorflow/part_seg/train_multi_gpu.py"
    click TF_Part "https://github.com/wangyueft/dgcnn/tree/master/tensorflow/part_seg/"
    click TF_Sem "https://github.com/wangyueft/dgcnn/tree/master/tensorflow/sem_seg/"
    click TF_Model "https://github.com/wangyueft/dgcnn/tree/master/tensorflow/models/"
    click TF_Util "https://github.com/wangyueft/dgcnn/blob/master/tensorflow/provider.py"
    click TF_Eval "https://github.com/wangyueft/dgcnn/blob/master/tensorflow/evaluate.py"

    %% Style Classes
    classDef interface fill:#E8DAEF,stroke:#333,stroke-width:2px;
    classDef training fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef data fill:#F7DC6F,stroke:#333,stroke-width:2px;
    classDef model fill:#85C1E9,stroke:#333,stroke-width:2px;
    classDef utility fill:#82E0AA,stroke:#333,stroke-width:2px;
    classDef segmentation_part fill:#D7BDE2,stroke:#333,stroke-width:2px;
    classDef segmentation_semantic fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#A9DFBF,stroke:#333,stroke-width:2px;
```
