DeepLabCut/napari-deeplabcut

# napari-deeplabcut - 用于姿态估计的关键点标注工具 [📚 插件文档](https://deeplabcut.github.io/DeepLabCut/docs/gui/napari_GUI.html) | [🛠️ DeepLabCut 安装指南](https://deeplabcut.github.io/DeepLabCut/docs/installation.html) | [🌎 DeepLabCut 官网](https://www.deeplabcut.org) | [](https://www.gnu.org/licenses/lgpl-3.0) [](https://pypi.org/project/napari-deeplabcut) [](https://python.org) [](https://github.com/DeepLabCut/napari-deeplabcut/actions/workflows/test_and_deploy.yml) [](https://codecov.io/gh/DeepLabCut/napari-deeplabcut) [](https://napari-hub.org/plugins/napari-deeplabcut) 一个用于关键点标注和标签精修的 napari 插件，也在 DeepLabCut 内部使用。 ## 安装说明 如果您已安装 `DeepLabCut[gui]`，则该插件已包含在内。 您也可以将 `napari-deeplabcut` 作为独立的关键点标注插件安装，而不使用完整的 DeepLabCut GUI。 ### 标准安装 使用 `pip`（例如在 `conda` 环境中）： ``` pip install napari-deeplabcut ``` 使用 `uv`： ``` uv venv -p 3.12 # create a new virtual environment with Python 3.12 source .venv/bin/activate # activate the virtual environment. Use the relevant command for your OS/shell if different. uv pip install napari-deeplabcut ``` ### 最新开发版本 使用 `pip`： ``` pip install git+https://github.com/DeepLabCut/napari-deeplabcut.git ``` ## 使用方法 ### 主文档 请参阅[官方插件文档](https://deeplabcut.github.io/DeepLabCut/docs/gui/napari/basic_usage.html)获取详细的使用说明。 ### 独立使用 启动 napari： ``` napari ``` 然后在以下位置激活插件： 可以加载的文件类型，如 `config.yaml`、图像文件夹、视频和 `.h5` 标注文件，既可以通过拖放到画布上加载，也可以通过 **文件** 菜单加载。 ### 推荐的入门方式 从零开始标注的最简单方法是： 1. 打开（或拖放）来自您计算机或 DeepLabCut 项目 `labeled-data` 目录下的一个仅包含图像的文件夹。 - 这意味着仅加载图像，不包含任何现有标注。 2. 打开（或拖放）来自您项目的 `config.yaml` 文件。 这会创建： - 一个包含图像（或视频帧）的 **图像** 图层，以及 - 一个填充了来自配置的关键点元数据的空 **点** 图层。 然后，您可以在刚创建的点图层中开始标注。 [🎥 演示](https://youtu.be/hsA9IB5r73E) ## 工具和快捷键 - `2` / `3`: 当 **点** 图层活动时，在标注和选择模式间切换。 - `4`: 启用平移和缩放。 - `M`: 循环切换顺序、快速和循环标注模式。 - `E`: 切换边缘着色。 - `F`: 在单个和身体部位着色模式间切换。 - `V`: 切换选定图层的可见性。 - `Backspace`: 删除选定的点。 - `Ctrl+C` / `Ctrl+V`: 复制和粘贴选定的点。 - 双击当前帧号可跳转到特定帧。 额外的停靠控件包括： - **覆盖时警告**: 启用或禁用在保存将覆盖现有标注时的确认提示。 - **显示轨迹**: 在主查看器中显示关键点随时间变化的轨迹。 - **显示轨迹图**: 在单独的停靠部件中打开轨迹图。 - **显示配色方案**: 显示活动/配置的颜色映射参考。 - **视频工具**: 提取当前帧并为视频存储裁剪坐标。 ## 保存图层 使用： 或快捷键： ``` Ctrl+S ``` ### 关键点保存行为 关键点标注会自动保存到相应的数据集文件夹中，格式为： ``` CollectedData_.h5 ``` 为方便起见，配套的 `.csv` 文件将写入同一文件夹。 ### 重要注意事项 - DeepLabCut 使用 **H5** 文件作为权威的标注文件。 - 保存前，请确保您要保存的 **点** 图层已选中。 - 如果同时选中了多个 **点** 图层，插件将不会保存，以避免歧义。 - 保存 `machinelabels...` 图层**不会**写回机器标签文件。 相反，精修后的标注会被写入相应的 `CollectedData...` 文件。 - 如果保存将覆盖现有标注，插件会提示确认。 - 在标注期间，可以通过取消勾选停靠部件中的“覆盖时警告”选项来禁用确认。 - 多个插件功能隐含地期望 `config.yaml` 位于保存的 `CollectedData...` 文件向上两级的目录中，因此为了最佳效果，请确保将配置文件保留在项目目录结构中。存在回退行为，但可能无法覆盖所有边缘情况。 - 如果您在预期位置没有配置文件的情况下保存 **点** 图层，系统会提示您提供与您正在处理的数据集相匹配的 `config.yaml` 文件路径。然后，插件将根据提供的配置路径将点和元数据保存到正确的文件夹中。之后，为了与其他 DeepLabCut 功能的最佳兼容性，建议将数据集文件夹移动到项目目录结构中的正确位置。如果需要，请编辑 `config.yaml` 文件以更新视频和图像文件夹的路径。 ## 视频支持 视频可以直接在 GUI 中打开。 当加载视频时，插件会启用一个小型视频操作面板，可用于： - 将当前帧提取到数据集中 - 可选择导出该帧的现有机器标签 - 定义裁剪坐标并将其保存到 DLC 的 `config.yaml` 中 基于视频的工作流中的关键点可以以与普通图像文件夹工作流相同的方式进行编辑和保存。 ## 工作流程（在 DLC GUI 之外） 建议的工作流程取决于数据集文件夹中已有的内容。 请注意，此处描述的是在 DeepLabCut GUI 之外，作为独立应用程序启动 napari 时的工作流程。 ### 1) 从零开始标注 当图像文件夹**尚不**包含 `CollectedData_.h5` 文件时使用此流程。 1. 打开一个包含提取图像的文件夹。 2. 打开相应的 DeepLabCut `config.yaml` 文件。 3. 选中刚创建的 **点** 图层。 4. 开始标注。 5. 使用 `Ctrl+S` 保存点图层。 保存后，该文件夹现在应该包含： ``` CollectedData_.h5 CollectedData_.csv ``` ### 2) 继续标注 当文件夹已包含 `CollectedData_.h5` 文件时使用此流程。 在 napari 中打开（或拖放）该文件夹。现有的关键点元数据和标注将从 H5 文件中加载，因此无需也不建议加载 `config.yaml`。 然而，在以下情况下加载配置仍然有用： - 项目的 bodyparts 发生了变化 - 您希望从项目配置中刷新已配置的配色方案 ### 3) 精修机器标签 当文件夹包含机器预测文件（如以下格式）时使用此流程： ``` machinelabels-iter<...>.h5 ``` 在 napari 中打开该文件夹。 如果同时存在 `CollectedData...` 文件和 `machinelabels...` 文件： - 编辑 `machinelabels` 图层以精修预测结果 - 可选择使用边缘着色 (`E`) 突出显示低置信度标签 - 保存选定的 `machinelabels` 图层，将精修结果合并到 `CollectedData` 中 如果文件夹仅包含 `machinelabels...` 而没有 `CollectedData...`，精修后的标注仍会被保存到一个新的 `CollectedData...` 目标文件中。 ## 工作流程图 ``` %%{init: {"flowchart": {"htmlLabels": false}} }%% graph TD id1[What stage of labeling?] id2[deeplabcut.label_frames] id3[deeplabcut.refine_labels] id4[Add labels to, or modify in, `CollectedData...` layer and save that layer] id5[Modify labels in `machinelabels` layer and save which will create or update `CollectedData...`] id6[Have you refined some labels from the most recent iteration and saved already?] id7["All extracted frames are already saved in `CollectedData...`. 1. Hide or remove all `machinelabels` layers. 2. Continue working in `CollectedData`."] id8["1. Keep only the most recent `machinelabels` layer. 2. Select it and press `E` to show edges. 3. Refine labels in `machinelabels`. 4. Save to merge into `CollectedData`. - If you revisit the dataset later, you can continue working in `CollectedData`."] id1 -->|I need to manually label new frames or fix existing labels|id2 id1 -->|I need to refine outlier frames from analyzed videos|id3 id2 --> id4 id3 -->|I only have a `machinelabels...` file|id5 id3 -->|I have both `machinelabels` and `CollectedData` files|id6 id6 -->|yes|id7 id6 -->|no, I just extracted outliers|id8 ``` ## 标注多个图像文件夹 一次应只处理一个数据集文件夹。 完成一个文件夹后： 1. 保存相关的 **点** 图层。 2. 从查看器中移除当前图层。 3. 打开下一个文件夹。 这可以保持插件操作和保存的明确性。 ## 定义裁剪坐标 要在 DLC 项目中存储裁剪坐标： 1. 从项目的 `videos` 文件夹打开视频。 2. 在视频工具中启用裁剪功能。 3. 在新创建的裁剪图层中绘制一个矩形（默认已选中该工具）。 4. 在部件中检查坐标后，点击 **存储裁剪坐标**。 裁剪坐标随后会被写回到项目配置中。 ## 参与贡献 欢迎贡献。 可以使用 [tox] 在本地运行测试。 请注意，我们使用 pre-commit 钩子对更改的文件运行检查工具和格式化程序，因此请确保安装 pre-commit 依赖项： ``` pip install pre-commit pre-commit install ``` ### 开发环境安装 克隆仓库并以可编辑模式安装。 使用 `pip`： ``` pip install -e . ``` 如果您还需要开发依赖项，请使用项目的 `dev` extra： ``` pip install -e .[dev] # includes pre-commit ``` ## 许可证 根据 [LGPL-3.0](https://www.gnu.org/licenses/lgpl-3.0) 条款分发。 ## 问题反馈 如果您遇到任何问题，请[提交问题](https://github.com/DeepLabCut/napari-deeplabcut/issues)并附上详细描述，如果可能，请提供一个最小的可重现示例。 ## 致谢 这个 [napari](https://github.com/napari/napari) 插件最初是使用 [Cookiecutter](https://github.com/audreyr/cookiecutter) 和 [@napari](https://github.com/napari) 的 [cookiecutter-napari-plugin](https://github.com/napari/cookiecutter-napari-plugin) 模板生成的。 我们感谢 Chan Zuckerberg Initiative (CZI) 为这项工作的初始开发提供资金支持！

标签：Apex, DeepLabCut, GUI, napari 插件, Python, 关键点标注, 图像标注, 姿态估计, 数据标注, 无后门, 机器学习, 标签细化, 深度学习, 生物力学分析, 计算机视觉, 逆向工具