# ByteTrack 安装配置

> 环境搭建指南

---

## 环境要求

| 项目 | 要求 |
|------|------|
| Python | ≥ 3.8 |
| GPU | NVIDIA (推荐 V100) |
| CUDA | ≥ 11.1 |
| PyTorch | ≥ 1.7 |

---

## 1. 安装 ByteTrack

```bash
# 克隆代码
git clone https://github.com/ifzhang/ByteTrack.git
cd ByteTrack

# 安装依赖
pip3 install -r requirements.txt

# 安装为开发模式
python3 setup.py develop
```

## 2. 安装 COCO 评估工具

```bash
pip3 install cython
pip3 install 'git+https://github.com/cocodataset/cocoapi.git#subdirectory=PythonAPI'
```

## 3. 安装 cython_bbox

```bash
pip3 install cython_bbox
```

---

## 4. Docker 安装（推荐）

```bash
# 构建镜像
docker build -t bytetrack:latest .

# 启动容器
docker run --gpus all -it --rm \
  -v $PWD/pretrained:/workspace/ByteTrack/pretrained \
  -v $PWD/datasets:/workspace/ByteTrack/datasets \
  bytetrack:latest
```

---

## 5. 数据集准备

### 目录结构

```
datasets/
├── mot/
│   ├── train/
│   └── test/
├── crowdhuman/
│   ├── Crowdhuman_train/
│   ├── Crowdhuman_val/
│   ├── annotation_train.odgt
│   └── annotation_val.odgt
├── MOT20/
│   ├── train/
│   └── test/
├── Cityscapes/
│   ├── images/
│   └── labels_with_ids/
└── ETHZ/
    └── ...
```

### 常用数据集

| 数据集 | 用途 | 下载 |
|--------|------|------|
| MOT17 | 训练/测试 | [MOTChallenge](https://motchallenge.net/) |
| MOT20 | 拥挤场景 | [MOTChallenge](https://motchallenge.net/) |
| CrowdHuman | 预训练 | [官网](https://www.crowdhuman.org/) |

### 转换为 COCO 格式

```bash
# 转换 MOT17
python3 tools/convert_mot17_to_coco.py

# 转换 MOT20
python3 tools/convert_mot20_to_coco.py

# 转换 CrowdHuman
python3 tools/convert_crowdhuman_to_coco.py
```

---

## 6. 预训练模型下载

```bash
# 创建目录
mkdir -p pretrained

# 下载模型（根据需要）
# ByteTrack_ablation (用于消融实验)
# ByteTrack_x_mot17 (大模型)
# ByteTrack_l_mot17 (中模型)
# ByteTrack_m_mot17
# ByteTrack_s_mot17 (小模型)
```

模型下载：
- [Google Drive](https://drive.google.com/)
- [百度网盘](https://pan.baidu.com/) (提取码: eeo8)

---

## 7. YOLOX 预训练模型

从 [YOLOX Model Zoo](https://github.com/Megvii-BaseDetection/YOLOX/tree/0.1.0) 下载：

```bash
# X 模型 (精度最高)
wget https://github.com/Megvii-BaseDetection/YOLOX/releases/download/0.1.0/yolox_x.pth

# 移动到预训练目录
mv yolox_x.pth pretrained/
```

---

## 8. 常用命令

### 测试追踪

```bash
# 基础追踪
python3 tools/track.py \
  -f exps/example/mot/yolox_x_ablation.py \
  -c pretrained/bytetrack_ablation.pth.tar \
  -b 1 -d 1 --fp16 --fuse

# 使用自己的检测结果
python3 tools/demo_track.py video \
  -f exps/example/mot/yolox_x_mix_det.py \
  -c pretrained/bytetrack_x_mot17.pth.tar \
  --fp16 --fuse --save_result
```

### 模型训练

```bash
# 消融实验
python3 tools/train.py \
  -f exps/example/mot/yolox_x_ablation.py \
  -d 8 -b 48 --fp16 -o \
  -c pretrained/yolox_x.pth

# MOT17 完整训练
python3 tools/train.py \
  -f exps/example/mot/yolox_x_mix_det.py \
  -d 8 -b 48 --fp16 -o \
  -c pretrained/yolox_x.pth
```

---

## 9. 部署支持

| 部署方式 | 说明 |
|----------|------|
| ONNX | Python ONNXRuntime 部署 |
| TensorRT | Python / C++ 部署 |
| ncnn | C++ 部署 |
| DeepStream | NVIDIA 边缘设备 |

详见 `deploy/` 目录。

---

## 10. 常见问题

### Q: 显存不足？

```bash
# 减小 batch size
-b 24  # 原 48
```

### Q: MOT20 边界溢出？

在 `yolox/data/data_augment.py` 中添加裁剪操作。

### Q: 如何使用自己的检测器？

```python
from yolox.tracker.byte_tracker import BYTETracker

tracker = BYTETracker(args)

for image in images:
    dets = your_detector(image)  # (N, 5) [x1,y1,x2,y2,score]
    online_targets = tracker.update(dets, info_imgs, img_size)
```

---

> 参考：[ByteTrack GitHub](https://github.com/FoundationVision/ByteTrack)