# yifita/deep_cage architecture

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

- Interactive diagram: https://gitdiagram.com/yifita/deep_cage
- Repository: https://github.com/yifita/deep_cage

## Overview

##### Main components
a. Data Storage
- Raw 3D assets (data/elaborated_chairs, data/fancy_humanoid, data/shapenet_target, data/Surreal, etc.)
- Preprocessed point clouds / cages (data/processed_shapenetseg, data/surreal_template*.ply/.picked, data/cage_*.obj)
- Trained models and outputs (trained_models/*)

b. Preprocessing & Data‐Generation Scripts
- scripts/resample_shapenet.py
- scripts/divide_shapenet_label.py
- scripts/generate_data_with_known_cage.py
- scripts/normalize_humanoids.py
- … and other scripts under scripts/

c. Core Python Modules
- datasets.py – dataset loaders (ShapeNet, SURREAL)
- common.py, option.py – shared utilities and CLI option parsing
- networks.py, network2.py – network architectures for cage deformation
- losses.py – loss definitions (CD, MVC, symmetry, normals, etc.)
- deformer_3d.py – model-only training & testing pipeline
- cage_deformer_3d.py – full pipeline for deformation with cage optimization

d. External Dependencies and Libraries
- PyTorch (torch)
- pytorch_points (vendor module)
- PyMesh2 (pymesh/pymesh2-*.whl)
- NumPy, SciPy, Open3D (via requirements.txt)
- Thea / MeshLab (for correspondence marking and mesh filtering)

e. Execution Workflows
- Training workflow
- ShapeNet deformation demo
- SURREAL deformation and deformation-transfer demo

##### Relationships and data flows
– Raw 3D models → Preprocessing scripts → Preprocessed point clouds and cages
– Preprocessed data + CLI options → DataLoader (datasets.py) → Batches of points + cages
– Batches → Networks (networks.py / network2.py) → Predicted cage deformations
– Predictions + ground truth → losses.py → Loss values → Optimizer → Updated network weights
– End of epoch → Checkpoint → trained_models/…

For inference:
– Source model + prebuilt cage → cage_deformer_3d.py → Loads checkpoint → Forward pass → Deformed mesh → Output renders (trained_models/*/renders)

For deformation transfer:
– Prebuilt cage + user landmarks (.picked) → optimize_cage.py → iterative optimization → Adapted cage

##### Architectural patterns & design principles
- Modularization: separate CLI entry-points (deformer_3d.py, cage_deformer_3d.py, optimize_cage.py) vs. reusable libraries (datasets.py, networks.py, losses.py).
- Pipeline pattern: distinct stages for data prep, training, inference.
- Configuration via option.py: decouples hyperparameters/paths from code.
- Extensibility: new datasets or deformation methods can be added by extending datasets.py or networks.py.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Storage
    subgraph "Data Storage"
        direction TB
        RAW1["Raw Assets: elaborated_chairs/"]:::data
        RAW2["Raw Assets: fancy_humanoid/"]:::data
        RAW3["Raw Assets: shapenet_target/"]:::data
        PROC1["Preprocessed: processed_shapenetseg/"]:::data
        PROC2["Preprocessed: surreal_template.ply/.picked"]:::data
        PROC3["Preprocessed: surreal_template_tpose.ply/.picked"]:::data
        PROC4["Preprocessed: cage_rpose.obj"]:::data
        PROC5["Preprocessed: cage_tpose.ply"]:::data
        TMP1["Templates & Extras: sphere_V42_F80.off"]:::data
        TMP2["Templates & Extras: synsetoffset2category.txt"]:::data
        MODEL["Trained Models & Renders: trained_models/"]:::data
    end

    %% Preprocessing & Utility Scripts
    subgraph "Preprocessing & Utility Scripts"
        direction TB
        S1["resample_shapenet.py"]:::script
        S2["divide_shapenet_label.py"]:::script
        S3["generate_data_with_known_cage.py"]:::script
        S4["normalize_humanoids.py"]:::script
        S5["remesh_shapenet.py"]:::script
        S6["run_meshlab_filter.sh"]:::script
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        DS["datasets.py"]:::code
        CM["common.py"]:::code
        OP["option.py"]:::code
        NW1["networks.py"]:::code
        NW2["network2.py"]:::code
        LS["losses.py"]:::code
    end

    %% CLI Entry Points
    subgraph "CLI Entry Points"
        direction TB
        C1["deformer_3d.py"]:::script
        C2["cage_deformer_3d.py"]:::script
        C3["optimize_cage.py"]:::script
    end

    %% External Dependencies
    subgraph "External Dependencies & Tools"
        direction TB
        E1["PyTorch"]:::ext
        E2["pytorch_points/"]:::ext
        E3["pymesh2-0.2.1-*.whl"]:::ext
        E4["requirements.txt"]:::ext
    end

    %% Data Flow: Raw → Preprocessing → Preprocessed
    RAW1 -->|"obj/.ply"| S1
    RAW2 -->|"obj/.ply"| S4
    RAW3 -->|"obj/.ply"| S2
    S1 -->|"ply"| PROC1
    S2 -->|"ply"| PROC1
    S3 -->|"ply,obj"| PROC2
    S3 -->|"ply,picked"| PROC3
    S5 -->|"obj"| PROC4
    S6 -->|"ply"| PROC5

    %% Core Flow: Preprocessed → Core Library → Training
    PROC1 -->|"point clouds"| DS
    PROC2 -->|"cages"| DS
    PROC3 -->|"cages"| DS
    DS -->|"Tensor batches"| NW1
    NW1 -->|"predictions"| LS
    LS -->|"loss values"| C1
    C1 -->|"updates weights"| MODEL

    %% Inference Flow
    MODEL -->|".pth"| C2
    PROC4 -->|"cage obj"| C2
    C2 -->|"deformed mesh"| MODEL

    %% Deformation Transfer Flow
    PROC3 -->|"landmarks"| C3
    C3 -->|"optimized cage"| PROC5

    %% CLI Invocations (Control Flow)
    Dinv1([User]) -.->|"run"| C1
    Dinv1 -.->|"run"| C2
    Dinv1 -.->|"run"| C3

    %% External Dependencies Usage
    C1 --> E1
    C1 --> E2
    C1 --> E3
    C2 --> E1
    C3 --> E1
    C3 --> E4

    %% Click Events
    click RAW1 "https://github.com/yifita/deep_cage/tree/master/data/elaborated_chairs/"
    click RAW2 "https://github.com/yifita/deep_cage/tree/master/data/fancy_humanoid/"
    click RAW3 "https://github.com/yifita/deep_cage/tree/master/data/shapenet_target/"
    click PROC1 "https://github.com/yifita/deep_cage/tree/master/data/processed_shapenetseg/"
    click PROC2 "https://github.com/yifita/deep_cage/blob/master/data/surreal_template.ply"
    click PROC3 "https://github.com/yifita/deep_cage/blob/master/data/surreal_template_tpose.ply"
    click PROC4 "https://github.com/yifita/deep_cage/blob/master/data/cage_rpose.obj"
    click PROC5 "https://github.com/yifita/deep_cage/blob/master/data/cage_tpose.ply"
    click TMP1 "https://github.com/yifita/deep_cage/blob/master/data/sphere_V42_F80.off"
    click TMP2 "https://github.com/yifita/deep_cage/blob/master/data/synsetoffset2category.txt"
    click MODEL "https://github.com/yifita/deep_cage/tree/master/trained_models/"
    click S1 "https://github.com/yifita/deep_cage/blob/master/scripts/resample_shapenet.py"
    click S2 "https://github.com/yifita/deep_cage/blob/master/scripts/divide_shapenet_label.py"
    click S3 "https://github.com/yifita/deep_cage/blob/master/scripts/generate_data_with_known_cage.py"
    click S4 "https://github.com/yifita/deep_cage/blob/master/scripts/normalize_humanoids.py"
    click S5 "https://github.com/yifita/deep_cage/blob/master/scripts/remesh_shapenet.py"
    click S6 "https://github.com/yifita/deep_cage/blob/master/scripts/run_meshlab_filter.sh"
    click DS "https://github.com/yifita/deep_cage/blob/master/datasets.py"
    click CM "https://github.com/yifita/deep_cage/blob/master/common.py"
    click OP "https://github.com/yifita/deep_cage/blob/master/option.py"
    click NW1 "https://github.com/yifita/deep_cage/blob/master/networks.py"
    click NW2 "https://github.com/yifita/deep_cage/blob/master/network2.py"
    click LS "https://github.com/yifita/deep_cage/blob/master/losses.py"
    click C1 "https://github.com/yifita/deep_cage/blob/master/deformer_3d.py"
    click C2 "https://github.com/yifita/deep_cage/blob/master/cage_deformer_3d.py"
    click C3 "https://github.com/yifita/deep_cage/blob/master/optimize_cage.py"
    click E2 "https://github.com/yifita/deep_cage/tree/master/pytorch_points/"
    click E3 "https://github.com/yifita/deep_cage/blob/master/pymesh/pymesh2-0.2.1-cp37-cp37m-linux_x86_64.whl"
    click E4 "https://github.com/yifita/deep_cage/blob/master/requirements.txt"

    %% Styles
    classDef data fill:#D6EAF8,stroke:#2874A6;
    classDef script fill:#F9E79F,stroke:#B9770E;
    classDef code fill:#D5F5E3,stroke:#239B56;
    classDef ext fill:#E8DAEF,stroke:#6C3483;
```
