Full Workflow using Cellpose（Cellpose 全流程向导）

Full Workflow using Cellpose - User Manual

Dragonfly Prototype Apps · Full Workflow using Cellpose...

版本 Version 1.0 · 2026-09-23

第一部分 中文手册

目录

1. 简介

2. 第一步：Preview and Configure（可选）

3. 第二步：全体积分割

4. 第三步：计算测量

5. 第四步：生成报告

6. 无人值守运行全部步骤

7. 环境需求

1. 简介

Dragonfly 本身就带了 Cellpose-SAM 模型，但要用好它需要在多个面板之间来回：调参数、跑分割、算测量、再做报告。本插件把这条链路做成一个四步向导，每步一个 tab，按顺序走完即可。

它不训练模型，也不需要虚拟环境 —— 直接调用 Dragonfly 自带的 cellpose。想训练自定义模型请用 Train Custom Model: Cellpose 插件。

本功能由第三方（Prototype Labs / Prototype Apps）提供，并非 Dragonfly 官方开发，Dragonfly 也不提供技术支持；使用风险由使用者自行承担。

2. 第一步：Preview and Configure（可选）

目的：用几秒钟的小体积试参数，而不是拿整个体积去赌。

本 tab 分三栏：左栏 = 全部设置（图像选择、子体范围、Cellpose 参数、运行列表、进度条），中栏 = 原图预览（从上到下 xy / yz / xz），右栏 = 分割结果预览（同样三个视图）。中右两栏是各自独立的面板，但共用同一套缩放/平移状态，所以永远对齐。

1. 在顶部下拉框选一个已发布的 image Channel（旁边“↻ 刷新”重新枚举）。

2. 设置 N（默认 100）。子体默认取自体心；用 Offset Z/Y/X 把它移到你关心的区域。下面一行实时显示子体的坐标范围、体素数，以及占全体积的百分比。

3. 点“Load preview”。中栏从上到下是 xy / yz / xz 三个 2D 视图：整幅原图压暗显示，子体区域全亮并用虚线框标出，一眼就知道待测试的是哪一块。

4. 选一个参数预设（或手工改 diameter / flow threshold / cell probability / Z stitch threshold / 是否真 3D / 是否用 GPU），点“▶ Run this preset on the sub-volume”。

5. 若想一次比较所有预设，勾选 “Compute all presets”：程序会依次跑完每个预设，每跑完一个就加入下方运行列表；下方进度条显示“第几个预设 / 第几张切片”，随时可点“Stop”停止（会连同排队中的预设一起取消）。

6. 结果出现在右栏同样的三个视图里，各 label 用不同颜色叠加在原图上。

7. 每跑一次就在运行列表里加一行（参数摘要 + label 数 + 实际耗时）。点任意一行即可切回那次结果做对比。

8. 选定满意的一行，点“Use this preset in step 2 →”，参数与耗时基准一起带到第二步。

中栏与右栏为什么能完全同步

左右两侧渲染的是同一坐标系里的同一张图，右侧只是在子体范围内额外叠加了 label 颜色。因此两边尺寸必然相同，缩放与平移也就精确同步：滚轮缩放（以光标位置为中心）、拖拽平移、双击复位，也可以点“Reset zoom/pan”。缩放对六个视图统一生效；平移按行同步 —— xy / yz / xz 三个平面的范围与轴向不同，共用一个平移量没有意义。

3. 第二步：全体积分割

这一步故意不显示图像：整体积分割可能很久，你此刻需要的是参数确认与时间预期，而不是再看一遍图。

外推按体素数线性进行：do_3D=False 时成本≈每片面积×片数；do_3D=True 时 cellpose 同样要走完整个网格 —— 两者都与体素数成正比。估计不含模型加载时间（那时模型已缓存），这也正是估计必须来自一次真实运行而不是公式的原因；它假设硬件与参数不变。

点“▶ Segment the full volume”，确认框会列出图像名、参数与预计耗时。运行期间 Dragonfly 仍可使用（推理在后台线程执行），进度条按切片推进，可随时“Cancel”（在当前切片结束后停止）。完成后结果以 MultiROI 发布，命名为「原图名 - Cellpose」；面板不会自动跳走 —— 只有无人值守的运行会切换 tab，用来跟随正在工作的那一步。

4. 第三步：计算测量

这里用的是 Dragonfly 自己的逐 label 测量引擎 —— 就是 Compute measurements 对话框背后那一套，因此可选项与 Dragonfly 完全一致（Basic Measurements、2D 测量、Radiomics 等，取决于对象类型与你的授权）。

1. 选择 MultiROI（第二步产生的那个会自动选中）。

2. 在树里勾选要计算的测量。“Select the common ones”会勾上常用的一组（体素数、体积、等效球径、表面积、球形度、质心）。

3. 点“▶ Compute measurements”。结果写成该对象的 measurement，因此在 Dragonfly 的对象属性里、以及第四步的报告里都能直接看到。

测量计算由 Dragonfly 在界面线程执行，测量项多或 label 数量大时窗口可能短时间不刷新，属正常现象。

5. 第四步：生成报告

第四步直接嵌入已安装的 “Multi-ROI 导出”（Multi-ROI Export）插件的“报告”选项卡（它取代了已停用的 “Create a Report from MultiROI”），而不是复制一份报告代码。嵌入的是只有“报告”一个选项卡的窗口，自带 Multi-ROI 选择框、时间步和“刷新”。好处是那个选项卡的任何改进（例如“分享到网页”生成链接与二维码、临时链接）在这里立刻可用，两边行为永远一致。

选择第二步产生的 MultiROI，选输出格式（Excel / PowerPoint / Word / PDF）与是否包含 3D 截图，生成报告；截图结束后，布局、可见性、着色、图例和相机都会恢复原状。需要分享时展开下方的“把报告分享到网页”或“临时链接”。若该插件未安装或被禁用，本 tab 会明确说明，请在应用商店中启用后重新打开本窗口。

6. 无人值守运行全部步骤

第一步的 tab 上还有一个按钮：“按当前设置执行全部步骤”。它会依次跑完向导的各步 —— 载入预览子体积、在其上试运行 Cellpose-SAM、把选中的预设带到第二步、分割整个体积并发布为 MultiROI、再在该 MultiROI 上计算已勾选的测量项 —— 每一步都使用它自己的 tab 在你按下按钮那一刻显示的设置。面板会自动切到正在运行的那一步，扫一眼就知道进行到哪里；按钮下方的一行小结会给出总耗时和产出了什么。

其中三步比较耗时或会写入会话，因此在按钮旁各有一个复选框，默认全部勾选：在子体积上试运行（第一步）、分割整个体积并发布（第二步）、计算测量（第三步）。未勾选的步骤会明确写入日志“已跳过”，不会被悄悄略过。按下这个按钮本身就等于对整体积分割的确认，因此不再弹出平时那个确认对话框。

第四步（报告）刻意不在运行范围内。它是另一个插件的面板，导出时会弹出文件对话框，无人值守的运行无法应答；请在运行结束后手动生成报告。

若勾选了“Compute all presets”，试运行会把所有预设都跑一遍 —— 此时无人值守的运行不会替你在它们之间做选择：它会说明原因，第二步回退到第一步的参数输入框，而不是悄悄拿最后跑完的那个预设去分割整个体积。

所有 tab 从一开始就保持可用可编辑，运行之前也一样：只有先把每个 tab 都设好，无人值守的运行才值得放手去跑。输入尚不存在的步骤会在自己的按钮上拒绝执行并指出应先运行哪一步 —— 例如没有选中 MultiROI 时点“Compute measurements”，它会提示先运行第二步，而不是毫无反应。

7. 环境需求

无需虚拟环境、无需管理员权限。使用 Dragonfly 自带的 cellpose 与 Cellpose-SAM 模型；首次运行时 cellpose 会下载一次约 1 GB 的 cpsam 权重（之后可离线使用）。有 CUDA 显卡会快很多，但不是必需 —— 可在参数中取消勾选 GPU 以纯 CPU 运行（会明显更慢）。需要会话中至少有一个已发布的 image Channel。

Part II English Manual

Contents

1. Introduction

2. Step 1: Preview and Configure (optional)

3. Step 2: Segment the full volume

4. Step 3: Compute measurements

5. Step 4: Build the report

6. Run everything unattended

7. Requirements

1. Introduction

Dragonfly already ships the Cellpose-SAM model, but getting value out of it means moving between several panels: tune parameters, run the segmentation, compute measurements, build a report. This plugin turns that chain into one four-step wizard, a tab per step, meant to be walked in order.

It does not train models and needs no virtual environment - it calls the cellpose that Dragonfly bundles. To train a custom model, use the Train Custom Model: Cellpose plugin.

This feature is provided by a third party (Prototype Labs / Prototype Apps), not officially developed or supported by Dragonfly. Use at your own risk.

2. Step 1: Preview and Configure (optional)

The point: spend seconds on a small volume instead of gambling the whole one.

The tab is three panes: left = all settings (image picker, sub-volume, Cellpose parameters, the run list, the progress bar), middle = the original image (xy / yz / xz top to bottom) and right = the segmentation (the same three views). The two image panes are independent widgets that share one zoom/pan state, so they are always aligned.

1. Pick a PUBLISHED image Channel in the drop-down ("↻ Refresh" re-enumerates).

2. Set N (default 100). The sub-volume is taken from the CENTRE of the volume; move it with the Z/Y/X offsets. The line underneath always states the sub-volume's coordinate ranges, its voxel count, and what percentage of the full volume that is.

3. Press "Load preview". The MIDDLE pane stacks the xy / yz / xz 2D views: the whole image dimmed, the sub-volume at full brightness inside a dashed box, so it is obvious which part is being tested.

4. Choose a parameter preset (or edit diameter / flow threshold / cell probability / Z stitch threshold / true-3D / GPU by hand) and press "▶ Run this preset on the sub-volume".

5. To compare every preset in one go, tick "Compute all presets": each preset runs in turn and joins the run list as it finishes, the progress bar reports preset i/N and slice j/K, and "Stop" cancels the current run along with the rest of the queue.

6. The result appears in the RIGHT pane, in the same three views, with each label colour-coded over the image.

7. Each run adds a line to the run list (parameter summary + label count + measured time). Click any line to bring that result back for comparison.

8. Select the line you like and press "Use this preset in step 2 →"; the parameters and the timing baseline both carry over.

Why the two sides stay perfectly in step

Both sides render the SAME picture in the SAME coordinate system; the right one merely blends label colours inside the sub-volume. So they are necessarily identical in size, and zoom and pan are exactly synchronised: wheel to zoom (around the cursor), drag to pan, double-click to reset, or press "Reset zoom/pan". Zoom applies to all six views; panning is shared per row, because xy, yz and xz have different extents and axes and a common pan would be meaningless.

3. Step 2: Segment the full volume

This step deliberately shows no images: a full-volume run can take a long time, and what you need at this moment is confirmation of the parameters and an expectation of the duration, not another look at the data.

The extrapolation is linear in voxels: with do_3D=False the cost is per-slice area x slices, and with do_3D=True cellpose still walks the whole grid - both are proportional to the voxel count. It excludes model loading (cached by then), which is exactly why the estimate must come from a REAL run rather than a formula, and it assumes the same hardware and parameters.

Press "▶ Segment the full volume"; the confirmation lists the image, the parameters and the estimate. Dragonfly stays usable while it runs (inference is on a worker thread), the progress bar advances per slice, and "Cancel" stops after the current slice. The result is published as a MultiROI named "<image> - Cellpose", and the panel stays where you are - only an unattended run moves the tab, so it follows the step it is working on.

4. Step 3: Compute measurements

This uses Dragonfly's own per-label measurement engine - the one behind the Compute measurements dialog - so the choices are exactly Dragonfly's (Basic Measurements, 2D measurements, Radiomics and so on, depending on the object and your licence).

1. Pick the MultiROI (the one from step 2 is selected automatically).

2. Tick the measurements to compute. "Select the common ones" ticks a sensible default set (voxel count, volume, equivalent spherical diameter, surface area, sphericity, centroid).

3. Press "▶ Compute measurements". The results become measurements ON the object, so they show up in Dragonfly's object properties and in the step-4 report.

Dragonfly performs this computation on the UI thread, so with many measurements or many labels the window may not repaint for a while. That is normal.

5. Step 4: Build the report

Step 4 embeds the Report tab of the installed "Multi-ROI Export" plugin (which replaced the retired "Create a Report from MultiROI") rather than carrying a second copy of the report code. It is embedded as a window with that one tab, bringing its own Multi-ROI picker, time step and Refresh. Any improvement there - the share-on-the-web link and QR code, the temporary link - is available here immediately, and the two can never drift apart.

Pick the MultiROI from step 2, choose the output format (Excel / PowerPoint / Word / PDF) and whether to include 3D screenshots, and generate; after the screenshots the layout, the visibility, the colouring, the legends and the camera are put back as they were. To share it, open "Share the report on the web" or "Temporary link" below the report. If the plugin is not installed or is disabled, this tab says so; enable it in the App Store and reopen this window.

6. Run everything unattended

Tab 1 carries one more button: "Execute All Steps with Current Settings". It runs the wizard's steps in order - load the preview sub-volume, rehearse Cellpose-SAM on it, carry the chosen preset into step 2, segment the WHOLE volume and publish it as a MultiROI, then compute the ticked measurements on that MultiROI - each step with whatever ITS OWN tab shows at the moment you press it. The panel follows the step that is working, so a glance says where the run is, and the one-line summary underneath the button reports the elapsed time and what was produced.

Three of those steps cost real time or write to the session, so each is a check box beside the button, all ticked by default: rehearse on the sub-volume (step 1), segment the full volume and publish it (step 2), compute the measurements (step 3). An unticked step is written into the log as skipped - it is never passed over silently. Pressing this button IS the confirmation for the full-volume run, so the usual confirmation dialog is not asked.

Step 4 (Report) is deliberately not part of the run. It is another plugin's panel and its export opens a file dialog, which an unattended run cannot answer; generate the report by hand when the run is done.

With "Compute all presets" ticked, the rehearsal runs every preset - and the run will then NOT choose between them. It says so and step 2 falls back to the parameter fields of step 1, rather than quietly committing the whole volume to whichever preset happened to finish last.

Every tab is open and editable from the start, including before anything has run: an unattended run is only worth leaving if you could set every tab first. A step whose input does not exist yet refuses at its own button and names the step that has to run first - for example, "Compute measurements" with no MultiROI selected says to run step 2 first instead of doing nothing at all.

7. Requirements

No venv and no admin rights. It uses the cellpose package and Cellpose-SAM model Dragonfly bundles; on FIRST use cellpose downloads the ~1 GB cpsam weights once (offline afterwards). A CUDA GPU makes it much faster but is not required - untick GPU to run on the CPU (noticeably slower). Needs at least one PUBLISHED image Channel in the session.