深度去噪 (CAREamics) 插件用户手册

Deep Denoising (CAREamics) - User Manual

Dragonfly Prototype Apps · Deep Denoising (CAREamics)...

版本 Version 1.0 · 2026-07-09

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

深度去噪 (CAREamics) 是一款 Dragonfly 插件,让您在自己的数据上训练并应用基于深度学习的去噪 / 图像复原模型。它把成熟的开源项目 CAREamics(底层为 PyTorch)集成到 Dragonfly:在 Train(训练) 选项卡里选择一个含噪的图像 Channel、算法、patch(切块)大小、训练轮数和模型名称即可训练;训练完成后在 Apply(应用) 选项卡里选择训练好的模型和一个 Channel,插件即输出一个与原图同网格(相同 spacing/origin)的去噪 Channel,并把模型保存下来供以后复用。

插件支持四种算法,分为两类:自监督——Noise2Void(N2V)与 N2V2,只需含噪数据本身,无需任何干净参考图像;有监督——CARE 需要一张配对的干净目标图像,Noise2Noise(N2N)需要对同一样本的第二次独立含噪采集作为目标。

Dragonfly 自带高斯、中值、非局部均值等经典滤波器,但没有可学习的自监督去噪器;本插件正是填补这一空白,能在保留细结构的前提下去除噪声。

所有重计算(PyTorch CUDA + careamics)均在插件独立的运行环境(venv)中,以子进程方式执行,绝不加载进 Dragonfly 自身的 Python,因此不会污染或拖垮 Dragonfly。

底层引擎与许可

• 去噪引擎: CAREamics(开源 Python 库,底层为 PyTorch / PyTorch Lightning)。
• 算法: Noise2Void、N2V2、CARE、Noise2Noise —— 由 CAREamics 的 create_n2v_configuration / create_care_configuration / create_n2n_configuration 配置构建器实现,N2V2 即 Noise2Void 的 use_n2v2=True 变体。
• 计算后端: PyTorch(CUDA 版,从官方 cu124 CUDA 轮子索引安装),需要 NVIDIA GPU。
• 各上游组件遵循其各自的开源许可;本插件仅通过子进程调用它们,不修改其源码。

2. 适用场景

本插件适用于任何噪声较大、经典滤波会损失细节的体数据或图像栈。典型场景包括:

• 低剂量 / 快速采集的显微 CT 与工业 CT —— 缩短曝光或降低剂量带来的噪声。
• 电子显微镜(TEM / SEM) —— 低电子剂量成像。
• 荧光显微镜与光片显微镜 —— 弱信号、短曝光下的散粒噪声。
• 需要批量清理同类数据集的场合 —— 训练一次,即可把模型应用到其余同类数据上。

如何选择算法

• 没有任何干净参考图像 —— 用 Noise2Void 或 N2V2,它们只凭含噪数据本身即可学习去噪(自监督)。
• 有配对的干净图像 —— 用 CARE(有监督),用干净图像作为训练目标。
• 有两次独立的含噪采集(同一样本、同一视野) —— 用 Noise2Noise,用第二次含噪采集作为目标。

特别适合需要在保留细结构的前提下,对一批相似样本做统一去噪的用户。

3. 安装与启用

本插件随 Prototype Apps 完整安装包(Full Package) 分发,按以下步骤安装和启用。

3.1 通过完整安装包安装

1. 把安装包 zip 解压到一个较短的目录(如 C:\PL\),不要放在很深的下载目录或 OneDrive 重定向的桌面下。

2. 双击 `Install_FullPackage.bat`。

3. 在弹出的对话框中选择核心安装模式:Fresh(全新安装,会先备份再重置 Prototype Labs 的 blocks/recipes)或 Compatible(兼容安装,保留你自己的 blocks 和 recipes)。该选项只影响 Prototype Labs 核心,不影响任何插件的环境和设置。

4. 在应用列表中勾选 “Deep Denoising (CAREamics)...”。注意:默认情况下所有插件都未勾选,本插件必须手动勾选才会部署。

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

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

本插件默认未勾选。 安装包默认只开启轻量菜单项、关闭所有插件。若不勾选 “Deep Denoising (CAREamics)...”,重启后菜单里不会出现它。

3.2 菜单出现的位置

重启后,插件出现在 Prototype Apps 菜单下,分组为 Filtering & Restoration(滤波与复原),菜单标题为 “Deep Denoising (CAREamics)...”。点击即弹出一个可移动的浮动面板。

3.3 以后修改勾选

最方便的方式是在 Dragonfly 内修改:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部的 “Prototype Apps (Full Package)” 列表中,每个应用有一个勾选框——勾选=部署,取消=移除该菜单项,重启 Dragonfly 生效。

停用从不删除插件已搭好的运行环境(venv);重新启用后立即可用,无需重新搭建。

3.4 卸载

双击 `Uninstall_FullPackage.bat`(位于 %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer 目录中)。它会移除所有 Full Package 的菜单项、插件和中央存储,但保留已搭建的运行环境(venv / 下载内容);结束时会列出这些路径,需要腾出磁盘空间时可手动删除。

全部内容安装在当前用户目录(%LOCALAPPDATA%)下,不需要管理员权限。

4. 运行环境与首次配置

重型插件在安装时不下载任何东西。 本插件首次使用前,必须在面板的 Setup(设置) 选项卡中点击 Setup Environment 按钮搭建独立运行环境。

4.1 Setup Environment 做了什么

1. 用一个基础 Python 创建一个独立的虚拟环境(venv),该 venv 默认建在插件安装目录内的 venv\ 子目录中。默认基础 Python 是 Dragonfly 自带的 `Python_env\python.exe`(其内置的 venv + pip 均可正常工作,因此您无需另外安装 Python)。

2. 升级 venv 内的 pip / setuptools / wheel。

3. 从 CUDA 轮子索引(默认 https://download.pytorch.org/whl/cu124)安装 torch + torchvision(GPU 版)。

4. 安装 careamics + numpy(careamics 会顺带拉入 PyTorch Lightning、bioimageio、scikit-image 等依赖)。

5. 做一次冒烟测试:导入 torch 与 careamics,并报告 CUDA 是否可用。

首次搭建通常需要数分钟,下载量约数 GB(torch CUDA + careamics)。搭建成功后,venv 的 python 路径会被记录到面板的 CAREamics venv python 字段,并保存到配置文件中,以后复用无需重建。

4.2 前置条件

• 联网: 首次 Setup 需要联网下载 torch 与 careamics。搭建完成后训练 / 应用不需要联网。
• NVIDIA GPU: 训练与推理都需要一块 NVIDIA GPU。
• Dragonfly 版本: 本插件面向 Dragonfly 2027.1 及以上。

Turing 架构显卡(如 RTX 8000,sm_75): cu124 轮子可以运行,但请使用 fp16,切勿使用 bf16——Turing 没有 bf16 张量核心。

4.3 失败时的替代方案

• 基础 Python 缺 venv 模块 / pip 失败: 在 Base Python (build) 字段填入另一个 CPython 3.9+ 的路径(或形如 py -3.12),再重试 Setup。留空则使用 Dragonfly 自带的 python。
• torch 安装失败: 确认 Torch CUDA wheel index 与您的显卡驱动匹配(如 cu121 / cu124),必要时修改该字段后重试。
• 半成品 venv: 若某次 Setup 中途失败留下一个没有可用 pip 的 venv,再次点击 Setup Environment 会自动检测并重建它。

安装位置:venv 位于插件在各 Dragonfly 版本 GenericMenuItems\CAREamics\venv 目录中;插件设置保存在 %LOCALAPPDATA%\CAREamics\config.json(以及插件代码目录下的 careamics_config.json)。

5. 界面说明

面板顶部有一行蓝色说明文字,概述插件用途。主体是三个选项卡:Setup、Train、Apply;下方是一个绿色的结果标签和一个只读的日志窗口,实时显示进度与错误。

5.1 Setup 选项卡(搭建环境)

• CAREamics venv python: 只读性质的路径字段,由 Setup Environment 自动填写(占位提示 “set by 'Setup Environment'”)。
• Base Python (build): 搭建 venv 所用的基础 Python。留空=使用本 Dragonfly 自带 python.exe(推荐);也可填路径或形如 py -3.12。
• Run mode: 运行模式下拉框,可选 windows(默认)或 wsl;实际发行版本仅支持 windows。
• Torch CUDA wheel index: torch 的 CUDA 轮子索引地址,默认 https://download.pytorch.org/whl/cu124。
• Setup Environment 按钮: 点击开始搭建 venv 并安装 torch + careamics。按钮下方有黄色提示,说明首次需数分钟、数 GB,需联网 + NVIDIA GPU,以及 Turing 用 fp16 的注意事项。

5.2 Train 选项卡(训练)

分为三个分组:

• Workspace(输出文件夹): Output folder 字段设置工作区目录(默认 C:\CAREamicsWorkspace),旁边有 “...” 浏览按钮;还有一个 Refresh channels 按钮,用于刷新场景中的 Channel 列表。
• Training data(训练数据): Noisy image Channel 下拉框选择含噪的图像 Channel;Target Channel (CARE/N2N) 下拉框选择目标 Channel(CARE 用干净图像、N2N 用第二次含噪采集),默认含 “(none)” 选项,自监督算法(N2V/N2V2)会忽略该项。
• Train(训练参数): Algorithm 下拉框(Noise2Void / N2V2 / CARE / Noise2Noise);Patch size 数字框(范围 8–1024,步进 8);Epochs 数字框(范围 1–100000);Model name 文本框(默认 careamics_model);Train 按钮(蓝色)开始训练。

5.3 Apply 选项卡(应用)

• Model: 训练好的模型文件路径字段,训练完成后会自动填入;旁边有 “...” 浏览按钮(过滤器为 *.ckpt *.zip *.pt *.pth)。
• Image Channel: 要去噪的图像 Channel 下拉框,旁边有一个 Refresh 按钮刷新列表。
• Result title: 去噪结果 Channel 的标题;留空则默认命名为 CAREamics_denoised。
• Apply -> publish denoised Channel 按钮: (绿色)开始推理并发布去噪后的 Channel。

6. 使用步骤

6.1 训练一个去噪模型

输入要求: 场景中至少有一个含噪的图像 Channel;若用 CARE/N2N 还需另一个目标 Channel。

1. 在 Dragonfly 中打开 / 载入含噪的图像数据,使其成为一个 Channel。

2. 打开面板,先在 Setup 选项卡完成 Setup Environment(仅首次)。

3. 切到 Train 选项卡,在 Workspace 分组设置一个 Output folder(工作区目录)。

4. 点击 Refresh channels 刷新列表,在 Noisy image Channel 中选择含噪 Channel。

5. 在 Algorithm 中选择算法。若选 CARE 或 Noise2Noise,还必须在 Target Channel 中选择目标 Channel。

6. 设置 Patch size、Epochs 与 Model name。

7. 点击 Train。日志窗口会显示进度(epoch 与 loss),训练完成后结果标签显示 “Trained.”,并把模型路径自动填入 Apply 选项卡。

得到什么: 一个保存到工作区(在 train_<时间戳> 子目录内)的训练好模型检查点(通常为 .ckpt),可反复应用到同类数据。

6.2 应用模型去噪一个 Channel

输入要求: 一个训练好的模型 + 一个待去噪的图像 Channel。

1. 切到 Apply 选项卡。若刚训练完,Model 字段已自动填好;否则点击 “...” 选择模型文件。

2. 点击 Refresh,在 Image Channel 中选择要去噪的 Channel。

3. (可选)在 Result title 中填写结果 Channel 的标题。

4. 点击 Apply -> publish denoised Channel。

5. 等待日志显示 “Finished”,去噪后的 Channel 会以指定标题发布到场景中。

得到什么: 一个与源 Channel 同网格(相同 spacing / origin)的去噪 Channel,可直接与原图对比、叠加或继续处理。

7. 参数说明

轴与维度自动推断: 插件根据导出体数据的形状自动决定处理维度——单层(z==1)按 2D(YX)处理,真三维体按 3D(ZYX)处理,并自动把 patch 边长强制为偶数。

8. 输出结果

训练输出: 在工作区的 train_<时间戳> 子目录内保存一个训练好的模型检查点(通常为 Lightning 的 .ckpt);其路径会显示在日志中,并自动填入 Apply 选项卡的 Model 字段。

应用输出: 一个新的去噪 Channel,发布到 Dragonfly 场景对象树中。该 Channel:

• 与源 Channel 同网格——相同的 spacing(体素间距)与 origin(原点),因此可与原图逐体素对齐、直接叠加对比。
• 标题为您在 Result title 填写的名称,留空时默认为 CAREamics_denoised。
• 数据类型为 float32(CAREamics 内部会做归一化)。

如何查看: 在对象树中找到新发布的去噪 Channel,把它加入某个 2D/3D 视图,与源图并排或叠加对比,即可直观评估去噪效果。中间导出的 .npy 文件、status.json、results.json 等则保留在对应的 apply_<时间戳> 工作目录中,便于排查。

9. 常见问题与故障排除

问:点击 Train 提示 “venv not set. Run Setup Environment first.” 怎么办?

答:说明尚未搭建运行环境。请先到 Setup 选项卡点击 Setup Environment,等待成功后 venv python 字段会自动填好,再回到 Train。

问:Setup Environment 报 torch 安装失败怎么办?

答:多为 CUDA 轮子索引与显卡驱动不匹配。检查 Torch CUDA wheel index 字段,改成与您驱动匹配的版本(如 cu121 或 cu124)后重试;同时确认网络可以访问 pytorch.org 的下载源。

问:训练 / 推理时报 CUDA 相关错误或显存不足(out of memory)怎么办?

答:确认机器有可用的 NVIDIA GPU 且驱动正常(本插件需要 GPU)。若是显存不足,可减小 Patch size、改用单层 / 较小的数据,或减小数据规模后重试。Turing 显卡(如 RTX 8000)请确保使用 fp16 而非 bf16。

问:选了 CARE 或 Noise2Noise 却提示需要目标 Channel?

答:CARE / N2N 是有监督算法,必须提供 Target Channel(CARE 用配对的干净图像,N2N 用同一样本的第二次独立含噪采集)。若没有目标图像,请改用自监督的 Noise2Void 或 N2V2。

问:菜单里找不到 “Deep Denoising (CAREamics)...” 怎么办?

答:通常是安装时未勾选本插件(默认所有插件关闭),或安装后未重启 Dragonfly。请在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 中勾选它,或重跑安装器勾选后,完全退出并重启 Dragonfly。

问:去噪结果与原图看起来没对齐 / 强度范围不同?

答:去噪 Channel 使用源 Channel 的 spacing 与 origin,几何上是对齐的。CAREamics 内部会归一化,输出为 float32,强度绝对值可能与源图不同属正常现象;可在视图中单独调整该 Channel 的显示窗宽窗位。

10. 注意事项与已知限制

• 需要 NVIDIA GPU: 训练与推理均需 GPU;无 GPU 无法运行。
• 首次联网: 仅 Setup Environment 阶段需要联网下载(数 GB);之后不需要。
• Turing 显卡: RTX 8000 等 sm_75 卡请使用 fp16,切勿用 bf16(无 bf16 张量核心)。
• Patch size 强制偶数: UNet 下采样要求偶数切块;插件会自动取偶,并不超过对应轴的实际尺寸。
• 目标数据对齐: 使用 CARE / N2N 时,目标 Channel 需与输入图像在几何上对应(runner 直接按数组传入)。
• 磁盘占用: venv(数 GB)与每次运行的工作目录会占用磁盘;不再需要时可删除 venv 与旧的 train_/apply_ 目录。
• 菜单发现: 启用 / 停用后需重启 Dragonfly 才能生效。

11. 参考资料

• CAREamics 项目: https://careamics.github.io/
• PyTorch(CUDA 轮子索引): https://download.pytorch.org/whl/cu124
• Noise2Void / N2V2 / CARE / Noise2Noise: 相关方法文献可在 CAREamics 官方文档中查到。
• Prototype Apps 完整安装包总手册: 安装包根目录下的 UserManual_用户手册.docx。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation & Enabling

4. Environment & First-Run Setup

5. Interface Reference

6. Step-by-Step Usage

7. Parameter Reference

8. Outputs

9. FAQ & Troubleshooting

10. Notes & Known Limitations

11. References

1. Overview

Deep Denoising (CAREamics) is a Dragonfly plugin that lets you train and apply deep-learning denoising / restoration models on your own data. It integrates the open-source CAREamics project (built on PyTorch) into Dragonfly: in the Train tab you pick a noisy image Channel, an algorithm, a patch size, the number of epochs and a model name; after training, the Apply tab takes a trained model plus a Channel and outputs a denoised Channel on the same grid (identical spacing/origin) as the input, and the trained model is saved for reuse.

Four algorithms are supported, in two families: self-supervised — Noise2Void (N2V) and N2V2 — which need only the noisy data itself and no clean reference; and supervised — CARE, which needs a paired clean target image, and Noise2Noise (N2N), which needs a second independent noisy acquisition of the same sample as the target.

Dragonfly ships classical filters (Gaussian, median, non-local means, etc.) but no learned self-supervised denoiser. This plugin fills that gap, removing noise while preserving fine structure.

All heavy compute (PyTorch CUDA + careamics) runs in the plugin's dedicated environment (venv) as a subprocess and is never loaded into Dragonfly's own Python, so it cannot pollute or slow down Dragonfly.

Underlying engine & license

• Denoising engine: CAREamics (an open-source Python library built on PyTorch / PyTorch Lightning).
• Algorithms: Noise2Void, N2V2, CARE, Noise2Noise — built via CAREamics' create_n2v_configuration / create_care_configuration / create_n2n_configuration config builders; N2V2 is the use_n2v2=True variant of Noise2Void.
• Compute backend: PyTorch (CUDA build, installed from the official cu124 CUDA wheel index); requires an NVIDIA GPU.
• Each upstream component keeps its own open-source license; the plugin only calls them via a subprocess and does not modify their source.

2. Use Cases

The plugin is ideal for any noisy volume or image stack where classical filtering would blur fine detail. Typical cases include:

• Low-dose / fast-acquisition micro-CT and industrial CT — noise from shorter exposure or reduced dose.
• Electron microscopy (TEM / SEM) — low electron-dose imaging.
• Fluorescence and light-sheet microscopy — shot noise under weak signal / short exposure.
• Batch-cleaning of similar datasets — train once, then apply the model to the rest of the same-type data.

How to choose an algorithm

• No clean reference at all — use Noise2Void or N2V2; they learn to denoise from the noisy data alone (self-supervised).
• A paired clean image exists — use CARE (supervised), with the clean image as the training target.
• Two independent noisy acquisitions (same sample, same field of view) — use Noise2Noise, with the second noisy acquisition as the target.

Especially useful when you must denoise a batch of similar samples uniformly while preserving fine structures.

3. Installation & Enabling

The plugin is distributed with the Prototype Apps Full Package. Install and enable it as follows.

3.1 Install via the Full Package

1. Unzip the package to a short folder (e.g. C:\PL\); avoid deep download folders or a OneDrive-redirected Desktop.

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, pick the core install mode: Fresh (backs up then resets Prototype Labs blocks/recipes) or Compatible (keeps your own blocks and recipes). This choice only affects the Prototype Labs core, not any plugin's environment or settings.

4. In the app list, tick “Deep Denoising (CAREamics)...”. Note: by default all plugins are OFF, so this plugin must be ticked manually to be deployed.

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

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

This plugin is OFF by default. The package enables only the light menu items and leaves all plugins off. If you do not tick “Deep Denoising (CAREamics)...”, it will not appear in the menu after restart.

3.2 Where the menu appears

After restart, the plugin appears under the Prototype Apps menu, in the Filtering & Restoration group, with the menu title “Deep Denoising (CAREamics)...”. Clicking it opens a movable floating panel.

3.3 Change your choice later

The easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager, and in the “Prototype Apps (Full Package)” list at the bottom each app has a checkbox — tick to deploy, untick to remove the menu entry. Restart Dragonfly to apply.

Disabling never deletes a plugin's built environment (venv); re-enabling is instant, with no need to rebuild.

3.4 Uninstall

Double-click `Uninstall_FullPackage.bat` (kept in %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer). It removes all Full-Package menu items, plugins and the central store, but keeps every built environment (venv / downloads); their paths are listed at the end so you can delete them manually to reclaim disk space.

Everything is installed per-user (under %LOCALAPPDATA%) and needs no administrator rights.

4. Environment & First-Run Setup

Heavy plugins download nothing at install time. Before first use, you must build the dedicated environment by clicking Setup Environment on the panel's Setup tab.

4.1 What Setup Environment does

1. Creates a dedicated virtual environment (venv) using a base Python; by default the venv is placed in a venv\ subfolder inside the plugin's installed code directory. The default base Python is Dragonfly's own `Python_env\python.exe` (whose built-in venv + pip work, so you need no separate Python install).

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

3. Installs torch + torchvision (GPU build) from the CUDA wheel index (default https://download.pytorch.org/whl/cu124).

4. Installs careamics + numpy (careamics pulls in PyTorch Lightning, bioimageio, scikit-image, etc.).

5. Runs a smoke test: imports torch and careamics and reports whether CUDA is available.

The first build usually takes several minutes and downloads roughly several GB (torch CUDA + careamics). On success, the venv's python path is recorded in the CAREamics venv python field and saved to the config, so it is reused later without rebuilding.

4.2 Prerequisites

• Internet: needed only for the first Setup (to download torch and careamics). Training / applying afterwards needs no internet.
• NVIDIA GPU: both training and inference require an NVIDIA GPU.
• Dragonfly version: the plugin targets Dragonfly 2027.1 and later.

Turing GPUs (e.g. RTX 8000, sm_75): the cu124 wheels run, but use fp16 — never bf16 (Turing has no bf16 tensor cores).

4.3 Fallbacks when Setup fails

• Base Python lacks venv / pip fails: enter the path to another CPython 3.9+ in the Base Python (build) field (or a form like py -3.12) and retry Setup. Leave it blank to use Dragonfly's own python.
• torch install fails: make sure the Torch CUDA wheel index matches your GPU driver (e.g. cu121 / cu124); edit the field and retry.
• Half-built venv: if a failed Setup leaves a venv with no working pip, clicking Setup Environment again detects and rebuilds it automatically.

Install locations: the venv lives under the plugin's GenericMenuItems\CAREamics\venv directory in each Dragonfly version; settings are saved to %LOCALAPPDATA%\CAREamics\config.json (and a careamics_config.json next to the plugin code).

5. Interface Reference

A blue note at the top of the panel summarizes what the plugin does. The body has three tabs — Setup, Train, Apply — with a green result label and a read-only log window below them that show live progress and errors.

5.1 Setup tab

• CAREamics venv python: a path field filled automatically by Setup Environment (placeholder “set by 'Setup Environment'”).
• Base Python (build): the base Python used to build the venv. Blank = this Dragonfly's own python.exe (recommended); or a path / a form like py -3.12.
• Run mode: a dropdown with windows (default) or wsl; only windows is shipped.
• Torch CUDA wheel index: the CUDA wheel index for torch, default https://download.pytorch.org/whl/cu124.
• Setup Environment button: builds the venv and installs torch + careamics. A yellow hint below explains the several-minutes / several-GB first build, the internet + NVIDIA GPU requirement, and the Turing fp16 note.

5.2 Train tab

Three groups:

• Workspace (output folder): the Output folder field sets the workspace directory (default C:\CAREamicsWorkspace) with a “...” browse button, plus a Refresh channels button to reload the scene's channel list.
• Training data: a Noisy image Channel dropdown picks the noisy Channel; a Target Channel (CARE/N2N) dropdown picks the target (a clean image for CARE, a second noisy acquisition for N2N) and includes a “(none)” entry — self-supervised algorithms (N2V/N2V2) ignore it.
• Train: the Algorithm dropdown (Noise2Void / N2V2 / CARE / Noise2Noise); the Patch size spin box (range 8–1024, step 8); the Epochs spin box (range 1–100000); the Model name text box (default careamics_model); and the Train button (blue) to start.

5.3 Apply tab

• Model: the trained-model path field, auto-filled after training; with a “...” browse button (filter *.ckpt *.zip *.pt *.pth).
• Image Channel: the dropdown for the Channel to denoise, with a Refresh button.
• Result title: the title for the denoised Channel; blank defaults to CAREamics_denoised.
• Apply -> publish denoised Channel button: (green) runs inference and publishes the denoised Channel.

6. Step-by-Step Usage

6.1 Train a denoising model

Input requirement: at least one noisy image Channel in the scene; for CARE/N2N also a target Channel.

1. Open / load the noisy image data in Dragonfly so it becomes a Channel.

2. Open the panel and complete Setup Environment on the Setup tab (first time only).

3. Switch to the Train tab and set an Output folder (workspace) in the Workspace group.

4. Click Refresh channels, then select the noisy Channel in Noisy image Channel.

5. Choose an algorithm in Algorithm. For CARE or Noise2Noise, you must also pick a Target Channel.

6. Set Patch size, Epochs and Model name.

7. Click Train. The log window shows progress (epoch and loss); on completion the result label reads “Trained.” and the model path is auto-filled into the Apply tab.

What you get: a trained model checkpoint (typically .ckpt) saved in the workspace (under a train_<timestamp> subfolder), reusable on similar data.

6.2 Apply a model to denoise a Channel

Input requirement: a trained model + an image Channel to denoise.

1. Switch to the Apply tab. If you just trained, the Model field is already filled; otherwise click “...” to select the model file.

2. Click Refresh, then pick the Channel to denoise in Image Channel.

3. (Optional) enter a title in Result title.

4. Click Apply -> publish denoised Channel.

5. Wait for the log to read “Finished”; the denoised Channel is published into the scene under the chosen title.

What you get: a denoised Channel on the same grid (identical spacing / origin) as the source, ready to compare, overlay or process further.

7. Parameter Reference

Axes / dimensionality are inferred automatically: the plugin decides the processing dimensionality from the exported volume shape — a single slice (z==1) is treated as 2D (YX), a true 3D volume as 3D (ZYX) — and forces the patch edge to be even.

8. Outputs

Training output: a trained model checkpoint (typically a Lightning .ckpt) saved under a train_<timestamp> subfolder in the workspace; its path is shown in the log and auto-filled into the Apply tab's Model field.

Apply output: a new denoised Channel published into the Dragonfly scene object tree. This Channel:

• is on the same grid as the source — identical spacing (voxel spacing) and origin — so it aligns voxel-for-voxel and can be overlaid or compared directly.
• carries the title you entered in Result title, defaulting to CAREamics_denoised when left blank.
• is float32 data (CAREamics normalizes internally).

How to view: find the newly published denoised Channel in the object tree, add it to a 2D/3D view, and compare it side-by-side or overlaid with the source to judge the result. Intermediate .npy files, status.json, and results.json remain in the corresponding apply_<timestamp> working folder for troubleshooting.

9. FAQ & Troubleshooting

Q: Clicking Train shows “venv not set. Run Setup Environment first.” What now?

A: The environment hasn't been built yet. Go to the Setup tab and click Setup Environment; once it succeeds the venv python field is filled automatically, then return to Train.

Q: Setup Environment reports that the torch install failed.

A: This is usually a mismatch between the CUDA wheel index and your GPU driver. Check the Torch CUDA wheel index field, set it to a version matching your driver (e.g. cu121 or cu124), and retry; also confirm you can reach the pytorch.org download source.

Q: I get CUDA errors or out-of-memory during training / inference.

A: Confirm the machine has a working NVIDIA GPU with a valid driver (this plugin requires a GPU). For out-of-memory, reduce Patch size, use smaller / single-slice data, or downscale the dataset and retry. On Turing GPUs (e.g. RTX 8000) make sure fp16 is used, not bf16.

Q: I chose CARE or Noise2Noise but it asks for a target Channel.

A: CARE / N2N are supervised algorithms and require a Target Channel (a paired clean image for CARE, a second independent noisy acquisition of the same sample for N2N). If you have no target image, use the self-supervised Noise2Void or N2V2 instead.

Q: I can't find “Deep Denoising (CAREamics)...” in the menu.

A: Usually the plugin wasn't ticked during install (all plugins are off by default) or Dragonfly wasn't restarted. Tick it in Developer ▸ Prototype Labs... ▸ Menu Item Manager (or re-run the installer and tick it), then quit Dragonfly completely and restart.

Q: The denoised result looks misaligned with the original / has a different intensity range.

A: The denoised Channel uses the source Channel's spacing and origin, so it is geometrically aligned. CAREamics normalizes internally and outputs float32, so the absolute intensity range may differ from the source — this is expected; simply adjust that Channel's window/level in the view.

10. Notes & Known Limitations

• NVIDIA GPU required: both training and inference need a GPU; the plugin cannot run without one.
• Internet on first use: only the Setup Environment step needs internet (several GB download); afterwards none is needed.
• Turing GPUs: on sm_75 cards such as the RTX 8000, use fp16 — never bf16 (no bf16 tensor cores).
• Patch size forced even: UNet downsampling requires even patches; the plugin rounds to an even value and never exceeds the corresponding axis extent.
• Target alignment: for CARE / N2N, the target Channel must correspond geometrically to the input (the runner passes arrays straight through).
• Disk usage: the venv (several GB) and each run's working folder consume disk; delete the venv and old train_/apply_ folders when no longer needed.
• Menu discovery: enabling / disabling requires a Dragonfly restart to take effect.

11. References

• CAREamics project: https://careamics.github.io/
• PyTorch (CUDA wheel index): https://download.pytorch.org/whl/cu124
• Noise2Void / N2V2 / CARE / Noise2Noise: method references are linked from the CAREamics documentation.
• Prototype Apps Full Package overview manual: UserManual_用户手册.docx in the package root.