用 Leap 从零训练动物姿态追踪模型

Leap 是一套用于动物姿态追踪的深度学习工具：给它一段（或若干段）视频，它会学习在每一帧上定位你关心的身体关键点，然后把学到的能力应用到新的、未标注的视频上。它适合手上只有原始录像、没有现成标注数据，又希望自己训练一个关键点检测网络的研究者与工程人员。整个流程围绕 HDF5 数据文件展开，从聚类采样挑出有代表性的帧、定义骨架、少量标注、快速训练、反复迭代，直到预测足够准确，最后把网络应用到新数据。本文按这条主线给出可照做的步骤与参数说明。如果你只是想先了解这类工具的整体定位，可以先看 Leap 的工具条目，再回到本文动手。

需要提前说明的是：Leap 的文档与功能仍在持续演进，界面细节、命令名与默认值都可能随版本变化。下文涉及的版本、配额、价格一类信息，请以官网当前信息为准。

准备工作

环境与依赖

Leap 的主工作流在 MATLAB 中运行，因此第一步是确认已经安装全部依赖项，并把代码仓库下载到本地。仓库中的示例与 GUI 都通过 MATLAB 命令窗口调用，所以后续所有操作都假定你在 MATLAB 会话中进行。

MATLAB，且能正常调用 HDF5 相关内置函数（h5disp、h5read、h5create、h5write）。
已下载的 Leap 代码仓库，并已加入 MATLAB 路径。
Python 环境（可选，但强烈建议准备）：用于交叉检查 HDF5 数据集的维度顺序，Python 侧使用 h5py 即可。

数据格式要求

Leap 的输入与输出统一使用 HDF5 文件。可以把它类比为 MATLAB 的 MAT 文件或 Python/numpy 的 NPY 文件：跨语言可读、无损，不像 MP4、AVI 那样有压缩损失。视频需要先转换成这种格式，转换脚本与说明属于预处理环节，本文不展开，但可以用 VideoReader、h5create、h5write 自行完成。

输入数据集必须满足以下形状约定：高度 × 宽度 × 通道数 × 帧数。示例数据是一个用深度相机拍摄的家猫视频，存放在 box.h5 的 /box 数据集中。用 h5disp 查看文件结构：

>> h5disp('box.h5')
HDF5 box.h5
Group '/'
    Attributes:
        'exptPath': 'D:\data\CatNect\20180217_225142'
        'dataPath': 'D:\data\CatNect\20180217_225142\20180217_225142.mat'
    Dataset 'box'
        Size: 192x192x1x2085
        MaxSize: 192x192x1x2085
        Datatype: H5T_IEEE_F32LE (single)
        ChunkSize: 192x192x1x2
        Filters: deflate(1)
        FillValue: 0.000000
        Attributes:
            'dtype': 'single'

读入 MATLAB 后形状保持不变：

>> box = h5read('box.h5', '/box');
>> size(box)
ans =
   192   192     1  2085

四个维度依次是高度（192）、宽度（192）、通道数（1）、帧数（2085）。这里有两条硬性约束：

图像的高和宽必须能被 4 整除，否则 Leap 无法运行。原因是网络中包含下采样与上采样步骤。
像素值应归一化到 [0, 1] 区间。示例数据是 single/float32，但 uint8 格式的图像同样可以正常工作。

多通道（RGB）图像也受支持，但尚未经过充分测试。建议先用灰度图验证流程是否跑通，灰度也更快。

在 MATLAB 中可以用缩放后的色图查看第一帧：

>> imagesc(box(:, :, :, 1)), axis image, colorbar

MATLAB 与 Python 的维度顺序差异

这是一个很容易踩的坑：MATLAB 与 Python 的字节序不同，同一个 HDF5 数据集在两边读出来的形状是转置关系。用 Python 打开同一个文件可以看到：

In [1]: import h5py
In [2]: f = h5py.File("box.h5")
In [3]: f["box"]
Out[3]: <HDF5 dataset "box": shape (2085, 1, 192, 192), type "<f4">

Python 侧看到的是 帧数 × 通道数 × 高度 × 宽度。写预处理脚本或做数据校验时，务必按你所用语言的约定来理解维度，不要直接把 MATLAB 的 size 结果套到 Python 代码里。

操作步骤

第一步：用聚类采样构建标注数据集

视频中相邻帧高度相似，如果随便抽帧标注，网络学到的信息量很低。Leap 提供聚类采样（cluster sampling）：先按图像的内在统计特征分组，再从每组中抽取相同数量的样本，让外观独特但出现较少的帧也有公平机会进入标注集。

在 MATLAB 命令窗口输入：

>> cluster_sample

随后按以下顺序操作：

添加数据：点击 Add file... 选择 box.h5。有多段视频时可以逐个添加，也可以直接添加整个文件夹。注意所有视频必须共享相同的图像尺寸。加载完成后，界面会显示每个数据集包含多少帧。
加载样本帧：在右上角面板设置 Samples per video，使总数控制在约 10,000 以内，避免内存耗尽。点击 Load samples，等待下方出现确认信息。GUI 会以均匀步长尽量多地载入图像，从而在时间轴上均匀采样，缓解相邻帧自相似的问题。
计算 PCA：192×192 的一帧就是 36864 个数值，直接聚类代价很高。点击 Compute PCA 做降维，等待完成提示。数据量大时这一步可能需要数分钟。
查看方差解释：点击 Plot variance explained，观察需要多少维才能解释足够比例的方差。示例数据中前 100 维已接近 90% 的方差，其中大部分集中在前 10 维，因此取 100 维是合理选择。
查看特征模态：点击 Plot eigenmodes 可以看到每个主成分对应的像素权重分布，颜色相近表示这些像素相关。
确认使用投影：进入下一步前，确保勾选 Use these projections for clustering，否则聚类会直接使用原始图像。
计算聚类：设置 Number of clusters to use。这个值取决于数据本身，可以从 5 开始试，观察分离效果。点击 Compute clusters 并等待完成。
查看聚类中心：点击 Plot cluster centroids，检查每个簇的平均图像是否覆盖了足够多样的姿态。如果觉得还有更多变化没有被区分出来，就增大簇数重新计算。
设置每簇样本数：Samples per cluster 不应超过最小簇的规模。如果最小簇少于 10 张图，说明簇数设多了，应减少分组数。
选择采样顺序：Sample order 默认是 Cluster order，即按交替的组顺序保存图像，使相邻样本来自不同簇。另一个选项 Shuffle order 会在采样后随机打乱，顺序更无偏，但可能需要标注更多样本才能泛化到全部图像。
保存：点击 Preview 或 Save... 生成采样数据集并写入新文件，供后续标注使用。

第二步：创建骨架文件

骨架文件描述你要追踪的关键点数量，同时可以定义点与点之间的连接（用于可视化）以及每个点的名称（用于标注与分析时区分）。在 MATLAB 命令窗口输入：

>> create_skeleton

启动 GUI 后，需要先提供一张示例图像，才能开始定义骨架。从第一步生成的标注数据集中载入第一帧即可：

>> I = ...

载入图像后，在界面上依次放置关键点、为每个点命名，并按需要连接成骨架。骨架主要服务于可视化，但点名称在后续标注和结果分析中会一直用到，命名时最好一次到位。

第三步：标注少量帧并快速训练

这一步是整个流程的核心循环：先标注少量帧，用快速训练模式得到一个初步网络，用它去预测未标注帧，再把预测不准的帧补进标注集，重新训练。如此重复若干轮，直到预测精度满足要求。每轮只增加少量标注，避免一次性投入大量人工。

训练时使用快速训练模式，目的是在迭代早期尽快拿到可用的预测结果，而不是追求单次训练的最优精度。随着标注集逐步扩大、预测质量提升，再逐步提高训练强度。

第四步：应用到新数据

当网络在验证帧上的预测足够准确后，就可以把它应用到新的、未标注的视频数据上。输入数据同样需要满足前面提到的 HDF5 形状约定与尺寸整除要求。

一个完整示例

下面把上述步骤串成一个从头到尾可跑通的最小流程，以示例中的家猫深度视频为起点。

检查输入文件：确认 box.h5 中 /box 数据集的形状为 192×192×1×2085，高宽均可被 4 整除，像素值在 [0, 1] 内。用 h5disp('box.h5') 与 size(h5read('box.h5','/box')) 各验证一次。
启动聚类采样：运行 cluster_sample，添加 box.h5，把 Samples per video 设为使总数不超过约 10,000 的值，点击 Load samples。
降维：点击 Compute PCA，用 Plot variance explained 确认前 100 维已覆盖接近 90% 的方差，勾选 Use these projections for clustering。
聚类：簇数设为 5，点击 Compute clusters，再用 Plot cluster centroids 检查姿态多样性。若多样性不足则增加簇数重算。
导出标注集：Samples per cluster 设为不超过最小簇规模的值，Sample order 保持 Cluster order，点击 Save... 生成采样文件。
定义骨架：运行 create_skeleton，载入采样文件的第一帧，放置并命名关键点，连接成骨架后保存。
标注与训练：在采样集上标注少量帧，执行快速训练，得到初始网络。
迭代：用初始网络预测其余未标注帧，挑出预测偏差明显的帧补标注，重新快速训练。重复直到预测稳定。
推理：把训练好的网络应用到新的视频数据上，输出每帧的关键点位置。

注意事项

尺寸整除是硬约束：图像高、宽必须能被 4 整除，否则 Leap 直接无法运行。预处理阶段就要把尺寸调整好。
维度顺序因语言而异：MATLAB 读出的是高×宽×通道×帧，Python 读出的是帧×通道×高×宽。跨语言处理数据时先确认顺序，否则会得到完全错误的切片。
像素值范围：输入应归一化到 [0, 1]。single 与 uint8 都可以，但不要混用未归一化的整数数据。
多通道图像未充分验证：RGB 输入受支持但测试不充分，建议先用灰度跑通流程，灰度也更快。
所有视频尺寸必须一致：在聚类采样中一次添加多段视频时，它们必须共享相同的图像尺寸。
内存限制：Samples per video 的总数应控制在约 10,000 以内，否则可能内存不足。
PCA 耗时：数据量大时 Compute PCA 可能需要数分钟，期间不要重复点击。
簇数不能过大：如果最小簇的图像少于 10 张，说明分组过细，应减少簇数后重新聚类。
采样顺序的取舍：Cluster order 让相邻样本来自不同簇，通常更省标注；Shuffle order 更无偏，但可能需要更多标注样本才能泛化。
文档与功能仍在演进：界面、命令与默认参数可能随版本变化，实际操作时以当前版本的行为与官网说明为准。