DeepLabCut 数据后处理实战：自动标记身体部位距离异常的帧-育师

人工智能
深度学习
计算机视觉
科研

【免费下载链接】DeepLabCut

Official implementation of DeepLabCut: Markerless pose estimation of user-defined features with deep learning for all animals incl. humans

项目地址：https://gitcode.com/gh_mirrors/de/DeepLabCut

点击查看免费下载

导读

在 DeepLabCut 项目中，标注质量与预测质量直接决定下游分析（轨迹、速度、角度等）的可靠性。本篇指南围绕docs/recipes/post.md中的数据处理配方展开：基于身体部位间欧氏距离的阈值检测，自动标记距离异常的帧，用于在deeplabcut.check_labels人工检查之外，以脚本化方式筛查标注错误或预测异常。读完本文，你将掌握标注数据 MultiIndex 结构的读写方法、单动物/多动物/3D 项目下的距离计算适配，以及如何将该思路与deeplabcut.filterpredictions、deeplabcut.analyzeskeleton等后处理工具串联成完整的数据质检流水线。

一、为什么需要"距离阈值"质检：check_labels 的局限

DeepLabCut 提供了deeplabcut.check_labels(config)用于在标注阶段可视化每一帧的标签位置，其实现位于 deeplabcut/generate_training_dataset/trainingsetmanipulation.py：它会为labeled-data下每个视频子目录中的帧生成叠加标注点的图像，默认以+标记人工标注位置，并支持draw_skeleton、scale、dpi等参数。

但check_labels是"人眼审查"工具——当项目包含数千帧时，逐帧翻图效率极低，且某些错误（如头部与尾部被标注得距离过大）并不显眼。因此社区配方给出了一条自动化路线：直接在标注 DataFrame 上计算两个身体部位之间的欧氏距离，凡距离超过物理阈值（如头-尾长度 > 100 像素）的帧即为可疑帧，可将其索引提取出来进一步复核。

这一思路同样适用于推理阶段：模型预测输出的 H5 文件结构与标注文件一致，因此同一套距离检测代码可以复用于"预测异常"筛查。

二、先读懂数据：标注 H5 的 MultiIndex 列结构

配方代码的第一步是读取标注文件：

df = pd.read_hdf('path_to_your_labeled_data_file')

该 H5 文件即labeled-data/<视频名>/CollectedData_<scorer>.h5，例如仓库示例项目 examples/openfield-Pranav-2018-10-30/labeled-data/m4s1/ 下的同名文件。从源码可确认其结构：

行索引为帧（图像文件名或序号）；
列是 MultiIndex，由scorer、bodyparts、coords等层级组成；
单动物项目列层级为(scorer, bodyparts, coords)，coords 通常为x、y；
多动物项目额外包含individuals层级，即(scorer, individuals, bodyparts, coords)。

这一点在 deeplabcut/utils/skeleton.py 的SkeletonBuilder中可印证——它通过df.columns.get_level_values("bodyparts")枚举部位、通过"individuals" in self.df.columns.names判断是否多动物项目。

df.xs('head', level='bodyparts', axis=1)正是利用 MultiIndex 的xs方法沿列轴取出全部属于head的子列（对多动物项目即取出所有个体的head），随后.to_numpy()得到(帧数, 2)或(帧数, n_个体 × 2)的坐标矩阵。

三、核心配方：标记身体部位距离异常的帧

3.1 完整代码

以下代码直接取自docs/recipes/post.md，并保持原样：

import numpy as np import pandas as pd max_dist = 100 df = pd.read_hdf('path_to_your_labeled_data_file') bpt1 = df.xs('head', level='bodyparts', axis=1).to_numpy() bpt2 = df.xs('tail', level='bodyparts', axis=1).to_numpy() # We calculate the vectors from a point to the other # and group them per frame and per animal. try: diff = (bpt1 - bpt2).reshape((len(df), -1, 2)) except ValueError: diff = (bpt1 - bpt2).reshape((len(df), -1, 3)) dist = np.linalg.norm(diff, axis=2) mask = np.any(dist >= max_dist, axis=1) flagged_frames = df.iloc[mask].index

3.2 逐行解析

步骤	作用	关键点
`max_dist = 100`	距离阈值（像素）	需要依据视频分辨率与动物体型设定，100 像素是头-尾最大长度的示例值
`pd.read_hdf(...)`	载入标注/预测 H5	key 通常为`df_with_missing`，`pd.read_hdf`会自动读取
`df.xs('head', level='bodyparts', axis=1)`	沿列轴按`bodyparts`层级取`head`的所有坐标列	多动物项目会一次性取出所有个体的该部位
`bpt1 - bpt2`	逐帧计算两点间的向量	结果形状为`(帧数, 2)`或`(帧数, n_个体 × 2)`
`.reshape((len(df), -1, 2))`	将向量分组为"每帧每动物"的二维坐标点	`-1`自动推断个体数
`except ValueError`	兼容含第三列（如 3D 项目`z`坐标）的数据	若坐标列数为 3，则按`(帧数, -1, 3)`重排
`np.linalg.norm(diff, axis=2)`	对最后一个轴求欧氏范数	得到`(帧数, 动物数)`的距离矩阵
`np.any(dist >= max_dist, axis=1)`	只要某一帧存在任一动物超距即标记	布尔掩码
`df.iloc[mask].index`	提取被标记帧的索引	可直接用于后续定位、复核或剔除

3.3 输出解读与落地用法

flagged_frames是一个 Index 对象，保存所有"至少一对部位距离 ≥ 阈值"的帧标识。常见的后续处理：

打印数量与占比，评估整体标注质量：print(len(flagged_frames), "frames flagged out of", len(df))；
结合图像复核：将索引与labeled-data中的帧文件名对应，人工检查；
与check_labels输出互补：先自动缩小可疑范围，再对可疑帧集中人工审查。

注：此处距离为像素单位的平面欧氏距离，未考虑相机透视与景深；在 3D 项目中可换用包含z的三维范数（即走except分支），阈值应重新标定。

四、从标注数据推广到推理输出：数据结构的同源性

标注 H5 与analyze_videos产生的预测 H5 具有一致的 MultiIndex 列结构，因此上述配方只需替换文件路径即可用于预测结果质检。预测文件在项目中的命名约定为视频名 + scorer + ".h5"，其定位逻辑位于 deeplabcut/utils/auxiliaryfunctions.py 的find_analyzed_data：按视频名、scorer、是否_filtered后缀以及跟踪方法（track_method为box/skeleton/ellipse时的bx/sk/el标记）筛选候选文件，再由load_analyzed_data统一读取（auxiliaryfunctions.py）。

不过预测数据每列的坐标层级是(x, y, likelihood)三元组，若直接用原配方，try分支的-1, 2会失败并落入except分支按三维点处理——此时范数会把 likelihood 当作第三个坐标轴，结果失真。正确的做法是先用df.xs(..., level='coords', axis=1)只取x、y两列，再套用距离计算；同时可利用 likelihood 过滤低置信度部位（例如将 likelihood < 0.5 的坐标置为 NaN 后再计算，配合np.nanmax处理缺失）。

五、与骨架（Skeleton）系统的关联：从距离到结构约束

"两个部位之间的距离"本质上是骨架约束的一种表达。DeepLabCut 将骨架定义存放在项目config.yaml的skeleton字段中（部位对列表），并配套了完整的定义与消费链路：

交互式定义：deeplabcut/utils/skeleton.py中的SkeletonBuilder提供 GUI，通过 Lasso 框选把身体部位连成"骨头"，保存时写回config.yaml的skeleton键（skeleton.py）；
自动分析骨骼：deeplabcut.analyzeskeleton(config, videos, ...)会遍历cfg["skeleton"]中的每对部位，逐帧输出length（骨长）、orientation（骨方向，逆时针角度）与likelihood（取两点似然最小值）三列，保存为*_skeleton.h5，实现在 deeplabcut/post_processing/analyze_skeleton.py。其中单动物按(bp1, bp2)命名骨头、多动物按(个体, bp1, bp2)命名（analyze_skeleton.py）；
距离与角度的底层函数：calc_distance_between_points_two_vectors_2d（成对欧氏距离）与calc_angle_between_vectors_of_points_2d（逐点逆时针夹角）都位于 analyze_skeleton.py，可直接被自定义脚本复用——例如把"头-尾距离异常"扩展为"骨骼长度超过 3 倍中位数"的动态阈值判据。

因此，本文配方的更高级形态是：先运行deeplabcut.analyzeskeleton得到逐帧骨长序列，再对骨长做异常检测（如基于分位数或 z-score），从而摆脱固定像素阈值，适应不同动物个体与拍摄距离。

六、异常帧的"修复"链路：filterpredictions 与样条插值

当异常帧来自预测而非标注时，除了标记与剔除，DeepLabCut 还提供后处理平滑工具deeplabcut.filterpredictions（deeplabcut/post_processing/filtering.py），支持三种 filtertype：

filtertype	原理	关键参数	适用场景
`median`（默认）	滑动窗口中值滤波，基于`scipy.signal.medfilt`	`windowlength`（须为奇数，默认 5）	一般轨迹去抖
`arima`	对每个坐标序列拟合 SARIMAX 模型，按置信区间识别并修正异常值	`p_bound`（似然低于此值视为缺失，默认 0.001）、`ARdegree`（自回归阶数，默认 3）、`MAdegree`（滑动平均阶数，默认 1）、`alpha`（显著性水平，默认 0.01）	存在间歇性遮挡/跳点的轨迹
`spline`	逐列三次样条插值，填充长度不超过`windowlength`的缺失段并轻度平滑	`windowlength`作为最大填充 gap 长度	短时缺失的补全

该函数从deeplabcut.utils.auxiliaryfunctions.load_analyzed_data读取已分析数据，输出*_filtered.h5（可选另存 CSV），且会跳过已过滤文件。若把上一节的距离检测定位到的异常帧与filterpredictions结合，即可构成完整闭环：检测 → 评估 → 平滑/插值 → 复检。