DeepLabCut GUI 视频分析实战指南：从模型推理到生成标记视频的完整流程

导读

在完成模型训练与评估之后，下一步就是把训练好的模型真正应用到你的实验视频数据上。本文以 DeepLabCut 官方图形界面（GUI）中的 "Analyze Videos" 与 "Create Labeled Video" 两个标签页为主线，完整讲解从导入视频、运行姿态估计推理、检查分析结果，到生成可视化标记视频的端到端流程。读完本文，你将掌握：如何在 GUI 中正确配置视频分析与结果输出参数、理解 .h5 / .csv / .metapickle / plot-poses 等输出文件的含义与生成位置，并学会为单动物与多动物项目分别选择合适的分析选项。

本文基于 docs/beginner-guides/video-analysis.md 展开，并深入对应当前仓库的 GUI 实现源码，帮助你理解界面选项背后的真实调用链。

前置条件：完成训练与评估

GUI 中的视频分析并不是一个孤立步骤。它依赖你已经在项目中完成的以下工作：

1. 训练好网络：通过 "Train Network" 标签页完成模型训练，生成对应 shuffle 与训练集划分（TrainingFraction）下的模型快照（snapshot）。
2. （推荐）评估模型：通过 "Evaluate Network" 标签页评估不同 snapshot 的性能，并在 config.yaml 中设置合适的 snapshotindex（例如 -1 表示使用最后一个快照）。

从源码实现看，analyze_videos 会根据 config.yaml 中的 snapshotindex 决定使用哪个训练快照；若设置为 "all"，则会对所有快照逐一分析，代价非常高昂，代码会强制回退到最后一个快照并给出警告（见 predict_videos.py）。

使用 Analyze Videos 标签页运行姿态估计

操作步骤

在 GUI 主窗口中切换到 "Analyze videos" 标签页（窗口注册见 window.py），按以下步骤操作：

1. 选择视频格式与文件
   • 标签页内置了视频选择组件 VideoSelectionWidget，支持 .mp4、.avi、.mkv、.mov 等格式；GUI 会按视频扩展名自动分组（源码通过 get_files_grouped_by_suffix 实现，见 analyze_videos.py）。
   • 点击 Select Videos 按钮浏览并打开你的视频文件（也支持选择整个视频文件夹）。
2. 配置分析属性（Attributes）
   • Shuffle：指定使用哪个 shuffle 的训练模型，对应 config.yaml 中的 shuffle 编号。
3. 点击 Analyze Videos 开始分析。

分析开始后，任务会被放到独立线程中运行（通过 move_to_separate_thread，见 analyze_videos.py），主界面会显示进度条，按钮暂时禁用，避免界面卡死。分析耗时取决于视频长度、分辨率与模型复杂度，具体进度会输出到启动 GUI 的终端或 Anaconda Prompt 中。

小提示：分析时如果尚未选择任何视频，GUI 会记录一条 "No videos selected." 警告并直接返回（见 analyze_videos.py）。

其他分析选项详解

在 "Attributes" 与 "Other options" 区域，GUI 还提供了多个影响输出与后处理的开关，这些选项在点击 Analyze 后会被收集为 AnalyzeVideosOptions（见 analyze_videos.py），最终逐项映射到底层 deeplabcut.analyze_videos API：

GUI 选项	对应底层参数	说明
Save result(s) as csv	save_as_csv	除默认的 .h5 外，额外导出 .csv 文件，便于导入 MATLAB、R、Prism 等工具
Filter predictions	filter_data	分析后自动调用 filterpredictions，使用 median 滤波（窗口长度 5）平滑轨迹
Plot trajectories	plot_trajectories	分析后自动生成轨迹图（默认输出到 plot-poses 子文件夹）
Show trajectory plots	show_trajectory_plots	是否以弹窗形式显示轨迹图（仅在勾选 Plot trajectories 后可用）
Dynamically crop bodyparts（单动物）	dynamic	启用动态裁剪，对应参数三元组 (True, 0.5, 10)，即检测阈值 0.5、边界扩展 10 像素

对于多动物（multi-animal）项目，标签页还会额外显示以下选项（见 analyze_videos.py）：

多动物选项	对应底层参数	说明
Tracking method	track_method	追踪方法下拉框：ellipse、box、skeleton 三选一
Number of animals in videos	n_tracks	视频中的动物数量（默认取项目 individuals 数量，最大 100）
Calibrate assembly	calibrate	是否使用训练数据校准动物装配（assembly）过程
Assemble with ID only	identity_only	是否仅依赖模型学到的身份（ID）预测进行装配与追踪
Create video with all detections	create_video_all_detections	分析后自动调用 create_video_with_all_detections 生成包含全部检测结果的视频

对于多动物项目，勾选 "Save result(s) as csv" 后，GUI 会在所有批次的视频分析完成后，为每个视频所在文件夹调用一次 analyze_videos_converth5_to_csv 完成批量转换（见 analyze_videos.py）。多动物项目默认 auto_track=True，即分析后自动完成追踪与 tracklet 拼接，直接产出最终的 .h5 文件；若关闭自动追踪，则需要后续手动执行 convert_detections2tracklets 与 stitch_tracklets。

理解分析结果文件

分析完成后，结果保存在 视频文件所在目录（也可通过 destfolder 重定向）。GUI 文档中提到的几个核心文件及其底层生成逻辑如下：

• .h5 文件：主数据文件，命名格式为 视频名 + DLCscorer + ".h5"。内容为 MultiIndex 结构的 Pandas DataFrame，包含网络名称（scorer）、身体部位名称、坐标（x、y）与每个部位每帧的似然值（likelihood）。底层由 save_data 写入 HDF5 格式，键为 df_with_missing（见 auxiliaryfunctions.py）。
• .metapickle 文件：元数据 pickle 文件，命名与 .h5 同名（视频名 + scorer_meta.pickle）。其中记录了 start、stop、run_duration、Scorer、fps、batch_size、frame_dimensions、nframes、training set fraction、cropping 与 cropping_parameters 等推理信息（见 predict_videos.py）。
• .csv 文件：仅当勾选 "Save result(s) as csv" 时生成，为同一份数据的逗号分隔导出。
• plot-poses 子文件夹：勾选 "Plot trajectories" 时生成，存放各视频的轨迹图。底层实现见 plotting.py，轨迹图以视频所在目录下的 plot-poses/<视频名>/ 结构输出。

说明：save_data 会在同目录下同时写出 .h5 与 _meta.pickle 两个文件（见 auxiliaryfunctions.py），这就是官方文档中"同时看到 .metapickle、.h5 与可能出现的 .csv"的原因。

检查结果质量

• 打开 .h5 数据，检查各身体部位的 likelihood 分布，确认模型预测是否稳定。
• 查看 plot-poses 中的轨迹图，观察轨迹是否连续、是否有异常跳变。
• 若发现大量低置信度预测，可以回到 "Extract Outlier Frames" 标签页补充标注，迭代改进模型（即主动学习循环，元数据中的 iteration (active-learning) 字段会记录当前迭代轮次）。

生成标记视频：Create Labeled Video 标签页

分析完成后，你可以把预测结果叠加到原始视频上，生成可视化标记视频，便于展示结果或进行下游定性分析。

操作步骤

1. 切换到 "Create labeled video" 标签页（窗口注册见 window.py）。
2. 标签页会自动带上之前分析过的视频；若未自动选择，通过视频选择组件手动选中。
3. 点击 Create Videos 按钮生成标记视频。

可调的视频渲染参数

CreateVideos 标签页（create_videos.py）提供了比文档步骤更丰富的渲染控制项，最终全部映射到底层 deeplabcut.create_labeled_video API（见 make_labeled_video.py）：

GUI 参数	对应底层参数（默认值）	说明
Overwrite videos	overwrite=False	是否覆盖已存在的同名标记视频
Specify the number of trail points	trailpoints=0	每个关键点绘制的轨迹拖尾点数
Plot all bodyparts	displayedbodyparts="all"	取消勾选后可手动选择要绘制的身体部位子集
Draw skeleton	draw_skeleton=False	是否根据 config.yaml 中的骨架定义（skeleton）连接关键点
Use filtered data	filtered=False	使用滤波后的预测数据（需先执行 Filter predictions）绘制视频
Plotting confidence cutoff (pcutoff)	pcutoff=0.6	置信度阈值，低于该值的预测点不在视频中显示
Plot trajectories	plot_trajectories	生成视频的同时额外输出轨迹图
High quality video (slow)	save_frames=False	逐帧保存再合成视频（慢但更精细），底层走 matplotlib 渲染而非 OpenCV fastmode
Color keypoints by（多动物）	color_by="bodypart"	多动物项目可选 bodypart（按部位着色）或 individual（按个体着色）

此外，多动物项目还可以点击 Build skeleton 按钮打开骨架构建器（SkeletonBuilder）自定义骨架连线（见 create_videos.py）。

从底层实现看，create_labeled_video 支持 fastmode=True（默认，使用 OpenCV，速度快）与 fastmode=False（使用 matplotlib，可精细控制透明度、裁剪等）；GUI 的 "High quality video (slow)" 选项对应 save_frames=True，即逐帧保存后再合成。输出视频的命名规则为"原视频名 + 模型信息（scorer）+ 相关参数 + labeled"。

查看与使用标记视频

• 标记视频生成在 视频所在文件夹 中，命名形如 原视频名_模型scorer_...labeled.扩展名。
• 你可以直接用它进行结果展示，也可以将其作为下游分析（例如行为量化、3D 重建）的输入。
• 若生成失败，GUI 会在输出面板中列出失败的具体视频文件列表（见 create_videos.py），可据此排查。

进阶阅读建议

视频分析是 DeepLabCut 工作流中承上启下的一环。完成基本分析后，你可以继续深入以下方向：

• 深入理解模型与参数：阅读 models.md 与 training.md，了解 backbone、augmentation 等参数如何影响推理精度与速度。
• 多动物追踪进阶：参考 multi-animal-tracking.md，学习 ellipse / box / skeleton 追踪方法的选型与 tracklet 拼接细节。
• 批处理与下游分析：参考 BatchProcessing.md，将 GUI 操作对应的 analyze_videos、filterpredictions、plot_trajectories、create_labeled_video 等 API 脚本化，实现大规模视频的自动化分析流水线。
• 若希望进一步优化模型，可结合 pose_cfg_file_breakdown.md 理解推理配置文件 pose_cfg.yaml 中各字段的作用。