ImageJ / Fiji Bridge（ImageJ/Fiji 桥接）
ImageJ / Fiji Bridge - User Manual
Dragonfly Prototype Apps · ImageJ / Fiji Bridge...
版本 Version 2.0 · 2026-07-31
第一部分 中文手册
目录
1. 简介
2. 适用场景
3. 安装与启用
4. 运行环境与首次配置
5. 界面说明
6. 使用步骤
7. 参数说明
8. 输出结果
9. 常见问题与故障排除
10. 注意事项与已知限制
11. 参考资料
1. 简介
ImageJ / Fiji Bridge 把 Dragonfly 和您本机安装的 Fiji/ImageJ 连起来：在面板里挑选 Dragonfly 中已发布的对象，选一个内置命令或者写一段宏（macro），插件会把这些对象导出成 ImageJ 格式的 TIFF，以无界面（headless）方式驱动本机 Fiji 处理，再把结果带回 Dragonfly。
从 2.0 版起，一次运行可以处理多个输入、时间序列的指定时间点、以及 MultiROI/ROI 标签，并且可以同时带回三种结果：新的 Channel、新的 MultiROI，以及 ImageJ 的测量结果表。
实现方式是一个作业目录（job folder）：插件为每次运行建立一个文件夹，把输入写成固定名字的文件，宏只需要知道这个文件夹。
文件 | 方向 | 含义 |
| → ImageJ | 图像输入，顺序就是您在列表里排的顺序 |
| → ImageJ | MultiROI（保留标签编号）或 ROI（0/255 掩膜） |
| → ImageJ | 标题、体素间距、时间点数、数据类型等信息 |
| ← ImageJ | 结果图像（可以是 4 维 hyperstack），回传为 Channel |
| ← ImageJ | 结果标签图像，回传为 MultiROI |
| ← ImageJ | ImageJ 的 Results 表，显示在面板的“结果表”页签 |
| ← ImageJ | Fiji 进程的全部输出，排查问题时看这个 |
老版本的 <输入>|<输出> 约定完全保留：您自己写过、保存在“我的宏”里的宏仍然按原样运行。宏用哪种约定，由宏自己声明（// @protocol job 或 // @protocol legacy），而不是由插件猜。
2. 适用场景
- 想直接复用 ImageJ/Fiji 庞大生态（插件、宏、算法）的用户：生命科学显微图像分析、材料图像处理。
- 双输入运算：减背景采集、除以本底（flat field）、两个时间点相减 —— 用 Image Calculator。
- 只要数字不要图像：Analyze Particles 逐对象测量、逐层灰度统计，结果直接以表格呈现，可另存 CSV。
- 要标签对象：把阈值分割的结果标记成一个个对象，作为 MultiROI 带回 Dragonfly，继续用 Dragonfly 的测量与显示功能。
- 时间序列：只处理 4 维图像中您关心的那几个时间点，既省内存也省时间。
- 用 MultiROI 当掩膜：只保留标签覆盖的区域，其余置 0。
3. 安装与启用
本插件随 Prototype Apps 一起分发。用安装程序（install_prototype_apps.exe）或 Dragonfly 内的 App Store 启用它即可；菜单位置是 Prototype Apps ▸ Detection & Bridges ▸ ImageJ / Fiji Bridge...。
菜单是在 Dragonfly 启动时构建的，所以新装或新启用之后需要重启一次 Dragonfly 才能看到条目。
4. 运行环境与首次配置
不需要任何 Python 虚拟环境，也不下载任何东西：TIFF 读写用的是 Dragonfly 自带的 tifffile（没有它时退回 Pillow）。唯一的外部依赖是本机安装的 Fiji/ImageJ，可从 https://fiji.sc 免费下载。
1. 打开面板，看 Fiji / ImageJ 一栏。插件会自动在常见位置搜索，多数情况下已经填好。
2. 没找到就点 Browse...，选择 Fiji 安装目录里的启动程序。请优先选 ImageJ-win64.exe。
3. 如果处理的是大体积数据，把 Max heap 调大（默认 4096 MB）。
4. 路径与堆大小会记在插件目录下的 imagej_config.json 里，下次自动带出。
为什么强调 ImageJ-win64.exe：新的 Jaunch 启动器（fiji-windows-x64.exe / fiji.exe）无法正确执行无界面宏 —— 它会返回“成功”却什么都没做。插件检测到 Jaunch 启动器时，会自动改用同一 Fiji.app 目录下的 ImageJ-win64.exe，并在日志里说明。
也可以用环境变量 DF_FIJI_PATH 指定启动程序路径。
5. 界面说明
输入对象（Inputs）
上方列表就是这次运行的输入清单，每一行显示它会变成哪个作业文件（in_1.tif / labels_1.tif）、类型、名称、尺寸、时间点数和标签数。下方下拉框列出当前会话中已发布的 Channel、MultiROI 和 ROI，点 添加 加入列表；上移/下移 改变顺序 —— 顺序决定谁是 in_1，这是与宏之间的约定。图像和 MultiROI/ROI 各自独立编号。
选中一行 4 维（时间序列）输入时，下面的时间点一栏可用：勾 All 表示全部，或者取消勾选后指定 from/to 范围。范围记在这一行上，切换选择再切回来仍然是您设定的值。
操作（Operation）
三种方式：内置命令（带参数的常用 ImageJ 操作）、自定义宏（可从宏库载入预设再改）、宏文件（.ijm）。内置命令会说明它需要几个输入、是否需要 MultiROI，以及会不会改变数据类型。
回传内容（Bring back）
三个勾选框：图像 → 新 Channel、标签 → 新 MultiROI、测量结果表。选择内置命令时，插件会自动勾选该命令能产生的项，并禁用它产生不了的项 —— 只测量的命令不会假装能给您一幅图像。
运行与诊断
Run in Fiji + Import 开始运行，Cancel 中止，Open job folder 打开这次的作业文件夹（里面有导出的输入、真正运行的宏和 runner_log.txt）。下方两个页签分别是运行日志和结果表；结果表可以 另存为 CSV。
6. 使用步骤
1. 在 Dragonfly 里准备好数据，并确保对象已发布（未发布的对象不会出现在下拉框里）。
2. 打开 Prototype Apps ▸ Detection & Bridges ▸ ImageJ / Fiji Bridge...。
3. 确认 Fiji 启动程序路径。
4. 在下拉框选择对象，点 添加；需要第二个图像或标签输入时重复一次，必要时用上移/下移调整顺序。
5. 4 维输入若只想处理部分时间点，选中该行后设置时间点范围。
6. 选一个内置命令并填参数，或切到自定义宏、从宏库载入一个预设再修改。
7. 核对回传内容的勾选，以及输入清单下方那句提示（它会告诉您还缺什么）。
8. 点 Run in Fiji + Import。运行过程中的输出会实时写进日志页签。
9. 结束后：新的 Channel / MultiROI 出现在 Dragonfly 对象列表中，测量结果表出现在结果表页签。
7. 参数说明
参数 | 含义 |
Launcher | Fiji/ImageJ 启动程序路径。建议 |
Max heap | 给 Fiji 的 JVM 最大堆内存（MB），0 表示用启动器默认值。体积大就加大。 |
Output suffix | 结果名称的后缀，最终名字是 |
时间点 All / from / to | 该输入参与运行的时间点范围（从 1 开始计数，含两端）。 |
Threshold method | 自动阈值方法（Otsu、Huang、Li、MaxEntropy、Mean、Triangle、Yen、Default），沿用 ImageJ 的命名。 |
Min size (px) | Analyze Particles 的最小对象尺寸（像素），小于它的对象被忽略。 |
Operation | Image Calculator 的运算：Add、Subtract、Multiply、Divide、AND、OR、XOR、Min、Max、Average、Difference。 |
Sigma / Radius / Iterations | 各滤波与形态学命令自身的参数，含义与 ImageJ 中同名命令一致。 |
宏里可以用的变量
变量 | 含义 |
| 作业文件夹路径（末尾带斜杠） |
|
|
|
|
| 默认 1，表示运行结束时把当前图像存成 |
宏若测量了任何东西（nResults > 0），Results 表会自动保存为 results.csv，不需要您自己写 saveAs。
8. 输出结果
- 新的 Channel（来自
out.tif）：名称为<输入名> - <后缀>。整数结果保持整数（8/16 位不会被强制转成浮点），体素间距与原点尽量沿用；4 维结果保留时间轴。 - 新的 MultiROI（来自
out_labels.tif）：标签会被重新编号为连续的 1..N，并赋予默认颜色。 - 测量结果表（来自
results.csv）：显示在结果表页签，数字列右对齐，可另存 CSV。 - 作业文件夹：导出的输入、
job.json、真正运行的macro.ijm和runner_log.txt都留在磁盘上，成功失败都不会自动删除 —— 这正是排查问题的依据。
9. 常见问题与故障排除
找不到 Fiji。 点 Browse 手动指向 ImageJ-win64.exe，或设置 DF_FIJI_PATH。还没有 Fiji 就先从 https://fiji.sc 下载。
Fiji“运行成功”但什么结果都没有。 十有八九用了 Jaunch 启动器（fiji-windows-x64.exe）。改用同目录的 ImageJ-win64.exe。日志与错误信息里也会这样提示。
提示没有产生 out.tif / out_labels.tif / results.csv。 打开作业文件夹看 runner_log.txt：通常是宏里的命令名或参数写错，或者该命令需要图形界面（无界面模式下不可用），或者需要的 Fiji 插件没装。
用了 MorphoLibJ 的预设却报错找不到命令。 在 Fiji 里通过 Help ▸ Update... 启用 IJPB-plugins 更新站点，重启 Fiji 后再试。
回传的图像看起来只剩一种颜色。 Dragonfly 的一个 Channel 每个体素只存一个值，所以 ImageJ 返回彩色图（例如 Analyze Skeleton 的着色骨架）时只能取第 1 个通道，日志里会写明。需要三个通道请在宏里自行拆分并分别输出。
标签结果导入失败，提示没有标签。 out_labels.tif 里所有体素都是 0，说明分割没有得到任何对象 —— 调整阈值方法或最小尺寸。
时间序列太大、内存吃紧。 用时间点范围分批处理：一次只导出您需要的那几个时间点。
运行直接被拒绝，说 TIFF 库自检未通过。 插件每次运行前会用已知数组做一次 TIFF 往返验证，验证不通过就不会开始 —— 与其写出读不回来的数据，不如当场停下。请把日志中的这段信息反馈给我们。
10. 注意事项与已知限制
- 方向矩阵（orientation）不随数据传递：本版本只传递体素间距与原点。若您的数据带有旋转/斜切的方向信息，回传结果的方向信息不会被还原。
- 一次运行只能带回一个 MultiROI（
out_labels.tif）和一个 Channel（out.tif）。 - MultiROI 没有时间轴：如果标签结果是 4 维的，只会使用第 1 个时间点，日志会说明。
- 声明为
legacy约定的宏只能拿到第一个 Channel；想用多输入，请按作业约定改写（用dir和in_1.tif）。 - ROI 导出为 0/255 掩膜，MultiROI 导出为标签编号 —— 这与 ImageJ 二值命令的习惯一致，写宏时请注意区别。
- 无界面模式下不可用的 ImageJ 命令（需要窗口、需要交互的）在这里同样不可用。
- 插件本身不安装、不更新 Fiji，也不会替您启用更新站点。
11. 参考资料
- Fiji / ImageJ：https://fiji.sc ；ImageJ 宏语言：https://imagej.net/ij/developer/macro/functions.html
- Analyze Particles / 颗粒分析：https://imagej.net/imaging/particle-analysis
- Image Calculator：https://imagej.net/ij/docs/menus/process.html#calculator
- MorphoLibJ：https://imagej.net/plugins/morpholibj ；Legland 等 2016，doi:10.1093/bioinformatics/btw413
- ImageJ 无界面模式：https://imagej.net/learn/headless
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
ImageJ / Fiji Bridge connects Dragonfly to the Fiji/ImageJ you already have installed: pick published Dragonfly objects in the panel, choose a built-in command or write a macro, and the plugin exports those objects as ImageJ TIFFs, drives your local Fiji headlessly to process them, and brings the results back into Dragonfly.
Since version 2.0 a single run can take several inputs, a chosen range of time points, and MultiROI/ROI labels, and can bring back three things at once: a new Channel, a new MultiROI, and ImageJ's measurements table.
The mechanism is a job folder: the plugin creates one folder per run, writes the inputs there under fixed names, and the macro only needs to know that folder.
File | Direction | Meaning |
| → ImageJ | image inputs, in the order you arranged them |
| → ImageJ | a MultiROI (label ids kept) or an ROI (0/255 mask) |
| → ImageJ | titles, voxel spacing, time-point count, data type |
| ← ImageJ | result image (may be a 4-D hyperstack) → a Channel |
| ← ImageJ | result label image → a MultiROI |
| ← ImageJ | the ImageJ Results table → the panel's Results tab |
| ← ImageJ | everything Fiji printed; the first place to look |
The older <in>|<out> contract still works exactly as before, so macros you wrote and saved in "My Macros" keep running. Which contract a macro wants is declared by the macro (// @protocol job or // @protocol legacy) rather than guessed.
2. Use cases
- Reusing ImageJ/Fiji's huge ecosystem (plugins, macros, algorithms) directly: life-science microscopy, materials image processing.
- Two-input arithmetic: subtract a background acquisition, divide by a flat field, difference two time points - with Image Calculator.
- Numbers, not pixels: Analyze Particles per object, or per-slice intensity statistics, shown as a table you can save as CSV.
- Labelled objects: turn a threshold result into one object per particle and bring it back as a MultiROI for Dragonfly's own measurement and display tools.
- Time series: process only the time points you care about in a 4-D image, saving both memory and time.
- A MultiROI as a mask: keep only what the labels cover and zero the rest.
3. Installation & enabling
The plugin ships with Prototype Apps. Enable it with the installer (install_prototype_apps.exe) or from the App Store inside Dragonfly; the menu entry is Prototype Apps ▸ Detection & Bridges ▸ ImageJ / Fiji Bridge....
Menus are built when Dragonfly starts, so restart Dragonfly once after installing or enabling it.
4. Runtime environment & first-run setup
There is no Python virtual environment to build and nothing to download: TIFF I/O uses Dragonfly's bundled tifffile (falling back to Pillow). The only external dependency is a locally installed Fiji/ImageJ, free from https://fiji.sc.
1. Open the panel and look at the Fiji / ImageJ group. The plugin searches the usual locations, so it is often already filled in.
2. If not, click Browse... and pick the launcher inside your Fiji installation. Prefer ImageJ-win64.exe.
3. Raise Max heap (default 4096 MB) for large volumes.
4. The path and heap size are remembered in imagej_config.json next to the plugin code.
Why ImageJ-win64.exe matters: the newer Jaunch launcher (fiji-windows-x64.exe / fiji.exe) does not run a headless macro - it reports success having done nothing. When the plugin sees a Jaunch launcher it switches to the ImageJ-win64.exe sibling in the same Fiji.app and says so in the log.
The environment variable DF_FIJI_PATH can also point at the launcher.
5. Interface
Inputs
The list at the top is this run's inputs. Each row shows which job file it becomes (in_1.tif / labels_1.tif), its type, name, shape, time-point count and label count. The combo below lists every published Channel, MultiROI and ROI in the session; Add puts one in the list and Move up/Move down reorder it - the order decides which object is in_1, which is the contract with the macro. Images and MultiROIs/ROIs are numbered in separate sequences.
Selecting a 4-D (time series) row enables the time points row: All, or an explicit from/to range. The range belongs to that input, so selecting another row and coming back keeps what you set.
Operation
Three ways: a built-in command (a common ImageJ operation with parameters), a custom macro (load a preset from the library and edit it), or a macro file (.ijm). A built-in command states how many inputs it needs, whether it needs a MultiROI, and whether it changes the data type.
Bring back
Three tick boxes: image → new Channel, labels → new MultiROI, measurements table. Choosing a built-in command ticks exactly what that command can produce and disables the rest - a measurement-only command will not pretend it can hand you an image.
Running and diagnosing
Run in Fiji + Import starts the run, Cancel stops it, and Open job folder opens this run's folder (the exported inputs, the macro that actually ran, and runner_log.txt). The two tabs below hold the log and the Results table; the table can be saved as CSV.
6. How to use
1. Prepare your data in Dragonfly and make sure the objects are published (unpublished objects are deliberately not offered).
2. Open Prototype Apps ▸ Detection & Bridges ▸ ImageJ / Fiji Bridge....
3. Check the Fiji launcher path.
4. Pick an object in the combo and click Add; repeat for a second image or a label input, and reorder if needed.
5. For a 4-D input, select its row and set the time-point range if you do not want all of them.
6. Choose a built-in command and its parameters, or switch to a custom macro and load a preset to edit.
7. Check the Bring back ticks and the hint under the input list - it tells you what is still missing.
8. Click Run in Fiji + Import. Output streams into the Log tab while Fiji works.
9. When it finishes, the new Channel / MultiROI appear in Dragonfly's object list and the table appears in the Results tab.
7. Parameters
Parameter | Meaning |
Launcher | Path to the Fiji/ImageJ launcher. Prefer |
Max heap | Maximum JVM heap for Fiji in MB; 0 uses the launcher default. Raise it for big volumes. |
Output suffix | Suffix of the result name, which becomes |
Time points All / from / to | Which time points of that input take part (1-based, inclusive). |
Threshold method | Auto-threshold method (Otsu, Huang, Li, MaxEntropy, Mean, Triangle, Yen, Default), named as in ImageJ. |
Min size (px) | Smallest object Analyze Particles keeps, in pixels. |
Operation | The Image Calculator operation: Add, Subtract, Multiply, Divide, AND, OR, XOR, Min, Max, Average, Difference. |
Sigma / Radius / Iterations | Each filter's own parameters, with the same meaning as in the identically named ImageJ command. |
Variables a macro can use
Variable | Meaning |
| the job folder, with a trailing slash |
| how many |
| how many |
| 1 by default: save the active image as |
If the macro measured anything (nResults > 0) the Results table is saved to results.csv automatically - no saveAs line needed.
8. Output
- A new Channel (from
out.tif), named<input> - <suffix>. Integer results stay integral (8/16-bit is not forced to float), voxel spacing and origin are carried over where possible, and a 4-D result keeps its time axis. - A new MultiROI (from
out_labels.tif): labels are renumbered to a consecutive 1..N and given default colours. - A measurements table (from
results.csv): shown in the Results tab with numeric columns right-aligned, and saveable as CSV. - The job folder: the exported inputs,
job.json, themacro.ijmthat actually ran andrunner_log.txtall stay on disk whether the run succeeded or failed - that is what you diagnose from.
9. FAQ & troubleshooting
Fiji is not found. Browse to ImageJ-win64.exe yourself, or set DF_FIJI_PATH. If you have no Fiji yet, download it from https://fiji.sc.
Fiji "succeeds" but produces nothing. Almost always the Jaunch launcher (fiji-windows-x64.exe). Use ImageJ-win64.exe from the same folder; the log and the error message say so too.
It says none of out.tif / out_labels.tif / results.csv was produced. Open the job folder and read runner_log.txt: usually a mistyped command or option, a command that needs a display (unavailable headless), or a missing Fiji plugin.
A MorphoLibJ preset reports an unknown command. Enable the IJPB-plugins update site in Fiji (Help ▸ Update...), restart Fiji, and try again.
The imported image looks like one colour only. A Dragonfly Channel holds one value per voxel, so when ImageJ returns a colour image (e.g. the tagged skeleton of Analyze Skeleton) only channel 1 can be kept, and the log says so. Split the channels in your macro and output them separately if you need all three.
The label import fails saying there are no labels. Every voxel in out_labels.tif is 0, i.e. the segmentation found nothing - adjust the threshold method or the minimum size.
A long time series runs out of memory. Use the time-point range and process it in batches: export only the frames you need.
The run is refused because the TIFF library failed its self-test. Before every run the plugin round-trips known arrays through TIFF; if that fails it stops rather than writing data it cannot read back. Please send us that log section.
10. Notes & known limitations
- Orientation matrices are not carried: this version transfers voxel spacing and origin only. If your data has a rotated or sheared orientation, the result's orientation is not restored.
- One run brings back at most one MultiROI (
out_labels.tif) and one Channel (out.tif). - A MultiROI has no time axis: if the label result is 4-D, only its first time point is used, and the log says so.
- A macro declaring the
legacycontract only receives the first Channel; rewrite it against the job contract (dir+in_1.tif) to use several inputs. - An ROI is exported as a 0/255 mask and a MultiROI as label ids - which matches what ImageJ's binary commands expect, but is a difference to keep in mind when writing macros.
- ImageJ commands that cannot run headless (needing a window or interaction) cannot run here either.
- The plugin never installs or updates Fiji, and never enables an update site for you.
11. References
- Fiji / ImageJ: https://fiji.sc ; the ImageJ macro language: https://imagej.net/ij/developer/macro/functions.html
- Particle analysis: https://imagej.net/imaging/particle-analysis
- Image Calculator: https://imagej.net/ij/docs/menus/process.html#calculator
- MorphoLibJ: https://imagej.net/plugins/morpholibj ; Legland et al. 2016, doi:10.1093/bioinformatics/btw413
- Running ImageJ headless: https://imagej.net/learn/headless