Reconstruct from ZEISS TXRM (MBIRJAX)（从 ZEISS TXRM 重建）

Reconstruct from ZEISS TXRM (MBIRJAX) - User Manual

Dragonfly Prototype Apps · Reconstruct from ZEISS TXRM (MBIRJAX)...

版本 Version 1.0 · 2026-08-05

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次搭建

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出说明

9. 常见问题与排查

10. 注意事项与已知限制

11. 参考资料

1. 简介

使用开源的 MBIRJAX 重建库（BSD-3-Clause，普渡大学），直接从 ZEISS Xradia 的 .txrm 投影文件重建三维体积。不需要任何其它数据源：投影、平场参考图、逐投影角度、源/探测器距离、光学放大倍数、转轴中心与逐投影漂移，全部从 .txrm 自身读取。

.txrm 是 OLE2 复合文件，与 .txm 是同一种容器，区别在于它装的是投影序列而不是重建后的体积。插件在 Dragonfly 进程内用内置的纯 Python olefile 检查它，然后把文件交给独立 Python 环境中的 MBIRJAX 完成重建。

提供两种算法。FDK 是滤波反投影：速度快，是完整 360 度扫描的正确默认选择。MBIR 是基于模型的迭代重建：慢得多，但在短扫描、有限角或稀疏视角数据上明显更好 —— 那些情况下 FDK 不做冗余加权，只是近似。

不点就不会发布任何东西。检查和重建都不会创建 Dragonfly 对象。只有第 6 步的「发布体积为 Channel」按钮会创建对象，并按 ORS 对象模型的惯例把体素间距以米为单位写入。

「输入」页的一键执行全部步骤（按当前设置）会无人值守地跑完流程：检查文件 → 汇总所选子集与预计内存 → 重建 → 发布，每一步都使用你按下按钮那一刻各自页签上显示的设置。发布是复选框且默认关闭：它会把整个体数据读入 Dragonfly 进程，实测全分辨率重建时约 62 GB，因此必须由你明确选择而不能是默认行为。环境安装完全不在流程内——它要创建虚拟环境并从网络安装 mbirjax——因此当环境缺失时，重建步骤会直接拒绝并指明是这一步。所有页签始终可以打开，以便在运行之前核对几何与参数；某一步所需的输入尚不存在时，按下它自己的按钮会给出提示，说明缺的是哪一步。

2. 适用场景

用一条每一步都可见、可调的开源流程，复现或替代厂商 Reconstructor 的结果。

用不同参数重新重建已有扫描 —— 换滤波器、降采样预览、裁掉探测器边缘、背景偏移或亮点校正 —— 不必回到设备上重新采集。

用迭代 MBIR 重建短扫描或有限角采集，它对角度覆盖不足的处理远好于 FDK。

在没有厂商软件许可的机器上处理 .txrm 数据。

与厂商结果互相对照：同目录存在 *_recon.txm 时，插件会在质检报告里点明它，可用「Load TXM Files」插件载入并逐层比对。

3. 安装与启用

1. 打开 Prototype Apps ▸ App Store，在 Reconstruction & Imaging 分组里找到 Reconstruct from ZEISS TXRM (MBIRJAX) 并启用。

2. 重启 Dragonfly。菜单项在启动时才被发现，仅关闭再打开窗口不够。

3. 菜单项出现在 Prototype Apps ▸ Reconstruct from ZEISS TXRM (MBIRJAX)...

4. 第一次重建前，请先完成下一节的一次性环境搭建。

4. 运行环境与首次搭建

⚠ 本插件需要 Dragonfly 没有提供的 Python 版本。 MBIRJAX 要求 CPython 3.11 或更高，而 Dragonfly 自带 CPython 3.10。本套件里其它插件都用 Dragonfly 自己的解释器搭环境，这个不行。机器上需要另外装有 64 位 Python 3.11+，推荐 python.org 的 3.12。

在 2 运行环境 标签页点击 搭建运行环境。搭建步骤会对能找到的解释器排序（先 python.org 安装，再按版本用 py 启动器，然后 conda/miniforge，最后 PATH），拒绝低于 3.11 或非 64 位的解释器，并打印每一个尝试过的解释器及其被拒原因。若自动探测选错，可在 基础 Python 里填路径后重跑。

搭建会在 %LOCALAPPDATA%\DragonflyPrototypeLabs\TxrmMbirjax\venv 建立虚拟环境，并以轮子方式安装 mbirjax==0.7.2、jax==0.10.1、jaxlib==0.10.1（需联网一次，约 200 MB）。位置刻意放在插件目录之外：一次搭建对所有已装 Dragonfly 版本生效、不会被 App Store 更新清除，也让 JAX 很深的包目录远离 Windows 260 字符路径上限。解析出的解释器记在 txrm_mbirjax_config.json 里，「恢复出厂设置」不会碰它。

Windows 上只有 CPU。 JAX 的 CUDA 版本只发布 Linux 轮子，Windows 上没有 CUDA 版 jaxlib，所以重建在 CPU 上运行。建议先重建一个降采样版本来判断耗时，再决定是否跑全分辨率。任何东西都不会装进 Dragonfly 自己的 Python_env。

⚠ 每次全分辨率运行前都看一下内存预估。第 4 步会从文件头把它算出来：投影 + MBIRJAX 额外分配的同尺寸全零暗场数组 + float32 正弦图 + 体积，再乘 2 得峰值。一次实测的全分辨率运行（3401 × 1013 × 1013）峰值约需 60 GB：页文件用到 62 GB、缺页 2.58 亿次、64 分钟墙上时间烧掉 19.3 小时 CPU，而且什么都没产出。当预估超过可用内存的一半时，质检页会给出 TOO BIG 并直接写出该改成多少。只有预估超过机器物理内存总量时，重建才会直接拒绝运行。

5. 界面说明

六个编号标签页，按顺序使用。

1 输入 —— 选一个 .txrm 文件，或扫描一个文件夹列出其下所有 .txrm。配套的 *_Drift.txrm（漂移跟踪扫描，不可重建）在文件夹扫描时自动过滤掉。检查文件读取几何并跳到质检页。

2 运行环境 —— 基础 Python、搭建运行环境、检查运行环境，以及各步骤写入的日志（pip 输出、runner 命令行、错误）。

3 参数 —— 算法与滤波器、探测器行/列降采样、视角抽样、探测器裁剪、背景偏移模式、亮点校正、自动裁剪，以及 1 ALU 的长度单位。

4 预览与质检 —— 几何报告：投影数与探测器尺寸、束几何与设备类型、SOD/ODD 与导出的放大倍数、重建应落在的体素尺寸、探测器像素间距、转轴偏移、是否有平场图、角度范围、自洽校验结果、同目录厂商重建，以及所有警告与阻断项。

5 运行 —— 开始与取消、进度条与当前阶段。进度从任务的 status.json 读取；取消是一个请求，runner 会在下一个检查点响应。

6 结果与导出 —— 完整结果记录（形状、体素尺寸、以米为单位的间距、MBIRJAX 实际使用的几何、各库版本）、Channel 名称输入框，以及发布体积为 Channel 按钮。

取消是先请求、再强制。第一次点击发出取消请求，重建会在下一个检查点响应；MBIRJAX 在重建过程内部没有可插入的钩子，所以再点一次会直接终止进程。关闭面板同样会停掉它 —— 不会留下一个看不见的进程继续跑。

6. 使用步骤

1. 1 输入 —— 浏览选择一个 .txrm，或扫描文件夹后从列表里选。点击检查文件。

2. 4 预览与质检 —— 读报告。closure check : PASS 表示放大链自洽。任何以 BLOCKING 开头的行必须先解决才能运行；以 WARNING 开头的是提示（有限角扫描、缺平场图、源距离变化等）。

3. 2 运行环境 —— 若状态不是就绪，点击搭建运行环境并等到出现 Setup complete.

4. 3 参数 —— 第一次试跑建议把两个降采样都设为 2、每 n 张投影取 1 张 设为 4。这样只花一小部分时间，就能在投入完整运行前确认几何和方向是否正确。

5. 3 参数 ▸ 投影子集 —— 若只用扫描的一部分重建，可设置丢弃开头/结尾 N 张投影、保留角度窗口，或排除角度区间；三者可叠加。做退化研究就在序列：各保留跨度里填例如 300, 240, 180, 150, 120。运行前先点预览子集并看质检页：它会报出保留张数、保留跨度、最大角度空洞，以及每个变体的警告。

6. 5 运行 —— 点击开始重建。整个投影序列在 venv 内读取，所以在重建真正开始前会有若干分钟的 I/O，尤其是从网络盘读取时。

7. 6 结果与导出 —— 核对 voxel_size_um 与质检报告里的预期体素尺寸，填写 Channel 名称，然后点击发布体积为 Channel。

8. 在 Dragonfly 里验证：新 Channel 的体素尺寸应等于 .txrm 的 PixelSize。若该扫描有厂商 _recon.txm，用「Load TXM Files」载入并比对对应切片。

7. 参数说明

8. 输出说明

9. 常见问题与排查

搭建时提示找不到可用的 CPython 3.11。请看它打印的 Interpreters tried 列表 —— 里面列出了每一个解释器及其被拒原因。Dragonfly 自带的 3.10 是刻意不作为候选的。请从 python.org 安装 64 位 Python 3.12，或把基础 Python 指向已有的 3.11+ 解释器。

质检报告出现 closure check : FAIL。放大链不自洽：PixelSize × M_geo × M_opt 本应等于 CamPixelSize × CameraBinning。说明其中某个流缺失或该文件不寻常。请不要重建 —— 体素尺寸会错，通常正好差一个光学放大倍数（4 倍、20 倍或 40 倍）。

运行失败，提示对 NoneType 做一元 - 运算。该容器里既没有 AutoRecon/CenterShift 也没有 ReconSettings/CenterShift，MBIRJAX 无法从中得到转轴中心。六套参考数据都有非零的转轴偏移，所以这种情况不正常 —— 请检查文件是否被采集软件完整写出。

进程退出但没有写状态文件。这是 venv 内部的硬崩溃（通常是 JAX/DLL 问题或内存不足被杀）。面板会显示 runner_log.txt 的末尾；完整日志在 %LOCALAPPDATA%\DragonflyPrototypeLabs\TxrmMbirjax\jobs 下的任务文件夹里。

卡在 45%「reconstructing with FDK」一直不动。几乎总是内存问题，而不是死锁。打开任务文件夹里的 runner_log.txt（路径会打印在运行环境页的日志里，位于 %LOCALAPPDATA%\DragonflyPrototypeLabs\TxrmMbirjax\jobs）；若最后一行就是 FDK 那条、之后再无内容，说明进程仍在计算但正在大量换页。请看质检页的内存预估。3401 张投影的全分辨率重建在 CPU 上并不现实：把每 n 张投影取 1 张设为 4、两个探测器降采样都设为 2，先确认几何无误，再考虑加大。注意单点一次「取消」无法中断重建阶段（MBIRJAX 内部没有可插入的检查点）—— 再点一次「取消」才会终止进程。

很慢，或内存不足。Windows 上重建是纯 CPU，一个完整的 Versa 体积以 float32 约 4 GB。预览时把探测器降采样设为 2、视角抽样设为 4；除非是短扫描，否则用 FDK 而不是 MBIR。

体积看起来左右镜像或上下颠倒。角度符号与行序都是存储约定：MBIRJAX 会对角度取负，而 ZEISS 自己的显示会翻转行序。在把方向用于任何有方向性的测量之前，请拿一个不对称特征与厂商 _recon.txm 对照确认。

扫描文件夹时没列出我预期的文件。*_Drift.txrm 是刻意过滤掉的，mosaic 采集会被报为阻断项。只有真正的投影序列（AcquisitionMode = 0）可以重建。

降采样会改变体素尺寸吗？会，插件已经把这一点算进去了：重建体素等于 PixelSize × 列降采样倍数，所以列降采样 2 会得到两倍大的体素。results.json 同时记录实际交付的 voxel_size_um 与预期值，发布的 Channel 间距始终由真实体素推导 —— 降采样后的体积标定是正确的，只是更粗。

可以只用一部分投影来重建吗？可以 —— 投影子集这一组就是为此设计的，也正是用来模拟被遮挡或无效角度的方式。三点提醒。(1) 从两端丢弃视角会缩短角度跨度（短扫描）；排除中间某段则跨度不变但在其中挖了个洞（缺失楔形）。两者伪影不同，质检预览会同时报出跨度和最大空洞，便于分辨你造出的是哪一种。(2) 锥束圆轨迹只在 180 度加上完整扇角以上才保持数据完备，所以把 360 度扫描裁到 300 度仍属温和工况；真正的有限角失真要低于该下限才出现，预览会按变体逐一提示。(3) 不同子集之间的灰度值不可直接比较，因为 FDK 的斜坡滤波折入了一个 pi / num_views 权重，它不跟随保留跨度变化 —— 请比较结构，或改用迭代 MBIR，它对覆盖缺失的处理远好于 FDK。

10. 注意事项与已知限制

不支持 mosaic（拼接）采集。这类文件会被检测出来并报为阻断项，而不是被悄悄 reshape 成一个错误的数组。

会被直接拒绝的文件（在第 4 步报为阻断项，绝不会被重建）：mosaic/拼接采集；平行束的 Xradia Ultra（波带片）扫描，它需要本插件未搭建的平行束重建；*_Drift.txrm 漂移跟踪配套文件，即使手动选中也一样；AcquisitionMode 不是投影序列的文件；在第一张投影之前就中断的扫描（ImagesTaken = 0）；未知的像素 DataType；以及放大链不自洽的文件。

.txrm 里没有暗场图。MBIRJAX 假定暗场为零。残余偏移改由背景偏移校正处理。

只使用第一个源距离和探测器距离。两者都是逐投影存储的；若它们有变化，质检报告会警告，且源/探测器漂移会被忽略。

缺平场图会降级而不是阻断。MBIRJAX 会退化为全 1 参考并给出警告，通常会留下环状和阴影伪影。质检报告会在运行前就告诉你这一点。

灰度值是每 ALU 的线积分衰减，记录在 results.json 的 value_units 里，而不是被悄悄换算。它不是 Hounsfield 单位，也不能与厂商重建的标定直接比较。

中断的扫描只读取已写出的部分。若 ImagesTaken 小于 NoOfImages，质检报告会警告，并且只使用已写出的投影。

几何恒等式已在六套真实 Xradia Versa 数据上验证（放大倍数 2.56 至 10.80，2026-08-05）：导出的放大倍数与 XrayMagnification 完全一致，自洽恒等式误差在 5e-8 以内，导出的半锥角与 ConeAngle 完全一致，且每个文件的 PixelSize 都等于其兄弟厂商重建的体素尺寸。

11. 参考资料

MBIRJAX（BSD-3-Clause）—— https://github.com/cabouman/mbirjax 与 https://mbirjax.readthedocs.io · JAX（Apache-2.0）—— https://github.com/jax-ml/jax · olefile（BSD-2-Clause）—— https://github.com/decalage2/olefile · MBIRJAX 中的 Zeiss 读取模块致谢 Amir Koushyar Ziabari（橡树岭国家实验室）。本套件中的相关插件：Load TXM Files（打开厂商已重建的 .txm）、CT/TEM Reconstruction (ASTRA)（重建已载入的投影 Channel）、CT Artifact Correction (Algotom)（环状/条纹与亮点校正）。

Part II English Manual

Contents

1. Introduction

2. Use cases

3. Installation & enabling

4. Runtime environment & first-run setup

5. Interface

6. How to use

7. Parameters

8. Output

9. FAQ & troubleshooting

10. Notes & known limitations

11. References

1. Introduction

Reconstructs a 3-D volume straight from a ZEISS Xradia .txrm projection file using the open-source MBIRJAX reconstruction library (BSD-3-Clause, Purdue University). No other data source is required: the projections, the flat-field reference, the per-projection angles, the source/detector distances, the optical magnification, the centre of rotation and the per-projection drift are all read out of the .txrm itself.

A .txrm is an OLE2 compound file — the same container as a .txm, but holding the PROJECTION set instead of a reconstructed volume. The plugin inspects it in Dragonfly's own process with a bundled pure-Python olefile, then hands the file to MBIRJAX in a separate Python environment for the reconstruction.

Two algorithms are offered. FDK is a filtered back-projection: fast, and the right default for a full 360-degree scan. MBIR is model-based iterative reconstruction: much slower, but better on short, limited-angle or sparse-view scans, where FDK applies no redundancy weighting and is only approximate.

Nothing is published until you ask for it. Inspecting and reconstructing create no Dragonfly objects. Only the Publish volume as a Channel button in step 6 creates anything, and it writes voxel spacing in metres, the ORS object-model convention.

Execute All Steps with Current Settings on the Input tab runs the workflow unattended - inspect the file, report the subset and the memory it will need, reconstruct, publish - each step with whatever its own tab shows when you press it. Publishing is a tick box and is OFF by default: it reads the whole volume into Dragonfly's process, which on a full-resolution run was measured at 62 GB, so it has to be a decision rather than a default. Setting up the environment is NOT part of the run at all - it builds a venv and installs mbirjax over the network - so the reconstruction step refuses and names it if the environment is missing. Every tab stays open so the geometry and parameters can be checked BEFORE the run; a step whose input does not exist yet refuses at ITS button and says which step is missing.

2. Use cases

Reproducing or replacing the vendor Reconstructor result with an open-source pipeline whose every step is visible and adjustable.

Re-reconstructing an existing scan with different parameters — a different filter, a downsampled preview, cropped detector margins, background-offset or zinger correction — without going back to the instrument.

Reconstructing a short or limited-angle acquisition with iterative MBIR, which handles missing angular coverage far better than FDK.

Processing .txrm data on a machine that has no vendor software licence.

Cross-checking a reconstruction against the vendor's own: when a *_recon.txm sits in the same folder, the plugin names it in the QC report so it can be loaded (with the Load TXM Files plugin) and compared side by side.

3. Installation & enabling

1. Open Prototype Apps ▸ App Store, find Reconstruct from ZEISS TXRM (MBIRJAX) in the Reconstruction & Imaging group, and enable it.

2. Restart Dragonfly. Menu items are discovered at startup, so a restart is required — closing and reopening the window is not enough.

3. The item appears as Prototype Apps ▸ Reconstruct from ZEISS TXRM (MBIRJAX)...

4. Before the first reconstruction, complete the one-time environment setup described in the next section.

4. Runtime environment & first-run setup

⚠ This plugin needs a Python that Dragonfly does not provide. MBIRJAX requires CPython 3.11 or newer; Dragonfly bundles CPython 3.10. Every other plugin in this suite builds its environment from Dragonfly's own interpreter — this one cannot. You need a separate 64-bit Python 3.11+ installed on the machine, and python.org 3.12 is the recommended choice.

On the 2 Environment tab, click Set up environment. The setup step ranks the interpreters it can find (python.org installs first, then the py launcher by version, then conda/miniforge, then PATH), refuses anything older than 3.11 or non-64-bit, and prints every interpreter it tried together with the reason each was rejected. If auto-detection picks the wrong one, type a path into Base Python and run it again.

Setup creates a virtual environment at %LOCALAPPDATA%\DragonflyPrototypeLabs\TxrmMbirjax\venv and installs mbirjax==0.7.2, jax==0.10.1 and jaxlib==0.10.1 as wheels (internet needed once, roughly 200 MB). The location is deliberately OUTSIDE the plugin folder: one setup serves every installed Dragonfly version, it survives App Store updates, and it keeps the deep JAX package tree clear of the Windows 260-character path limit. The resolved interpreter is remembered in txrm_mbirjax_config.json and is never touched by Reset to factory defaults.

CPU only on Windows. JAX publishes CUDA builds for Linux only — there is no Windows CUDA jaxlib — so reconstruction runs on the CPU. Reconstruct a downsampled version first to judge timing before committing to a full-resolution run. Nothing is ever installed into Dragonfly's own Python_env.

⚠ Check the memory estimate before every full-resolution run. Step 4 predicts it from the header: projections + a same-sized all-zero dark array that MBIRJAX allocates + the float32 sinogram + the volume, doubled for the peak. A measured full-resolution run of a 3401 x 1013 x 1013 dataset needed about 60 GB at peak; it reached 62 GB of page file and 258 million page faults, burned 19.3 CPU-hours in 64 minutes of wall clock and produced nothing. When the estimate exceeds half the available RAM the QC step says TOO BIG and names the exact factors to use instead. The reconstruction refuses outright only when the estimate exceeds the machine's total physical memory.

5. Interface

Six numbered tabs, worked through in order.

1 Input — pick a .txrm file, or scan a folder to list every .txrm under it. The companion *_Drift.txrm (the drift-tracking scan, not reconstructable) is filtered out of folder scans automatically. Inspect file reads the geometry and moves you to the QC tab.

2 Environment — Base Python, Set up environment, Check environment, and the log that every step writes to (pip output, the runner command line, errors).

3 Parameters — algorithm and filter, detector row/column downsampling, view subsampling, detector cropping, background-offset mode, zinger correction, auto-crop, and the length unit for 1 ALU.

4 Preview & QC — the geometry report: projection count and detector size, beam geometry and scanner type, SOD/ODD and the derived magnification, the voxel size the reconstruction must land on, the detector pitch, the centre shift, whether a flat field is present, the angular range, the closure check, the sibling vendor reconstruction, and any warnings or blocking problems.

5 Run — start and cancel, a progress bar and the current stage. Progress is read from the job's status.json; cancellation is a request the runner honours at its next checkpoint.

6 Results & Export — the full result record as JSON (shape, voxel size, spacing in metres, the geometry MBIRJAX actually used, library versions), a Channel title field, and the Publish volume as a Channel button.

Cancel asks, then insists. The first click requests cancellation, which the reconstruction honours at its next checkpoint; MBIRJAX offers no hook inside the reconstruction itself, so a second click stops the process outright. Closing the dock also stops it - it never keeps running invisibly.

6. How to use

1. 1 Input — Browse to a .txrm, or scan a folder and pick one from the list. Click Inspect file.

2. 4 Preview & QC — read the report. closure check : PASS means the magnification chain is self-consistent. Any line beginning BLOCKING must be resolved before a run is possible; lines beginning WARNING are advisory (a limited-angle scan, a missing flat field, a varying source distance).

3. 2 Environment — if the status is not ready, click Set up environment and wait for Setup complete.

4. 3 Parameters — for a first pass set both downsample factors to 2 and Keep every n-th projection to 4. That reconstructs in a small fraction of the time and tells you whether the geometry and orientation are right before you spend the full run.

5. 3 Parameters, Projection subset — to reconstruct from only part of the scan, set Drop first/last N projections, or a Keep angles window, or Exclude angle ranges; the three combine. For a degradation study fill Series: retained spans with e.g. 300, 240, 180, 150, 120. Click Preview subset and read the QC tab BEFORE running: it reports the kept count, the retained span, the largest angular hole and a warning per variant.

6. 5 Run — click Run reconstruction. The whole projection set is read inside the venv, so expect several minutes of I/O before the reconstruction itself starts, especially from a network drive.

7. 6 Results & Export — check voxel_size_um against the QC report's expected voxel size, set a Channel title, then click Publish volume as a Channel.

8. Verify in Dragonfly: the new Channel's voxel size should equal the .txrm PixelSize. If the scan has a vendor _recon.txm, load it with Load TXM Files and compare a matching slice.

7. Parameters

8. Output

9. FAQ & troubleshooting

Setup says no usable CPython 3.11 was found. Read the Interpreters tried list it prints — it names every interpreter and why each was rejected. Dragonfly's own 3.10 is deliberately not a candidate. Install 64-bit Python 3.12 from python.org, or point Base Python at an existing 3.11+ interpreter.

QC reports closure check : FAIL. The magnification chain does not close: PixelSize x M_geo x M_opt should equal CamPixelSize x CameraBinning. One of those streams is missing or unusual for this file. Do not reconstruct — the voxel size would be wrong, typically by the optical magnification (4x, 20x or 40x).

The run fails mentioning unary - on NoneType. The container has neither AutoRecon/CenterShift nor ReconSettings/CenterShift, so MBIRJAX cannot derive the centre of rotation from it. All six reference datasets carry a non-zero centre shift, so this is unusual — check whether the file was fully written by the acquisition software.

The process exits without writing a status file. That is a hard crash inside the venv (typically a JAX/DLL problem or an out-of-memory kill). The panel shows the tail of runner_log.txt; the full log is in the job folder under %LOCALAPPDATA%\DragonflyPrototypeLabs\TxrmMbirjax\jobs.

It sits at 45% "reconstructing with FDK" and never moves. Almost always memory, not a hang. Open the job folder's runner_log.txt (the path is printed in the log on the Environment tab, under %LOCALAPPDATA%\DragonflyPrototypeLabs\TxrmMbirjax\jobs); if the last line is the FDK message and nothing follows, the process is still computing but paging. Check the memory estimate on the QC tab. A full-resolution 3401-view reconstruction on the CPU is not a practical run: set Keep every n-th projection to 4 and both detector downsample factors to 2, confirm the geometry, and only then consider more. Note that Cancel alone cannot interrupt the reconstruction phase — MBIRJAX has no hook inside it — so click Cancel a second time to stop the process.

It is very slow, or runs out of memory. Reconstruction is CPU-only on Windows and a full Versa volume is around 4 GB in float32. Downsample the detector by 2 and subsample views by 4 for a preview, and use FDK rather than MBIR unless the scan is short.

The volume looks mirrored or upside down. Angle sign and vertical row order are stored conventions, and MBIRJAX negates the angles while ZEISS's own display flips rows. Compare against the vendor _recon.txm on an asymmetric feature before trusting orientation for a directional measurement.

A folder scan does not offer a file I expected. *_Drift.txrm is filtered out by design, and mosaic acquisitions are reported as blocking. Only true projection sets (AcquisitionMode = 0) can be reconstructed.

Does downsampling change the voxel size? Yes, and the plugin accounts for it: the reconstruction voxel is PixelSize x column-downsample, so a 2x column downsample gives twice the voxel. results.json records both the delivered voxel_size_um and the expected value, and the published Channel's spacing is always derived from the real voxel - a downsampled volume is correctly scaled, just coarser.

Can I reconstruct from only part of the projections? Yes - that is what the Projection subset group is for, and it is the intended way to simulate angles that were blocked or invalid. Three cautions. (1) Dropping views from the ENDS shortens the angular span (a short scan); excluding a MIDDLE range leaves the span intact but punches a hole in it (a missing wedge). The artefacts differ, and the QC preview reports both the span and the largest hole so you can tell which you have built. (2) A circular cone-beam scan stays data-complete only down to 180 deg PLUS the full fan angle, so trimming a 360-deg scan to 300 deg is still a mild case; genuine limited-angle distortion starts below that limit, which the preview flags per variant. (3) Grey values are NOT comparable between subsets, because the FDK ramp filter folds in a pi / num_views weight that does not track the retained span - compare structure, or use the iterative MBIR algorithm, which handles missing coverage far better than FDK.

10. Notes & known limitations

Mosaic (stitched) acquisitions are not supported. They are detected and reported as blocking rather than silently reshaped into a wrong array.

Files that are refused outright (reported as blocking in step 4, never reconstructed): mosaic/stitched acquisitions; a parallel-beam Xradia Ultra (zone-plate) scan, which needs a parallel-beam reconstruction this plugin does not set up; the *_Drift.txrm drift-tracking companion, even when selected by hand; anything whose AcquisitionMode is not a projection set; a scan aborted before its first projection (ImagesTaken = 0); an unknown pixel DataType; and a file whose magnification chain does not close.

No dark frame exists in a .txrm. MBIRJAX assumes a zero dark scan. Residual offset is handled by the background-offset correction instead.

Only the first source and detector distance is used. Both are stored per projection; if they vary, the QC report warns and any source/detector drift is ignored.

A missing flat field degrades rather than blocks. MBIRJAX falls back to an all-ones reference with a warning, which typically leaves ring and shading artefacts. The QC report says so before you run.

Grey values are line-integral attenuation per ALU, recorded in results.json as value_units rather than silently rescaled. They are not Hounsfield units and not directly comparable with the vendor reconstruction's scaling.

Interrupted scans read only what was written. If ImagesTaken is less than NoOfImages the QC report warns and only the written projections are used.

The geometry identities were verified against six real Xradia Versa datasets (magnification 2.56x to 10.80x) on 2026-08-05: the derived magnification matched XrayMagnification exactly, the closure identity held to within 5e-8, the derived half-cone angle matched ConeAngle exactly, and PixelSize equalled the sibling vendor reconstruction's voxel size on every file.

11. References

MBIRJAX (BSD-3-Clause) — https://github.com/cabouman/mbirjax and https://mbirjax.readthedocs.io · JAX (Apache-2.0) — https://github.com/jax-ml/jax · olefile (BSD-2-Clause) — https://github.com/decalage2/olefile · The Zeiss reader in MBIRJAX credits Amir Koushyar Ziabari (Oak Ridge National Laboratory). Companion plugins in this suite: Load TXM Files (opens a vendor-reconstructed .txm), CT/TEM Reconstruction (ASTRA) (reconstructs an already-loaded projection Channel), CT Artifact Correction (Algotom) (ring/stripe and zinger correction).