# alexandrebinninger/sens architecture

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

- Interactive diagram: https://gitdiagram.com/alexandrebinninger/sens
- Repository: https://github.com/alexandrebinninger/sens

## Overview

##### Project Type and Purpose
- It supports two modes of operation:
- CLI inference (`run.py`) for offline sketch→mesh conversion
- It also provides a training pipeline (`trainer_combined.py`) to reproduce or fine-tune the model on a chair dataset.

##### File Structure
- Top-level:
- assets/ — static resources and model checkpoints
- data_loaders/ — classes to load and augment datasets
- deep_sdf/ + models/ + pointnetpp/ — neural-network architectures and utilities
- ui_sketch/ — UI entrypoint, controllers, and mesh/render utilities
- utils/ — shared helper modules (I/O, meshing, evaluation, rotation, SVG, etc.)
- run.py — simple CLI inference script
- trainer_combined.py — end-to-end training orchestration
- constants.py, custom_types.py, options.py — global config and type definitions

##### README for Insights
- The system uses two pre‐trained decoders:
- Supports both batch/CLI mode and interactive real-time mode with PyQt/OpenGL.

##### Main Components and Their Relationships
a. Data Layer
- assets/data/ (preprocessed meshes, sketches)
- data_loaders/ modules feed data into networks
b. Model Layer
- deep_sdf/, models/, pointnetpp/ define encoder/decoder networks and loss functions
- options.py/config constants select architectures at runtime
c. Training Pipeline
- trainer_combined.py orchestrates data loading, model instantiation, optimizer setup (utils/train_utils.py), logging, and checkpoint saving to assets/checkpoints/
d. Inference Pipelines
- CLI (`run.py`): loads checkpoints, loads a single sketch, runs forward pass, and writes mesh .obj to assets/output/
- GUI (`ui_sketch/sketch_main.py` + controllers): real-time sketch canvas → inference_processing → occ_inference & sketch_inference → mesh_plotter → on-screen rendering; user can select parts and re-infer subregions.
e. Utilities
- utils/*: meshing (mcubes_meshing), mesh export (mesh_utils), evaluation, image/svg I/O, rotation transforms

##### Architectural Patterns & Design Principles
- Modular separation: data loading, model definitions, training, inference, and UI are in distinct packages
- Config-driven instantiation: options.py and environment.yml drive reproducibility
- Single responsibility: each module/class has a focused purpose (e.g., `clipasso_dataset.py` vs. `prosketch_dataset.py`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data & Assets
    subgraph "Data & Assets"
        AssetsData["assets/data/"]:::data
        AssetsChk["assets/checkpoints/"]:::data
        AssetsUI["assets/ui_resources/"]:::data
    end

    %% Training Stack
    subgraph "Training Stack"
        subgraph "Data Loaders" 
            DL1["augment_clipcenter.py"] 
            DL2["clipasso_dataset.py"] 
            DL3["combined_dataset.py"] 
            DL4["prosketch_dataset.py"] 
            DL5["sketch_dataset.py"] 
        end
        subgraph "Model Layer"
            DSDF1["deepsdf_model.py"] 
            DSDF2["dualsdf_model.py"] 
            DSDF3["imnet_model.py"] 
            M1["deep_sdf.py"] 
            M2["occ_gmm.py"] 
            M3["occ_a.py"] 
            M4["sketch_model.py"] 
            M5["transformer.py"] 
            M6["gm_utils.py"] 
            M7["mlp_models.py"] 
            M8["model_gm.py"] 
            M9["models_utils.py"] 
            M10["sdf_discriminator.py"] 
            M11["sdf_loss.py"] 
            P1["pointnet_msg.py"] 
            P2["pointnet_ssg.py"] 
            P3["pointnet_seg.py"] 
            P4["pointnet_utils.py"] 
        end
        Trainer["trainer_combined.py"]:::script
        AssetsChk2["assets/checkpoints/"]:::data
    end

    AssetsData --> DL1 & DL2 & DL3 & DL4 & DL5
    DL1 & DL2 & DL3 & DL4 & DL5 --> DSDF1 & DSDF2 & DSDF3 & M1 & M2 & M3 & M4 & M5 & M6 & M7 & M8 & M9 & M10 & M11 & P1 & P2 & P3 & P4
    DSDF1 & DSDF2 & DSDF3 & M1 & M2 & M3 & M4 & M5 & M6 & M7 & M8 & M9 & M10 & M11 & P1 & P2 & P3 & P4 --> Trainer
    Trainer --> AssetsChk2

    AssetsChk --> Trainer
    AssetsChk --> Run
    AssetsChk --> SketchMain

    %% Inference CLI
    subgraph "Inference CLI"
        Run["run.py"]:::script
        ModelCLI["Model Modules"]:::model
        MeshingCLI["mcubes_meshing.py"]:::util
        Output["assets/output/"]:::data
    end

    Run -->|"loads checkpoints & sketch"| ModelCLI
    ModelCLI -->|"mesh vertices & faces"| MeshingCLI
    MeshingCLI -->|"outputs .obj"| Output

    %% Inference GUI
    subgraph "Inference GUI"
        SketchMain["sketch_main.py"]:::script
        Controllers["ui_controllers.py"]:::script
        Interactors["interactors.py"]:::script
        InfProc["inference_processing.py"]:::script
        OccInf["occ_inference.py"]:::script
        SketchInf["sketch_inference.py"]:::script
        MeshPlot["mesh_plotter.py"]:::script
    end

    SketchMain --> Controllers
    Controllers --> Interactors
    Interactors --> InfProc
    InfProc --> OccInf
    InfProc --> SketchInf
    OccInf --> MeshPlot
    SketchInf --> MeshPlot
    MeshPlot -->|"renders via OpenGL"| SketchMain

    %% Shared Utilities
    subgraph "Shared Utilities"
        U1["edge_detection.py"] 
        U2["evaluation_utils.py"] 
        U3["files_utils.py"] 
        U4["image_utils.py"] 
        U5["mcubes_meshing.py"] 
        U6["mesh_data.py"] 
        U7["mesh_utils.py"] 
        U8["rotation_utils.py"] 
        U9["svg_utils.py"] 
    end

    %% Click Events
    click DL1 "https://github.com/alexandrebinninger/sens/blob/main/data_loaders/augment_clipcenter.py"
    click DL2 "https://github.com/alexandrebinninger/sens/blob/main/data_loaders/clipasso_dataset.py"
    click DL3 "https://github.com/alexandrebinninger/sens/blob/main/data_loaders/combined_dataset.py"
    click DL4 "https://github.com/alexandrebinninger/sens/blob/main/data_loaders/prosketch_dataset.py"
    click DL5 "https://github.com/alexandrebinninger/sens/blob/main/data_loaders/sketch_dataset.py"
    click DSDF1 "https://github.com/alexandrebinninger/sens/blob/main/deep_sdf/deepsdf_model.py"
    click DSDF2 "https://github.com/alexandrebinninger/sens/blob/main/deep_sdf/dualsdf_model.py"
    click DSDF3 "https://github.com/alexandrebinninger/sens/blob/main/deep_sdf/imnet_model.py"
    click M1 "https://github.com/alexandrebinninger/sens/blob/main/models/deep_sdf.py"
    click M2 "https://github.com/alexandrebinninger/sens/blob/main/models/occ_gmm.py"
    click M3 "https://github.com/alexandrebinninger/sens/blob/main/models/occ_a.py"
    click M4 "https://github.com/alexandrebinninger/sens/blob/main/models/sketch_model.py"
    click M5 "https://github.com/alexandrebinninger/sens/blob/main/models/transformer.py"
    click M6 "https://github.com/alexandrebinninger/sens/blob/main/models/gm_utils.py"
    click M7 "https://github.com/alexandrebinninger/sens/blob/main/models/mlp_models.py"
    click M8 "https://github.com/alexandrebinninger/sens/blob/main/models/model_gm.py"
    click M9 "https://github.com/alexandrebinninger/sens/blob/main/models/models_utils.py"
    click M10 "https://github.com/alexandrebinninger/sens/blob/main/models/sdf_discriminator.py"
    click M11 "https://github.com/alexandrebinninger/sens/blob/main/models/sdf_loss.py"
    click P1 "https://github.com/alexandrebinninger/sens/blob/main/pointnetpp/pointnet_msg.py"
    click P2 "https://github.com/alexandrebinninger/sens/blob/main/pointnetpp/pointnet_ssg.py"
    click P3 "https://github.com/alexandrebinninger/sens/blob/main/pointnetpp/pointnet_seg.py"
    click P4 "https://github.com/alexandrebinninger/sens/blob/main/pointnetpp/pointnet_utils.py"
    click Trainer "https://github.com/alexandrebinninger/sens/blob/main/trainer_combined.py"
    click Run "https://github.com/alexandrebinninger/sens/blob/main/run.py"
    click SketchMain "https://github.com/alexandrebinninger/sens/blob/main/ui_sketch/sketch_main.py"
    click Controllers "https://github.com/alexandrebinninger/sens/blob/main/ui_sketch/ui_controllers.py"
    click Interactors "https://github.com/alexandrebinninger/sens/blob/main/ui_sketch/interactors.py"
    click InfProc "https://github.com/alexandrebinninger/sens/blob/main/ui_sketch/inference_processing.py"
    click OccInf "https://github.com/alexandrebinninger/sens/blob/main/ui_sketch/occ_inference.py"
    click SketchInf "https://github.com/alexandrebinninger/sens/blob/main/ui_sketch/sketch_inference.py"
    click MeshPlot "https://github.com/alexandrebinninger/sens/blob/main/ui_sketch/mesh_plotter.py"
    click U5 "https://github.com/alexandrebinninger/sens/blob/main/utils/mcubes_meshing.py"

    %% Styles
    classDef data fill:#cce5ff,stroke:#66b0ff;
    classDef model fill:#d4edda,stroke:#8fd19e;
    classDef script fill:#fff3cd,stroke:#ffe08a;
    classDef util fill:#e2e3e5,stroke:#bcbec0;
```
