# ubiqelife-lin/opentld architecture

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

- Interactive diagram: https://gitdiagram.com/ubiqelife-lin/opentld
- Repository: https://github.com/ubiqelife-lin/opentld

## Overview

##### Project Type and Purpose
- This is a native C++ computer‐vision tracking toolkit and application (“OpenTLD”), implementing the TLD (Tracking-Learning-Detection) algorithm.
- It comprises a reusable library (`libopentld`), two executables (CLI: `opentld`, and GUI: `qopentld`), plus third-party embedded libs (cvblobs, libconfig), build scripts, and packaging manifests.

##### File-Structure Analysis
- Top level
- CMakeLists.txt, OpenTLDConfig.cmake.in → build orchestration via CMake
- debian/ → Debian packaging metadata
- src/
- src/3rdparty/cvblobs → image-segmentation helpers
- src/3rdparty/libconfig → configuration-file parser
- src/libopentld → core modules:
– imacq: frame acquisition (camera, video, stream)
– mftracker: median-flow tracker implementations
– tld: detection (cascade, classifiers), model update, clustering
- src/opentld → command-line front end (`OpenTLD.cpp`, image display, keyboard shortcuts)
- src/opentld/qopentld → Qt GUI front end (ConfigDialog.ui + handlers)
- Packaging: debian rules and manpages; desktop files for Linux menus.

##### README Insights
- Confirms use of OpenCV, CMake, optional libconfig++ and Qt4.
- Describes CLI vs GUI executables, command-line flags, config file usage.
- Suggests out-of-source CMake build and package steps.

##### Main Components
A. External Dependencies
- OpenCV (image processing, display)
- Qt4 (GUI dialog) – optional
- libconfig++ (configuration parser) – optional
- OpenMP (parallelization) – optional
B. Embedded Third-Party
- cvblobs (blob extraction)
- libconfig (C API)
C. Core Library (`libopentld`)
1. Image Acquisition (ImAcq)
2. Tracking (MFTracker: BB, FBTrack, LK methods, median filter)
3. Detection & Learning (TLD: cascade, ensemble classifier, NNClassifier, ForegroundDetector, VarianceFilter)
4. Model Management (export/import, configuration)
D. Front Ends
- CLI (`opentld`): frame loop → ImAcq → TLD pipeline → console/display → keyboard input
- Qt GUI (`qopentld`): wraps same pipeline with Qt widgets for config, frame view, controls
E. Build & Packaging
- CMake build graph → produces static/shared libs + executables
- Packaging: Debian control files, desktop entries, manpages

##### Relationships & Data Flow
- User → selects input (camera, video, images, RTSP)
- ImAcq streams frames into core TLD pipeline
- Results → drawn on display (CLI/Qt) → user controls (keyboard or GUI) feed back into config and learning mode
- Config parameters read by libconfig at startup; dynamic changes via GUI/CLI toggle features
- Model import/export via file I/O

##### Architectural Patterns & Design Principles
- Modular library core with clear separation of concerns (acquisition, tracking, detection)
- Pluggable front ends (console vs Qt GUI) depending on build flags
- Embedded third-party code to avoid external dependencies by default; optional `USE_SYSTEM_LIBS` flag
- CMake-driven out-of-source builds, conditional targets (BUILD_QOPENTLD)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        OPE["OpenCV"]:::external
        QT["Qt4 (optional)"]:::external
        LC["libconfig++ (optional)"]:::external
        OMP["OpenMP (optional)"]:::external
    end

    %% Embedded Third-Party
    subgraph "Embedded Third-Party"
        CVBLOBS["cvblobs"]:::embedded
        LCAPI["libconfig C API"]:::embedded
    end

    %% Core Library
    subgraph "Core: libopentld"
        IMACQ["ImAcq"]:::core
        MFT["MFTracker"]:::core
        TLDDET["TLD Detector & Learning"]:::core
        UTIL["Model I/O"]:::core
    end

    %% Front-End Executables
    subgraph "Front Ends"
        CLI["CLI: opentld"]:::ui
        QTG["Qt GUI: qopentld"]:::ui
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        BUILD["CMake"]:::build
        DEB["Debian Packaging"]:::build
    end

    %% Data & Dependency Flows
    OPE -->|image processing| IMACQ
    OPE -->|vision algorithms| MFT
    OPE -->|feature extraction| TLDDET
    QT -->|GUI dialogs| QTG
    LC -->|config parsing| IMACQ
    LC -->|config parsing| TLDDET
    OMP -->|parallel loops| MFT

    CVBLOBS -->|blob extraction| MFT
    LCAPI -->|config C API| IMACQ
    LCAPI -->|config C API| TLDDET

    IMACQ -->|frame stream| MFT
    MFT -->|predicted BB| TLDDET
    TLDDET -->|updated BB| CLI
    TLDDET -->|updated BB| QTG

    CLI -->|keyboard input| IMACQ
    QTG -->|GUI controls| IMACQ

    TLDDET -->|model load/save| UTIL
    UTIL -->|utilities| TLDDET

    BUILD -->|build targets| IMACQ
    BUILD --> MFT
    BUILD --> TLDDET
    BUILD --> UTIL
    BUILD --> CLI
    BUILD --> QTG

    BUILD --> DEB

    %% Click Events
    click CVBLOBS "https://github.com/ubiqelife-lin/opentld/tree/master/src/3rdparty/cvblobs"
    click LCAPI "https://github.com/ubiqelife-lin/opentld/tree/master/src/3rdparty/libconfig"
    click IMACQ "https://github.com/ubiqelife-lin/opentld/blob/master/src/libopentld/imacq/ImAcq.cpp"
    click MFT "https://github.com/ubiqelife-lin/opentld/tree/master/src/libopentld/mftracker"
    click TLDDET "https://github.com/ubiqelife-lin/opentld/tree/master/src/libopentld/tld"
    click UTIL "https://github.com/ubiqelife-lin/opentld/blob/master/src/libopentld/tld/TLDUtil.cpp"
    click CLI "https://github.com/ubiqelife-lin/opentld/blob/master/src/opentld/OpenTLD.cpp"
    click QTG "https://github.com/ubiqelife-lin/opentld/blob/master/src/opentld/qopentld/ConfigDialog.ui"
    click BUILD "https://github.com/ubiqelife-lin/opentld/blob/master/CMakeLists.txt"
    click DEB "https://github.com/ubiqelife-lin/opentld/tree/master/debian/"

    %% Styling
    classDef external fill:#DDEEFF,stroke:#0000FF,color:#0000FF;
    classDef embedded fill:#EEFFDD,stroke:#00AA00,color:#006600;
    classDef core fill:#FFEEDD,stroke:#FF8800,color:#AA5500;
    classDef ui fill:#F0DDFF,stroke:#AA00AA,color:#660066;
    classDef build fill:#DDDDDD,stroke:#888888,color:#333333;
```
