# cvg/deeplsd architecture

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

- Interactive diagram: https://gitdiagram.com/cvg/deeplsd
- Repository: https://github.com/cvg/deeplsd

## Overview

##### Project type and purpose
- DeepLSD is an open-source, research-oriented deep learning library and CLI toolkit for generic line segment detection and refinement in images.
- It combines a Python-based neural network backbone with a C++ optimization module for final line refinement.

##### File structure
- Top-level directories:
- deeplsd/             ← core Python package
- line_refinement/     ← C++ solver wrapped via pybind11
- third_party/         ← bundled external libraries (AFM, homography_est, progressive-x, pytlbd, pytlsd)
- notebooks/           ← Jupyter demos
- assets/, scripts, configs, requirements.txt, setup/install scripts
- Inside deeplsd/:
- configs/             ← YAML files for train/export/eval
- datasets/            ← data loaders & augmentation
- models/              ← network definitions & inference wrappers
- geometry/            ← homography, projection, visualization
- evaluation/          ← line detection & VP metrics
- utils/               ← experiment tracking, tensor tools, CLI helpers
- scripts/             ← entry-point Python files (train, export, evaluate, refine)
- settings.py          ← global paths (EXPER_PATH, DATA_PATH)

##### README for additional insights
- Architecture is config-driven: all experiments rely on YAML files.
- Two main workflows:
a) Training & exporting features (distance/angle fields)
b) Inference & line refinement (via C++ module)
- External dependencies: OpenCV, GFlags, GLog, Ceres, CUDA, Python 3.7+, GCC 9.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data & Config
    subgraph "Data & Config" 
        direction TB
        RAW_IMG["Raw Images"]:::data
        CONFIG["Config Loader (YAML)"]:::data
    end

    %% Python Core Package
    subgraph "deeplsd (Python Core)" 
        direction TB
        SETTINGS["Global Settings"]:::python
        DP["Data Pipeline"]:::python
        MODEL["Model Definitions & Inference"]:::python
        GEO["Geometry Module"]:::python
        EVAL["Evaluation Module"]:::python
        CLI["CLI Scripts"]:::python
    end

    %% C++ Extension
    subgraph "line_refinement (C++ Extension)" 
        direction TB
        CPP_SOLVER["Line Refinement Solver"]:::cpp
    end

    %% Third-Party Libraries
    subgraph "Third-Party Libraries" 
        direction TB
        THIRD["third_party/"]:::external
    end

    %% Notebooks & Assets
    subgraph "Notebooks & Assets"
        direction TB
        NOTEBOOKS["Jupyter Notebooks"]:::external
        ASSETS["Assets (images/videos)"]:::data
    end

    %% Workflows
    RAW_IMG --> DP
    CONFIG --> DP
    SETTINGS --> DP

    DP --> MODEL
    MODEL --> GEO
    MODEL --> EVAL
    GEO --> EVAL

    MODEL --> CLI
    EVAL --> CLI

    MODEL -->|"Predictions"| CLI
    CLI -->|"Inference"| CPP_SOLVER
    CPP_SOLVER -->|"Refined Lines"| CLI

    THIRD --> DP
    THIRD --> CPP_SOLVER

    NOTEBOOKS --> DP
    NOTEBOOKS --> MODEL

    ASSETS --> RAW_IMG

    %% Click Events
    click CONFIG "https://github.com/cvg/deeplsd/blob/main/deeplsd/configs/*.yaml"
    click DP "https://github.com/cvg/deeplsd/tree/main/deeplsd/datasets/"
    click DP "https://github.com/cvg/deeplsd/blob/main/deeplsd/datasets/utils/data_augmentation.py"
    click DP "https://github.com/cvg/deeplsd/blob/main/deeplsd/datasets/utils/preprocessing.py"
    click MODEL "https://github.com/cvg/deeplsd/blob/main/deeplsd/models/deeplsd.py"
    click MODEL "https://github.com/cvg/deeplsd/blob/main/deeplsd/models/deeplsd_inference.py"
    click MODEL "https://github.com/cvg/deeplsd/blob/main/deeplsd/models/base_model.py"
    click MODEL "https://github.com/cvg/deeplsd/blob/main/deeplsd/models/lbd.py"
    click MODEL "https://github.com/cvg/deeplsd/blob/main/deeplsd/models/line_refiner.py"
    click MODEL "https://github.com/cvg/deeplsd/blob/main/deeplsd/models/backbones/vgg_unet.py"
    click GEO "https://github.com/cvg/deeplsd/blob/main/deeplsd/geometry/homography_adaptation.py"
    click GEO "https://github.com/cvg/deeplsd/blob/main/deeplsd/geometry/line_utils.py"
    click GEO "https://github.com/cvg/deeplsd/blob/main/deeplsd/geometry/projection.py"
    click GEO "https://github.com/cvg/deeplsd/blob/main/deeplsd/geometry/utils.py"
    click GEO "https://github.com/cvg/deeplsd/blob/main/deeplsd/geometry/viz_2d.py"
    click EVAL "https://github.com/cvg/deeplsd/blob/main/deeplsd/evaluation/ls_evaluation.py"
    click CLI "https://github.com/cvg/deeplsd/blob/main/deeplsd/scripts/train.py"
    click CLI "https://github.com/cvg/deeplsd/blob/main/deeplsd/scripts/export_features.py"
    click CLI "https://github.com/cvg/deeplsd/blob/main/deeplsd/scripts/homography_adaptation_df.py"
    click CLI "https://github.com/cvg/deeplsd/blob/main/deeplsd/scripts/evaluate_line_detection.py"
    click CLI "https://github.com/cvg/deeplsd/blob/main/deeplsd/scripts/evaluate_vp_estimation.py"
    click CLI "https://github.com/cvg/deeplsd/blob/main/deeplsd/scripts/line_refinement.py"
    click SETTINGS "https://github.com/cvg/deeplsd/blob/main/deeplsd/settings.py"
    click CPP_SOLVER "https://github.com/cvg/deeplsd/blob/main/line_refinement/CMakeLists.txt"
    click CPP_SOLVER "https://github.com/cvg/deeplsd/blob/main/line_refinement/line_vp_optim.cpp"
    click CPP_SOLVER "https://github.com/cvg/deeplsd/blob/main/line_refinement/cost_functions.h"
    click CPP_SOLVER "https://github.com/cvg/deeplsd/blob/main/line_refinement/vp_det.h"
    click CPP_SOLVER "https://github.com/cvg/deeplsd/blob/main/line_refinement/setup.py"
    click THIRD "https://github.com/cvg/deeplsd/tree/main/third_party/"
    click NOTEBOOKS "https://github.com/cvg/deeplsd/tree/main/notebooks/"
    click ASSETS "https://github.com/cvg/deeplsd/tree/main/assets/images/"
    click ASSETS "https://github.com/cvg/deeplsd/tree/main/assets/videos/"

    %% Styles
    classDef python fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef cpp fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10;
    classDef external fill:#FFE6CC,stroke:#CC5500,color:#CC5500;
    classDef data fill:#F0F0F0,stroke:#888888,color:#555555;
```
