CellFocus Volume Crop & QC（细胞体积裁剪与质检）

CellFocus Volume Crop & QC - User Manual

Dragonfly Prototype Apps · CellFocus Volume Crop & QC...

版本 Version 1.0 · 2026-08-02

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

在体积电镜（SBF-SEM 等）图像栈中找到细胞，裁剪到它的三维包围盒，并给出足以判断这次裁剪是否可信的质检信息。

裁剪本质上是一次平移。 因此插件会明确返回并在发布时应用新的 origin，让每个体素仍然位于其真实空间位置，裁剪之后所做的任何测量依然成立。若当前 Dragonfly 版本无法设置 origin，插件会在发布时明确警告并给出偏移量——绝不悄悄发布一个被挪动过的对象。

逐层重新居中会破坏几何关系。 该模式为深度学习训练帧准备，它独立平移每一层，因此层与层之间的空间关系被破坏，输出上的任何三维测量都不再成立。它绝非默认选项，会保存每层的 dx/dy 以便撤销，并在运行之前就给出警告。

2. 适用场景

• 体积电镜数据在进入分割或深度学习流程前的裁剪与瘦身。
• 快速判断一个图像栈中哪些层存在充电、失焦或空白。
• 为深度学习准备居中的训练帧（需明确接受其破坏层间几何关系）。

3. 安装与启用

1. 安装 Prototype Apps 完整包（或在 App Store 中勾选本插件）。

2. 本插件默认未启用，请在 App Store 或菜单项管理器中启用。

3. 完全重启 Dragonfly（插件只在启动时被发现）。

4. 运行环境与首次配置

无需任何安装或配置。 完全运行在 Dragonfly 自带的 Python 中，使用其已附带的 NumPy 与 SciPy。不联网、不下载、不需要 GPU、不创建虚拟环境。

面板顶部会显示当前 Dragonfly 版本是否支持发布通道、发布 ROI 以及设置 origin。

5. 界面说明

1. 输入

选择通道（只列出已发布对象）与时间步；显示形状、三轴间距与 origin。

2. 标定与预处理

细胞极性（亮/暗）、平滑 sigma、闭运算半径。预处理只作用于工作副本，绝不修改输入对象。

3. 参数

最小/最大细胞面积占比、最小对比度、裁剪边距、异常灵敏度 k、裁剪方式，以及是否将背景置零。

4. 预览与质检

在降采样数据上快速运行，显示包围盒与保留比例。不发布任何对象，也不启用导出按钮。

5. 运行

全分辨率运行，可随时取消。

6. 结果与导出

发布裁剪后的通道或细胞掩膜 ROI；导出逐层表格（CSV）与完整结果（JSON，含每层 dx/dy）。

6. 使用步骤

1. 第 1 步选择通道。

2. 第 2 步确认细胞极性。

3. 第 4 步先跑预览，确认包围盒合理、没有大量异常层。

4. 第 5 步全分辨率运行。

5. 第 6 步发布或导出。

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

• 提示某些层没有检测到细胞 —— 若这些层确实在细胞范围之外，属于正常现象；若不是，请检查细胞极性与最小对比度。
• 发布时出现 origin 警告 —— 当前 Dragonfly 版本无法设置对象 origin，发布出来的裁剪会位于源对象的位置，警告中给出了具体偏移量。
• 包围盒几乎等于整个体积 —— 通常是空白层被误分割成大块「细胞」；降低最大面积占比或提高最小对比度。

10. 注意事项与已知限制

• 整卷读入内存；超大体积请先用预览确定参数。
• 输入必须是已发布的通道。
• 发布始终是第 6 步的显式操作，预览与运行都不会发布任何对象。
• 逐层重新居中后的数据不可用于任何三维测量。

11. 参考资料

工作流参考 Hermine-K/amira-sbfsem-cell-mask（MIT）：https://github.com/Hermine-K/amira-sbfsem-cell-mask ——未复制其源代码，运行时不需要 Amira 或 Hx API。阈值方法：N. Otsu, IEEE Trans. SMC 9(1), 1979。

Part II English Manual

Contents

1. Introduction

2. Use cases

3. Installation & enabling

4. Runtime environment & first-run setup

5. Interface

6. How to use

7. Parameters

8. Output

9. FAQ & troubleshooting

10. Notes & known limitations

11. References

1. Introduction

Finds the cell in a volume-EM (SBF-SEM and similar) stack, crops to its 3-D bounding box, and reports enough QC to judge whether that crop is trustworthy.

Cropping is a translation. The plugin therefore returns the new origin and applies it when publishing, so every voxel keeps its true position in space and any measurement made after the crop is still valid. If this Dragonfly build cannot set an origin, the plugin warns clearly at publish time and states the resulting offset — it never quietly publishes a displaced object.

Per-slice re-centring destroys geometry. That mode exists for deep-learning training frames; it translates each slice independently, so the spatial relationship between slices is destroyed and no 3-D measurement on the output is meaningful. It is never the default, it saves every dx/dy so it can be undone, and it warns before the run, not only after.

2. Use cases

• Cropping and shrinking volume-EM data before segmentation or deep learning.
• Seeing at a glance which slices in a stack are charged, out of focus or blank.
• Preparing centred training frames for deep learning, having accepted that it breaks the geometry between slices.

3. Installation & enabling

1. Install the Prototype Apps package (or tick this plugin in the App Store).

2. This plugin is disabled by default — enable it in the App Store or the Menu Item Manager.

3. Restart Dragonfly completely (plugins are discovered at startup only).

4. Runtime environment & first-run setup

Nothing to install or configure. It runs entirely in Dragonfly's own Python using the NumPy and SciPy it already ships. No internet, no download, no GPU, no virtual environment.

The header reports whether this build can publish Channels, publish ROIs and set an origin.

5. Interface

1. Inputs

Choose the Channel (published objects only) and timestep; shape, spacing and origin are shown.

2. Calibration & Preprocessing

Cell polarity, smoothing sigma and closing radius. Preprocessing acts on a working copy and never modifies the input object.

3. Parameters

Minimum and maximum cell area fraction, minimum contrast, crop margin, anomaly sensitivity k, crop mode, and whether to zero the background.

4. Preview & QC

A fast pass on downsampled data showing the box and the fraction kept. Nothing is published and the export buttons stay disabled.

5. Run

Full resolution, cancellable at any time.

6. Results & Export

Publish the cropped Channel or the cell-mask ROI; export the per-slice table (CSV) and the full result (JSON, including per-slice dx/dy).

6. How to use

1. Pick the Channel in step 1.

2. Confirm the cell polarity in step 2.

3. Run a preview in step 4 and check the box looks sensible with few anomalous slices.

4. Run at full resolution in step 5.

5. Publish or export in step 6.

7. Parameters

8. Output

9. FAQ & troubleshooting

• Some slices report no cell — normal if they lie outside the cell; otherwise check the polarity and the minimum contrast.
• An origin warning at publish time — this build cannot set an object origin, so the published crop sits at the source's position; the warning states the exact offset.
• The box is almost the whole volume — usually blank slices mis-segmented into a large "cell"; lower the maximum area fraction or raise the minimum contrast.

10. Notes & known limitations

• The whole volume is read into memory; use the preview to settle parameters on large data.
• Inputs must be published Channels.
• Publishing is always an explicit step-6 action; neither preview nor run publishes anything.
• Data produced by per-slice re-centring must not be used for any 3-D measurement.

11. References

The workflow follows Hermine-K/amira-sbfsem-cell-mask (MIT): https://github.com/Hermine-K/amira-sbfsem-cell-mask — no source was copied and no Amira or Hx API is required. Thresholding: N. Otsu, IEEE Trans. SMC 9(1), 1979.