CT/TEM 断层重建 (ASTRA) 插件用户手册

CT/TEM Reconstruction (ASTRA) - User Manual

Dragonfly Prototype Apps · CT/TEM Reconstruction (ASTRA)...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

CT/TEM 断层重建 (ASTRA) 插件在 Dragonfly 内部直接把一组投影图像堆栈重建为三维体数据。您选择投影图像 Channel（可选附加平场/暗场校正图像），输入射线源-探测器几何参数，选择重建算法（FDK、SIRT3D 或 CGLS3D），即可在后台运行 GPU 加速的重建，结果以新的图像 Channel 形式导回 Dragonfly，并带有正确的体素间距。

面板还内置了新手演示：自动生成三维体模（phantom）、模拟 X 射线投影并完成重建，无需任何数据即可体验完整流程。此外还提供 TEM（透射电镜）倒向序列重建模式：对平行束投影先做对齐再重建，支持 GPU 与 CPU。

底层引擎与算法

• ASTRA Toolbox — GPU（CUDA）断层重建引擎，提供锥束 FDK 以及 SIRT3D、CGLS3D 迭代求解器（迭代求解器仅支持 CUDA）。
• TomoPy — 预处理库，负责平场/暗场归一化、minus-log、环状/条纹伪影去除、旋转中心（COR）自动查找（find_center_vo）。
• TEM 平行束重建可在 GPU（ASTRA CUDA）或 CPU（TomoPy gridrec/SIRT 或 scikit-image）上运行，并支持倒向序列对齐。
• 重建计算在一个专用的 WSL2 Linux conda 环境（名为 astra）中运行，从不占用 Dragonfly 自带的 Python。

许可证要点

插件本身作为 Dragonfly Prototype Apps 的一部分发布。其依赖的上游引擎 ASTRA Toolbox（GPLv3）与 TomoPy（BSD-3）均为开源项目，在首次环境安装时从 conda 频道下载；请遵循各自上游项目的许可证条款。

2. 适用场景

本插件适合拥有显微 CT 或工业 CT 原始投影数据、希望在同一软件中完成重建与分析的用户：

• 材料科学：对实验室/台式 micro-CT 投影做优于扫描仪默认的重建（迭代、伪影校正）。
• 工业检测与计量：对零件、铸造件、增材制造样件的内部结构重建与尺寸测量。
• 电子失效分析：对 PCB、封装等宽/扫平对象（可配合截断校正与侧向 FOV 扩展）。
• 地球科学：岩芯、多孔介质的三维重建。
• 实验室与同步辐射 CT 用户：需要调试重建参数、对比迭代算法。
• 电子断层（TEM）用户：对平行束倒向序列先对齐再重建（支持缺失楔形情形下的迭代重建）。

3. 安装与启用

本插件随 Prototype Apps 完整安装包（Full Package） 一同分发。安装包本身不会下载任何重型依赖，重建计算环境需在首次使用时单独搭建（见第 4 章）。

3.1 使用完整安装包安装

1. 将完整安装包 zip 解压到任意位置（建议短路径，如 C:\PL\，避免路径过长）。

2. 双击 `Install_FullPackage.bat`。

3. 在弹出的对话框中选择核心安装模式（Fresh 全新安装 / Compatible 保留您自己的 blocks 和 recipes）。

4. 在应用列表中勾选 CT/TEM Reconstruction (ASTRA)。注意：所有插件默认处于未勾选（停用）状态，必须手动勾选才会安装。

5. 点击 Install，等待控制台完成。

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

3.2 菜单位置

重启后，菜单条出现在：Prototype Apps ▸ CT/TEM Reconstruction (ASTRA)...（位于 “Reconstruction & Imaging” 分组）。点击即可打开一个可浮动、可停靠的面板窗口。

3.3 以后修改启用/停用

最方便的方式是在 Dragonfly 内：打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager，在底部的 “Prototype Apps (Full Package)” 列表中找到本插件的勾选框：勾选 = 部署，取消 = 移除菜单条。修改后重启 Dragonfly 生效。停用从不删除插件已搭好的 WSL 环境，重新启用立即可用。

菜单只在 Dragonfly 启动时扫描——每次修改勾选后都需重启一次。全部安装在当前用户目录（%LOCALAPPDATA%）下，不需要管理员权限。

4. 运行环境与首次配置

本插件的重建计算在一个专用的 WSL2 Linux conda 环境（名为 `astra`） 中进行。首次使用前必须搭建该环境。

4.1 前置条件

• Dragonfly 2025.1 或 2027.1，且至少启动过一次。
• Windows 10/11 已安装 WSL2（管理员命令：wsl --install，然后重启）。
• 一块 NVIDIA GPU 并保持驱动较新（支持 WSL CUDA）。
• WSL（Ubuntu）内已安装 Miniconda（搭建脚本会用到）。
• 首次搭建需要联网（从 conda 频道下载，体量达数 GB）。

4.2 搭建 WSL astra 环境

双击插件目录中的 setup_astra_env.bat（它会调用 setup_astra_env.ps1）。脚本会：

1. 在 WSL（默认发行版 Ubuntu）内创建名为 astra 的 conda 环境（Python 3.11 + astra-toolbox + tomopy），历时几分钟。

2. 额外安装 python-docx，以启用每次重建的 .docx 报告。

3. 将环境信息（WSL 发行版、astra 解释器路径、作业目录）写入 %LOCALAPPDATA%\TomoRecon\config.json，供面板自动填充。

REM 默认参数（Ubuntu 发行版、astra 环境名、C:\TomoJobs 作业目录）：

setup_astra_env.bat

REM 自定义参数：

powershell -ExecutionPolicy Bypass -File setup_astra_env.ps1 -Distro Ubuntu -JobRoot C:\TomoJobs

4.3 面板自动检测

重启 Dragonfly 后打开面板，它会从 config.json 自动读取 astra 解释器路径。若未读到，可在右侧 WSL astra environment (GPU) 区点击 Setup / Detect env，面板会尝试在 WSL 常见位置（如 ~/miniconda3/envs/astra/bin/python）探测解释器；也可手动粘贴路径。

4.4 环境与数据位置

若自动搭建失败（如 WSL 内未装 Miniconda），可先在 WSL 中手动安装 Miniconda，再重跑 setup 脚本；或在面板的 “ASTRA interpreter” 框中直接粘贴一个已建好的 astra 环境 python 路径。

5. 界面说明

面板分三列：左列为新手演示（可折叠），中列为配置，右列为重建/TEM/环境参数与日志。顶部 ◀ Hide demo 按钮可隐藏/显示左列。

5.1 新手演示（左列）

• Phantom size (voxels)：体模尺寸，范围 32–256，默认 128。
• Projections (angles)：模拟投影角度数，范围 45–1440，默认 180。
• Generate phantom + Run demo（绿色按钮）：生成体模、模拟投影并重建，得到两个 Channel：Demo_Reconstruction 与 Demo_Phantom_GroundTruth，可叠加对比。

5.2 重建模式（Reconstruction mode）

• Mode 下拉框：Cone-beam CT (X-ray, lab micro-CT)（默认）或 TEM tilt-series (parallel beam, electron tomography)。切换到 TEM 时，右侧 TEM 选项组才会启用。

5.3 投影数据（Projection data）

• 投影 Channel 下拉框 + Refresh 按钮：刷新并选择投影图像堆栈（列出名称与 shape）。
• Angle (rotation) axis：投影堆栈中代表旋转角度的轴（0 - Z默认 / 1 - Y / 2 - X）。
• In-plane axis order：探测器平面两轴的顺序，(X, Y) - as stored（默认）或 (Y, X) - swap（重建看似转置时切换）。
• Flat field (optional) / Dark field (optional)：可选平场/暗场校正 Channel（默认 (none)），用于归一化。

5.4 锥束几何（Cone-beam geometry）

• Source-origin distance [mm]（SOD）：射线源到旋转轴的距离，默认 100。
• Origin-detector distance [mm]（ODD）：旋转轴到探测器的距离，默认 100。
• Detector pixel size [mm]：探测器物理像元尺寸，默认 0.05。
• Get from x/y spacing of projection images（按钮）：可选从所选投影 Channel 的 X/Y 间距填充像元尺寸。注意：Dragonfly 的间距经常为错误值或未设置（如 1.0），因此不会自动使用，请根据扫描仪真实像元间距确认。
• Angle start [deg] / Angle end [deg]：扫描角度范围（默认 0 到 360）。
• Rotation direction：Counter-clockwise (CCW)（默认）或 Clockwise (CW)（重建出现镜像时翻转）。

5.5 预处理（Preprocessing）

• Invert：仅当致密材料显为亮（而非暗）时勾选，默认关。
• Normalize：归一化（若上方设了平/暗场则用之，否则用下方白电平），默认开。
• Minus-log：透射强度转为衰减，默认开。
• Ring / stripe removal：环状/条纹伪影去除，默认开。
• White level I0：无平场时用于归一化的开束强度，留空/0 = 从亮区自动估计。
• COR method（旋转中心查找方法）：Auto - Vo (recommended)（默认）/ Auto - phase correlation / Auto - entropy (slow) / Detector centre (no search) / Manual (value below)。
• Manual COR [px]：COR method 为 Manual 时使用的手动旋转中心列号。

5.6 重建（Reconstruction，右列）

• Algorithm：FDK_CUDA（默认）/ SIRT3D_CUDA / CGLS3D_CUDA。
• Iterations (iterative)：迭代次数（SIRT3D/CGLS 适用，FDK 忽略），范围 1–2000，默认 150。
• Binning factor：探测器降采样因子，范围 1–8，默认 1（输出更小、更快）。
• GPU memory limit [GB] (0=auto)：分层重建的显存预算，0 = 自动检测空闲显存（默认 0）。
• Truncation correction：截断校正，用于宽/扫平对象（如 PCB），默认关。FDK 会对投影填补以抑制杯状伪影；SIRT3D/CGLS3D 不填补。
• Lateral FOV factor (1.0-2.0)：侧向重建宽度为探测器宽度的倍数，对象比探测器视场宽时用 >1（如 1.5–2.0），默认 1.0。上限 2.0（代价随因子平方增长）。
• Import reconstructed volume as a Channel：将重建体导入为 Channel，默认开。
• Convert to UShort (16bit) with Min-Max to 0-65535：转为 16 位无符号整数并将最小-最大值映射到 0–65535，默认开。

5.7 TEM 倒向序列选项（仅 TEM 模式）

• Device：Auto (GPU if available, else CPU)（默认）/ GPU (ASTRA CUDA) / CPU (TomoPy / scikit-image)。
• Algorithm：FBP（默认）/ SIRT / SART / CGLS / gridrec。
• Align tilt series before reconstruction：重建前对齐倒向序列（去除台阶漂移/抖动），默认勾选。
• Alignment：Cross-correlation (phase)（默认）或 None。
• Refine with TomoPy projection matching (slower)：以 TomoPy 投影匹配精化对齐，较慢，默认关。
• TEM Demo (synthetic tilt series)（绿色按钮）：生成合成倒向序列、对齐并重建，无需数据。TEM 模式的倾角范围取自上方的 Angle start/end。

5.8 操作按钮（日志上方）

• Geometry Check：重建前对几何（SOD/ODD/像元尺寸）做合理性检查，报告放大率、锥角、体素尺寸与体积维度，给出 PASS/SUSPICIOUS/VERY SUSPICIOUS 结论。
• Reconstruct（蓝色）：按当前参数运行完整重建。
• Reconstruct Preview：仅用 FDK 快速重建中心切片，用于预检几何/COR/预处理是否大致正确。
• Stop Recon（红色）：中断正在运行的重建并放弃所有进度（仅在重建时可用）。
• Save Recon Parameters to File：将当前重建参数保存为 .json（命名 <投影名>_ReconPara_<时间戳>.json）。
• Import Parameters from JSON file：从 .json 加载重建参数（投影/平场/暗场 Channel 选择不会导入）。
• Open Output Folder：打开最近一次作业的输出目录（默认在作业根目录下）。
• Log：只读日志区，实时显示进度、COR、体素尺寸、错误信息。

5.9 WSL astra 环境（右列）

• WSL distro：WSL 发行版名，默认 Ubuntu。
• ASTRA interpreter：astra 环境的 python 路径（自动检测，或手动粘贴）。
• Job root (Windows)：Windows 侧作业根目录，默认 C:\TomoJobs。
• Setup / Detect env（按钮）：探测或确认 astra 解释器。

6. 使用步骤

6.1 新手演示（无需数据）

1. 确保已搭建 WSL astra 环境（第 4 章）。

2. 在左列设置 Phantom size 与 Projections。

3. 点击 Generate phantom + Run demo。

4. 等待重建完成，得到 Demo_Reconstruction 与 Demo_Phantom_GroundTruth 两个 Channel，叠加对比（FDK 快但有锥/边缘伪影；SIRT3D/CGLS 更平滑但更慢）。

6.2 重建您自己的锥束 CT 投影

1. 将投影图像堆栈（及可选的平场/暗场）导入 Dragonfly。

2. 在面板中点击 Refresh，选择投影 Channel，并设置哪个轴是旋转角度轴。

3. （可选）选择平场与暗场 Channel。

4. 在 Cone-beam geometry 区输入 SOD、ODD、探测器像元尺寸与角度范围。

5. 先点 Geometry Check 确认几何合理（得到 PASS 为佳）。

6. 选择算法（FDK/SIRT3D/CGLS3D）与其他重建参数。

7. （建议）先点 Reconstruct Preview 看中心切片是否正常，确认后再点 Reconstruct 运行完整重建。

8. 完成后重建体作为 Channel 导入；可在弹窗或 Open Output Folder 中查看报告与参数文件。

6.3 TEM 倒向序列重建

1. 将 Mode 切为 TEM tilt-series；右侧 TEM 选项组启用。

2. 选择投影（倒向序列）Channel，并在 Angle start/end 设置倾角范围（如 -70 到 70）。

3. 选择 Device、Algorithm，并决定是否对齐（STEM-HAADF 关闭 Normalize/Minus-log；明场 TEM 开启 Minus-log）。

4. 点击 Reconstruct 运行；重建体以 TEM_ 前缀导入为 Channel。

5. 若无数据可先点 TEM Demo 体验完整流程。

7. 参数说明

下表列出主要可调参数、面板默认值与说明（默认值以面板初始状态为准，上次运行的部分参数会被记住）。

体素尺寸 = 探测器像元 / 放大率，放大率 M = (SOD+ODD)/SOD。Channel 以此各向同性间距创建。

8. 输出结果

重建完成后，插件会在 Dragonfly 中生成图像 Channel，并在作业目录中保存相关文件。

8.1 Dragonfly 对象

• 完整 CT 重建：一个名为 Reconstruction 的 Channel（带正确的各向同性体素间距）。
• 预览：中心切片，名称前缀 Preview_。
• 新手演示：Demo_Reconstruction 与 Demo_Phantom_GroundTruth 两个 Channel。
• TEM 重建：名称前缀 TEM_（演示为 TEM_Demo_）的 Channel。

8.2 作业目录文件

每次作业在作业根目录（默认 C:\TomoJobs）下创建一个带时间戳的子目录，其中包含：

• volume.npy — 重建体数据（z,y,x）。
• recon_params.json / result.json — 重建参数与计算结果（体素尺寸、体积维度、实际使用的 COR 及其相对探测器中心的偏移等）。
• report.docx — 双语重建报告（若 astra 环境已装 python-docx），含少量投影预览图。
• status.json — 重建过程的进度状态。

8.3 如何查看

重建完成后会弹出“重建完成”对话框（显示体积尺寸、COR 与报告路径），可点 Open Output Folder 打开目录。重建体 Channel 可直接在 Dragonfly 的 2D/3D 视图中查看、渲染与后续分析（分割、测量等）。

9. 常见问题与故障排除

10. 注意事项与已知限制

• 必须有 WSL2 + NVIDIA GPU：ASTRA 的锥束与迭代求解器仅支持 CUDA，重建无法在无 GPU 环境运行（TEM 平行束可选 CPU）。
• 重建在 WSL conda 环境运行，而非 Dragonfly 自带 Python：需先搭建 astra 环境。
• 探测器像元尺寸不会自动从 Dragonfly 间距获取：因为该间距常为错误值，请手动输入真实值。
• Lateral FOV factor 上限为 2.0：代价随因子平方增长（内存/时间）。
• 大体积自动分 Z-slab 重建以适配 GPU 显存。
• 首次搭建需联网下载数 GB（astra-toolbox + tomopy）。
• 报告 .docx 需 python-docx：未安装时重建仍会成功，仅跳过报告。

11. 参考资料

• ASTRA Toolbox：https://astra-toolbox.com/
• TomoPy：https://tomopy.readthedocs.io/
• Windows WSL：https://learn.microsoft.com/windows/wsl/
• WSL 中的 CUDA：https://docs.nvidia.com/cuda/wsl-user-guide/
• Miniconda：https://docs.conda.io/en/latest/miniconda.html

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation & Enabling

4. Runtime Environment & First-Run Setup

5. User Interface

6. Step-by-Step Usage

7. Parameter Reference

8. Outputs

9. FAQ & Troubleshooting

10. Notes & Known Limitations

11. References

1. Overview

The CT/TEM Reconstruction (ASTRA) plugin reconstructs a 3D volume from a projection image stack directly inside Dragonfly. You select the projection Channel (with optional flat/dark correction images), enter the source-detector geometry, choose a reconstruction algorithm (FDK, SIRT3D, or CGLS3D), and the GPU-accelerated reconstruction runs in the background and returns the result as a new image Channel with correct voxel spacing.

The panel also includes a built-in beginner demo: it generates a 3D phantom, simulates X-ray projections, and reconstructs it, so you can try the whole pipeline with no data. A TEM (transmission electron microscopy) tilt-series mode is also available: it aligns and then reconstructs parallel-beam projections, on GPU or CPU.

Underlying engines and algorithms

• ASTRA Toolbox — the GPU (CUDA) reconstruction engine, providing cone-beam FDK plus the SIRT3D and CGLS3D iterative solvers (the iterative solvers are CUDA-only).
• TomoPy — the preprocessing library: flat/dark normalization, minus-log, ring/stripe artifact removal, and automatic centre-of-rotation (COR) search (find_center_vo).
• TEM parallel-beam reconstruction runs on GPU (ASTRA CUDA) or CPU (TomoPy gridrec/SIRT or scikit-image), with optional tilt-series alignment.
• All reconstruction compute runs in a dedicated WSL2 Linux conda env (named astra) and never in Dragonfly's own Python.

Licensing highlights

The plugin ships as part of Dragonfly Prototype Apps. Its upstream engines ASTRA Toolbox (GPLv3) and TomoPy (BSD-3) are open-source and downloaded from conda channels during the one-time environment setup; please observe each upstream project's license terms.

2. Use Cases

This plugin is for anyone with raw micro-CT or industrial CT projection data who wants to reconstruct and analyze volumes in one place:

• Materials science — reconstructions better than a scanner's default (iterative, artifact correction) on lab / desktop micro-CT projections.
• Industrial inspection & metrology — internal-structure reconstruction and dimensioning of parts, castings, and additive-manufacturing samples.
• Electronics failure analysis — wide/flat objects such as PCBs and packages (pair with truncation correction and lateral-FOV widening).
• Geoscience — 3D reconstruction of rock cores and porous media.
• Lab and synchrotron CT users — experimenting with reconstruction parameters and iterative algorithms.
• Electron tomography (TEM) users — aligning and reconstructing parallel-beam tilt series (iterative solvers cope with a missing wedge).

3. Installation & Enabling

This plugin ships with the Prototype Apps Full Package. The installer itself downloads no heavy dependencies; the reconstruction compute environment is built separately on first use (see Chapter 4).

3.1 Install via the Full Package

1. Unzip the Full Package to any location (a short path such as C:\PL\ is best, to avoid path-length limits).

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, pick the core install mode (Fresh = install 100% new / Compatible = keep your own blocks & recipes).

4. In the app list, tick CT/TEM Reconstruction (ASTRA). Note: all plugins default to unticked (disabled) — you must tick it to install.

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

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

3.2 Menu location

After the restart, the menu entry appears at Prototype Apps ▸ CT/TEM Reconstruction (ASTRA)... (in the “Reconstruction & Imaging” group). Clicking it opens a floating, dockable panel window.

3.3 Change your choice later

The easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager, find this plugin's checkbox in the “Prototype Apps (Full Package)” list — tick = deploy, untick = remove the menu entry. Restart Dragonfly to apply. Disabling never deletes the plugin's built WSL environment; re-enabling is instant.

Menus are discovered only at Dragonfly startup — every enable/disable change needs one restart. Everything installs per-user (%LOCALAPPDATA%); no admin rights are needed.

4. Runtime Environment & First-Run Setup

Reconstruction compute runs in a dedicated WSL2 Linux conda environment (named `astra`). You must build this environment once before first use.

4.1 Prerequisites

• Dragonfly 2025.1 or 2027.1, launched at least once.
• Windows 10/11 with WSL2 installed (admin: wsl --install, then reboot).
• An NVIDIA GPU with a current driver (WSL CUDA support).
• Miniconda installed inside WSL (Ubuntu) — the setup script uses it.
• Internet for the one-time build (several-GB download from conda channels).

4.2 Build the WSL astra environment

Double-click setup_astra_env.bat in the plugin folder (it calls setup_astra_env.ps1). The script:

1. Creates a conda env named astra inside WSL (default distro Ubuntu) with Python 3.11 + astra-toolbox + tomopy (several minutes).

2. Additionally installs python-docx to enable the per-reconstruction .docx report.

3. Writes environment info (WSL distro, astra interpreter path, job root) to %LOCALAPPDATA%\TomoRecon\config.json so the panel auto-fills.

REM Default arguments (Ubuntu distro, 'astra' env name, C:\TomoJobs job root):

setup_astra_env.bat

REM Custom arguments:

powershell -ExecutionPolicy Bypass -File setup_astra_env.ps1 -Distro Ubuntu -JobRoot C:\TomoJobs

4.3 Panel auto-detection

After restarting Dragonfly, open the panel; it auto-reads the astra interpreter path from config.json. If not found, click Setup / Detect env in the right-column WSL astra environment (GPU) group — the panel probes common WSL locations (e.g. ~/miniconda3/envs/astra/bin/python); you can also paste the path manually.

4.4 Environment & data locations

If auto-setup fails (e.g. no Miniconda in WSL), install Miniconda inside WSL first and re-run the setup script; or paste an existing astra-env python path directly into the panel's “ASTRA interpreter” field.

5. User Interface

The panel has three columns: left = beginner demo (collapsible), middle = configuration, right = reconstruction / TEM / environment parameters and log. The top ◀ Hide demo button hides/shows the left column.

5.1 Beginner demo (left column)

• Phantom size (voxels): range 32–256, default 128.
• Projections (angles): simulated projection angles, range 45–1440, default 180.
• Generate phantom + Run demo (green button): builds a phantom, simulates projections, and reconstructs; yields two Channels, Demo_Reconstruction and Demo_Phantom_GroundTruth, to overlay and compare.

5.2 Reconstruction mode

• Mode dropdown: Cone-beam CT (X-ray, lab micro-CT) (default) or TEM tilt-series (parallel beam, electron tomography). Switching to TEM enables the TEM options group on the right.

5.3 Projection data

• Projection Channel dropdown + Refresh button: refresh and pick the projection stack (lists names and shapes).
• Angle (rotation) axis: which stack axis indexes the projection angle (0 - Z default / 1 - Y / 2 - X).
• In-plane axis order: (X, Y) - as stored (default) or (Y, X) - swap (use if the reconstruction looks transposed).
• Flat field (optional) / Dark field (optional): optional normalization Channels (default (none)).

5.4 Cone-beam geometry

• Source-origin distance [mm] (SOD): source-to-rotation-axis distance, default 100.
• Origin-detector distance [mm] (ODD): rotation-axis-to-detector distance, default 100.
• Detector pixel size [mm]: physical detector pixel, default 0.05.
• Get from x/y spacing of projection images (button): optionally fill the pixel size from the projection Channel's X/Y spacing. Warning: Dragonfly's spacing is often wrong or unset (e.g. 1.0), so it is never used automatically — confirm against your scanner's true pixel pitch.
• Angle start [deg] / Angle end [deg]: scan angular range (default 0 to 360).
• Rotation direction: Counter-clockwise (CCW) (default) or Clockwise (CW) (flip if the reconstruction is mirrored).

5.5 Preprocessing

• Invert: tick only if dense material is BRIGHT (not dark); default off.
• Normalize: normalize by flat/dark if set, else by the white level below; default on.
• Minus-log: transmission -> attenuation; default on.
• Ring / stripe removal: reduce ring artifacts; default on.
• White level I0: open-beam intensity used when no flat field is given; blank/0 = auto from a bright region.
• COR method: Auto - Vo (recommended) (default) / Auto - phase correlation / Auto - entropy (slow) / Detector centre (no search) / Manual (value below).
• Manual COR [px]: the manual centre-of-rotation column used when COR method = Manual.

5.6 Reconstruction (right column)

• Algorithm: FDK_CUDA (default) / SIRT3D_CUDA / CGLS3D_CUDA.
• Iterations (iterative): iteration count for SIRT3D/CGLS (ignored by FDK), range 1–2000, default 150.
• Binning factor: detector downsample factor, range 1–8, default 1 (smaller output, faster).
• GPU memory limit [GB] (0=auto): VRAM budget for slab reconstruction, 0 = auto-detect free VRAM (default 0).
• Truncation correction: for wide/flat objects (e.g. a PCB), default off. FDK pads projections to suppress cupping; SIRT3D/CGLS3D do not pad.
• Lateral FOV factor (1.0-2.0): in-plane reconstruction width as a multiple of detector width; use >1 (e.g. 1.5–2.0) when the object is wider than the detector FOV; default 1.0, hard cap 2.0 (cost grows with the square of the factor).
• Import reconstructed volume as a Channel: default on.
• Convert to UShort (16bit) with Min-Max to 0-65535: default on.

5.7 TEM tilt-series options (TEM mode only)

• Device: Auto (GPU if available, else CPU) (default) / GPU (ASTRA CUDA) / CPU (TomoPy / scikit-image).
• Algorithm: FBP (default) / SIRT / SART / CGLS / gridrec.
• Align tilt series before reconstruction: register projections and estimate the tilt axis before reconstructing; default on.
• Alignment: Cross-correlation (phase) (default) or None.
• Refine with TomoPy projection matching (slower): default off.
• TEM Demo (synthetic tilt series) (green button): generate, align, and reconstruct a synthetic tilt series with no data. The tilt-angle range is taken from Angle start/end above.

5.8 Action buttons (above the log)

• Geometry Check: sanity-checks the geometry (SOD/ODD/pixel size) before reconstructing; reports magnification, cone angle, voxel size, and volume dimensions, with a PASS / SUSPICIOUS / VERY SUSPICIOUS verdict.
• Reconstruct (blue): run a full reconstruction with the current parameters.
• Reconstruct Preview: quickly reconstruct only the central slice(s) with FDK to check the geometry / COR / preprocessing are roughly right.
• Stop Recon (red): abort the running reconstruction and discard all in-progress work (active only while running).
• Save Recon Parameters to File: save the current parameters as <projection>_ReconPara_<timestamp>.json.
• Import Parameters from JSON file: load parameters from a .json (the projection/flat/dark Channel selection is NOT imported).
• Open Output Folder: open the most recent job's output directory (defaults to the job root).
• Log: a read-only log area showing progress, COR, voxel size, and errors in real time.

5.9 WSL astra environment (right column)

• WSL distro: the WSL distribution name, default Ubuntu.
• ASTRA interpreter: the astra-env python path (auto-detected or pasted).
• Job root (Windows): Windows-side job root, default C:\TomoJobs.
• Setup / Detect env (button): detect or confirm the astra interpreter.

6. Step-by-Step Usage

6.1 Beginner demo (no data)

1. Make sure the WSL astra environment is built (Chapter 4).

2. Set Phantom size and Projections in the left column.

3. Click Generate phantom + Run demo.

4. Wait for reconstruction to finish; you get Demo_Reconstruction and Demo_Phantom_GroundTruth Channels, which you can overlay to compare (FDK is fast but shows cone/edge artifacts; SIRT3D/CGLS are smoother but slower).

6.2 Reconstruct your own cone-beam CT projections

1. Load your projection stack (and optional flat/dark) into Dragonfly.

2. In the panel, click Refresh, pick the projection Channel, and set which axis is the rotation angle.

3. (Optional) pick the flat and dark Channels.

4. In the Cone-beam geometry group, enter SOD, ODD, detector pixel size, and the angle range.

5. Click Geometry Check first to confirm the geometry is reasonable (a PASS verdict is best).

6. Choose an algorithm (FDK/SIRT3D/CGLS3D) and other reconstruction parameters.

7. (Recommended) click Reconstruct Preview to check the central slice, then click Reconstruct for the full run.

8. When finished, the volume imports as a Channel; view the report and parameter files via the completion dialog or Open Output Folder.

6.3 TEM tilt-series reconstruction

1. Switch Mode to TEM tilt-series; the TEM options group on the right becomes enabled.

2. Pick the projection (tilt-series) Channel and set the tilt range in Angle start/end (e.g. -70 to 70).

3. Choose Device and Algorithm, and decide whether to align (STEM-HAADF: leave Normalize/Minus-log off; bright-field TEM: enable Minus-log).

4. Click Reconstruct; the volume imports as a Channel with a TEM_ prefix.

5. With no data, click TEM Demo first to try the whole flow.

7. Parameter Reference

The table below lists the main adjustable parameters, their panel defaults, and notes (defaults are the panel's initial state; some parameters are remembered from the last run).

Voxel size = detector pixel / magnification, with magnification M = (SOD+ODD)/SOD. The Channel is created with this isotropic spacing.

8. Outputs

After reconstruction the plugin creates image Channels in Dragonfly and saves related files in the job directory.

8.1 Dragonfly objects

• Full CT reconstruction: a Channel named Reconstruction (with correct isotropic voxel spacing).
• Preview: the central slice(s), named with a Preview_ prefix.
• Beginner demo: two Channels, Demo_Reconstruction and Demo_Phantom_GroundTruth.
• TEM reconstruction: a Channel with a TEM_ prefix (TEM_Demo_ for the demo).

8.2 Job-directory files

Each job creates a timestamped sub-directory under the job root (default C:\TomoJobs), containing:

• volume.npy — the reconstructed volume (z,y,x).
• recon_params.json / result.json — the parameters and computed results (voxel size, volume dimensions, the actually-used COR and its offset from the detector centre, etc.).
• report.docx — a bilingual reconstruction report (if python-docx is installed in the astra env), with a few projection preview images.
• status.json — progress state during reconstruction.

8.3 How to view

On completion a “Reconstruction complete” dialog appears (showing volume size, COR, and the report path), with an Open Output Folder button. The reconstructed Channel can be viewed and rendered directly in Dragonfly's 2D/3D views and used for downstream analysis (segmentation, measurement, etc.).

9. FAQ & Troubleshooting

10. Notes & Known Limitations

• WSL2 + NVIDIA GPU required: ASTRA's cone-beam and iterative solvers are CUDA-only; reconstruction cannot run without a GPU (TEM parallel-beam offers a CPU option).
• Reconstruction runs in a WSL conda env, not Dragonfly's Python: the astra env must be built first.
• Detector pixel size is not taken automatically from Dragonfly spacing: that spacing is often wrong, so enter the real value manually.
• Lateral FOV factor is capped at 2.0: cost grows with the square of the factor (memory/time).
• Large volumes are auto-reconstructed in Z-slabs to fit GPU memory.
• The one-time setup downloads several GB (astra-toolbox + tomopy) and needs internet.
• The .docx report needs python-docx: without it, reconstruction still succeeds; only the report is skipped.

11. References

• ASTRA Toolbox: https://astra-toolbox.com/
• TomoPy: https://tomopy.readthedocs.io/
• Windows WSL: https://learn.microsoft.com/windows/wsl/
• CUDA on WSL: https://docs.nvidia.com/cuda/wsl-user-guide/
• Miniconda: https://docs.conda.io/en/latest/miniconda.html