Image Exporter（图像导出器）

Image Exporter - User Manual

Dragonfly Prototype Apps · Image Exporter...

版本 Version 2.0 · 2026-08-11

第一部分 中文手册

目录

1. 简介

2. 标签页 1 — Bruker CTAn（8 位 BMP）

3. 标签页 2 — DICOM 序列（独立写入器）

4. 标签页 3–5 — NIfTI、ITK / 3D Slicer、VGStudio

5. 值得了解的细节

6. 环境需求

1. 简介

把图像通道导出为其它软件所需的确切文件格式。面板由多个标签页组成——每个标签页对应一种目标软件/格式：Bruker CTAn（8 位 BMP 序列）、DICOM 序列、NIfTI、ITK / 3D Slicer（MetaImage / NRRD）和 VGStudio（.vgi + .vol）。

不创建、不修改会话中的任何对象。 本插件只读取所选通道，并把文件写入你指定的文件夹。

每个标签页的上半部分相同：选择通道（发布新通道后点「刷新」），查看尺寸、数据类型和体素尺寸，4D 数据可选时间步，选择输出文件夹，点「导出」。进度条显示进度，「取消」可中止，「打开输出文件夹」查看结果。

⚠ 除 CTAn 的 BMP 外，其余格式都携带几何信息。体素尺寸无法从通道读取时，导出会被拒绝而不是写入猜测值；原点未知时写 0, 0, 0 并在结果信息中说明。

导出数值（位于标签页上方，对全部标签页生效）：「原始灰度值」（默认）按存储值导出体素；「校准值」导出 Dragonfly 的 readout values——原始值 × slope + offset——并且一律以 float32（4 字节浮点）写出。通道信息行会显示 readout 公式；校准导出完成后结果信息也会重复该公式。通道的 slope/offset 无法读取时，校准导出会被拒绝，而不是悄悄退回原始值。在 CTAn 标签页中，校准值按浮点数据处理（仍会做 0–255 映射，「保持原值」不可用）；在 DICOM 中量化为 16 位并报告 rescale slope/intercept。

2. 标签页 1 — Bruker CTAn（8 位 BMP）

CTAn 可以加载七种文件类型（BMP、JPG、PNG、TIFF、RAW、ISQ、DICOM），但它的分析流程只处理 1 位黑白和 8 位灰度图像。因此 8 位灰度 BMP 序列是最稳妥的交换格式，本标签页写出的正是这种格式。

• 灰度映射：「保持原值」（仅当数据已是 8 位）、「自动」（数据最小值 → 0、最大值 → 255）或「自定义范围」（范围外的值截断）。「读取数据范围」把实测范围填入最小/最大输入框。
• 文件编号：前缀（默认跟随通道名，手动修改后不再跟随）、「编号位数」（3 = 000–999，4 = 0000–9999）和「起始编号」，并实时预览第一个和最后一个文件名。位数装不下最后一个文件时，在写出任何文件之前就会被拒绝。
• NRecon 风格 .log：默认勾选，在切片旁写出 <前缀>.log，以微米记录像素尺寸——CTAn、CTvox、DataViewer 会自动读取，不再需要手动填写像素尺寸。仅当 X 与 Y 体素尺寸一致时才写 log（该格式只有一个像素尺寸字段）；若 Z 间距与之不同，log 仍会写出，但结果信息会警告 CTAn 将按立方体素处理。

在 CTAn 中打开序列的第一个文件；CTAn 会按相同前缀和等宽编号自动识别整个序列。

3. 标签页 2 — DICOM 序列（独立写入器）

使用与 Dragonfly 自带 DICOM 导出完全无关的写入器（内置 pydicom 2.4.4，不使用 Dragonfly 的任何代码）写出 DICOM 序列。它的定位是对照工具：当 Dragonfly 导出的数据在其它软件中出现偏差时，用本标签页导出同一通道进行比对。

• 每个切片一个 CT Image Storage 文件，Explicit VR Little Endian，逐片写明几何信息：PixelSpacing 按 DICOM 的 [行, 列] = [Y, X] 顺序、ImagePositionPatient 按 Z 间距递增、SliceThickness、InstanceNumber。
• 像素以 16 位存储。uint16/int16 原样写出（slope 1、intercept 0）；8 位数据无损加宽；浮点和 32 位整数数据量化为 65536 级，并写入可换算回原始值的 RescaleSlope/Intercept——结果信息会给出准确的 slope、intercept 和量化步长。
• 患者姓名、患者 ID、序列描述均可编辑（默认分别为 "Dragonfly Export"、"DF"、通道名）。中文通道名可正常保存（UTF-8 字符集）。

4. 标签页 3–5 — NIfTI、ITK / 3D Slicer、VGStudio

• NIfTI：一个 .nii 文件；文件名以 .gz 结尾时（默认）写 .nii.gz。3D Slicer、ITK-SNAP、nnU-Net、MONAI 的通用格式。体素尺寸与原点以毫米写入（sform/qform code 1）。NIfTI 的坐标轴为 RAS，而 Dragonfly 的世界坐标为 LPS（与 DICOM 相同），因此 x、y 轴取反写入——与 ITK / SimpleITK 的写法完全一致——图像与本插件导出的 NRRD、MetaImage 文件落在同一组物理位置上。（2026-09-23 之前的 NIfTI 未做该取反，相对它们绕 Z 轴旋转了 180°。）
• ITK / 3D Slicer：MetaImage（.mhd + .raw 或单文件 .mha）或 NRRD（gzip 编码，LPS 空间）。ITK / elastix / Slicer 生态的格式；文件扩展名随所选格式自动切换。
• VGStudio：.vol 原始数据文件加 VGSTUDIO 可直接打开的 .vgi 描述文件（尺寸、数据类型、毫米体素尺寸）。支持的存储类型为 8/16 位无符号整数和 float32；其它数据会转换为 float32 并在结果信息中说明。若某个 VGStudio 版本不接受该 .vgi，.vgi 文本本身也列出了手动 raw 导入所需的全部参数。
• 不支持的数据类型会转换为该格式能容纳的最接近类型，转换总会在结果信息中写明——不做任何静默转换。

5. 值得了解的细节

• 目标文件已存在时，会先询问是否覆盖。
• 非有限体素（浮点数据中的 NaN/Inf）在 BMP 中写为 0，在 DICOM 中写为数据最小值；结果信息会注明。
• 切片序列导出被取消时，已写完的文件保留；单文件导出被取消时，不完整的文件会被删除。
• 4D 数据可选择要导出的时间步；每次导出一个时间步。
• 所有写入器均由本插件自行实现、输出字节确定；自动化测试既手工解析文件字节，也用 SimpleITK 作为独立解码器读回验证（含几何信息）。

6. 环境需求

无需安装、联网、GPU 或虚拟环境——面板在 Dragonfly 自带 Python（PyQt6 + numpy）中进程内运行；DICOM 标签页使用随插件分发的 pydicom。需要会话中有已发布的图像通道（Channel）。

Part II English Manual

Contents

1. Introduction

2. Tab 1 — Bruker CTAn (8-bit BMP)

3. Tab 2 — DICOM series (independent writer)

4. Tabs 3–5 — NIfTI, ITK / 3D Slicer, VGStudio

5. Details worth knowing

6. Requirements

1. Introduction

Exports image channels in the exact file format some other software expects. The panel is a set of tabs — one per target software or file format: Bruker CTAn (8-bit BMP stack), DICOM series, NIfTI, ITK / 3D Slicer (MetaImage / NRRD) and VGStudio (.vgi + .vol).

Nothing is created or modified in the session. The plugin only reads the selected channel and writes files into the folder you choose.

Every tab shares the same top section: pick the channel (Refresh after publishing a new one), see its size, data type and voxel size, pick the time step for 4D data, choose the output folder, press Export. A progress bar tracks the run, Cancel stops it, and Open output folder opens the result.

⚠ All formats except CTAn's BMP carry geometry. When the voxel size cannot be read from the channel, the export is REFUSED rather than writing a guessed value; an unknown origin is written as 0, 0, 0 and stated in the result message.

Values to export (above the tabs, applies to every tab): Original grayscale values (default) writes the voxels as stored; Calibrated values writes Dragonfly's readout values — raw × slope + offset — always as float32 (4-byte float). The channel info line shows the readout formula; the result message repeats it after a calibrated export. A channel whose slope/offset cannot be read REFUSES a calibrated export rather than silently exporting raw values. In the CTAn tab, calibrated data behaves like any float data (the 0–255 remapping still applies, and "keep original values" is unavailable); in DICOM it is quantized to 16-bit with the rescale slope/intercept reported.

2. Tab 1 — Bruker CTAn (8-bit BMP)

CTAn can load seven file types (BMP, JPG, PNG, TIFF, RAW, ISQ, DICOM), but its analysis pipeline processes only 1-bit monochrome and 8-bit grayscale images. An 8-bit grayscale BMP stack is therefore the safest interchange format, and it is what this tab writes.

• Grayscale mapping: Keep original values (only when the data is already 8-bit), Auto (data min → 0, max → 255) or Custom range (values outside are clipped). Read data range fills the min/max fields with the measured range.
• File numbering: prefix (follows the channel name until you type your own), number of digits (3 = 000–999, 4 = 0000–9999) and start number, with a live preview of the first and last filename. A digit width that cannot hold the last file is refused before anything is written.
• NRecon-style .log: ticked by default, writes <prefix>.log next to the slices with the pixel size in micrometres — CTAn, CTvox and DataViewer read it automatically, so the pixel size no longer has to be typed by hand. The log is only written when the X and Y voxel sizes agree (the format has a single pixel-size field); if the Z spacing differs, the log is still written but the result message warns that CTAn assumes cubic voxels.

In CTAn, open the FIRST file of the stack; CTAn picks up the rest by the shared prefix and the equal-width numbering.

3. Tab 2 — DICOM series (independent writer)

Writes a DICOM series with a writer that is fully independent of Dragonfly's own DICOM export (it uses a bundled copy of pydicom 2.4.4 and none of Dragonfly's code). It exists as a cross-check: if a dataset exported by Dragonfly lands with deviations in other software, export the same channel here and compare.

• One CT Image Storage file per slice, Explicit VR Little Endian, with the geometry stated per slice: PixelSpacing in DICOM's [row, column] = [Y, X] order, ImagePositionPatient stepping by the Z spacing, SliceThickness, InstanceNumber.
• Pixels are stored as 16-bit. uint16/int16 data passes through unchanged (slope 1, intercept 0); 8-bit widens losslessly; float and 32-bit integer data is quantized to 65536 levels with a RescaleSlope/Intercept that maps stored cells back to the original values — the result message states the exact slope, intercept and quantization step.
• Patient name, patient ID and series description are editable fields (defaults: "Dragonfly Export", "DF", the channel title). Chinese titles survive (UTF-8 character set).

4. Tabs 3–5 — NIfTI, ITK / 3D Slicer, VGStudio

• NIfTI: one .nii file, gzipped to .nii.gz when the file name ends with .gz (the default). The common format of 3D Slicer, ITK-SNAP, nnU-Net and MONAI. Voxel size and origin in millimetres (sform/qform code 1). NIfTI's axes are RAS while Dragonfly's world is LPS (as in DICOM), so the x and y axes are written negated — exactly what ITK / SimpleITK write — and the image lands on the same physical points as this plugin's NRRD and MetaImage files. (Before 2026-09-23 the NIfTI was written unflipped, i.e. rotated 180° about Z against them.)
• ITK / 3D Slicer: MetaImage as .mhd + .raw pair or single-file .mha, or NRRD (gzip encoding, LPS space). The formats of the ITK/elastix/Slicer world; the file-name extension follows the chosen format automatically.
• VGStudio: a .vol raw file plus the .vgi descriptor VGSTUDIO opens directly (size, data type, voxel size in mm). Supported cell types are 8/16-bit unsigned and float32; other data is converted to float32 and the result message says so. If a particular VGStudio build rejects the .vgi, the .vgi itself lists every parameter a manual raw import needs.
• Unsupported data types are converted to the nearest type the format can hold, and the conversion is always named in the result message — nothing is converted silently.

5. Details worth knowing

• If target files already exist, the panel asks before overwriting them.
• Non-finite voxels (NaN/Inf in float data) are written as 0 in BMP, and as the data minimum in DICOM; the result message notes it.
• Cancelling a slice-stack export keeps the complete files already written; cancelling a single-file export deletes the partial file.
• For 4D data, pick the time step to export; one time step is exported per run.
• Every writer is implemented in this plugin and produces byte-deterministic output; the automated tests parse the files back by hand AND read them through SimpleITK as an independent decoder (geometry included).

6. Requirements

No install, no internet, no GPU, no virtual environment — the panel runs in-process on Dragonfly's own Python (PyQt6 + numpy); the DICOM tab uses a copy of pydicom bundled with the plugin. It needs a published image Channel in the session.