MorphoLibJ Remade by Python(Python 重制版 MorphoLibJ)插件用户手册

MorphoLibJ Remade by Python - User Manual

Dragonfly Prototype Apps · MorphoLibJ Remade by Python...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

MorphoLibJ Remade by Python(Python 重制版 MorphoLibJ)是 Dragonfly 的一个 Prototype Apps 插件。它把 MorphoLibJ 中最常用的二值分割流程用纯 Python 重新实现,直接作用于 Dragonfly 中的 ROI(感兴趣区),把结果作为 MultiROI(多标签 ROI)导回 Dragonfly。它不调用 ImageJ、Fiji、Java,也不使用 MorphoLibJ 的 jar 包。

MorphoLibJ 是 Fiji/ImageJ 生态中一个著名的数学形态学与分割插件。传统上要使用它必须安装 Fiji、启用 IJPB-plugins 更新站点,并让 Dragonfly 与 Java 进行桥接。本插件把这套流程中最核心的一部分——连通域标记与距离变换分水岭(Distance Transform Watershed)——用 NumPy、SciPy 与 scikit-image 在 Python 中直接重写,因此首次搭建环境之后就无需 Fiji、ImageJ 或 Java。

底层引擎与算法

本插件在一个独立的 Python 虚拟环境(venv)中运行,依赖以下三个开源库:

• NumPy —— 数组与数值计算基础库(BSD 许可)。
• SciPy —— 提供 scipy.ndimage 的连通域标记、二值形态学(开运算 / 闭运算 / 填洞)与欧氏距离变换(BSD 许可)。
• scikit-image —— 提供 h_maxima(扩展极大值,用于生成分水岭标记)与 watershed(分水岭分割)(BSD 许可)。

距离变换分水岭的算法链沿用 MorphoLibJ 的 Java 设计思路:

二值 ROI

-> 距离变换 (distance transform)

-> 由距离图极值生成标记 (marker generation)

-> 标记控制的分水岭 (marker-controlled watershed)

-> Dragonfly MultiROI

在 MorphoLibJ 的 Java 表述中,这等价于「在反转距离图上、施加扩展极小值(extended minima)后做分水岭」。在本插件的 Python 实现中,等价写法是 watershed(-distance, h_maxima(distance), mask=ROI):因为把距离图反转会让物体中心变成极小值,所以用距离图的 h-maxima(扩展极大值) 来生成标记,和「对反转图施加扩展极小值」是同一种标记生成意图。

许可证要点

MorphoLibJ 采用 LGPL-3.0 许可。本插件不打包任何 MorphoLibJ 的 Java 类或 jar 文件,而是用 NumPy / SciPy / scikit-image 直接实现所需算法;这三个库均为宽松的 BSD 类许可。项目参考的上游源码主要是 MorphoLibJ 的 DistanceTransformWatershed.java 与 DistanceTransformWatershed3D.java。

本插件目前只实现了 MorphoLibJ 的核心分割路径(连通域标记 + 距离变换分水岭 + 简单的开/闭/填洞预处理),并非 MorphoLibJ 的完整移植。

2. 适用场景

本插件适用于希望复用 MorphoLibJ 风格的二值 ROI 分割,但不想安装或调用 Fiji / ImageJ / Java 的用户。典型场景包括:

• 分离相互接触的物体:对已经二值化的 ROI,用距离变换分水岭把粘连在一起的颗粒、气孔、细胞等拆分成一个个独立标签。
• 颗粒 / 孔隙 / 细胞区域分割:把一整块前景 ROI 拆成 MultiROI,便于后续逐个测量体积、面积或计数。
• 连通域标记:把一个二值 ROI 中彼此不相连的区域各自赋予一个标签编号。
• 带预处理的连通域标记:在标记前先做形态学开运算(去除小噪点 / 断开细连接)、闭运算(填补小缺口 / 连接近邻)或填洞,再拆分成 MultiROI。

由于全部运算在本地 Python 中完成,处理过程不需要联网、不需要 GPU、不需要 Java,适合在离线环境或没有安装 Fiji 的机器上使用。

3. 安装与启用

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

1. 把完整安装包 zip 解压到一个较短的目录(例如 C:\PL\),避免路径过长报错。

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

3. 在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),并在插件列表中勾选 MorphoLibJ Remade by Python。

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

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

所有插件在安装包中默认未勾选(轻量菜单项默认开启,所有插件默认关闭)。要使用本插件,必须在安装时手动勾选它,或稍后在 Menu Item Manager 中启用它。

重启后,插件会出现在 Dragonfly 顶部菜单:

Prototype Apps -> MorphoLibJ Remade by Python...

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

以后修改勾选

最方便的方式是在 Dragonfly 内修改:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部的 "Prototype Apps (Full Package)" 列表里勾选 / 取消勾选本插件,然后重启 Dragonfly 生效。停用插件从不删除已搭建好的环境,重新启用可立即使用。也可以随时重跑安装器,它会记住上次的勾选作为默认值。

卸载

双击 `Uninstall_FullPackage.bat` 可移除所有 Full Package 的菜单项与插件。卸载会保留插件已搭建的环境(venv),结束时会列出这些路径,供你在需要腾出磁盘空间时手动删除。

4. 运行环境与首次配置

本插件采用「代码目录内建 venv(venv_in_code)」的环境模式:所有第三方库都装在插件自己的一个隔离虚拟环境里,与 Dragonfly 主环境彼此独立。安装包本身不会下载任何东西,环境要在首次使用时手动搭建。

Setup Environment 具体做什么

在面板的 Setup 分页点击 Setup Environment (numpy + scipy + scikit-image) 按钮后,插件会:

1. 以一个基础 Python 为底(默认自动探测 Dragonfly 自带的 Python 或系统 Python;也可在 Base Python 中手动指定),在插件代码目录下创建一个 venv 文件夹。

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

3. 从 PyPI 联网 pip 安装 numpy、scipy、scikit-image(纯 Python wheel,通常几十到几百 MB,数分钟内完成)。

4. 运行一次导入自检(导入 numpy / scipy / skimage 以及 watershed、h_maxima),成功后把 venv 的 python 路径写回面板的 Analysis venv python 字段并保存到配置。

下载体积 / 联网 / GPU / WSL / 外部软件

环境安装到哪些路径

• venv:创建在已安装的插件代码目录内,即 ...\pythonUserExtensions\GenericMenuItems\MorphoLibJPython\venv。
• Job root(作业根目录):默认 C:\MorphoLibJPythonJobs,可在 Setup 分页修改。每次运行会在其下建立一个带时间戳的作业文件夹,存放导出的 ROI、配置和结果 .npy 文件。

失败时的替代方案

• 如果自动探测的基础 Python 没有 venv / pip 能力,可在 Base Python 字段用 Browse... 手动指定一个可用的 Python 3.10–3.12 解释器(python.exe),再重新点击 Setup Environment。
• 如果已经在别处装好了含 numpy / scipy / scikit-image 的环境,也可以直接把它的 python.exe 路径填进 Analysis venv python 字段,跳过搭建。
• 首次搭建务必保持联网;若下载中断,重新点击 Setup Environment 会复用并续装现有 venv。

5. 界面说明

面板顶部是一行标题说明,下方是三个分页:Setup(环境搭建)、Run(运行)、Summary(结果摘要)。面板最底部有一个绿色的状态行和一个只读的日志框,实时显示运行过程与错误信息。

5.1 Setup 分页

• Analysis venv python(分析用 venv 的 python):文本框。搭建成功后自动填入 venv 中 python 的路径;也可手动填入一个现成环境的 python。
• Base Python(基础 Python):文本框 + Browse... 按钮。留空表示自动探测 Dragonfly / 系统 Python 作为搭建 venv 的底;也可点 Browse 手动选择一个 python.exe。
• Job root(作业根目录):文本框,默认 C:\MorphoLibJPythonJobs。
• Setup Environment (numpy + scipy + scikit-image):按钮,点击后在后台线程中搭建 venv 并安装依赖。
• 下方提示文字:提醒本插件不使用 Fiji / ImageJ / Java,首次搭建仅下载 Python wheel。

5.2 Run 分页

Run 分页分为两个分组框。

Input ROI(输入 ROI)分组:

• ROI:下拉框 + Refresh 按钮。列出当前 Dragonfly 场景中的 ROI(优先显示当前选中的 ROI),每一项后面附带其形状尺寸;点 Refresh 重新扫描。
• Output MultiROI(输出 MultiROI 名称):文本框,默认 MorphoLibJ Python MultiROI,即生成的 MultiROI 的标题。

Operation(操作)分组:

• Algorithm(算法):下拉框,五种操作(见第 7 章),默认 Distance Transform Watershed(距离变换分水岭)。
• Connectivity(连通性):下拉框,可选 6 / 18 / 26 邻域,默认 26(2D 图像会自动换算为对应的 2D 邻域)。
• Distance metric(距离度量):下拉框,可选 Borgefors chamfer 3/4/5(MorphoLibJ 风格) 或 Euclidean distance transform(欧氏距离变换),默认 Borgefors。仅影响距离变换分水岭。
• Marker dynamic(标记动态值 h):双精度数值框,范围 0–100000,步进 0.5,默认 2.0。控制 h-maxima 生成标记的强度(见第 7 章)。
• Morphology radius(形态学半径):整数数值框,范围 1–128,默认 1。用于开 / 闭运算的球形结构元半径。
• Normalize chamfer distances(归一化 chamfer 距离):复选框,默认勾选。对 Borgefors chamfer 距离除以 3 归一化。
• Keep watershed lines as background(把分水岭分割线保留为背景):复选框,默认不勾选。勾选后相邻标签之间保留一条背景分割线。
• Use voxel spacing for Euclidean distance(欧氏距离使用体素间距):复选框,默认不勾选。勾选后欧氏距离变换会使用 Dragonfly 中该 ROI 的真实体素间距。
• Publish distance and marker debug Channels(发布距离图与标记的调试 Channel):复选框,默认不勾选。勾选后把中间的距离图与标记体作为额外 Channel 发布,便于检查。
• Run Python MorphoLibJ + Create MultiROI:蓝色主按钮,点击后在后台线程中执行完整流程并生成 MultiROI。

5.3 Summary 分页

运行结束后自动切换到此分页,以 Metric / Value(指标 / 数值) 两列表格显示本次运行的摘要,例如操作类型、连通性、距离度量、标记数、标签数、前景体素数等。

6. 使用步骤

6.1 首次搭建环境(只需一次)

1. 打开 Prototype Apps ▸ MorphoLibJ Remade by Python...,切到 Setup 分页。

2. (可选)在 Base Python 指定基础 Python;通常留空自动探测即可。

3. (可选)修改 Job root 作业根目录。

4. 确保联网,点击 Setup Environment (numpy + scipy + scikit-image)。

5. 在底部日志框观察进度,状态行显示 Environment ready. 即表示成功,Analysis venv python 会自动填好。

6.2 距离变换分水岭(分离接触物体)

输入要求:场景中已有一个二值化的前景 ROI(例如阈值分割得到的颗粒 / 孔隙 / 细胞团)。

1. 切到 Run 分页,点击 Refresh,在 ROI 下拉框中选中目标 ROI。

2. Algorithm 选 Distance Transform Watershed。

3. 选择 Distance metric:形状规则、追求 MorphoLibJ 风格时用 Borgefors;需要各向异性 / 真实间距时用 Euclidean 并勾选 Use voxel spacing。

4. 调节 Marker dynamic (h):值越大合并越多、拆分越少(过度分割更少);值越小拆分越细。可从默认 2.0 起试。

5. (可选)设置 Output MultiROI 名称;如需检查中间量,勾选 Publish distance and marker debug Channels。

6. 点击 Run Python MorphoLibJ + Create MultiROI。

7. 运行结束后自动跳到 Summary 分页;在对象列表中查看新生成的 MultiROI,每个分离出的物体是一个标签。

6.3 连通域标记(可带预处理)

输入要求:一个二值 ROI。

1. 在 Run 分页选中目标 ROI。

2. Algorithm 选 Connected Components Labeling(直接标记),或 Opening / Closing / Fill Holes then Connected Components(先做形态学预处理再标记)。

3. 设置 Connectivity(6/18/26)决定哪些体素算相连。

4. 若选了开 / 闭运算,用 Morphology radius 设定结构元大小。

5. 点击 Run Python MorphoLibJ + Create MultiROI,得到按连通域拆分的 MultiROI。

7. 参数说明

7.1 操作(Algorithm)

7.2 参数默认值一览

8. 输出结果

本插件在 Dragonfly 中生成以下对象:

• MultiROI(多标签 ROI):主要输出。距离变换分水岭得到每个被分离物体一个标签;连通域标记得到每个连通区域一个标签。名称取自 Output MultiROI 字段,并自动分配默认颜色。它与源 ROI 共享体素间距与原点(几何对齐)。
• 距离图 Channel(可选):勾选调试选项后发布,标题默认 MorphoLibJ distance,以浮点数值显示每个前景体素到背景的(近似)距离。
• 标记 Channel(可选):勾选调试选项后发布,标题默认 MorphoLibJ markers,显示分水岭使用的标记体。

查看方式:在 Dragonfly 的对象列表(Object Browser)中找到新对象;MultiROI 会以不同颜色区分各标签,可在 2D / 3D 视图中显示,并可对其做后续的形态测量、计数或统计。

此外,每次运行会在 Job root 下建立一个带时间戳的作业文件夹(如 morpholibj_py_YYYYMMDD_HHMMSS),其中保存导出的输入掩膜 input_roi.npy、导出信息 export.json、以及结果 .npy / results.json,便于排查或复现。

9. 常见问题与故障排除

问:菜单里找不到 MorphoLibJ Remade by Python...?

答:请确认安装时勾选了该插件(所有插件默认未勾选),并在安装后完全重启了 Dragonfly。仍未出现时,可在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 中勾选它,再重启一次。

问:点击 Run 提示 "Run Setup first, or set the analysis venv python."?

答:说明还没搭建环境。请先到 Setup 分页点击 Setup Environment 成功搭好 venv(状态行显示 Environment ready.),或手动在 Analysis venv python 填入一个含 numpy/scipy/scikit-image 的 python 路径。

问:点击 Run 提示 "Select a ROI first."?

答:说明没有选中输入 ROI。请到 Run 分页点 Refresh,在 ROI 下拉框中选一个二值 ROI;若列表为空,请先在 Dragonfly 中创建 / 分割出一个 ROI。

问:Setup Environment 失败或卡住怎么办?

答:首次搭建需要联网从 PyPI 下载 wheel,请确认网络可用;若自动探测到的基础 Python 无 pip / venv 能力,请在 Base Python 用 Browse 指定一个可用的 Python 3.10–3.12,再重试。日志框会显示具体错误。

问:分水岭结果分得太碎(过度分割)?

答:调大 Marker dynamic (h) 值,让更多局部极大值被合并;也可尝试改用 Euclidean 距离,或先用「开运算再标记」去掉细小噪声。反之,若该分开的物体被合在一起,则调小 h。

问:欧氏距离没有考虑非立方体素?

答:勾选 Use voxel spacing for Euclidean distance,插件会读取 ROI 的真实体素间距用于距离计算(仅对 Euclidean 度量生效)。

10. 注意事项与已知限制

• 并非 MorphoLibJ 完整移植:仅实现连通域标记、距离变换分水岭,以及开 / 闭 / 填洞预处理这一核心分割路径。
• 输入需为二值 ROI:插件会把输入 ROI 中非零体素视为前景;非二值 / 灰度数据请先阈值化。
• Borgefors chamfer 距离为纯 Python 两遍扫描实现,对很大的三维体积可能较慢;此时可改用速度更快的 Euclidean 距离度量。
• MultiROI 与源 ROI 几何对齐:输出会继承源 ROI 的体素间距与原点。
• 首次搭建需要联网;之后的处理完全离线。运算均在 CPU 上进行,不使用 GPU。
• 停用插件不会删除 venv:重新启用即可继续使用,无需再次搭建。

11. 参考资料

• MorphoLibJ 源码仓库:https://github.com/ijpb/MorphoLibJ
• MorphoLibJ 文档:https://imagej.net/plugins/morpholibj
• MorphoLibJ 许可证:LGPL-3.0
• SciPy 文档(ndimage 形态学与距离变换):https://docs.scipy.org/
• scikit-image 文档(watershed / h_maxima):https://scikit-image.org/

本插件不打包任何 MorphoLibJ Java 类或 jar,亦不需要 Fiji / ImageJ / Java;算法用 NumPy / SciPy / scikit-image 直接实现。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation and Enabling

4. Runtime Environment and First-Time Setup

5. Interface Reference

6. Step-by-Step Usage

7. Parameter Reference

8. Outputs

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

1. Overview

MorphoLibJ Remade by Python is a Dragonfly Prototype Apps plugin. It reimplements the most commonly used MorphoLibJ binary-segmentation workflow in pure Python, operating directly on a Dragonfly ROI and importing the result back into Dragonfly as a MultiROI. It does not call ImageJ, Fiji, Java, or the MorphoLibJ jar.

MorphoLibJ is a well-known mathematical-morphology and segmentation plugin in the Fiji/ImageJ ecosystem. Traditionally, using it requires installing Fiji, enabling the IJPB-plugins update site, and bridging Dragonfly to Java. This plugin rewrites the core part of that workflow -- connected-components labeling and the Distance Transform Watershed -- directly in Python with NumPy, SciPy, and scikit-image, so that after the one-time environment setup, no Fiji, ImageJ, or Java is required.

Underlying engine and algorithm

The plugin runs in an isolated Python virtual environment (venv) that depends on three open-source libraries:

• NumPy -- array and numerical computing (BSD license).
• SciPy -- provides scipy.ndimage connected-components labeling, binary morphology (opening / closing / fill holes), and the Euclidean distance transform (BSD license).
• scikit-image -- provides h_maxima (extended maxima, used to generate watershed markers) and watershed (BSD license).

The Distance Transform Watershed follows the MorphoLibJ Java design:

binary ROI

-> distance transform

-> marker generation from distance-map extrema

-> marker-controlled watershed

-> Dragonfly MultiROI

In MorphoLibJ's Java wording this is a watershed on the inverse distance map with extended minima imposed. In Python the equivalent is watershed(-distance, h_maxima(distance), mask=ROI): inverting the distance map turns object centers into minima, so the plugin generates markers from the h-maxima (extended maxima) of the distance map -- the same marker-generation intent as extended minima on the inverted image.

License notes

MorphoLibJ is licensed LGPL-3.0. This plugin bundles no MorphoLibJ Java classes or jar files; instead it implements the required algorithms directly with NumPy / SciPy / scikit-image, all under permissive BSD-style licenses. The main upstream references were MorphoLibJ's DistanceTransformWatershed.java and DistanceTransformWatershed3D.java.

This plugin currently implements only MorphoLibJ's core segmentation path (connected components + distance-transform watershed + simple opening/closing/fill-holes preprocessing); it is not a complete port of MorphoLibJ.

2. Use Cases

This plugin is for users who want MorphoLibJ-style binary ROI splitting without installing or calling Fiji / ImageJ / Java. Typical scenarios:

• Separating touching objects: on an already-binarized ROI, use the distance-transform watershed to split fused grains, pores, or cells into individual labels.
• Grain / pore / cell-region segmentation: split one foreground ROI into a MultiROI, ready for per-object volume, area, or count measurements.
• Connected-components labeling: assign a distinct label number to each disconnected region of a binary ROI.
• Labeling with preprocessing: first apply morphological opening (remove small noise / break thin bridges), closing (close small gaps / join neighbors), or fill holes, then split into a MultiROI.

Because all computation runs locally in Python, processing needs no internet, no GPU, and no Java, making it suitable for offline machines or machines without Fiji installed.

3. Installation and Enabling

The plugin ships in the Prototype Labs & Apps Full Package. To install:

1. Unzip the Full Package to a short folder (e.g. C:\PL\) to avoid path-length errors.

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, pick the core install mode (Fresh or Compatible) and tick MorphoLibJ Remade by Python in the plugin list.

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

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

All plugins are unticked by default in the installer (light menu items are ON, all plugins are OFF). You must tick this plugin at install time, or enable it later in the Menu Item Manager.

After the restart the plugin appears in the top menu:

Prototype Apps -> MorphoLibJ Remade by Python...

It sits in the Detection & Bridges section of the Prototype Apps menu. Clicking it opens a dockable floating panel.

Changing your choices later

The easiest way is inside Dragonfly: open Developer > Prototype Labs... > Menu Item Manager and tick / untick this plugin in the "Prototype Apps (Full Package)" list at the bottom, then restart Dragonfly to apply. Disabling a plugin never deletes its built environment, so re-enabling is instant. You can also re-run the installer anytime; it remembers your previous choices as defaults.

Uninstall

Double-click `Uninstall_FullPackage.bat` to remove all Full-Package menu items and plugins. Uninstall keeps each plugin's built environment (venv); the paths are listed at the end so you can delete them manually to reclaim disk space.

4. Runtime Environment and First-Time Setup

The plugin uses a "venv-in-code" environment model: all third-party libraries live in the plugin's own isolated virtual environment, separate from Dragonfly's main environment. The installer downloads nothing; the environment is built by hand on first use.

What Setup Environment does

On the Setup tab, clicking Setup Environment (numpy + scipy + scikit-image) makes the plugin:

1. Create a venv folder inside the plugin's code directory, based on a base Python (by default auto-detected from Dragonfly's own Python or a system Python; you can override it via Base Python).

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

3. pip-install numpy, scipy, and scikit-image from PyPI over the internet (pure-Python wheels; usually tens to a few hundred MB, done within minutes).

4. Run an import self-check (importing numpy / scipy / skimage plus watershed and h_maxima); on success it writes the venv python path back into the Analysis venv python field and saves it to config.

Download size / internet / GPU / WSL / external apps

Where the environment is installed

• venv: inside the installed plugin code directory, i.e. ...\pythonUserExtensions\GenericMenuItems\MorphoLibJPython\venv.
• Job root: default C:\MorphoLibJPythonJobs, editable on the Setup tab. Each run creates a timestamped job folder underneath it holding the exported ROI, the config, and result .npy files.

Fallbacks when setup fails

• If the auto-detected base Python has no venv / pip capability, use Browse... on Base Python to point at a working Python 3.10-3.12 interpreter (python.exe) and click Setup Environment again.
• If you already have an environment with numpy / scipy / scikit-image, you can paste its python.exe path directly into Analysis venv python and skip the build.
• Keep the machine online for first setup; if a download is interrupted, clicking Setup Environment again reuses and resumes the existing venv.

5. Interface Reference

The panel has a title line at the top and three tabs: Setup, Run, and Summary. A green status line and a read-only log box at the bottom show progress and errors in real time.

5.1 Setup tab

• Analysis venv python: text field. Filled automatically with the venv python path after a successful setup; you may also paste an existing environment's python.
• Base Python: text field + Browse... button. Leave blank to auto-detect Dragonfly / system Python as the venv base, or Browse to pick a python.exe.
• Job root: text field, default C:\MorphoLibJPythonJobs.
• Setup Environment (numpy + scipy + scikit-image): button; builds the venv and installs dependencies in a background thread.
• Note text below: reminds you that no Fiji / ImageJ / Java is used and first setup only downloads Python wheels.

5.2 Run tab

The Run tab has two group boxes.

Input ROI group:

• ROI: dropdown + Refresh button. Lists the ROIs in the current Dragonfly scene (currently selected ROIs first), each item followed by its shape; Refresh re-scans.
• Output MultiROI: text field, default MorphoLibJ Python MultiROI -- the title of the generated MultiROI.

Operation group:

• Algorithm: dropdown of five operations (see Chapter 7), default Distance Transform Watershed.
• Connectivity: dropdown of 6 / 18 / 26 neighborhoods, default 26 (2D images are automatically mapped to the corresponding 2D neighborhood).
• Distance metric: dropdown of Borgefors chamfer 3/4/5 (MorphoLibJ-style) or Euclidean distance transform, default Borgefors. Affects the distance-transform watershed only.
• Marker dynamic (h): double spin box, range 0-100000, step 0.5, default 2.0. Controls the strength of h-maxima marker generation (see Chapter 7).
• Morphology radius: integer spin box, range 1-128, default 1. Ball structuring-element radius for opening / closing.
• Normalize chamfer distances: checkbox, checked by default. Divides Borgefors chamfer distances by 3.
• Keep watershed lines as background: checkbox, unchecked by default. Keeps a background separation line between adjacent labels when checked.
• Use voxel spacing for Euclidean distance: checkbox, unchecked by default. Uses the ROI's real voxel spacing in the Euclidean distance transform when checked.
• Publish distance and marker debug Channels: checkbox, unchecked by default. Publishes the intermediate distance map and marker volume as extra Channels.
• Run Python MorphoLibJ + Create MultiROI: the blue main button; runs the full pipeline in a background thread and creates the MultiROI.

5.3 Summary tab

The panel switches here automatically after a run and shows a two-column Metric / Value table with the run summary -- e.g. operation, connectivity, distance metric, number of markers, number of labels, and foreground voxel count.

6. Step-by-Step Usage

6.1 Build the environment (once)

1. Open Prototype Apps > MorphoLibJ Remade by Python... and go to the Setup tab.

2. (Optional) Set Base Python; usually leaving it blank for auto-detect is fine.

3. (Optional) Change the Job root.

4. With the machine online, click Setup Environment (numpy + scipy + scikit-image).

5. Watch the log box; when the status line reads Environment ready. the build succeeded and Analysis venv python is filled in.

6.2 Distance Transform Watershed (separate touching objects)

Input requirement: a binarized foreground ROI already in the scene (e.g. thresholded grains / pores / a cell cluster).

1. Go to the Run tab, click Refresh, and select the target ROI in the ROI dropdown.

2. Set Algorithm to Distance Transform Watershed.

3. Choose the Distance metric: use Borgefors for regular shapes / MorphoLibJ style; use Euclidean with Use voxel spacing checked for anisotropic / real-spacing distances.

4. Tune Marker dynamic (h): larger values merge more and split less (less over-segmentation); smaller values split more finely. Start from the default 2.0.

5. (Optional) Set the Output MultiROI name; tick Publish distance and marker debug Channels to inspect intermediates.

6. Click Run Python MorphoLibJ + Create MultiROI.

7. When it finishes it jumps to Summary; find the new MultiROI in the object list, where each separated object is one label.

6.3 Connected components (optionally with preprocessing)

Input requirement: a binary ROI.

1. Select the target ROI on the Run tab.

2. Set Algorithm to Connected Components Labeling (direct), or Opening / Closing / Fill Holes then Connected Components for preprocessing before labeling.

3. Set Connectivity (6/18/26) to decide which voxels count as connected.

4. If opening / closing is chosen, set the Morphology radius for the structuring element.

5. Click Run Python MorphoLibJ + Create MultiROI to get a MultiROI split by connected component.

7. Parameter Reference

7.1 Operations (Algorithm)

7.2 Default values at a glance

8. Outputs

The plugin produces the following objects in Dragonfly:

• MultiROI (multi-label ROI): the primary output. The distance-transform watershed gives one label per separated object; connected-components labeling gives one label per connected region. Its title comes from the Output MultiROI field and it gets default colors automatically. It shares voxel spacing and origin with the source ROI (geometrically aligned).
• Distance Channel (optional): published when the debug option is checked, default title MorphoLibJ distance, showing the (approximate) float distance from each foreground voxel to the background.
• Markers Channel (optional): published when the debug option is checked, default title MorphoLibJ markers, showing the marker volume used by the watershed.

To view: find the new objects in Dragonfly's Object Browser; the MultiROI colors each label differently, can be shown in 2D / 3D views, and is ready for downstream morphometry, counting, or statistics.

In addition, each run creates a timestamped job folder under Job root (e.g. morpholibj_py_YYYYMMDD_HHMMSS) containing the exported input mask input_roi.npy, an export.json, and the result .npy / results.json files for troubleshooting or reproducibility.

9. FAQ and Troubleshooting

Q: I can't find MorphoLibJ Remade by Python... in the menu.

A: Confirm you ticked the plugin at install time (all plugins are unticked by default) and fully restarted Dragonfly afterwards. If it still doesn't appear, enable it in Developer > Prototype Labs... > Menu Item Manager and restart once more.

Q: Clicking Run says "Run Setup first, or set the analysis venv python."

A: The environment isn't built yet. Go to the Setup tab and click Setup Environment until the status line reads Environment ready., or manually paste a python path (with numpy/scipy/scikit-image) into Analysis venv python.

Q: Clicking Run says "Select a ROI first."

A: No input ROI is selected. On the Run tab click Refresh and pick a binary ROI in the ROI dropdown; if the list is empty, first create / segment an ROI in Dragonfly.

Q: Setup Environment fails or hangs.

A: First setup downloads wheels from PyPI, so make sure the network works; if the auto-detected base Python lacks pip / venv, point Base Python (via Browse) at a working Python 3.10-3.12 and retry. The log box shows the exact error.

Q: The watershed over-segments (too many fragments).

A: Increase the Marker dynamic (h) value so more local maxima merge; you can also try the Euclidean metric, or run "Opening then Connected Components" first to remove small noise. Conversely, lower h if objects that should be split stay merged.

Q: The Euclidean distance ignores non-cubic voxels.

A: Tick Use voxel spacing for Euclidean distance and the plugin reads the ROI's real voxel spacing for the distance computation (applies to the Euclidean metric only).

10. Notes and Known Limitations

• Not a complete MorphoLibJ port: only connected-components labeling, distance-transform watershed, and opening / closing / fill-holes preprocessing are implemented.
• Input must be a binary ROI: non-zero voxels are treated as foreground; threshold non-binary / grayscale data first.
• The Borgefors chamfer distance is a pure-Python two-pass scan and can be slow on very large 3D volumes; switch to the faster Euclidean metric in that case.
• The MultiROI is geometrically aligned to the source ROI: it inherits the source ROI's voxel spacing and origin.
• First setup needs internet; processing afterwards is fully offline. All computation runs on the CPU; no GPU is used.
• Disabling the plugin does not delete the venv: re-enable to keep using it without rebuilding.

11. References

• MorphoLibJ source repository: https://github.com/ijpb/MorphoLibJ
• MorphoLibJ documentation: https://imagej.net/plugins/morpholibj
• MorphoLibJ license: LGPL-3.0
• SciPy documentation (ndimage morphology and distance transform): https://docs.scipy.org/
• scikit-image documentation (watershed / h_maxima): https://scikit-image.org/

This plugin bundles no MorphoLibJ Java classes or jar files and needs no Fiji / ImageJ / Java; the algorithms are implemented directly with NumPy / SciPy / scikit-image.