MorphoLibJ via Fiji 插件用户手册

MorphoLibJ via Fiji - User Manual

Dragonfly Prototype Apps · MorphoLibJ via Fiji...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

MorphoLibJ via Fiji 是一个 Dragonfly 插件,它把 Dragonfly 中已有的一个 ROI(感兴趣区域)桥接到本机安装的 Fiji / ImageJ,在 Fiji 里调用 MorphoLibJ(IJPB-plugins)的形态学与分割算法进行处理,再把 Fiji 生成的标签图(label image)导入回 Dragonfly,转换为一个 MultiROI(多区域对象)。

整个流程是基于文件交换的:插件先把选中的 ROI 导出为 Fiji 可读取的 二值 ImageJ TIFF(前景 = 255,背景 = 0,并写入 Dragonfly 的体素间距元数据),随后以 无界面(headless) 方式启动 Fiji 运行一段自动生成的 ImageJ 宏,让 MorphoLibJ 完成连通域标记 / 分水岭 / 形态学预处理,把结果保存为标签 TIFF;最后插件读取这张标签 TIFF,把每个正整数标签作为一个独立对象,构建成 Dragonfly 的 MultiROI 并发布到场景中。

底层引擎与算法:

• Fiji / ImageJ — 用户自行安装的图像处理平台,作为外部程序被本插件以无界面模式调用。
• MorphoLibJ(IJPB-plugins) — Fiji 的形态学与数学形态图像分析工具集,由 Fiji 的 IJPB-plugins 更新站点(https://sites.imagej.net/IJPB-plugins/)提供;本插件调用其 Connected Components Labeling、Distance Transform Watershed、Morphological Filters、Fill Holes 等命令。
• tifffile — 用于 ROI 与标签图的 TIFF 读写,由 Dragonfly 自带的 Python 提供,无需另行安装。

许可证要点:插件代码遵循 DragonflyPrototypeLabs 仓库相同的条款。本插件不捆绑任何 Fiji 或 MorphoLibJ 代码,它只是驱动用户自行、单独安装的 Fiji/ImageJ 与 MorphoLibJ 作为外部软件运行;Fiji 与 MorphoLibJ 各自的许可证条款以其官方发布为准。

本插件不负责创建源 ROI。请先在 Dragonfly 中准备好一个 ROI(例如经过阈值分割得到的孔隙、颗粒或细胞前景),再用本插件对它做对象级的拆分与形态学处理。

2. 适用场景

本插件面向已经拥有一个 Dragonfly ROI、并且希望复用 Fiji 中成熟的 MorphoLibJ 分割与形态学算法来生成对象级 MultiROI 的用户。典型用途包括:

• 连通域拆分:把一整块二值前景按连通性拆分成一个个独立对象(孔隙、颗粒、细胞、纤维片段等),每个对象成为 MultiROI 中的一个标签。
• 分水岭分割:对相互接触、粘连的对象,用 MorphoLibJ 的距离变换分水岭(Distance Transform Watershed)把它们分开,得到更贴合单个对象的分割结果。
• 形态学清理后再标记:先用开运算去除细小的桥接与噪点,或用闭运算填补小缝隙,或填补内部孔洞,然后再做连通域标记,得到更干净的对象集合。
• 在 Dragonfly 与 Fiji 之间打通工作流:让习惯 Fiji/MorphoLibJ 的用户无需手动导出导入,即可在 Dragonfly 里一键调用这些算法。

如果你需要的是与 Fiji 更通用的桥接(运行任意 ImageJ 内置操作或自定义宏),或不想依赖本机的 Fiji 安装,可考虑同一分组下的其他插件(如 ImageJ / Fiji Bridge、MorphoLibJ Remade by Python)。本插件专注于 ROI → MultiROI 这一条聚焦的形态学分割工作流。

3. 安装与启用

本插件随 Prototype Labs 完整安装包(Full Package) 分发,通过安装包一次性装入本机所有 Dragonfly 版本。

1. 把完整安装包 zip 解压到任意较短的目录(例如桌面或 C:\PL\;不要放在很深的下载目录或 OneDrive 重定向的桌面里,以免触发 Windows 路径过长错误)。

2. 双击 `Install_FullPackage.bat`。

3. 在弹出的对话框中选择核心安装模式(Fresh 全新安装 / Compatible 兼容安装,仅影响 Prototype Labs 核心的 blocks 与 recipes,不影响任何插件);在 Prototype Apps 列表中勾选 “MorphoLibJ via Fiji”。

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

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

所有插件在安装列表中默认不勾选。若不主动勾选,MorphoLibJ via Fiji 不会被部署。请务必在安装时勾选它,或按下文在 Menu Item Manager 中启用。

重启后,菜单项出现在:

Prototype Apps ▸ MorphoLibJ via Fiji...

该菜单位于 Prototype Apps 菜单下的 Detection & Bridges(检测与桥接) 分组中。点击后会打开一个可停靠的浮动面板。

以后修改启用状态

启用或停用本插件最方便的方式是在 Dragonfly 内操作:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部的 “Prototype Apps (Full Package)” 列表中找到本插件的复选框,勾选 = 部署菜单项,取消 = 移除菜单项;每次修改后重启一次 Dragonfly 生效。停用从不删除任何已配置内容,重新启用后立即可用。

也可以随时重新运行安装器(它会记住上次的选择作为默认值)。全部内容都安装在当前用户目录 %LOCALAPPDATA% 下,不需要管理员权限。

4. 运行环境与首次配置

本插件属于 外部程序(external app) 类型:它不创建任何 Python 虚拟环境(venv)、不需要 GPU、不需要 WSL,TIFF 的读写直接使用 Dragonfly 自带的 tifffile。因此它没有 “Setup Environment” 一类的重型环境搭建步骤。它唯一的外部依赖是用户本机安装的 Fiji / ImageJ,并在其中装有 MorphoLibJ。

4.1 安装 Fiji

如果本机还没有 Fiji,请先从 Fiji 官网 https://fiji.sc 下载并解压安装。插件会在打开面板时自动查找常见位置(如 %LOCALAPPDATA%、Program Files、桌面、下载目录以及各盘符根下的 Fiji.app / Fiji / ImageJ 等子目录)里的启动器(ImageJ-win64.exe、fiji-windows-x64.exe 等)。也可以通过环境变量 DF_FIJI_PATH 预先指定启动器路径。

4.2 让面板找到 Fiji 启动器

在面板的 Fiji / MorphoLibJ 分组中:

• 如果自动检测成功,启动器路径会自动填入 Launcher 文本框。
• 点击 Locate 让插件重新自动搜索一次。
• 点击 Browse... 手动选择启动器可执行文件(通常是 ImageJ-win64.exe 或 fiji-windows-x64.exe)。

当你选择的是较新的 Fiji(Jaunch)启动器时,插件会尽量在同目录下改用经典的 ImageJ-win64.exe 启动器来执行无界面批处理宏,因为经典启动器对 -batch(无界面运行)行为最稳定。

4.3 检测 / 安装 MorphoLibJ

点击 Check / Install MorphoLibJ 按钮:插件会扫描所选 Fiji 安装的 plugins、jars 等目录,查找文件名中包含 morpholibj 或 ijpb 的 jar/class 文件。

• 已检测到:弹窗提示 MorphoLibJ 的所在文件,状态栏显示 “MorphoLibJ detected: …”。
• 未检测到:弹出询问对话框 “Install MorphoLibJ?”。若选择 Yes,插件会以无界面方式调用 Fiji 的更新器命令,添加 IJPB-plugins 更新站点(https://sites.imagej.net/IJPB-plugins/)并应用更新。

安装/更新 MorphoLibJ 时需要联网(需要访问 IJPB-plugins 更新站点),整个过程可能需要几分钟。安装完成后,新命令有时不会立即生效——如果状态栏提示按文件扫描仍未找到,请重启 Fiji / Dragonfly,或在 Fiji 里通过 Help ▸ Update ▸ Manage update sites ▸ IJPB-plugins 手动安装。正常的图像处理(即已装好 MorphoLibJ 后运行算法)本身不需要联网。

4.4 内存(JVM 堆)设置

面板的 Max heap 数值框设置 Fiji JVM 的最大堆内存,默认 4096 MB。处理较大的三维体数据时,可适当调高以避免 Fiji 内存不足。

面板中填写的启动器路径、堆大小与输出后缀会保存在插件代码目录下的 morpholibj_config.json 中,下次打开面板时自动恢复。

5. 界面说明

面板顶部是一句功能说明。下面按从上到下的分组逐一说明各控件(与插件代码一致)。

5.1 Input ROI(输入 ROI)

• ROI 下拉框:列出当前 Dragonfly 场景中可用的 ROI。列表优先展示当前选中的 ROI,并汇总所有 ROI 实例;每一项显示 ROI 标题,后面附带其形状尺寸(Z × Y × X)。
• Refresh 按钮:重新扫描并刷新 ROI 列表。刷新完成后状态栏会显示 “Found N ROI(s).”。

5.2 MorphoLibJ operation(MorphoLibJ 操作)

• 操作下拉框:选择要执行的 MorphoLibJ 操作,共 5 种(见第 7 章参数说明)。
• 参数区:随所选操作动态变化,展示该操作的可调参数(下拉框 / 整数框 / 浮点框)。
• 说明文字:灰色小字,显示当前操作的简短说明。

5.3 Fiji / MorphoLibJ

• Launcher(启动器)文本框:Fiji/ImageJ 启动器可执行文件的完整路径;占位提示为 path to ImageJ-win64.exe / fiji-windows-x64.exe。
• Locate 按钮:自动搜索本机 Fiji 启动器并填入。
• Browse... 按钮:打开文件对话框手动选择启动器(过滤器为 *.exe)。
• Max heap 数值框:Fiji JVM 最大堆内存,单位 MB,默认 4096,步进 512,范围 0–262144。
• Check / Install MorphoLibJ 按钮:检测所选 Fiji 是否已安装 MorphoLibJ;未安装时询问是否安装 IJPB-plugins 更新站点。

5.4 Output(输出)

• MultiROI suffix(输出后缀)文本框:输出 MultiROI 名称的后缀,默认 `MorphoLibJ`。最终输出名为 <ROI 标题> - <后缀>。

5.5 运行与日志

• Run MorphoLibJ + Create MultiROI 按钮(蓝底白字):启动完整流程——导出 ROI、运行 Fiji 宏、导入结果为 MultiROI。
• 状态栏:显示当前状态(找到多少 ROI、是否检测到 MorphoLibJ、完成或失败等)。
• 日志区:只读文本框,显示逐步进度、Fiji 的报错行以及最终结果;运行过程中,Run 与 Check/Install 按钮会被禁用以避免重复触发。

6. 使用步骤

下面是从一个已有 ROI 到得到 MultiROI 的完整端到端步骤。

前提:Dragonfly 场景中已存在一个 ROI;本机已安装 Fiji;Fiji 中已安装 MorphoLibJ(或准备在流程中按提示安装)。

1. 打开 Prototype Apps ▸ MorphoLibJ via Fiji...,弹出面板。

2. 在 Input ROI 分组中,从下拉框选择要处理的 ROI;若列表不完整,点击 Refresh 刷新。

3. 在 MorphoLibJ operation 分组中选择操作(如 Distance Transform Watershed),并按需调整下方出现的参数(如 Connectivity、Dynamic、Radius)。

4. 在 Fiji / MorphoLibJ 分组中确认 Launcher 路径已正确填入;若为空或错误,点击 Locate 或 Browse... 指定;必要时调整 Max heap。

5. (首次使用建议)点击 Check / Install MorphoLibJ 确认 MorphoLibJ 已就绪;若提示未安装,按需选择安装(需联网),完成后如提示未生效则重启 Fiji/Dragonfly。

6. 在 Output 分组中,按需修改 MultiROI suffix(默认 MorphoLibJ)。

7. 点击 Run MorphoLibJ + Create MultiROI。插件会:导出 ROI 为二值 TIFF → 无界面启动 Fiji 运行 MorphoLibJ 宏 → 生成标签 TIFF → 导入回 Dragonfly 转为 MultiROI。

8. 关注状态栏与日志:成功时状态栏显示 “Done: created MultiROI with N label(s).”,日志给出创建的 MultiROI 名称与标签数量;新 MultiROI 会发布到 Dragonfly 场景中。

运行时会自动检查 MorphoLibJ 是否就绪(相当于在后台又做了一次 Check/Install)。如果尚未安装且你选择了安装,本次运行不会自动继续——因为 Fiji 装完新插件后往往需要重启才能加载,请安装并重启后再次点击 Run。

7. 参数说明

下表列出面板中所有可调参数、默认值与含义。参数区会随所选操作动态显示对应参数。

7.1 五种操作

8. 输出结果

成功运行后,插件在 Dragonfly 中生成并发布一个 MultiROI(多区域对象):

• 名称:<源 ROI 标题> - <MultiROI 后缀>(后缀默认 MorphoLibJ)。
• 内容:标签 TIFF 中每个非零标签被重新编号并作为 MultiROI 的一个独立对象;标签数量在日志中报告(“Created MultiROI '…' with N label(s).”)。
• 几何:插件尽量沿用源 ROI 的体素间距(spacing)与原点(origin),使 MultiROI 与源数据在空间上对齐。
• 外观:导入后会为各标签指定默认颜色(assignDefaultColors)。

查看方式:在 Dragonfly 的对象浏览器 / 数据面板中找到该 MultiROI,勾选其可见性即可在 2D/3D 视图中查看;可像普通 MultiROI 一样进一步做测量、按标量着色、导出等操作。

中间文件:导出的输入 TIFF、宏文件与标签 TIFF 都写在操作系统临时目录下一个以 morpholibj_ 开头的作业文件夹中。成功导入后仍会在日志中打印该作业文件夹路径,便于需要时手动检查 Fiji 的输入/输出;失败时错误文本也会保留这些路径供排查。

9. 常见问题与故障排除

Q1:点击 Run 后提示 “set the Fiji/ImageJ launcher path.” 或找不到 Fiji?

A:说明面板没有拿到有效的 Fiji 启动器。请先安装 Fiji(https://fiji.sc),然后点击 Locate 自动搜索,或用 Browse... 手动选择 ImageJ-win64.exe / fiji-windows-x64.exe。也可用环境变量 DF_FIJI_PATH 指定路径。

Q2:提示未检测到 MorphoLibJ,或运行报某个命令不可用?

A:点击 Check / Install MorphoLibJ,按提示安装 IJPB-plugins 更新站点(需联网)。安装完成后如仍未生效,请重启 Fiji/Dragonfly;或在 Fiji 中通过 Help ▸ Update ▸ Manage update sites ▸ IJPB-plugins 手动安装。注意不同 Fiji 版本的 MorphoLibJ 命令名可能略有差异,日志会回显 Fiji 的 stdout/stderr 以帮助定位。

Q3:ROI 下拉框是空的?

A:本插件不创建 ROI,只处理已有 ROI。请先在 Dragonfly 中准备好一个 ROI(例如阈值分割得到的前景),再回到面板点击 Refresh 刷新列表。

Q4:运行失败、Fiji 报内存不足,或大体数据很慢?

A:Fiji/MorphoLibJ 作为外部进程运行,大体数据耗时较长且需要足够的 JVM 堆。请调高 Max heap(默认 4096 MB),并耐心等待。若仍失败,可根据日志中打印的作业文件夹路径,手动在 Fiji 中打开输入 TIFF 与宏进行检查。

Q5:提示 “MorphoLibJ output contains no foreground labels” 或标签数为 0?

A:说明 Fiji 输出的标签图里没有任何前景对象。常见原因是源 ROI 本身为空,或所选形态学操作(如半径过大的开运算)把前景全部消除。请检查源 ROI 是否有前景,并适当减小 Radius 或更换操作。

10. 注意事项与已知限制

• 插件需要一个已存在的 Dragonfly ROI 作为输入,它不负责创建源 ROI。
• Fiji/MorphoLibJ 以外部进程运行,大体数据处理耗时较长,并需要足够的 JVM 堆内存(见 Max heap)。
• 输出 MultiROI 的几何在可能范围内沿用源 ROI 的几何;若源 ROI 几何信息不完整,可能退回到默认间距/原点。
• MorphoLibJ 命令名在不同 Fiji 构建之间可能不同;操作列表使用当前 MorphoLibJ/Fiji 安装中的标准命令名,遇到命令不可用时会回显 Fiji 的 stdout/stderr。
• 安装/更新 MorphoLibJ 需要联网;安装完成后新命令可能要重启 Fiji/Dragonfly 才生效。
• MultiROI 标签基于 uint16 编号,单次导入的标签数上限为 65535;超出会报错。
• 菜单项只在 Dragonfly 启动时被扫描,启用/停用或更新代码后需重启一次 Dragonfly。

11. 参考资料

• Fiji(ImageJ 发行版)官网:https://fiji.sc
• MorphoLibJ / IJPB-plugins 更新站点:https://sites.imagej.net/IJPB-plugins/
• MorphoLibJ 项目主页(IJPB-plugins):https://imagej.net/plugins/morpholibj
• Prototype Labs 完整安装包安装/启用/卸载说明:随包 README.md 与 Dragonfly 内 Developer ▸ Prototype Labs... ▸ Menu Item Manager。

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. Parameters

8. Output

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

1. Overview

MorphoLibJ via Fiji is a Dragonfly plugin that bridges an existing Dragonfly ROI to a locally installed Fiji / ImageJ, runs MorphoLibJ (IJPB-plugins) morphology and segmentation algorithms inside Fiji, then imports the resulting label image back into Dragonfly as a MultiROI.

The workflow is file-based: the plugin first exports the selected ROI as a Fiji-readable binary ImageJ TIFF (foreground = 255, background = 0, with Dragonfly voxel-spacing metadata). It then launches Fiji headlessly to run an auto-generated ImageJ macro so MorphoLibJ performs connected-components labeling, watershed, or morphology-assisted labeling, saving the result as a label TIFF. Finally the plugin reads that label TIFF, treats each positive integer label as a separate object, builds a Dragonfly MultiROI and publishes it into the scene.

Underlying engines and algorithms:

• Fiji / ImageJ — the user's own image-processing platform, driven by this plugin as an external application in headless mode.
• MorphoLibJ (IJPB-plugins) — Fiji's mathematical-morphology image-analysis toolkit, provided by Fiji's IJPB-plugins update site (https://sites.imagej.net/IJPB-plugins/); this plugin calls its Connected Components Labeling, Distance Transform Watershed, Morphological Filters, and Fill Holes commands.
• tifffile — used for TIFF read/write of the ROI and label images, provided by Dragonfly's bundled Python (no separate install).

License notes: the plugin code follows the same terms as the DragonflyPrototypeLabs repository. The plugin bundles no Fiji or MorphoLibJ code; it merely drives a separately, user-installed Fiji/ImageJ and MorphoLibJ as external software. Fiji and MorphoLibJ each carry their own license terms as published officially.

This plugin does not create the source ROI. Prepare a ROI in Dragonfly first (for example a thresholded pore/grain/cell foreground), then use this plugin to split it into objects and apply morphology.

2. Use Cases

This plugin targets users who already have a Dragonfly ROI and want to reuse the mature MorphoLibJ segmentation and morphology algorithms in Fiji to produce object-level MultiROIs. Typical uses include:

• Connected-components splitting: break one binary foreground into individual objects (pores, grains, cells, fiber fragments, etc.) by connectivity, with each object becoming a label in the MultiROI.
• Watershed segmentation: for touching, merged objects, use MorphoLibJ's distance-transform watershed to separate them into individual objects.
• Morphology cleanup, then labeling: remove thin bridges and noise with an opening, close small gaps with a closing, or fill internal holes, then run connected-components labeling for a cleaner object set.
• Bridge Dragonfly and Fiji workflows: let users familiar with Fiji/MorphoLibJ call these algorithms from Dragonfly without manual export/import.

If you need a more general Fiji bridge (arbitrary ImageJ built-in operations or custom macros), or you prefer not to depend on a local Fiji install, consider the other plugins in the same group (such as ImageJ / Fiji Bridge, or MorphoLibJ Remade by Python). This plugin focuses on the single ROI → MultiROI morphology-segmentation workflow.

3. Installation and Enabling

This plugin ships with the Prototype Labs Full Package, which installs it into every Dragonfly version on the machine at once.

1. Unzip the Full Package to any short folder (Desktop or C:\PL\ is fine; avoid deep download folders or a OneDrive-redirected Desktop to prevent Windows path-too-long errors).

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, pick the core install mode (Fresh or Compatible — this affects only the Prototype Labs core blocks & recipes, not any plugin), and tick “MorphoLibJ via Fiji” in the Prototype Apps list.

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

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

All plugins are unticked by default in the installer list. If you do not tick it, MorphoLibJ via Fiji will not be deployed. Be sure to tick it at install time, or enable it later via the Menu Item Manager below.

After restart, the menu entry appears at:

Prototype Apps ▸ MorphoLibJ via Fiji...

The entry sits in the Detection & Bridges group under the Prototype Apps menu. Clicking it opens a dockable floating panel.

Changing your choice later

The easiest way to enable/disable this plugin is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager, find this plugin's checkbox in the bottom “Prototype Apps (Full Package)” list — tick = deploy the menu entry, untick = remove it. Restart Dragonfly once to apply. Disabling never deletes any configured content; re-enabling is instant.

You can also re-run the installer anytime (it remembers your previous choices as the new defaults). Everything installs under the per-user %LOCALAPPDATA% folder and needs no admin rights.

4. Environment and First-Run Setup

This plugin is an external-app type: it creates no Python virtual environment (venv), needs no GPU, and needs no WSL; TIFF I/O uses Dragonfly's bundled tifffile. It therefore has no heavy “Setup Environment” step. Its only external dependency is a user-installed Fiji / ImageJ with MorphoLibJ.

4.1 Install Fiji

If Fiji is not yet on the machine, download and unpack it from https://fiji.sc. When the panel opens, it auto-searches common locations (such as %LOCALAPPDATA%, Program Files, Desktop, Downloads, and drive roots' Fiji.app / Fiji / ImageJ subfolders) for a launcher (ImageJ-win64.exe, fiji-windows-x64.exe, etc.). You may also predefine the launcher path via the DF_FIJI_PATH environment variable.

4.2 Point the panel at the Fiji launcher

In the panel's Fiji / MorphoLibJ group:

• If auto-detection succeeds, the launcher path is filled into the Launcher text box automatically.
• Click Locate to re-run the automatic search.
• Click Browse... to pick the launcher executable manually (usually ImageJ-win64.exe or fiji-windows-x64.exe).

When you select a newer Fiji (Jaunch) launcher, the plugin tries to switch to the classic ImageJ-win64.exe launcher in the same folder to run the headless batch macro, because the classic launcher has the most reliable -batch (headless) behavior.

4.3 Check / install MorphoLibJ

Click Check / Install MorphoLibJ: the plugin scans the selected Fiji install's plugins, jars, and related folders for jar/class files whose names contain morpholibj or ijpb.

• Detected: a dialog reports where MorphoLibJ was found, and the status bar shows “MorphoLibJ detected: …”.
• Not detected: an “Install MorphoLibJ?” prompt appears. Choosing Yes runs Fiji's updater commands headlessly to add the IJPB-plugins update site (https://sites.imagej.net/IJPB-plugins/) and apply updates.

Installing/updating MorphoLibJ needs internet access (to reach the IJPB-plugins update site) and may take a few minutes. After install, new commands sometimes are not available immediately — if the status bar reports it still cannot be found by the file scan, restart Fiji/Dragonfly, or install manually via Fiji Help ▸ Update ▸ Manage update sites ▸ IJPB-plugins. Normal processing (running algorithms once MorphoLibJ is installed) needs no internet.

4.4 Memory (JVM heap)

The Max heap spin box sets Fiji's maximum JVM heap, default 4096 MB. For larger 3D volumes, raise it to avoid Fiji out-of-memory errors.

The launcher path, heap size, and output suffix entered in the panel are saved to morpholibj_config.json in the plugin's code folder and restored the next time the panel opens.

5. Interface Reference

A one-line description sits at the top of the panel. The controls are described top-to-bottom by group (matching the plugin code).

5.1 Input ROI

• ROI dropdown: lists ROIs available in the current Dragonfly scene. It prefers the currently selected ROI and aggregates all ROI instances; each item shows the ROI title followed by its shape (Z × Y × X).
• Refresh button: rescans and refreshes the ROI list. When done, the status bar shows “Found N ROI(s).”.

5.2 MorphoLibJ operation

• Operation dropdown: selects the MorphoLibJ operation to run — 5 in total (see Section 7, Parameters).
• Parameter area: changes dynamically with the selected operation, exposing that operation's tunable parameters (dropdown / integer / float).
• Note text: gray small text showing a short description of the current operation.

5.3 Fiji / MorphoLibJ

• Launcher text box: full path to the Fiji/ImageJ launcher executable; placeholder is path to ImageJ-win64.exe / fiji-windows-x64.exe.
• Locate button: auto-searches the machine for a Fiji launcher and fills it in.
• Browse... button: opens a file dialog to pick the launcher manually (filter *.exe).
• Max heap spin box: Fiji JVM maximum heap in MB, default 4096, step 512, range 0–262144.
• Check / Install MorphoLibJ button: checks whether the selected Fiji has MorphoLibJ; if not, prompts to install the IJPB-plugins update site.

5.4 Output

• MultiROI suffix text box: suffix for the output MultiROI name, default `MorphoLibJ`. The final name is <ROI title> - <suffix>.

5.5 Run and log

• Run MorphoLibJ + Create MultiROI button (blue with white text): starts the full workflow — export ROI, run the Fiji macro, import the result as a MultiROI.
• Status bar: shows the current state (how many ROIs were found, whether MorphoLibJ was detected, done or failed, etc.).
• Log area: a read-only text box showing step-by-step progress, Fiji error lines, and the final result; while running, the Run and Check/Install buttons are disabled to prevent re-triggering.

6. Step-by-Step Usage

Below is the complete end-to-end path from an existing ROI to a MultiROI.

Prerequisites: a ROI already exists in the Dragonfly scene; Fiji is installed on the machine; MorphoLibJ is installed in Fiji (or you are ready to install it when prompted).

1. Open Prototype Apps ▸ MorphoLibJ via Fiji... to bring up the panel.

2. In Input ROI, pick the ROI to process from the dropdown; if the list looks incomplete, click Refresh.

3. In MorphoLibJ operation, select an operation (e.g. Distance Transform Watershed) and adjust the parameters that appear (e.g. Connectivity, Dynamic, Radius) as needed.

4. In Fiji / MorphoLibJ, confirm the Launcher path is filled correctly; if empty or wrong, use Locate or Browse...; adjust Max heap if needed.

5. (Recommended on first use) Click Check / Install MorphoLibJ to confirm MorphoLibJ is ready; if prompted that it is missing, install it (needs internet), and restart Fiji/Dragonfly if it does not take effect.

6. In Output, adjust the MultiROI suffix if desired (default MorphoLibJ).

7. Click Run MorphoLibJ + Create MultiROI. The plugin will: export the ROI to a binary TIFF → launch Fiji headlessly to run the MorphoLibJ macro → produce a label TIFF → import it back into Dragonfly as a MultiROI.

8. Watch the status bar and log: on success the status bar shows “Done: created MultiROI with N label(s).”, the log reports the MultiROI name and label count, and the new MultiROI is published into the Dragonfly scene.

At run time the plugin automatically checks whether MorphoLibJ is ready (an implicit Check/Install in the background). If it is not installed and you choose to install it, this run will not continue automatically — Fiji usually needs a restart to load newly installed jars, so install, restart, and click Run again.

7. Parameters

The table below lists every tunable parameter in the panel, its default, and its meaning. The parameter area shows the parameters for the selected operation dynamically.

7.1 The five operations

8. Output

On a successful run, the plugin creates and publishes one MultiROI in Dragonfly:

• Name: <source ROI title> - <MultiROI suffix> (suffix defaults to MorphoLibJ).
• Content: each non-zero label in the label TIFF is renumbered and becomes one object in the MultiROI; the label count is reported in the log (“Created MultiROI '…' with N label(s).”).
• Geometry: the plugin reuses the source ROI's voxel spacing and origin where possible, so the MultiROI aligns spatially with the source data.
• Appearance: default colors are assigned to the labels on import (assignDefaultColors).

How to view: find the MultiROI in Dragonfly's object browser / data panel and toggle its visibility to see it in the 2D/3D views. It behaves like any MultiROI — you can measure it, color it by a scalar, export it, and so on.

Intermediate files: the exported input TIFF, the macro file, and the label TIFF are written to a morpholibj_-prefixed job folder under the OS temp directory. The job folder path is printed in the log even after a successful import, so you can inspect Fiji's input/output manually if needed; on failure, the error text retains these paths for troubleshooting.

9. FAQ and Troubleshooting

Q1: After clicking Run it says “set the Fiji/ImageJ launcher path.” or Fiji cannot be found?

A: The panel has no valid Fiji launcher. Install Fiji first (https://fiji.sc), then click Locate to auto-search, or use Browse... to pick ImageJ-win64.exe / fiji-windows-x64.exe manually. You can also set the path via the DF_FIJI_PATH environment variable.

Q2: It reports MorphoLibJ was not detected, or a command is unavailable during the run?

A: Click Check / Install MorphoLibJ and follow the prompt to install the IJPB-plugins update site (needs internet). If it still does not take effect after install, restart Fiji/Dragonfly, or install manually via Fiji Help ▸ Update ▸ Manage update sites ▸ IJPB-plugins. Note that MorphoLibJ command names can differ across Fiji builds; the log echoes Fiji stdout/stderr to help you diagnose.

Q3: The ROI dropdown is empty?

A: This plugin does not create ROIs; it only processes an existing one. Prepare a ROI in Dragonfly first (for example a thresholded foreground), then return to the panel and click Refresh.

Q4: The run fails with a Fiji out-of-memory error, or large volumes are slow?

A: Fiji/MorphoLibJ runs as an external process; large volumes take time and need enough JVM heap. Raise Max heap (default 4096 MB) and be patient. If it still fails, use the job-folder path printed in the log to open the input TIFF and macro manually in Fiji for inspection.

Q5: It says “MorphoLibJ output contains no foreground labels” or the label count is 0?

A: This means Fiji's label image has no foreground objects. Common causes are an empty source ROI, or a morphology operation (such as an opening with too large a radius) that erased the entire foreground. Check that the source ROI has foreground, and reduce Radius or switch operations.

10. Notes and Known Limitations

• The plugin requires an existing Dragonfly ROI as input; it does not create the source ROI.
• Fiji/MorphoLibJ runs as an external process, so large volumes take time and need enough JVM heap (see Max heap).
• The output MultiROI geometry reuses the source ROI geometry where possible; if the source geometry is incomplete, it may fall back to default spacing/origin.
• MorphoLibJ command names can vary between Fiji builds; the operation list uses standard command names from current MorphoLibJ/Fiji installs and echoes Fiji stdout/stderr when a command is unavailable.
• Installing/updating MorphoLibJ needs internet; new commands may require a Fiji/Dragonfly restart to load.
• MultiROI labels use uint16 numbering, so a single import is capped at 65535 labels; exceeding that raises an error.
• Menus are scanned only at Dragonfly startup, so a restart is needed after enabling/disabling or updating code.

11. References

• Fiji (ImageJ distribution) home: https://fiji.sc
• MorphoLibJ / IJPB-plugins update site: https://sites.imagej.net/IJPB-plugins/
• MorphoLibJ project page (IJPB-plugins): https://imagej.net/plugins/morpholibj
• Prototype Labs Full Package install/enable/uninstall instructions: the packaged README.md and, in Dragonfly, Developer ▸ Prototype Labs... ▸ Menu Item Manager.