DeepLabCut napari-DLC 高级标注功能实战指南：图层状态面板、复制粘贴、颜色方案与轨迹图

napari-DLC 是 DeepLabCut 生态中基于 napari 的关键点标注与标签精修插件，可内嵌于 DeepLabCut 主 GUI，也可作为独立标注工具使用。本文深入讲解该插件的进阶能力——图层状态面板、标注复制粘贴、颜色方案交互、以及轨迹绘图，帮助标注者在多帧、多个体、多关键点的大规模标注任务中显著提升效率。

napari-DLC 的入门工作流（帧提取、从零标注、续标、精修机器标签、视频裁剪）见 基础使用文档，本文假定读者已熟悉 napari 的基本标注操作。

认识 napari-DLC 的插件定位

在 deeplabcut/gui/widgets.py 中可以看到，DeepLabCut 主 GUI 通过 launch_napari() 启动 napari 查看器并自动挂载 napari-deeplabcut 插件的 Keypoint controls 停靠组件：

def launch_napari(files=None, plugin="napari-deeplabcut", stack=False):
    viewer = napari.Viewer()
    if plugin == "napari-deeplabcut":
        # Automatically activate the napari-deeplabcut plugin
        _, _ = viewer.window.add_plugin_dock_widget(
            "napari-deeplabcut",
            "Keypoint controls",
        )
    if files is not None:
        viewer.open(files, plugin=plugin, stack=stack)
    return viewer

因此，无论你从 Label Frames 标签页 点击 Label Frames 按钮，还是从 Extract Frames 标签页 进行手动抽帧，最终打开的始终是同一套 napari 标注界面。你还可以通过 pip install napari-deeplabcut 独立安装插件，再在终端运行 napari 从 Plugins -> napari-deeplabcut: Keypoint controls 打开。本文介绍的高级功能在该两种使用方式下行为一致。

图层状态面板：当前文件夹、标注进度与关键点大小

插件停靠组件（dock widget）顶部集中展示了与当前激活 Points 图层 相关的一系列状态信息。

当前文件夹（Current folder）

停靠组件顶部会显示当前激活 Points 图层所关联的标注数据文件夹。这一路径即使用 File -> Save Selected Layer(s)（或快捷键 Ctrl+S）保存标注时的落盘位置。实际保存行为可参考 基础使用文档 中的说明：标注会写入该文件夹下的 CollectedData_<ScorerName>.h5，同时生成配套的 CollectedData_<ScorerName>.csv。

这里有一个值得留意的项目结构约定：插件多项功能期望 config.yaml 位于 CollectedData_... 文件向上两级目录处（即标准 DeepLabCut 项目结构 项目根/config.yaml 与 项目根/labeled-data/<视频名>/CollectedData_...）。保持数据位于项目目录内可获得最佳兼容性；若不满足该结构，插件会提供回退路径请求你手动指定 config 文件，但部分功能可能受限。

标注进度（Labeling progress）

当加载已标注数据文件夹时，停靠组件会显示已标注帧的百分比。其分母是理论上可标注的关键点总数，即：

bodyparts 数量 × individuals 数量 × frames 数量

该百分比只是相对标注进度的粗略估计，而非绝对完整度指标，原因如下：可见性无法纳入计算，被遮挡/隐藏的关键点不会出现在每个个体、每个帧上。因此对于存在遮挡的项目，你不可能（也不应该）在每个个体的每个帧上标满所有 bodypart，进度百分比永远到不了 100% 是正常现象。

关键点大小滑块（Point size slider）

停靠组件内置一个滑块，用于统一调整查看器中所有关键点的显示大小。所选尺寸会写入项目的 config.yaml 以便记忆，下次会话自动复用——这意味着你可以在团队间通过配置文件同步一致的标注视图体验。

跨帧复制粘贴标注

当多个帧的标注内容高度相似（例如动物姿态在相邻帧中几乎不变）时，napari-DLC 提供跨帧复制粘贴能力：

1. 使用选择工具（快捷键 3）选中要复制的关键点；
2. 按 Ctrl+C 复制选中的关键点；
3. 跳转到目标帧，按 Ctrl+V 粘贴。

粘贴后按需微调关键点位置即可，可以显著减少逐帧重复标注的工作量。该功能同样适用于在【精修机器标签】场景下把人工修正后的姿态快速复制到相邻帧。

颜色方案显示与快速选择

插件会在停靠组件中列出所有 bodypart 及其对应的颜色，并通过 Show color scheme 按钮控制该列表的显示/隐藏。列表默认只显示当前查看器中可见的关键点所对应的 bodypart，如需显示 config 中定义的全部 bodypart，勾选列表顶部的 Show all bodyparts 复选框即可。

颜色方案与 config 的联动遵循 基础使用文档 中的更新机制：当你在标注过程中拖入一份新的 config.yaml，若新的 bodypart 集合未增加新关键点（通常只是颜色调整），插件会直接应用新配色而不弹出任何提示。

快速选择指定 bodypart / individual

• 按 bodypart 选择：在颜色方案列表中点击某个 bodypart，会选中查看器中该 bodypart 的所有关键点（多动物项目里跨个体一并选中）。这在需要批量编辑某个身体部位时非常高效，例如统一微调 "snout" 的所有标注点。
• 按 individual 选择：在 individual 着色模式下，颜色方案列表还会显示 individuals 列表，点击某个 individual 即选中属于该个体的全部关键点。

跳转到当前不可见的关键点

当你需要定位一个当前不在查看器视窗内的 bodypart 时：

1. 在颜色方案列表中勾选 Show all bodyparts；
2. 点击目标 bodypart 条目；
3. 查看器会自动跳转到该 bodypart 的第一个实例并将其选中（如果该关键点存在）。

若该 bodypart 已可见，点击条目则退化为上述的"选中该 bodypart 全部关键点"行为。这一交互对多人协作时快速核对遗漏部位很有帮助。

轨迹图（Trajectory plot）

点击 Show trajectories 按钮，会在独立停靠组件中打开一个轨迹图，展示所有选中关键点随时间变化的轨迹，并按当前激活的颜色方案（bodypart 或 individual）着色。

• 要查看某个关键点的轨迹，先在查看器中选中该关键点（可用选择工具，或点击颜色方案列表中对应的 bodypart）。
• 轨迹图停靠组件提供缩放、平移以及调整时间窗口等控制项，方便聚焦分析某一时间段内的运动轨迹。

轨迹图与 半自动跟踪标注工作流 配合效果尤佳：跟踪结果常出现漂移（如某个跟踪点开始跟随背景或跳到另一个 bodypart/individual），此时可以选中疑似漂移的关键点，用轨迹图直观判断跟踪何时开始偏离，再在漂移起点执行修正与重新跟踪。

与基础标注流程的衔接

高级功能不是孤立的炫技，而是围绕标注效率设计的组合拳。建议的典型用法：

1. 用 基础使用文档 中的工作流完成抽帧与首帧标注；
2. 用 快速 bodypart 选择 批量定位某一部位，配合 跨帧复制粘贴 快速铺满相似帧；
3. 用 标注进度 监控整体完成度，用 轨迹图 复查连续帧上的标注一致性；
4. 若配置了机器预测（machinelabels-iter<...>.h5），结合 E 键的边界着色（红色边界代表置信度低于 config.yaml 中阈值）精修机器标签，详见 基础使用文档 的精修章节；
5. 最后确认选中正确的 Points 图层，以 Ctrl+S 保存为 CollectedData_<ScorerName>.h5。

常见问题排查

若你在使用高级功能时遇到异常，可参考 故障排查文档：

• 打开 Help -> Generate napari-dlc logs 生成诊断日志，并用 Copy to clipboard 复制，这是向维护者反馈问题最有效的途径；
• 图层被锁定（出现 "does not match the frames now in ..." 等消息）时，先保存有未提交修改的图层，再清空全部图层并重新打开目标文件夹；
• 若标注被写入错误文件夹（仅影响插件 v0.4.0 之前的旧版本写入的文件），可通过编辑 CollectedData_<ScorerName>.csv 并运行 deeplabcut.convertcsv2h5("/path/to/config.yaml") 修复。

小结

napari-DLC 的高级功能围绕"更快、更准、更可控"的标注目标设计：图层状态面板让标注进度与保存目标一目了然；复制粘贴与颜色方案交互把重复性操作压缩到数次点击；轨迹图则为连续帧一致性审查提供了直观工具。将这些能力与基础工作流、半自动跟踪标注（tracking 文档）相结合，可以构建一套覆盖从抽帧到最终训练数据产出的完整高效标注管线。