去卷积(DeconvolutionLab2)插件用户手册

Deconvolution (DeconvolutionLab2) - User Manual

Dragonfly Prototype Apps · Deconvolution (DeconvolutionLab2)...

版本 Version 1.0 · 2026-07-09

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

去卷积(DeconvolutionLab2) 是一个 Dragonfly 插件,用于对三维图像做经典去卷积(反卷积)图像复原。它在 Dragonfly 中选择一个图像 Channel 和一个点扩散函数(PSF),把它们导出为 Fiji 可读取的 TIFF 文件,在本机安装的 Fiji / ImageJ 中以无界面(headless)方式通过 DeconvolutionLab2 运行去卷积算法,再把复原后的图像作为一个新的 Channel(与原图网格对齐)导入回 Dragonfly。

所谓去卷积,是在已知或可近似估计成像系统 PSF(光学模糊)的前提下,尽量逆转模糊过程,恢复出更清晰的图像。本插件把这一步交给成熟的开源引擎 DeconvolutionLab2 完成,Dragonfly 只负责数据准备、参数配置和结果回收。

底层引擎: DeconvolutionLab2(Sage 等人,发表于 Methods 2017 期刊)。它以短命令令牌加位置参数的形式暴露每种算法,例如 -algorithm RL 10 表示 10 次迭代的 Richardson-Lucy。本插件支持以下 6 种经典算法:Richardson-Lucy(RL)、Richardson-Lucy 全变分(RL-TV)、FISTA、Tikhonov(TM)、Wiener(TRIF)、Landweber(LW)。

运行方式: DeconvolutionLab2 通过 Fiji 的更新站点安装(或作为 DeconvolutionLab2_.jar 放入,由 Fiji 自带 Java 运行)。插件在运行前会检查所选 Fiji 是否已装 DeconvolutionLab2;若缺失,会弹窗询问是否先启用其更新站点。

许可证要点: DeconvolutionLab2 是 GPL-3.0-only 软件。本插件从不把 DeconvolutionLab2 或任何 Fiji / ImageJ 代码导入 Dragonfly 进程,也不随包捆绑这些代码。它只驱动用户自行安装的 Fiji 作为一个独立的 Java 子进程运行(通过 TIFF 文件交换数据)。这个 JVM 子进程就是 GPL 隔离边界;仓库内只包含宽松许可的粘合代码(TIFF 读写、宏拼装)。插件本身遵循 DragonflyPrototypeLabs 仓库的许可条款。

2. 适用场景

本插件适用于因光学模糊而需要复原的三维图像。典型场景包括:

• 共聚焦显微 (confocal) 三维堆栈:在已知或可估计 PSF 时,提升轴向(Z)与横向(XY)分辨率与对比度。
• 宽场荧光 (widefield fluorescence) 图像:去除离焦模糊,让结构边界更锐利。
• 显微 CT (micro-CT) 等体数据:当成像系统的模糊可用 PSF 近似时,做去卷积复原以获得更清晰的 Channel。
• 为后续分割与测量做准备: 去卷积后得到的更清晰 Channel,可直接送入 Dragonfly 的阈值分割、深度学习分割或形态测量流程,减少模糊带来的误差。

关于 PSF 的选择: 当有实测 PSF(例如用荧光微球测得)时,建议用 PSF Channel 模式,复原质量最佳;若没有实测 PSF,可用面板内置的合成高斯 PSF(由一个高斯 sigma 生成)做粗略近似——它只是一个近似,复原效果不如实测 PSF。

3. 安装与启用

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

1. 把完整安装包解压到任意较短的目录(建议 C:\PL\ 一类短路径,避免路径过长报错)。

2. 双击 `Install_FullPackage.bat`。

3. 在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),并在应用列表里勾选 “Deconvolution (DeconvolutionLab2)”。

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

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

本插件默认未勾选。 在应用列表中,轻量菜单项默认开启,而所有插件(含本插件)默认关闭,需要你手动勾选后才会安装启用。

重启后,插件出现在 Dragonfly 菜单栏的:

Prototype Apps > Deconvolution (DeconvolutionLab2)...

它归入 Filtering & Restoration(滤波与复原) 分组。点击后会打开一个可停靠的浮动面板。

以后修改是否启用

最方便的方式是在 Dragonfly 内修改:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,底部 “Prototype Apps (Full Package)” 列表里每个应用一个勾选框——勾选=部署,取消=移除菜单项。修改后重启 Dragonfly 生效。停用从不删除已配置好的 Fiji 路径等设置,重新启用立即可用。

另一种方式是随时重跑安装器(它会记住上次的勾选作为默认值);即使删除了解压文件夹,也可运行 %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat。

卸载

双击完整安装包 installer 目录里的 `Uninstall_FullPackage.bat`,即可移除所有 Full Package 的菜单项与插件。它不会动你本机的 Fiji 安装。

4. 运行环境与首次配置

本插件的环境类型为 external_app(外部应用):它不创建任何 Python 虚拟环境(venv),不需要 GPU,不使用 WSL。它唯一的外部依赖是本机已安装的 Fiji / ImageJ,以及 Fiji 中的 DeconvolutionLab2。

因此,首次使用前需要完成两件事:(A) 让插件找到 Fiji 启动器;(B) 确认 Fiji 中已装 DeconvolutionLab2。

A. 定位 Fiji / ImageJ

• 面板打开时会自动尝试查找 Fiji:它会检查配置中保存的路径、环境变量 DF_FIJI_PATH,以及一批常见位置(%LOCALAPPDATA%、Program Files、用户目录、桌面、下载、C:\/D:\/E:\ 根目录下的 Fiji.app / Fiji / ImageJ 等文件夹)。
• 支持的启动器名包括 ImageJ-win64.exe、fiji-windows-x64.exe、fiji.exe、ImageJ-win32.exe、ImageJ.exe。
• 若自动查找失败,点面板 Locate 再试一次,或点 Browse... 手动选择 Fiji 启动器(建议选择经典的 ImageJ-win64.exe,其无界面 -batch 行为最稳定)。
• 也可以通过设置系统环境变量 DF_FIJI_PATH 指向启动器或 Fiji 安装目录。

B. Setup / 检查 DeconvolutionLab2

点面板上的 Check / Install DeconvolutionLab2 按钮:插件会扫描所选 Fiji 安装的 plugins、jars 文件夹,查找文件名含 deconvolutionlab 的 jar/class。

• 若已检测到: 会弹窗提示 “DeconvolutionLab2 detected”,并在状态栏显示其路径。无需其它操作。
• 若未检测到: 会弹窗询问 “Install DeconvolutionLab2?”。选择 Yes 后,插件在后台运行 Fiji 更新器命令,添加 DeconvolutionLab2 更新站点并应用更新。

添加的更新站点为:

DeconvolutionLab2 -> https://sites.imagej.net/DeconvolutionLab2/

是否联网: 只有在安装 / 更新 DeconvolutionLab2 更新站点时才需要联网;之后的日常去卷积运行不需要联网。安装通常需要几分钟,完成后 Fiji 往往需要重启才能加载新装的 jar——若装完后命令仍不可用,请重启 Fiji / Dragonfly。

失败时的替代方案

• 若自动安装失败,可手动在 Fiji 中操作:Help > Update > Manage update sites,勾选 DeconvolutionLab2 更新站点后应用更新并重启。
• 或者把 DeconvolutionLab2_.jar 直接放入 Fiji 的 plugins 目录,由 Fiji 自带 Java 运行。
• 运行报错时,插件会把临时工作目录路径保留在错误信息里,便于你手动检查 Fiji 的输出。

配置好的 Fiji 路径、堆内存、PSF 模式等会保存在插件代码目录下的 deconvolutionlab2_config.json(重装时该文件会被保留,不丢失设置)。

5. 界面说明

面板从上到下由若干分组框(GroupBox)构成,逐一说明如下。

Input image (Channel) — 输入图像

• 下拉框: 列出 Dragonfly 中当前可用的图像 Channel(显示为 “标题 (Z, Y, X)” 形式)。
• Refresh 按钮: 重新扫描当前会话里的 Channel,刷新两个下拉框(输入图像与 PSF Channel)。

PSF (point spread function) — 点扩散函数

• PSF Channel(单选): 选此项时下方出现一个下拉框,从 Dragonfly 已有 Channel 中选一个作为实测 PSF。
• Synthetic Gaussian(单选,默认): 选此项时下方出现 Gaussian sigma (voxels) 数值框,由该 sigma 合成一个高斯 PSF(以体素为单位)。
• Gaussian sigma (voxels): 高斯 sigma,范围 0.1–100.0,步长 0.5,默认 2.0。

Algorithm — 算法

• 算法下拉框: 6 选 1(RL / RL-TV / FISTA / Tikhonov / Wiener / Landweber)。
• 参数区: 根据所选算法动态显示对应参数控件(迭代次数、正则化 lambda、步长 gamma 等,详见第 7 章参数表)。
• 说明文字: 下方灰色说明简述当前算法的特点。

Fiji / DeconvolutionLab2 — 引擎设置

• Launcher(文本框): Fiji/ImageJ 启动器路径,占位提示为 path to ImageJ-win64.exe / fiji-windows-x64.exe。旁边有 Locate(自动查找)与 Browse...(手动选择)两个按钮。
• Max heap(数值框): JVM 最大堆内存,单位 MB,范围 0–262144,步长 512,默认 4096。体数据较大或迭代很多时可调高。
• Check / Install DeconvolutionLab2(按钮): 检查或安装 DeconvolutionLab2(见第 4 章)。

Output — 输出

• Channel suffix(文本框): 输出 Channel 名称的后缀,默认 Deconvolved。最终名称为 “<原 Channel 标题> - <后缀>”。

运行与日志

• Run Deconvolution + Create Channel(蓝色主按钮): 开始一次完整去卷积并创建新 Channel。运行期间该按钮和检查按钮会被禁用。
• 状态栏: 显示检测到的 Channel 数、DeconvolutionLab2 检测结果、运行结果等简短状态。
• 日志框(只读): 显示每一步的详细文本日志(导出、Fiji 运行、导入、错误等)。

6. 使用步骤

下面给出一次端到端去卷积的完整步骤。前提: Dragonfly 中已有待处理的图像 Channel(本插件不采集图像,只处理已有 Channel)。

1. 打开 Prototype Apps > Deconvolution (DeconvolutionLab2)...。

2. 在 Input image (Channel) 下拉框选择要复原的图像 Channel;必要时先点 Refresh 刷新列表。

3. 在 PSF 分组选择 PSF 来源:有实测 PSF 就选 PSF Channel 并在下拉框选中它;否则选 Synthetic Gaussian 并设置 Gaussian sigma(默认 2.0)。

4. 在 Algorithm 下拉框选择算法,并按需调整其参数(迭代次数、正则化 lambda、步长 gamma 等)。若不确定,可先用 Richardson-Lucy (RL)、迭代 10 次试跑。

5. 在 Fiji / DeconvolutionLab2 分组确认 Launcher 已指向有效的 Fiji 启动器(点 Locate 或 Browse...),必要时调整 Max heap。

6. 点 Check / Install DeconvolutionLab2 确认引擎已就绪(首次可能需要联网安装并重启)。

7. 在 Output 分组按需修改 Channel suffix(默认 Deconvolved)。

8. 点 Run Deconvolution + Create Channel。插件会把图像与 PSF 导出为 TIFF、无界面启动 Fiji 运行 DeconvolutionLab2、再把结果导入。运行过程见日志框。

9. 运行成功后,日志会显示 “Created Channel '...'” 及其形状;新的去卷积 Channel 会发布到 Dragonfly,可在对象列表和视图中查看。

耗时提示: Fiji / DeconvolutionLab2 作为外部进程运行,大体数据或高迭代次数会比较慢,并需要足够的 JVM 堆内存(Max heap)。首次运行建议用较小的迭代次数或裁剪后的子体积快速验证参数。

7. 参数说明

面板通用参数(与算法无关):

各算法的专有参数(参数按 DeconvolutionLab2 期望的顺序传入;迭代次数被下限约束为 ≥ 1,正则化 / 步长被约束为 ≥ 0):

参数调优建议: 迭代次数越多、复原越锐利,但也越容易放大噪声并延长耗时;带正则化的算法(RL-TV、FISTA、TM)可通过增大 lambda 抑制噪声。DeconvolutionLab2 不同构建版本的命令 / 参数名可能略有差异,若某令牌不可用,插件会把 Fiji 的 stderr / stdout 报到日志里。

8. 输出结果

一次成功运行会在 Dragonfly 中生成一个新的图像 Channel:

• 对象类型: Channel(图像),由去卷积后的 TIFF 通过 createChannelFromNumpyArray 创建并发布。
• 命名: “<原 Channel 标题> - <后缀>”,后缀默认 Deconvolved。
• 几何对齐: 新 Channel 尽量恢复源 Channel 的网格——沿用原图的体素间距(spacing)与原点(origin),因此与原图在空间上对齐,可直接叠加对比。
• 数据类型: 复原图像以 float32(浮点)写入。

如何查看: 新 Channel 会自动发布到 Dragonfly 的对象列表(Object List)中,可在 2D / 3D 视图里显示。把它与原图放在同一视图并切换显示,即可直观比较去卷积前后的清晰度差异。

临时文件: 运行过程中的输入 TIFF、PSF TIFF、输出 TIFF 与宏文件放在操作系统临时目录下的一个 decolab_... 工作文件夹里。运行成功后日志会打印该 “Job folder” 路径;运行失败时也会保留该路径,便于手动排查 Fiji 输出。这些临时文件不影响 Dragonfly 中生成的 Channel。

9. 常见问题与故障排除

Q1:面板提示找不到 Fiji / ImageJ,怎么办?

先点 Locate 让插件重新自动查找;若仍找不到,点 Browse... 手动选择 Fiji 启动器(推荐经典的 ImageJ-win64.exe)。也可以设置环境变量 DF_FIJI_PATH 指向启动器或 Fiji 目录。如果本机尚未安装 Fiji,请先从官方渠道安装 Fiji。

Q2:提示 DeconvolutionLab2 未检测到 / 安装后仍不可用?

点 Check / Install DeconvolutionLab2,在弹窗中选 Yes 让插件启用 DeconvolutionLab2 更新站点(需联网,可能几分钟)。装完后 Fiji 常需重启才能加载新 jar——重启 Fiji / Dragonfly 再试。若自动安装失败,可在 Fiji 里手动操作 Help > Update > Manage update sites > DeconvolutionLab2,或把 DeconvolutionLab2_.jar 放入 Fiji 的 plugins 目录。

Q3:运行报错 “Fiji produced no output TIFF” 或退出码非 0?

这通常意味着 Fiji / DeconvolutionLab2 命令没有成功产出结果。请检查:(1) DeconvolutionLab2 是否真的已安装并可用;(2) 所选算法令牌在你的 DeconvolutionLab2 版本里是否存在(不同构建的命令名可能不同);(3) 查看日志框里 Fiji 的 stderr / stdout 报错。日志里保留了临时工作目录路径,可进去手动检查输入 / 输出 TIFF 与宏文件。

Q4:去卷积结果反而更差 / 出现明显噪声或伪影?

最常见的原因是 PSF 不准。合成高斯 PSF 只是粗略近似,若有条件请改用实测 PSF Channel。其次,迭代次数过多会放大噪声——减少迭代次数,或改用带正则化的算法(RL-TV / FISTA / TM)并适当增大正则化 lambda。也可先在小裁剪区域上试几组参数再应用到全图。

Q5:处理很慢或内存不足怎么办?

DeconvolutionLab2 在外部 JVM 中运行,大体数据 + 高迭代次数会很耗时。可以:调高 Max heap(默认 4096 MB)给 JVM 更多内存;减少迭代次数;或先在裁剪后的子体积上验证。

Q6:输入图像下拉框是空的?

说明当前 Dragonfly 会话里没有可用的图像 Channel,或列表尚未刷新。先在 Dragonfly 中加载 / 生成一个图像 Channel,再点面板上的 Refresh 重新扫描。

10. 注意事项与已知限制

• 需要已有 Channel: 插件只处理 Dragonfly 中已存在的图像 Channel,不负责采集或导入原始图像。
• PSF 质量决定成败: 有实测 PSF 时优先用 PSF Channel;合成高斯 PSF 只是粗略近似。
• 外部进程开销: Fiji / DeconvolutionLab2 作为外部进程运行,大体数据与高迭代次数耗时较长,并需要足够的 JVM 堆内存。
• 几何恢复尽力而为: 输出 Channel 会尽可能从源 Channel 恢复几何(间距 / 原点),但取决于 TIFF 元数据能否被正确读回。
• 命令名版本差异: DeconvolutionLab2 不同构建的命令 / 参数名可能不同;算法列表使用标准的 DeconvolutionLab2 令牌,遇到不可用命令时会把 Fiji 的 stderr / stdout 报到日志。
• 联网仅用于安装: 只有启用 / 更新 DeconvolutionLab2 更新站点时需要联网,日常运行无需联网,也不需要 Python 虚拟环境或 GPU。
• GPL 隔离: DeconvolutionLab2(GPL-3.0)始终只作为独立的 Fiji Java 子进程运行,不会被导入 Dragonfly 进程,也不随包捆绑。

11. 参考资料

• DeconvolutionLab2 更新站点:https://sites.imagej.net/DeconvolutionLab2/
• DeconvolutionLab2 参考文献:Sage 等人,Methods,2017(DeconvolutionLab2 算法框架)。
• Fiji / ImageJ:开源图像处理平台,DeconvolutionLab2 作为其更新站点提供。
• Fiji 更新站点管理入口:Fiji 菜单 Help > Update > Manage update sites。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation and Enabling

4. Runtime Environment and First-Run Setup

5. Interface Guide

6. Usage Steps

7. Parameter Reference

8. Output

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

1. Overview

Deconvolution (DeconvolutionLab2) is a Dragonfly plugin for classical 3D deconvolution (image restoration). It lets you select an image Channel and a point spread function (PSF) in Dragonfly, exports them as Fiji-readable TIFFs, runs a deconvolution algorithm headlessly through DeconvolutionLab2 in your locally installed Fiji / ImageJ, and imports the restored image back into Dragonfly as a new Channel aligned to the source grid.

Deconvolution attempts to reverse optical blur to recover a sharper image, given a known or approximated system PSF. This plugin delegates that step to the mature open-source DeconvolutionLab2 engine; Dragonfly only handles data preparation, parameter configuration, and result collection.

Underlying engine: DeconvolutionLab2 (Sage et al., Methods, 2017). Each algorithm is exposed as a short command token plus positional parameters, e.g. -algorithm RL 10 for a 10-iteration Richardson-Lucy run. The plugin supports 6 classical algorithms: Richardson-Lucy (RL), Richardson-Lucy Total Variation (RL-TV), FISTA, Tikhonov (TM), Wiener (TRIF), and Landweber (LW).

How it runs: DeconvolutionLab2 is installed through Fiji's update site (or dropped in as DeconvolutionLab2_.jar and run via Fiji's bundled Java). Before running, the plugin checks the selected Fiji for DeconvolutionLab2; if it is missing, it prompts you to enable the update site first.

Licensing: DeconvolutionLab2 is GPL-3.0-only software. This plugin never imports DeconvolutionLab2 or any Fiji / ImageJ code into the Dragonfly process, and bundles none of it. It only drives a user-installed Fiji as a separate Java subprocess (exchanging plain TIFF files). That JVM subprocess is the GPL isolation boundary; only permissively-licensed glue (TIFF I/O, macro assembly) ships in the repo. The plugin itself follows the DragonflyPrototypeLabs repository's license terms.

2. Use Cases

This plugin is for 3D images degraded by optical blur that need restoration. Typical scenarios include:

• Confocal microscopy 3D stacks: when the PSF is known or can be estimated, improve axial (Z) and lateral (XY) resolution and contrast.
• Widefield fluorescence images: remove out-of-focus blur for sharper structure boundaries.
• Micro-CT and similar volume data: deconvolve for restoration when the system blur can be approximated by a PSF.
• Preparing for segmentation and measurement: the sharper Channel produced by deconvolution feeds directly into Dragonfly's thresholding, deep-learning segmentation, or morphological measurement workflows, reducing blur-induced error.

Choosing a PSF: when a measured PSF is available (e.g. from fluorescent beads), use PSF Channel mode for the best restoration quality. Without a measured PSF, use the panel's built-in Synthetic Gaussian PSF (generated from a Gaussian sigma) as a rough approximation - it is only an approximation and restores less well than a measured PSF.

3. Installation and Enabling

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

1. Unzip the Full Package to a short folder (a short path like C:\PL\ avoids path-too-long errors).

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, choose the core install mode (Fresh or Compatible) and tick "Deconvolution (DeconvolutionLab2)" in the app list.

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

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

This plugin is unticked by default. In the app list the light menu items are ON by default, while all plugins (including this one) are OFF; you must tick it to install and enable it.

After restarting, the plugin appears in the Dragonfly menu bar at:

Prototype Apps > Deconvolution (DeconvolutionLab2)...

It belongs to the Filtering & Restoration group. Clicking it opens a dockable floating panel.

Changing your choice later

The easiest way is inside Dragonfly: open Developer > Prototype Labs... > Menu Item Manager; the "Prototype Apps (Full Package)" list at the bottom has a checkbox per app - tick = deploy, untick = remove the menu entry. Restart Dragonfly to apply. Disabling never deletes your configured settings (such as the Fiji path); re-enabling is instant.

Alternatively, re-run the installer anytime (it remembers your previous choices as defaults); even after deleting the unzipped folder, run %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat.

Uninstall

Double-click `Uninstall_FullPackage.bat` in the Full Package's installer folder to remove all Full Package menu items and plugins. It does not touch your local Fiji installation.

4. Runtime Environment and First-Run Setup

The plugin's environment kind is external_app: it creates no Python virtual environment (venv), needs no GPU, and does not use WSL. Its only external dependency is a locally installed Fiji / ImageJ plus DeconvolutionLab2 inside Fiji.

Before first use you therefore need two things: (A) let the plugin find your Fiji launcher; (B) confirm DeconvolutionLab2 is installed in Fiji.

A. Locate Fiji / ImageJ

• On open, the panel auto-detects Fiji: it checks the saved config path, the DF_FIJI_PATH environment variable, and a set of common locations (%LOCALAPPDATA%, Program Files, the user profile, Desktop, Downloads, and Fiji.app / Fiji / ImageJ folders under C:\/D:\/E:\).
• Supported launcher names include ImageJ-win64.exe, fiji-windows-x64.exe, fiji.exe, ImageJ-win32.exe, ImageJ.exe.
• If auto-detection fails, click Locate to retry, or Browse... to pick the launcher manually (the classic ImageJ-win64.exe has the most reliable headless -batch behavior).
• You can also set the DF_FIJI_PATH environment variable to the launcher or to a Fiji install directory.

B. Set up / check DeconvolutionLab2

Click Check / Install DeconvolutionLab2: the plugin scans the selected Fiji install's plugins and jars folders for a jar/class whose name contains deconvolutionlab.

• If detected: a "DeconvolutionLab2 detected" message shows its path in the status bar. No further action needed.
• If not detected: an "Install DeconvolutionLab2?" prompt appears. Choosing Yes runs Fiji's updater commands in the background to add the DeconvolutionLab2 update site and apply updates.

The update site added is:

DeconvolutionLab2 -> https://sites.imagej.net/DeconvolutionLab2/

Internet: only installing / updating the DeconvolutionLab2 update site needs internet; normal deconvolution runs do not. Installation can take a few minutes, and Fiji often needs a restart to load newly installed jars - if the command is not available right after install, restart Fiji / Dragonfly.

Fallbacks if install fails

• Do it manually in Fiji: Help > Update > Manage update sites, enable the DeconvolutionLab2 site, apply updates, and restart.
• Or drop DeconvolutionLab2_.jar directly into Fiji's plugins folder and run it via Fiji's bundled Java.
• On a failed run the plugin keeps the temporary working-directory path in the error text so you can inspect the Fiji output manually.

Configured settings (Fiji path, heap, PSF mode, etc.) are saved in the plugin's deconvolutionlab2_config.json, which is preserved across re-installs so your settings are not lost.

5. Interface Guide

The panel is a stack of group boxes from top to bottom, described below.

Input image (Channel)

• Dropdown: lists the image Channels currently available in Dragonfly (shown as "title (Z, Y, X)").
• Refresh button: rescans the current session's Channels and refreshes both dropdowns (input image and PSF Channel).

PSF (point spread function)

• PSF Channel (radio): when selected, a dropdown appears below to choose an existing Channel as the measured PSF.
• Synthetic Gaussian (radio, default): when selected, a Gaussian sigma (voxels) spin box appears; a Gaussian PSF is synthesized from that sigma (in voxels).
• Gaussian sigma (voxels): Gaussian sigma, range 0.1-100.0, step 0.5, default 2.0.

Algorithm

• Algorithm dropdown: pick 1 of 6 (RL / RL-TV / FISTA / Tikhonov / Wiener / Landweber).
• Parameter area: the parameter controls (iterations, regularization lambda, step gamma, etc.) are shown dynamically for the selected algorithm (see Chapter 7).
• Note text: a gray line below briefly describes the selected algorithm.

Fiji / DeconvolutionLab2

• Launcher (text field): the Fiji/ImageJ launcher path, with placeholder path to ImageJ-win64.exe / fiji-windows-x64.exe. Beside it are Locate (auto-detect) and Browse... (manual pick) buttons.
• Max heap (spin box): JVM max heap in MB, range 0-262144, step 512, default 4096. Raise it for large volumes or many iterations.
• Check / Install DeconvolutionLab2 (button): check for or install DeconvolutionLab2 (see Chapter 4).

Output

• Channel suffix (text field): the suffix for the output Channel name, default Deconvolved. The final name is "<source Channel title> - <suffix>".

Run and log

• Run Deconvolution + Create Channel (blue primary button): starts a full deconvolution run and creates the new Channel. The run and check buttons are disabled while a job is running.
• Status bar: shows short status (number of Channels found, DeconvolutionLab2 detection, run result, etc.).
• Log box (read-only): shows detailed step-by-step text (export, Fiji run, import, errors).

6. Usage Steps

Here is a complete end-to-end deconvolution run. Prerequisite: an image Channel already exists in Dragonfly (the plugin does not acquire images; it only processes existing Channels).

1. Open Prototype Apps > Deconvolution (DeconvolutionLab2)....

2. In Input image (Channel), select the Channel to restore; click Refresh first if needed.

3. In the PSF group choose the PSF source: with a measured PSF pick PSF Channel and select it in the dropdown; otherwise pick Synthetic Gaussian and set Gaussian sigma (default 2.0).

4. In the Algorithm dropdown choose an algorithm and adjust its parameters (iterations, regularization lambda, step gamma). If unsure, start with Richardson-Lucy (RL) at 10 iterations.

5. In the Fiji / DeconvolutionLab2 group confirm the Launcher points to a valid Fiji launcher (via Locate or Browse...); adjust Max heap if needed.

6. Click Check / Install DeconvolutionLab2 to confirm the engine is ready (first time may need internet to install, then a restart).

7. In the Output group adjust the Channel suffix if desired (default Deconvolved).

8. Click Run Deconvolution + Create Channel. The plugin exports the image and PSF as TIFFs, launches Fiji headlessly to run DeconvolutionLab2, and imports the result. Follow progress in the log box.

9. On success the log shows "Created Channel '...'" with its shape; the new deconvolved Channel is published to Dragonfly and visible in the object list and views.

Timing: Fiji / DeconvolutionLab2 runs as an external process, so large volumes or high iteration counts can be slow and need enough JVM heap (Max heap). For a first run, validate parameters quickly with fewer iterations or a cropped sub-volume.

7. Parameter Reference

General panel parameters (algorithm-independent):

Per-algorithm parameters (passed in DeconvolutionLab2's expected order; iterations are clamped to >= 1, regularization / step to >= 0):

Tuning tips: more iterations sharpen more but amplify noise and cost more time; regularized algorithms (RL-TV, FISTA, TM) suppress noise by increasing lambda. DeconvolutionLab2 command/parameter names can vary between builds; if a token is unavailable, the plugin reports Fiji's stderr / stdout to the log.

8. Output

A successful run produces one new image Channel in Dragonfly:

• Object type: Channel (image), created and published from the deconvolved TIFF via createChannelFromNumpyArray.
• Naming: "<source Channel title> - <suffix>", suffix defaulting to Deconvolved.
• Geometry alignment: the new Channel restores the source grid where possible - reusing the source voxel spacing and origin - so it is spatially aligned with the original and can be overlaid for comparison.
• Data type: the restored image is written as float32 (floating point).

How to view it: the new Channel is published to Dragonfly's object list automatically and can be displayed in 2D / 3D views. Placing it in the same view as the original and toggling display lets you compare sharpness before and after deconvolution.

Temporary files: the input TIFF, PSF TIFF, output TIFF, and macro are placed in a decolab_... working folder under the OS temp directory. On success the log prints this "Job folder" path; on failure the path is kept so you can inspect the Fiji output manually. These temp files do not affect the Channel created in Dragonfly.

9. FAQ and Troubleshooting

Q1: The panel cannot find Fiji / ImageJ - what do I do?

First click Locate to auto-detect again; if it still fails, click Browse... and pick the launcher manually (the classic ImageJ-win64.exe is recommended). You can also set the DF_FIJI_PATH environment variable to the launcher or to a Fiji directory. If Fiji is not installed on this machine yet, install Fiji from the official source first.

Q2: DeconvolutionLab2 is not detected / still unavailable after install?

Click Check / Install DeconvolutionLab2 and choose Yes to enable the DeconvolutionLab2 update site (needs internet, may take a few minutes). After installing, Fiji usually needs a restart to load the new jar - restart Fiji / Dragonfly and retry. If auto-install fails, do it manually in Fiji via Help > Update > Manage update sites > DeconvolutionLab2, or drop DeconvolutionLab2_.jar into Fiji's plugins folder.

Q3: The run errors with "Fiji produced no output TIFF" or a non-zero exit code?

This usually means the Fiji / DeconvolutionLab2 command did not produce a result. Check: (1) DeconvolutionLab2 really is installed and usable; (2) the selected algorithm token exists in your DeconvolutionLab2 build (command names can differ between builds); (3) the Fiji stderr / stdout in the log box. The log keeps the temporary working-directory path so you can inspect the input / output TIFFs and macro manually.

Q4: The deconvolved result looks worse / shows noise or artifacts?

The most common cause is an inaccurate PSF. The synthetic Gaussian is only a rough approximation - use a measured PSF Channel if you can. Second, too many iterations amplify noise - reduce iterations, or switch to a regularized algorithm (RL-TV / FISTA / TM) and increase the regularization lambda. It also helps to test a few parameter sets on a small cropped region before applying to the full image.

Q5: Processing is slow or runs out of memory?

DeconvolutionLab2 runs in an external JVM, so large volumes plus high iteration counts are slow. You can raise Max heap (default 4096 MB) to give the JVM more memory, reduce iterations, or validate first on a cropped sub-volume.

Q6: The input image dropdown is empty?

There is no usable image Channel in the current Dragonfly session, or the list has not been refreshed. Load or create an image Channel in Dragonfly first, then click Refresh on the panel to rescan.

10. Notes and Known Limitations

• Requires an existing Channel: the plugin only processes an existing image Channel in Dragonfly; it does not acquire or import the source image.
• A good PSF matters: prefer a measured PSF Channel when available; the synthetic Gaussian is only a rough approximation.
• External-process overhead: Fiji / DeconvolutionLab2 runs as an external process, so large volumes and high iteration counts take time and need enough JVM heap.
• Best-effort geometry: the output Channel restores the source geometry (spacing / origin) where possible, depending on whether the TIFF metadata is read back correctly.
• Build-dependent command names: DeconvolutionLab2 command/parameter names can vary between builds; the algorithm list uses standard DeconvolutionLab2 tokens and reports Fiji stderr / stdout when a command is unavailable.
• Internet only for install: internet is needed only to enable / update the DeconvolutionLab2 update site; normal runs need no internet, no Python venv, and no GPU.
• GPL isolation: DeconvolutionLab2 (GPL-3.0) always runs only as a separate Fiji Java subprocess; it is never imported into the Dragonfly process and never bundled.

11. References

• DeconvolutionLab2 update site: https://sites.imagej.net/DeconvolutionLab2/
• DeconvolutionLab2 reference: Sage et al., Methods, 2017 (the DeconvolutionLab2 algorithm framework).
• Fiji / ImageJ: the open-source image-processing platform that provides DeconvolutionLab2 as an update site.
• Fiji update-site manager: Fiji menu Help > Update > Manage update sites.