GPU 图像滤波 (pyclesperanto) 插件用户手册

GPU Image Filters (pyclesperanto) - User Manual

Dragonfly Prototype Apps · GPU Image Filters (pyclesperanto)...

版本 Version 1.0 · 2026-07-09

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

GPU 图像滤波 (pyclesperanto) 是一个 Dragonfly 插件,借助 GPU(OpenCL)对图像 Channel(通道) 进行快速滤波与一键实例标记。它把耗时的体数据(2D/3D)运算从 CPU 转移到显卡上执行,在大体积 CT / 显微图像栈上通常比 CPU 版 scikit-image 快很多。

底层计算引擎为开源库 pyclesperanto(clEsperanto 项目),通过 OpenCL 在 GPU 或 CPU 上执行图像处理内核。本插件随包使用 稳定版 `pyclesperanto`(而非实验性的 pyclesperanto_prototype)。

本插件提供六种操作,分为两类输出:滤波类(高斯模糊、Top-hat 背景扣除、高斯差分 DoG、Otsu 阈值分割)输出为新的 Channel;标记类(Voronoi-Otsu 标记、连通域标记)输出为 MultiROI(每个物体一个实例标签)。计算结果会以与源图像相同的网格(体素间距 spacing + 原点 origin)对齐后发布回 Dragonfly 场景。

许可证要点

• 计算引擎 pyclesperanto:采用 BSD-3-Clause 许可证(宽松许可)。
• numpy:采用 BSD 许可证。
• 插件本身代码遵循 DragonflyPrototypeLabs 项目的许可条款。
• OpenCL 驱动(ICD)是系统组件,由显卡厂商驱动或 CPU OpenCL 运行时提供,不通过 pip 安装。

2. 适用场景

本插件适用于大体积 CT / 显微图像的批量预处理与分割前处理,尤其在数据量大、需要 GPU 加速的场景下表现突出:

• 去噪与平滑——用高斯模糊压制随机噪声,为后续分割或测量提供更平滑的输入。
• 背景扣除——用 Top-hat 变换去除缓变的背景亮度不均,突出小尺度的亮结构。
• 边缘 / 斑点增强——用高斯差分(DoG)增强特定尺度的斑点状或边缘结构。
• 二值化——用 Otsu 自动阈值把图像分为前景 / 背景两类。
• 一键实例标记——用 Voronoi-Otsu 或连通域标记直接得到颗粒 / 细胞的实例分割(每个物体一个标签),输出为 MultiROI。
• 大数据加速——在大图像栈上,GPU 版滤波通常比 CPU 版 scikit-image 快很多。

3. 安装与启用

本插件作为 Prototype Apps 的一部分,通过 Full Package(完整安装包) 安装。它在安装器中默认未勾选,需要手动启用。

安装步骤

1. 把 Full Package 压缩包解压到任意位置(建议解压到较短的目录,如 C:\PL\,避免路径过长)。

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

3. 在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),并在 Prototype Apps 列表中勾选 “GPU Image Filters (pyclesperanto)...”(所有插件默认关闭,必须手动勾选)。

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

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

重启后,菜单项出现在:Prototype Apps ▸ GPU Image Filters (pyclesperanto)...(位于 “Filtering & Restoration(滤波与复原)” 分组下)。点击它即打开一个可停靠 / 浮动的面板。

以后修改勾选

最方便的方式是在 Dragonfly 内修改:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部 “Prototype Apps (Full Package)” 列表中勾选 / 取消勾选本插件,重启 Dragonfly 生效。停用从不删除插件已搭建的运行环境(venv),重新启用立即可用。

菜单只在 Dragonfly 启动时扫描——每次修改勾选后都需要重启一次 Dragonfly 才能看到变化。

卸载

双击 `Uninstall_FullPackage.bat` 可移除所有 Full Package 的菜单项、插件和中央存储。卸载会保留各插件已搭建的运行环境(venv),其路径会在结束时列出,需要腾出磁盘空间时可手动删除。

4. 运行环境与首次配置

本插件采用 venv_in_code 模式:计算引擎(pyclesperanto + numpy)运行在一个专用虚拟环境(venv)中,由子进程执行,不会污染 Dragonfly 自带的 Python。首次使用前必须先搭建这个环境。

Setup Environment 做什么

在面板上点击 Setup Environment 按钮后,插件会:

1. 用一个 “基础 Python” 创建一个本地 venv(默认使用 Dragonfly 自带的 Python,即 Python_env\python.exe,无需另装 Python)。

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

3. 从默认的 PyPI 源 pip 安装 `pyclesperanto`(BSD-3) 与 `numpy`(均为预编译 wheel)。

4. 做一次冒烟检测(打印 numpy / pyclesperanto 版本与检测到的 OpenCL 设备),成功后把 venv 的 Python 路径记录下来。

搭建完成后,面板 Status(状态) 栏会显示 Ready: <venv python 路径>。之后再次使用无需重复搭建;若已存在可用的 venv,插件会直接复用。

下载体积 / 联网 / GPU 要求

环境安装位置

venv 建立在已安装的插件代码目录内,即 Dragonfly 用户扩展目录下的 ...\GenericMenuItems\Pyclesperanto\venv(位于 %LOCALAPPDATA%\comet\<Dragonfly 版本>\pythonUserExtensions\ 之下)。OpenCL 驱动(ICD)本身是系统组件,不装入此 venv。

失败时的替代方案

• 基础 Python 不含 venv 模块 / venv 创建失败:在面板的 Base Python 输入框里指定另一个 CPython 3.10+ 的路径(如 C:\Python312\python.exe)或形如 py -3.11 的启动命令,再重新点 Setup Environment。pyclesperanto 需要 CPython(Windows 上支持 3.9–3.12 的预编译 wheel)。
• 没有 OpenCL 设备:安装显卡厂商驱动(提供 GPU 的 ICD),或安装 CPU OpenCL 运行时(POCL / Intel CPU runtime)作为回退设备,然后重新点 List devices 枚举。

5. 界面说明

面板从上到下由若干分组构成,逐一说明如下(与代码一致)。

Input Channel(输入通道)

• Channel(下拉框)——列出当前 Dragonfly 场景中的所有 Channel,条目形如 “通道名 (尺寸)”。若场景中没有 Channel,会显示 “(no channels - load an image in Dragonfly)” 提示。
• Refresh(按钮)——重新读取场景中的 Channel 列表。加载了新图像后点它刷新。

Operation(操作)

• Operation(下拉框)——选择六种操作之一(见下方参数表)。切换操作时,sigma / radius 输入框会根据该操作是否用到自动启用或禁用。
• sigma(数值框)——高斯尺度,取值 0.0–50.0,步进 0.5,默认 2.0。用于 Gaussian blur、Difference of Gaussian、Voronoi-Otsu labeling。
• radius(数值框)——结构元半径(体素),取值 0.0–100.0,步进 1.0,默认 5.0。仅用于 Top-hat 背景扣除。

OpenCL device(OpenCL 设备)

• Device(下拉框)——选择用于计算的 OpenCL 设备。默认项为 “(default)”(让 pyclesperanto 自行选择)。
• List devices(按钮)——在 venv 中枚举可见的 OpenCL 设备并填入下拉框(需先完成 Setup Environment)。
• 面板下方有提示文字:pyclesperanto 需要 OpenCL ICD;GPU 驱动通常自带,否则可用 CPU OpenCL 运行时(POCL / Intel)作为回退设备。

Environment(pyclesperanto venv 环境)

• Base Python(输入框)——留空表示使用当前这套 Dragonfly 自带的 Python;也可填入某个 Python 的路径或形如 py -3.11 的命令来覆盖基础解释器。
• Status(状态标签)——显示环境是否就绪:就绪时为 Ready: <路径>,未就绪时提示先点 Setup Environment。

操作按钮与输出区

• Setup Environment(按钮)——搭建 / 复用 venv 并安装依赖(见第 4 章)。
• Compute(按钮)——用当前所选 Channel、操作与参数执行计算,并把结果发布回 Dragonfly。
• Summary(摘要标签)——一行显示本次结果的要点(操作名、设备、标签数或统计值、形状)。
• 日志区(只读文本框)——显示运行过程中的进度与信息(读取图像、上传 GPU、运行操作、下载结果、发布对象等)。

6. 使用步骤

工作流 A:滤波(输出 Channel)

适用于 Gaussian blur、Top-hat 背景扣除、Difference of Gaussian、Otsu 阈值分割。

1. 输入要求:在 Dragonfly 中先加载一幅 2D 或 3D 灰度图像(作为一个 Channel)。

2. 打开 Prototype Apps ▸ GPU Image Filters (pyclesperanto)... 面板。

3. (首次)点击 Setup Environment 搭建环境,等待 Status 显示 Ready。

4. 在 Input Channel 里选择要处理的 Channel(必要时点 Refresh 刷新列表)。

5. 在 Operation 里选择一个滤波操作;按需调整 sigma(高斯类)或 radius(Top-hat)。

6. (可选)点 List devices,在 Device 下拉框里选择 GPU 或 CPU OpenCL 设备。

7. 点击 Compute。运行结束后,日志显示 “Published: Channel”,场景中随即出现一个名为 “<原通道名> - <操作名>” 的新 Channel,无需重启。

工作流 B:一键实例标记(输出 MultiROI)

适用于 Voronoi-Otsu labeling、Connected components labeling。

1. 输入要求:同样先加载一幅灰度图像 Channel(颗粒 / 细胞等亮结构)。

2. 选择 Channel;在 Operation 里选 “Voronoi-Otsu labeling” 或 “Connected components labeling”。

3. Voronoi-Otsu 会用到 sigma(作为 spot / outline 尺度);连通域标记先做 Otsu 阈值再标记,不需要 sigma / radius。

4. 点击 Compute。运行结束后,日志显示 “Published: MultiROI (N labels)”,场景中出现一个名为 “<原通道名> - <操作名>” 的 MultiROI,每个物体一个实例标签,与源图像网格对齐。

7. 参数说明

操作一览

控件默认值与取值范围

8. 输出结果

根据所选操作,插件会在 Dragonfly 场景中发布不同类型的对象,全部与源图像的网格(spacing + origin)对齐:

• 新的 Channel(通道)——由滤波类操作(Gaussian blur、Top-hat、DoG、Otsu 阈值)产生,命名为 “<原通道名> - <操作名>”。Otsu 阈值输出为 0/1 二值图,其余为浮点滤波结果。
• MultiROI(多区域标签)——由标记类操作(Voronoi-Otsu、连通域)产生,命名为 “<原通道名> - <操作名>”,每个物体一个整数实例标签(0 为背景)。

结果发布后立即出现在场景中,无需重启 Dragonfly。面板底部的 Summary 栏会给出摘要:滤波结果显示操作名、设备、min / mean / max 与形状;标记结果显示操作名、设备、标签数(labels)与形状。

如何查看

• 新 Channel:在对象树中选中它,即可在 2D / 3D 视图中显示;可像其他 Channel 一样调整窗宽窗位或叠加显示。
• MultiROI:在对象树中展开,可查看各实例标签,用于后续的颗粒 / 细胞计数、形状测量或进一步分析。

9. 常见问题与故障排除

Q1:点 Compute 提示 “environment not set up”?

说明还没搭建运行环境。先点 Setup Environment 并等待 Status 显示 Ready,然后再点 Compute。

Q2:List devices 报告没有 OpenCL 设备怎么办?

pyclesperanto 需要一个 OpenCL ICD(驱动)。请安装显卡厂商驱动(通常自带 GPU 的 ICD);若机器没有 GPU,可安装 CPU OpenCL 运行时(POCL 或 Intel CPU runtime)作为回退设备,再重新点 List devices。设备枚举失败不会导致插件崩溃,只是列表为空。

Q3:Setup Environment 失败,提示没有 venv 模块或创建失败?

在 Base Python 输入框里指定一个带标准库 venv 与 pip 的 CPython 3.10+ 路径(例如 C:\Python312\python.exe),或形如 py -3.11 的命令,再重新点 Setup Environment。pyclesperanto 在 Windows 上需要 3.9–3.12 的预编译 wheel。

Q4:计算时提示内存不足(Out of memory)?

GPU / 内存无法容纳整幅体数据。请先裁剪出较小的 ROI 再处理,或对图像做降采样后再运行。

Q5:菜单里找不到该插件?

该插件默认未勾选。请确认安装时已勾选它,或在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 中勾选后重启 Dragonfly。菜单仅在启动时扫描。

Q6:下拉框里没有 Channel?

说明当前场景没有已加载的图像。先在 Dragonfly 中加载一幅图像,再点面板上的 Refresh 刷新列表。

10. 注意事项与已知限制

• 输入图像必须是 2D 或 3D 灰度数据;插件会先转换为 float32 再送入 GPU。
• OpenCL 驱动(ICD)是系统组件,不随插件安装。没有任何 OpenCL 设备时无法计算——请安装 GPU 驱动或 CPU OpenCL 运行时。
• 使用 CPU OpenCL 运行时作为回退设备时,速度优势会减弱(取决于 CPU 与实现)。GPU 加速的收益在大图像栈上最明显。
• 标记类操作(Voronoi-Otsu / 连通域)输出为 MultiROI,标签数量受图像内容与阈值影响;连通域标记依赖先行的 Otsu 阈值结果。
• 首次搭建环境需要联网一次;之后运行无需联网。
• 菜单仅在 Dragonfly 启动时扫描,启用 / 停用后需重启。
• 本插件随包使用稳定版 `pyclesperanto`,不使用 pyclesperanto_prototype;不同 pyclesperanto 版本的部分 API 名称(如 top-hat / 连通域)略有差异,插件已做兼容处理。

11. 参考资料

• pyclesperanto(计算引擎,BSD-3-Clause):https://github.com/clEsperanto/pyclesperanto
• clEsperanto 项目主页:https://clesperanto.github.io/
• OpenCL(Khronos):https://www.khronos.org/opencl/
• POCL(可移植的 CPU OpenCL 运行时):https://portablecl.org/

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation & Enabling

4. Runtime Environment & First-Run Setup

5. Interface Reference

6. Step-by-Step Usage

7. Parameter Reference

8. Outputs

9. FAQ & Troubleshooting

10. Notes & Known Limitations

11. References

1. Overview

GPU Image Filters (pyclesperanto) is a Dragonfly plugin that uses the GPU (OpenCL) to run fast image filtering and one-shot instance labeling on an image Channel. It moves heavy 2D/3D volume operations from the CPU onto the graphics card, and on large CT / microscopy stacks it is typically much faster than CPU-based scikit-image.

The underlying compute engine is the open-source pyclesperanto library (from the clEsperanto project), which executes image-processing kernels through OpenCL on a GPU or CPU device. The plugin ships the stable `pyclesperanto` (not the experimental pyclesperanto_prototype).

Six operations are provided in two output families: filter operations (Gaussian blur, top-hat background subtraction, difference-of-Gaussian, Otsu threshold) publish a new Channel; labeling operations (Voronoi-Otsu labeling, connected-components labeling) publish a MultiROI (one instance label per object). Results are published back into the Dragonfly scene aligned with the source grid (voxel spacing + origin).

License notes

• Compute engine pyclesperanto: BSD-3-Clause (permissive).
• numpy: BSD license.
• The plugin code follows the terms of the DragonflyPrototypeLabs project.
• The OpenCL driver (ICD) is a system component provided by a GPU vendor driver or a CPU OpenCL runtime; it is not installed via pip.

2. Use Cases

This plugin is aimed at batch pre-processing and pre-segmentation of large CT / microscopy stacks, especially where GPU acceleration pays off:

• Denoising and smoothing — suppress random noise with a Gaussian blur to give segmentation or measurement a smoother input.
• Background subtraction — remove slowly varying background non-uniformity with a top-hat transform to bring out small bright structures.
• Edge / blob enhancement — enhance blob-like or edge structures of a given scale with difference-of-Gaussian (DoG).
• Thresholding — split the image into foreground / background with automatic Otsu thresholding.
• One-click instance labeling — get instance segmentation of particles / cells directly (one label per object) with Voronoi-Otsu or connected-components labeling, output as a MultiROI.
• Big-data acceleration — on large image stacks, GPU filtering is typically far faster than CPU scikit-image.

3. Installation & Enabling

This plugin ships as part of the Prototype Apps in the Full Package installer. It is not ticked by default and must be enabled manually.

Install steps

1. Unzip the Full Package anywhere (prefer a short folder such as C:\PL\ to avoid path-length issues).

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, pick the core install mode (Fresh or Compatible) and tick "GPU Image Filters (pyclesperanto)..." in the Prototype Apps list (all plugins are OFF by default and must be ticked).

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

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

After the restart the menu item appears under Prototype Apps ▸ GPU Image Filters (pyclesperanto)... (in the "Filtering & Restoration" group). Clicking it opens a dockable / floating panel.

Changing your choice later

The easiest way is from 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. Disabling a plugin never deletes its built environment (venv) — re-enabling is instant.

Menus are discovered only at Dragonfly startup — every enable/disable change requires one restart before it takes effect.

Uninstall

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

4. Runtime Environment & First-Run Setup

The plugin uses the venv_in_code model: the compute engine (pyclesperanto + numpy) runs in a dedicated virtual environment (venv) driven by a subprocess, so it never touches Dragonfly's own Python. You must build that environment once before first use.

What Setup Environment does

When you click Setup Environment on the panel, the plugin:

1. Creates a local venv from a "base Python" (by default Dragonfly's own Python, i.e. Python_env\python.exe — no separate Python install needed).

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

3. pip-installs `pyclesperanto` (BSD-3) and `numpy` from the default PyPI index (both prebuilt wheels).

4. Runs a smoke check (prints numpy / pyclesperanto versions and detected OpenCL devices), then records the venv's Python path on success.

After setup, the panel's Status field shows Ready: <venv python path>. Later runs need no rebuild; if a usable venv already exists, it is reused.

Download size / internet / GPU requirements

Where the environment is installed

The venv lives inside the installed plugin code directory, i.e. ...\GenericMenuItems\Pyclesperanto\venv under %LOCALAPPDATA%\comet\<Dragonfly version>\pythonUserExtensions\. The OpenCL driver (ICD) itself is a system component and is not installed into this venv.

Fallbacks when setup fails

• Base Python has no venv module / venv creation fails: enter a different CPython 3.10+ path (e.g. C:\Python312\python.exe) or a launcher command like py -3.11 in the Base Python field and re-run Setup Environment. pyclesperanto needs CPython (prebuilt wheels for 3.9–3.12 on Windows).
• No OpenCL device: install a GPU vendor driver (provides the GPU's ICD) or a CPU OpenCL runtime (POCL / Intel CPU runtime) as a fallback, then click List devices again.

5. Interface Reference

The panel is organized top-to-bottom into the following groups (matching the code).

Input Channel

• Channel (dropdown) — lists every Channel in the current Dragonfly scene as "name (shape)". If the scene has no Channel it shows "(no channels - load an image in Dragonfly)".
• Refresh (button) — re-reads the Channel list from the scene. Click it after loading a new image.

Operation

• Operation (dropdown) — one of the six operations (see the parameter table). Switching operation automatically enables or disables the sigma / radius fields depending on whether that operation uses them.
• sigma (spin box) — Gaussian scale, range 0.0–50.0, step 0.5, default 2.0. Used by Gaussian blur, difference-of-Gaussian and Voronoi-Otsu labeling.
• radius (spin box) — structuring-element radius in voxels, range 0.0–100.0, step 1.0, default 5.0. Used only by top-hat background subtraction.

OpenCL device

• Device (dropdown) — the OpenCL device to compute on. The default entry is "(default)" (let pyclesperanto choose).
• List devices (button) — enumerates the OpenCL devices the venv can see and fills the dropdown (requires Setup Environment first).
• A note below reminds you that pyclesperanto needs an OpenCL ICD; a GPU driver usually provides one, otherwise a CPU OpenCL runtime (POCL / Intel) is a valid fallback device.

Environment (pyclesperanto venv)

• Base Python (field) — leave blank to use this Dragonfly's own Python, or enter a Python path or a command like py -3.11 to override the base interpreter.
• Status (label) — shows whether the environment is ready: Ready: <path> when built, otherwise a prompt to click Setup Environment first.

Action buttons & output area

• Setup Environment (button) — builds / reuses the venv and installs dependencies (see Chapter 4).
• Compute (button) — runs the computation with the selected Channel, operation and parameters and publishes the result back to Dragonfly.
• Summary (label) — a one-line summary of the result (operation, device, label count or statistics, shape).
• Log area (read-only text box) — shows progress and messages during the run (reading image, uploading to GPU, running operation, downloading result, publishing object, etc.).

6. Step-by-Step Usage

Workflow A: filtering (Channel output)

For Gaussian blur, top-hat background subtraction, difference-of-Gaussian, and Otsu threshold.

1. Input requirement: first load a 2D or 3D grayscale image (a Channel) in Dragonfly.

2. Open the Prototype Apps ▸ GPU Image Filters (pyclesperanto)... panel.

3. (First run) click Setup Environment and wait for Status to show Ready.

4. Pick the Channel to process in Input Channel (click Refresh if needed).

5. Choose a filter operation in Operation; adjust sigma (Gaussian family) or radius (top-hat) as needed.

6. (Optional) click List devices and pick a GPU or CPU OpenCL device in Device.

7. Click Compute. When it finishes, the log shows "Published: Channel" and a new Channel named "<source> - <operation>" appears in the scene — no restart needed.

Workflow B: one-click instance labeling (MultiROI output)

For Voronoi-Otsu labeling and connected-components labeling.

1. Input requirement: again load a grayscale image Channel (bright structures such as particles / cells).

2. Pick the Channel; in Operation choose "Voronoi-Otsu labeling" or "Connected components labeling".

3. Voronoi-Otsu uses sigma (as the spot / outline scale); connected-components labeling first applies Otsu threshold and needs no sigma / radius.

4. Click Compute. When it finishes, the log shows "Published: MultiROI (N labels)" and a MultiROI named "<source> - <operation>" appears in the scene — one instance label per object, aligned with the source grid.

7. Parameter Reference

Operations at a glance

Control defaults and ranges

8. Outputs

Depending on the operation, the plugin publishes different object types into the Dragonfly scene, all aligned with the source grid (spacing + origin):

• A new Channel — from filter operations (Gaussian blur, top-hat, DoG, Otsu threshold), named "<source> - <operation>". Otsu threshold outputs a 0/1 binary image; the others output a floating-point filtered result.
• A MultiROI — from labeling operations (Voronoi-Otsu, connected components), named "<source> - <operation>", with one integer instance label per object (0 is background).

The result appears in the scene immediately — no restart needed. The panel's Summary line reports: for a filter result, the operation, device, min / mean / max and shape; for a labeling result, the operation, device, label count and shape.

How to view

• New Channel: select it in the object tree to display it in 2D / 3D views; adjust window/level or overlay it like any other Channel.
• MultiROI: expand it in the object tree to inspect the instance labels for downstream particle / cell counting, shape measurement or further analysis.

9. FAQ & Troubleshooting

Q1: Compute says "environment not set up"?

The runtime environment has not been built yet. Click Setup Environment, wait for Status to show Ready, then click Compute again.

Q2: List devices reports no OpenCL device — now what?

pyclesperanto needs an OpenCL ICD (driver). Install a GPU vendor driver (usually provides the GPU's ICD); if the machine has no GPU, install a CPU OpenCL runtime (POCL or the Intel CPU runtime) as a fallback device and click List devices again. Device enumeration never crashes the plugin — it just returns an empty list.

Q3: Setup Environment fails saying there is no venv module or creation failed?

Enter a CPython 3.10+ with stdlib venv and pip (e.g. C:\Python312\python.exe) or a command like py -3.11 in the Base Python field, then re-run Setup Environment. pyclesperanto needs a prebuilt wheel (3.9–3.12 on Windows).

Q4: I get an out-of-memory error while computing?

The GPU / memory cannot hold the whole volume. Crop a smaller ROI before processing, or downsample the image and run again.

Q5: The plugin is not in the menu?

This plugin is off by default. Make sure you ticked it during install, or tick it under Developer ▸ Prototype Labs... ▸ Menu Item Manager and restart Dragonfly. Menus are only scanned at startup.

Q6: The Channel dropdown is empty?

There is no loaded image in the current scene. Load an image in Dragonfly first, then click Refresh on the panel.

10. Notes & Known Limitations

• The input image must be 2D or 3D grayscale data; the plugin converts it to float32 before sending it to the GPU.
• The OpenCL driver (ICD) is a system component and is not installed with the plugin. With no OpenCL device at all, computation cannot run — install a GPU driver or a CPU OpenCL runtime.
• Using a CPU OpenCL runtime as a fallback reduces the speed advantage (depends on the CPU and implementation). The GPU benefit is greatest on large image stacks.
• Labeling operations (Voronoi-Otsu / connected components) output a MultiROI; the number of labels depends on image content and thresholding, and connected-components labeling relies on the preceding Otsu threshold.
• The first environment setup needs internet once; later runs need none.
• Menus are scanned only at Dragonfly startup, so enabling / disabling requires a restart.
• The plugin ships the stable `pyclesperanto`, not pyclesperanto_prototype; some API names differ across pyclesperanto versions (e.g. top-hat / connected components), and the plugin already handles those variations.

11. References

• pyclesperanto (compute engine, BSD-3-Clause): https://github.com/clEsperanto/pyclesperanto
• clEsperanto project home: https://clesperanto.github.io/
• OpenCL (Khronos): https://www.khronos.org/opencl/
• POCL (Portable CPU OpenCL runtime): https://portablecl.org/