# vertical-beach/bytetrack-cpp architecture

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

- Interactive diagram: https://gitdiagram.com/vertical-beach/bytetrack-cpp
- Repository: https://github.com/vertical-beach/bytetrack-cpp

## Overview

##### Project Type and Purpose
- This is an open-source C++ tracking library (“ByteTrack-cpp”) implementing only the Multi-Object Tracking (MOT) algorithm from ByteTrack.
- It does *not* include object detection; instead it exposes a tracking API that any detector can feed.
- It is packaged as a shared library (libbytetrack.so) for C++17-or-higher clients, with a small GoogleTest-based test harness and a Dockerfile for reproducible builds.

##### Key Artifacts from the File Tree
- Top-level build and deployment: CMakeLists.txt, Dockerfile, .gitignore
- Source code API:
- /ByteTrack/*.h – public headers for BYTETracker, STrack, KalmanFilter, Object, Rect, lapjv algorithm
- src/*.cpp – corresponding implementations
- Data for verification: data/YOLOX_ncnn_palace/*.json (tracking & detection results from reference implementation)
- Tests: test/test_BYTETracker.cpp utilizing GoogleTest

##### Main Components
a. Client Application
- Any C++ consumer that:
– Instantiates a Detector (external)
– Feeds detection results into the Tracker API
b. ByteTrack-cpp Shared Library
- Public API Layer (headers in include/ByteTrack)
- Core Tracking Engine:
– BYTETracker (manages per-frame update, tracklet lifecycle)
– STrack (single-object state + feature)
– KalmanFilter (predict/update motion model)
– lapjv (Hungarian-style data association)
- Data Structures: Object, Rect
- Serialization Module (optional): outputs tracklets to JSON (for verification)
c. External Dependencies
- Eigen 3.3 – linear algebra for KalmanFilter
- CMake – build orchestration
- GoogleTest – unit tests (test harness)
- Docker – containerized build/test environment
d. Verification Data
- JSON blobs generated by the ncnn-based reference implementation
- Used both in CI tests and as a sample data source

##### Relationships and Data Flows
1. Build Flow (sidecar):
– CMake + C++ compiler -> compile src/*.cpp -> link into libbytetrack.so
– Optionally, compile test/test_BYTETracker.cpp & link GoogleTest -> test executable
2. Run-Time Flow:
Client App
↓ (calls)
ByteTrack-cpp Public API
↓
Tracking Core
- BYTETracker.update(detections)
- internally: STrack instances + KalmanFilter.predict/update + lapjv.assign()
↓
Tracklet Output
↓
JSON Serializer (or client callback)

##### Architectural Patterns and Principles
- Modular layering: Public API ↔ Core Engine ↔ Data Structures ↔ External linear-algebra library
- Inversion of Control for detection: no detector hard-coded, strong separation of concerns
- Shared library distribution for reuse in multiple C++20+ applications
- Test harness decoupled from core logic via CMake option BUILD_BYTETRACK_TEST

##### Critical Details to Capture
- The decoupling of detection vs. tracking logic
- Core algorithm components (STrack, KalmanFilter, lapjv) inside the library
- The shared-library packaging and test-harness build option
- External dependencies influencing both build and runtime

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        build_cmake["CMake"]:::external
        build_compile["C++ Compiler"]:::external
        build_link["Link libbytetrack.so"]:::core
        build_testbuild["Build Test Harness"]:::core
        build_docker["Docker"]:::external
    end

    build_cmake -->|"orchestrates"| build_compile
    build_compile -->|"compiles src/*.cpp"| build_link
    build_link -->|"produces libbytetrack.so"| build_docker
    build_compile -->|"compiles test/test_BYTETracker.cpp"| build_testbuild
    build_testbuild -->|"links GoogleTest"| build_docker

    %% Runtime Flow
    subgraph "Runtime Flow"
        direction TB
        client["Client Application"]:::client
        detector["Detector (external)"]:::external
        api["ByteTrack-cpp Public API"]:::api
        subgraph "Core Tracking Engine"
            direction TB
            tracker["BYTETracker"]:::core
            strack["STrack"]:::core
            kf["KalmanFilter"]:::core
            da["lapjv"]:::core
            objects["Object, Rect"]:::core
        end
        serializer["JSON Serializer"]:::core
        datastore1["detection_results.json"]:::datastore
        datastore2["tracking_results.json"]:::datastore
    end

    client -->|"frame data"| detector
    detector -->|"detections"| api
    api -->|"calls update()"| tracker
    tracker --> strack
    tracker --> kf
    tracker --> da
    strack --> objects
    kf --> objects
    tracker -->|"outputs tracklets"| serializer
    serializer -->|"writes JSON"| datastore1
    serializer -->|"writes JSON"| datastore2

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        eigen["Eigen 3.3"]:::external
        gtest["GoogleTest"]:::external
    end
    kf --> eigen
    build_testbuild --> gtest

    %% Click Events
    click api "https://github.com/vertical-beach/bytetrack-cpp/tree/main/include/ByteTrack"
    click tracker "https://github.com/vertical-beach/bytetrack-cpp/blob/main/include/ByteTrack/BYTETracker.h"
    click tracker "https://github.com/vertical-beach/bytetrack-cpp/blob/main/src/BYTETracker.cpp"
    click strack "https://github.com/vertical-beach/bytetrack-cpp/blob/main/include/ByteTrack/STrack.h"
    click strack "https://github.com/vertical-beach/bytetrack-cpp/blob/main/src/STrack.cpp"
    click kf "https://github.com/vertical-beach/bytetrack-cpp/blob/main/include/ByteTrack/KalmanFilter.h"
    click kf "https://github.com/vertical-beach/bytetrack-cpp/blob/main/src/KalmanFilter.cpp"
    click da "https://github.com/vertical-beach/bytetrack-cpp/blob/main/include/ByteTrack/lapjv.h"
    click da "https://github.com/vertical-beach/bytetrack-cpp/blob/main/src/lapjv.cpp"
    click objects "https://github.com/vertical-beach/bytetrack-cpp/blob/main/include/ByteTrack/Object.h"
    click objects "https://github.com/vertical-beach/bytetrack-cpp/blob/main/src/Object.cpp"
    click objects "https://github.com/vertical-beach/bytetrack-cpp/blob/main/include/ByteTrack/Rect.h"
    click objects "https://github.com/vertical-beach/bytetrack-cpp/blob/main/src/Rect.cpp"
    click build_testbuild "https://github.com/vertical-beach/bytetrack-cpp/blob/main/test/test_BYTETracker.cpp"
    click build_cmake "https://github.com/vertical-beach/bytetrack-cpp/blob/main/CMakeLists.txt"
    click build_docker "https://github.com/vertical-beach/bytetrack-cpp/tree/main/Dockerfile"
    click datastore1 "https://github.com/vertical-beach/bytetrack-cpp/blob/main/data/YOLOX_ncnn_palace/detection_results.json"
    click datastore2 "https://github.com/vertical-beach/bytetrack-cpp/blob/main/data/YOLOX_ncnn_palace/tracking_results.json"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef api fill:#d4edda,stroke:#155724,color:#155724
    classDef client fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#ffe5b4,stroke:#ff8c00,color:#ff8c00
    classDef datastore fill:#f8f9fa,stroke:#6c757d,color:#6c757d
```
