[!IMPORTANT] EGO-EXO4D 数据集公告： Ego-Exo4D V2 现已 向公众开放。V2 版本包含 5035 次拍摄中的 1286.30 小时视频（其中 221.26 小时为第一视角视频），并附有 更多标注信息。有关具体变更内容，请参阅 更改日志。

EGO4D 更新： 由于新增了 Goal-Step 标注及配套的“分组视频”，现已发布 V2.1 版本。更多信息请参阅 文档。

Ego4D 和 Ego-Exo4D

Ego-Exo4D 是一个大规模多模态、多视角（包括 3D）的视频数据集及基准挑战赛。该数据集由参与者佩戴至少一台第一视角（egocentric Aria 眼镜）和一台第三视角（exocentric GoPro 相机）摄像设备同步录制而成。

• 请参阅 官网、 文档、 论文、博客文章以及 视频介绍。

Ego4D 是全球最大的第一视角视频机器学习数据集及基准测试套件，包含超过 3700 小时的标注第一视角视频数据。

• 有关更多信息，请参阅 官网、 文档 或 论文。

入门指南

• 若要 访问 数据，请参考文档：
  • 对于 Ego-Exo4D：请参阅 入门指南 页面。
  • 对于 Ego4D：请参阅 从这里开始 页面。
• 若要 下载 数据，请参考：
  • 对于 Ego-Exo4D：Ego-Exo4D 下载 CLI README
  • 对于 Ego4D：Ego4D CLI README
• 在此处 探索 Ego4D 或 Ego-Exo4D（需持有许可证）：Ego4D 可视化工具
• 请阅读下方的 概要 以了解本仓库的详细信息。

概要

Ego4d 仓库（ego4d Python 模块）包含以下内容：

• Ego-Exo4D 下载 CLI，用于下载 Ego-Exo4D 数据集（可通过命令 egoexo 使用）
• Ego4D 下载 CLI，用于下载 Ego4D 数据集（可通过命令 ego4d 使用）
• 一个简化 API，用于抽象常见的视频读取库 (TorchAudio, PyAV),
• 一个用于 特征提取 的 API，其中包括针对常见模型的轻量级封装 (Omnivore 和 SlowFast 等)
• 笔记本（适用于 Ego4D 和 Ego-Exo4D)，用作分析和使用数据集的示例与教程
  • Ego4D 的 Colab 笔记本还提供了基准测试（VQ、NLQ 和 STA）的额外示例，详情请见：https://ego4d-data.org/docs/challenge/
• 用于在数据集中训练模型的研究代码，例如 clep
  • 注意： Ego-Exo4D 的基线代码即将推出！
  • 注意： Ego4D 基准测试的基线代码位于单独的 GitHub 仓库中，详情请参阅 EGO4D 组织 和 文档

有关详细信息，请参阅下方的 仓库结构。

设置

请按照以下步骤设置 Ego4D 下载 CLI 并安装 ego4d Python 模块。

选项 1：通过 PyPi 包

[!TIP] 请确保您已创建并激活 conda 或 pyenv 环境。如果您不确定如何操作，可以参考 选项 2：步骤 1。

pip install ego4d --upgrade

注意： 请确保您使用的是 Python 3.10 或更高版本。

选项 2：克隆或下载代码

请确保您已将代码克隆或下载到本地磁盘。所有说明均假定您位于 仓库根目录。

步骤 1：创建或使用环境

创建一个 conda 环境以支持 pip 安装：

conda create -n ego4d python=3.11 -y
conda activate ego4d

如果您正在使用现有的 conda（或 pyenv）环境，请确保已安装 至少 Python 3.10。

步骤 2：

pip install .  # 从 Ego4D 根目录运行

现在您应该能够导入 ego4d：

python3 -c 'import ego4d; print(ego4d)'

您可以通过上述命令的输出检查 ego4d 模块是否正确链接到您文件系统中的相应文件。

仓库结构

该仓库包含多个按主题划分的目录。每个主题都配有相应的 README.md 文件，请参阅。

所有 Python 代码均位于 ego4d 及其子目录中。每个子目录旨在覆盖一个特定主题。

• ego4d：包含 ego4d Python 模块
  • cli：用于下载 Ego4D 数据集的 Ego4D CLI 工具
  • features：用于在数据集中进行特征提取
  • research：与数据集的研究和使用相关的所有内容（数据加载器等）。
    • research/clep：对比语言第一视角视频预训练
• viz：可视化引擎

可视化与演示

• 演示笔记本：标注笔记本
• 可视化引擎：Viz README

许可证

Ego4D 采用 MIT 许可证 发布。

Ego4D & Ego-Exo4D 快速上手指南

Ego4D 是全球最大的第一人称视角视频机器学习数据集，Ego-Exo4D 则是其升级版，包含多模态、多视角（第一人称 + 第三人称）同步视频数据。本指南帮助开发者快速配置环境并安装工具包。

环境准备

在开始之前，请确保满足以下系统要求：

• 操作系统: Linux 或 macOS (Windows 用户建议使用 WSL2)
• Python 版本: Python 3.10 或更高版本 (推荐 3.11)
• 包管理工具: 推荐使用 conda 或 pyenv 管理虚拟环境
• 网络环境: 下载数据集需要访问 Meta 服务器，建议配置稳定的网络连接

安装步骤

你可以选择通过 PyPI 直接安装，或克隆源码进行安装。推荐使用 Option 2 (源码安装) 以便获取最新的功能和示例代码。

Option 1: 通过 PyPI 安装 (最简方式)

如果你只需要使用 CLI 工具或基础 API，且已激活包含 Python 3.10+ 的虚拟环境：

pip install ego4d --upgrade

Option 2: 克隆源码安装 (推荐)

此方式适合需要进行二次开发、运行示例 Notebook 或使用研究代码的开发者。

第一步：创建并激活虚拟环境

使用 conda 创建名为 ego4d 的环境（指定 Python 3.11）：

conda create -n ego4d python=3.11 -y
conda activate ego4d

注意: 如果使用现有的 conda 或 pyenv 环境，请确保其中 Python 版本至少为 3.10。

第二步：克隆仓库并安装

首先克隆代码库（如果尚未克隆）：

git clone https://github.com/facebookresearch/Ego4d.git
cd Ego4d

在仓库根目录下执行安装命令：

pip install .

第三步：验证安装

运行以下命令检查模块是否链接正确：

python3 -c 'import ego4d; print(ego4d)'

如果输出显示了 ego4d 模块在你本地文件系统中的路径，则安装成功。

基本使用

安装完成后，你将获得两个主要的命令行工具（CLI）用于下载数据，以及一个 Python API 用于读取视频和提取特征。

1. 下载数据集

根据你需要下载的数据集类型，使用对应的命令：

• 下载 Ego4D 数据:

  ego4d --help  # 查看帮助文档
  # 具体下载命令请参考 ego4d/cli/README.md
  

• 下载 Ego-Exo4D 数据:

  egoexo --help # 查看帮助文档
  # 具体下载命令请参考 ego4d/egoexo/download/README.md
  

重要提示: 下载数据前，请务必前往 Ego4D 官网 或 Ego-Exo4D 官网 申请访问许可 (License)。

2. 使用 Python API 读取视频

ego4d 模块提供了统一的 API 来抽象不同的视频读取后端（如 TorchAudio, PyAV）。

import ego4d

# 示例：初始化数据集对象 (需先配置好数据路径)
# 具体用法请参考 notebooks 目录下的示例代码
dataset = ego4d.datasets.Ego4DDataset(split="test")

# 访问数据加载器或特征提取工具
# 详见 ego4d/features/README.md

3. 探索与可视化

• 在线浏览: 拥有 License 后，可访问 Ego4D Visualizer 在线浏览标注数据。
• 本地示例: 运行仓库中提供的 Jupyter Notebook 来学习如何分析数据：
  • 标注可视化: notebooks/annotation_visualization.ipynb
  • Colab 示例: 参考官网挑战页面获取基准测试 (VQ, NLQ, STA) 的 Colab 笔记。