FiftyOne 加载 UCF101 视频动作识别数据集：下载、split 划分与 App 可视化实战-平芜编程栈

FiftyOne 加载 UCF101 视频动作识别数据集：下载、split 划分与 App 可视化实战

【免费下载链接】fiftyoneRefine high-quality datasets and visual AI models项目地址: https://gitcode.com/GitHub_Trending/fi/fiftyone

导读

UCF101 是动作识别领域最经典的真实场景视频数据集之一，本文基于 FiftyOne 仓库中的数据集文档，完整讲解如何在 FiftyOne 中通过 Zoo API 加载该数据集、如何理解其train/testsplit 与fold机制、如何借助 FFmpeg 将原始视频重编码为 App 可直接播放的 H.264 MP4，以及如何用 CLI 完成同样的操作。读完本文，你将掌握foz.load_zoo_dataset("ucf101")从下载到可视化的完整链路，并了解其底层实现（fiftyone/utils/ucf101.py 与 ZooDataset 实现）。

FiftyOne App 中以网格方式浏览 UCF101 test split 的 25 个视频样本，缩略图下方的蓝色标签为各样本的动作类别（如 FieldHockeyPenalty、GolfSwing、BenchPress 等）。

数据集概览

UCF101 是一个从 YouTube 收集的真实动作识别视频数据集，包含101 个动作类别、13,320 段视频。它是 UCF50（50 类）的扩展版本，其核心价值在于"真实"二字：与许多由演员摆拍、场景受控的动作识别数据集不同，UCF101 的视频在相机运动、物体外观与姿态、物体尺度、视角、杂乱背景、光照条件等方面都存在巨大变化，因此是动作识别研究中公认最具挑战性的基准之一。

在数据组织上，101 个动作类别的视频被划分为25 个 group，每个 group 由同一动作的 4～7 段视频组成。同一 group 内的视频可能共享某些特征（如相似的背景、相似的视角），这正是官方训练/测试划分（splits）的设计基础——保证评测时模型看到的是"未见过的 group"。

数据集关键信息

根据 ucf101.rst 与 UCF101Dataset 类定义，该数据集在 FiftyOne 中的元信息如下：

项目	值
数据集名称（name）	`ucf101`
数据来源	UCF（中佛罗里达大学）CV 实验室官方网站
许可证（license）	`CC0-1.0`
数据集大小	约 6.48 GB
标签（tags）	`video, action-recognition`
支持的 split	`train`、`test`
ZooDataset 类	`UCF101Dataset`

在源码中，这些信息分别由 UCF101Dataset 的license、tags、supported_splits属性提供，并在parameters属性中以{"fold": self.fold}的形式暴露可配置参数。

环境准备：FFmpeg 与解压工具

视频数据集与图像数据集不同，处理链路依赖两个系统级工具：

1. FFmpeg（必需）

FiftyOne 需要 FFmpeg 来处理视频编解码。若未安装，视频在 App 中虽然"看起来"能显示，但不会以正确的宽高比渲染，标签叠加位置也会错位（详见 docs/source/installation/troubleshooting.rst#L92-L122）。各平台安装方式：

Linux：sudo apt install -y ffmpeg
macOS：brew install ffmpeg
Windows：从 FFmpeg 官网下载构建版本解压后加入 PATH

2. RAR 解压工具（按需）

UCF101 官方以.rar压缩包发布原始视频，FiftyOne 下载后需要解压。若系统中没有解压.rar的工具，需要额外安装，例如 macOS 上执行：

brew install rar

该要求与下载实现中的etau.extract_rar(rar_path, ...)调用直接对应——解压依赖系统或 Python 环境提供的 RAR 支持。

快速上手：Python 方式加载 UCF101

FiftyOne 通过 Zoo 系统封装了 UCF101 的下载、解压、split 整理与元数据解析，一条 API 即可完成：

import fiftyone as fo import fiftyone.zoo as foz import fiftyone.utils.video as fouv dataset = foz.load_zoo_dataset("ucf101", split="test") # Re-encode source videos as H.264 MP4s so they can be viewed in the App fouv.reencode_videos(dataset) session = fo.launch_app(dataset)

这段代码共三步：

加载数据集：foz.load_zoo_dataset("ucf101", split="test")下载并准备 test split，返回一个SampleCollection。
重编码视频：fouv.reencode_videos(dataset)将原始视频转码为 H.264 MP4，使其能被 FiftyOne App 流畅可视化（详见下文"视频重编码"一节）。
启动 App：fo.launch_app(dataset)在浏览器中打开可视化界面，即可浏览视频网格、按动作类别筛选样本（如上面的截图所示）。

关于 fold 参数

UCF101Dataset构造函数接受fold参数，默认值为1，支持1、2、3三种取值。fold 决定使用官方哪一套 train/test 划分文件来整理磁盘上的视频目录：

# 使用 fold 2 的划分 dataset = foz.load_zoo_dataset("ucf101", split="train", fold=2)

从下载实现可以看到，fold直接决定读取的划分文件：

test 划分文件：testlist%02d.txt（即testlist01.txt/testlist02.txt/testlist03.txt）
train 划分文件：trainlist%02d.txt

若传入fold之外的非法值，download_ucf101_dataset会抛出ValueError("fold must be (1, 2, 3)")。

快速上手：CLI 方式加载 UCF101

不写 Python 代码，直接通过fiftyone命令行完成同样的流程：

fiftyone zoo datasets load ucf101 --split test # Re-encode source videos as H.264 MP4s so they can be viewed in the App fiftyone utils transform-videos ucf101-test --reencode fiftyone app launch ucf101-test

三步对应关系：

fiftyone zoo datasets load ucf101 --split test：加载 test split，数据集在 FiftyOne 中注册为ucf101-test。
fiftyone utils transform-videos ucf101-test --reencode：对名为ucf101-test的数据集执行视频重编码。该命令在 fiftyone/core/cli.py#L5156-L5167 中定义，--reencode之外还支持--fps、--max-size 1920,1080、--max-fps 30.0等参数（例如--max-size 1920,1080 --max-fps 30.0可强制所有视频不超过 1920×1080、30fps）。
fiftyone app launch ucf101-test：启动 App 打开该数据集。

视频重编码：为什么需要，如何做

UCF101 原始视频并非统一的 H.264 MP4 格式，而 FiftyOne App 的视频播放依赖 H.264 编码。reencode_videos（fiftyone/utils/video.py#L89-L102）正是为此设计：将样本集合中的所有视频重编码为可在 App 中可视化的 H.264 MP4。

默认情况下，底层执行的ffmpeg命令为：

ffmpeg \ -loglevel error -vsync 0 -i $INPUT_PATH \ -c:v libx264 -preset medium -crf 23 -pix_fmt yuv420p -vsync 0 -an \ $OUTPUT_PATH

关键参数含义：

-c:v libx264：使用 H.264（x264）编码器；
-preset medium：编码速度/压缩率平衡档；
-crf 23：恒定质量因子，数值越小画质越高、体积越大；
-pix_fmt yuv420p：强制 YUV 4:2:0 像素格式，保证浏览器兼容；
-an：去除音轨（动作识别数据集通常无需音频）。

该函数还暴露了丰富的可选参数，可在 fiftyone/utils/video.py#L130-L150 及后续定义中查阅，常用的包括：

force_reencode=True：是否对已是 MP4 的视频也强制重编码；
media_field="filepath"：输入视频路径所在字段；
output_field/output_dir/rel_dir：输出路径控制；
update_filepaths=True：是否用新路径更新样本的filepath；
delete_originals=False：是否删除原始视频（未指定output_dir且不删除原始文件时，若新文件名冲突，原文件会被重命名为<name>-original.<ext>）；
skip_failures=False：单个视频转码失败时是否跳过继续；
其余**kwargs会透传给eta.core.video.FFmpeg，用于自定义编码器、码率等细节。

一个容易忽略的细节：重编码不会自动更新数据集的metadata字段。如果需要刷新元数据（时长、帧率、尺寸等），需手动执行：

sample_collection.compute_metadata(overwrite=True)

底层实现：下载与 split 整理流程

深入 fiftyone/utils/ucf101.py 可以看到完整链路。核心入口download_ucf101_dataset(dataset_dir, scratch_dir=None, fold=1, cleanup=True)的流程为：

下载视频：从UCF101.rar链接下载约 6.48 GB 的压缩包（L73-L96），已存在的文件不会重复下载。
下载划分文件：下载UCF101TrainTestSplits-RecognitionTask.zip官方划分压缩包并解压（L99-L114）。
按 fold 整理文件：读取testlist%02d.txt与trainlist%02d.txt（L117-L119 中的_load_split_info按行解析出视频相对路径），把视频逐个移动（etau.move_file）到dataset_dir/test/与dataset_dir/train/目录（L49-L67）。
清理：默认删除 scratch 临时目录。

而在 Zoo 层面，UCF101Dataset._download_and_prepare 做了两件关键事情：

去 split 化下载：UCF101 官方把全部视频打包在单一文件中，无法按 split 单独下载，因此该方法会先os.path.dirname(dataset_dir)去掉 split 子目录，下载完整数据集；只有对应 split 目录已存在时才跳过下载（L3423-L3431）。这意味着首次无论加载train还是test，都要下载完整的 6.48 GB 数据。
自动识别元数据：下载完成后，用VideoClassificationDirectoryTree数据集类型及其 Importer 解析出类别列表（classes）与样本数（num_samples），供 FiftyOne 建立索引。

正是这一设计，让"一行代码加载数据集"成为可能：用户只需要关心split和fold，文件组织与元数据推断全部由框架完成。

使用建议与常见问题

磁盘空间：完整数据集约 6.48 GB，且首次加载会下载全量数据（无论指定哪个 split），请预留充足空间；重编码后若保留原始文件，还会额外占用磁盘。
split 与评测规范：UCF101 官方划分为 3 个 fold，社区通常报告 3 个 fold 的平均准确率。若要在 FiftyOne 中复现该评测流程，请分别在fold=1/2/3下加载train与test。
App 中视频无法正确渲染：多半是 FFmpeg 缺失，按上文"环境准备"一节安装即可；重编码时注意-pix_fmt yuv420p与浏览器兼容性。
元数据过期：重编码改变了视频属性，若需要基于时长/帧率做分析，记得调用compute_metadata(overwrite=True)刷新。