|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +**motcpp** is a modern C++ multi-object tracking (MOT) library implementing 10 state-of-the-art tracking algorithms (SORT, ByteTrack, OC-SORT, DeepOC-SORT, StrongSORT, BoT-SORT, BoostTrack, HybridSORT, UCMCTrack, OracleTrack). It is a C++ port of the Python BoxMOT library, targeting 10–100x speed improvements over Python equivalents. |
| 8 | + |
| 9 | +**License**: AGPL-3.0 |
| 10 | +**Requires**: C++17, CMake 3.20+, OpenCV 4.x, Eigen3, yaml-cpp |
| 11 | +**Optional**: ONNX Runtime (ReID features), spdlog, GoogleTest (auto-fetched) |
| 12 | + |
| 13 | +## Build Commands |
| 14 | + |
| 15 | +```bash |
| 16 | +# Standard build |
| 17 | +cmake -B build -DCMAKE_BUILD_TYPE=Release |
| 18 | +cmake --build build -j$(nproc) |
| 19 | + |
| 20 | +# Build with tests (default: ON) |
| 21 | +cmake -B build -DMOTCPP_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug |
| 22 | +cmake --build build -j$(nproc) |
| 23 | + |
| 24 | +# Run tests |
| 25 | +cd build && ctest --output-on-failure |
| 26 | + |
| 27 | +# Run a single test binary |
| 28 | +./build/tests/motcpp_tests --gtest_filter=TestSuiteName.TestCaseName |
| 29 | + |
| 30 | +# Coverage report |
| 31 | +cmake -B build -DMOTCPP_COVERAGE=ON |
| 32 | +cmake --build build --target coverage |
| 33 | +# Output: build/coverage_report/index.html |
| 34 | + |
| 35 | +# Build shared library |
| 36 | +cmake -B build -DBUILD_SHARED_LIBS=ON |
| 37 | + |
| 38 | +# Disable ONNX (motion-only trackers) |
| 39 | +cmake -B build -DMOTCPP_ENABLE_ONNX=OFF |
| 40 | +``` |
| 41 | + |
| 42 | +**Key CMake options**: |
| 43 | +| Option | Default | Purpose | |
| 44 | +|--------|---------|---------| |
| 45 | +| `MOTCPP_BUILD_TESTS` | ON | GoogleTest unit tests | |
| 46 | +| `MOTCPP_BUILD_BENCHMARKS` | OFF | Benchmark targets | |
| 47 | +| `MOTCPP_BUILD_EXAMPLES` | ON | Example binaries | |
| 48 | +| `MOTCPP_BUILD_TOOLS` | ON | `motcpp_eval` CLI tool | |
| 49 | +| `MOTCPP_ENABLE_ONNX` | ON | ONNX Runtime for ReID | |
| 50 | +| `MOTCPP_COVERAGE` | OFF | gcov/lcov coverage | |
| 51 | +| `BUILD_SHARED_LIBS` | OFF | Static by default | |
| 52 | + |
| 53 | +## Architecture |
| 54 | + |
| 55 | +### Data Flow |
| 56 | + |
| 57 | +``` |
| 58 | +Detections (N×6: x1,y1,x2,y2,conf,cls) |
| 59 | + ↓ |
| 60 | + BaseTracker::update() |
| 61 | + ↓ |
| 62 | + ┌──────────────────────────────────┐ |
| 63 | + │ 1. Pre-process & validate │ |
| 64 | + │ 2. Predict existing tracks │ |
| 65 | + │ 3. Compute cost matrix │ |
| 66 | + │ (IoU / appearance / hybrid) │ |
| 67 | + │ 4. Hungarian assignment │ |
| 68 | + │ 5. Update matched tracks │ |
| 69 | + │ 6. Birth/death track states │ |
| 70 | + └──────────────────────────────────┘ |
| 71 | + ↓ |
| 72 | +Tracks (M×8: x1,y1,x2,y2,id,conf,cls,det_idx) |
| 73 | +``` |
| 74 | + |
| 75 | +### Key Abstractions |
| 76 | + |
| 77 | +**`BaseTracker`** (`include/motcpp/tracker.hpp`, `src/tracker.cpp`) |
| 78 | +Abstract base class for all trackers. Defines `update(dets, img)` and `reset()`. Manages per-class tracking, input validation, and visualization utilities. All 10 trackers inherit from this. |
| 79 | + |
| 80 | +**Motion Models** (`include/motcpp/motion/`, `src/motion/`) |
| 81 | +- `KalmanFilterXYSR` — state: [x, y, scale, aspect ratio]; used by SORT, OC-SORT, BoostTrack |
| 82 | +- `KalmanFilterXYAH` — state: [x, y, aspect ratio, height]; used by ByteTrack, StrongSORT, OracleTrack |
| 83 | +- `UCMCKalmanFilter` — ground-plane model for camera motion compensation |
| 84 | +- `BaseKalmanFilter` — common interface: `initiate`, `predict`, `update`, `project` |
| 85 | + |
| 86 | +**Association** (`include/motcpp/utils/`, `src/utils/`) |
| 87 | +- `iou.hpp` — IoU, GIoU, DIoU, CIoU computations |
| 88 | +- `matching.hpp` — Hungarian algorithm (linear assignment), cascade matching |
| 89 | +- `association.hpp` — Mahalanobis and Gaussian gating distances |
| 90 | + |
| 91 | +**Appearance / ReID** (`include/motcpp/appearance/`, `src/appearance/`) |
| 92 | +- `ReIDBackend` — abstract interface for feature extraction |
| 93 | +- `ONNXBackend` — ONNX Runtime implementation |
| 94 | +- Used by: DeepOC-SORT, StrongSORT, BoT-SORT, BoostTrack, HybridSORT |
| 95 | + |
| 96 | +**Configuration** (`include/motcpp/config.hpp`, `src/config.cpp`) |
| 97 | +YAML-based config loading. Per-tracker default configs live in `configs/trackers/*.yaml`. Supports float/int/bool/string parameters. |
| 98 | + |
| 99 | +### Tracker Categories |
| 100 | + |
| 101 | +| Motion-only | Appearance (ReID) required | |
| 102 | +|-------------|---------------------------| |
| 103 | +| SORT, ByteTrack, OC-SORT, UCMCTrack, OracleTrack | DeepOC-SORT, StrongSORT, BoT-SORT, BoostTrack, HybridSORT | |
| 104 | + |
| 105 | +### Source Layout |
| 106 | + |
| 107 | +``` |
| 108 | +include/motcpp/ ← Public headers (installed with library) |
| 109 | + motcpp.hpp ← Single-include entrypoint |
| 110 | + tracker.hpp ← BaseTracker interface |
| 111 | + trackers/ ← One header per tracker |
| 112 | + motion/ ← Kalman filter interfaces |
| 113 | + appearance/ ← ReID backend interfaces |
| 114 | + utils/ ← IoU, matching, ops |
| 115 | + association/ ← LAP solver |
| 116 | +
|
| 117 | +src/ ← Implementations (.cpp) |
| 118 | + trackers/ motion/ appearance/ utils/ data/ |
| 119 | +
|
| 120 | +tests/ ← GoogleTest unit tests (per module) |
| 121 | +configs/trackers/ ← YAML defaults per tracker |
| 122 | +cmake/ ← ONNX download, model export, package config |
| 123 | +scripts/ ← Benchmarking, ReID export, eval helpers |
| 124 | +assets/ ← MOT17 mini datasets for testing |
| 125 | +``` |
| 126 | + |
| 127 | +## Code Style |
| 128 | + |
| 129 | +The repo uses `.clang-format`. Run before committing: |
| 130 | +```bash |
| 131 | +clang-format -i src/**/*.cpp include/**/*.hpp |
| 132 | +``` |
| 133 | + |
| 134 | +## Adding a New Tracker |
| 135 | + |
| 136 | +1. Add header to `include/motcpp/trackers/my_tracker.hpp` inheriting `BaseTracker` |
| 137 | +2. Add implementation to `src/trackers/my_tracker.cpp` |
| 138 | +3. Include it in `include/motcpp/motcpp.hpp` |
| 139 | +4. Add a YAML config to `configs/trackers/` |
| 140 | +5. Register in `src/tracker_factory.cpp` (if a factory exists) or the CMakeLists source list |
| 141 | +6. Add tests in `tests/test_my_tracker.cpp` |
0 commit comments