How vertical-beach/bytetrack-cpp works
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