远程深度学习推理 (Remote DL Inferring) 插件用户手册

Remote DL Inferring - User Manual

Dragonfly Prototype Apps · Remote DL Inferring...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

远程深度学习推理(Remote DL Inferring) 是一个在 Dragonfly 3D World 内运行的可停靠面板插件。它把一个已经训练好的深度学习分割模型应用到一张图像(Channel)上,在远程(或本机)的 Dragonfly 服务器进程中完成推理,最终得到一个分割结果 MultiROI。

面板顶部是一条 远程 Dragonfly 服务器 设置栏,用于填写目标服务器的地址(Address)、端口(Port)和访问令牌(Token);下方则是与独立版应用完全一致的 Remote DL Inferring 标签页(选择服务器上已有的模型,或上传一个模型 zip,应用到 Channel 并可逐切片实时预览)。所有网络请求都会发送到你在顶部设置的服务器。

这样的设计让一台没有 GPU / 性能有限的电脑上的 Dragonfly,可以把繁重的推理任务交给另一台带 GPU 的 Dragonfly 服务器去做——服务器可以通过 Tailscale 虚拟 IP(如 100.64.0.2)或局域网 IP(如 192.168.0.82)访问。它与配套的 远程深度学习训练(Remote DL Training) 插件搭配使用:先训练模型,再用本插件推理。

底层引擎 / 技术

• 推理由 Dragonfly 内置的深度学习分割引擎(与 Dragonfly「Deep Learning Tool / Segment with AI」相同的底层能力)在服务器进程中执行,本插件只负责把图像与模型送过去、把结果取回来。
• 本插件界面代码来自 gui_qt 包(与独立版应用、嵌入式 Prototype Labs 面板共用同一套 UI),使用 PyQt6(2025.1 与 2027.1 均随附 PyQt6 6.7.1)。
• 客户端与服务器之间使用长度前缀 JSON 报文(length-prefixed JSON)+ 可选二进制的 TCP 协议通信,默认端口 54321。
• 无需 venv、无需下载:插件运行于 Dragonfly 自带的 Python 中。

许可证要点

本插件是 Dragonfly Prototype Apps 的一部分,推理能力依赖 Dragonfly 自身的深度学习工具,受你所安装的 Dragonfly 许可协议约束。插件本身不引入额外的第三方重型依赖。

2. 适用场景

本插件适用于希望把深度学习推理从本地转移到远程 GPU 服务器的工作流:在客户端 Dragonfly 中选好要分割的图像,一键提交到远程服务器推理,并在本地实时查看分割结果预览。

• GPU 卸载:本地机器没有独立显卡或算力不足,而实验室 / 机房里有一台带 GPU 的 Dragonfly。用本插件把推理送到那台机器上跑。
• 训练—推理配套:先用 Remote DL Training 插件在服务器上训练好一个分割模型,再用本插件把该模型应用到新的图像上。
• 批量 / 大体积数据:当图像位于服务器可直接读取的共享盘上时,可用「直接读取路径」模式,避免上传大文件(单个上传文件限制 200 MB)。
• 本机推理:把地址设为 127.0.0.1 即可让本机 Dragonfly 自己推理(此时无需令牌),或使用「本地无窗口 Dragonfly 子进程」在本机后台推理。

3. 安装与启用

本插件通过 Full Package(完整安装包) 安装。安装步骤如下:

1. 把安装包解压到任意较短的路径(如 C:\PL\,避免过深的目录导致「路径过长」)。

2. 双击 `Install_FullPackage.bat`。

3. 在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),并在 Prototype Apps 列表中勾选 Remote DL Inferring(见下方说明)。

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

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

本插件默认未勾选。 在安装包的应用列表中,轻量菜单项默认开启,而所有插件(含本插件)默认关闭。请务必手动勾选 Remote DL Inferring 才会安装。

重启后,插件出现在菜单栏的以下位置:

• Prototype Apps ▸ Remote DL Inferring...(所在分组:Train Custom Model / Remote Deep Learning)。

依赖:必须同时安装 Prototype Labs 嵌入式包

本插件的界面代码来自 gui_qt 包,而该包由 Prototype Labs 嵌入式包 提供。安装本插件时请同时勾选 / 安装 Prototype Labs 嵌入式包。插件会在运行时从相邻的 GenericMenuItems\Prototype_Labs 文件夹解析 gui_qt;若缺失,面板会显示「找不到 gui_qt」的错误。

以后修改勾选(启用 / 停用)

安装后如需启用或停用本插件,最方便的方式是在 Dragonfly 内操作:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部「Prototype Apps (Full Package)」列表中勾选 / 取消 Remote DL Inferring,然后重启 Dragonfly 生效。停用从不删除任何环境,重新启用立即可用。

也可以随时重跑安装器(会记住上次的勾选作为默认值)。

卸载

双击 `Uninstall_FullPackage.bat`(位于 %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer 中也有一份),即可移除所有 Full Package 的菜单项与插件。

4. 运行环境与首次配置

本插件是 in_process(进程内) 类型:它运行在 Dragonfly 自带的 Python 中,不需要单独的 venv、不需要 Setup Environment、安装时不下载任何东西。因此没有独立的「运行环境搭建」步骤。

首次配置:连接目标服务器

首次打开面板后,唯一需要的「配置」是在顶部设置栏填写目标 Dragonfly 服务器的连接信息:

1. 在 Address 中填写服务器地址:远程可填 Tailscale IP(如 100.64.0.2)或局域网 IP(如 192.168.0.82);本机填 127.0.0.1。

2. 在 Port 中填写服务器端口(默认 54321)。

3. 在 Token 中填写服务器的访问令牌:连接远程服务器必须填写正确令牌;连接 `127.0.0.1` 则留空即可。

4. 点击 Apply 应用设置,或点击 Test 先连接并 ping 一下检查地址 / 端口 / 令牌是否可用。

令牌不会保存到磁盘(出于安全考虑):地址与端口会跨会话记住,但令牌每次会话都需要重新输入。

前提:目标服务器必须正在运行

使用前,目标端必须有一台已启动 Prototype Labs 服务器的 Dragonfly 在运行,并且该服务器已就绪(GUI 内启动了 TCP 服务器,或运行了无窗口的 headless 服务器)。若连接失败,请先确认服务器已启动、地址端口正确、令牌无误。

5. 界面说明

面板从上到下分为服务器设置栏与推理标签页两大部分,推理标签页又分左右两列。以下逐一说明各控件(与代码一致)。

5.1 顶部:远程 Dragonfly 服务器栏

• Address(地址):文本框,填写目标服务器地址;占位提示为 e.g. 100.64.0.2 (Tailscale) / 192.168.0.82 (LAN) / 127.0.0.1。
• Port(端口):数字框(范围 1–65535),默认取自配置(通常为 54321)。
• Token(令牌):密码框(输入以圆点遮盖);占位提示为「remote 必填,127.0.0.1 可留空」。
• Apply(应用):把当前地址 / 端口 / 令牌设为后续推理的目标服务器。
• Test(测试):连接并 ping 服务器,验证地址 / 端口 / 令牌是否可达。
• 状态行:显示当前目标,如 Target: 100.64.0.2:54321 (remote - token set);会提示 loopback「无需令牌」、「remote - token set」或「remote - TOKEN REQUIRED」。

5.2 左列:待分割图像与模型

Image to segment(待分割图像) 分组:

• Image(图像):文本框 + Browse... 按钮,选择要分割的图像。可为 .ORSObject Channel,或原始图像文件(.tif/.tiff/.png/.jpg/.jpeg/.bmp)。
• Channel index(通道索引):数字框(0–999),当 .ORSObject 中包含多个 Channel 时指定用第几个(0 = 第一个)。

Model(模型) 分组(二选一):

• Use a model already on the Dragonfly server(使用服务器上已有模型):默认选中。下方为模型下拉框 + Refresh list(刷新列表) 按钮;列表来自服务器 AI 库中已训练完成的模型,条目形如「模型名 (N classes)」,多输入模型会标注 [needs N inputs]。
• Upload a model .zip(上传模型 zip):选择本地的模型 zip 文件(由 Remote DL Training 或 Dragonfly 导出);下方为文本框 + Browse... 按钮。

5.3 右列:文件传输、运行位置与结果

How should the server get the files?(服务器如何获取文件?) 分组:

• Upload to the Dragonfly server(上传到服务器):默认选中。跨机器可用,但每个文件必须小于 200 MB。
• The server can read these paths directly(服务器直接读取路径):同机或共享盘时可用,不限大小。

Where should inference run?(推理在哪里运行?) 分组:

• On the connected Dragonfly (GUI Sync)(在连接的 Dragonfly 上):默认选中。把推理发送到你在顶部配置的服务器(带 GUI 的 Dragonfly,或 headless 服务器)。
• Headless of local Dragonfly (subprocess)(本机无窗口 Dragonfly 子进程):在本机启动一个无窗口 Dragonfly 进程推理,直接读取所选文件,Cancel 可硬停止。
• Headless on a Dragonfly Server (no GUI)(在无 GUI 的 Dragonfly 服务器上):连接到你自己在另一台机器上启动的 headless Dragonfly 服务器;旁边的 ? 按钮会弹出「什么是 headless 服务器、如何启动」的说明。
• Dragonfly(版本下拉)+ Detect(检测):仅当选择「本机子进程」时有效,用于选择由哪个本机 Dragonfly 安装运行子进程(建议选 2026.x)。

Result(结果) 分组:

• Also save to(同时保存到):可选文本框,填写服务器端 .ORSObject 路径,把结果直接额外保存一份(在「直接读取路径」模式下最有用)。

5.4 底部:可视化反馈、日志与操作按钮

• Visual feedback(可视化反馈,可折叠,默认折叠):勾选 Show segmentation preview(显示分割预览) 后,推理会按 z 方向分块处理,预览随扫描逐块刷新;Preview every(每隔多少切片预览) 数字框默认 0(自动 = 图像 z 切片数的 1/10)。该功能需要服务器与本机共享文件系统(即服务器在本机 / loopback,或本机子进程);否则该区块被禁用并给出说明。
• Run inference(运行推理):开始推理。
• Cancel(取消):默认禁用;可视化反馈的分块推理可在下一块之间停止,本机子进程可随时硬停止。
• Download Result MultiROI(下载结果 MultiROI):默认禁用,推理成功后可用,把结果保存为本地 .ORSObject。
• Status(状态)/ 进度行 / Log(日志,可折叠):显示当前状态(Idle/Connecting/Inferring slice x/y/Done/Failed 等)、进度与详细日志。

6. 使用步骤

6.1 端到端:在远程 GPU 服务器上推理

输入要求:一台已启动 Prototype Labs 服务器的远程 Dragonfly + 其访问令牌;一张待分割图像;服务器 AI 库中已有一个已训练的单输入分割模型(或本地的模型 zip)。

1. 菜单栏点击 Prototype Apps ▸ Remote DL Inferring... 打开面板。

2. 在顶部填写服务器 Address / Port / Token,点击 Test 确认可连接,再点击 Apply。

3. 在 Image to segment 中通过 Browse... 选择待分割图像;若是含多 Channel 的 .ORSObject,设置 Channel index。

4. 在 Model 中保持「使用服务器上已有模型」,点击 Refresh list 加载列表并选一个模型;或改选「上传模型 zip」并选择本地 zip。

5. 在 How should the server get the files? 中,跨机器保持「上传到服务器」(每个文件 < 200 MB);同机或共享盘可选「直接读取路径」。

6. 在 Where should inference run? 中保持「On the connected Dragonfly (GUI Sync)」。

7. (可选)展开 Visual feedback 并勾选「显示分割预览」以实时观察进度(需共享文件系统)。

8. 点击 Run inference 开始;在 Status / Log 中观察进度。

9. 完成后点击 Download Result MultiROI,选择保存位置,把结果 MultiROI 保存到本地 .ORSObject。

得到什么:一个分割结果 MultiROI(可下载为本地 .ORSObject),日志会给出标签数量与文件大小。

6.2 本机推理(无需远程服务器)

1. 把 Address 设为 127.0.0.1、Token 留空,点击 Apply(此时本机 Dragonfly 需已启动服务器);或者在 Where should inference run? 中选择「本机无窗口 Dragonfly 子进程」并用 Detect 选择本机的 Dragonfly 版本(建议 2026.x)。

2. 按 6.1 的第 3–5 步选择图像与模型。

3. 点击 Run inference;子进程模式下 Cancel 可随时硬停止。

4. 完成后下载或(直接模式下)在服务器端指定路径查看结果。

多输入模型不受支持:本标签页只提供单张图像。若所选模型需要多个输入通道,会弹出提示,请改用单输入模型,或直接在 Dragonfly 中处理多输入模型。

7. 参数说明

8. 输出结果

推理成功后产生的核心结果是一个分割 MultiROI(多标签 ROI 对象),对应模型对图像各类别的分割。

• 结果 MultiROI:在服务器进程中生成,点击 Download Result MultiROI 可下载为本地 .ORSObject 文件,随后可在 Dragonfly 中打开查看。日志会显示标签数(label 数)与文件大小。
• 额外直接保存(可选):若填写了 Also save to 路径(直接 / 共享模式),结果会额外在服务器端保存为一个 .ORSObject。
• 可视化反馈预览:开启后,推理过程中会在预览区显示逐切片的分割预览图,并标注当前切片(如「Inference preview at slice X (of Y)」)。这是过程预览,最终结果仍以下载的 MultiROI 为准。
• 日志(Log):记录整个推理过程,便于排查(连接、上传、推理、结果大小、错误堆栈等)。

若图像是单切片 / 2D,则没有逐切片预览,日志会提示「可视化反馈已跳过(2D / 单切片图像)」,但推理结果不受影响。

9. 常见问题与故障排除

Q1:面板打开后显示「找不到 gui_qt / Failed to load Remote DL Inferring panel」怎么办?

A:本插件的界面来自 Prototype Labs 嵌入式包 提供的 gui_qt。请确认你也安装了 Prototype Labs 嵌入式包(它会安装到相邻的 GenericMenuItems\Prototype_Labs 文件夹)。安装后重启 Dragonfly 再试。

Q2:点击 Test 提示「cannot reach server / 无法连接服务器」?

A:依次检查:(1) 目标 Dragonfly 是否正在运行且已启动 Prototype Labs 服务器;(2) Address 与 Port 是否正确;(3) 远程连接是否填了正确的 Token(状态行若显示「TOKEN REQUIRED」说明缺令牌);(4) 网络 / Tailscale / 防火墙是否放通该端口。

Q3:模型列表为空 /「no trained models on the server」?

A:列表只显示服务器 AI 库中已训练完成的模型。请先用 Remote DL Training 训练并保存一个模型到该服务器,或改用「上传模型 zip」。点击 Refresh list 重新加载。

Q4:提示模型需要多个输入通道,无法推理?

A:本标签页只提供单张图像输入,不支持多输入模型。请选择单输入(single-input)模型,或直接在 Dragonfly 的深度学习工具中处理多输入模型。

Q5:上传时报文件过大 / 想跑很大的数据?

A:上传模式下每个文件必须小于 200 MB。若数据更大,请把图像放在服务器能直接读取的路径(同机或共享盘),并在「服务器如何获取文件」中选择「直接读取路径」。

Q6:可视化反馈(预览)区被禁用 / 灰掉了?

A:预览需要读取服务器写出的预览图,因此要求本机与服务器共享文件系统——即服务器在本机(loopback),或使用「本机无窗口子进程」。连接到另一台机器上的服务器时没有共享路径,预览不可用,但推理仍会正常运行,完成后下载结果即可。

10. 注意事项与已知限制

• 必须先启动目标服务器:插件本身不会启动 Dragonfly 服务器;远程 / 本机目标都需事先运行并启动 Prototype Labs 服务器。
• 令牌不落盘:地址与端口跨会话记住,但令牌每次会话都需重新输入(安全考虑)。
• 远程必须提供令牌;连接 127.0.0.1 无需令牌。
• 依赖 Prototype Labs 嵌入式包:缺少 gui_qt 时面板无法加载。
• 只支持单输入分割模型;多输入模型请直接在 Dragonfly 中使用。
• 上传单文件上限 200 MB;更大数据请用「直接读取路径」模式。
• 可视化反馈需共享文件系统;连接异机服务器时预览不可用(推理不受影响)。
• 客户端不做算力:推理速度取决于服务器端(建议服务器带 GPU、使用 2026.x 版本进行深度学习)。
• 每次修改菜单勾选后需重启 Dragonfly 才能生效。

11. 参考资料

• 配套插件:Remote DL Training(远程深度学习训练)——用于在服务器上训练分割模型。
• Dragonfly 深度学习 / AI 分割工具官方文档(参见你所安装 Dragonfly 版本的 Help 文档)。
• Full Package 安装 / 启用 / 卸载说明:随包 README.md 与 Install_FullPackage.bat / Uninstall_FullPackage.bat。
• Prototype Labs 面板与 Menu Item Manager:Dragonfly 内 Developer ▸ Prototype Labs...。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation & Enabling

4. Runtime Environment & First-Run Setup

5. Interface Guide

6. Step-by-Step Usage

7. Parameter Reference

8. Output

9. FAQ & Troubleshooting

10. Notes & Known Limitations

11. References

1. Overview

Remote DL Inferring is a dockable panel plugin that runs inside Dragonfly 3D World. It applies an already-trained deep-learning segmentation model to an image (a Channel), performing the inference in a remote (or local) Dragonfly server process, and returns a segmentation MultiROI.

The top of the panel is a Remote Dragonfly server bar for the target server's Address, Port and access Token; below it is the exact Remote DL Inferring tab from the standalone app (pick a model already on the server, or upload a model zip, apply it to a Channel, with optional slab-by-slab live preview). Every request goes to the server you set at the top.

This lets a GPU-less / limited machine's Dragonfly offload heavy inference to another GPU-equipped Dragonfly server — reachable via a Tailscale IP such as 100.64.0.2 or a LAN IP such as 192.168.0.82. It pairs with the companion Remote DL Training plugin: train a model, then infer with this plugin.

Underlying engine / technology

• Inference is executed by Dragonfly's built-in deep-learning segmentation engine (the same capability as Dragonfly's Deep Learning / Segment-with-AI tools) in the server process; the plugin only sends the image and model and retrieves the result.
• The plugin's UI comes from the gui_qt package (shared with the standalone app and the embedded Prototype Labs panel), built on PyQt6 (both 2025.1 and 2027.1 ship PyQt6 6.7.1).
• Client and server communicate over a length-prefixed JSON (+ optional binary) TCP protocol, default port 54321.
• No venv, no downloads: the plugin runs in Dragonfly's own Python.

Licensing notes

This plugin is part of the Dragonfly Prototype Apps. Its inference capability relies on Dragonfly's own deep-learning tools and is governed by the Dragonfly license you have installed. The plugin itself introduces no additional heavy third-party dependencies.

2. Use Cases

Use this plugin to move deep-learning inference from a local machine to a remote GPU server: choose the image to segment in the client Dragonfly, submit it to the remote server with one click, and watch the segmentation preview locally in real time.

• GPU offload: your local machine has no discrete GPU or limited compute, but a GPU-equipped Dragonfly exists elsewhere. Send inference to that machine.
• Train-then-infer pairing: first train a segmentation model on the server with the Remote DL Training plugin, then apply it to new images here.
• Batch / large data: when the image lives on a drive the server can read directly, use direct-path mode to avoid uploading large files (each uploaded file must be < 200 MB).
• Local inference: set the address to 127.0.0.1 to have the local Dragonfly infer (no token needed), or use the local windowless Dragonfly subprocess to infer in the background on this machine.

3. Installation & Enabling

This plugin is installed via the Full Package installer:

1. Unzip the package to any short path (e.g. C:\PL\) to avoid "path too long" errors from deep folders.

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, choose the core install mode (Fresh / Compatible) and tick Remote DL Inferring in the Prototype Apps list (see note below).

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 OFF 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 Remote DL Inferring for it to install.

After restart, the plugin appears at:

• Prototype Apps ▸ Remote DL Inferring... (group: Train Custom Model / Remote Deep Learning).

Dependency: also install the Prototype Labs embedded package

The plugin's UI comes from the gui_qt package, which is provided by the Prototype Labs embedded package. When installing this plugin, also tick / install the Prototype Labs embedded package. At runtime the panel resolves gui_qt from the sibling GenericMenuItems\Prototype_Labs folder; if it is missing, the panel shows a "could not find gui_qt" error.

Change your choice later (enable / disable)

To enable or disable the plugin afterwards, the easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager, tick / untick Remote DL Inferring in the bottom "Prototype Apps (Full Package)" list, then restart Dragonfly. Disabling never deletes any environment; re-enabling is instant.

You can also re-run the installer anytime (it remembers your previous choices as the new defaults).

Uninstall

Double-click `Uninstall_FullPackage.bat` (a copy also lives in %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer) to remove all Full-Package menu items and plugins.

4. Runtime Environment & First-Run Setup

This plugin is in_process: it runs in Dragonfly's own Python and needs no separate venv, no Setup Environment step, and downloads nothing at install time. There is therefore no dedicated environment-build step.

First-run configuration: connect to the target server

The only "configuration" needed on first open is to enter the target Dragonfly server's connection details in the top bar:

1. Enter the server Address: a Tailscale IP (e.g. 100.64.0.2) or LAN IP (e.g. 192.168.0.82) for a remote server; 127.0.0.1 for the local machine.

2. Enter the Port (default 54321).

3. Enter the Token: required for a remote server; leave blank for `127.0.0.1`.

4. Click Apply to apply the settings, or Test first to connect and ping the server and check the address / port / token.

The token is NOT saved to disk (for security): the address and port are remembered across sessions, but the token must be re-entered each session.

Prerequisite: the target server must be running

Before use, the target must be a running Dragonfly with the Prototype Labs server started (either the TCP server started inside a GUI Dragonfly, or a windowless headless server). If a connection fails, first confirm the server is running, the address/port are correct, and the token is right.

5. Interface Guide

The panel is split into a server bar at the top and an inference tab below, and the tab has left and right columns. Each control is described below (matching the code).

5.1 Top: Remote Dragonfly server bar

• Address: text field for the target server address; placeholder e.g. 100.64.0.2 (Tailscale) / 192.168.0.82 (LAN) / 127.0.0.1.
• Port: spin box (range 1–65535), defaulting to the configured value (typically 54321).
• Token: password field (masked with dots); placeholder notes it is required for remote and can be blank for 127.0.0.1.
• Apply: use this server for the inference below.
• Test: connect + ping the server to check the address / port / token.
• Status line: shows the current target, e.g. Target: 100.64.0.2:54321 (remote - token set); it also reports loopback "no token needed", "remote - token set", or "remote - TOKEN REQUIRED".

5.2 Left column: image to segment and model

Image to segment group:

• Image: text field + Browse... button to select the image. It can be an .ORSObject Channel or a raw image (.tif/.tiff/.png/.jpg/.jpeg/.bmp).
• Channel index: spin box (0–999) selecting which Channel to use when the .ORSObject holds several (0 = first).

Model group (one of two):

• Use a model already on the Dragonfly server: selected by default. Below it is a model dropdown + Refresh list button; the list contains the trained models in the server's AI library, each shown as "name (N classes)"; multi-input models are marked [needs N inputs].
• Upload a model .zip: select a local model zip (exported by Remote DL Training or Dragonfly) via a text field + Browse... button.

5.3 Right column: file transfer, run location, result

How should the server get the files? group:

• Upload to the Dragonfly server: selected by default. Works across machines, but each file must be under 200 MB.
• The server can read these paths directly: for the same machine or a shared drive; any size.

Where should inference run? group:

• On the connected Dragonfly (GUI Sync): selected by default. Sends inference to the server configured at the top (a GUI Dragonfly or a headless server).
• Headless of local Dragonfly (subprocess): spawns a windowless Dragonfly process on this machine to infer, reading the selected files directly; Cancel hard-stops it.
• Headless on a Dragonfly Server (no GUI): connects to a headless Dragonfly server you started yourself on another machine; the adjacent ? button explains what it is and how to start one.
• Dragonfly (version dropdown) + Detect: only active for the local subprocess mode; selects which local Dragonfly install runs the subprocess (a 2026.x install is recommended).

Result group:

• Also save to: optional text field for a server-side .ORSObject path to also save the result directly (most useful in direct-path mode).

5.4 Bottom: visual feedback, log, action buttons

• Visual feedback (collapsible, collapsed by default): ticking Show segmentation preview processes the volume in z-slabs so the preview refreshes as inference scans down; Preview every spin box defaults to 0 (auto = 1/10 of the image's z slices). This needs a filesystem shared between the app and the server (server on this machine / loopback, or the local subprocess); otherwise the section is disabled with an explanation.
• Run inference: start the inference.
• Cancel: disabled by default; a visual-feedback slab run can be stopped between slabs, and a local subprocess can be hard-stopped at any time.
• Download Result MultiROI: disabled by default, enabled after a successful run; saves the result as a local .ORSObject.
• Status / progress line / Log (collapsible): shows the current status (Idle/Connecting/Inferring slice x/y/Done/Failed, etc.), progress, and a detailed log.

6. Step-by-Step Usage

6.1 End-to-end: infer on a remote GPU server

Inputs required: a running remote Dragonfly with the Prototype Labs server started plus its access token; an image to segment; a trained single-input segmentation model already in the server's AI library (or a local model zip).

1. Open the panel from Prototype Apps ▸ Remote DL Inferring....

2. Enter the server Address / Port / Token at the top, click Test to confirm reachability, then click Apply.

3. In Image to segment, Browse... to the image; if it is a multi-Channel .ORSObject, set Channel index.

4. In Model, keep "Use a model already on the Dragonfly server", click Refresh list and pick a model; or switch to "Upload a model .zip" and select a local zip.

5. In How should the server get the files?, keep "Upload to the Dragonfly server" across machines (each file < 200 MB); use "direct paths" for the same machine or a shared drive.

6. In Where should inference run?, keep "On the connected Dragonfly (GUI Sync)".

7. (Optional) expand Visual feedback and tick "Show segmentation preview" to watch progress live (needs a shared filesystem).

8. Click Run inference; watch progress in Status / Log.

9. When done, click Download Result MultiROI, choose a location, and save the result MultiROI as a local .ORSObject.

What you get: a segmentation MultiROI (downloadable as a local .ORSObject); the log reports the label count and file size.

6.2 Local inference (no remote server)

1. Set Address to 127.0.0.1, leave Token blank, and click Apply (the local Dragonfly must have its server started); or, in Where should inference run?, choose "Headless of local Dragonfly (subprocess)" and use Detect to pick the local Dragonfly version (2026.x recommended).

2. Select the image and model as in steps 3–5 of 6.1.

3. Click Run inference; in subprocess mode, Cancel can hard-stop it at any time.

4. When done, download the result, or (in direct mode) view it at the server-side path you specified.

Multi-input models are not supported: this tab provides a single image only. If the chosen model needs multiple input channels, a warning appears — use a single-input model, or process multi-input models directly in Dragonfly.

7. Parameter Reference

8. Output

The core result of a successful run is a segmentation MultiROI (a multi-label ROI object) corresponding to the model's per-class segmentation of the image.

• Result MultiROI: created in the server process; click Download Result MultiROI to save it as a local .ORSObject, then open it in Dragonfly. The log shows the label count and file size.
• Extra direct save (optional): if an Also save to path is given (direct / shared mode), the result is also saved server-side as an .ORSObject.
• Visual-feedback preview: when enabled, a slab-by-slab segmentation preview appears in the preview pane during inference, captioned with the current slice (e.g. "Inference preview at slice X (of Y)"). This is a progress preview; the final result is the downloaded MultiROI.
• Log: records the whole inference process (connect, upload, infer, result size, error tracebacks) for troubleshooting.

If the image is single-slice / 2D, there is no per-slice preview and the log notes "Visual feedback skipped (2D / single-slice image)"; the inference result is unaffected.

9. FAQ & Troubleshooting

Q1: The panel shows "could not find gui_qt / Failed to load Remote DL Inferring panel" — what now?

A: The plugin's UI comes from the gui_qt package provided by the Prototype Labs embedded package. Confirm you also installed that package (it installs to the sibling GenericMenuItems\Prototype_Labs folder), then restart Dragonfly and try again.

Q2: Clicking Test says "cannot reach server"?

A: Check in order: (1) the target Dragonfly is running with the Prototype Labs server started; (2) the Address and Port are correct; (3) for a remote server the correct Token is entered (if the status line says "TOKEN REQUIRED", the token is missing); (4) the network / Tailscale / firewall allows that port.

Q3: The model list is empty / "no trained models on the server"?

A: The list only shows trained models in the server's AI library. First train and save a model to that server with Remote DL Training, or switch to "Upload a model .zip". Click Refresh list to reload.

Q4: It says the model needs multiple input channels and won't infer?

A: This tab provides a single image only and does not support multi-input models. Choose a single-input model, or handle multi-input models directly in Dragonfly's deep-learning tools.

Q5: Upload says the file is too large / I need to run very large data?

A: In upload mode each file must be under 200 MB. For larger data, place the image on a path the server can read directly (same machine or a shared drive) and choose "The server can read these paths directly".

Q6: The visual-feedback (preview) section is disabled / greyed out?

A: The preview reads a preview image the server writes, so it requires a filesystem shared between your app and the server — i.e. the server on this machine (loopback) or the local subprocess. Connecting to a server on another machine has no shared path, so the preview is unavailable, but inference still runs; download the result when it finishes.

10. Notes & Known Limitations

• Start the target server first: the plugin does not start a Dragonfly server; the remote / local target must already be running with the Prototype Labs server started.
• Token is not persisted: address and port are remembered across sessions, but the token must be re-entered each session (for security).
• Remote requires a token; connecting to 127.0.0.1 needs none.
• Depends on the Prototype Labs embedded package: without gui_qt the panel cannot load.
• Single-input segmentation models only; use multi-input models directly in Dragonfly.
• Upload limit of 200 MB per file; use direct-path mode for larger data.
• Visual feedback needs a shared filesystem; unavailable when connecting to a server on another machine (inference itself is unaffected).
• The client does no compute: inference speed depends on the server (a GPU and a 2026.x install are recommended for deep learning).
• Restart Dragonfly after any menu enable/disable change for it to take effect.

11. References

• Companion plugin: Remote DL Training — trains segmentation models on the server.
• Dragonfly deep-learning / AI segmentation documentation (see the Help of your installed Dragonfly version).
• Full Package install / enable / uninstall guide: the bundled README.md and Install_FullPackage.bat / Uninstall_FullPackage.bat.
• Prototype Labs panel and Menu Item Manager: Developer ▸ Prototype Labs... inside Dragonfly.