CT 伪影校正(Algotom) 插件用户手册

CT Artifact Correction (Algotom) - User Manual

Dragonfly Prototype Apps · CT Artifact Correction (Algotom)...

版本 Version 1.0 · 2026-07-09

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

CT 伪影校正(Algotom) 是一个 Dragonfly 插件,用于在 CT 数据 重建前或重建后 对图像 Channel 进行 伪影校正。你在场景里选择一个图像 Channel(可以是 投影/正弦图堆栈,也可以是 已重建的切片),选择一种校正操作并设置相应参数,然后点击 Correct Artifacts 计算;插件会 逐个 z 切片 独立处理整个体数据,并发布一个 形状与几何(体素间距、原点)与源数据完全一致 的新校正后 Channel。

本插件 不是重建器——它只是在重建 前后 清理数据,是负责重建的 TomoRecon 插件的补充,二者相互独立。

底层计算引擎为开源工具库 Algotom(许可证 Apache-2.0,宽松许可),同时依赖 numpy 与 scipy(均为 BSD 许可)。本插件提供以下四种操作:

• 环形/条纹去除(remove_all_stripe) —— 调用 algotom.prep.removal.remove_all_stripe,参数为 snr / la_size / sm_size。作用于 投影域(每个 z 切片是一幅投影/正弦图),去除探测器缺陷导致的条纹——这些条纹在重建后表现为同心环。
• 环形/条纹去除(基于排序) —— 调用 algotom.prep.removal.remove_stripe_based_sorting,仅使用 sm_size 参数。同样作用于 投影域。
• 亮点(zinger/speckle)去除 —— 调用 algotom.prep.removal.remove_zinger,参数为 threshold / size,去除散射造成的孤立亮斑点;投影域或切片域均可使用。
• Paganin 相位恢复 —— 调用 algotom.prep.phase.paganin_filter,参数为 X 射线能量 / 样品-探测器距离 / 像素尺寸 / δ/β 比值;对经过平场校正的投影做单材料相位恢复,以增强弱吸收样品的对比度。

本插件将 Algotom 严格隔离在一个专用 Python 虚拟环境(venv)中,通过子进程 + JSON 文件通信运行,不会向 Dragonfly 自带的 Python 安装任何内容。

2. 适用场景

本插件面向 同步辐射 CT 与实验室 CT 数据的预处理与后处理,典型用途包括:

• 去除由探测器缺陷引起的 环形/条纹伪影——在投影域抑制条纹,重建后即可避免恼人的同心环。
• 去除 CT 数据中散射造成的 亮点(zinger),即孤立的过亮像素斑点。
• 对 弱吸收样品(如软组织、聚合物、复合材料)做 Paganin 单材料相位恢复,显著增强重建前投影的对比度。
• 在把数据交给重建(如 TomoRecon 插件)或后续分析之前,先做一遍标准化的伪影清理。

校正后的数据以新 Channel 形式回到场景中,可直接用于后续重建、分割、测量或可视化。

3. 安装与启用

本插件随 Prototype Apps 完整安装包(Full Package) 一起分发。安装步骤如下:

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

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

3. 在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),并在应用列表中 勾选 “CT Artifact Correction (Algotom)”。默认所有插件均 未勾选,因此本插件需要你手动勾选启用。

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

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

重启后,插件出现在菜单:Prototype Apps ▸ CT Artifact Correction (Algotom)...(位于 “Reconstruction & Imaging(重建与成像)” 分区)。点击该菜单项即可打开一个可停靠(浮动)的面板。

以后修改勾选:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部 “Prototype Apps (Full Package)” 列表里勾选或取消本插件,重启 Dragonfly 生效。停用 从不 删除已搭建的计算环境,重新启用立即可用。

所有内容都安装在当前用户目录 %LOCALAPPDATA% 下,不需要管理员权限。每次修改勾选后都需要重启一次 Dragonfly。

4. 运行环境与首次配置

本插件采用 代码目录内建 venv(venv_in_code) 的环境模式。安装完成后并 不会 自动下载任何依赖;首次使用前需要点击面板中的 Setup Environment 一次性搭建环境。

Setup Environment 具体做什么:

• 使用 Dragonfly 自带的 Python(默认,无需另装解释器)作为基础解释器,在插件代码目录内创建一个专用 venv。
• 从默认 PyPI 源联网安装 algotom + numpy + scipy(无 CUDA)。这些依赖在 CPython 3.10-3.12 上均以 wheel 形式安装。
• 安装完成后进行一次冒烟检查(导入 numpy/scipy/algotom 及所需函数),并记录 venv 的 Python 路径。

下载体积: 较小(算法库为纯 Python/科学计算依赖,无 CUDA)。是否联网: 仅首次搭建环境需要联网一次,之后无需联网。是否需要 GPU: 不需要(纯 CPU)。是否需要 WSL 或外部软件: 均 不需要。

环境安装位置: venv 建在已安装的插件代码目录内,即 %LOCALAPPDATA%\comet\<Dragonfly版本>\pythonUserExtensions\GenericMenuItems\Algotom\venv。venv 的 Python 路径会保存在同目录下的配置文件 algotom_config.json 中,面板下次打开时会自动识别。

失败时的替代方案: 若 Dragonfly 自带 Python 因故无法创建 venv(例如缺少 venv 模块),可在面板的 Base Python 字段填入另一套 CPython 3.10+ 的路径(例如 C:\Python312\python.exe),或形如 py -3.11 的启动命令,再次点击 Setup Environment 重试。面板状态栏会显示当前环境是 “Ready”(就绪)还是 “Not set up”(尚未搭建)。

环境隔离:Algotom 只在这个 venv/子进程内运行,与 Dragonfly 自身的 Python 保持距离,不会污染 Dragonfly。

5. 界面说明

面板从上到下由若干分组框(GroupBox)组成。下面逐一说明每个控件(与代码完全一致)。

输入 Channel(Input Channel)

• Channel(下拉框) —— 选择要处理的图像 Channel;列表项显示为 “标题 (Z×Y×X)”。旁边的 Refresh 按钮重新扫描当前场景中的 Channel。若无 Channel,会显示 “(no channels - load a volume in Dragonfly)”。
• Input domain(输入域,下拉框) —— 两个选项:Projection / sinogram stack(投影/正弦图堆栈,每个 z 切片是一幅 角度×探测器 的投影,内部值 projection,默认)与 Reconstructed slices(已重建切片,内部值 slice)。该选择用于生成下面的提示说明。
• 提示行(灰色小字) —— 根据所选操作与输入域,自动显示匹配提示:若选择了投影域操作(环形/条纹去除、Paganin)却把输入域设为切片,会提示该操作应作用于投影域;Paganin 作用于投影域时提示 “需要经过平场校正的投影”。

操作(Operation)

• Operation(下拉框) —— 四个选项,按顺序为:环形/条纹去除 remove_all_stripe(投影)、环形/条纹去除 基于排序(投影)、亮点(speckle)去除(投影或切片)、Paganin 相位恢复(投影)。选择不同操作时,下方只显示与之对应的参数分组框。

环形/条纹参数(Ring/stripe parameters)

在选择两种环形/条纹去除操作时显示。当选择 “基于排序” 方法时,只使用 sm_size,snr 与 la_size 会被置灰。

• snr(浮点微调框) —— 检测条纹用的信噪比阈值,范围 1.0-50.0,步长 0.5,默认 3.0;值越大越保守(标记的条纹越少)。
• la_size(整数微调框) —— 去除 大 条纹的窗口(需为奇数),范围 1-501,步长 2,默认 51。
• sm_size(整数微调框) —— 去除 小 条纹的窗口(需为奇数),范围 1-201,步长 2,默认 21;基于排序方法也用它作为排序窗口大小。

亮点参数(Zinger parameters)

在选择亮点去除时显示。

• threshold(浮点微调框) —— 判定亮点的相对强度跳变阈值,范围 0.0-10.0,3 位小数,步长 0.01,默认 0.08;超过该阈值的体素视为亮点。
• size(整数微调框) —— 替换亮点所用的中值窗口半径,范围 1-21,默认 2。

Paganin 相位恢复参数(Paganin phase-retrieval parameters)

在选择 Paganin 相位恢复时显示。

• energy (keV)(浮点微调框) —— X 射线能量(keV),范围 1.0-1000.0,步长 1.0,默认 30.0。
• distance (m)(浮点微调框) —— 样品到探测器的距离(米),范围 0.0-100.0,4 位小数,步长 0.05,默认 0.5。
• pixel size (m)(浮点微调框) —— 探测器像素尺寸(米),范围 0.0-1.0,9 位小数,步长 1e-6,默认 1e-6(即 1 微米)。
• ratio (delta/beta)(浮点微调框) —— δ/β 比值,范围 0.0-1e6,2 位小数,步长 10.0,默认 100.0;值越大平滑越强。

环境(Environment · Algotom venv)

• Base Python(文本框) —— 可选;留空表示使用本 Dragonfly 自带的 Python;也可填入某个 CPython 解释器的路径或形如 py -3.11 的命令。
• Status(状态标签) —— 显示环境状态:就绪时显示 “Ready: <venv python 路径>”;未搭建时提示点击 Setup Environment。

操作按钮与输出

• Setup Environment(按钮) —— 搭建/复用 venv 并安装依赖(见第 4 章)。
• Correct Artifacts(按钮) —— 按当前操作与参数对所选 Channel 执行校正。
• 摘要标签 —— 计算完成后显示一行摘要:操作、输入域、切片数、输出数值范围、均值、非有限值个数。
• 日志文本区(只读) —— 显示运行过程中的日志与错误信息。

6. 使用步骤

首次使用:先搭建环境

1. 打开面板:Prototype Apps ▸ CT Artifact Correction (Algotom)...。

2. (可选)在 Base Python 中指定基础解释器,否则留空使用 Dragonfly 自带 Python。

3. 点击 Setup Environment,等待日志出现环境就绪信息;首次需联网。状态栏变为 “Ready: ...” 即完成。

环形/条纹去除工作流(去除同心环)

1. 在 Dragonfly 中载入 投影/正弦图堆栈(每个 z 切片是一幅 角度×探测器 的投影/正弦图)。

2. 在面板顶部点 Refresh,从 Channel 下拉框选中该堆栈。

3. 把 Input domain 设为 Projection / sinogram stack。

4. 在 Operation 选择 remove_all_stripe 或 基于排序 方法。

5. 调节 snr / la_size / sm_size(基于排序方法只需 sm_size);la_size、sm_size 若填偶数会被自动加 1 变为奇数。

6. 点击 Correct Artifacts,插件逐切片处理并发布校正后的 Channel。校正后的堆栈可再交给重建。

亮点去除工作流

1. 选中含有孤立亮斑的 Channel(投影域或切片域均可)。

2. 在 Operation 选择 亮点(speckle)去除。

3. 设置 threshold(相对强度跳变阈值)与 size(中值窗口半径)。

4. 点击 Correct Artifacts,得到去除亮点后的新 Channel。

Paganin 相位恢复工作流

1. 载入 经过平场校正的投影 堆栈并选中。

2. 把 Input domain 设为 Projection / sinogram stack。

3. 在 Operation 选择 Paganin 相位恢复。

4. 按你的采集几何设置 energy(keV) / distance(m) / pixel size(m) / ratio(δ/β)。

5. 点击 Correct Artifacts,发布相位恢复后的投影,再进行重建以获得高对比度结果。

所有操作均 逐个 z 切片 独立处理,因此即使是很大的体数据,内存占用也是有界的。

7. 参数说明

环境相关设置见下表。

8. 输出结果

计算完成后,插件在 Dragonfly 场景中 发布一个新的 Channel(图像通道):

• 新 Channel 的名称为 “源 Channel 标题 - 操作标签”,形状与源数据 完全一致,并沿用源数据的 体素间距 与 原点(几何对齐)。
• 输出数据类型为 float32;非有限值(NaN/Inf)在导入时会被置为 0。
• 计算过程中若含 2D 输入会被自动提升为 3D 处理,输出仍保持与输入相同的维度。

如何查看: 校正后的 Channel 会立即出现在对象树/场景中(无需重启)。摘要标签会显示一行统计信息,例如:操作名、输入域、切片数、输出数值范围 [最小, 最大]、均值、非有限值个数。你可以像对待任何 Channel 一样在 2D/3D 视图中显示它,或将其送入重建、分割与测量流程。

本插件只做校正,不做重建。若你处理的是投影/正弦图堆栈,校正后仍需用重建工具(如 TomoRecon 插件)得到最终切片。

9. 常见问题与故障排除

Q1:菜单里找不到 “CT Artifact Correction (Algotom)...”?

A:确认在安装器或 Menu Item Manager 中 勾选 了本插件(所有插件默认未勾选),并且已 完全重启 Dragonfly。菜单位于 Prototype Apps ▸ Reconstruction & Imaging 分区。

Q2:点击 Correct Artifacts 提示 “environment not set up”?

A:说明尚未搭建 venv。先点击 Setup Environment 完成一次性环境搭建(首次需联网);状态栏显示 “Ready: ...” 后再运行。

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

A:在 Base Python 字段填入一套带 stdlib venv + pip 的 CPython 3.10+ 解释器路径(例如 C:\Python312\python.exe),或 py -3.11,再重试。同时确认首次搭建时网络可用(需从 PyPI 下载 algotom/numpy/scipy)。

Q4:重建后仍然有明显的同心环,校正没起作用?

A:环形/条纹去除必须作用于 投影域。请确认输入的是 投影/正弦图堆栈 且 Input domain 设为 Projection;若把它用在已重建的切片上,提示行会警告可能无法正确去环。

Q5:运行时报 “Out of memory”(内存不足)?

A:虽然处理是逐切片进行的,但整卷仍需读入。请尝试先裁剪出更小的 ROI 或对体数据降采样后再运行。

Q6:下拉框显示 “(no channels - load a volume in Dragonfly)”?

A:当前场景没有可用 Channel。先在 Dragonfly 中载入一个体数据,再点面板上的 Refresh 刷新列表。

10. 注意事项与已知限制

• 本插件 只做伪影校正,不做重建;重建请使用 TomoRecon 等工具。
• 输入域很关键:环形/条纹去除与 Paganin 恢复面向 投影域;亮点去除投影域/切片域皆可。选错域会有提示,但插件不会强制阻止。
• la_size / sm_size 会被强制为 奇数(中值/排序窗口要求),填偶数将自动加 1。
• Paganin 相位恢复假设 单材料 样品且输入为 平场校正后的投影;参数需与实际采集几何(能量、距离、像素尺寸)一致才有物理意义。
• 计算在 CPU 上进行(无 GPU 加速);非常大的体数据会较慢,建议先裁剪或降采样试跑。
• 环境搭建 仅首次需要联网;之后运行离线即可。不会向 Dragonfly 自带 Python 安装任何东西。
• 停用/卸载插件 不会 删除已搭建的 venv;如需回收磁盘空间可手动删除代码目录内的 venv 文件夹。

11. 参考资料

• Algotom 项目主页与源码:https://github.com/algotom/algotom (Apache-2.0)
• 所用函数:algotom.prep.removal.remove_all_stripe、remove_stripe_based_sorting、remove_zinger;algotom.prep.phase.paganin_filter。
• 依赖库:numpy(BSD)、scipy(BSD)。
• 相关插件:TomoRecon(CT/TEM 重建)——本插件为其在伪影校正方向的补充。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation & Enabling

4. 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

CT Artifact Correction (Algotom) is a Dragonfly plugin for pre/post-reconstruction artifact correction of an image Channel. You pick an image Channel from the scene (a projection/sinogram stack, or already-reconstructed slices), choose a correction operation, set its parameters, and click Correct Artifacts. The plugin processes the whole volume slice-by-slice and publishes a new corrected Channel with exactly the same shape and geometry (voxel spacing, origin) as the source.

This plugin is not a reconstructor - it cleans the data *around* reconstruction and is the complement to the TomoRecon plugin, which performs the reconstruction. The two are independent.

The compute engine is the open-source toolkit Algotom (Apache-2.0, permissive), together with numpy and scipy (both BSD). Four operations are provided:

• Ring/stripe removal (remove_all_stripe) - calls algotom.prep.removal.remove_all_stripe with snr / la_size / sm_size. Acts on the projection domain (each z-slice = one projection/sinogram); removes detector-defect stripes that become concentric rings after reconstruction.
• Ring/stripe removal (sorting-based) - calls algotom.prep.removal.remove_stripe_based_sorting, using only sm_size. Also acts on the projection domain.
• Zinger (bright-speckle) removal - calls algotom.prep.removal.remove_zinger with threshold / size; removes isolated bright scattering speckles. Works on either the projection or slice domain.
• Paganin phase retrieval - calls algotom.prep.phase.paganin_filter with X-ray energy / sample-to-detector distance / pixel size / delta-over-beta ratio; single-material phase retrieval on flat-field-corrected projections to boost contrast on weakly absorbing samples.

The plugin keeps Algotom strictly isolated in a dedicated Python virtual environment (venv), running it as a subprocess with JSON-file IPC; nothing is installed into Dragonfly's own Python.

2. Use Cases

The plugin targets pre/post-processing of synchrotron and lab CT data. Typical uses:

• Remove ring/stripe artifacts caused by detector defects - suppress the stripes in the projection domain so the concentric rings never appear after reconstruction.
• Remove zingers (isolated over-bright pixel speckles) caused by scattering.
• Perform single-material Paganin phase retrieval on weakly absorbing samples (soft tissue, polymers, composites) to substantially boost pre-reconstruction contrast.
• Run a standardized artifact cleanup before handing the data to reconstruction (e.g. the TomoRecon plugin) or downstream analysis.

The corrected data comes back to the scene as a new Channel, ready for reconstruction, segmentation, measurement, or visualization.

3. Installation & Enabling

The plugin ships with the Prototype Apps Full Package. To install:

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 or Compatible) and tick "CT Artifact Correction (Algotom)" in the app list. All plugins are unticked by default, so you must enable this plugin manually.

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

5. Fully quit and restart Dragonfly (menus are discovered only at startup).

After the restart, the plugin appears under Prototype Apps ▸ CT Artifact Correction (Algotom)... (in the "Reconstruction & Imaging" section). Clicking it opens a dockable (floating) panel.

To change your choice later: open Developer ▸ Prototype Labs... ▸ Menu Item Manager and tick/untick this plugin in the "Prototype Apps (Full Package)" list at the bottom; restart Dragonfly to apply. Disabling never deletes the built environment - re-enabling is instant.

Everything installs per-user under %LOCALAPPDATA%; no admin rights are needed. Every enable/disable change requires one Dragonfly restart.

4. Environment & First-Run Setup

The plugin uses a venv-in-code environment model. Installation downloads nothing; before first use you click Setup Environment once in the panel.

What Setup Environment does:

• Uses Dragonfly's own Python by default (no separate interpreter to install) as the base and creates a dedicated venv inside the plugin's code directory.
• Installs algotom + numpy + scipy (no CUDA) from the default PyPI index. These install as wheels on CPython 3.10-3.12.
• Runs a smoke check (imports numpy/scipy/algotom and the required functions) and records the venv's Python path.

Download size: small (the algorithm library is pure Python plus scientific dependencies, no CUDA). Internet: needed only once for the first setup, not afterwards. GPU: not required (CPU-only). WSL / external apps: not required.

Where the environment lives: the venv is built inside the installed code directory, i.e. %LOCALAPPDATA%\comet\<Dragonfly version>\pythonUserExtensions\GenericMenuItems\Algotom\venv. The venv Python path is saved in algotom_config.json in the same folder, and the panel auto-detects it next time.

Fallback if setup fails: if Dragonfly's own Python cannot create a venv (e.g. no venv module), enter the path to another CPython 3.10+ interpreter (e.g. C:\Python312\python.exe) or a launcher command like py -3.11 in the Base Python field, then click Setup Environment again. The status line shows whether the environment is "Ready" or "Not set up".

Isolation: Algotom runs only inside this venv/subprocess, kept at arm's length from Dragonfly's own Python, so it never pollutes Dragonfly.

5. User Interface

The panel is a stack of group boxes from top to bottom. Each control is described below (matching the code exactly).

Input Channel

• Channel (dropdown) - the image Channel to process; entries read "title (ZxYxX)". The Refresh button next to it re-scans the Channels in the current scene. With no Channels it shows "(no channels - load a volume in Dragonfly)".
• Input domain (dropdown) - two options: Projection / sinogram stack (each z-slice = one angle x detector projection; internal value projection, the default) and Reconstructed slices (internal value slice). This choice feeds the guidance note below.
• Guidance line (grey small text) - shows a note matching the chosen operation and domain: choosing a projection-domain operation (ring/stripe removal, Paganin) with the domain set to slice warns it should act on the projection domain; Paganin on the projection domain notes it "expects flat-field-corrected projections".

Operation

• Operation (dropdown) - four options in order: ring/stripe removal remove_all_stripe (projection), ring/stripe removal sorting-based (projection), zinger (speckle) removal (projection or slice), and Paganin phase retrieval (projection). Selecting a different operation shows only its matching parameter group box below.

Ring/stripe parameters

Shown for the two ring/stripe removal operations. For the sorting-based method only sm_size is used; snr and la_size are greyed out.

• snr (double spinbox) - signal-to-noise ratio for detecting stripes, range 1.0-50.0, step 0.5, default 3.0; larger is more conservative (fewer stripes flagged).
• la_size (spinbox) - window (odd) for removing large stripes, range 1-501, step 2, default 51.
• sm_size (spinbox) - window (odd) for removing small stripes, range 1-201, step 2, default 21; also the sorting-window size for the sorting-based method.

Zinger parameters

Shown for zinger removal.

• threshold (double spinbox) - relative intensity-jump threshold above which a voxel is treated as a zinger, range 0.0-10.0, 3 decimals, step 0.01, default 0.08.
• size (spinbox) - median-window radius used to replace zingers, range 1-21, default 2.

Paganin phase-retrieval parameters

Shown for Paganin phase retrieval.

• energy (keV) (double spinbox) - X-ray energy in keV, range 1.0-1000.0, step 1.0, default 30.0.
• distance (m) (double spinbox) - sample-to-detector distance in metres, range 0.0-100.0, 4 decimals, step 0.05, default 0.5.
• pixel size (m) (double spinbox) - detector pixel size in metres, range 0.0-1.0, 9 decimals, step 1e-6, default 1e-6 (1 micrometre).
• ratio (delta/beta) (double spinbox) - delta/beta ratio, range 0.0-1e6, 2 decimals, step 10.0, default 100.0; larger = stronger smoothing.

Environment (Algotom venv)

• Base Python (text field) - optional; blank means this Dragonfly's own Python, or enter a CPython path or a command like py -3.11.
• Status (label) - shows the environment state: "Ready: <venv python path>" when set up, otherwise prompts you to click Setup Environment.

Action buttons & output

• Setup Environment (button) - builds/reuses the venv and installs the dependencies (see Section 4).
• Correct Artifacts (button) - runs the selected operation with the current parameters on the chosen Channel.
• Summary label - after compute, shows one line: operation, input domain, slice count, output value range, mean, and non-finite count.
• Log text area (read-only) - shows progress logs and any errors.

6. Step-by-Step Usage

First use: build the environment

1. Open the panel: Prototype Apps ▸ CT Artifact Correction (Algotom)....

2. (Optional) set Base Python; leave blank to use Dragonfly's own Python.

3. Click Setup Environment and wait for the ready message in the log; this first run needs internet. The status line turns to "Ready: ..." when done.

Ring/stripe removal workflow (kill the concentric rings)

1. Load a projection/sinogram stack in Dragonfly (each z-slice = one angle x detector projection/sinogram).

2. Click Refresh at the top and select the stack in the Channel dropdown.

3. Set Input domain to Projection / sinogram stack.

4. In Operation choose remove_all_stripe or the sorting-based method.

5. Tune snr / la_size / sm_size (the sorting-based method needs only sm_size); an even la_size/sm_size is auto-incremented to be odd.

6. Click Correct Artifacts; the plugin processes slice-by-slice and publishes the corrected Channel, which you can then feed into reconstruction.

Zinger removal workflow

1. Select a Channel containing isolated bright speckles (projection or slice domain both fine).

2. In Operation choose Zinger (speckle) removal.

3. Set threshold (relative intensity-jump) and size (median-window radius).

4. Click Correct Artifacts to get a new zinger-free Channel.

Paganin phase-retrieval workflow

1. Load and select a stack of flat-field-corrected projections.

2. Set Input domain to Projection / sinogram stack.

3. In Operation choose Paganin phase retrieval.

4. Set energy (keV) / distance (m) / pixel size (m) / ratio (delta/beta) to match your acquisition geometry.

5. Click Correct Artifacts to publish the phase-retrieved projections, then reconstruct for a high-contrast result.

Every operation is applied independently to each z-slice, so even a very large volume is processed with a bounded memory footprint.

7. Parameter Reference

Environment-related settings are below.

8. Outputs

When the compute finishes, the plugin publishes a new Channel into the Dragonfly scene:

• The new Channel is named "source title - operation label", has exactly the same shape as the source, and reuses the source's voxel spacing and origin (geometry-aligned).
• Output data type is float32; non-finite values (NaN/Inf) are set to 0 on import.
• A 2D input is auto-promoted to 3D internally, and the output preserves the same dimensionality as the input.

How to view: the corrected Channel appears in the object tree / scene immediately (no restart needed). The summary label shows one line of statistics: operation, input domain, slice count, output value range [min, max], mean, and non-finite count. You can display it in 2D/3D views like any Channel, or feed it into reconstruction, segmentation, and measurement.

This plugin only corrects; it does not reconstruct. If you processed a projection/sinogram stack, you still need a reconstruction tool (e.g. the TomoRecon plugin) to get the final slices.

9. FAQ & Troubleshooting

Q1: I can't find "CT Artifact Correction (Algotom)..." in the menu.

A: Make sure you ticked this plugin in the installer or the Menu Item Manager (all plugins are unticked by default), and that you fully restarted Dragonfly. The menu is under Prototype Apps ▸ Reconstruction & Imaging.

Q2: Correct Artifacts says "environment not set up".

A: The venv has not been built yet. Click Setup Environment first (internet needed the first time); once the status line reads "Ready: ...", run again.

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

A: Enter the path to a CPython 3.10+ interpreter with stdlib venv + pip (e.g. C:\Python312\python.exe) or py -3.11 in the Base Python field and retry. Also confirm you have internet for the first setup (algotom/numpy/scipy are downloaded from PyPI).

Q4: There are still obvious concentric rings after reconstruction - the correction didn't help.

A: Ring/stripe removal must act on the projection domain. Confirm the input is a projection/sinogram stack and that Input domain is set to Projection; applying it to reconstructed slices triggers a warning in the guidance line and may not remove rings correctly.

Q5: It reports "Out of memory".

A: Although processing is slice-by-slice, the full volume still needs to be read in. Try cropping a smaller ROI first, or downsample the volume before running.

Q6: The dropdown shows "(no channels - load a volume in Dragonfly)".

A: There is no usable Channel in the current scene. Load a volume in Dragonfly, then click Refresh on the panel to update the list.

10. Notes & Known Limitations

• This plugin only corrects artifacts; it does not reconstruct - use TomoRecon or another tool for reconstruction.
• The input domain matters: ring/stripe removal and Paganin retrieval target the projection domain; zinger removal works on either domain. A mismatch triggers a note but is not blocked.
• la_size / sm_size are forced to be odd (median/sorting windows require it); an even value is auto-incremented by 1.
• Paganin phase retrieval assumes a single-material sample and flat-field-corrected projections; parameters (energy, distance, pixel size) must match the real acquisition geometry to be physically meaningful.
• Compute runs on the CPU (no GPU acceleration); very large volumes can be slow - crop or downsample for a trial run.
• The environment setup needs internet only the first time; runs are offline afterwards. Nothing is installed into Dragonfly's own Python.
• Disabling/uninstalling the plugin does not delete the built venv; to reclaim disk space, manually delete the venv folder inside the code directory.

11. References

• Algotom project & source: https://github.com/algotom/algotom (Apache-2.0)
• Functions used: algotom.prep.removal.remove_all_stripe, remove_stripe_based_sorting, remove_zinger; algotom.prep.phase.paganin_filter.
• Dependencies: numpy (BSD), scipy (BSD).
• Related plugin: TomoRecon (CT/TEM reconstruction) - this plugin complements it on the artifact-correction side.