README.md

# Unicorn
实现目标跟踪的大统一。

## 论文
`Towards Grand Unification of Object Tracking`
- https://arxiv.org/abs/2207.07078
- ECCV 2022

## 模型结构
<!-- 此处一句话简要介绍模型结构 -->
Unicorn 的统一表现在可以使用相同的模型参数通过单个网络同时解决四个跟踪问题（SOT、MOT、VOS、MOTS）。

<div align=center>
    <img src="./doc/unicorn.png"/>
</div>

## 算法原理
Unicorn 由三个部分组成：统一输入与主干、统一嵌入、统一输出头。三个组件分别负责获得强大的视觉表征、建立精确的对应关系和检测不同的跟踪目标。 
- 统一输入和主干\
为了有效地定位多个潜在目标，Unicorn 将整个图像（参考帧和当前帧）而不是局部搜索区域作为输入。在特征提取过程中，参考帧和当前帧通过权重共享主干获得特征金字塔表示（FPN）。为了在计算对应关系时保持重要细节并减少计算负担，本文选择 stride 为 16 的特征图作为之后嵌入模块的输入。参考帧和当前帧的相应特征分别称为 F_ref 和 F_cur。
- 统一嵌入\
目标跟踪的核心任务是在视频中的帧之间建立准确的对应关系。对于 SOT 和 VOS，逐像素对应将用户提供的目标从参考帧（通常是 1^th 帧）传播到 t^th 帧，为最终的框或掩码预测提供强大的先验信息。此外，对于 MOT 和 MOTS，实例级对应有助于将 t^th 帧上检测到的实例与参考帧（通常是 t-1^th 帧）上的现有轨迹相关联。
- 统一输出头\
为了实现目标跟踪的大统一，另一个重要且具有挑战性的问题是为四个跟踪任务设计一个统一头。具体而言，MOT 检测特定类别的目标，SOT 需要检测参考帧中给定的任何目标。为了弥补这一差距，Unicorn 向原始检测器头引入了一个额外的输入（称为目标先验）。无需任何进一步修改，Unicorn 就可以通过这个统一的头轻松检测四项任务所需的各种目标。

<div align=center>
    <img src="./doc/Unicorn_components.png"/>
</div>

## 环境配置
```
mv unicorn_pytoch unicorn # 去框架名后缀
# -v 路径、docker_name和imageID根据实际情况修改
```
### Docker（方法一）
<!-- 此处提供[光源](https://www.sourcefind.cn/#/service-details)拉取docker镜像的地址与使用步骤 -->
```
docker pull image.sourcefind.cn:5000/dcu/admin/base/pytorch:1.10.0-centos7.6-dtk-23.04-py37-latest # 本镜像imageID为：7d3d0bcfe217
docker run -it -v /path/your_code_data/:/path/your_code_data/ -v /opt/hyhal/:/opt/hyhal/:ro --shm-size=16G --privileged=true --device=/dev/kfd --device=/dev/dri/ --group-add video --name docker_name imageID bash

cd /your_code_path/unicorn
pip3 install -U pip && pip3 install -r requirements.txt
pip3 install -v -e .  # or python3 setup.py develop

# Install Deformable Attention
cd unicorn/models/ops
bash make.sh
cd ../../..

# Install mmcv, mmdet
cd external/qdtrack
# 确认一下环境中 mmcv_full=1.6.1+git0d20119.abi0.dtk2304.torch1.10 版本
pip3 install --user mmdet==2.26

# Install bdd100k
cd bdd100k
python3 setup.py develop --user
pip3 uninstall -y scalabel
pip3 install --user git+https://github.com/scalabel/scalabel.git
cd ../../..
```
### Dockerfile（方法二）
<!-- 此处提供dockerfile的使用方法 -->
```
cd /your_code_path/unicorn/docker
docker build --no-cache -t codestral:latest .
docker run -it -v /path/your_code_data/:/path/your_code_data/ -v /opt/hyhal/:/opt/hyhal/:ro --shm-size=16G --privileged=true --device=/dev/kfd --device=/dev/dri/ --group-add video --name docker_name imageID bash

cd /your_code_path/unicorn
pip3 install -U pip && pip3 install -r requirements.txt
pip3 install -v -e .  # or python3 setup.py develop

# Install Deformable Attention
cd unicorn/models/ops
bash make.sh
cd ../../..

# Install mmcv, mmdet
cd external/qdtrack
# 确认一下环境中 mmcv_full=1.6.1+git0d20119.abi0.dtk2304.torch1.10 版本
pip3 install --user mmdet==2.26

# Install bdd100k
cd bdd100k
python3 setup.py develop --user
pip3 uninstall -y scalabel
pip3 install --user git+https://github.com/scalabel/scalabel.git
cd ../../..
```
### Anaconda（方法三）
<!-- 此处提供本地配置、编译的详细步骤，例如： -->

关于本项目DCU显卡所需的特殊深度学习库可从[光合](https://developer.hpccube.com/tool/)开发者社区下载安装。
```
DTK驱动：dtk23.04
python：python3.7
pytorch:1.10.0
```
`Tips：以上DTK驱动、python、pytorch等DCU相关工具版本需要严格一一对应`

其它非深度学习库参照requirements.txt安装：
```
pip3 install -U pip && pip3 install -r requirements.txt
pip3 install -v -e .  # or python3 setup.py develop

# Install Deformable Attention
cd unicorn/models/ops
bash make.sh
cd ../../..

# Install mmcv, mmdet
cd external/qdtrack
pip3 install --user mmcv_full==1.6.1 # 根据具体情况选择对应版本
pip3 install --user mmdet==2.26

# Install bdd100k
cd bdd100k
python3 setup.py develop --user
pip3 uninstall -y scalabel
pip3 install --user git+https://github.com/scalabel/scalabel.git
cd ../../..
```
## 数据集
数据集有COCO, LaSOT, GOT-10K, TrackingNet, DAVIS, Youtube-VOS 2018, MOT17, CrowdHuman, ETHZ等。\
这里针对SOT任务提供了`GOT-10K`用于训练测试
- http://got-10k.aitestunion.com/ 
- 百度网盘链接：https://pan.baidu.com/s/1JYdcw41kDnbdu09itdJwbA 提取码：kwyc
<!-- - 建议从SCNet下载 http://113.200.138.88:18080/aidatasets/project-dependency/nyu-depvh-v2-sync -->

<!-- 数据下载、预处理脚本的使用方法
```
cd /your_code_path/unicorn/
python get_davis.py # 下载数据集DAVIS-2017-trainval-480p
python main_processing.py # 预处理数据集
``` -->

训练数据目录结构如下，用于正常训练的完整数据集请按此目录结构进行制备：
```
├──GOT10k
    ├──train
        ├──sequence_1
        ├──sequence_2
        ├──...
    ├──val
    ├──test
```

## 训练
<!-- 一般情况下，ModelZoo上的项目提供单机训练的启动方法即可，单机多卡、单机单卡至少提供其一训练方法。 -->
<!-- ### 单机多卡
```
python train.py --config configs/default.txt # 注意修改configs文件以及config.py文件
``` -->
针对SOT任务只采用了部分数据集`GOT-10K`，在GPU和DCU上完全保持一致
### 单机单卡
```
cd /your_code_path/unicorn
HIP_VISIBLE_DEVICES=0 python3 launch_uni.py --name unicorn_track_tiny_sot_only_dcu --nproc_per_node 1 --batch 2 --mode multiple
# 这里是在预训练权重unicorn_det_convnext_tiny_800x1280上进行的微调，可根据情况自行选择。
```

## 测试
```
HIP_VISIBLE_DEVICES=0 python3 tools/test.py unicorn_sot unicorn_track_tiny_sot_only_dcu  --dataset got10k_val --threads 8
python3 tools/analysis_results.py --name unicorn_track_tiny_sot_only_dcu/got10k
```

<!-- ## 推理
```
python run.py --encoder vitb --img-path assets/examples --outdir depth_vis
``` -->

<!-- ## result
此处填算法效果测试图（包括输入、输出） -->

## result
暂无
### 精度
GPU：A800，DCU：Z100L
<!-- <div align=center>
    <img src="./doc/metric.png"/>
</div> -->

<!-- 根据测试结果情况填写表格： -->
| GOT10K | AUC | OP50 | OP75 | Pre | Norm Pre |
| :------: | :------: | :------: | :------: |:------: |:------: |
| DCU | 78.97 | 88.64 | 78.13 | 74.11 | 87.86 |
| GPU | 78.86 | 88.72 | 78.30 | 73.49 | 88.03 |

## 应用场景
### 算法类别
<!-- 参考此分类方法（上传时请去除参考图片），与icon图标类别一致，请勿随意命名： -->
<!-- <div align=center>
    <img src="./doc/icon.png"/>
</div> -->

<!-- 超出以上分类的类别命名也可参考此网址中的类别名：https://huggingface.co/ \ -->
`目标跟踪`

### 热点应用行业
<!-- 应用行业的填写需要做大量调研，从而为使用者提供专业、全面的推荐，除特殊算法，通常推荐数量>=3。 -->
`制造,电商,医疗,教育`

<!-- ## 预训练权重 -->
<!-- - 此处填写预训练权重在公司内部的下载地址（预训练权重存放中心为：[SCNet AIModels](http://113.200.138.88:18080/aimodels) ，模型用到的各预训练权重请分别填上具体地址。），过小权重文件可打包到项目里。
- 此处填写公开预训练权重官网下载地址（非必须）。 -->

## 源码仓库及问题反馈
<!-- - 此处填本项目gitlab地址 -->
- https://developer.hpccube.com/codes/modelzoo/unicorn_pytorch

## 参考资料
- https://github.com/MasterBin-IIAU/Unicorn