# davisking/dlib architecture

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

- Interactive diagram: https://gitdiagram.com/davisking/dlib
- Repository: https://github.com/davisking/dlib

## Overview

##### Project type and purpose
- This is dlib: an open-source, modern C++ toolkit (header-only plus optional compiled components) providing machine learning algorithms, computer vision, linear algebra, and a Python API.
- It also includes examples, tests, documentation, and helper tools for training models and converting networks.

##### File structure
- Top-level directories:
- dlib/          ← the core C++ library source and headers, organized by modules (dnn, image_processing, matrix, svm, etc.)
- examples/      ← C++ sample programs showing how to use each feature
- python_examples/← pure Python usage examples of the Python API
- tools/         ← command-line utilities and scripts (e.g., imglab, htmlify, convert_dlib_nets_to_caffe)
- docs/          ← XML-based documentation sources and build scripts
- dlib/test/     ← C++ unit tests
- CMakeLists.txt, setup.py, pyproject.toml ← build configurations for C++ and Python APIs
- Build system:
- CMake drives compilation of core modules, examples, tools, tests
- Uses FindBLAS, CUDA, pybind11, etc., via dlib/cmake_utils and .github workflows
- Python binding:
- Under tools/python/src, leverages pybind11 to expose C++ functions/types as a pip-installable package

##### README for additional insights
- Confirms C++ and Python build instructions, external dependencies (AVX, CUDA, BLAS), testing commands

##### Final advice
- Compile-time variability: show decision nodes for AVX/CUDA detection and backend selection
- Avoid over-splitting trivial headers; focus on high-value components that users and contributors care about

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core C++ Library Modules"
        direction TB
        DNN["DNN Module"]:::core
        ImageProc["Image Processing Module"]:::core
        Matrix["Matrix Module"]:::core
        Stats["Statistics Module"]:::core
        Opt["Optimization Module"]:::core
        SVM["SVM Module"]:::core
        GUI_Core["GUI Core Module"]:::core
        GUI_Widgets["GUI Widgets Module"]:::core
        Threading["Threading Module"]:::core
        ImageIO["Image I/O (image_io.h)"]:::core
        DataIO["Data I/O Module"]:::core
        ImageLoader["Image Loader Module"]:::core
        ImageSaver["Image Saver Module"]:::core
    end

    subgraph "Build & Configuration"
        direction TB
        CMakeTop["Top-level CMakeLists.txt"]:::build
        DlibCMake["dlib/CMakeLists.txt"]:::build
        CMakeUtils["CMake Utilities & Find Scripts"]:::build
    end

    subgraph "Python API"
        direction TB
        PySrc["Python Extension Source"]:::python
        PyInit["Python Package Entry & Templates"]:::python
        PyPkgCfg["Python Packaging Configs"]:::python
    end

    subgraph "Examples & Tools"
        direction TB
        CppExamples["C++ Examples"]:::examples
        PyExamples["Python Examples"]:::examples
        subgraph "Tools"
            direction TB
            Imglab["imglab Tool"]:::examples
            Htmlify["htmlify Tool"]:::examples
            Convert["Convert DNN Nets to Caffe"]:::examples
        end
    end

    subgraph "Documentation & Tests"
        direction TB
        Docs["Documentation Sources"]:::docs
        Tests["C++ Unit Tests"]:::docs
    end

    subgraph "External Dependencies"
        direction TB
        BLAS["BLAS/LAPACK"]:::external
        JPEG["JPEG Library"]:::external
        PNG["PNG Library"]:::external
        WebP["WebP Library"]:::external
        Zlib["zlib"]:::external
        Pybind11["pybind11"]:::external
    end

    %% Relationships
    CMakeTop -->|compiles| DNN
    CMakeTop -->|compiles| ImageProc
    CMakeTop -->|compiles| Matrix
    CMakeTop -->|compiles| Stats
    CMakeTop -->|compiles| Opt
    CMakeTop -->|compiles| SVM
    CMakeTop -->|compiles| GUI_Core
    CMakeTop -->|compiles| GUI_Widgets
    CMakeTop -->|compiles| Threading
    CMakeTop -->|compiles| ImageIO
    CMakeTop -->|compiles| DataIO
    CMakeTop -->|compiles| ImageLoader
    CMakeTop -->|compiles| ImageSaver
    CMakeTop -->|builds Python extension| PySrc
    DlibCMake -->|includes| CMakeUtils

    PySrc -->|packages via| PyInit
    PyInit -->|configured by| PyPkgCfg

    DNN -->|used by| CppExamples
    ImageProc -->|used by| CppExamples
    Matrix -->|used by| CppExamples
    DNN -->|used by| PyExamples
    ImageProc -->|used by| PyExamples

    DNN -->|used by| Imglab
    GUI_Core -->|used by| Imglab
    DNN -->|used by| Htmlify
    DNN -->|used by| Convert

    DNN -->|tested by| Tests
    ImageProc -->|tested by| Tests
    Matrix -->|tested by| Tests

    DNN -->|documented in| Docs
    ImageProc -->|documented in| Docs
    Matrix -->|documented in| Docs

    CMakeUtils -->|finds| BLAS
    CMakeUtils -->|finds| JPEG
    CMakeUtils -->|finds| PNG
    CMakeUtils -->|finds| WebP
    CMakeUtils -->|finds| Zlib
    CMakeUtils -->|includes| Pybind11
    CMakeTop -->|CI Pipelines| CMakeUtils

    %% Click Events
    click DNN "https://github.com/davisking/dlib/tree/master/dlib/dnn/"
    click ImageProc "https://github.com/davisking/dlib/tree/master/dlib/image_processing/"
    click Matrix "https://github.com/davisking/dlib/tree/master/dlib/matrix/"
    click Stats "https://github.com/davisking/dlib/tree/master/dlib/statistics/"
    click Opt "https://github.com/davisking/dlib/tree/master/dlib/optimization/"
    click SVM "https://github.com/davisking/dlib/tree/master/dlib/svm/"
    click GUI_Core "https://github.com/davisking/dlib/tree/master/dlib/gui_core/"
    click GUI_Widgets "https://github.com/davisking/dlib/tree/master/dlib/gui_widgets/"
    click Threading "https://github.com/davisking/dlib/tree/master/dlib/threads/"
    click ImageIO "https://github.com/davisking/dlib/blob/master/dlib/image_io.h"
    click DataIO "https://github.com/davisking/dlib/tree/master/dlib/data_io/"
    click ImageLoader "https://github.com/davisking/dlib/tree/master/dlib/image_loader/"
    click ImageSaver "https://github.com/davisking/dlib/tree/master/dlib/image_saver/"
    click CMakeTop "https://github.com/davisking/dlib/blob/master/CMakeLists.txt"
    click DlibCMake "https://github.com/davisking/dlib/blob/master/dlib/CMakeLists.txt"
    click CMakeUtils "https://github.com/davisking/dlib/tree/master/dlib/cmake_utils/"
    click PySrc "https://github.com/davisking/dlib/tree/master/tools/python/src/"
    click PyInit "https://github.com/davisking/dlib/blob/master/tools/python/dlib/__init__.py.in"
    click PyPkgCfg "https://github.com/davisking/dlib/blob/master/setup.py"
    click CppExamples "https://github.com/davisking/dlib/tree/master/examples/"
    click PyExamples "https://github.com/davisking/dlib/tree/master/python_examples/"
    click Imglab "https://github.com/davisking/dlib/tree/master/tools/imglab/"
    click Htmlify "https://github.com/davisking/dlib/tree/master/tools/htmlify/"
    click Convert "https://github.com/davisking/dlib/tree/master/tools/convert_dlib_nets_to_caffe/"
    click Docs "https://github.com/davisking/dlib/tree/master/docs/"
    click Tests "https://github.com/davisking/dlib/tree/master/dlib/test/"
    click BLAS "https://github.com/davisking/dlib/tree/master/dlib/external/cblas/"
    click JPEG "https://github.com/davisking/dlib/tree/master/dlib/external/libjpeg/"
    click PNG "https://github.com/davisking/dlib/tree/master/dlib/external/libpng/"
    click WebP "https://github.com/davisking/dlib/tree/master/dlib/external/libwebp/"
    click Zlib "https://github.com/davisking/dlib/tree/master/dlib/external/zlib/"
    click Pybind11 "https://github.com/davisking/dlib/tree/master/dlib/external/pybind11/"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef build fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef python fill:#FFF9C4,stroke:#333,stroke-width:1px
    classDef examples fill:#E1BEE7,stroke:#333,stroke-width:1px
    classDef docs fill:#CFD8DC,stroke:#333,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px
```
