自定义模型训练：Cellpose 插件用户手册

Train Custom Model: Cellpose - User Manual

Dragonfly Prototype Apps · Train Custom Model: Cellpose...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

自定义模型训练：Cellpose(菜单标题 Train Custom Model: Cellpose...)是一款嵌入 Dragonfly 的插件,让您直接使用 Dragonfly 场景中的数据训练属于自己的 Cellpose 细胞/目标分割模型,然后把它应用到完整图像上。整个流程分两步:先在 Train(训练) 选项卡里用「图像通道 Channel + 已标注的 MultiROI」微调出一个新模型文件;再在 Infer(推理) 选项卡里挑选任意一个已训练模型,对整幅图像逐切片分割,并把检测到的目标作为一个新的 MultiROI 发布回场景中。

底层引擎是 Cellpose——一个广泛使用的开源细胞分割深度学习框架。本插件调用的是 Dragonfly 2027.1 自带(内置)的 Cellpose,包括其 Cellpose-SAM 基础模型以及 Dragonfly 的 CellposeHelper 辅助类。因此本插件完全在 Dragonfly 进程内运行,不需要单独安装 Python 环境、不需要 venv、也没有「Setup Environment(搭建环境)」这一步。

许可证要点:Cellpose 采用 BSD 开源许可;其 Cellpose-SAM 权重则遵循其发布方各自的使用条款。本插件仅调用 Dragonfly 已内置的组件,安装或使用过程中从不联网下载任何内容。

运行前提:本插件需要 Dragonfly 2027.1(内含 Cellpose-SAM + CellposeHelper + cellpose)。在更早的 Dragonfly 版本上无法使用。

2. 适用场景

本插件特别适合生命科学与生物医学成像:当您需要在二维切片或三维堆栈中分割细胞、细胞核或其他类圆形结构,而通用模型对您自己的染色方式、放大倍率或样品类型效果不够理想、需要微调时,它非常有用。

• 手动标注了少量切片,希望训练出一个能推广到整个大型数据集的模型;
• 针对特定的染色、放大倍率、成像模态或样品类型,对通用模型做微调(fine-tune);
• 在已训练的自定义模型基础上继续微调(把上一个自定义模型作为新的基础模型);
• 在材料学或工业图像中分割其他团块状(blob-like)特征——只要能用 MultiROI 标注出目标,同样适用。

简而言之:凡是「有几张手工标好的切片 + 想要一个自动分割整卷数据的模型」的工作流程,本插件都能覆盖。

3. 安装与启用

本插件通过 Full Package(完整安装包) 安装。它属于「插件」类应用,在安装器中默认未勾选,需要您手动启用。

1. 把随附的 Full Package 压缩包解压到任意较短的目录(例如 C:\PL\,避免过深路径)。

2. 双击运行 `Install_FullPackage.bat`。

3. 在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),这只影响 Prototype Labs 核心的 blocks 与 recipes,不影响任何插件。

4. 在应用列表中勾选 `Train Custom Model: Cellpose...`(插件默认关闭,必须手动勾上)。

5. 点击 Install,等待控制台完成。

6. 完全退出并重启 Dragonfly(菜单只在启动时被扫描)。

重启后,菜单项出现在:Prototype Apps ▸ Train Custom Model: Cellpose...(位于 Train Custom Model 分组)。点击即可打开面板。

以后如需修改启用状态,最方便的方式是在 Dragonfly 内操作:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部的「Prototype Apps (Full Package)」列表里找到本插件,勾选=部署、取消=移除菜单项,重启 Dragonfly 生效。停用从不删除任何东西——本插件不含独立环境,重新启用后立即可用。

卸载:双击 Uninstall_FullPackage.bat 会移除所有 Full Package 的菜单项与插件。本插件在进程内运行、不含 venv/下载内容,所以卸载不会遗留任何独立的环境目录。

4. 运行环境与首次配置

本插件没有「Setup Environment(搭建环境)」这一步。 与需要联网下载、创建 venv 或导入 WSL 发行版的重型插件不同,本插件直接使用 Dragonfly 2027.1 自带的 Python 及其内置的 cellpose、torch 和 CellposeHelper,全部在 Dragonfly 进程内运行。

• 下载体积:0。 安装与首次使用都不联网、不下载任何模型或依赖包。
• 是否需要联网:否。 全程离线可用。
• 是否需要 GPU:建议但非必须。 插件会自动检测 NVIDIA GPU(通过 torch.cuda.is_available()):检测到就用 GPU 加速训练与推理;没有 GPU 时自动回退到 CPU,功能不变,只是更慢。
• 是否需要 WSL:否。
• 版本要求:必须是 Dragonfly 2027.1。 更早版本未内置 Cellpose-SAM/CellposeHelper,无法运行。

首次使用前唯一需要设置的是「Models folder(模型文件夹)」——训练得到的模型会保存在这里,推理时也从这里列出可选模型。默认值为 C:\CellposeModels,该目录在训练时会自动创建;您也可以用 … 按钮改到任意可写目录。

面板上的设置会自动记忆,保存在插件代码目录的 cellpose_config.json 以及 %LOCALAPPDATA%\CellposeCustom\config.json 中,下次打开面板时自动恢复。

失败时的替代方案:因为不涉及环境搭建,常见问题一般来自数据本身(见第 9 节)。若怀疑 GPU 显存不足,可关闭 True 3D 改用默认的 2D+Z 拼接模式,或减小批大小/图像尺寸后重试。

5. 界面说明

面板顶部有一段蓝色说明文字,概述插件用途。下方是一个可滚动区域,依次分为三块:公共设置、① 训练、② 推理。最底部是一行绿色的结果状态标签,以及一个只读的日志窗口(实时显示 Cellpose 的训练轮次、进度和错误信息)。

公共设置(Models folder)

• Models folder(模型文件夹):文本框 + … 浏览按钮。模型保存与列出的位置,默认 C:\CellposeModels。
• Refresh channels / MultiROIs / models(刷新):重新扫描当前 Dragonfly 场景中的图像通道、MultiROI,并刷新模型文件夹里的模型列表。

① Train / fine-tune(训练 / 微调)

• Image Channel(图像通道):下拉框,选择作为训练输入的图像通道。
• MultiROI (labels)(标注 MultiROI):下拉框,选择作为「金标准」标注的 MultiROI(每个标签 = 一个目标)。
• Orientation(切片方向):下拉框,可选 XY / XZ / YZ,默认 XY。
• Slice index(切片序号):数值框,选择在该方向上用作训练样本的切片;范围随所选通道尺寸自动调整,默认取中间切片。
• Add pair(添加样本对) / Clear pairs(清空样本对):把当前「通道 + MultiROI + 切片」加入训练集合,或清空已加入的样本;下方「Training pairs: N」显示已加入的对数。
• Base model(基础模型):下拉框,可选 Cellpose-SAM(默认)、cyto3、nuclei、(custom path...)(自定义路径)。
• Custom base path(自定义基础模型路径):文本框 + … 浏览按钮;仅当基础模型选为 (custom path...) 时使用,可指向之前训练的自定义模型以继续微调。
• Epochs(训练轮数):数值框,范围 1–5000,默认 100。
• Learning rate(学习率):文本框,默认 1e-05。
• Batch size(批大小):数值框,范围 1–64,默认 1。
• Diameter(直径):文本框,留空或 0 表示自动(Cellpose-SAM 忽略此项)。
• New model name(新模型名称):文本框,留空则自动生成带时间戳的名称。
• Train(训练):蓝色按钮,开始训练(在后台工作线程运行,界面保持响应)。

② Infer(推理,发布 MultiROI)

• Model(模型):下拉框列出模型文件夹中的所有模型(显示名称与文件大小 MB),旁边有 Refresh models(刷新模型) 按钮。
• Image Channel(图像通道):下拉框,选择要进行推理的完整图像通道。
• Stitch threshold (Z)(Z 向拼接阈值):文本框,默认 0.3,用于把逐切片的 2D 结果沿 Z 方向拼接成一致的三维目标。
• Flow threshold(流场阈值):文本框,默认 0.4。
• Cellprob threshold(细胞概率阈值):文本框,默认 0.0。
• Diameter(直径):文本框,留空或 0 表示自动。
• True 3D (do_3D) instead of 2D+stitch(真三维):复选框,默认不勾选;勾选后用真三维分割替代「2D 逐切片 + Z 拼接」。
• Result title(结果标题):文本框,留空则自动命名生成的 MultiROI。
• Infer -> publish MultiROI(推理并发布 MultiROI):绿色按钮,开始推理并把结果发布回场景。

6. 使用步骤

工作流 A:训练 / 微调一个模型

输入要求:场景中至少有一个图像通道,以及一个在该通道对应切片上标注了目标的 MultiROI(每个标签代表一个目标)。

1. 打开面板,点击 Refresh channels / MultiROIs / models 加载当前场景对象。

2. (可选)设置 Models folder 到您希望保存模型的目录。

3. 在 ① Train 里选择 Image Channel 与 MultiROI (labels)。

4. 选择 Orientation 和 Slice index——确保该切片上确实有标注目标。

5. 点击 Add pair 加入这一对样本;对每一张已标注的切片重复此步(可跨方向、跨切片)。「Training pairs」计数应随之增加。

6. 选择 Base model(初次训练建议用默认的 Cellpose-SAM;继续微调已有自定义模型则选 (custom path...) 并指定路径)。

7. 设置 Epochs、Learning rate、Batch size,并在 New model name 填写名称(留空则自动带时间戳)。

8. 点击 Train。日志窗口会显示各训练轮的进度;完成后新模型被保存到 Models folder,并自动出现在推理下拉框中。

若某个样本对所选切片上没有任何标签,训练时会自动跳过它;如果所有样本对都没有标签,训练会失败并提示。请确认切片方向与序号正确。

工作流 B:用模型推理并发布 MultiROI

输入要求:Models folder 中至少有一个模型(内置训练所得,或自定义路径导入),以及一个待分割的图像通道。

1. 在 ② Infer 中点击 Refresh models,从下拉框选择一个模型。

2. 选择要推理的 Image Channel。

3. 设置 Stitch threshold (Z)、Flow threshold、Cellprob threshold 与(可选)Diameter。

4. 如需真三维分割,勾选 True 3D;否则保持默认的 2D 逐切片 + Z 拼接。

5. (可选)在 Result title 填写生成 MultiROI 的名称。

6. 点击 Infer -> publish MultiROI。插件会逐切片分割、沿 Z 拼接,并把检测到的目标作为一个新的 MultiROI 发布回场景;日志会报告发布的目标数量。

7. 参数说明

训练参数(① Train 选项卡):

推理参数(② Infer 选项卡):

推理时的批大小由插件通过 CellposeHelper.findOptimizedBatchSizeForCellpose 自动优化,以匹配可用显存,无需手动设置;训练固定使用较小的内部权重衰减(weight decay)= 0.1。

8. 输出结果

训练输出:一个新的 Cellpose 模型文件,保存到 Models folder(文件名为您填写的名称,或自动生成的 cellpose_custom_<时间戳>)。训练完成后,插件会自动刷新推理选项卡的模型下拉框,新模型立即可选。模型列表按修改时间排序,显示模型名称与文件大小(MB)。

推理输出:一个新的 MultiROI 对象,发布回当前 Dragonfly 场景。它对齐到源图像通道的网格(几何、间距、原点一致),每个检测到的目标对应一个 MultiROI 标签。默认经由 Dragonfly 的 CellposeHelper 构建;若该路径不可用,插件会用备用方案(把标签体转成通道再取 MultiROI)自动完成。

如何查看:发布后,MultiROI 会出现在 Dragonfly 的对象浏览器(Object Tree)中,名称为您设置的 Result title 或自动名称 Cellpose_<模型名>。可像任何 MultiROI 一样,在 2D 切片视图和 3D 视图中显示、着色、做后续测量与分析。面板底部的日志会给出「Published MultiROI '...' with N object(s).」的确认信息。

9. 常见问题与故障排除

问:菜单里找不到「Train Custom Model: Cellpose...」?

答:确认在安装器中已勾选本插件(它默认关闭),并在安装后完全重启了 Dragonfly;菜单只在启动时扫描。也可在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 中检查其勾选状态。还需确认使用的是 Dragonfly 2027.1。

问:训练报错「All pairs had 0 labels on the chosen slices.(所选切片上都没有标签)」?

答:说明加入的样本对在所选方向/切片上不含任何 MultiROI 标签。请核对 Orientation 与 Slice index,确保定位到确实带标注的切片,重新 Add pair 后再训练。

问:推理提示「Cellpose found no objects.(未检测到目标)」?

答:可尝试调低 Cellprob threshold、显式填写一个 Diameter,或换用更贴合数据的模型;必要时增加训练样本或训练轮数重新训练。

问:训练/推理很慢或提示显存不足?

答:训练与推理会自动使用 NVIDIA GPU(检测到时);无 GPU 时回退到 CPU 会明显变慢。若显存不足,推理请保持不勾选 True 3D(用默认 2D+Z 拼接),训练可减小 Batch size 或使用更小的切片。

问:下拉框里看不到我的通道或 MultiROI?

答:先在 Dragonfly 中加载好数据,再点击 Refresh channels / MultiROIs / models 重新扫描场景。

问:训练好的模型在推理列表里看不到?

答:确认推理选项卡的 Models folder 指向与训练相同的目录,然后点击 Refresh models。列表会忽略 .json / .txt / .npy 等非模型文件。

10. 注意事项与已知限制

• 仅支持 Dragonfly 2027.1:依赖其内置的 Cellpose-SAM 与 CellposeHelper。
• 训练样本是二维切片:每个样本对取一张 2D 切片(可来自不同方向/序号),Cellpose 在这些 2D 图像上微调。
• MultiROI 标签与目标 1:1:每个 MultiROI 标签被当作一个独立目标(实例)。
• 在 Dragonfly 进程内训练:训练与推理共享 Dragonfly 进程;运行期间尽量避免同时进行占用大量显存/内存的其他操作。界面在后台线程中保持响应。
• Cellpose-SAM 与直径/通道无关:Diameter 主要面向 cyto 系列基础模型;选用 Cellpose-SAM 时该参数被忽略。
• 推理默认为 2D 逐切片 + Z 拼接:靠 Stitch threshold 在 Z 方向保持目标标签一致;True 3D 为可选模式。
• GPU 为可选加速项:无 GPU 也可运行,仅速度较慢。

11. 参考资料

• Cellpose 开源项目(BSD 许可):https://github.com/MouseLand/cellpose
• Cellpose 官方文档:https://cellpose.readthedocs.io
• Dragonfly 2027.1 内置的 Cellpose-SAM 功能与 CellposeHelper(见 Dragonfly 自带帮助文档)
• Full Package 安装与启用说明:随包 README.md 与安装器对话框

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation & Enabling

4. Runtime Environment & First-Run Setup

5. Interface Guide

6. Step-by-Step Usage

7. Parameter Reference

8. Outputs

9. FAQ & Troubleshooting

10. Notes & Known Limitations

11. References

1. Overview

Train Custom Model: Cellpose (menu title Train Custom Model: Cellpose...) is an embedded Dragonfly plugin that lets you train your own Cellpose cell/object-segmentation model directly from your Dragonfly data and then apply it to full images. The workflow has two steps: in the Train tab you fine-tune a new model file from an image Channel plus an already-labeled MultiROI; in the Infer tab you pick any trained model, segment a full image slice by slice, and publish the detected objects back into your scene as a new MultiROI.

The underlying engine is Cellpose, a widely used open-source deep-learning framework for cell segmentation. This plugin uses the Cellpose that ships inside Dragonfly 2027.1 — including its Cellpose-SAM base model and Dragonfly's CellposeHelper. As a result the plugin runs entirely in-process inside Dragonfly: there is no separate Python environment, no venv, and no "Setup Environment" step.

Licensing: Cellpose is distributed under the BSD license; its Cellpose-SAM weights follow their publishers' respective terms. The plugin only calls components already bundled with Dragonfly and never downloads anything during install or use.

Prerequisite: this plugin requires Dragonfly 2027.1 (which ships Cellpose-SAM + CellposeHelper + cellpose). It cannot run on earlier Dragonfly versions.

2. Use Cases

The plugin is ideal for life-science and biomedical imaging: when you need to segment cells, nuclei, or other rounded structures in 2D slices or 3D stacks, and the generic model needs fine-tuning to your own staining, magnification, or sample type.

• You have a few hand-labeled slices and want a model that generalizes to the rest of a large dataset;
• You want to fine-tune a generic model for a specific stain, magnification, imaging modality, or sample type;
• You want to continue fine-tuning an earlier custom model (use that previous model as the new base);
• You want to segment other blob-like features in materials or industrial images — anything you can label as a MultiROI.

In short, any workflow of the form "a few hand-labeled slices + a model to auto-segment the whole volume" fits this plugin.

3. Installation & Enabling

This plugin is installed via the Full Package installer. It is a "plugin"-type app and is OFF by default in the installer, so you must enable it explicitly.

1. Unzip the supplied Full Package to any short folder (e.g. C:\PL\) to avoid long-path issues.

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, pick the core install mode (Fresh or Compatible) — this only affects the Prototype Labs core blocks/recipes, not any plugin.

4. In the app list, tick `Train Custom Model: Cellpose...` (plugins are OFF by default, so you must check it).

5. Click Install and wait for the console to finish.

6. Fully quit and restart Dragonfly (menus are scanned only at startup).

After the restart the menu item appears at: Prototype Apps ▸ Train Custom Model: Cellpose... (in the Train Custom Model group). Click it to open the panel.

To change your choice later, the easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager, find this plugin in the "Prototype Apps (Full Package)" list at the bottom, tick = deploy / untick = remove the menu entry, and restart Dragonfly to apply. Disabling never deletes anything — this plugin has no separate environment, so re-enabling is instant.

Uninstall: double-click Uninstall_FullPackage.bat to remove all Full Package menu items and plugins. Because this plugin runs in-process with no venv/downloads, uninstalling leaves no separate environment folder behind.

4. Runtime Environment & First-Run Setup

This plugin has NO "Setup Environment" step. Unlike heavy plugins that download packages, build a venv, or import a WSL distro, this plugin uses Dragonfly 2027.1's own Python together with its bundled cellpose, torch, and CellposeHelper, all running in-process inside Dragonfly.

• Download size: 0. Neither install nor first use downloads any model or dependency.
• Internet needed: No. Fully usable offline.
• GPU needed: recommended, not required. The plugin auto-detects an NVIDIA GPU (via torch.cuda.is_available()): if present it accelerates training and inference; if absent it falls back to CPU with identical functionality, just slower.
• WSL needed: No.
• Version requirement: Dragonfly 2027.1 only. Earlier versions lack the bundled Cellpose-SAM / CellposeHelper and cannot run it.

The only thing to set before first use is the Models folder — trained models are saved there and listed there for inference. The default is C:\CellposeModels, created automatically at training time; you can point it anywhere writable via the … button.

Panel settings are remembered automatically in cellpose_config.json in the plugin's code folder and in %LOCALAPPDATA%\CellposeCustom\config.json, and restored the next time you open the panel.

Fallback when things fail: since no environment build is involved, most issues come from the data itself (see Section 9). If you suspect out-of-memory on the GPU, turn off True 3D (use the default 2D+Z stitch), or reduce batch size / image size and retry.

5. Interface Guide

The panel opens with a short blue note describing its purpose. Below is a scrollable area with three sections: common settings, ① Train, and ② Infer. At the very bottom are a green result-status label and a read-only log window that shows Cellpose epochs, progress, and any error messages in real time.

Common settings (Models folder)

• Models folder: text field + … browse button. Where models are saved and listed; default C:\CellposeModels.
• Refresh channels / MultiROIs / models: rescans the current Dragonfly scene for image Channels and MultiROIs, and refreshes the model list from the models folder.

① Train / fine-tune

• Image Channel: dropdown; the image Channel used as training input.
• MultiROI (labels): dropdown; the ground-truth MultiROI (each label = one object).
• Orientation: dropdown, XY / XZ / YZ, default XY.
• Slice index: spin box; the slice used as a training example in that orientation; range adapts to the Channel's size, defaulting to the middle slice.
• Add pair / Clear pairs: add the current (Channel + MultiROI + slice) to the training set, or clear it; the "Training pairs: N" label shows how many are queued.
• Base model: dropdown, Cellpose-SAM (default), cyto3, nuclei, or (custom path...).
• Custom base path: text field + … button; used only when Base model = (custom path...), to continue fine-tuning a previously trained model.
• Epochs: spin box, range 1–5000, default 100.
• Learning rate: text field, default 1e-05.
• Batch size: spin box, range 1–64, default 1.
• Diameter: text field; blank or 0 means auto (Cellpose-SAM ignores it).
• New model name: text field; blank auto-generates a timestamped name.
• Train: blue button; starts training on a background worker thread (the UI stays responsive).

② Infer (publish a MultiROI)

• Model: dropdown listing every model in the models folder (name + file size in MB), with a Refresh models button beside it.
• Image Channel: dropdown; the full image Channel to segment.
• Stitch threshold (Z): text field, default 0.3; stitches the per-slice 2D results into Z-consistent 3D objects.
• Flow threshold: text field, default 0.4.
• Cellprob threshold: text field, default 0.0.
• Diameter: text field; blank or 0 means auto.
• True 3D (do_3D) instead of 2D+stitch: checkbox, default off; when on, uses true 3D segmentation instead of 2D-per-slice + Z stitch.
• Result title: text field; blank auto-names the resulting MultiROI.
• Infer -> publish MultiROI: green button; runs inference and publishes the result into the scene.

6. Step-by-Step Usage

Workflow A: Train / fine-tune a model

Input requirements: at least one image Channel in the scene, plus a MultiROI that labels objects on the corresponding slice(s) of that Channel (each label = one object).

1. Open the panel and click Refresh channels / MultiROIs / models to load the current scene objects.

2. (Optional) Set the Models folder to where you want models saved.

3. In ① Train, select the Image Channel and the MultiROI (labels).

4. Choose an Orientation and Slice index — make sure that slice actually contains labeled objects.

5. Click Add pair to queue that pair; repeat for each labeled slice (across orientations/indices as needed). The "Training pairs" count should increase.

6. Choose a Base model (use the default Cellpose-SAM for a first training; pick (custom path...) and a path to continue fine-tuning an existing custom model).

7. Set Epochs, Learning rate, Batch size, and a New model name (blank = auto timestamp).

8. Click Train. The log shows per-epoch progress; when done, the new model is saved to the Models folder and appears automatically in the inference dropdown.

If a queued pair has no labels on its chosen slice, it is skipped automatically during training; if all pairs lack labels, training fails with a message. Verify the orientation and slice index.

Workflow B: Infer with a model and publish a MultiROI

Input requirements: at least one model in the Models folder (trained here, or imported via a custom path), plus an image Channel to segment.

1. In ② Infer, click Refresh models and select a model from the dropdown.

2. Select the Image Channel to segment.

3. Set Stitch threshold (Z), Flow threshold, Cellprob threshold, and (optional) Diameter.

4. For true 3D segmentation, tick True 3D; otherwise keep the default 2D-per-slice + Z stitch.

5. (Optional) Enter a name in Result title for the resulting MultiROI.

6. Click Infer -> publish MultiROI. The plugin segments slice by slice, stitches through Z, and publishes the detected objects as a new MultiROI; the log reports the object count.

7. Parameter Reference

Training parameters (① Train tab):

Inference parameters (② Infer tab):

The inference batch size is auto-optimized by the plugin via CellposeHelper.findOptimizedBatchSizeForCellpose to fit available GPU memory — no manual setting needed; training uses a fixed internal weight decay of 0.1.

8. Outputs

Training output: a new Cellpose model file saved into the Models folder (named as you specified, or auto-generated as cellpose_custom_<timestamp>). When training finishes, the plugin refreshes the Infer model dropdown so the new model is immediately selectable. The list is sorted by modification time and shows each model's name and file size (MB).

Inference output: a new MultiROI object published back into the current Dragonfly scene. It is aligned to the source image Channel's grid (matching geometry, spacing, and origin), with one MultiROI label per detected object. It is built via Dragonfly's CellposeHelper by default; if that path is unavailable, the plugin completes automatically with a fallback (label volume → Channel → MultiROI).

How to view: after publishing, the MultiROI appears in Dragonfly's object tree with the name you set as Result title, or the auto name Cellpose_<model name>. You can display, color, and further measure/analyze it in 2D slice and 3D views like any other MultiROI. The panel's log confirms with a line like "Published MultiROI '...' with N object(s)."

9. FAQ & Troubleshooting

Q: I can't find "Train Custom Model: Cellpose..." in the menu.

A: Make sure you ticked this plugin in the installer (it is OFF by default) and fully restarted Dragonfly afterward; menus are scanned only at startup. You can also check its state in Developer ▸ Prototype Labs... ▸ Menu Item Manager. Confirm you are on Dragonfly 2027.1.

Q: Training reports "All pairs had 0 labels on the chosen slices."

A: The queued pairs contain no MultiROI labels on the chosen orientation/slice. Verify the Orientation and Slice index so you land on a slice that truly has annotations, re-Add the pair, and train again.

Q: Inference reports "Cellpose found no objects."

A: Try lowering the Cellprob threshold, entering an explicit Diameter, or using a model that fits your data better; if needed, add more training examples or epochs and retrain.

Q: Training/inference is slow or reports out of memory.

A: Training and inference use an NVIDIA GPU automatically when present; without a GPU, CPU fallback is notably slower. If the GPU runs out of memory, keep True 3D unchecked for inference (use the default 2D+Z stitch), and reduce Batch size or use smaller slices for training.

Q: My Channel or MultiROI isn't in the dropdown.

A: Load the data in Dragonfly first, then click Refresh channels / MultiROIs / models to rescan the scene.

Q: My trained model doesn't show in the inference list.

A: Make sure the Infer tab's Models folder points to the same directory you trained into, then click Refresh models. The list ignores non-model files such as .json / .txt / .npy.

10. Notes & Known Limitations

• Dragonfly 2027.1 only: depends on its bundled Cellpose-SAM and CellposeHelper.
• Training examples are 2D slices: each pair takes one 2D slice (which may come from different orientations/indices); Cellpose fine-tunes on these 2D images.
• MultiROI labels map 1:1 to objects: each MultiROI label is treated as one distinct object (instance).
• Training runs in Dragonfly's process: training and inference share the Dragonfly process; avoid other memory/VRAM-heavy operations while they run. The UI stays responsive on a background thread.
• Cellpose-SAM is diameter/channel-agnostic: Diameter mainly targets cyto-family base models and is ignored when Cellpose-SAM is selected.
• Inference defaults to 2D-per-slice + Z stitch: the Stitch threshold keeps object labels consistent through Z; True 3D is an optional mode.
• GPU is an optional accelerator: it runs without a GPU, just more slowly.

11. References

• Cellpose open-source project (BSD license): https://github.com/MouseLand/cellpose
• Cellpose official documentation: https://cellpose.readthedocs.io
• Dragonfly 2027.1's bundled Cellpose-SAM feature and CellposeHelper (see Dragonfly's own Help)
• Full Package install & enable instructions: the packaged README.md and the installer dialog