SiameseFC PyTorch实现

简介

本项目是论文《用于目标跟踪的全卷积孪生网络》中提出的目标跟踪器的PyTorch实现，该论文发表于arXiv，相关项目页面请见这里。原始版本使用Matlab结合MatConvNet框架编写，代码可在这里找到（包含训练和跟踪部分），而本Python版本则基于TensorFlow移植版（仅跟踪部分）改编而来，该TensorFlow版本的代码可参见这里。

项目结构

该项目主要分为三个部分：训练、跟踪以及可视化应用。

训练

本工作的核心在于训练部分，即通过训练孪生网络来学习补丁之间的相似性度量，这在论文中有详细描述。

训练结果

不同参数和实现之间唯一可比较的训练指标是平均中心误差（或称中心位移）。作者在其论文《学习前馈式一次性学习者》的附录B中提供了这一指标，其中验证集上的平均中心误差为7.40像素，训练集上则为6.26像素。

我们的基准结果如下：

我们与作者的结果相比大约落后4像素，我们认为主要原因包括：

• 相关性图缺少双三次上采样层，导致相关性图的分辨率仅为原图的四分之一（由于网络的步幅所致）。
• 损失函数中缺乏类别归一化处理，无法有效应对相关性图标签中负样本与正样本数量极不平衡的问题（负样本远多于正样本）。

另一方面，我们的模型过拟合风险更低，因为我们每次训练时都会随机采样不同的图像对，而作者则是在训练开始前就固定了所有图像对，并在每次训练中重复使用相同的图像对。

本训练得到的模型以BaselinePretrained.pth.tar的形式提供。

如何运行 - 训练

1. 先决条件： 本项目使用Python 3.6开发，并在Ubuntu 16.04和17.04系统上进行了测试。硬件方面，我们在GTX 1080 Ti和GTX 950M显卡上进行了测试。此外，还需要安装PyTorch 4.1。其余依赖库可通过以下命令安装：

# 经测试使用的scipy版本为1.1.0
pip install scipy
# 经测试使用的scikit-learn版本为0.20.0
pip install scikit-learn 
# 经测试使用的tqdm版本为4.26.0
pip install tqdm
# 经测试使用的tensorboardx版本为1.4
pip install tensorboardx
# 经测试使用的imageio版本为2.4.1
pip install imageio
# 若后续需要运行TensorBoard文件，则需安装TensorFlow。
pip install tensorflow

# 若要运行可视化应用，则需要PyQt5和pyqtgraph。
# 经测试使用的pyqt版本为5.6.0
pip install pyqt5
# 经测试使用的pyqtgraph版本为0.10.0
pip install pyqtgraph

若使用Anaconda，可通过conda虚拟环境安装依赖：

# 使用conda 4.5.11版本
conda env create -f environment.yaml
conda activate siamfc

# PyQtGraph未包含在conda环境中，需通过pip单独安装。
pip install pyqtgraph

(可选： 如需加速数据加载，请参考本节）

2. 从http://bvisionweb1.cs.unc.edu/ILSVRC2017/download-videos-1p39.php下载ImageNet VID数据集，并将其解压到您选择的文件夹中（注意：数据读取是在运行时完成的，因此建议将数据集解压到SSD分区以提高效率）。您可以删除数据集中的“test”部分，因为它没有标注信息。

3. 每次新的训练都需要创建一个实验文件夹（该文件夹用于存储训练参数和输出结果）：

# 进入experiments文件夹
cd training/experiments
# 创建名为<EXP_NAME>的实验文件夹
mkdir <EXP_NAME>
# 将默认实验文件夹中的参数文件复制到新文件夹中
cp default/parameters.json <EXP_NAME>/

4. 根据需求编辑parameters.json文件。每个参数的说明可在此处找到。

5. 运行train.py脚本：

# <EXP_NAME>是实验文件夹的名称，而非路径。
python train.py --data_dir <FULL_PATH_TO_DATASET_ROOT> --exp_name <EXP_NAME>

• 如果需要分析执行时间，可以添加--time参数，执行时间将被记录在train.log文件中。

6. 训练完成后，将生成以下输出文件：

• train.log：训练日志，其中大部分内容也会显示在终端中。
• metadata.train和metadata.val：训练集和验证集的元数据，这些文件会在程序启动时自动生成。只需将这些文件复制到任何新的实验文件夹中，即可节省约15分钟的设置时间（对我而言如此）。
• metrics_val_last_weights.json：包含最近一次验证epoch指标的JSON文件，便于阅读。
• metrics_val_best_weights.json：包含AUC得分最高那次验证epoch指标的JSON文件，同样便于阅读。
• best.pth.tar和last.pth.tar：包含模型状态字典及其他相关信息的文件，可用于后续的训练、验证或推理。其中last表示当前epoch的模型权重，而best则表示AUC得分最高的模型权重。
• tensorboard：包含总结训练过程的TensorBoard文件夹，分为val和train两个子文件夹，以便在同一张图中绘制曲线。要启动TensorBoard，可输入以下命令：

为此，您需要安装 TensorFlow 的 TensorBoard。

tensorboard --logdir <实验文件夹路径>/tensorboard

<center>
    <figure>
        <img src="https://oss.gittoolsai.com/images/rafellerc_Pytorch-SiamFC_readme_ce4f7cc5a5a8.png" height="60%" width="60%">
        <figcaption>存储的三个指标分别是：标签相关图（由参数定义）与实际相关图之间二分类误差的 ROC 曲线的平均<b>AUC</b>；<b>中心误差</b>,即相关图峰值位置与实际中心之间的像素距离；以及用于优化模型的平均<b>二元交叉熵损失</b>。
        </figcaption>
    </figure>
</center>

**注**: 我们的损失函数定义与作者略有不同，但应具有等价性。请参阅[损失函数定义](#loss-definition)。
<center>
    <figure>
        <img src="https://oss.gittoolsai.com/images/rafellerc_Pytorch-SiamFC_readme_9ff3f0cb1b69.png" height="60%" width="60%">
        <figcaption>我们还会为每个 epoch 存储参考/搜索/相关图三联图，以便调试和探索。这些图像会在每个验证 epoch 收集，因此第一张图对应的是第一个训练 epoch 之前的验证结果。它们可以帮助我们观察网络在每个训练 epoch 后对结果估计的变化过程。</figcaption>
    </figure>
</center>

**注:** 若要设置每个 epoch 存储的三联图数量，请使用 `--summary_samples <三联图数量>` 标志：

python train.py -s 10 -d <数据集根目录完整路径> -e <实验名称>

不过，这些图像可能会占用大量空间，尤其是在 epoch 数量较多时。

### 其他用途

#### 继续训练/加载预训练权重

您可以通过调用训练脚本并添加 `--restore_file <模型名称>` 标志来继续训练网络或加载预训练权重，其中 `<模型名称>` 是文件名，**不包含** *.pth.tar* 扩展名（例如 *best*，对应 *best.pth.tar*）。程序随后会在实验文件夹中查找名为 `NAME_OF_MODEL.pth.tar` 的文件，并将其状态作为初始状态加载，其余训练流程将正常进行。  

python train.py -r <模型名称> -d <数据集根目录完整路径> -e <实验名称>

#### 仅评估

完成训练并获得包含网络权重的 *.pth.tar* 文件后，您可以通过结合 `--mode eval` 和 `--restore_file <模型名称>` 来对该模型在数据集中进行评估：

python train.py -m eval -r <模型名称> -d <数据集根目录完整路径> -e <实验名称>

评估结果将被存储在 `metrics_test_best.json` 中。


### 跟踪

[开发中]

## 数据集

用于跟踪器评估的数据集是由以下数据集中的序列汇编而成：
[TempleColor](http://www.dabi.temple.edu/~hbling/data/TColor-128/TColor-128.html)、
[VOT2013、VOT2014 和 VOT2016](http://www.votchallenge.net/challenges.html)。Temple Color 和 VOT2013 数据集采用直立矩形边界框标注（4 个数字），而 VOT2014 和 VOT2016 则采用旋转边界框标注（8 个数字）。标注顺序大致如下：

* TC：左下角(x , y)，宽度，高度
* VOT2013：左下角(x, y)，宽度，高度
* VOT2014：左上角(x, y)，左下角(x, y)，右下角(x, y)，右上角(x, y)
* VOT2016：左下角(x, y)，右下角(x, y)，右上角(x, y)，左上角(x, y)

**注**: VOT2014 和 VOT2016 中的标注也可能只是按任意顺序列出的一系列点，用来定义边界框的轮廓，但这些点必须符合矩形的相邻关系。我并未检查所有真实标签以确保所有标注都按照此处描述的特定顺序排列。如果出现严重问题，您可能需要再次确认这一点。

用于训练的数据集是 2015 年 ImageNet VID，其中包含目标视频，每帧都用边界框标记了目标。

## 可视化应用

<center>
    <figure>
        <img src="https://oss.gittoolsai.com/images/rafellerc_Pytorch-SiamFC_readme_8ad42491239e.gif" height="60%" width="80%">
        <figcaption>
        </figcaption>
    </figure>
</center>

我还开发了一个可视化应用，用于实时查看网络的输出。其目的是观察该网络作为**相似度函数**的优点和局限性，**而非**评估或可视化整个跟踪器。

vis_app 会针对给定序列中的每一帧，将参考嵌入与**整张帧**进行比较，而不是像跟踪器那样只在受限区域内进行比较。基本流程如下：

* 获取目标首次出现的第一帧。
* 计算一个缩放因子，使得参考图像（边界框 + 上下文区域）的尺寸为 127 像素，与训练时一致。后续所有帧也将按此比例缩放。
* 将参考图像输入嵌入分支，得到参考嵌入。**不更新**参考嵌入。
* 对于序列中的每一帧，我们在图像边缘填充零，以使得分图的输出尺寸与当前帧尺寸相同。
* 将参考嵌入与当前帧的嵌入（可能非常大）进行卷积，得到完整的得分图。然后对得分图进行上采样，以抵消步幅的影响，并将其叠加到当前帧上。得分图的强度通过 [inferno 颜色映射](https://matplotlib.org/users/colormaps.html) 转换为颜色显示。
* 我们还在每一帧中标出得分图的峰值位置，作为网络对当前目标位置的预测。同时绘制中心误差曲线。

该应用采用两个线程实现：负责 GUI 的**显示线程**和执行所有计算的**生产者线程**。

<center>
    <figure>
        <img src="https://oss.gittoolsai.com/images/rafellerc_Pytorch-SiamFC_readme_8eab80966d9c.png" height="60%" width="100%">
        <figcaption> 窗口顶部显示当前的显示帧率；目标是否可见的状态（如果目标在帧内则为真）；以及存储生产者线程生成帧的缓冲区中当前的帧数。
        </figcaption>
    </figure>
</center>

<center>
    <figure>
        <img src="https://oss.gittoolsai.com/images/rafellerc_Pytorch-SiamFC_readme_a66e42b7ecf9.png" height="60%" width="80%">
        <figcaption> 图片底部显示当前帧的完整路径；参考图像显示网络当前使用的参考图像；真实标签显示当前帧及其叠加的边界框；得分图显示网络在当前帧上计算出的得分图，各部分的透明度可通过<b>alpha 参数</b>控制。得分图的峰值处会标记一个绿色十字。
        </figcaption>
    </figure>
</center>

<center>
    <figure>
        <img src="https://oss.gittoolsai.com/images/rafellerc_Pytorch-SiamFC_readme_9a008f69ede4.png" height="60%" width="100%">
        <figcaption> 最后是每帧的中心误差曲线，表示得分图峰值与真实标签边界框中心之间的距离。我们还绘制了一条蓝色水平线，位于 63 像素处（即参考图像边长的一半），作为判断目标位置是否超出边界框的阈值。
        </figcaption>
    </figure>
</center>

### 如何运行——可视化应用

假设 ImageNet VID 数据集的路径为 \<ILSVRC>, 并且已安装 PyQt5 和 pyqtgraph 包，则可运行以下命令：

-d 指定数据集路径，-n 指定模型文件路径。

python vis_app.py -d -n BaselinePretrained.pth.tar -t train -s 10

此外，数据集按照 `train` 和 `val` 分别组织序列，并按顺序编号。因此，要获取第 150 个训练序列，需使用参数 `-t train -s 149`（索引从 0 开始）。`train` 序列的编号范围为 0 到 3861，`val` 序列的编号范围为 0 到 554。

您还可以设置 alpha 值，取值范围为 0.0 到 1.0，用于控制得分图覆盖帧的比例。若希望仅显示得分图而不显示背景帧，可使用参数 `-a 1`。如需查看所有可用参数，可运行 `python vis_app.py -h`。


## 参数

无论是跟踪脚本还是训练脚本，其行为都由用户定义的参数决定。这些参数存储在 .json 文件中，用户可以直接修改。对于跟踪和训练任务而言，一组特定的参数即构成一次“实验”，因此它们会被放置在训练和跟踪目录下的 `experiments` 文件夹中。若要为新实验定义参数，只需复制默认的实验文件夹及其 .json 文件，并根据需要重命名，然后将其放入 `training` 或 `tracking` 目录下的 `experiments` 文件夹中即可。以下简要介绍一些基本参数：

### 训练参数：

* `model`: 用作孪生网络分支的嵌入网络，模型定义在 [models.py](training/models.py) 中。可用的模型包括 *BaselineEmbeddingNet*、*VGG11EmbeddingNet_5c* 和 *VGG16EmbeddingNet_8c*。
* `parameter_freeze`: 嵌入网络中需要冻结的层列表（即这些层的参数不会被更新）。编号对应于 [models.py](training/models.py) 中定义网络的 `nn.Sequential` 类。例如，对于 `BaselineEmbeddingNet`，[0, 1, 4, 5] 表示冻结前两层卷积层（0 和 4）以及前两层批归一化层（1 和 5）。
* `batch_size`: 以参考/搜索区域对为单位的批量大小。论文作者建议使用 8 对的批量。
* `num_epochs`: 总训练轮数。在训练开始前以及每一轮训练结束后都会进行一次验证。
* `train_epoch_size`: 每个训练轮次的迭代次数。如果该值大于数据集中帧的总数，则轮次大小将默认设置为整个数据集，并向用户发出警告。
* `eval_epoch_size`: 每个验证轮次的迭代次数。如果该值大于数据集中帧的总数，则轮次大小将默认设置为整个数据集，并向用户发出警告。
* `save_summary_steps`: 在评估指标之前经过的批次数量。若设置为 0，则在计算损失后会对所有批次的指标进行评估；若设置为 10，则每 10 个批次评估一次。
* `optim`: 训练过程中使用的优化器。可选的有随机梯度下降法（SGD）和自适应矩估计法（Adam）。
* `optim_kwargs`: 与各优化器初始化相关的关键字参数。它本身是一个字典，应遵循 PyTorch 的文档说明。例如，若优化器为 `SGD`，则可以指定为 {`lr`: 1e-3, `momentum`:0.9}，表示学习率为 0.001，动量为 0.9。每种优化器都有其可用的关键字，更多信息请参阅：https://pytorch.org/docs/stable/optim.html。
* `max_frame_sep`: 最大帧间间隔，即数据集中每对帧之间允许的最大距离。默认值为 50。
* `reference_sz`: 参考区域的尺寸，单位为像素。默认值为 127。
* `search_sz`: 搜索区域的尺寸，单位为像素。默认值为 255。
* `final_sz`: 将成对的图像输入模型后得到的最终输出尺寸。
* `upscale`: 一个布尔值，用于指示网络是否应包含双线性上采样层。注意：这可能会显著减慢训练速度。
* `pos_thr`: 标签中的正样本阈值距离，即被视为正样本像素的距离上限。
* `neg_thr`: 标签中的负样本阈值距离，即被视为负样本像素的距离下限。任何距离介于正负阈值之间的像素都被视为中性像素，既不计入正样本也不计入负样本。
* `context_margin`: 参考区域的上下文边距。


### 跟踪参数：

[开发中]

### 加速数据加载

[即将推出]

### 损失函数定义

[即将推出]

致谢：
本项目最初由 Parrot Drones SAS 开发并开源。

Pytorch-SiamFC 快速上手指南

Pytorch-SiamFC 是经典目标跟踪算法 SiameseFC 的 PyTorch 实现版本。该项目主要用于训练孪生网络以学习图像块之间的相似度度量，并提供了可视化工具来观察网络输出。

1. 环境准备

本项目基于 Python 3.6 开发，已在 Ubuntu 16.04/17.04 系统上测试通过。推荐使用 NVIDIA GPU（如 GTX 1080 Ti 或 GTX 950M）进行加速。

核心依赖

• PyTorch: 版本需为 0.4.1 (注意：原文标注为 4.1，但结合上下文及历史版本，实际指 0.4.1)
• 其他库: scipy, scikit-learn, tqdm, tensorboardx, imageio
• 可选库 (用于可视化): tensorflow (用于 TensorBoard), PyQt5, pyqtgraph

国内加速建议

在中国大陆地区，建议使用清华源或阿里源加速 pip 和 conda 包的下载。

2. 安装步骤

方案 A：使用 Conda 虚拟环境（推荐）

如果你已安装 Anaconda 或 Miniconda，这是最简便的方式。

1. 创建并激活环境：

   conda env create -f environment.yaml
   conda activate siamfc
   

2. 安装缺失的可视化依赖（environment.yaml 中未包含）：

   pip install pyqtgraph -i https://pypi.tuna.tsinghua.edu.cn/simple
   

方案 B：手动安装依赖

如果不使用 Conda，请确保 Python 版本为 3.6，然后执行以下命令安装依赖（已配置国内镜像源）：

# 安装基础科学计算库
pip install scipy scikit-learn tqdm tensorboardx imageio -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装 PyTorch (请根据具体 CUDA 版本前往 pytorch.org 获取对应命令，此处为通用示例)
# 注意：原项目依赖较旧的 PyTorch 0.4.1，若遇兼容性问题可能需要调整版本
pip install torch==0.4.1 torchvision==0.2.1 -i https://download.pytorch.org/whl/cu90

# 安装 TensorFlow (仅用于运行 TensorBoard)
pip install tensorflow==1.12.0 -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装可视化工具依赖
pip install pyqt5 pyqtgraph -i https://pypi.tuna.tsinghua.edu.cn/simple

数据集准备

训练需要使用 ImageNet VID 2015 数据集。

1. 下载地址：ILSVRC2017 Video Detection
2. 解压到任意目录（建议解压至 SSD 固态硬盘以提升读取速度）。
3. 可删除数据集中的 test 部分，因为该部分不包含标注信息。

3. 基本使用

以下流程演示如何从头开始训练一个模型。

第一步：创建实验文件夹

在 training/experiments 目录下创建一个新的实验文件夹，并复制默认参数文件。

cd training/experiments
mkdir <EXP_NAME>
cp default/parameters.json <EXP_NAME>/

请将 <EXP_NAME> 替换为你自定义的实验名称（例如 my_first_trial）。

第二步：配置参数

编辑 <EXP_NAME>/parameters.json 文件，根据你的需求修改训练参数（如学习率、批次大小等）。具体参数说明可参考项目文档中的 "Training Parameters" 部分。同时，请在文件中或命令行指定数据集路径。

第三步：启动训练

运行 train.py 脚本开始训练。

# 语法：python train.py --data_dir <数据集根目录绝对路径> --exp_name <实验文件夹名称>
python train.py --data_dir /home/user/datasets/ILSVRC2015 --exp_name my_first_trial

训练输出说明：

• train.log: 终端日志的文件备份。
• best.pth.tar / last.pth.tar: 保存的最佳模型权重和最新 epoch 权重。
• tensorboard/: 包含训练曲线数据。可通过以下命令查看可视化图表：

  tensorboard --logdir training/experiments/<EXP_NAME>/tensorboard
  

进阶用法

加载预训练权重继续训练

如果你想基于已有的模型（如 best.pth.tar）继续训练：

python train.py --restore_file best --data_dir <FULL_PATH_TO_DATASET_ROOT> --exp_name <EXP_NAME>

注意：--restore_file 后跟文件名不含 .pth.tar 后缀。

仅进行评估

如果已有训练好的权重文件，只想在数据集上进行评估：

python train.py --mode eval --restore_file best --data_dir <FULL_PATH_TO_DATASET_ROOT> --exp_name <EXP_NAME>

评估结果将保存在 metrics_test_best.json 中。

可视化应用

项目包含一个实时可视化工具，用于观察网络作为相似度函数的输出（非完整跟踪器效果）。需确保已安装 PyQt5 和 pyqtgraph，运行相应的可视化脚本（具体脚本名请参考项目 visualization-application 章节，通常为 vis_app.py 或类似入口）。