From 31d07405232a2e424cd32a2edbbd50214ecf5e11 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Tue, 29 Jul 2025 14:49:10 +0000
Subject: [PATCH] Add Chinese tutorial documentation for Multitarget-tracker
 project

Co-authored-by: zzp726000g6 <zzp726000g6@2925.com>
---
 TUTORIAL_CN.md | 555 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 555 insertions(+)
 create mode 100644 TUTORIAL_CN.md

diff --git a/TUTORIAL_CN.md b/TUTORIAL_CN.md
new file mode 100644
index 00000000..8fac9ff5
--- /dev/null
+++ b/TUTORIAL_CN.md
@@ -0,0 +1,555 @@
+# Multitarget-tracker 多目标跟踪项目教程
+
+## 项目简介
+
+Multitarget-tracker 是一个功能强大的多目标跟踪系统，支持多种检测器和跟踪算法。该项目可以用于视频中的目标检测、跟踪和分析，广泛应用于计算机视觉、视频监控、自动驾驶等领域。
+
+### 主要特性
+
+- 🎯 **多种检测器支持**：背景减除、YOLO（v3-v12）、人脸检测、行人检测等
+- 🚀 **多种跟踪算法**：卡尔曼滤波器、匈牙利算法、双目标算法等
+- 🔧 **灵活的配置**：支持多种距离度量、匹配算法和预测模型
+- 📱 **多平台支持**：Windows、Linux、macOS
+- 🐍 **Python 接口**：提供 Python 包装器，易于集成
+- ⚡ **硬件加速**：支持 OpenCL、CUDA、TensorRT
+
+## 环境准备
+
+### 系统要求
+
+- 操作系统：Ubuntu 18.04+、Windows 10+、macOS
+- 编译器：GCC 7+、MSVC 2017+、Clang
+- CMake 3.9+
+- Python 3.6+（如需 Python 接口）
+
+### 依赖库安装
+
+#### 1. OpenCV 安装
+
+```bash
+# Ubuntu/Debian
+sudo apt update
+sudo apt install libopencv-dev libopencv-contrib-dev
+
+# 或从源码编译
+git clone https://github.com/opencv/opencv.git
+git clone https://github.com/opencv/opencv_contrib.git
+cd opencv
+mkdir build && cd build
+cmake -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules ..
+make -j$(nproc)
+sudo make install
+```
+
+#### 2. 其他依赖
+
+```bash
+# Ubuntu/Debian
+sudo apt install cmake build-essential git
+
+# 可选：CUDA 和 cuDNN（用于 GPU 加速）
+# 下载并安装 NVIDIA CUDA Toolkit 和 cuDNN
+
+# 可选：TensorRT（用于 YOLO TensorRT 检测器）
+# 下载并安装 NVIDIA TensorRT
+```
+
+## 编译安装
+
+### 1. 克隆项目
+
+```bash
+git clone https://github.com/Smorodov/Multitarget-tracker.git
+cd Multitarget-tracker
+```
+
+### 2. 基础编译
+
+```bash
+mkdir build
+cd build
+cmake .. -DUSE_OCV_BGFG=ON -DUSE_OCV_KCF=ON -DUSE_OCV_UKF=ON
+make -j$(nproc)
+```
+
+### 3. 完整功能编译
+
+```bash
+cmake .. \
+    -DUSE_OCV_BGFG=ON \
+    -DUSE_OCV_KCF=ON \
+    -DUSE_OCV_UKF=ON \
+    -DBUILD_YOLO_LIB=ON \
+    -DBUILD_YOLO_TENSORRT=ON \
+    -DBUILD_ASYNC_DETECTOR=ON \
+    -DBUILD_CARS_COUNTING=ON
+make -j$(nproc)
+```
+
+### 4. Python 包安装
+
+```bash
+# 直接从源码安装
+pip install .
+
+# 或者开发模式安装
+pip install -e .
+```
+
+### 编译选项说明
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `USE_OCV_BGFG` | 启用 OpenCV 背景减除算法 | OFF |
+| `USE_OCV_KCF` | 启用 OpenCV KCF 跟踪器 | OFF |
+| `USE_OCV_UKF` | 启用无迹卡尔曼滤波器 | OFF |
+| `BUILD_YOLO_LIB` | 编译 YOLO Darknet 库 | OFF |
+| `BUILD_YOLO_TENSORRT` | 编译 YOLO TensorRT 支持 | OFF |
+| `BUILD_ASYNC_DETECTOR` | 编译异步检测器示例 | OFF |
+| `BUILD_CARS_COUNTING` | 编译车辆计数示例 | OFF |
+| `SILENT_WORK` | 禁用所有显示窗口 | OFF |
+
+## 快速开始
+
+### 1. C++ 示例
+
+#### 基本使用
+
+```bash
+# 运行鼠标跟踪示例
+./MultitargetTracker 0 -e=0
+
+# 运行运动检测示例
+./MultitargetTracker ../data/atrium.avi -e=1
+
+# 运行人脸检测示例
+./MultitargetTracker 0 -e=2
+
+# 运行 YOLO 检测示例
+./MultitargetTracker ../data/test.mp4 -e=6
+```
+
+#### 命令行参数
+
+```bash
+./MultitargetTracker <视频文件> [选项]
+
+选项：
+  -e, --example=N          示例类型 (0-6)
+  -sf, --start_frame=N     起始帧号
+  -ef, --end_frame=N       结束帧号
+  -o, --out=文件名         输出视频文件
+  -sl, --show_logs=0/1     显示日志
+  -g, --gpu=0/1            使用 GPU
+  -a, --async=0/1          异步处理
+  -r, --res=文件名         CSV 结果文件
+  -s, --settings=文件名    配置文件
+```
+
+### 2. Python 示例
+
+#### 基础运动检测
+
+```python
+import cv2
+import pymtracking as mt
+
+# 打开视频
+cap = cv2.VideoCapture('test_video.mp4')
+ret, frame = cap.read()
+
+# 配置背景减除器
+config = mt.KeyVal()
+config.Add('history', '1000')
+config.Add('nmixtures', '3')
+config.Add('backgroundRatio', '0.7')
+
+# 创建检测器
+detector = mt.BaseDetector(mt.BaseDetector.Detectors.MOG, config, frame)
+
+# 配置跟踪器
+tracker_settings = mt.TrackerSettings()
+tracker_settings.SetDistance(mt.MTracker.DistRects)
+tracker_settings.kalmanType = mt.MTracker.KalmanLinear
+tracker_settings.filterGoal = mt.MTracker.FilterCenter
+tracker_settings.matchType = mt.MTracker.MatchHungrian
+
+# 创建跟踪器
+tracker = mt.MTracker(tracker_settings)
+
+while True:
+    ret, frame = cap.read()
+    if not ret:
+        break
+    
+    # 检测
+    detector.Detect(frame)
+    regions = detector.GetDetects()
+    
+    # 跟踪
+    fps = 30  # 视频帧率
+    tracker.Update(regions, frame, fps)
+    tracks = tracker.GetTracks()
+    
+    # 绘制结果
+    for track in tracks:
+        if track.IsRobust(int(fps/4), 0.7, (0.1, 10.), 3):
+            rect = track.GetBoundingRect()
+            cv2.rectangle(frame, (rect.x, rect.y), 
+                         (rect.x + rect.width, rect.y + rect.height), 
+                         (0, 255, 0), 2)
+    
+    cv2.imshow('跟踪结果', frame)
+    if cv2.waitKey(1) & 0xFF == ord('q'):
+        break
+
+cap.release()
+cv2.destroyAllWindows()
+```
+
+## 核心组件详解
+
+### 1. 检测器 (Detectors)
+
+#### 1.1 背景减除检测器
+
+```python
+# MOG2 背景减除
+config = mt.KeyVal()
+config.Add('history', '500')
+config.Add('detectShadows', 'true')
+detector = mt.BaseDetector(mt.BaseDetector.Detectors.MOG2, config, frame)
+
+# VIBE 背景减除
+detector = mt.BaseDetector(mt.BaseDetector.Detectors.Motion_VIBE, config, frame)
+
+# SuBSENSE 背景减除
+detector = mt.BaseDetector(mt.BaseDetector.Detectors.Motion_SuBSENSE, config, frame)
+```
+
+#### 1.2 深度学习检测器
+
+```python
+# YOLO Darknet 检测器
+config = mt.KeyVal()
+config.Add('modelConfiguration', 'yolo.cfg')
+config.Add('modelBinary', 'yolo.weights')
+config.Add('classNames', 'coco.names')
+config.Add('confidenceThreshold', '0.5')
+config.Add('nmsThreshold', '0.4')
+detector = mt.BaseDetector(mt.BaseDetector.Detectors.Yolo_Darknet, config, frame)
+
+# DNN OpenCV 检测器
+config.Add('modelConfiguration', 'MobileNetSSD_deploy.prototxt')
+config.Add('modelBinary', 'MobileNetSSD_deploy.caffemodel')
+detector = mt.BaseDetector(mt.BaseDetector.Detectors.DNN_OCV, config, frame)
+```
+
+### 2. 跟踪器配置
+
+#### 2.1 距离度量
+
+```python
+tracker_settings = mt.TrackerSettings()
+
+# 中心点欧几里得距离
+tracker_settings.SetDistance(mt.MTracker.DistCenters)
+
+# 矩形欧几里得距离
+tracker_settings.SetDistance(mt.MTracker.DistRects)
+
+# Jaccard/IoU 距离
+tracker_settings.SetDistance(mt.MTracker.DistJaccard)
+```
+
+#### 2.2 卡尔曼滤波器
+
+```python
+# 线性卡尔曼滤波器
+tracker_settings.kalmanType = mt.MTracker.KalmanLinear
+
+# 无迹卡尔曼滤波器
+tracker_settings.kalmanType = mt.MTracker.KalmanUnscented
+
+# 滤波目标
+tracker_settings.filterGoal = mt.MTracker.FilterCenter  # 仅坐标
+tracker_settings.filterGoal = mt.MTracker.FilterRect    # 坐标和尺寸
+```
+
+#### 2.3 匹配算法
+
+```python
+# 匈牙利算法
+tracker_settings.matchType = mt.MTracker.MatchHungrian
+
+# 双线性匹配
+tracker_settings.matchType = mt.MTracker.MatchBipart
+```
+
+### 3. 高级跟踪选项
+
+#### 3.1 视觉搜索
+
+```python
+# 禁用视觉搜索
+tracker_settings.lostTrackType = mt.MTracker.TrackNone
+
+# KCF 跟踪器
+tracker_settings.lostTrackType = mt.MTracker.TrackKCF
+
+# CSRT 跟踪器
+tracker_settings.lostTrackType = mt.MTracker.TrackCSRT
+
+# STAPLE 跟踪器
+tracker_settings.lostTrackType = mt.MTracker.TrackSTAPLE
+```
+
+#### 3.2 重要参数设置
+
+```python
+tracker_settings.useAcceleration = False       # 是否使用加速度
+tracker_settings.dt = 0.3                      # 时间间隔
+tracker_settings.accelNoiseMag = 0.1           # 加速度噪声
+tracker_settings.distThres = 0.8               # 距离阈值
+tracker_settings.maximumAllowedSkippedFrames = 50  # 最大跳帧数
+tracker_settings.maxTraceLength = 50           # 最大轨迹长度
+```
+
+## 高级功能
+
+### 1. 异步处理
+
+项目支持三种处理模式：
+
+#### 1.1 同步模式
+- 单线程顺序处理
+- 适用于快速算法
+
+#### 1.2 双线程模式
+- 检测和跟踪分离
+- 提高处理效率
+
+#### 1.3 完全异步模式
+- 四线程并行处理
+- 适用于慢速但精确的检测器
+
+### 2. 车辆计数
+
+```bash
+# 编译车辆计数示例
+cmake .. -DBUILD_CARS_COUNTING=ON
+make
+
+# 运行车辆计数
+./CarsCounting ../data/traffic.mp4
+```
+
+### 3. TensorRT 加速
+
+```bash
+# 安装 TensorRT
+# 编译支持
+cmake .. -DBUILD_YOLO_TENSORRT=ON
+
+# 导出 ONNX 模型
+python export_onnx.py --weights yolov8n.pt --include onnx
+
+# 运行 TensorRT 检测
+./MultitargetTracker test.mp4 -e=6
+```
+
+## 配置文件
+
+### 1. INI 配置文件示例
+
+```ini
+[Detector]
+Type=6                    # YOLO TensorRT
+ModelPath=yolo.onnx
+ConfThreshold=0.5
+NMSThreshold=0.4
+MaxBatch=1
+
+[Tracker]
+DistType=2               # DistJaccard
+KalmanType=0             # KalmanLinear
+FilterGoal=1             # FilterRect
+MatchType=0              # MatchHungrian
+UseAcceleration=false
+dt=0.3
+AccelNoiseMag=0.1
+DistThres=0.8
+MaxSkippedFrames=30
+MaxTraceLength=50
+
+[Paths]
+ModelConfig=models/yolo.cfg
+ModelWeights=models/yolo.weights
+ClassNames=models/coco.names
+```
+
+### 2. 使用配置文件
+
+```bash
+./MultitargetTracker video.mp4 --settings=config.ini
+```
+
+## 性能优化
+
+### 1. 编译优化
+
+```bash
+# 使用 Release 模式
+cmake .. -DCMAKE_BUILD_TYPE=Release
+
+# 启用本地指令集优化
+cmake .. -DCMAKE_CXX_FLAGS="-march=native -mtune=native"
+
+# 启用 OpenMP
+cmake .. -DUSE_OPENMP=ON
+```
+
+### 2. 运行时优化
+
+```python
+# 设置合适的检测阈值
+detector.SetMinObjectSize((20, 20))  # 最小目标尺寸
+
+# 调整跟踪参数
+tracker_settings.distThres = 0.7     # 降低距离阈值
+tracker_settings.maxTraceLength = 30 # 减少轨迹长度
+```
+
+### 3. 内存优化
+
+```python
+# 使用灰度图处理（如果检测器支持）
+if detector.CanGrayProcessing():
+    gray_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+    detector.Detect(gray_frame)
+```
+
+## 常见问题
+
+### 1. 编译问题
+
+**Q: 找不到 OpenCV**
+```bash
+# 指定 OpenCV 路径
+cmake .. -DOpenCV_DIR=/path/to/opencv/build
+```
+
+**Q: CUDA 相关错误**
+```bash
+# 检查 CUDA 安装
+nvcc --version
+# 确保 CUDA 路径在环境变量中
+export PATH=/usr/local/cuda/bin:$PATH
+export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
+```
+
+### 2. 运行问题
+
+**Q: 检测效果不佳**
+- 调整检测器参数（阈值、NMS等）
+- 尝试不同的检测器类型
+- 检查输入图像质量
+
+**Q: 跟踪不稳定**
+- 调整距离阈值
+- 修改卡尔曼滤波器参数
+- 启用视觉搜索功能
+
+### 3. 性能问题
+
+**Q: 处理速度慢**
+- 使用 GPU 加速
+- 启用异步处理
+- 降低输入分辨率
+- 减少检测频率
+
+## 扩展开发
+
+### 1. 自定义检测器
+
+```cpp
+class CustomDetector : public BaseDetector 
+{
+public:
+    CustomDetector(const cv::Mat& gray) : BaseDetector(gray) {}
+    
+    bool Init(const config_t& config) override {
+        // 初始化代码
+        return true;
+    }
+    
+    void Detect(const cv::Mat& gray) override {
+        // 检测算法实现
+        m_regions.clear();
+        // 添加检测结果到 m_regions
+    }
+};
+```
+
+### 2. 自定义距离函数
+
+```cpp
+track_t CustomDistance(const cv::Rect& rect1, const cv::Rect& rect2) {
+    // 自定义距离计算
+    return distance_value;
+}
+```
+
+### 3. 集成到其他项目
+
+```cmake
+# CMakeLists.txt
+find_package(MTTracking REQUIRED)
+target_link_libraries(your_target MTTracking::mtracking MTTracking::mdetection)
+```
+
+## 应用案例
+
+### 1. 视频监控
+
+- 人员跟踪
+- 异常行为检测
+- 区域入侵检测
+
+### 2. 交通监控
+
+- 车辆计数
+- 速度检测
+- 违章监控
+
+### 3. 体育分析
+
+- 运动员跟踪
+- 轨迹分析
+- 战术分析
+
+### 4. 工业应用
+
+- 产品检测
+- 质量控制
+- 自动化监控
+
+## 参考资源
+
+- [项目主页](https://github.com/Smorodov/Multitarget-tracker)
+- [示例运行说明](https://github.com/Smorodov/Multitarget-tracker/wiki/Run-examples)
+- [俄语 Wiki](https://github.com/Smorodov/Multitarget-tracker/wiki)
+- OpenCV 文档
+- YOLO 官方文档
+
+## 许可证
+
+本项目采用 Apache 2.0 许可证。详见 [LICENSE](LICENSE) 文件。
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request 来改进本项目。
+
+---
+
+*本教程涵盖了 Multitarget-tracker 项目的主要功能和使用方法。如有问题，请参考官方文档或提交 Issue。*
\ No newline at end of file