深度去噪 (CSBDeep / Noise2Void) 插件用户手册

Deep Denoising (CSBDeep / Noise2Void) - User Manual

Dragonfly Prototype Apps · Deep Denoising (CSBDeep / Noise2Void)...

版本 Version 1.0 · 2026-07-09

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

深度去噪 (CSBDeep / Noise2Void) 是一款 Dragonfly 插件,用于对图像做内容感知修复(去噪)。它基于 TensorFlow 2 深度学习框架,提供两种互补的算法:

• CARE(来自 csbdeep,监督式):需要成对的"含噪"与"干净"图像 Channel。模型学习从低质量图像重建高质量参考图像,修复能力更强。
• Noise2Void (N2V)(来自 n2v,自监督):只需含噪图像,不需要任何干净参考。当你没有高质量参考图像时,可以仅凭含噪数据训练出一个去噪模型。

工作方式分两步:在 Train(训练) 分页中添加一个或多个训练样本并训练一个模型;在 Apply(应用) 分页中选择一个已保存的模型和一个 Channel 进行预测。去噪后的结果会作为一个全新的 Channel 发布回 Dragonfly 场景,直接可用于测量、分割与可视化。

底层引擎与算法:

• 深度学习框架:TensorFlow 2(Keras)。
• 监督式内容感知修复引擎:csbdeep(CARE)。
• 自监督去噪引擎:n2v(Noise2Void)。n2v 0.3.x 系列锁定 TensorFlow 2。
• 辅助库:numpy、tifffile。

架构要点:所有繁重的机器学习工作(TensorFlow + csbdeep + n2v)都运行在插件独立的 Python 虚拟环境(venv)中,通过子进程 + JSON 文件通信调用,绝不进入 Dragonfly 自带的 Python。这样既隔离了依赖冲突,也避免了污染 Dragonfly 运行时。

许可证要点:本插件是 CSBDeep 与 Noise2Void 两个开源项目的封装。TensorFlow、csbdeep、n2v、numpy、tifffile 等第三方库均在首次"Setup Environment"时从 PyPI 下载并安装到插件自己的虚拟环境中,各自遵循其上游许可证。使用前请遵循相应项目的许可条款,学术使用请引用相应论文。

2. 适用场景

只要在测量或分割之前需要降低图像噪声,本插件都能派上用场。典型场景包括:

• 低剂量或快速采集的 CT:为缩短扫描时间或降低辐射剂量而采集的图像,信噪比较低,去噪后边界更清晰、分割更稳定。
• 含噪的显微镜与荧光体数据:活细胞成像、光片显微镜等在低曝光下采集的三维数据。
• 材料科学与工业扫描:X 射线或电镜数据中的斑点噪声、颗粒噪声。
• 任何后续定量分析的预处理步骤:去噪往往能显著提升后续阈值分割、连通域分析和形态测量的可靠性。

如何在两种算法之间选择:

• 当你没有干净的参考图像时,使用 Noise2Void:它仅凭含噪数据本身即可自监督地学习去噪,无需任何配对标注。
• 当你拥有配对的高质量参考图像(例如同一样品的高剂量/高曝光采集,或低噪-高噪对)时,使用 CARE:监督式训练通常能获得更强的修复效果。

插件对 2D 与 3D 数据都支持:若导出的体数据 z 方向长度为 1(单层),会被当作 2D(YX)处理;否则按真正的三维体数据(ZYX)处理。

3. 安装与启用

本插件随 Prototype Apps 完整安装包(Full Package) 分发。安装步骤如下:

1. 将完整安装包 zip 解压到一个较短的目录(例如 C:\PL\),避免路径过长(见下方提示)。

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

3. 在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),并在列表中勾选 "Deep Denoising (CSBDeep / Noise2Void)"。注意:所有插件默认未勾选(关闭),需要手动勾选启用。

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

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

重启后,插件出现在菜单:Prototype Apps ▸ Deep Denoising (CSBDeep / Noise2Void)...(位于 *Filtering & Restoration*(滤波与修复)分组下)。点击后会打开一个可浮动的面板窗口。

以后修改勾选:最方便的方式是在 Dragonfly 内操作。打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部的 "Prototype Apps (Full Package)" 列表中,每个应用都有一个复选框:勾选=部署,取消=移除菜单项。修改后重启 Dragonfly 生效。停用从不删除插件已搭建的环境(venv),重新启用立即可用。

卸载:双击 `Uninstall_FullPackage.bat`(也保存在安装器目录中)。它会移除所有 Full Package 菜单项、插件与中央存储,但保留 Prototype Labs 核心以及每个插件已搭建的环境(venv / 下载内容)——结束时会列出这些路径,如需回收磁盘空间可手动删除。

路径过长(错误 0x80010135):Windows 单个完整路径上限为 260 字符。请勿在资源管理器里拖动/复制解压出来的文件夹,直接运行 Install_FullPackage.bat 即可(它会安装到很短的路径)。并请把压缩包解压到很短的目录(如 C:\PL\),不要放在很深的"下载\<压缩包名>\…"或 OneDrive 重定向的桌面下。

4. 运行环境与首次配置

本插件属于 venv-in-code 类型:安装时不会下载任何机器学习依赖。首次使用时,你需要在面板的 Setup(设置) 分页点击 Setup Environment 按钮来搭建运行环境。

Setup Environment 具体做什么:

1. 使用一个"基础 Python"创建一个专用的虚拟环境(venv)。默认使用当前 Dragonfly 自带的 `Python_env\python.exe`——它是一套完整的 CPython,自带 venv 与 pip,因此无需另外安装 Python。

2. 在该 venv 中升级 pip / setuptools / wheel。

3. 从 PyPI 安装完整依赖栈:tensorflow、csbdeep、n2v、numpy、tifffile。

4. 运行一次"冒烟测试":导入 tensorflow / csbdeep / n2v 并报告是否检测到 GPU。

5. 成功后,venv 的 python 路径会自动填入 "CSBDeep venv python" 字段并保存到配置。

下载体积:首次搭建需从网络下载 TensorFlow 2 + csbdeep + n2v(合计数 GB),耗时数分钟到十几分钟不等(取决于网速)。

联网 / GPU 要求:

• 需要联网:所有依赖从 PyPI 解析下载(与 PyTorch 不同,TensorFlow 的 PyPI wheel 直接处理 GPU,无需额外的 CUDA wheel 索引)。
• 强烈建议配备 NVIDIA GPU(并安装匹配的 CUDA/cuDNN),以获得可用的训练/预测速度。没有 GPU 也能运行,但训练会明显更慢。

环境安装到哪里:venv 建在插件已安装代码目录下的 venv 子文件夹中,即 %LOCALAPPDATA%\comet\<Dragonfly版本>\pythonUserExtensions\GenericMenuItems\CSBDeep\venv。插件配置(含 venv python 路径)保存在同一代码目录的 csbdeep_config.json,并同时备份到 %LOCALAPPDATA%\CSBDeepDenoising\config.json。

Setup 分页的其他字段:

• CSBDeep venv python:由 Setup Environment 自动填写,一般无需手动改。
• Base Python (build):构建 venv 用的基础 Python。留空 = 使用当前 Dragonfly 自带的 python.exe(推荐);也可以填一个路径或形如 py -3.10 的命令来覆盖。
• Run mode:windows(默认,已发布)或 wsl(预留,当前仅 windows 模式随包发布)。

失败时的替代方案:如果用 Dragonfly 自带 Python 构建 venv 失败(例如提示 venv 或 pip 不可用),在 "Base Python (build)" 字段填入另一套 CPython 3.9+(自带标准库 venv + pip)的路径,例如 C:\Python310\python.exe,再点一次 Setup Environment。若已有半成品 venv(有 python.exe 但 pip 不可用),Setup 会自动检测并重建它。

5. 界面说明

面板顶部是一段蓝色说明文字,概述插件功能。中部是三个分页 Setup / Train / Apply;底部依次是一行绿色的结果状态栏和一个只读的运行日志框(显示导出、训练、预测等实时进度)。

5.1 Setup 分页

用于搭建运行环境。控件见下:

• CSBDeep venv python(文本框):venv 的 python 路径,由 Setup Environment 填写。
• Base Python (build)(文本框):构建 venv 的基础 Python,留空=Dragonfly 自带 python。
• Run mode(下拉):windows / wsl,默认 windows。
• Setup Environment (build venv + install TensorFlow + csbdeep + n2v)(按钮):点击开始搭建环境。

5.2 Train 分页

分为四个分组,自上而下逐步完成一次训练。

Mode(模式)分组:

• Training mode(下拉):选择 Noise2Void (self-supervised, only noisy) 或 CARE (supervised, noisy + clean pairs),默认 Noise2Void。切换到 CARE 时,下面的"Clean Channel"行会自动出现;选 N2V 时则隐藏。

Workspace(工作区)分组:

• Output folder(文本框 + "…"浏览按钮):训练产物与保存的模型都会落在这里,默认 C:\CSBDeepWorkspace。
• Model name(文本框):保存的模型名称。留空则用默认名(N2V 为 n2v_model,CARE 为 care_model)。
• Refresh channels(按钮):从当前 Dragonfly 场景重新读取 Channel 列表,填充下面的下拉框。

(1) Add training cases(添加训练样本)分组:

• Noisy Channel(下拉):选择含噪的 Channel。
• Clean Channel (CARE)(下拉,仅 CARE 模式可见):选择配对的干净(高质量)Channel。
• Add case(按钮):把当前选择添加为一个训练样本(累加到内存列表)。N2V 只需含噪 Channel;CARE 需同时选好含噪与干净 Channel。
• Clear cases(按钮):清空已添加的训练样本。
• Training cases: N(标签):显示当前已添加的样本数量。

(2) Train(训练)分组:

• Patch size(数字框):训练用小块(patch)的边长,范围 16–512,步长 8,默认 64。2D 为正方形块,3D 为立方块。
• Epochs(数字框):训练轮数,范围 1–5000,默认 20。
• Steps per epoch(数字框):每轮训练步数,范围 1–100000,默认 100。
• Batch size(数字框):批大小,范围 1–512,默认 16。
• Train(蓝色按钮):导出已添加的样本并启动训练。

5.3 Apply 分页

用已保存的模型对某个 Channel 做预测(去噪)。控件见下:

• Model type(下拉):模型类型 Noise2Void 或 CARE,须与训练时一致。
• Model folder(文本框 + "…"浏览按钮):已保存模型所在的文件夹(即 …/<model_name>)。训练成功后此处会被自动预填。
• Image Channel(下拉 + Refresh 按钮):选择要去噪的图像 Channel。
• Tiles (memory; >1 splits volume)(数字框):分块数,范围 1–64,默认 1。当体数据过大导致显存/内存不足时,设为大于 1 会把体数据切块预测。
• Result title(文本框):结果 Channel 的标题。留空则自动命名为 <源Channel名>_restored。
• Apply -> publish restored Channel(绿色按钮):启动预测并把去噪结果作为新 Channel 发布。

6. 使用步骤

6.1 首次准备(仅一次)

1. 打开 Prototype Apps ▸ Deep Denoising (CSBDeep / Noise2Void)...。

2. 切到 Setup 分页,保持 "Base Python" 留空(使用 Dragonfly 自带 Python)。

3. 点击 Setup Environment,等待控制台完成安装(首次数 GB,需联网)。日志显示 "Environment ready." 即可。

6.2 训练 Noise2Void 模型(只有含噪图像)

输入要求:至少一个含噪的 Channel(无需干净参考)。

1. 切到 Train 分页,Training mode 选 Noise2Void。

2. 设置 Output folder(默认 C:\CSBDeepWorkspace)与可选的 Model name。

3. 点 Refresh channels 载入场景中的 Channel。

4. 在 Noisy Channel 选择含噪 Channel,点 Add case。可对多个含噪 Channel 重复此步累加样本。

5. 在 (2) Train 分组按需调整 Patch size / Epochs / Steps per epoch / Batch size。

6. 点 Train。日志会实时显示 "epoch X/Y, loss …" 的进度。

7. 训练结束后,结果栏显示 "Trained.",且 Apply 分页的 Model folder 会被自动预填为刚保存的模型路径。

6.3 训练 CARE 模型(含噪 + 干净配对)

输入要求:成对的含噪 Channel 与干净(高质量)Channel,且两者对齐到同一网格。

1. 在 Train 分页,Training mode 选 CARE——此时会出现 Clean Channel (CARE) 行。

2. 点 Refresh channels;在 Noisy Channel 选含噪 Channel,在 Clean Channel 选对应的干净 Channel。

3. 点 Add case 添加这一对。可重复添加多对。

4. 调整训练参数后点 Train。

6.4 应用模型去噪

输入要求:一个已保存的模型文件夹,以及一个待去噪的图像 Channel。

1. 切到 Apply 分页,Model type 选择与训练时相同的类型(N2V 或 CARE)。

2. 确认 Model folder 指向已保存模型文件夹(训练完成后通常已自动预填,也可用 "…" 浏览选择)。

3. 点 Refresh,在 Image Channel 选择要去噪的 Channel。

4. 如遇内存/显存不足,把 Tiles 调大(>1);可选地填写 Result title。

5. 点 Apply -> publish restored Channel。完成后,去噪结果作为一个新 Channel 出现在场景中。

7. 参数说明

下表列出面板中各可调参数、默认值与说明。

关于 Patch size:csbdeep / n2v 要求各轴长度可被网络下采样倍数整除,因此本插件会把你输入的值向下取整到 8 的倍数(且不小于 16)后再使用。

8. 输出结果

训练输出:一个已保存的深度学习模型,位于 <Output folder>/<model_name>/(csbdeep / n2v 的约定为 <basedir>/<name>/)。训练过程中的中间产物(导出的样本 .npy、CARE 的分块 .npz、状态与结果 JSON)保存在按时间戳命名的作业子文件夹(如 train_YYYYMMDD_HHMMSS)中。

应用输出:一个全新的 Channel,发布回当前 Dragonfly 场景。

• 该 Channel 的标题为你在 Result title 中填写的名字,留空时为 <源Channel名>_restored。
• 去噪结果复用源 Channel 的网格几何(spacing 体素间距与 origin 原点被复制过来),因此空间对齐正确,可与原图叠加比较。
• 对于被当作 2D 处理的单层数据,预测后会恢复其前导的单层 z 轴,以便重新发布到源 Channel 的 (z, y, x) 网格上。

如何查看:新 Channel 会出现在 Dragonfly 的对象列表(Object List)中,和普通 Channel 一样,可在 2D/3D 视图里显示、调整窗宽窗位、参与阈值分割与测量。建议把去噪 Channel 与原始含噪 Channel 并排或叠加对比,评估去噪效果。

9. 常见问题与故障排除

问:点击 Train 或 Apply 时提示 "venv not set. Run Setup Environment first." 怎么办?

答:说明还没有搭建运行环境。先切到 Setup 分页点击 Setup Environment,等日志显示 "Environment ready." 并且 "CSBDeep venv python" 字段被填上后,再回来训练或应用。

问:Setup Environment 失败,提示下载或安装出错?

答:多为网络问题或 TensorFlow / n2v 与当前 Python 版本不兼容。请确认能访问 PyPI(需联网);若 Dragonfly 自带 Python 构建失败,可在 Base Python (build) 填入另一套 CPython 3.9+(自带 venv + pip)的路径,例如 C:\Python310\python.exe,再重试。已存在的半成品 venv 会被自动重建。

问:训练/预测报显存不足(out of memory / OOM)或 CUDA 相关错误?

答:预测时把 Tiles 调大(>1),将体数据切块以降低单次显存占用;训练时可减小 Patch size 或 Batch size。如果日志提示找不到 GPU / CUDA,插件仍可在 CPU 上运行(更慢),或请检查 NVIDIA 驱动与匹配的 CUDA/cuDNN。

问:添加 CARE 训练样本时提示 "CARE needs a clean (high-quality) Channel too"?

答:CARE 是监督式算法,每个样本必须同时提供含噪 Channel 与配对的干净 Channel。请在出现的 Clean Channel (CARE) 行选好干净 Channel 后再点 Add case;若你没有干净参考,请改用 Noise2Void 模式。

问:点 Add case 提示 "select a noisy Channel (Refresh)"?

答:下拉框里没有可选的 Channel,或还未选择。先点 Refresh channels 载入当前场景中的 Channel,再在 Noisy Channel 里选择。

问:菜单里找不到该插件?

答:确认安装时已在列表中勾选了该插件(默认未勾选),并且安装后完全重启了 Dragonfly(菜单只在启动时扫描)。也可在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 中勾选它后再重启。

10. 注意事项与已知限制

• 首次需要联网下载数 GB 依赖(TensorFlow 2 + csbdeep + n2v),请预留时间与磁盘空间。
• GPU 强烈推荐:无 GPU 也能运行,但训练/预测会明显变慢。
• n2v 0.3.x 锁定 TensorFlow 2,并要求与之兼容的 Python 版本;若自动安装失败,可尝试用另一套匹配的 Python 作为 Base Python。
• CARE 需要成对数据且含噪与干净两个 Channel 需对齐到同一网格;N2V 只需含噪数据。
• Model type 需与训练一致:用 N2V 训练的模型必须以 N2V 类型应用,CARE 同理。
• Run mode 目前仅 windows 模式随包发布(wsl 为预留选项)。
• 大体数据预测建议使用 Tiles(>1)分块,避免内存/显存溢出。
• 去噪是对图像的估计重建:请始终将结果与原图对比,评估是否引入了不希望的平滑或伪影,再用于定量分析。

11. 参考资料

• CSBDeep(CARE / 内容感知修复)项目主页:https://github.com/CSBDeep/CSBDeep
• Noise2Void(n2v)项目主页:https://github.com/juglab/n2v
• TensorFlow 官方网站:https://www.tensorflow.org/
• CARE 论文:Weigert et al., "Content-aware image restoration: pushing the limits of fluorescence microscopy", Nature Methods, 2018.
• Noise2Void 论文:Krull et al., "Noise2Void - Learning Denoising from Single Noisy Images", CVPR, 2019.
• Prototype Apps 完整安装包安装/启用说明:随包 UserManual_用户手册.docx 与安装器目录中的 README。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation and Enabling

4. Environment and First-Run Setup

5. Interface Reference

6. Step-by-Step Usage

7. Parameter Reference

8. Output Results

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

1. Overview

Deep Denoising (CSBDeep / Noise2Void) is a Dragonfly plugin for content-aware image restoration (denoising). It is built on the TensorFlow 2 deep-learning framework and offers two complementary algorithms:

• CARE (from csbdeep, supervised): needs paired 'noisy' and 'clean' image Channels. The model learns to reconstruct the high-quality reference from the low-quality input, giving stronger restoration.
• Noise2Void (N2V) (from n2v, self-supervised): needs only the noisy image — no clean reference at all. When you have no high-quality reference, you can still train a denoiser from the noisy data alone.

The workflow has two steps: in the Train tab you add one or more training cases and train a model; in the Apply tab you pick a saved model and a Channel to predict on. The denoised result is published back into the Dragonfly scene as a brand-new Channel, ready for measurement, segmentation and visualization.

Underlying engines and algorithms:

• Deep-learning framework: TensorFlow 2 (Keras).
• Supervised content-aware restoration engine: csbdeep (CARE).
• Self-supervised denoising engine: n2v (Noise2Void). The n2v 0.3.x series pins TensorFlow 2.
• Helper libraries: numpy, tifffile.

Architecture note: all heavy machine-learning work (TensorFlow + csbdeep + n2v) runs in the plugin's dedicated Python virtual environment (venv), driven via a subprocess + JSON file IPC — never inside Dragonfly's own Python. This isolates dependencies and keeps the Dragonfly runtime clean.

Licensing note: this plugin wraps the CSBDeep and Noise2Void open-source projects. TensorFlow, csbdeep, n2v, numpy and tifffile are downloaded from PyPI into the plugin's own virtual environment on first 'Setup Environment', each under its upstream license. Please observe the respective project licenses, and cite the relevant papers for academic use.

2. Use Cases

This plugin is useful whenever image noise should be reduced before measurement or segmentation. Typical scenarios include:

• Low-dose or fast-acquisition CT: images acquired to shorten scan time or lower dose have a low SNR; denoising sharpens boundaries and stabilizes segmentation.
• Noisy microscopy and fluorescence volumes: live-cell imaging, light-sheet microscopy and similar low-exposure 3-D data.
• Materials-science and industrial scans: speckle and grain noise in X-ray or electron-microscopy data.
• A general preprocessing step for downstream quantification: denoising often markedly improves the reliability of subsequent thresholding, connected-component analysis and morphometry.

How to choose between the two algorithms:

• When you have no clean reference, use Noise2Void: it learns to denoise in a self-supervised way from the noisy data itself, with no paired labels.
• When you have paired high-quality references (e.g. a high-dose/high-exposure acquisition of the same sample, or low-noise / high-noise pairs), use CARE: supervised training usually gives stronger restoration.

The plugin supports both 2D and 3D data: if an exported volume has a z-length of 1 (a single slice) it is treated as 2D (YX); otherwise it is handled as a genuine 3-D volume (ZYX).

3. Installation and Enabling

This plugin ships in the Prototype Apps Full Package. Install it as follows:

1. Unzip the Full Package zip to a short folder (e.g. C:\PL\) to avoid long-path errors (see the note below).

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, pick the core install mode (Fresh or Compatible) and tick "Deep Denoising (CSBDeep / Noise2Void)" in the list. Note: all plugins are unchecked (off) by default and must be ticked to enable.

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

5. Quit Dragonfly completely and restart it (menus are only scanned at startup).

After the restart, the plugin appears under the menu: Prototype Apps ▸ Deep Denoising (CSBDeep / Noise2Void)... (in the *Filtering & Restoration* group). Clicking it opens a floating panel window.

Changing your choices later: the easiest way is inside Dragonfly. Open Developer ▸ Prototype Labs... ▸ Menu Item Manager; in the "Prototype Apps (Full Package)" list at the bottom, each app has a checkbox: ticked = deploy, unticked = remove the menu entry. Restart Dragonfly to apply. Disabling never deletes a plugin's built environment (venv) — re-enabling is instant.

Uninstall: double-click `Uninstall_FullPackage.bat` (also kept in the installer folder). It removes all Full-Package menu items, plugins and the central store, but keeps the Prototype Labs core and every plugin's built environment (venv / downloads) — their paths are listed at the end so you can delete them manually to reclaim disk space.

"Path too long" (Error 0x80010135): Windows caps a full path at 260 characters. Do not drag/copy the unzipped folder in Explorer — just run Install_FullPackage.bat (it deploys to short paths). Extract the zip to a short folder (e.g. C:\PL\), not a deep 'Downloads\<zip name>\…' path or a OneDrive-redirected Desktop.

4. Environment and First-Run Setup

This plugin is a venv-in-code type: no machine-learning dependencies are downloaded at install time. On first use, click the Setup Environment button on the panel's Setup tab to build the runtime environment.

What Setup Environment does:

1. Creates a dedicated virtual environment (venv) using a 'base Python'. By default it uses the current Dragonfly's own `Python_env\python.exe` — a full CPython with venv and pip, so no separate Python install is needed.

2. Upgrades pip / setuptools / wheel inside that venv.

3. Installs the full stack from PyPI: tensorflow, csbdeep, n2v, numpy, tifffile.

4. Runs a smoke test: imports tensorflow / csbdeep / n2v and reports whether a GPU was detected.

5. On success, the venv's python path is filled into the "CSBDeep venv python" field and saved to config.

Download size: the first build downloads TensorFlow 2 + csbdeep + n2v (several GB total), taking a few to a dozen-plus minutes depending on your connection.

Internet / GPU requirements:

• Internet is required: all dependencies resolve from PyPI (unlike PyTorch, TensorFlow's PyPI wheels handle GPU directly, so no separate CUDA wheel index is needed).
• An NVIDIA GPU is strongly recommended (with matching CUDA/cuDNN) for practical training/prediction speed. It also runs without a GPU, but training will be noticeably slower.

Where the environment is installed: the venv is built in a venv subfolder of the plugin's installed code directory, i.e. %LOCALAPPDATA%\comet\<DragonflyVersion>\pythonUserExtensions\GenericMenuItems\CSBDeep\venv. The plugin config (including the venv python path) is saved to csbdeep_config.json in that same code directory and also mirrored to %LOCALAPPDATA%\CSBDeepDenoising\config.json.

Other fields on the Setup tab:

• CSBDeep venv python: filled automatically by Setup Environment; normally no need to edit.
• Base Python (build): the base Python used to build the venv. Blank = the current Dragonfly's own python.exe (recommended); you can also enter a path or a command like py -3.10 to override.
• Run mode: windows (default, shipped) or wsl (reserved; only the windows mode ships currently).

Fallback if setup fails: if building the venv with Dragonfly's Python fails (e.g. venv or pip unavailable), enter the path to another CPython 3.9+ (with the stdlib venv + pip) in the "Base Python (build)" field — for example C:\Python310\python.exe — and click Setup Environment again. A half-built venv (has python.exe but no working pip) is detected and rebuilt automatically.

5. Interface Reference

The top of the panel shows a blue note summarizing the plugin. The middle holds three tabs, Setup / Train / Apply; the bottom has a green result status line followed by a read-only run log (showing live progress of export, training, prediction, etc.).

5.1 Setup tab

Used to build the runtime environment. Controls:

• CSBDeep venv python (text field): the venv's python path, filled by Setup Environment.
• Base Python (build) (text field): the base Python for building the venv; blank = Dragonfly's own python.
• Run mode (dropdown): windows / wsl, default windows.
• Setup Environment (build venv + install TensorFlow + csbdeep + n2v) (button): click to build the environment.

5.2 Train tab

Divided into four groups, completed top to bottom for one training run.

Mode group:

• Training mode (dropdown): choose Noise2Void (self-supervised, only noisy) or CARE (supervised, noisy + clean pairs), default Noise2Void. Switching to CARE reveals the "Clean Channel" row below; choosing N2V hides it.

Workspace group:

• Output folder (text field + "…" browse button): all training artifacts and the saved model land here; default C:\CSBDeepWorkspace.
• Model name (text field): the saved model's name. Blank = default name (n2v_model for N2V, care_model for CARE).
• Refresh channels (button): re-reads the Channel list from the current Dragonfly scene to populate the dropdowns below.

(1) Add training cases group:

• Noisy Channel (dropdown): select the noisy Channel.
• Clean Channel (CARE) (dropdown, visible only in CARE mode): select the paired clean (high-quality) Channel.
• Add case (button): add the current selection as a training case (accumulated in an in-memory list). N2V needs only the noisy Channel; CARE needs both noisy and clean selected.
• Clear cases (button): clear the accumulated training cases.
• Training cases: N (label): shows how many cases have been added.

(2) Train group:

• Patch size (spin box): the training patch edge length, range 16–512, step 8, default 64. Square patches in 2D, cubic in 3D.
• Epochs (spin box): number of training epochs, range 1–5000, default 20.
• Steps per epoch (spin box): range 1–100000, default 100.
• Batch size (spin box): range 1–512, default 16.
• Train (blue button): export the added cases and start training.

5.3 Apply tab

Predicts (denoises) a Channel using a saved model. Controls:

• Model type (dropdown): model type Noise2Void or CARE; must match the type used at training.
• Model folder (text field + "…" browse button): the folder of the saved model (i.e. …/<model_name>). After a successful training, this is pre-filled automatically.
• Image Channel (dropdown + Refresh button): select the image Channel to denoise.
• Tiles (memory; >1 splits volume) (spin box): tile count, range 1–64, default 1. When a volume is too large for memory/GPU, a value >1 splits it into tiles for prediction.
• Result title (text field): the title of the result Channel. Blank = auto-named <source>_restored.
• Apply -> publish restored Channel (green button): start prediction and publish the denoised result as a new Channel.

6. Step-by-Step Usage

6.1 First-time preparation (once only)

1. Open Prototype Apps ▸ Deep Denoising (CSBDeep / Noise2Void)....

2. Go to the Setup tab, leaving "Base Python" blank (to use Dragonfly's own Python).

3. Click Setup Environment and wait for the console to finish (several GB the first time; internet required). The log showing "Environment ready." means success.

6.2 Train a Noise2Void model (noisy images only)

Input requirement: at least one noisy Channel (no clean reference needed).

1. Go to the Train tab and set Training mode to Noise2Void.

2. Set the Output folder (default C:\CSBDeepWorkspace) and an optional Model name.

3. Click Refresh channels to load the scene's Channels.

4. Pick a noisy Channel in Noisy Channel and click Add case. Repeat for multiple noisy Channels to accumulate cases.

5. Adjust Patch size / Epochs / Steps per epoch / Batch size in the (2) Train group as needed.

6. Click Train. The log shows live "epoch X/Y, loss …" progress.

7. When training finishes, the result line shows "Trained." and the Apply tab's Model folder is pre-filled with the just-saved model path.

6.3 Train a CARE model (noisy + clean pairs)

Input requirement: paired noisy and clean (high-quality) Channels, both aligned to the same grid.

1. On the Train tab, set Training mode to CARE — the Clean Channel (CARE) row now appears.

2. Click Refresh channels; pick the noisy Channel in Noisy Channel and the matching clean Channel in Clean Channel.

3. Click Add case to add this pair. Repeat to add more pairs.

4. Adjust the training parameters and click Train.

6.4 Apply a model to denoise

Input requirement: a saved model folder and an image Channel to denoise.

1. Go to the Apply tab and set Model type to the same type used at training (N2V or CARE).

2. Make sure Model folder points to the saved model folder (usually pre-filled after training; you can also browse with "…").

3. Click Refresh and pick the Channel to denoise in Image Channel.

4. If you hit memory/GPU limits, raise Tiles (>1); optionally fill in Result title.

5. Click Apply -> publish restored Channel. When done, the denoised result appears as a new Channel in the scene.

7. Parameter Reference

The table below lists the adjustable parameters, their defaults and meaning.

About Patch size: csbdeep / n2v require each axis length to be divisible by the network's downsampling factor, so the plugin rounds your entered value down to a multiple of 8 (not below 16) before using it.

8. Output Results

Training output: a saved deep-learning model at <Output folder>/<model_name>/ (csbdeep / n2v store a model as <basedir>/<name>/). Intermediate artifacts of the run (exported case .npy files, CARE patch .npz, status/results JSON) are kept in a timestamped job subfolder (e.g. train_YYYYMMDD_HHMMSS).

Apply output: a brand-new Channel published back into the current Dragonfly scene.

• The Channel's title is what you entered in Result title; blank gives <source Channel>_restored.
• The denoised result reuses the source Channel's grid geometry (voxel spacing and origin are copied over), so it is spatially aligned and can be overlaid on the original.
• For single-slice data treated as 2D, the leading singleton z axis is restored after prediction so the result re-publishes onto the source Channel's (z, y, x) grid.

How to view: the new Channel appears in Dragonfly's Object List like any other Channel. You can display it in 2D/3D views, adjust window/level, and use it for thresholding and measurement. It is good practice to compare the denoised Channel side by side with (or overlaid on) the original noisy Channel to judge the result.

9. FAQ and Troubleshooting

Q: Train or Apply says "venv not set. Run Setup Environment first." What do I do?

A: The runtime environment has not been built yet. Go to the Setup tab and click Setup Environment; once the log shows "Environment ready." and the "CSBDeep venv python" field is filled, return to train or apply.

Q: Setup Environment fails with a download or install error?

A: This is usually a network issue or a TensorFlow / n2v incompatibility with the current Python. Confirm you can reach PyPI (internet required); if building with Dragonfly's Python fails, enter the path to another CPython 3.9+ (with venv + pip) in Base Python (build) — e.g. C:\Python310\python.exe — and retry. A half-built venv is rebuilt automatically.

Q: Training/prediction reports out-of-memory (OOM) or a CUDA-related error?

A: For prediction, raise Tiles (>1) to split the volume and lower per-pass memory; for training, reduce Patch size or Batch size. If the log says no GPU / CUDA was found, the plugin can still run on CPU (slower), or check your NVIDIA driver and a matching CUDA/cuDNN.

Q: Adding a CARE case says "CARE needs a clean (high-quality) Channel too"?

A: CARE is supervised, so each case must supply both a noisy Channel and a paired clean Channel. Pick a clean Channel in the Clean Channel (CARE) row before clicking Add case; if you have no clean reference, switch to Noise2Void instead.

Q: Add case says "select a noisy Channel (Refresh)"?

A: No Channel is available in the dropdown or none is selected. Click Refresh channels to load the Channels in the current scene, then select one in Noisy Channel.

Q: The plugin does not appear in the menu?

A: Confirm you ticked the plugin during install (it is unchecked by default) and fully restarted Dragonfly afterwards (menus are scanned only at startup). You can also tick it in Developer ▸ Prototype Labs... ▸ Menu Item Manager and restart.

10. Notes and Known Limitations

• Internet is required the first time to download several GB of dependencies (TensorFlow 2 + csbdeep + n2v); allow time and disk space.
• A GPU is strongly recommended: it runs without one, but training/prediction will be markedly slower.
• n2v 0.3.x pins TensorFlow 2 and needs a compatible Python version; if the auto-install fails, try a matching Python as the Base Python.
• CARE needs paired data with the noisy and clean Channels aligned to the same grid; N2V needs only noisy data.
• Model type must match training: a model trained with N2V must be applied as N2V, and likewise for CARE.
• Only the windows Run mode currently ships (wsl is a reserved option).
• For large-volume prediction, use Tiles (>1) to avoid memory/GPU overflow.
• Denoising is an estimated reconstruction of the image: always compare the result with the original to check for unwanted smoothing or artifacts before using it for quantitative analysis.

11. References

• CSBDeep (CARE / content-aware restoration) project: https://github.com/CSBDeep/CSBDeep
• Noise2Void (n2v) project: https://github.com/juglab/n2v
• TensorFlow official site: https://www.tensorflow.org/
• CARE paper: Weigert et al., "Content-aware image restoration: pushing the limits of fluorescence microscopy", Nature Methods, 2018.
• Noise2Void paper: Krull et al., "Noise2Void - Learning Denoising from Single Noisy Images", CVPR, 2019.
• Prototype Apps Full Package install/enable guide: the bundled UserManual_用户手册.docx and the README in the installer folder.