CoTracker3：通过伪标签真实视频实现更简单、更优秀的点跟踪

Meta AI Research, GenAI；牛津大学 VGG

Nikita Karaev，Iurii Makarov，Jianyuan Wang，Ignacio Rocco，Benjamin Graham，Natalia Neverova，Andrea Vedaldi，Christian Rupprecht

项目页面 | 论文 #1 | 论文 #2 | X 帖子 | BibTeX

CoTracker 是一种基于 Transformer 的快速模型，能够跟踪视频中的任意点。它为点跟踪带来了光流的一些优势。

CoTracker 可以跟踪：

• 视频中的 任意像素
• 一组 准密集 的像素
• 点可以手动选择，也可以在任意视频帧中按网格采样

您可以通过我们的 Colab 示例 或 Hugging Face Space 🤗 自行尝试这些跟踪模式。

更新：

• [2025年1月21日] 📦 CoTracker3 使用的 Kubric 数据集现已可用！该数据集包含 6,000 个高分辨率序列（512×512px，120 帧），具有轻微的相机运动，由 Kubric 引擎渲染。请在 Hugging Face 数据集 上查看。

• [2024年10月15日] 📣 我们发布了 CoTracker3！采用轻量级架构的最先进点跟踪技术，训练数据仅为先前最佳模型的 1/1000。基准模型和伪标签流水线的代码以及模型检查点均已发布在仓库中。更多详情请参阅我们的 论文。

• [2024年9月25日] CoTracker2.1 现已发布！该模型在 TAP-Vid 基准测试中表现更好，并沿用了原始 CoTracker 的架构。快来试试吧！

• [2024年6月14日] 我们发布了用于从任意图像序列中基于点跟踪恢复相机位姿和 3D 结构的模型 VGGSfM 的代码！VGGSfM 是首个完全可微分的 SfM 框架，实现了规模化应用，并在标准基准测试中优于传统 SfM 方法。

• [2023年12月27日] CoTracker2 现已发布！现在它可以同时跟踪更多（最多 265*265！）点，并且实现了更简洁、更节省内存的实现方式。它还支持在线处理。更多细节请参阅 更新后的论文。旧版本仍可在 此处 获取。

• [2023年9月5日] 您现在可以在本地运行我们的 Gradio 示例 app.py。

快速入门

使用 CoTracker 最简单的方式是从 torch.hub 加载预训练模型：

离线模式：

pip install imageio[ffmpeg], 然后：

import torch
# 下载视频
url = 'https://github.com/facebookresearch/co-tracker/raw/refs/heads/main/assets/apple.mp4'

import imageio.v3 as iio
frames = iio.imread(url, plugin="FFMPEG")  # plugin="pyav"

device = 'cuda'
grid_size = 10
video = torch.tensor(frames).permute(0, 3, 1, 2)[None].float().to(device)  # B T C H W

# 运行离线 CoTracker：
cotracker = torch.hub.load("facebookresearch/co-tracker", "cotracker3_offline").to(device)
pred_tracks, pred_visibility = cotracker(video, grid_size=grid_size) # B T N 2,  B T N 1

在线模式：

cotracker = torch.hub.load("facebookresearch/co-tracker", "cotracker3_online").to(device)

# 运行在线 CoTracker，同一模型但使用不同的 API：
# 初始化在线处理
cotracker(video_chunk=video, is_first_step=True, grid_size=grid_size)  

# 处理视频
for ind in range(0, video.shape[1] - cotracker.step, cotracker.step):
    pred_tracks, pred_visibility = cotracker(
        video_chunk=video[:, ind : ind + cotracker.step * 2]
    )  # B T N 2,  B T N 1

在线处理更加节省内存，适合处理较长的视频。不过，在上述示例中，视频长度是已知的！请参阅 在线演示 以了解如何从长度未知的在线流中进行跟踪。

可视化预测轨迹：

在 安装 CoTracker 后，您可以使用以下代码可视化轨迹：

from cotracker.utils.visualizer import Visualizer

vis = Visualizer(save_dir="./saved_videos", pad_value=120, linewidth=3)
vis.visualize(video, pred_tracks, pred_visibility)

我们还提供了其他与 CoTracker 交互的方式：

1. 交互式 Gradio 示例：
   • 示例可在 facebook/cotracker Hugging Face Space 🤗 上找到。
   • 您也可以在本地运行 Gradio 示例，方法是安装所需包后执行 python -m gradio_demo.app：pip install -r gradio_demo/requirements.txt。
2. Jupyter 笔记本：
   • 您可以在 Google Colab 中运行笔记本。
   • 或者探索位于 notebooks/demo.ipynb 的笔记本。
3. 您可以将 CoTracker 本地 安装后：

   • 运行一个 离线 示例，从视频的第一帧上按网格采样 10 × 10 个点（结果将保存到 ./saved_videos/demo.mp4）：

     python demo.py --grid_size 10
     

   • 或者运行一个 在线 示例：

     python online_demo.py
     

强烈建议使用 GPU 来本地运行 CoTracker。

安装说明

您可以通过上述方式使用 PyTorch Hub 中的预训练模型，也可以从本 GitHub 仓库安装 CoTracker。如果您需要运行我们的本地演示或对 CoTracker 进行评估/训练，这是最佳方式。

请确保您的系统上已安装 PyTorch 和 TorchVision。请按照 此处 的说明进行安装。我们强烈建议同时安装支持 CUDA 的 PyTorch 和 TorchVision，尽管对于小型任务，CoTracker 也可以在 CPU 上运行。

安装开发版本

git clone https://github.com/facebookresearch/co-tracker
cd co-tracker
pip install -e .
pip install matplotlib flow_vis tqdm tensorboard

您可以手动从以下链接下载所有 CoTracker3 检查点（基准模型和缩放模型，以及单窗口和滑动窗口架构），并将其放置在 checkpoints 文件夹中，如下所示：

mkdir -p checkpoints
cd checkpoints
# 下载在线（多窗口）模型
wget https://huggingface.co/facebook/cotracker3/resolve/main/scaled_online.pth
# 下载离线（单窗口）模型
wget https://huggingface.co/facebook/cotracker3/resolve/main/scaled_offline.pth
cd ..

您还可以下载仅在 Kubric 数据集上训练的 CoTracker3 检查点：

# 下载在线（滑动窗口）模型
wget https://huggingface.co/facebook/cotracker3/resolve/main/baseline_online.pth
# 下载离线（单窗口）模型
wget https://huggingface.co/facebook/cotracker3/resolve/main/baseline_offline.pth

有关旧版检查点，请参阅 此部分。

评估

为复现论文中展示的结果，请下载以下数据集：

• TAP-Vid
• Dynamic Replica

并安装必要的依赖项：

pip install hydra-core==1.1.0 mediapy

然后，执行以下命令以在 TAP-Vid DAVIS 数据集上评估在线模型：

python ./cotracker/evaluation/evaluate.py --config-name eval_tapvid_davis_first exp_dir=./eval_outputs dataset_root=your/tapvid/path

对于离线模型：

python ./cotracker/evaluation/evaluate.py --config-name eval_tapvid_davis_first exp_dir=./eval_outputs dataset_root=/fsx-repligen/shared/datasets/tapvid offline_model=True window_len=60 checkpoint=./checkpoints/scaled_offline.pth

为了加快推理速度，我们会一次性对所有目标点进行联合评估。采用这种评估方式得到的结果与论文中展示的数值相近。如果您希望完全复现论文中的精确数值，请添加 single_point=True 标志。

以下是您应能使用发布的检查点和当前代码库版本复现的数值：

	Kinetics, $\delta_\text{avg}^\text{vis}$	DAVIS, $\delta_\text{avg}^\text{vis}$	RoboTAP, $\delta_\text{avg}^\text{vis}$	RGB-S, $\delta_\text{avg}^\text{vis}$
CoTracker2, 27.12.23	61.8	74.6	69.6	73.4
CoTracker2.1, 25.09.24	63	76.1	70.6	79.6
CoTracker3 离线版, 15.10.24	67.8	76.9	78.0	85.0
CoTracker3 在线版, 15.10.24	68.3	76.7	78.8	82.7

训练

基准

要按照我们论文中的描述训练 CoTracker，您首先需要为 Google Kubric MOVI-f 数据集生成标注。 标注生成说明可在 此处 找到。关于数据集生成的讨论也可见于 此议题。

完成标注后，您需要确保已按照评估设置步骤操作，并安装训练所需的依赖项：

pip install pip==24.0
pip install pytorch_lightning==1.6.0 tensorboard opencv-python

现在您可以开始在 Kubric 数据集上进行训练了。我们的模型是在 32 张 GPU 上（4 个节点，每个节点 8 张 GPU）训练了 50000 次迭代。在运行此命令之前，请相应地修改 dataset_root 和 ckpt_path。如果要在 4 个节点上训练，请添加 --num_nodes 4。

以下是启动 Kubric 数据集上在线模型训练的示例：

 python train_on_kubric.py --batch_size 1 --num_steps 50000 \
 --ckpt_path ./ --model_name cotracker_three --save_freq 200 --sequence_len 64 \
  --eval_datasets tapvid_davis_first tapvid_stacking --traj_per_sample 384 \
  --sliding_window_len 16 --train_datasets kubric --save_every_n_epoch 5 \
  --evaluate_every_n_epoch 5 --model_stride 4 --dataset_root ${path_to_your_dataset} \
   --num_nodes 4 --num_virtual_tracks 64 --mixed_precision --corr_radius 3 \ 
   --wdecay 0.0005 --linear_layer_for_vis_conf --validate_at_start --add_huber_loss

在 Kubric 数据集上训练离线模型：

python train_on_kubric.py --batch_size 1 --num_steps 50000 \
 --ckpt_path ./ --model_name cotracker_three --save_freq 200 --sequence_len 60 \
 --eval_datasets tapvid_davis_first tapvid_stacking --traj_per_sample 512 \
 --sliding_window_len 60 --train_datasets kubric --save_every_n_epoch 5 \
 --evaluate_every_n_epoch 5 --model_stride 4 --dataset_root ${path_to_your_dataset} \
 --num_nodes 4 --num_virtual_tracks 64 --mixed_precision --offline_model \
 --random_frame_rate --query_sampling_method random --corr_radius 3 \
 --wdecay 0.0005 --random_seq_len --linear_layer_for_vis_conf \
 --validate_at_start --add_huber_loss

使用伪标签进行微调

为了启动基于伪标签的训练，你需要收集自己的真实视频数据集。在 cotracker/datasets/real_dataset.py 中提供了一个示例类，其中包含我们用于训练的关键字过滤功能。你的类应该实现加载视频并将视频存储为 CoTrackerData 类的一个字段，而伪标签将在 train_on_real_data.py 中生成。

你应该有一个已经使用 Kubric 训练好的模型，以便用伪标签进行微调。以下是启动在线模型微调的示例命令：

python ./train_on_real_data.py --batch_size 1 --num_steps 15000 \
 --ckpt_path ./ --model_name cotracker_three --save_freq 200 --sequence_len 64 \
 --eval_datasets tapvid_stacking tapvid_davis_first --traj_per_sample 384 \
 --save_every_n_epoch 15 --evaluate_every_n_epoch 15 --model_stride 4 \
 --dataset_root ${path_to_your_dataset} --num_nodes 4 --real_data_splits 0 \
 --num_virtual_tracks 64 --mixed_precision --random_frame_rate \
 --restore_ckpt ./checkpoints/baseline_online.pth \
 --lr 0.00005 --real_data_filter_sift --validate_at_start \
 --sliding_window_len 16 --limit_samples 15000

对于离线模型：

python train_on_real_data.py --batch_size 1 --num_steps 15000 \
 --ckpt_path ./ --model_name cotracker_three --save_freq 200 --sequence_len 80 \
 --eval_datasets tapvid_stacking tapvid_davis_first --traj_per_sample 384 --save_every_n_epoch 15 \
 --evaluate_every_n_epoch 15 --model_stride 4 --dataset_root ${path_to_your_dataset} \
  --num_nodes 4 --real_data_splits 0 --num_virtual_tracks 64 --mixed_precision \
  --random_frame_rate --restore_ckpt ./checkpoints/baseline_offline.pth --lr 0.00005 \
  --real_data_filter_sift --validate_at_start --offline_model --limit_samples 15000

开发

构建文档

要构建 CoTracker 文档，首先安装依赖项：

pip install sphinx
pip install sphinxcontrib-bibtex

然后你可以使用以下命令在 docs/_build/html 文件夹中生成文档：

make -C docs html

以前的版本

CoTracker v2

你可以在离线和在线模式下使用 torch.hub 的 CoTracker v2。

离线模式：

pip install imageio[ffmpeg], 然后：

import torch
# 下载视频
url = 'https://github.com/facebookresearch/co-tracker/blob/main/assets/apple.mp4'

import imageio.v3 as iio
frames = iio.imread(url, plugin="FFMPEG")  # plugin="pyav"

device = 'cuda'
grid_size = 10
video = torch.tensor(frames).permute(0, 3, 1, 2)[None].float().to(device)  # B T C H W

# 运行离线 CoTracker：
cotracker = torch.hub.load("facebookresearch/co-tracker", "cotracker2").to(device)
pred_tracks, pred_visibility = cotracker(video, grid_size=grid_size) # B T N 2,  B T N 1

在线模式：

cotracker = torch.hub.load("facebookresearch/co-tracker", "cotracker2_online").to(device)

# 运行在线 CoTracker，使用不同的 API 的同一模型：
# 初始化在线处理
cotracker(video_chunk=video, is_first_step=True, grid_size=grid_size)  

# 处理视频
for ind in range(0, video.shape[1] - cotracker.step, cotracker.step):
    pred_tracks, pred_visibility = cotracker(
        video_chunk=video[:, ind : ind + cotracker.step * 2]
    )  # B T N 2,  B T N 1

v2 的检查点可以通过以下命令下载：

wget https://huggingface.co/facebook/cotracker/resolve/main/cotracker2.pth

CoTracker v1

它可以直接通过 pytorch hub 获取：

import torch
import einops
import timm
import tqdm

cotracker = torch.hub.load("facebookresearch/co-tracker:v1.0", "cotracker_w8")

旧版本的代码可以在这里找到 here。 你也可以下载相应的检查点：

wget https://dl.fbaipublicfiles.com/cotracker/cotracker_stride_4_wind_8.pth
wget https://dl.fbaipublicfiles.com/cotracker/cotracker_stride_4_wind_12.pth
wget https://dl.fbaipublicfiles.com/cotracker/cotracker_stride_8_wind_16.pth

许可证

CoTracker 的大部分内容采用 CC-BY-NC 许可证，但项目的部分内容则采用单独的许可条款：Particle Video Revisited 采用 MIT 许可证，TAP-Vid 和 LocoTrack 则采用 Apache 2.0 许可证。

致谢

我们感谢 PIPs、TAP-Vid、LocoTrack 公开发布他们的代码和数据。我们还要感谢 Luke Melas-Kyriazi 对论文的校对，以及 Jianyuan Wang、Roman Shapovalov 和 Adam W. Harley 提供的富有洞见的讨论。

引用 CoTracker

如果你觉得我们的仓库很有用，请考虑给它一个星 ⭐，同时在你的工作中引用我们的研究论文：

@inproceedings{karaev23cotracker,
  title     = {CoTracker: It is Better to Track Together},
  author    = {Nikita Karaev and Ignacio Rocco and Benjamin Graham and Natalia Neverova and Andrea Vedaldi and Christian Rupprecht},
  booktitle = {Proc. {ECCV}},
  year      = {2024}
}

@inproceedings{karaev24cotracker3,
  title     = {CoTracker3: Simpler and Better Point Tracking by Pseudo-Labelling Real Videos},
  author    = {Nikita Karaev and Iurii Makarov and Jianyuan Wang and Natalia Neverova and Andrea Vedaldi and Christian Rupprecht},
  booktitle = {Proc. {arXiv:2410.11831}},
  year      = {2024}
}

CoTracker3 快速上手指南

CoTracker3 是一款基于 Transformer 的高速视频点跟踪模型，能够跟踪视频中的任意像素点或准密集点集。它结合了光流法的优势，支持离线（整体处理）和在线（流式处理）两种模式。

1. 环境准备

系统要求

• 操作系统: Linux (推荐) 或 macOS
• GPU: 强烈推荐使用支持 CUDA 的 NVIDIA GPU（本地运行时必需以获得最佳性能）。虽然小任务可在 CPU 运行，但速度较慢。
• Python: 3.8+

前置依赖

确保已安装 PyTorch 和 TorchVision。建议安装带有 CUDA 支持的版本以加速计算。

请访问 PyTorch 官网 获取适合你环境的安装命令。 国内用户建议使用清华源或阿里源加速 PyTorch 安装：

pip install torch torchvision --index-url https://pypi.tuna.tsinghua.edu.cn/simple

此外，还需要安装 ffmpeg 用于视频读写：

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y ffmpeg

# macOS
brew install ffmpeg

2. 安装步骤

你可以选择通过 torch.hub 直接加载预训练模型（最简单），或者克隆仓库进行本地开发。

方式一：直接使用（推荐）

无需克隆代码，只需安装必要的 Python 库即可通过 torch.hub 加载模型。

pip install imageio[ffmpeg]
# 国内加速
# pip install imageio[ffmpeg] -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：本地开发安装

如果你需要运行本地 Demo、评估或训练模型，请克隆仓库并安装。

git clone https://github.com/facebookresearch/co-tracker
cd co-tracker

# 安装核心包
pip install -e .

# 安装可视化和辅助工具依赖
pip install matplotlib flow_vis tqdm tensorboard hydra-core==1.1.0 mediapy

# 国内加速
# pip install -e . matplotlib flow_vis tqdm tensorboard hydra-core==1.1.0 mediapy -i https://pypi.tuna.tsinghua.edu.cn/simple

下载预训练权重（仅本地安装需要）： 如果选择本地安装，需手动下载检查点放入 checkpoints 文件夹：

mkdir -p checkpoints
cd checkpoints

# 下载 CoTracker3 在线模式模型 (滑动窗口，适合长视频)
wget https://huggingface.co/facebook/cotracker3/resolve/main/scaled_online.pth

# 下载 CoTracker3 离线模式模型 (单窗口，精度更高)
wget https://huggingface.co/facebook/cotracker3/resolve/main/scaled_offline.pth

cd ..

(注：国内网络下载 HuggingFace 文件可能较慢，建议使用镜像站或代理)

3. 基本使用

以下示例展示如何加载预训练模型并跟踪视频中的网格点。

离线模式 (Offline Mode)

适用于已知长度的视频，一次性处理所有帧，精度通常更高。

import torch
import imageio.v3 as iio

# 1. 准备视频数据
url = 'https://github.com/facebookresearch/co-tracker/raw/refs/heads/main/assets/apple.mp4'
frames = iio.imread(url, plugin="FFMPEG")  # 读取视频帧

device = 'cuda'
grid_size = 10  # 在第一帧采样 10x10 的点网格
# 转换格式为 (B, T, C, H, W) 并移至 GPU
video = torch.tensor(frames).permute(0, 3, 1, 2)[None].float().to(device)

# 2. 加载离线模型
cotracker = torch.hub.load("facebookresearch/co-tracker", "cotracker3_offline").to(device)

# 3. 执行跟踪
# pred_tracks: (B, T, N, 2) 坐标; pred_visibility: (B, T, N, 1) 可见性
pred_tracks, pred_visibility = cotracker(video, grid_size=grid_size)

在线模式 (Online Mode)

适用于长视频或实时流处理，内存效率更高，分块处理视频。

import torch
import imageio.v3 as iio

# 准备数据 (同上)
url = 'https://github.com/facebookresearch/co-tracker/raw/refs/heads/main/assets/apple.mp4'
frames = iio.imread(url, plugin="FFMPEG")
device = 'cuda'
grid_size = 10
video = torch.tensor(frames).permute(0, 3, 1, 2)[None].float().to(device)

# 1. 加载在线模型
cotracker = torch.hub.load("facebookresearch/co-tracker", "cotracker3_online").to(device)

# 2. 初始化在线处理
cotracker(video_chunk=video, is_first_step=True, grid_size=grid_size)

# 3. 分步处理视频
# step 是模型内部处理的步长，按需切片输入
for ind in range(0, video.shape[1] - cotracker.step, cotracker.step):
    pred_tracks, pred_visibility = cotracker(
        video_chunk=video[:, ind : ind + cotracker.step * 2]
    )

可视化结果

安装本地版本后，可使用内置可视化工具将跟踪轨迹保存为视频。

from cotracker.utils.visualizer import Visualizer

# 初始化可视器
vis = Visualizer(save_dir="./saved_videos", pad_value=120, linewidth=3)

# 生成视频 (保存至 ./saved_videos/demo.mp4)
vis.visualize(video, pred_tracks, pred_visibility)

命令行快速演示 (仅限本地安装)

如果你已完整安装仓库，可直接运行脚本测试：

# 运行离线 Demo (网格采样 10x10)
python demo.py --grid_size 10

# 运行在线 Demo
python online_demo.py