用 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

随后按以下顺序操作：

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

第二步：创建骨架文件

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

>> create_skeleton

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

>> I = ...

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

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

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

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

第四步：应用到新数据

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

一个完整示例

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

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

注意事项

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