imagefly. Prototype Apps Documentation All manuals Analysis guides
Reconstruction & ImagingChinese & English

Load TXM Files

Load TXM Files opens ZEISS Xradia .txm reconstructed volume files inside Dragonfly and publishes them as Dragonfly image Channels. It is a dockable panel under Prototype Apps: use Add Files... to pick one or more .txm fi

Updated 2026-07-26User manual

Load TXM Files(加载 ZEISS Xradia .txm 重建体数据)

Load TXM Files - User Manual

Dragonfly Prototype Apps · Load TXM Files...

版本 Version 1.0 · 2026-07-26


第一部分 中文手册

目录

1. 简介

2. 功能特点

3. 使用步骤

4. 环境需求

5. 提示与注意事项

1. 简介

Load TXM Files 在 Dragonfly 内打开蔡司(ZEISS)Xradia 的 .txm 重建体数据文件,并把它们发布为 Dragonfly 的 image Channel。它是 Prototype Apps 里的一个可停靠(dockable)面板:用 Add Files... 选择一个或多个 .txm,或用 Add Folder... 递归扫描某个文件夹下的全部 .txm;在列表里点选某个文件即可看到它的尺寸、数据类型、体素尺寸与一张中间切片的预览缩略图;点 Load into Dragonfly 把列表里的文件全部读入并发布。

本插件刻意不使用任何 Dragonfly 内置加载器。它的解码逻辑逐字沿用 UnitedVision 项目中已验证可用的 TXM 读取代码,因此读取路径(体素 spacing、切片顺序、数据类型映射)与 UnitedVision 完全一致——当你需要让两套工具得到可复现的结果时,这一点非常有用。

.txm 本质是一个 OLE2 复合文档(Compound File):重建体数据以每张灰度切片一个 ImageDataN/ImageM 流的方式存放,ImageInfo/* 流里保存尺寸、数据类型编码与像素尺寸。插件用一个随包携带的纯 Python olefile 逐流读取,无需任何编译依赖。

2. 功能特点

  • 批量导入:一次可加入多个 .txm 文件;Add Folder... 会递归扫描整个文件夹并按路径排序加入所有 .txm。
  • 导入前预览:在列表中点选某个文件,右侧会显示它的 Dimensions(X × Y × Z)、Data type、Voxel size 与 File size,并渲染一张中间切片的灰度缩略图——预览只读取单张切片,速度很快。
  • 准确的体素尺寸:体素尺寸由 TXM 的 ImageInfo/PixelSize(单位微米)读出;ZEISS 体数据为各向同性,发布时按物理尺寸写入 X/Y/Z spacing(以米为单位,符合 ORS 约定)。
  • 数据类型映射:DataType == 5 → uint16,其余 → float32,与 UnitedVision 的读取一致。
  • 不卡界面:较慢的整卷解码在后台工作线程上进行,进度条实时显示 [i/n] 进度,只有对象模型(发布 Channel)那几步才会切回 Qt UI 线程;随时可点 Cancel 中止。
  • 列表管理:Remove 移除选中项、Clear 清空列表;底部日志区显示每个文件的解码与发布过程。

3. 使用步骤

1. 在 Prototype Apps ▸ Load TXM Files... 打开面板(位于 Reconstruction & Imaging 分组)。

2. 点 Add Files... 选择一个或多个 .txm 文件;或点 Add Folder... 选一个文件夹,插件会递归扫描其中所有 .txm 并加入列表。

3. (可选)在列表里点选某个文件,查看右侧的尺寸、数据类型、体素尺寸,以及中间切片预览缩略图,确认这是你要导入的数据。

4. (可选)用 Remove 移除不需要的项,或 Clear 清空重来。

5. 点 Load into Dragonfly,插件会逐个解码并发布——进度条显示总体进度,日志区打印每个文件的 shape 与 spacing。

6. 完成后每个 .txm 会成为对象列表里的一个新 Channel(名称取自文件名),体素 spacing 已按 PixelSize 写好,可直接在 2D/3D 视图中查看。若中途要停止,点 Cancel。

4. 环境需求

纯进程内运行,零配置:无需建立 venv、无需联网、无需 GPU、无需管理员权限。

  • 仅依赖 Dragonfly 自带的 numpy,以及随插件打包的纯 Python olefile(OLE2 读取器,BSD 许可,位于 txm_code/vendor/olefile)——首次使用无需任何下载或安装步骤。
  • 内存:整卷会一次性读入内存后再发布,请确保内存足以容纳该体数据。一个约 990 张切片的 uint16 体数据(约 2 GB)解码约需数十秒;插件在处理下一个文件前会主动释放上一卷占用的内存。
  • 安装:运行 python install_load_txm_plugin.py(任意 Python 3 均可),然后完全重启 Dragonfly;--uninstall 可卸载。本插件也随 Full / Apps 安装包分发(id load_txm,默认启用)。

5. 提示与注意事项

  • 为什么不用内置加载器:Dragonfly 本身也能打开 .txm,但本插件特意改用 UnitedVision 那套读取代码,以保证两个工具的体素 spacing、切片顺序与 dtype 逐位一致,便于复现。若你只想快速打开、不在意与 UnitedVision 对齐,用 Dragonfly 自带的导入也可以。
  • 预览失败不影响导入:预览是尽力而为的;即使某个文件读不出缩略图或元数据,通常仍可点 Load into Dragonfly 正常导入(真正的失败会在日志里打印完整堆栈)。
  • 只认 .txm:文件筛选与文件夹扫描都只匹配 .txm 扩展名;若文件不是合法的 OLE2 容器,读取会报 Not a valid TXM/OLE image container。
  • 缺少 PixelSize 时:体素尺寸会显示为 unknown,Channel 仍会发布,但没有物理 spacing——后续如需真实尺寸,请在 Dragonfly 里手动设置。


Part II English Manual

Contents

1. Introduction

2. Features

3. How to use

4. Requirements

5. Tips & notes

1. Introduction

Load TXM Files opens ZEISS Xradia .txm reconstructed volume files inside Dragonfly and publishes them as Dragonfly image Channels. It is a dockable panel under Prototype Apps: use Add Files... to pick one or more .txm files, or Add Folder... to recursively scan a folder for every .txm; select a file in the list to see its dimensions, data type, voxel size and a mid-slice preview thumbnail; then click Load into Dragonfly to read and publish every listed file.

The plugin deliberately does not use any Dragonfly built-in loader. Its decode logic is carried over verbatim from the working TXM reader in the UnitedVision project, so the read path (voxel spacing, slice order, dtype mapping) is identical to UnitedVision — useful whenever you want reproducible results across the two tools.

A .txm is really an OLE2 compound file: the reconstructed volume is stored as one grayscale slice per ImageDataN/ImageM stream, while ImageInfo/* streams hold the dimensions, dtype code and pixel size. The plugin reads them stream-by-stream with a bundled pure-Python olefile, so there is no compiled dependency.

2. Features

  • Batch import: add many .txm files at once; Add Folder... recursively scans a whole folder and adds every .txm it finds, sorted by path.
  • Preview before import: selecting a file in the list shows its Dimensions (X x Y x Z), Data type, Voxel size and File size on the right, plus a grayscale thumbnail of the middle slice — the preview reads only a single slice, so it is fast.
  • Accurate voxel size: the voxel spacing is read from the TXM ImageInfo/PixelSize (in micrometres); ZEISS volumes are isotropic, so the X/Y/Z spacing is written from the physical size (in metres, per the ORS convention) when the Channel is published.
  • Data-type mapping: DataType == 5 maps to uint16, everything else to float32, matching UnitedVision's reader.
  • Responsive UI: the slow full-volume decode runs on a background worker thread with a live [i/n] progress bar; only the object-model calls (publishing the Channel) are marshaled onto the Qt UI thread, and you can hit Cancel at any time.
  • List management: Remove drops the selected items and Clear empties the list; a log pane at the bottom traces each file's decode and publish steps.

3. How to use

1. Open the panel at Prototype Apps ▸ Load TXM Files... (in the Reconstruction & Imaging group).

2. Click Add Files... to pick one or more .txm files; or Add Folder... to pick a folder, and the plugin recursively scans it for every .txm and adds them to the list.

3. (Optional) Select a file in the list to inspect its dimensions, data type and voxel size on the right, plus the mid-slice preview thumbnail, and confirm it is the data you want.

4. (Optional) Use Remove to drop unwanted entries, or Clear to start over.

5. Click Load into Dragonfly; the plugin decodes and publishes each file in turn — the progress bar shows overall progress and the log prints each file's shape and spacing.

6. When it finishes, each .txm becomes a new Channel in the object list (named from the file name) with voxel spacing already set from PixelSize, ready to view in 2D/3D. Click Cancel to stop partway.

4. Requirements

Runs purely in-process with zero setup: no venv, no internet, no GPU and no admin rights.

  • It depends only on Dragonfly's bundled numpy plus a pure-Python olefile (a BSD-licensed OLE2 reader packaged under txm_code/vendor/olefile) — there is no download or install step on first use.
  • Memory: the full volume is read into memory before publishing, so make sure you have room for it. A ~990-slice uint16 volume (~2 GB) takes on the order of tens of seconds to decode; the plugin releases each volume's memory before starting the next file.
  • Install: run python install_load_txm_plugin.py (any Python 3), then fully restart Dragonfly; --uninstall removes it. The plugin also ships in the Full / Apps packages (id load_txm, enabled by default).

5. Tips & notes

  • Why not the built-in loader: Dragonfly can open .txm natively, but this plugin intentionally uses UnitedVision's read code so the voxel spacing, slice order and dtype are bit-for-bit identical across the two tools, for reproducibility. If you just want a quick open and do not care about matching UnitedVision, the built-in importer is fine too.
  • A failed preview does not block import: the preview is best-effort — even if a file's thumbnail or metadata cannot be read, you can usually still click Load into Dragonfly and import it (a real failure prints the full stack trace in the log).
  • .txm only: both the file filter and the folder scan match only the .txm extension; if a file is not a valid OLE2 container the read fails with Not a valid TXM/OLE image container.
  • When PixelSize is missing: the voxel size shows as unknown and the Channel is still published, but without physical spacing — set it manually in Dragonfly afterwards if you need real-world units.
You’ve reached the end of this manual.Explore the library →