跟踪任意点（TAP）

[TAP-Vid] [TAPIR] [RoboTAP] [博客文章] [BootsTAP] [TAPVid-3D] [TAPNext] [TRAJAN] [TAPNext++]

https://github.com/google-deepmind/tapnet/assets/4534987/9f66b81a-7efb-48e7-a59c-f5781c35bebc

欢迎来到 Google DeepMind 官方的“跟踪任意点”（TAP）仓库，这里汇集了 TAP-Vid 和 TAPVid-3D 数据集、我们性能领先的 TAPIR 模型以及 RoboTAP 扩展。

• TAP-Vid 是用于评估此类任务模型的基准，包含针对真实视频和合成视频的真实标注点集合。
• TAPIR 是一种两阶段算法，第一阶段为匹配阶段，独立地在每一帧中为查询点找到合适的候选匹配点；第二阶段为精炼阶段，基于局部相关性更新轨迹和查询特征。该模型速度快，在 TAP-Vid 基准上显著超越了所有先前方法。
• RoboTAP 是一个利用 TAPIR 点轨迹在现实世界中高效执行机器人操作任务的系统。它还包含一个数据集，其中对真实的机器人操作视频进行了真实标注点的注释。
• BootsTAP（即 TAP 的自举训练）使用大量未标注的真实世界视频来提升跟踪精度。具体而言，该模型被训练为在视频的不同空间变换和损坏情况下，以及不同查询点选择下，都能给出一致的预测结果。我们将这一方法应用于 TAPIR，从而创建了 BootsTAPIR，其架构与 TAPIR 类似，但在 TAP-Vid 上表现显著优于 TAPIR。
• TAPVid-3D 是用于评估 3D 点跟踪任务模型的基准及指标集合。该基准包含 4,000 多个真实世界视频中的 100 万条以上计算得出的真实轨迹。
• TAPNext 是我们最新、功能最强、速度最快且最简单的跟踪器。它将 TAP 问题建模为下一个标记预测，并通过在网络中传播信息来简单地跟踪点。值得注意的是，我们最好的 TAPNext 检查点是使用 BootsTAP 流程进行微调的。
• TRAJAN 是我们的首个点轨迹自动编码器（TRAJAN）。TRAJAN 以一组支持点轨迹为条件，重建一组待测查询点的轨迹。TRAJAN 学习到的嵌入空间可用于比较视频分布、在不依赖物体外观的情况下比较不同视频中的运动轨迹，以及评估生成式视频模型输出视频的真实性和一致性。
• TAPNext++ 是一个改进版的 TAPNext 检查点，其稳定跟踪性能提升了 40 倍，能够穿越遮挡并展现出强大的重新检测能力。它已在包含多种新颖训练策略的 1024 帧合成序列上进行了微调。

本仓库包含以下内容：

• TAPNext / TAPNext++ / TAPIR / BootsTAPIR 演示，可通过克隆此仓库实现在线 Colab 演示 和离线 实时演示。
• TRAJAN 演示，用于在线 Colab 演示。
• TAP-Vid 基准，包括评估用的 数据集 和 指标。
• RoboTAP 基准，包括评估用的 数据集 和基于点轨迹的聚类代码。
• TAPVid-3D 基准，提供评估用的 指标 以及 TAPVid-3D 基准的示例 评估代码。
• 检查点，包含 TAP-Net（TAP-Vid 论文中提出的基线）、TAPIR 和 BootsTAPIR 的 预训练 模型权重，格式分别为 Jax 和 PyTorch。
• 训练说明，介绍如何在 Kubric 上 训练 TAP-Net（TAP-Vid 论文中提出的基线）和 TAPIR。

演示

运行 TAPNext / TAPNext++ / TAPIR / BootsTAPIR 最简单的方式是使用我们的在线 Colab 演示。您也可以克隆本仓库并在自己的硬件上运行，包括实时演示。

Colab 示例

您可以通过运行 Colab 示例来了解 TAPIR 的工作原理。您还可以上传自己的视频，并尝试使用 TAPIR 进行点跟踪。

我们提供了几个 Colab 示例：

1. TAPNext++：这是一个经过微调的 BootsTAPNext 检查点，能够进行长期跟踪、遮挡跟踪和重新检测。它已在 PointOdyssey 和 Kubric-1024 数据集上进行了微调。

2. BootsTAPNext：这是功能最强大的 TAPNext 模型，可在每帧上在线运行。该模型即论文中所报道的 BootsTAPNext 模型。

3. BootsTAPNext PyTorch：这是用 PyTorch 重新实现的功能最强大的 TAPNext 模型，其架构和权重与 Jax 版本完全一致。

4. 标准 TAPIR：这是功能最强大的 TAPIR / BootsTAPIR 模型，可一次性处理整段视频。我们在论文中主要报告了该模型的结果。

5. 在线 TAPIR：这是顺序因果的 TAPIR / BootsTAPIR 模型，支持对点的在线跟踪，可在 GPU 平台上实时运行。

6. 彩虹可视化：这种可视化效果被广泛应用于我们的预告视频中：它能够自动进行前景/背景分割，并校正因相机运动导致的轨迹偏移，从而直观展示物体在真实空间中的运动路径。

7. 标准 PyTorch TAPIR：这是用 PyTorch 重新实现的 TAPIR / BootsTAPIR 模型，其架构和权重与 Jax 版本完全一致。

8. 在线 PyTorch TAPIR：这是用 PyTorch 重新实现的顺序因果 BootsTAPIR 模型，其架构和权重与 Jax 版本完全一致。

9. TRAJAN：这是一种点轨迹自编码器，可根据一组输入点轨迹重建未见点轨迹的运动。
10. RoboTAP：这是 RoboTAP 中使用的分割算法演示。
11. Kubric for TAPVid(3D)：此可视化展示了如何使用 Kubric 数据集生成具有世界坐标系的 2D 和 3D 真实点轨迹。

实时演示

克隆仓库：

git clone https://github.com/deepmind/tapnet.git

切换到项目目录：

cd tapnet

安装 tapnet Python 包（以及运行推理所需的依赖）：

pip install .

下载检查点：

mkdir checkpoints
wget -P checkpoints https://storage.googleapis.com/dm-tapnet/causal_tapir_checkpoint.npy

将当前路径（即 TapNet 安装目录的父目录）添加到 PYTHONPATH：

export PYTHONPATH=`(cd ../ && pwd)`:`pwd`:$PYTHONPATH

如果您希望使用 CUDA，请确保已安装相应的驱动程序，并安装与您的 CUDA 和 CUDNN 版本兼容的 JAX 版本。请参考 JAX 官方文档，以正确安装支持 CUDA 的 JAX 版本。

随后，您可以在实时摄像头画面中运行预训练的因果 TAPIR 模型，并选择要跟踪的点：

cd ..
python3 ./tapnet/live_demo.py \

在我们的测试中，使用 Quadro RTX 4000（一款 2018 年发布的移动 GPU）处理 480x480 分辨率的图像时，帧率可达约 17 fps。

基准测试

该仓库包含三个相互关联但独立的基准测试：TAP-Vid、其后续扩展 RoboTAP 以及 TAPVid-3D。

TAP-Vid

https://github.com/google-deepmind/tapnet/assets/4534987/ff5fa5e3-ed37-4480-ad39-42a1e2744d8b

TAP-Vid 是一个包含视频及其点轨迹的数据集，这些轨迹可以是人工标注的，也可以是从模拟器中获取的。其目标是评估在任何固体物理表面上对可追踪点的跟踪性能。算法会接收某一帧上的单个查询点，并需要生成该点在整个视频序列中的完整轨迹，即包括该点移动到了哪里（如果可见）以及在其他每一帧中是否可见。这要求达到点级别的精度（不同于以往基于边界框和分割的跟踪工作），并且能够在可能的变形表面上进行长期跟踪（不同于结构光流法），同时适用于任何物体（即不依赖于特定类别，不同于以往针对人类等特定类别的关键点跟踪方法）。

关于如何下载、使用及在 TAP-Vid 基准测试 上进行评估的更多详细信息，请参阅相应的 README。

RoboTAP

RoboTAP 是 TAP-Vid 和 TAPIR 的后续工作，旨在展示点跟踪模型在机器人技术中的重要性。

RoboTAP 数据集 采用与 TAP-Vid 相同的标注格式，但作为 TAP-Vid 的补充发布。从领域上看，RoboTAP 数据集与 TAP-Vid-RGB-Stacking 大致相似，主要区别在于所有机器人相关视频均为真实采集并由人工标注。此外，视频来源和物体类别也更加多样化。该基准数据集包含 265 个视频，仅用于评估目的。更多详情请参阅 TAP-Vid 的 README。我们还提供了一个 RoboTAP Colab Notebook，演示了论文中使用的分割算法。

TAPVid-3D

TAPVid-3D 是一个用于评估三维长距离任意点跟踪任务（TAP-3D）的数据集和基准测试。

该基准测试包含 4,000 多段真实世界视频，以及它们的度量级 3D 位置点轨迹。数据集涵盖了三种不同的视频来源，涉及多种物体类型、运动模式以及室内外环境。此仓库文件夹包含用于下载和生成这些标注及数据集样本以供查看的代码。请注意，它与 TAP-Vid 使用的是不同的许可证。

关于如何下载、使用及在 TAPVid-3D 基准测试 上进行评估的更多详细信息，请参阅相应的 README。

关于坐标的一点说明

在我们的存储数据集中，(x, y) 坐标通常采用归一化的栅格坐标：即 (0, 0) 表示左上角像素的左上角，而 (1, 1) 表示右下角像素的右下角。然而，我们的代码会立即将这些坐标转换为常规的栅格坐标，与 Kubric 读取器的输出一致：(0, 0) 表示左上角像素的左上角，而 (h, w) 则表示右下角像素的右下角，其中 h 是图像的高度（以像素为单位），w 是对应的宽度。

在处理 2D 坐标时，我们通常按 (x, y) 的顺序存储；而在处理 3D 坐标时，则通常按 (t, y, x) 的顺序存储，其中 y 和 x 仍为上述的栅格坐标，而 t 则是帧坐标，即 0 表示第一帧，0.5 表示第一帧和第二帧之间的时间点。请务必注意这一点：根据我们的指标，哪怕只差一个像素，结果也会有所不同。

检查点

tapnet/checkpoint/ 目录下必须包含一个名为 checkpoint.npy 的文件，该文件可使用我们的 NumpyFileCheckpointer 加载。您可以在下方或在 HuggingFace 上下载检查点，这些检查点应与论文中使用的检查点高度一致。

注：表格中的评估结果是在 256×256 推理分辨率下报告的，但更高的分辨率可能会带来更好的效果。对于 BootsTAPIR，我们通常发现 512×512 分辨率下的效果最佳；而对于 TAPIR，则甚至可以使用高于 512×512 的分辨率来进一步提升性能。

模型	检查点	配置	骨干网络	训练分辨率	DAVIS First (AJ)	DAVIS Strided (AJ)	Kinetics First (AJ)	RoboTAP First (AJ)
TAP-Net	Jax	tapnet_config.py	TSM-ResNet18	256×256	33.0%	38.4%	38.5%	45.1%
TAPIR	Jax & PyTorch	tapir_config.py	ResNet18	256×256	58.5%	63.3%	50.0%	59.6%
在线 TAPIR	Jax	causal_tapir_config.py	ResNet18	256×256	56.2%	58.3%	51.2%	59.1%
BootsTAPIR	Jax & PyTorch	tapir_bootstrap_config.py	ResNet18 + 4 层卷积	256×256 + 512×512	62.4%	67.4%	55.8%	69.2%
在线 BootsTAPIR	Jax & PyTorch	tapir_bootstrap_config.py	ResNet18 + 4 层卷积	256×256 + 512×512	59.7%	61.2%	55.1%	69.1%
TAPNext	Jax	tapnext_demo.ipynb	TrecViT-B	256×256	65.25%	68.9%	57.3%	64.1%
TAPNext++	PyTorch	torch_tapnextpp_demo.ipynb	TrecViT-B	256×256	65.6%	-	53.9%	61.1%
TRAJAN	Jax	trajan_demo.ipynb

训练

我们在训练目录中为 TAP-Net 和 TAPIR 提供了一个 Jax 训练与评估框架；详情请参阅训练 README。

其他研究者开发了 TAPIR 的 PyTorch 训练实现，可能也会引起您的兴趣；然而，这项工作 并非 由 Google DeepMind 开发，其准确性也尚未经过我们的验证。

引用本工作

请使用以下 BibTeX 条目来引用我们的工作：

@article{doersch2022tap,
  title={{TAP}-Vid: A Benchmark for Tracking Any Point in a Video},
  author={Doersch, Carl and Gupta, Ankush and Markeeva, Larisa and Recasens, Adria and Smaira, Lucas and Aytar, Yusuf and Carreira, Joao and Zisserman, Andrew and Yang, Yi},
  journal={Advances in Neural Information Processing Systems},
  volume={35},
  pages={13610--13626},
  year={2022}
}

@inproceedings{doersch2023tapir,
  title={{TAPIR}: Tracking any point with per-frame initialization and temporal refinement},
  author={Doersch, Carl and Yang, Yi and Vecerik, Mel and Gokay, Dilara and Gupta, Ankush and Aytar, Yusuf and Carreira, Joao and Zisserman, Andrew},
  booktitle={Proceedings of the IEEE/CVF International Conference on Computer Vision},
  pages={10061--10072},
  year={2023}
}

@article{vecerik2023robotap,
  title={{RoboTAP}: Tracking arbitrary points for few-shot visual imitation},
  author={Vecerik, Mel and Doersch, Carl and Yang, Yi and Davchev, Todor and Aytar, Yusuf and Zhou, Guangyao and Hadsell, Raia and Agapito, Lourdes and Scholz, Jon},
  journal={International Conference on Robotics and Automation},
  pages={5397--5403},
  year={2024}
}

@article{doersch2024bootstap,
  title={{BootsTAP}: Bootstrapped Training for Tracking-Any-Point},
  author={Doersch, Carl and Luc, Pauline and Yang, Yi and Gokay, Dilara and Koppula, Skanda and Gupta, Ankush and Heyward, Joseph and Rocco, Ignacio and Goroshin, Ross and Carreira, Jo{\~a}o and Zisserman, Andrew},
  journal={Asian Conference on Computer Vision},
  year={2024}
}

@article{koppula2024tapvid,
  title={{TAPVid}-{3D}: A Benchmark for Tracking Any Point in {3D}},
  author={Koppula, Skanda and Rocco, Ignacio and Yang, Yi and Heyward, Joe and Carreira, Jo{\~a}o and Zisserman, Andrew and Brostow, Gabriel and Doersch, Carl},
  journal={Advances in Neural Information Processing Systems},
  year={2024}
}

@article{zholus2025tapnext,
  title={TAPNext: Tracking Any Point (TAP) as Next Token Prediction},
  author={Zholus, Artem and Doersch, Carl and Yang, Yi and Koppula, Skanda and Patraucean, Viorica and He, Xu Owen and Rocco, Ignacio and Sajjadi, Mehdi S. M. and Chandar, Sarath and Goroshin, Ross},
  journal={arXiv preprint arXiv:2504.05579},
  year={2025}
}

@article{allen2025trajan,
  title={Direct Motion Models for Assessing Generated Videos},
  author={Allen, Kelsey and Doersch, Carl and Zhou, Guangyao and Suhail, Mohammed and Driess, Danny and Rocco, Ignacio and Rubanova, Yulia and Kipf, Thomas and Sajjadi, Mehdi S. M. and Murphy, Kevin and Carreira, Joao and van Steenkiste, Sjoerd},
  journal={arXiv preprint},
  year={2025}
}

许可与免责声明

版权所有 © 2022–2024 Google LLC

专属于 TAPVid-3D 基准的软件及其他材料受 tapvid3d/LICENSE 文件中所列许可协议的约束。

本仓库中的所有其他软件均采用 Apache License, Version 2.0（Apache 2.0）许可；除非符合 Apache 2.0 许可协议的规定，否则不得使用。您可以在以下网址获取 Apache 2.0 许可协议的副本：

https://www.apache.org/licenses/LICENSE-2.0

此处发布的所有非软件材料，包括 TAP-Vid 数据集的标注、RGB-Stacking 视频以及 RoboTAP 视频，均采用 Creative Commons BY 许可。您可以在以下网址获取 CC-BY 许可协议的法律文本：

https://creativecommons.org/licenses/by/4.0/legalcode

DAVIS 的原始视频来自验证集，同样根据其创作者的授权采用知识共享许可；详情请参阅 DAVIS 数据集。Kinetics 视频在 YouTube 上公开可用，但受各自独立许可的约束。详情请参阅 Kinetics 数据集网页。

除非适用法律另有规定或双方另有书面约定，否则在此处依据 Apache 2.0 或 CC-BY 许可协议分发的所有软件和材料均按“现状”提供，不附带任何明示或默示的保证或条件。具体的权利与限制以相应许可协议中的条款为准。

本项目并非 Google 官方产品。

TAPNet 快速上手指南

TAPNet 是 Google DeepMind 开源的“任意点跟踪”（Tracking Any Point）工具库，包含业界领先的 TAPIR、TAPNext 等模型，用于在视频中高精度跟踪任意物理表面上的点。

环境准备

• 操作系统: Linux (推荐) 或 macOS
• Python: 3.8+
• 深度学习框架: 支持 JAX 或 PyTorch。
  • 若使用 GPU 加速，请确保已安装对应的 CUDA 驱动和 cuDNN。
  • JAX 用户需根据 CUDA 版本安装对应的 jax[cuda] 版本。
• 硬件要求:
  • 离线处理：任意现代 GPU。
  • 实时演示：建议具备中等算力 GPU（测试显示 Quadro RTX 4000 可达 ~17 FPS）。

安装步骤

1. 克隆仓库

git clone https://github.com/google-deepmind/tapnet.git
cd tapnet

2. 安装依赖包

直接通过 pip 安装当前目录下的包及其推理依赖：

pip install .

提示：国内用户若下载缓慢，可添加清华或阿里镜像源： pip install . -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 配置环境变量

将项目根目录添加到 PYTHONPATH，以便正确导入模块：

export PYTHONPATH=$(cd ../ && pwd):$(pwd):$PYTHONPATH

4. 下载预训练模型

创建检查点目录并下载因果型 TAPIR (Causal TAPIR) 模型权重（适用于实时跟踪）：

mkdir checkpoints
wget -P checkpoints https://storage.googleapis.com/dm-tapnet/causal_tapir_checkpoint.npy

注意：若需其他模型（如 TAPNext++ 或 BootsTAPIR），请访问官方 Colab 示例或 HuggingFace 获取对应 .npy 权重文件。

基本使用

方式一：运行实时摄像头演示 (Live Demo)

安装完成后，可直接调用预训练模型连接摄像头进行实时点跟踪。运行后在画面中点击即可选择跟踪点。

python3 ./tapnet/live_demo.py

方式二：使用 Colab 在线体验 (推荐新手)

若本地环境配置困难，可直接使用 Google Colab 在线运行各种模型（包括 TAPNext++, BootsTAPIR, TRAJAN 等）：

• TAPNext++ (长时跟踪、遮挡恢复): 打开 Colab
• Standard TAPIR (离线全视频处理，精度最高): 打开 Colab
• Online TAPIR (实时逐帧处理): 打开 Colab
• PyTorch 版本: 仓库提供了与 JAX 架构完全一致的 PyTorch 实现，可在上述链接中选择带有 "PyTorch" 字样的 Notebook。

方式三：代码调用示例 (Python)

在 Python 脚本中加载模型并进行推理（以 TAPIR 为例）：

import jax.numpy as jnp
from tapnet.models import tapir_model

# 初始化模型
model = tapir_model.TAPIR()
checkpoint_path = 'checkpoints/causal_tapir_checkpoint.npy'
state = model.load_checkpoint(checkpoint_path)

# 准备输入数据 (video: [B, T, H, W, 3], query_points: [B, N, 3])
# query_points 格式为 [t, y, x]
video = ... 
query_points = ...

# 执行跟踪
predictions = model.predict(
    video=video,
    query_points=query_points,
    state=state,
    is_causal=True # 若使用因果模型进行实时/在线跟踪设为 True
)

# predictions 包含坐标轨迹、可见性概率及置信度