BigStitcher Lite 插件用户手册

BigStitcher Lite - User Manual

Dragonfly Prototype Apps · BigStitcher Lite...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

BigStitcher Lite 是一款在 Dragonfly 内运行的轻量级图像块(tile)拼接工具。它把多个已经导入 Dragonfly 的 Channel tile,按照平移(translation)对齐后融合为一个全新的拼接 Channel,并同时导出一份 offsets.csv 偏移量清单。该插件的设计灵感来自 BigStitcher 的使用场景,但不依赖 Fiji、ImageJ 或 Java,完全使用 Python 科学计算库在本地完成拼接。

底层引擎 / 算法。 拼接核心是纯 Python 实现的 bigstitcher_core 模块,依赖三个常见科学计算库:numpy(数组运算与融合画布)、scipy 以及 scikit-image。当选择自动估计偏移时,平移量由 scikit-image 的 skimage.registration.phase_cross_correlation(相位相关 / phase correlation)计算得到;融合(blending)则在 numpy 画布上按均值、最大值、第一个 tile 优先或最后一个 tile 优先的方式完成。

"Lite" 定位。 顾名思义,这是一个有意精简的版本,聚焦最常用的平移拼接这一最小可用能力:它只支持整数体素(voxel)平移偏移,不做旋转、仿射(affine)或形变(deformable)配准,也不复刻完整 BigStitcher 生态中的元数据导入、interest-point 配准或大规模分布式处理。

许可证要点。 本插件为 Dragonfly Prototype Apps 内部工具。它调用的第三方库(NumPy、SciPy、scikit-image)均为宽松开源许可(BSD / 3-clause 类),这些库在您首次配置环境时从 PyPI 联网安装到插件自己的独立虚拟环境中,不与 Dragonfly 自带的 Python 环境混用。

2. 适用场景

当您已经把分块采集(tiled acquisition)的数据以多个 Channel 的形式导入 Dragonfly,并希望在 Dragonfly 内部完成一次快速、轻量的平移拼接或预览融合时,本插件非常合适。典型场景包括:

• 显微成像:荧光、共聚焦或宽场显微镜按视场分块拍摄的多个 tile,已知或可估计的 X/Y 平移偏移。
• CT / 断层数据:大样品分区扫描后得到的多个体数据块,需要沿 Z/Y/X 方向拼接为一个整体。
• 其他分块数据:任何已经载入 Dragonfly、彼此之间仅存在平移关系的 2D 或 3D Channel。
• 快速预览融合:在做完整、精确的配准之前,先用相位相关快速估计一版对齐效果,判断分块顺序与重叠是否合理。

本插件面向 "先拼出来看看" 的轻量需求。如果您的数据需要旋转 / 仿射配准、逐对重叠感知的精确配准、或大规模分布式处理,应使用专门的完整拼接方案;BigStitcher Lite 不覆盖这些高级功能。

3. 安装与启用

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

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

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

3. 在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),然后在 Prototype Apps 列表中勾选 BigStitcher Lite。

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

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

默认未勾选,需要手动启用。 在安装包中,所有插件默认处于关闭状态(轻量菜单项默认开启)。因此 BigStitcher Lite 必须在安装时手动勾选,或稍后在 Dragonfly 内启用。

重启后菜单位置。 启用并重启后,插件出现在 Dragonfly 顶部的 Prototype Apps 菜单下,标题为 BigStitcher Lite...,归类在 Reconstruction & Imaging 分组内。点击即可打开插件面板。

以后修改勾选。 最方便的方式是在 Dragonfly 内操作:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部的 "Prototype Apps (Full Package)" 列表里找到 BigStitcher Lite,勾选=部署,取消=移除菜单项,重启 Dragonfly 生效。停用从不删除插件已搭建好的环境,重新启用即刻可用。

每次修改勾选(启用 / 停用)都需要重启一次 Dragonfly 才能生效,因为菜单仅在启动时被扫描。

卸载。 双击 Uninstall_FullPackage.bat 可移除所有 Full Package 菜单项与插件。卸载会保留插件已搭建的运行环境(venv),脚本结束时会列出这些路径,如需释放磁盘空间可手动删除。

4. 运行环境与首次配置

BigStitcher Lite 采用独立虚拟环境(venv)的方式隔离依赖:拼接计算在一个专属的 Python 子进程里运行,不污染 Dragonfly 自带的 Python。首次使用前需要在 Setup 分页里搭建一次这个环境。

4.1 Setup Environment 做什么

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

1. 选择一个 Base Python(基础解释器)来创建虚拟环境。若 "Base Python" 留空,插件会自动探测:优先使用 Dragonfly 自带的 Python,其次是系统的 py 启动器 / python,以及常见的 Miniconda / Anaconda 安装位置。您也可以用 Browse... 手动指定一个 python.exe。

2. 在插件代码目录内创建一个名为 venv 的子文件夹作为独立虚拟环境。

3. 升级该环境的 pip,然后从 PyPI 联网安装 numpy、scipy、scikit-image 三个依赖。

4. 安装成功后,把新建的虚拟环境 python 路径回填到 Analysis venv python 一栏,并保存到配置中。

4.2 下载体积与联网 / 硬件要求

• 需要联网:仅在首次 Setup 时用于从 PyPI 下载 numpy / scipy / scikit-image 及其依赖。之后的日常拼接不需要联网。
• 下载体积:三个库及其依赖合计约数百 MB(具体取决于网络与 pip 解析结果)。请预留足够磁盘空间与耐心等待安装完成。
• 不需要 GPU:拼接为纯 CPU 计算。
• 不需要 Fiji / ImageJ / Java:全部功能由 Python 库完成,无外部软件依赖。
• 不需要 WSL:插件在 Windows 本地直接运行。

4.3 环境安装到哪些路径

启用后,插件代码被复制到当前用户目录下的 Dragonfly 扩展目录中(位于 %LOCALAPPDATA%\comet\<Dragonfly 版本>\pythonUserExtensions 下)。相关的可写路径包括:

• 虚拟环境:venv 子目录,创建在已安装插件代码目录 GenericMenuItems\BigStitcherLite 内,由面板的 Setup Environment 按钮构建。
• 作业目录(Job root):默认 C:\BigStitcherLiteJobs。每次运行会在其中创建一个带时间戳的子目录(形如 bigstitcher_lite_YYYYMMDD_HHMMSS),用于存放导出的 tile 数据与拼接结果。可在 Setup 分页修改 Job root。

4.4 失败时的替代方案

如果自动探测没有找到可用的 Base Python,或所选解释器缺少可用的 pip,Setup 会在状态栏与日志中报错。此时可以:

• 用 Browse... 手动指定一个明确带有 pip 的 python.exe(例如系统的 Python 或 Miniconda 的 python.exe),然后重试 Setup。
• 确认网络可访问 PyPI(公司网络代理 / 防火墙可能拦截 pip 下载)。
• 查看面板底部的日志区,里面会打印 Base Python 选择、pip 安装命令与退出码,便于定位问题。

5. 界面说明

面板顶部标题为 "BigStitcher Lite for Dragonfly - translational tile stitching for Channels"。主体是四个分页:Setup、Tiles、Stitch、Summary。面板底部有一个绿色状态行与一个只读日志框,分别显示当前状态与运行过程输出。

5.1 Setup 分页

• Analysis venv python(文本框):拼接实际使用的虚拟环境 python 路径。通常由 Setup Environment 自动填写;也可手动粘贴一个已就绪的 venv python 路径。
• Base Python(文本框 + Browse... 按钮):用于创建虚拟环境的基础解释器。留空表示自动探测 Dragonfly / 系统 Python。
• Job root(文本框):作业根目录,默认 C:\BigStitcherLiteJobs。
• Setup Environment (numpy + scipy + scikit-image)(按钮):创建虚拟环境并安装依赖。
• 说明文字:提示不使用 Fiji/ImageJ/Java,手动偏移以体素 Z/Y/X 坐标表示。

5.2 Tiles 分页

• Channel(下拉框):列出当前 Dragonfly 会话中可用的 Channel(显示标题与形状)。
• Refresh(按钮):重新扫描并刷新可用 Channel 列表。
• Add Tile(按钮):把下拉框当前选中的 Channel 作为一个 tile 加入下方表格,初始偏移为 (0, 0, 0)。
• tile 表格:六列 —— Tile(序号)、Title(标题)、Shape(形状)、Offset Z、Offset Y、Offset X。偏移三列可直接在单元格中编辑,填入整数体素偏移。
• Remove Selected(按钮):移除表格中当前选中的一行(tile)。
• Clear(按钮):清空整个 tile 列表。

5.3 Stitch 分页

分为 "Registration and blending"(配准与融合)与 "Output"(输出)两个分组,底部是运行按钮。

• Offset mode(下拉框):偏移量来源。可选 Manual offsets(手动偏移,默认)、Estimate: phase correlation to previous tile(相位相关到前一个 tile)、Estimate: phase correlation to first tile(相位相关到第一个 tile)。
• Blend mode(下拉框):融合方式。可选 Mean blend(均值,默认)、Max intensity(最大强度)、First tile wins(第一个 tile 优先)、Last tile wins(最后一个 tile 优先)。
• Phase upsample(整数微调框,范围 1–100,默认 1):相位相关的上采样因子,数值越大子体素对齐越精细但更慢。
• Fill value(小数微调框,默认 0.0):画布上未被任何 tile 覆盖区域的填充值。
• Normalize each tile by percentiles before stitching(勾选框,默认关闭):拼接前按百分位对每个 tile 归一化。
• Percentile low(小数微调框,范围 0–100,默认 1.0)与 Percentile high(范围 0–100,默认 99.0):归一化的下 / 上百分位。仅在勾选归一化时生效。
• Output Channel(文本框,默认 BigStitcher Lite stitched):输出拼接 Channel 的标题。
• Run Stitching(蓝色按钮):执行拼接。

5.4 Summary 分页

• 摘要表格:两列 Metric / Value,在拼接完成后显示本次运行的关键指标(tile 数量、输出形状、融合方式、偏移模式、原点偏移等)。运行成功后面板会自动切换到该分页。

6. 使用步骤

下面给出从零开始的完整端到端流程。前提:您已经在 Dragonfly 中导入了至少两个属于同一数据集、彼此仅存在平移关系的 Channel tile。

6.1 首次准备(仅一次)

1. 打开 Prototype Apps ▸ BigStitcher Lite...。

2. 切到 Setup 分页,如需可填写 Base Python 或修改 Job root,通常保持默认即可。

3. 点击 Setup Environment,等待日志显示安装完成,Analysis venv python 一栏自动填好路径,状态栏显示 "Environment ready."。

6.2 组织 tile 列表

1. 切到 Tiles 分页,点击 Refresh 扫描当前会话的 Channel。

2. 在 Channel 下拉框中选中第一个 tile,点击 Add Tile 加入表格;重复此步骤按拼接顺序依次加入其余 tile(至少两个)。

3. 在表格的 Offset Z / Offset Y / Offset X 三列中,为每个 tile 填入其相对全局坐标系的整数体素偏移。若打算用相位相关自动估计,可暂时保留 0。

4. 如加错可用 Remove Selected 删除某行,或用 Clear 全部清空重来。

6.3 设置配准与融合并运行

1. 切到 Stitch 分页,选择 Offset mode:若已手工填写偏移用 Manual offsets;若想自动估计平移,选择到前一个或第一个 tile 的相位相关模式。

2. 选择 Blend mode(默认 Mean blend),按需调整 Phase upsample、Fill value、是否 Normalize 及其百分位。

3. 在 Output Channel 里填写输出 Channel 的标题(默认 BigStitcher Lite stitched)。

4. 点击 Run Stitching。插件会把每个 tile 导出为临时数据、在虚拟环境子进程中完成偏移解析与融合,过程进度显示在日志区。

5. 完成后面板自动切到 Summary 分页,状态栏给出成功信息(包含 offsets.csv 路径与输出 Channel 名),拼接后的 Channel 出现在 Dragonfly 对象列表中。

运行前必须满足两点:至少已加入两个 tile;已完成 Setup(Analysis venv python 非空)。否则状态栏会提示 "Add at least two Channel tiles first." 或 "Run Setup first..."。

7. 参数说明

8. 输出结果

一次成功的拼接会产生以下结果:

• 拼接 Channel:一个新的 Dragonfly Channel(标题即 Output Channel 中填写的名称),直接发布到当前场景。其体素间距(spacing)复制自第一个 tile,原点(origin)按所有 tile 偏移的最小值进行平移,从而与原始数据保持一致的空间坐标。它会出现在 Dragonfly 的对象树中,可像普通 Channel 一样在 2D/3D 视图中查看。
• offsets.csv:偏移量清单文件,包含每个 tile 的序号、标题以及最终的 offset_z / offset_y / offset_x(全局体素坐标)。位于本次运行的作业子目录中。
• Summary 摘要:Summary 分页表格中展示的运行指标,包括 n_tiles(tile 数)、output_shape(输出形状)、blend_mode、offset_mode、origin_offset_zyx(原点偏移)等。
• 中间文件:作业子目录中还会保存各 tile 的导出数据、export.json、config.json、status.json、results.json 和 stitched.npy 等中间产物,便于排查与复用。

如何查看。 拼接完成后,在 Dragonfly 的对象列表里找到新生成的 Channel,双击或拖入视图即可显示。若要检查对齐是否合理,可在 3D 视图中观察重叠边界,或打开作业目录中的 offsets.csv 核对每个 tile 的最终偏移量。

9. 常见问题与故障排除

Q1:点击 Run Stitching 后提示 "Add at least two Channel tiles first."

拼接至少需要两个 tile。请到 Tiles 分页,用 Refresh 刷新后从 Channel 下拉框逐个 Add Tile,确保表格中至少有两行,再回到 Stitch 分页运行。

Q2:提示 "Run Setup first, or set the analysis venv python."

说明还没有可用的分析虚拟环境。请到 Setup 分页点击 Setup Environment 完成一次环境搭建;成功后 Analysis venv python 一栏会自动填好。若您已有可用的 venv,也可手动把其 python 路径粘贴到该栏。

Q3:Setup 失败,日志显示找不到 Base Python 或没有可用 pip

自动探测未能找到带 pip 的解释器。请用 Setup 分页的 Browse... 手动指定一个确有 pip 的 python.exe(例如系统 Python 或 Miniconda 的 python.exe),并确认网络可访问 PyPI(代理 / 防火墙可能拦截),然后重试。

Q4:拼接结果错位或对不上,怎么办?

本插件只做整数体素平移,不做旋转 / 缩放 / 仿射。若手动偏移不准,可尝试切换到相位相关模式自动估计;若数据之间存在旋转或形变,相位相关也无法纠正——这属于 "Lite" 版本的已知局限。也可适当增大 Phase upsample 提升对齐精度,或先勾选 Normalize 让亮度差异大的 tile 更易匹配。

Q5:Channel 下拉框是空的 / 找不到我的 tile

插件只能拼接已经导入 Dragonfly 会话中的 Channel。请先在 Dragonfly 中导入 tile,然后回到 Tiles 分页点击 Refresh 重新扫描。状态栏会显示 "Found N Channel(s)."。

Q6:安装后菜单里看不到 BigStitcher Lite

确认三点:安装时已勾选 BigStitcher Lite(插件默认关闭);安装后已完全重启 Dragonfly;菜单位于 Prototype Apps ▸ BigStitcher Lite...(Reconstruction & Imaging 分组)。也可在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 中确认其为勾选状态。

10. 注意事项与已知限制

• 仅支持平移:只处理整数体素 Z/Y/X 偏移,不支持旋转、仿射或形变配准。
• 手动元数据:tile 顺序与偏移由用户在表格中手动组织,本版本不导入采集元数据 / stage 坐标。
• 相位相关是辅助工具:自动估计的平移不保证等价于精确的 stage 坐标或逐对重叠感知配准,请结合结果人工核对。
• 内存占用:融合画布尺寸取决于所有 tile 的形状与偏移范围;tile 越多、偏移越大,画布与内存占用越大。
• 几何一致性:输出 Channel 的 spacing 复制自第一个 tile;请确保各 tile 使用一致的体素间距,否则拼接结果的空间尺度可能不准确。
• 首次需联网:仅 Setup 阶段联网安装依赖;日常拼接离线可用。

11. 参考资料

• scikit-image 相位相关配准:skimage.registration.phase_cross_correlation(https://scikit-image.org)。
• NumPy(https://numpy.org)、SciPy(https://scipy.org):底层数组与科学计算库。
• BigStitcher(设计灵感来源,完整拼接生态):https://imagej.net/plugins/bigstitcher/。
• Full Package 安装 / 启用 / 卸载说明:随包 README.md(Prototype Labs & Apps 完整安装包)。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation and Enabling

4. Runtime Environment and First-Run 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

BigStitcher Lite is a lightweight tile-stitching tool that runs inside Dragonfly. It takes multiple Dragonfly Channel tiles already loaded in your session, aligns them by translation, fuses them into one new stitched Channel, and also writes an offsets.csv listing the resolved offsets. The plugin is inspired by the BigStitcher use case but requires no Fiji, ImageJ, or Java - all stitching is done locally with Python scientific libraries.

Engine / algorithm. The stitching core is a pure-Python bigstitcher_core module built on three common libraries: numpy (array math and the fusion canvas), scipy, and scikit-image. When automatic offset estimation is chosen, translations are computed by scikit-image's skimage.registration.phase_cross_correlation (phase correlation); blending is done on a numpy canvas as mean, maximum, first-tile-wins, or last-tile-wins.

"Lite" scope. As the name says, this is a deliberately minimal version that focuses on the most common capability - translational stitching. It supports integer-voxel translation offsets only: no rotation, affine, or deformable registration, and it does not reproduce the full BigStitcher ecosystem of metadata importers, interest-point registration, or large-scale distributed processing.

Licensing notes. The plugin is an internal Dragonfly Prototype Apps tool. Its third-party dependencies (NumPy, SciPy, scikit-image) are permissively licensed (BSD / 3-clause family) and are installed from PyPI into the plugin's own isolated virtual environment during first-time setup - kept separate from Dragonfly's bundled Python.

2. Use Cases

This plugin fits when you have a tiled acquisition already loaded into Dragonfly as several Channels and want a quick, lightweight translational stitch or preview fusion done inside Dragonfly. Typical scenarios:

• Microscopy: fluorescence, confocal, or widefield fields captured as multiple tiles with known or estimable X/Y translation offsets.
• CT / tomography: a large sample scanned in sub-regions, producing several volume blocks to be joined along Z/Y/X.
• Other tiled data: any 2D or 3D Channels already loaded in Dragonfly that differ only by translation.
• Quick preview fusion: before doing a full, precise registration, use phase correlation to get a first alignment and judge whether tile order and overlap look reasonable.

This plugin targets the "just stitch it and take a look" need. If your data requires rotation/affine registration, precise overlap-aware pairwise registration, or large-scale distributed processing, use a dedicated full stitching solution; BigStitcher Lite does not cover those advanced features.

3. Installation and Enabling

The plugin ships with the Prototype Labs & Apps Full Package. The recommended path is the installer, which deploys into every Dragonfly version on this PC at once.

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

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, pick the core install mode (Fresh / Compatible), then tick BigStitcher Lite in the Prototype Apps list.

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

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

Off by default - must be enabled. In the package, all plugins are OFF by default (lightweight menu items are ON). So BigStitcher Lite must be ticked at install time, or enabled later from within Dragonfly.

Menu location after restart. Once enabled and restarted, the plugin appears under Dragonfly's Prototype Apps menu as BigStitcher Lite..., in the Reconstruction & Imaging section. Click it to open the panel.

Changing your choice later. The easiest way is inside Dragonfly: open Developer > Prototype Labs... > Menu Item Manager, find BigStitcher Lite in the "Prototype Apps (Full Package)" list at the bottom - tick to deploy, untick to remove the menu entry, and restart Dragonfly to apply. Disabling never deletes the plugin's built environment; re-enabling is instant.

Every enable/disable change needs one Dragonfly restart to take effect, because menus are only scanned at startup.

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

4. Runtime Environment and First-Run Setup

BigStitcher Lite isolates its dependencies in a dedicated virtual environment (venv): the stitching computation runs in a separate Python subprocess and does not pollute Dragonfly's own Python. Before first use you build this environment once from the Setup tab.

4.1 What Setup Environment does

Clicking Setup Environment (numpy + scipy + scikit-image) on the Setup tab makes the plugin:

1. Choose a Base Python to build the venv. If "Base Python" is blank, the plugin auto-detects: it prefers Dragonfly's bundled Python, then the system py launcher / python, then common Miniconda / Anaconda locations. You can also point it at a python.exe manually with Browse....

2. Create a venv subfolder inside the plugin's code directory as the isolated environment.

3. Upgrade that environment's pip, then install numpy, scipy, and scikit-image from PyPI over the internet.

4. On success, write the new venv python path back into the Analysis venv python field and save it to the configuration.

4.2 Download size and internet / hardware requirements

• Internet required: only during the first Setup, to download numpy / scipy / scikit-image and their dependencies from PyPI. Everyday stitching afterwards needs no internet.
• Download size: the three libraries and their dependencies total roughly a few hundred MB (exact size depends on network and pip resolution). Allow disk space and time.
• No GPU required: stitching is CPU-only.
• No Fiji / ImageJ / Java required: everything is done by Python libraries, with no external software.
• No WSL required: the plugin runs natively on Windows.

4.3 Where the environment is installed

Once enabled, the plugin code is copied into the current user's Dragonfly extensions directory (under %LOCALAPPDATA%\comet\<Dragonfly version>\pythonUserExtensions). The relevant writable paths are:

• Virtual environment: a venv subdirectory created inside the installed code directory GenericMenuItems\BigStitcherLite, built by the panel's Setup Environment button.
• Job root: default C:\BigStitcherLiteJobs. Each run creates a timestamped subfolder (like bigstitcher_lite_YYYYMMDD_HHMMSS) to hold the exported tiles and stitched results. The Job root can be changed on the Setup tab.

4.4 Fallback if setup fails

If auto-detection finds no usable Base Python, or the chosen interpreter lacks a working pip, Setup reports an error in the status bar and log. In that case:

• Use Browse... to point at a python.exe that definitely has pip (e.g. a system Python or Miniconda's python.exe), then retry Setup.
• Confirm your network can reach PyPI (a corporate proxy / firewall may block pip downloads).
• Read the log panel at the bottom; it prints the Base Python choice, the pip install commands, and exit codes to help diagnose the issue.

5. Interface Reference

The panel header reads "BigStitcher Lite for Dragonfly - translational tile stitching for Channels". The body is four tabs: Setup, Tiles, Stitch, Summary. At the bottom are a green status line and a read-only log box that show the current status and run output.

5.1 Setup tab

• Analysis venv python (text field): the venv python path actually used for stitching. Usually filled in automatically by Setup Environment; you may also paste a ready venv python path.
• Base Python (text field + Browse... button): the base interpreter used to create the venv. Blank means auto-detect Dragonfly / system Python.
• Job root (text field): the job root directory, default C:\BigStitcherLiteJobs.
• Setup Environment (numpy + scipy + scikit-image) (button): creates the venv and installs the dependencies.
• Note text: reminds you that no Fiji/ImageJ/Java is used and that manual offsets are in voxel Z/Y/X coordinates.

5.2 Tiles tab

• Channel (dropdown): lists the Channels available in the current Dragonfly session (showing title and shape).
• Refresh (button): re-scans and refreshes the available Channel list.
• Add Tile (button): adds the currently selected Channel as a tile in the table below, with an initial offset of (0, 0, 0).
• tile table: six columns - Tile (index), Title, Shape, Offset Z, Offset Y, Offset X. The three offset columns are editable in-cell; enter integer voxel offsets.
• Remove Selected (button): removes the currently selected row (tile) from the table.
• Clear (button): empties the whole tile list.

5.3 Stitch tab

Split into a "Registration and blending" group and an "Output" group, with the run button at the bottom.

• Offset mode (dropdown): the source of offsets. Options are Manual offsets (default), Estimate: phase correlation to previous tile, and Estimate: phase correlation to first tile.
• Blend mode (dropdown): the fusion rule. Options are Mean blend (default), Max intensity, First tile wins, and Last tile wins.
• Phase upsample (integer spinbox, range 1-100, default 1): the phase-correlation upsampling factor; higher gives finer sub-voxel alignment but is slower.
• Fill value (double spinbox, default 0.0): the value used for canvas regions not covered by any tile.
• Normalize each tile by percentiles before stitching (checkbox, default off): normalizes each tile by percentiles before stitching.
• Percentile low (double spinbox, range 0-100, default 1.0) and Percentile high (range 0-100, default 99.0): the lower/upper normalization percentiles. Effective only when normalization is on.
• Output Channel (text field, default BigStitcher Lite stitched): the title of the output stitched Channel.
• Run Stitching (blue button): runs the stitch.

5.4 Summary tab

• Summary table: two columns Metric / Value, showing key metrics of the run after stitching completes (tile count, output shape, blend mode, offset mode, origin offset, etc.). On success, the panel automatically switches to this tab.

6. Step-by-Step Usage

Below is the full end-to-end flow from scratch. Prerequisite: you already have at least two Channel tiles loaded in Dragonfly that belong to the same dataset and differ only by translation.

6.1 One-time preparation

1. Open Prototype Apps > BigStitcher Lite....

2. Go to the Setup tab; optionally fill in Base Python or change Job root - defaults are usually fine.

3. Click Setup Environment, wait for the log to report completion, the Analysis venv python field to be filled in, and the status bar to show "Environment ready.".

6.2 Build the tile list

1. Go to the Tiles tab and click Refresh to scan the session's Channels.

2. Select the first tile in the Channel dropdown and click Add Tile; repeat to add the remaining tiles in stitching order (at least two).

3. In the table's Offset Z / Offset Y / Offset X columns, enter each tile's integer voxel offset relative to the global coordinate system. If you intend to auto-estimate with phase correlation, you can leave them at 0.

4. Use Remove Selected to delete a wrong row, or Clear to start over.

6.3 Set registration/blending and run

1. Go to the Stitch tab and choose an Offset mode: use Manual offsets if you typed offsets, or a phase-correlation mode (to previous or first tile) to auto-estimate translation.

2. Choose a Blend mode (default Mean blend), and adjust Phase upsample, Fill value, and whether to Normalize (and its percentiles) as needed.

3. Enter the output Channel title in Output Channel (default BigStitcher Lite stitched).

4. Click Run Stitching. The plugin exports each tile, resolves offsets and blends in the venv subprocess, with progress shown in the log.

5. On completion the panel switches to the Summary tab, the status bar shows a success message (including the offsets.csv path and output Channel name), and the stitched Channel appears in Dragonfly's object list.

Two conditions must hold before running: at least two tiles added; Setup completed (Analysis venv python is non-empty). Otherwise the status bar prompts "Add at least two Channel tiles first." or "Run Setup first...".

7. Parameter Reference

8. Outputs

A successful stitch produces the following:

• Stitched Channel: a new Dragonfly Channel (titled as entered in Output Channel), published directly into the current scene. Its voxel spacing is copied from the first tile, and its origin is shifted by the minimum of all tile offsets so it stays in a consistent spatial coordinate system with the source data. It appears in Dragonfly's object tree and can be viewed in 2D/3D like any Channel.
• offsets.csv: an offsets listing containing each tile's index, title, and final offset_z / offset_y / offset_x (global voxel coordinates). It sits in this run's job subfolder.
• Summary metrics: the metrics shown in the Summary tab table, including n_tiles, output_shape, blend_mode, offset_mode, and origin_offset_zyx.
• Intermediate files: the job subfolder also keeps the exported per-tile data, export.json, config.json, status.json, results.json, and stitched.npy for troubleshooting and reuse.

How to view. After stitching, find the newly created Channel in Dragonfly's object list and double-click it or drag it into a view to display it. To check whether alignment looks right, inspect the overlap boundaries in a 3D view, or open offsets.csv in the job folder to verify each tile's final offset.

9. FAQ and Troubleshooting

Q1: After clicking Run Stitching I get "Add at least two Channel tiles first."

Stitching needs at least two tiles. Go to the Tiles tab, click Refresh, then Add Tile each Channel from the dropdown so the table has at least two rows, and run again from the Stitch tab.

Q2: It says "Run Setup first, or set the analysis venv python."

There is no usable analysis venv yet. Go to the Setup tab and click Setup Environment to build it once; on success the Analysis venv python field fills in automatically. If you already have a usable venv, you can paste its python path into that field.

Q3: Setup fails with no Base Python or no usable pip in the log

Auto-detection did not find an interpreter with pip. Use Browse... on the Setup tab to point at a python.exe that definitely has pip (e.g. a system Python or Miniconda's python.exe), confirm the network can reach PyPI (proxy / firewall may block it), then retry.

Q4: The stitched result is misaligned - what can I do?

The plugin only does integer-voxel translation, not rotation / scaling / affine. If manual offsets are off, try a phase-correlation mode to auto-estimate; if the data contains rotation or deformation, phase correlation cannot correct it either - that is a known "Lite" limitation. You can also raise Phase upsample for finer alignment, or enable Normalize so tiles with large brightness differences match more easily.

Q5: The Channel dropdown is empty / I can't find my tiles

The plugin can only stitch Channels already loaded in the Dragonfly session. Load the tiles in Dragonfly first, then go to the Tiles tab and click Refresh to re-scan. The status bar shows "Found N Channel(s).".

Q6: I can't see BigStitcher Lite in the menu after installing

Check three things: BigStitcher Lite was ticked at install (plugins are off by default); Dragonfly was fully restarted afterwards; the menu is at Prototype Apps > BigStitcher Lite... (Reconstruction & Imaging section). You can also confirm it is ticked in Developer > Prototype Labs... > Menu Item Manager.

10. Notes and Known Limitations

• Translation only: handles integer voxel Z/Y/X offsets only - no rotation, affine, or deformable registration.
• Manual metadata: tile order and offsets are organized manually in the table; this version does not import acquisition metadata / stage coordinates.
• Phase correlation is a helper: estimated translations are not guaranteed equivalent to proper stage coordinates or overlap-aware pairwise registration - review results manually.
• Memory footprint: the fusion canvas size depends on all tile shapes and offset range; more tiles and larger offsets mean a larger canvas and more memory.
• Geometry consistency: the output Channel's spacing is copied from the first tile; make sure all tiles use a consistent voxel spacing, or the stitched result's spatial scale may be wrong.
• Internet on first run only: only Setup needs internet to install dependencies; everyday stitching works offline.

11. References

• scikit-image phase-correlation registration: skimage.registration.phase_cross_correlation (https://scikit-image.org).
• NumPy (https://numpy.org) and SciPy (https://scipy.org): the underlying array and scientific computing libraries.
• BigStitcher (design inspiration; full stitching ecosystem): https://imagej.net/plugins/bigstitcher/.
• Full Package install / enable / uninstall guide: the bundled README.md (Prototype Labs & Apps Full Package).