# zhou13/lcnn architecture

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

- Interactive diagram: https://gitdiagram.com/zhou13/lcnn
- Repository: https://github.com/zhou13/lcnn

## Overview

##### Project type and purpose
- This is a research‑oriented machine‑learning codebase (L‑CNN) for end‑to‑end wireframe parsing in images.
- The purpose is to train, evaluate, and demo a PyTorch model that detects junctions and line segments (wireframes) on input images.

##### High‐level architecture (main components)
a. Data layer
- Raw dataset (ShanghaiTech or custom images)
- Pre‑processed dataset (npz files under data/wireframe)
b. Configuration
- YAML config files (config/wireframe.yaml) specifying hyperparameters
c. Core library (lcnn/ )
- models/ (hourglass_pose, line_vectorizer, multitask_learner)
- datasets.py (data loader, preprocessing hooks)
- metric.py (sAP, APH, mAPJ computation)
- trainer.py (training loop, checkpointing, logging)
- postprocess.py (thresholding, line merging)
- utils.py (helpers)
d. Entry‑point scripts
- train.py (launches training)
- process.py (batch inference over dataset)
- demo.py (single‑image inference)
- post.py (post‑processing + optional plotting)
- eval-sAP.py / eval-mAPJ.py / eval-APH.py (evaluation suites)
e. External services & tools
- HuggingFace (model & dataset download)
- MATLAB (for APH evaluation via mex interfaces)
f. Artifacts & outputs
- logs/ (tensorboard, checkpoints, npz outputs)
- post/ (thresholded npz, plots)
- figs/ (qualitative result images)

##### Relationships & data flow
- Data Preparation:
raw images → dataset/wireframe.py → pre‑processed npz → data/wireframe/
- Training:
config + pre‑processed npz → trainer.py → model checkpoints + logs + npz predictions
- Inference:
process.py (config + checkpoint + dataset) → batch npz predictions
- Post‑processing:
npz predictions → post.py → refined predictions + optional plots
- Evaluation:
sAP/mAPJ: eval-sAP.py / eval-mAPJ.py consume npz + ground truth → metrics + PR curves
APH: post outputs + MATLAB eval_release.m → APH metrics

##### Architectural patterns & design principles
- Modular Python package (lcnn/) separated from entry scripts
- Clear separation of concerns: data loading, model definition, training, post‑processing, evaluation
- Configuration‑driven via YAML + global config module
- Reusable components: hourglass backbone, line vectorizer, multi‑task heads

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Raw["Raw Images"]:::data
        DS1["dataset/wireframe.py"]:::core
        DS2["dataset/york.py"]:::core
        Pre["Preprocessed NPZ"]:::data
    end

    %% Configuration
    subgraph "Configuration"
        direction TB
        CFG["config/wireframe.yaml"]:::data
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        HG["lcnn/models/hourglass_pose.py"]:::core
        LV["lcnn/models/line_vectorizer.py"]:::core
        MTL["lcnn/models/multitask_learner.py"]:::core
        DSmod["lcnn/datasets.py"]:::core
        MET["lcnn/metric.py"]:::core
        TRmod["lcnn/trainer.py"]:::core
        PPmod["lcnn/postprocess.py"]:::core
        UT["lcnn/utils.py"]:::core
        GCmod["lcnn/config.py"]:::core
        BB["lcnn/box.py"]:::core
    end

    %% Entry-Point Scripts
    subgraph "Entry-Point Scripts"
        direction TB
        Train["train.py"]:::scripts
        Process["process.py"]:::scripts
        Demo["demo.py"]:::scripts
        PostScr["post.py"]:::scripts
        Eval1["eval-sAP.py"]:::scripts
        Eval2["eval-mAPJ.py"]:::scripts
        Eval3["eval-APH.py"]:::scripts
    end

    %% External Services
    subgraph "External Services"
        direction TB
        HF["HuggingFace"]:::external
        MEX["matlab/eval_release.m"]:::external
        COR["matlab/correspondPixels.*"]:::external
    end

    %% Artifacts & Outputs
    subgraph "Artifacts & Outputs"
        direction TB
        Logs["logs/"]:::output
        PostOut["post/"]:::output
        Figs["figs/"]:::output
    end

    %% Data Flow
    Raw --> DS1 --> Pre
    Raw --> DS2 --> Pre
    CFG --> Train
    CFG --> Process
    CFG --> Demo
    CFG --> PostScr
    CFG --> Eval1
    CFG --> Eval2
    CFG --> Eval3

    Pre --> Train
    Train --> Logs
    Pre --> Process
    Process --> PostScr
    PostScr --> PostOut
    PostOut --> Eval3

    %% Script to Core Library usage
    Train --> TRmod
    Process --> PPmod
    Demo --> HG
    Demo --> LV
    Demo --> MTL
    Eval1 --> MET
    Eval2 --> MET
    Eval3 --> MET

    %% Core Library internal usage
    TRmod --> HG
    TRmod --> LV
    TRmod --> MTL
    TRmod --> DSmod
    TRmod --> UT
    TRmod --> GCmod
    TRmod --> BB

    PPmod --> MET

    %% External Dependencies
    HF --> DS1
    HF --> DS2
    HF --> Train
    Eval3 --> MEX
    Eval3 --> COR

    %% Outputs
    Train --> Figs
    Demo --> Figs

    %% Click Events
    click DS1 "https://github.com/zhou13/lcnn/blob/master/dataset/wireframe.py"
    click DS2 "https://github.com/zhou13/lcnn/blob/master/dataset/york.py"
    click CFG "https://github.com/zhou13/lcnn/blob/master/config/wireframe.yaml"
    click HG "https://github.com/zhou13/lcnn/blob/master/lcnn/models/hourglass_pose.py"
    click LV "https://github.com/zhou13/lcnn/blob/master/lcnn/models/line_vectorizer.py"
    click MTL "https://github.com/zhou13/lcnn/blob/master/lcnn/models/multitask_learner.py"
    click DSmod "https://github.com/zhou13/lcnn/blob/master/lcnn/datasets.py"
    click MET "https://github.com/zhou13/lcnn/blob/master/lcnn/metric.py"
    click TRmod "https://github.com/zhou13/lcnn/blob/master/lcnn/trainer.py"
    click PPmod "https://github.com/zhou13/lcnn/blob/master/lcnn/postprocess.py"
    click UT "https://github.com/zhou13/lcnn/blob/master/lcnn/utils.py"
    click GCmod "https://github.com/zhou13/lcnn/blob/master/lcnn/config.py"
    click BB "https://github.com/zhou13/lcnn/blob/master/lcnn/box.py"
    click Train "https://github.com/zhou13/lcnn/blob/master/train.py"
    click Process "https://github.com/zhou13/lcnn/blob/master/process.py"
    click Demo "https://github.com/zhou13/lcnn/blob/master/demo.py"
    click PostScr "https://github.com/zhou13/lcnn/blob/master/post.py"
    click Eval1 "https://github.com/zhou13/lcnn/blob/master/eval-sAP.py"
    click Eval2 "https://github.com/zhou13/lcnn/blob/master/eval-mAPJ.py"
    click Eval3 "https://github.com/zhou13/lcnn/blob/master/eval-APH.py"
    click MEX "https://github.com/zhou13/lcnn/blob/master/matlab/eval_release.m"
    click COR "https://github.com/zhou13/lcnn/blob/master/matlab/correspondPixels.*"
    click Figs "https://github.com/zhou13/lcnn/tree/master/figs/"

    %% Styles
    classDef data fill:#add8e6,stroke:#000,color:#000
    classDef core fill:#98fb98,stroke:#000,color:#000
    classDef scripts fill:#ffb347,stroke:#000,color:#000
    classDef external fill:#d3d3d3,stroke:#000,color:#000
    classDef output fill:#87ceeb,stroke:#000,color:#000
```
