Z 层 2D 拼接器 (Z-Stack 2D Stitcher) 插件用户手册

Z-Stack 2D Stitcher - User Manual

Dragonfly Prototype Apps · Z-Stack 2D Stitcher...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Z 层 2D 拼接器(Z-Stack 2D Stitcher) 是一个 Dragonfly 插件。它把一个 Dragonfly Channel(图像通道)的 Z stack(Z 层堆叠) 当作一组处于同一平面的 2D tile(二维分块) 来处理，把它们拼接成一张大的单层 2D 图像，并作为一个新的 Channel 发布回 Dragonfly。

很多显微、相机或其他二维分块采集的数据，导入 Dragonfly 后会变成一个“应该平铺开、却被堆成 Z 层”的体积。本插件就是把这种 Z 层重新“铺平”。用户先选择输入 Channel，设置行列数(rows / columns)和拼接路线(route)；面板会用网格、序号和箭头可视化地预览各个 Z slice 的拼接顺序。

底层引擎与算法

• 标称偏移(nominal offsets)：根据你给定的 X / Y 重叠百分比，推算相邻 tile 之间的应有位移；
• 相位相关配准(phase correlation)：可选地用 scikit-image 的 skimage.registration.phase_cross_correlation 在相邻 tile 的重叠带上估计平移修正；
• 融合(fusion)：最后用 mean / max / first / last 四种方式将重叠区域融合成一张画布。

拼接计算在一个独立的 Python 环境(venv)中以子进程方式运行，不会干扰 Dragonfly 自身的运行环境。依赖只有三个：numpy、scipy、scikit-image。

许可证要点

本插件依赖的第三方库均为开源项目：numpy 与 scipy 采用 BSD 许可证，scikit-image 采用 BSD 许可证。在首次搭建环境时，这些库会从 PyPI 按各自的许可证自动下载安装。

2. 适用场景

本插件适用于已经以 Z stack 形式导入 Dragonfly、但实际上是同一平面上分块采集的 2D tile 的数据：

• 显微镜采集的多视野(field-of-view)平铺 tile，每个视野存为一个 Z slice；
• 工业相机、扫描电镜或其他二维采集设备按行列分块拍摄、后拼成大图的场景；
• 希望在 Dragonfly 内部、按扫描路线快速得到一张大 2D 拼接图，而不想导出到外部软件处理的情况。

它尤其适合以平移为主、重叠固定的 tile 数据：即相邻 tile 之间主要只差一个平移量，没有明显的旋转、缩放或镜头畸变。

注意：本插件只估计平移(translation)。如果你的 tile 之间存在明显旋转、缩放、仿射变换或非线性畸变，本插件不会校正它们，拼接结果可能不对齐。

3. 安装与启用

本插件作为 Prototype Apps 的一部分发布。推荐通过 Full Package(完整安装包) 安装器安装。

1. 解压完整安装包到任意(较短)目录，双击运行 `Install_FullPackage.bat`。

2. 在弹出的安装对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容)，并在应用列表里勾选 Z-Stack 2D Stitcher。默认情况下所有插件均未勾选，本插件属于需要手动启用的插件。

3. 点击 Install，等待控制台提示完成。

4. 完全退出并重启 Dragonfly（菜单只在 Dragonfly 启动时扫描）。

重启后，在 Dragonfly 菜单栏打开 Prototype Apps > Z-Stack 2D Stitcher...（位于 Reconstruction & Imaging(重建与成像) 分组）即可打开面板。面板是可停靠的浮动窗口（标题 Z-Stack 2D Stitcher）。

以后想启用 / 停用本插件，最方便的方式是在 Dragonfly 内部：打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager，在底部 “Prototype Apps (Full Package)” 列表中勾选 / 取消本插件，重启 Dragonfly 生效。

停用插件从不会删除它已搭好的运行环境(venv)；重新启用时无需重新搭建，立即可用。

4. 运行环境与首次配置

本插件采用 venv-in-code 机制：拼接计算不在 Dragonfly 自身的解释器里运行，而是在一个独立的 Python 虚拟环境中以子进程方式运行。首次使用前，必须在 Setup 分页搭建这个环境。

Setup Environment 按钮做了什么

点击 Setup 分页下的 Setup Environment (numpy + scipy + scikit-image) 按钮后，插件会：

1. 自动探测一个可用的 base Python（默认优先使用 Dragonfly 自带的 Python，其次是系统上的 py / python / Miniconda / Anaconda 等）；也可在 Base Python 栏手动指定一个 python.exe；

2. 在插件代码目录内创建一个 venv 子目录作为虚拟环境；

3. 升级 pip，并从 PyPI 安装 numpy、scipy、scikit-image；

4. 安装成功后，把环境的 python.exe 路径回填到 Analysis venv python 栏，并将配置保存。状态栏会显示 “Environment ready.”。

下载体积、联网与硬件要求

• 联网：仅首次搭建环境时需要。 从 PyPI 下载 numpy / scipy / scikit-image 及其依赖，典型下载量在几十 MB 量级。环境搭好后，日常拼接不再需要联网。
• GPU：不需要。 拼接完全在 CPU 上完成。
• 外部软件：不需要。 无需 Fiji、ImageJ、Java 或 WSL。

环境与作业安装在哪里

• 虚拟环境：安装在已安装插件代码目录下的 venv\ 子目录（即 ...\GenericMenuItems\ZStack2DStitcher\venv）。
• 作业目录(Job root)：默认 C:\ZStack2DStitcherJobs，可在 Setup 分页修改。每次运行会在其下创建一个带时间戳的子目录，存放导出的输入堆叠、拼接结果与 offsets.csv。

失败时的替代方案

• 若自动探测到的 base Python 没有可用 pip，插件会自动再次探测其他候选；仍失败时，请在 Base Python 栏手动指定一个带 pip 的 Python（如 Miniconda 的 python.exe），再重新点 Setup Environment。
• 若你已经在其他地方建好了含 numpy / scipy / scikit-image 的 Python 环境，也可直接在 Analysis venv python 栏填入那个环境的 python.exe，跳过 Setup。

5. 界面说明

面板顶部是一句说明，下方是四个分页：Setup、Layout、Stitch、Summary；最底部是一个绿色状态行和一个只读日志框。

5.1 Setup 分页（环境）

• Analysis venv python：分析虚拟环境的 python.exe 路径，通常由 Setup Environment 自动填入；也可手动填写。
• Base Python：搭建 venv 时使用的基础 Python；留空 = 自动探测 Dragonfly / 系统 Python。右侧 Browse... 按钮可选择一个 python.exe。
• Job root：作业输出根目录，默认 C:\ZStack2DStitcherJobs。
• Setup Environment (numpy + scipy + scikit-image)：点击搭建 / 重建虚拟环境。

5.2 Layout 分页（输入与路线）

• Z-stack Channel 下拉框：选择作为 Z 层 tile 堆叠的输入 Channel；每项显示标题与形状。右侧 Refresh 按钮重新枚举 Dragonfly 中的所有 Channel。
• Rows(行数)：网格行数，默认 3，取值范围 1–10000。
• Columns(列数)：网格列数，默认 4，取值范围 1–10000。
• Route(路线)：拼接扫描顺序，可选 Zigzag / serpentine（蛇形）、Spiral clockwise inward（顺时针向内螺旋）、Raster rows（逐行行扫描），默认 Zigzag。
• 路线预览图：下方的可视化区域用网格、每格内的 slice 序号与蓝色箭头画出拼接顺序；行 / 列 / 路线任一变化时实时重绘。

小提示：选定 Channel 后，若当前行×列不等于 Z slice 数，插件会自动用开方估计一组接近正方形的行列数作为初始值，你可再手动调整。

5.3 Stitch 分页（对齐与输出）

Overlap alignment(重叠对齐) 分组：

• Alignment(对齐方式)：可选 “Use scikit-image phase correlation on overlap strips”（在重叠带上用相位相关，默认）或 “Nominal grid only”（仅用标称网格位置，不做配准）。
• Y overlap %：Y 方向重叠百分比，默认 10.00，范围 0–95。
• X overlap %：X 方向重叠百分比，默认 10.00，范围 0–95。
• Subpixel upsample(亚像素上采样)：相位相关的上采样因子，默认 1（=整像素），范围 1–100；值越大定位越精细但越慢。
• Max correction px(最大修正)：允许相位相关在标称位置上叠加的最大平移像素数，默认 20.00；超过此值的修正被视为异常并被拒绝（回退到标称位置）。
• Normalize overlap strips before alignment（配准前对重叠带归一化）：复选框，默认勾选。

Output(输出) 分组：

• Blend mode(融合方式)：Mean blend（均值，默认）/ Max intensity（取最大）/ First tile wins（首块优先）/ Last tile wins（末块优先）。
• Fill value(填充值)：拼接画布中未被任何 tile 覆盖的空白区域的填充值，默认 0.0000。
• Output Channel(输出通道名)：生成的新 Channel 标题，默认 Z-stack 2D stitched。
• Run 2D Stitching（蓝底按钮）：开始拼接。

5.4 Summary 分页（汇总）

一个两列表格（Metric / Value），拼接完成后自动展示，列出 tile 数、行列、路线、对齐与融合方式、步长、输出尺寸、成功对齐的相邻对数等指标；完成后面板会自动切到此页。

6. 使用步骤

前提：已在 Dragonfly 中打开一个 Channel，其 Z slices 是同一平面上的 2D tile 图像。

1. 打开 Prototype Apps > Z-Stack 2D Stitcher...。

2. 首次使用：切到 Setup 分页，（可选）修改 Job root，点 Setup Environment，等待状态栏显示 “Environment ready.”。已搭好环境则可跳过。

3. 切到 Layout 分页，点 Refresh，在 Z-stack Channel 下拉框选择输入 Channel。

4. 设置 Rows / Columns（行×列不能超过 Z slice 数），选择 Route，对照预览图确认拼接顺序与你的采集顺序一致。

5. 切到 Stitch 分页，设置 X / Y 重叠百分比（尽量接近实际采集重叠），选择对齐方式与融合方式，（可选）调整上采样、最大修正、填充值与输出名。

6. 点 Run 2D Stitching。插件会导出 Channel 堆叠 → 在虚拟环境中估计偏移并拼接 → 把结果发布回 Dragonfly。日志框实时显示进度。

7. 完成后，面板切到 Summary 分页展示指标；状态栏显示拼接结果与 offsets.csv 路径；新的 2D Channel 出现在 Dragonfly 对象列表中。

若行×列大于 Z slice 数，或未设置分析虚拟环境，状态栏会提示错误并阻止运行。

7. 参数说明

8. 输出结果

拼接完成后会得到以下结果：

• 一个新的 2D Channel：单层拼接图作为新 Channel 发布回 Dragonfly（默认标题 Z-stack 2D stitched），出现在对象浏览器中。它的 X / Y / Z 间距以及原点从输入 Channel 继承，并根据拼接原点偏移修正，以保持与原数据一致的物理尺度。
• `offsets.csv`：位于本次作业目录（Job root 下带时间戳的子目录），逐 slice 记录行、列、偏移 Y/X、是否使用了配准、配准得到的平移量以及（若未采用配准）原因。
• Summary 指标表：在面板 Summary 分页内展示（tile 数、输出尺寸、成功对齐的相邻对数等）。

查看方式：在 Dragonfly 对象列表中双击新 Channel 即可在视图中显示；offsets.csv 可用任意表格 / 文本编辑器打开以核对拼接偏移。

9. 常见问题与故障排除

Q1：状态栏提示 “Run Setup first, or set the analysis venv python.”，无法运行？

A：尚未搭建分析环境。请先到 Setup 分页点 Setup Environment 搭建 venv；或在 Analysis venv python 栏直接填入一个已含 numpy/scipy/scikit-image 的 python.exe。

Q2：提示 “Rows x columns exceeds the Channel Z slice count.”？

A：行×列的乘积大于输入 Channel 的 Z slice 总数。请到 Layout 分页把 Rows / Columns 调小，使其乘积不超过实际 slice 数（也可等于）。

Q3：启用了相位相关对齐，但 offsets.csv 里很多行 used_alignment 为 False？

A：可能是重叠带纹理太弱导致配准不可靠，或配准得到的平移超过了 Max correction px 而被拒绝（回退到标称位置）。可适当增大 Max correction、确认 X/Y 重叠百分比接近实际值；若重叠带纹理仍过弱，标称网格位置反而更可靠。

Q4：拼接图明显错位、对不齐？

A：首先确认 Route 与实际采集扫描顺序一致（对照预览图序号与箭头）；其次确认行 / 列正确；再确认 X/Y 重叠百分比与采集参数匹配。本插件只处理平移，若 tile 存在旋转 / 缩放 / 畸变则不适用。

Q5：Setup Environment 失败，提示找不到带 pip 的 Python？

A：在 Base Python 栏手动指定一个带 pip 的 python.exe（如 C:\ProgramData\miniconda3\python.exe），确保首次搭建时可以访问 PyPI，再重新点 Setup Environment。

10. 注意事项与已知限制

• 仅估计平移：不处理旋转、缩放、仿射变换、镜头畸变或非线性校正。
• 需手动提供网格与路线：插件不会从显微镜载物台元数据自动推断行列或扫描顺序，需你手动设置。
• 相位相关只在相邻路线步上生效：非相邻的跳转（如 zigzag 换行、spiral 拐弯）使用标称网格位置。
• 低纹理重叠带：当重叠区域纹理不足时，标称位置可能比相位相关更可靠；Max correction 作为守卫拒绝异常偏移。
• 输出为单层 2D Channel：本插件不生成体积重建，只把同平面 tile 拼成一张大图。
• 首次搭建需联网：环境搭好后日常拼接无需联网；作业目录会随次数增长，可定期清理 Job root 下的旧子目录。

11. 参考资料

• scikit-image 官方文档：skimage.registration.phase_cross_correlation(相位交叉相关配准)。
• scikit-image 项目主页：https://scikit-image.org
• NumPy：https://numpy.org · SciPy：https://scipy.org
• Full Package 安装 / 启用 / 卸载说明：随完整安装包附带的 README。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation and Enabling

4. Runtime Environment and First-Time Setup

5. User Interface

6. Step-by-Step Usage

7. Parameter Reference

8. Output

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

1. Overview

Z-Stack 2D Stitcher is a Dragonfly plugin. It treats the Z stack of one Dragonfly Channel as a set of same-plane 2D tiles and stitches them into one large single-slice 2D image, publishing the result back into Dragonfly as a new Channel.

Many microscopy, camera, or other tiled 2D acquisitions arrive in Dragonfly as a Z stack that really ought to be laid out flat. This plugin re-flattens that Z stack. You select an input Channel, set the grid rows/columns and a stitching route, and the panel draws a grid preview with slice indices and arrows so you can see the acquisition/stitch order.

Underlying engine and algorithm

• Nominal offsets: derived from the X/Y overlap percentages you supply, giving the expected translation between adjacent tiles.
• Phase correlation: optionally refines those offsets on adjacent tile overlap strips using scikit-image's skimage.registration.phase_cross_correlation.
• Fusion: blends overlapping regions into one canvas using mean, max, first-tile-wins, or last-tile-wins modes.

The stitching computation runs as a subprocess inside an isolated Python virtual environment (venv), so it never disturbs Dragonfly's own runtime. The only dependencies are numpy, scipy, and scikit-image.

Licensing notes

All third-party libraries are open source: numpy and scipy are BSD-licensed, and scikit-image is BSD-licensed. They are downloaded automatically from PyPI under their respective licenses during first-time environment setup.

2. Use Cases

This plugin is for data that was imported into Dragonfly as a Z stack but is really a set of same-plane 2D tiles acquired in a grid:

• Microscope multi-field-of-view tiles, each stored as one Z slice;
• Industrial cameras, scanning stages, or other 2D acquisition devices that shoot in rows/columns and are stitched into one large image afterward;
• Cases where you want a large 2D stitched image inside Dragonfly by scan route, without exporting to external software.

It is best suited to translation-dominant, fixed-overlap tile data: adjacent tiles differ mainly by a shift, with no significant rotation, scale, or lens distortion.

Note: this plugin estimates translation only. If your tiles differ by significant rotation, scale, affine transform, or nonlinear distortion, it will not correct them and the stitch may be misaligned.

3. Installation and Enabling

This plugin ships as part of Prototype Apps. The recommended way to install it is through the Full Package installer.

1. Unzip the Full Package to any (short) folder and double-click `Install_FullPackage.bat`.

2. In the installer dialog, choose the core install mode (Fresh or Compatible) and tick Z-Stack 2D Stitcher in the app list. By default all plugins are unticked, so this plugin must be enabled manually.

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

4. Quit Dragonfly completely and restart it (menus are discovered only at startup).

After the restart, open Prototype Apps > Z-Stack 2D Stitcher... (under the Reconstruction & Imaging group). The panel opens as a dockable floating window titled Z-Stack 2D Stitcher.

To enable or disable the plugin later, the easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager and tick/untick the plugin in the “Prototype Apps (Full Package)” list at the bottom, then restart Dragonfly to apply.

Disabling a plugin never deletes the environment (venv) it already built; re-enabling is instant, with no rebuild required.

4. Runtime Environment and First-Time Setup

This plugin uses a venv-in-code mechanism: stitching does not run in Dragonfly's own interpreter but as a subprocess inside an isolated Python virtual environment. Before first use you must build that environment on the Setup tab.

What Setup Environment does

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

1. Auto-detect a usable base Python (Dragonfly's built-in Python is preferred by default, then system py / python / Miniconda / Anaconda, etc.); you can also point Base Python at a specific python.exe.

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

3. Upgrade pip and install numpy, scipy, and scikit-image from PyPI.

4. On success, fill the venv python.exe path into Analysis venv python and save the configuration. The status bar shows “Environment ready.”.

Download size, internet, and hardware

• Internet: needed only for first-time setup. numpy / scipy / scikit-image and their dependencies are downloaded from PyPI (tens of MB typically). Once the environment is built, everyday stitching is offline.
• GPU: not required. Stitching runs entirely on the CPU.
• External software: not required. No Fiji, ImageJ, Java, or WSL is needed.

Where the environment and jobs live

• Virtual environment: a venv\ subfolder inside the installed plugin code directory (i.e. ...\GenericMenuItems\ZStack2DStitcher\venv).
• Job root: defaults to C:\ZStack2DStitcherJobs, editable on the Setup tab. Each run creates a timestamped subfolder there holding the exported input stack, the stitched result, and offsets.csv.

Fallback if setup fails

• If the auto-detected base Python has no usable pip, the plugin retries other candidates automatically; if it still fails, point Base Python at a Python that has pip (e.g. a Miniconda python.exe) and click Setup Environment again.
• If you already have a Python environment elsewhere with numpy / scipy / scikit-image, you can fill its python.exe into Analysis venv python directly and skip Setup.

5. User Interface

The top of the panel shows a one-line description, followed by four tabs: Setup, Layout, Stitch, Summary; a green status line and a read-only log box sit at the bottom.

5.1 Setup tab (environment)

• Analysis venv python: path to the analysis venv python.exe, normally filled by Setup Environment; can also be entered manually.
• Base Python: the base Python used to build the venv; blank = auto-detect Dragonfly/system Python. The Browse... button lets you pick a python.exe.
• Job root: root directory for job outputs, default C:\ZStack2DStitcherJobs.
• Setup Environment (numpy + scipy + scikit-image): builds/rebuilds the virtual environment.

5.2 Layout tab (input and route)

• Z-stack Channel dropdown: choose the input Channel whose Z slices are the tile stack; each entry shows its title and shape. The Refresh button re-enumerates all Channels in Dragonfly.
• Rows: grid rows, default 3, range 1–10000.
• Columns: grid columns, default 4, range 1–10000.
• Route: the scan/stitch order — Zigzag / serpentine, Spiral clockwise inward, or Raster rows; default Zigzag.
• Route preview: the area below draws the grid, per-cell slice index, and blue arrows showing the stitch order; it redraws live whenever rows, columns, or route change.

Tip: after you pick a Channel, if the current rows×columns does not equal the Z slice count, the plugin auto-guesses a near-square rows/columns as a starting point, which you can then adjust.

5.3 Stitch tab (alignment and output)

Overlap alignment group:

• Alignment: either “Use scikit-image phase correlation on overlap strips” (default) or “Nominal grid only” (no registration, nominal grid positions only).
• Y overlap %: vertical overlap percentage, default 10.00, range 0–95.
• X overlap %: horizontal overlap percentage, default 10.00, range 0–95.
• Subpixel upsample: phase-correlation upsampling factor, default 1 (= whole-pixel), range 1–100; larger is finer but slower.
• Max correction px: the maximum shift phase correlation may add on top of the nominal position, default 20.00; corrections beyond this are rejected as anomalous (falling back to the nominal position).
• Normalize overlap strips before alignment: checkbox, default on.

Output group:

• Blend mode: Mean blend (default) / Max intensity / First tile wins / Last tile wins.
• Fill value: value used for canvas regions not covered by any tile, default 0.0000.
• Output Channel: title of the new Channel, default Z-stack 2D stitched.
• Run 2D Stitching (blue button): starts stitching.

5.4 Summary tab

A two-column table (Metric / Value) shown automatically after stitching, listing tile count, rows/columns, route, alignment and blend modes, step sizes, output dimensions, the number of adjacent pairs successfully aligned, and more; the panel switches to this tab on completion.

6. Step-by-Step Usage

Prerequisite: a Channel is open in Dragonfly whose Z slices are same-plane 2D tile images.

1. Open Prototype Apps > Z-Stack 2D Stitcher....

2. First use: go to the Setup tab, optionally change Job root, click Setup Environment, and wait for the status bar to read “Environment ready.”. Skip this if the environment already exists.

3. Go to the Layout tab, click Refresh, and select the input Channel in the Z-stack Channel dropdown.

4. Set Rows / Columns (rows×columns must not exceed the Z slice count), choose a Route, and confirm against the preview that the stitch order matches your acquisition order.

5. Go to the Stitch tab, set X/Y overlap percentages (as close to the real acquisition overlap as possible), choose the alignment and blend modes, and optionally adjust upsample, max correction, fill value, and output name.

6. Click Run 2D Stitching. The plugin exports the Channel stack → estimates offsets and stitches in the venv → publishes the result back to Dragonfly. The log box shows live progress.

7. On completion, the panel switches to the Summary tab; the status bar shows the result and the offsets.csv path; the new 2D Channel appears in Dragonfly's object list.

If rows×columns exceeds the Z slice count, or the analysis venv python is not set, the status bar reports an error and the run is blocked.

7. Parameter Reference

8. Output

After stitching completes you get:

• A new 2D Channel: the single-slice stitched image is published back to Dragonfly as a new Channel (default title Z-stack 2D stitched) and appears in the object browser. Its X/Y/Z spacing and origin are inherited from the input Channel and adjusted by the stitch origin offset, so the physical scale matches the source data.
• `offsets.csv`: written to the current job folder (a timestamped subfolder under Job root). It records, per slice, the row, column, offset Y/X, whether alignment was used, the estimated shift, and (if alignment was not used) the reason.
• Summary metrics table: shown on the panel's Summary tab (tile count, output dimensions, number of adjacent pairs successfully aligned, etc.).

To view: double-click the new Channel in Dragonfly's object list to display it in a view; open offsets.csv in any spreadsheet / text editor to inspect the stitch offsets.

9. FAQ and Troubleshooting

Q1: The status bar says “Run Setup first, or set the analysis venv python.” and I cannot run.

A: The analysis environment has not been built. Click Setup Environment on the Setup tab, or fill Analysis venv python with a python.exe that already has numpy/scipy/scikit-image.

Q2: It says “Rows x columns exceeds the Channel Z slice count.”

A: The product of rows and columns is larger than the number of Z slices in the input Channel. On the Layout tab reduce Rows / Columns so their product does not exceed (it may equal) the actual slice count.

Q3: I enabled phase correlation, but many rows in offsets.csv have used_alignment = False.

A: The overlap strip may have too little texture for reliable registration, or the estimated shift exceeded Max correction px and was rejected (falling back to the nominal position). Try increasing Max correction, confirm the X/Y overlap percentages are close to the real values; if the overlap strip is still too low-texture, the nominal grid position may be more reliable.

Q4: The stitched image is badly misaligned.

A: First confirm the Route matches the real acquisition scan order (check the preview indices and arrows); then confirm the rows/columns are correct; then confirm the X/Y overlap percentages match the acquisition. This plugin handles translation only, so tiles with rotation/scale/distortion are out of scope.

Q5: Setup Environment fails, reporting no Python with pip.

A: Point Base Python at a python.exe that has pip (e.g. C:\ProgramData\miniconda3\python.exe), make sure it can reach PyPI for the first-time build, and click Setup Environment again.

10. Notes and Known Limitations

• Translation only: no rotation, scale, affine transform, lens distortion, or nonlinear correction.
• Grid and route are manual: the plugin does not infer rows/columns or scan order from microscope stage metadata; you set them.
• Phase correlation applies only to adjacent route steps: non-adjacent jumps (e.g. zigzag row changes, spiral turns) use the nominal grid position.
• Low-texture overlap strips: when the overlap region lacks texture, the nominal position may be more reliable than phase correlation; Max correction guards against anomalous shifts.
• Output is a single-slice 2D Channel: this plugin does not produce a volume reconstruction; it flattens same-plane tiles into one large image.
• First-time setup needs internet: everyday stitching is offline afterward. The job root grows with each run — periodically clean out old timestamped subfolders under Job root.

11. References

• scikit-image documentation: skimage.registration.phase_cross_correlation (phase cross-correlation registration).
• scikit-image project: https://scikit-image.org
• NumPy: https://numpy.org · SciPy: https://scipy.org
• Full Package install / enable / uninstall instructions: the README bundled with the Full Package.