Multi-ROI Export（Multi-ROI 导出）

Multi-ROI Export - User Manual

Dragonfly Prototype Apps · Multi-ROI Export...

版本 Version 2.0 · 2026-09-23

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

在窗口顶部只选一次 Multi-ROI（及其时间步），再用三个选项卡以三种方式把它导出：单个 STL 文件（每个标签一个 STL 文件）、NIfTI (.nii)（全部勾选的标签写成一个 NIfTI 标签图）和报告（该 Multi-ROI 全部测量的 Excel、PowerPoint、Word 或 PDF 报告）。三个选项卡是同一输入的三种输出，不是先后步骤；同一时间只运行其中一个。

不向会话添加任何对象，也不修改任何对象。 STL 与 NIfTI 选项卡只使用临时对象，用完即删；报告选项卡为截图临时改变的视图、可见性和着色会在完成后全部恢复。绝不覆盖已有文件：重名时自动改名，或为报告新建子文件夹。

报告选项卡就是原来的插件“Create a Report from MultiROI（从 MultiROI 生成报告）”，该插件已并入这里并停用：xlsx / pptx / docx / pdf、直方图、每项测量的三维截图、分享到网页和临时链接全部保留，并修正了截图后不能恢复会话等问题。安装新版本时，旧插件会被自动移除。Full Workflow using Cellpose 向导的第 4 步嵌入的也是这个报告选项卡。

单个 STL 文件选项卡是 Multi-ROI to Multi-Mesh (Surface Determination) 插件的简化版：不做表面确定（灰度吸附），只做 Dragonfly 自己的 ROI → 网格（marching cubes）。

2. 适用场景

• STL：把多相材料、颗粒、孔隙、骨骼/牙齿、器官或零件分割后的每个类别分别导出为 STL，交给 CAD、3D 打印切片软件、有限元（FEA）或 CFD 前处理；只导出某几个标签；逐个打印分离的部件（勾选“将每个部件居中到原点”）。
• NIfTI：把分割结果作为标签图交给 nnU-Net、MONAI 等深度学习训练（勾选“按 1..K 连续重新编号”）；在 ITK-SNAP 或 3D Slicer 中打开，与原图像（用图像导出插件导出的 NIfTI / NRRD / MetaImage）叠加检查；与使用 ITK、nibabel 的分析流程交换数据。
• 报告：把一次孔隙/颗粒/晶粒分割的各项测量（体积、球形度、表面积、等效直径……）整理成可直接汇报的报告；用 PowerPoint 逐项展示分布与三维着色图；用 Excel 汇总统计量便于二次分析；在网页上把报告分享给同事或客户。

3. 安装与启用

1. 打开 Prototype Apps ▸ App Store（应用商店），在 Generators & Utilities 分组里找到 Multi-ROI Export 并启用（或用 Prototype Apps 安装程序安装时勾选它）。

2. 完全重启 Dragonfly——插件只在启动时被发现。

3. 菜单项为 Prototype Apps ▸ Multi-ROI Export...（中文界面下显示为“Multi-ROI 导出…”），位于 Import & Export 一节。

4. 如果以前安装过 “Create a Report from MultiROI”，App Store、安装程序和卸载程序会自动移除它（只移除带有本产品标记的文件夹）；重启 Dragonfly 后它的菜单项消失。

5. 如需隐藏或恢复该菜单项，可使用 Menu Item Manager（菜单项管理器）。

4. 运行环境与首次配置

无需任何配置。 插件在 Dragonfly 自己的 Python 中进程内运行（PyQt6 + Dragonfly 自带的 numpy、openpyxl、matplotlib）：无需虚拟环境、无需 GPU、无需管理员权限。PowerPoint 所需的 python-pptx 1.0.2（MIT 许可）随插件提供，不再在首次使用时下载。

Dragonfly 2025.1 与 2027.1 均可使用。STL 与 NIfTI 文件由插件自带的写入器生成（纯 numpy），两个版本写出的文件完全一致。

只有报告选项卡的“把报告分享到网页”和“临时链接”需要联网，而且只在你点击并确认后才会上传或下载：临时链接首次使用时需要 Cloudflare 的 cloudflared.exe（约 52 MB），会先征得你的同意再下载并按用户保存。

5. 界面说明

选项卡上方（三个选项卡共用）

• 要导出的 Multi-ROI：选择会话中已发布的 Multi-ROI。刷新只重新列出 Multi-ROI，不会改动各选项卡的内容；只有换了所选的 Multi-ROI 才会重新读取标签。会话中的对象发生变化时，列表会自动更新。
• 时间步：只有多时间步（4D）的 Multi-ROI 才可调整；三个选项卡都使用这里选的时间步。
• 重新读取标签：例如在 Dragonfly 中给标签改名或删除标签之后使用；已勾选的项和已输入的文件名会保留。
• 下方一行显示标签数、网格大小和体素尺寸；窗口底部是进度条和状态行。整个窗口同一时间只运行一项工作：一个选项卡正在导出时，其他选项卡的开始按钮会说明原因而不开始。

选项卡 1 — 单个 STL 文件

• 全选 / 全不选 / 重置文件名；网格生成（marching cubes）：采样 X / Y / Z、先填充内部空腔、平滑次数、平滑强度；输出：文件夹（可输入或“浏览…”）、STL 格式、单位、文件名后缀、将每个部件居中到原点；导出 STL 文件、取消（当前标签完成后停止）、打开文件夹，以及结果摘要和逐文件日志。

选项卡 2 — NIfTI (.nii)

• 全选 / 全不选；按 1..K 连续重新编号（用于机器学习）。
• 输出：文件夹（可输入或“浏览…”）；文件名（留空 = 使用 Multi-ROI 的名称）——四个文件共用这一个名称；NIfTI 文件：.nii（默认）或 .nii.gz（压缩）。下方一行显示将写入的四个文件名。
• 导出 NIfTI、取消（停止后文件夹中不留下任何文件）、打开文件夹，以及结果摘要和日志。

选项卡 3 — 报告

• 顶部一行显示将包含多少项测量（鼠标悬停可看到测量名称）；Multi-ROI 还没有测量时会提示先在 Dragonfly 中计算。
• 格式：Excel (.xlsx)、PowerPoint (.pptx)、Word (.docx)、PDF (.pdf)；每项测量附一张三维截图（使用实时三维视图，较慢），默认勾选；文件夹（默认为用户目录下的 DragonflyReports）与“浏览…”。
• 生成报告、取消（在下一步停止，不写出报告，并恢复会话）、打开文件夹（打开上一份报告所在的文件夹），以及结果行和日志。
• 两个可折叠的分区，用于分享上一份报告：把报告分享到网页（一直在线，直到您将其撤下）——GitHub Pages / Netlify / Gitee，可见性为公开、不公开或密码保护，发布后显示网址和二维码，“撤下”可再次删除；临时链接（无需账号；停止分享或退出 Dragonfly 时失效）——通过 Cloudflare 快速隧道从本机提供页面。没有报告时两个分区都不能发布。

6. 使用步骤

1. 在 Dragonfly 中准备好并发布一个 Multi-ROI（例如分割结果）；要生成报告，请先在 Dragonfly 中为它计算测量。

2. 打开 Prototype Apps ▸ Multi-ROI Export...，在顶部选择该 Multi-ROI（多时间步时再选时间步）；标签会自动读入。

3. 选择需要的选项卡，按下面相应的步骤操作。

导出 STL 文件

1. 勾选要导出的标签；需要时双击“文件名”修改名称。

2. 按需设置采样、填充空腔和平滑；选择文件夹、格式、单位、后缀，以及是否居中到原点。

3. 检查“最终文件名”一列，然后按 导出 STL 文件。

导出 NIfTI 标签图

1. 勾选要写入的标签；用于机器学习时勾选“按 1..K 连续重新编号（用于机器学习）”，并在“文件中的数值”一列核对编号。

2. 选择文件夹；需要时输入文件名；选择 .nii 或 .nii.gz。

3. 按 导出 NIfTI。完成后在 ITK-SNAP 中打开 .nii，再用 Segmentation ▸ Import Label Descriptions 导入 _itksnap.txt，即可看到名称和颜色。

生成报告

1. 选择格式和文件夹；需要三维截图时，确认当前布局中有三维视图。

2. 按 生成报告。截图期间请不要操作视图；完成后视图会自动恢复原状。

3. 按 打开文件夹 查看报告；需要分享时展开“把报告分享到网页”或“临时链接”分区。

7. 参数说明

单个 STL 文件

NIfTI (.nii)

报告

8. 输出结果

单个 STL 文件

• 每个勾选的标签一个 .stl 文件，写入所选文件夹；文件名即“最终文件名”一列所示。二进制文件头注明来源和单位（例如 unit=mm），且不以 solid 开头，以免被误认作 ASCII 文件。
• 坐标为 Dragonfly 的世界坐标（真实位置），按所选单位写出；三角形法向朝外（右手定则），封闭的表面在切片软件中是实体。每个文件写完都会读回核对三角形数量。

NIfTI (.nii)

• 文件头：intent 为 NIFTI_INTENT_LABEL（1002）、intent_name 为 Labels；数据类型取能容纳最大数值的最小整数类型（≤255 为 uint8，≤65535 为 uint16，否则 int32），从不使用浮点；scl_slope 恰为 1、scl_inter 恰为 0；cal_min 0、cal_max 为写入的最大数值；qform 与 sform 均为 1；单位毫米。ITK-SNAP 文件名不超过 23 个 ASCII 字符时还会写入 aux_file。
• 几何：文件放在 Dragonfly 中 Multi-ROI 所在的位置，含旋转（斜切网格也支持），单位毫米。Dragonfly 的世界坐标按 DICOM 的 LPS 理解，NIfTI 为 RAS，因此 x、y 轴取反写入——与 ITK / SimpleITK 的写法完全相同。文件中的体素 0 位于 Dragonfly 网格的角点（与图像导出插件的全部格式以及 Dragonfly 自身的 DICOM 导入相同）。
• 每个文件在获得正式文件名之前都会被读回校验（文件头、长度和体素校验和），并把每个标签的体素数与 Multi-ROI 自身的统计核对；任何一项不符都不会留下文件。

报告

• 所选文件夹中的新子文件夹 <Multi-ROI 名称>_report_<日期_时间>，内有报告文件（同名，扩展名为所选格式）以及直方图和截图图片。
• 总览：每项测量一行——平均值、中位数、最小值、最大值、Std Dev (population)（总体标准差）、单位、N（标签数）。Excel 中的统计量是数值，可直接排序和计算。随后每项测量一页（工作表 / 幻灯片 / 页），含直方图和三维截图；多时间步的 Multi-ROI 会注明时间步。
• 分享时另外生成一个自包含的 .html（所有图片内嵌），可见性和密码都写在这个文件里，因此每次发布都会重新生成。

会话中不会出现任何新对象。报告截图期间临时改变的布局、可见性、着色、图例、相机和当前视图，在完成、出错、取消或关闭窗口时都会恢复；报告为截图新建的图例会被删除。

9. 常见问题与故障排除

• 按钮提示原因而不开始：按钮始终可点，点击或悬停时会说明缺少什么——例如没有选择 Multi-ROI、没有勾选标签、文件夹不可写、另一个选项卡正在运行、Multi-ROI 没有测量。
• 导出被拒绝：“读取之后该 Multi-ROI 的标签已发生变化”：表格读取之后，Dragonfly 中有标签被删除（其后的标签会重新编号）、改名，或网格变了。为了不把一个标签的数据写成另一个标签的名称，STL 和 NIfTI 选项卡都不会写出任何文件。请按“重新读取标签”，检查表格后再导出。
• 我的 NIfTI 看起来旋转了 180°，或与原图像不重合——用的是什么坐标约定？ 本插件按 ITK 的标准写出：Dragonfly 的世界坐标按 LPS（与 DICOM 相同）理解，NIfTI 为 RAS，所以 x、y 取反；ITK-SNAP、3D Slicer、nibabel、SimpleITK 读取时都会把它放回正确位置。请与同样按此约定写出的图像比较：图像导出插件自 2026-09-23 起的 NIfTI、NRRD 和 MetaImage 与本标签图完全重合；该插件在此之前导出的 NIfTI 没有取反 x、y（绕 Z 轴旋转了 180°），请重新导出图像。只看体素数组（不看文件头）的工具不做这种换算。
• 为什么差半个体素？ NIfTI 规范把体素中心作为位置，而本插件与图像导出插件的全部格式、以及 Dragonfly 自身的 DICOM 导入一样，把体素 0 放在网格的角点。同一插件家族导出的图像和标签图因此彼此完全重合；与其他来源的数据比较时，可能相差半个体素。
• nnU-Net 报错说标签不连续：勾选“按 1..K 连续重新编号（用于机器学习）”再导出，并使用 JSON 中的 labels 段作为 dataset.json 的 labels。
• 提示超过 65535 个标签：文件改用 32 位整数写出；ITK-SNAP 只能显示不超过 65535 的标签数值，其他工具不受影响。提示某个轴超过 32767 个体素：NIfTI-1 无法保存，导出被拒绝（本插件不写 NIfTI-2）。
• 为什么报告会改变我的视图，之后又恢复？ 三维截图需要把布局中的三维视图最大化、隐藏其他对象，并按每项测量依次给 Multi-ROI 着色（使用 Dragonfly 为该测量提供的颜色映射，标签颜色从不被修改）。完成后——无论成功、出错、取消还是关闭窗口——布局、每个被改动对象的二维/三维可见性、着色、图例、相机和当前视图都会恢复，报告新建的图例会被删除；万一有某项未能恢复，日志会写明。不想改变视图时，取消勾选“每项测量附一张三维截图”。
• 报告里没有截图：当前布局中没有三维视图、没有当前视图，或所选时间步不为 0（Dragonfly 只按时间步 0 给 Multi-ROI 着色）时不截图，报告中会写明原因；统计量和直方图照常使用所选的时间步。
• 报告提示没有测量：测量须先在 Dragonfly 中计算（其测量工具会把结果加到 Multi-ROI 上）；本选项卡只负责汇报。计算后切换回报告选项卡，数量会自动更新。
• “Create a Report from MultiROI” 去哪儿了？ 它已并入本插件的报告选项卡，功能全部保留；旧插件在安装新版本时会被自动移除。其原来保存的设置不会迁移，需要重新填写一次托管账号等设置。
• 文件名后面多了 _1：文件夹中已有同名文件（或本次另一个标签使用了该名称）。插件绝不覆盖文件；NIfTI 的四个文件总是一起改名。
• 导入 CAD 后尺寸差 1000 倍：检查 STL 的“单位”。STL 不带单位，例如以 µm 写出的文件在默认毫米的软件中会大 1000 倍。
• 导出期间表格和选项变灰：这是有意的——一项工作运行时，所有会影响写入内容的输入都会锁定，结束后自动恢复。日志随时可读，“取消”可停止当前工作。
• 菜单中找不到插件：确认已在安装程序/应用商店中勾选，并完全重启 Dragonfly。

10. 注意事项与已知限制

• 只支持 Multi-ROI（不支持 2027.1 的 DenseMultiROI）。
• STL：单层切片（2D）的 Multi-ROI 无法生成网格；采样设置使某个方向少于 3 个采样点时同样不行。表面沿体素边界生成，不做亚体素的灰度吸附（需要时请使用 Multi-ROI to Multi-Mesh (Surface Determination) 插件）。Windows 路径长度限制为 260 个字符。
• NIfTI：每个文件一个时间步，不写 4D 文件，也不写 NIfTI-2；每个轴最多 32767 个体素。名称和颜色只保存在三个附属文件中（NIfTI 本身没有标签表），不写文件头扩展。体素 0 位于网格角点的约定与本产品其他导出一致，但尚未用 Dragonfly 自身的 NIfTI 导入做往返核对。
• 报告：只有时间步 0 才能截图；截图期间请不要操作视图。临时链接在按“停止分享”或退出 Dragonfly 之前一直有效（关闭本窗口只是把它隐藏）。
• 多时间步（4D）Multi-ROI 可选时间步导出，但尚未在运行中的 Dragonfly 中用真实 4D 数据验证。导出过程中不要删除该 Multi-ROI；插件会检查它是否仍然存在，若已删除则停止并说明原因。

11. 参考资料

• STL 文件格式：3D Systems 的 StereoLithography Interface Specification（二进制与 ASCII 两种形式）。W. E. Lorensen, H. E. Cline, “Marching Cubes: A High Resolution 3D Surface Construction Algorithm”, SIGGRAPH 1987。
• NIfTI-1 数据格式：NIfTI Data Format Working Group，nifti1.h（nifti.nimh.nih.gov）；ITK / SimpleITK 的 NIfTI 读写（RAS 与 LPS 的换算）。
• ITK-SNAP 标签描述文件格式；3D Slicer 颜色表（Colors 模块，CSV 形式）；nnU-Net 数据集格式（dataset.json 的 labels）。
• python-pptx 1.0.2（MIT 许可）；openpyxl；matplotlib。Dragonfly 帮助：ROI 导出为网格（Export as Sampled Mesh）、测量、视图布局。

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

Choose a Multi-ROI once (and its time step) at the top of the window, then export it three ways, one tab each: Individual STL Files (one STL file per label), NIfTI (.nii) (the ticked labels as one NIfTI label map) and Report (an Excel, PowerPoint, Word or PDF report of all its measurements). The three tabs are three outputs of one input, not steps in a sequence; only one of them runs at a time.

Nothing in the session is created or modified. The STL and NIfTI tabs use only temporary objects, deleted as they go; whatever the Report tab changes to take its screenshots — the view, visibility, colouring — is put back afterwards. No existing file is ever overwritten: a clash is renamed, and every report gets a new sub-folder.

The Report tab IS the former plugin Create a Report from MultiROI, retired into this one: xlsx / pptx / docx / pdf, histograms, a 3-D screenshot per measurement, web sharing and the temporary link all survive, and it now hands the session back after its screenshots. Installing this version removes the old plugin automatically. The Full Workflow using Cellpose wizard's step 4 embeds this same Report tab.

The Individual STL Files tab is a simplified sibling of Multi-ROI to Multi-Mesh (Surface Determination): no surface determination (no grey-level snap), only Dragonfly's own ROI → mesh (marching cubes).

2. Use cases

• STL: exporting each phase, particle, pore, bone or tooth, organ or part of a segmentation as its own STL for CAD, a 3D-printing slicer, FEA or CFD pre-processing; exporting only some labels; printing separated parts one at a time (tick Centre each part at the origin).
• NIfTI: handing a segmentation to nnU-Net, MONAI or another training pipeline as a label map (tick Renumber consecutively 1..K); opening it in ITK-SNAP or 3D Slicer over the original image (exported as NIfTI / NRRD / MetaImage by the Image Exporter); exchanging data with ITK- or nibabel-based analysis.
• Report: turning a pore / particle / grain segmentation's measurements (volume, sphericity, surface area, equivalent diameter, …) into a deliverable report; presenting per-measurement distributions and 3-D colour maps as a pptx; summarising the statistics in an xlsx for further analysis; sharing the report on the web with colleagues or customers.

3. Installation & enabling

1. Open Prototype Apps ▸ App Store, find Multi-ROI Export in the Generators & Utilities group and enable it (or tick it in the Prototype Apps installer).

2. Fully restart Dragonfly — plugins are discovered at startup only.

3. The item appears as Prototype Apps ▸ Multi-ROI Export..., in the Import & Export section.

4. If “Create a Report from MultiROI” was installed before, the App Store, the installer and the uninstaller remove it automatically (only folders carrying our own marker); its menu entry is gone after a restart.

5. Hide or restore the entry with the Menu Item Manager if needed.

4. Runtime environment & first-run setup

Nothing to set up. The plugin runs in-process in Dragonfly's own Python (PyQt6 + the numpy, openpyxl and matplotlib Dragonfly ships): no virtual environment, no GPU, no admin rights. python-pptx 1.0.2 (MIT), which PowerPoint output needs, ships with the plugin — there is no download on first use any more.

Works in Dragonfly 2025.1 and 2027.1. The STL and NIfTI files are written by the plugin's own writers (pure numpy), so both versions write identical files.

Only the Report tab's “Share the report on the web” and “Temporary link” need internet, and neither uploads or downloads anything without a click and a confirmation. The temporary link needs Cloudflare's cloudflared.exe (about 52 MB), which it downloads once, after asking, and keeps per user.

5. Interface

Above the tabs (shared by all three)

• Multi-ROI to export: pick a published Multi-ROI. Refresh only lists the Multi-ROIs again and leaves the tabs alone; the labels are read again only when the chosen Multi-ROI changes. The list also follows the session by itself when objects are added or deleted.
• Time step: enabled only for a multi-time-step (4-D) Multi-ROI; all three tabs use it.
• Re-read labels: e.g. after renaming or deleting a label in Dragonfly; ticks and typed file names are kept.
• Below them a line gives the label count, the grid size and the voxel size; the bottom of the window holds the progress bar and the status line. The whole window runs one job at a time: while one tab exports, another tab's start button says why instead of starting.

Tab 1 — Individual STL Files

• Select all / Select none / Reset file names; Meshing (marching cubes): Sampling X / Y / Z, Fill inner voids first, Smoothing passes, Smoothing strength; Output: Folder (typed or Browse...), STL format, Unit, File name suffix, Centre each part at the origin; Export STL files, Cancel (stops after the current label), Open folder, with the summary and a per-file log below.

Tab 2 — NIfTI (.nii)

• Select all / Select none; Renumber consecutively 1..K (for machine learning).
• Output: Folder (typed or Browse...); File name (empty = the Multi-ROI's name) — the one name all four files share; NIfTI file: .nii (default) or .nii.gz (compressed). The line below lists the four file names that will be written.
• Export NIfTI, Cancel (nothing is left in the folder), Open folder, with the summary and a log below.

Tab 3 — Report

• The top line says how many measurements will be included (hover for their names); a Multi-ROI with no measurements yet gets a note to compute some in Dragonfly first.
• Format: Excel (.xlsx), PowerPoint (.pptx), Word (.docx), PDF (.pdf); Include a 3D screenshot per measurement (live 3D view; slower), ticked by default; Folder (DragonflyReports in your user folder by default) and Browse....
• Generate report, Cancel (stops at the next step, writes no report and puts the session back), Open folder (the last report's folder), with a result line and a log below.
• Two folding sections share the last report: Share the report on the web (stays online until you take it down) — GitHub Pages / Netlify / Gitee, public, unlisted or password-protected, with the address and a QR code, and “Take it down” to delete it again; and Temporary link (no account; ends when you stop sharing or quit Dragonfly) — a Cloudflare quick tunnel serving the page from this computer. Neither can publish until there is a report.

6. How to use

1. Prepare and publish a Multi-ROI in Dragonfly (e.g. a segmentation); for a report, compute its measurements in Dragonfly first.

2. Open Prototype Apps ▸ Multi-ROI Export... and pick it at the top (and the time step, for a 4-D one); its labels are read in.

3. Choose the tab you need and follow its steps below.

Export STL files

1. Tick the labels to export; double-click a File name to change it.

2. Set the sampling, void filling and smoothing as needed; choose the folder, format, unit, suffix and whether to centre each part.

3. Check the Final file name column, then press Export STL files.

Export a NIfTI label map

1. Tick the labels to write; for machine learning tick Renumber consecutively 1..K (for machine learning) and check the numbers in the Value in file column.

2. Choose the folder, type a file name if you want one, and pick .nii or .nii.gz.

3. Press Export NIfTI. Then open the .nii in ITK-SNAP and use Segmentation ▸ Import Label Descriptions on the _itksnap.txt to get the names and colours.

Generate a report

1. Choose the format and the folder; for screenshots make sure the layout has a 3D view.

2. Press Generate report. Leave the views alone while the screenshots are taken; they are put back by themselves afterwards.

3. Press Open folder to see the report; to share it, open “Share the report on the web” or “Temporary link”.

7. Parameters

Individual STL Files

NIfTI (.nii)

Report

8. Output

Individual STL Files

• One .stl file per ticked label in the chosen folder, named as the Final file name column shows. The binary header names the source and the unit (e.g. unit=mm) and deliberately does not start with solid, so no reader mistakes it for ASCII.
• Coordinates are Dragonfly's world coordinates (the real position) in the chosen unit; triangles face outward (right-hand rule), so a closed surface is a solid in a slicer. Every file is read back to confirm its triangle count.

NIfTI (.nii)

• Header: intent NIFTI_INTENT_LABEL (1002), intent_name Labels; the data type is the smallest integer type holding the largest value (uint8 up to 255, uint16 up to 65535, int32 beyond), never floating point; scl_slope exactly 1 and scl_inter exactly 0; cal_min 0 and cal_max the largest value written; qform and sform codes 1; millimetres. aux_file names the ITK-SNAP file when that name fits in 23 ASCII characters.
• Geometry: the file is placed where Dragonfly places the Multi-ROI, rotation included (oblique grids too), in millimetres. Dragonfly's world is read as DICOM LPS and NIfTI is RAS, so x and y are written negated — exactly as ITK / SimpleITK write it. Voxel 0 of the file is Dragonfly's grid corner, as in every format of the Image Exporter and in Dragonfly's own DICOM import.
• Before any file gets its final name it is read back and checked (header, length and a checksum of the voxels), and every label's voxel count is compared with the Multi-ROI's own; if anything disagrees, no file is left behind.

Report

• A new sub-folder <Multi-ROI name>_report_<date_time> in the chosen folder, holding the report file (same name, the chosen format's extension) and its histogram and screenshot pictures.
• Overview: one row per measurement — mean, median, min, max, Std Dev (population), unit, N (the number of labels). In Excel the statistics are numbers, ready to sort and calculate with. Then one page (sheet / slide / page) per measurement with its histogram and 3-D screenshot; a multi-time-step Multi-ROI's report states its time step.
• Sharing builds an extra self-contained .html (every picture embedded). The visibility and the password are baked into that file, so it is rebuilt for every publish.

No new object appears in the session. The layout, visibility, colouring, legends, camera and current view the screenshots change are put back on success, on an error, on Cancel and when the window closes, and any legend the report created for them is deleted.

9. FAQ & troubleshooting

• A button says why instead of starting: it stays clickable and tells you what is missing — no Multi-ROI, no label ticked, an unwritable folder, another tab still running, a Multi-ROI with no measurements.
• Export refused: “the Multi-ROI's labels changed since they were read”: after the table read them, a label was deleted in Dragonfly (the labels after it are renumbered), renamed, or the grid changed. Rather than write one label's data under another label's name, neither the STL nor the NIfTI tab writes anything. Press Re-read labels, check the table, and export again.
• My NIfTI looks rotated 180°, or does not overlay the image — which convention is this? The ITK one: Dragonfly's world is read as LPS (as in DICOM) and NIfTI is RAS, so x and y are negated, and ITK-SNAP, 3D Slicer, nibabel and SimpleITK all put it back in the right place. Compare it with an image written the SAME way: the Image Exporter's NIfTI, NRRD and MetaImage since 2026-09-23 overlay this label map exactly; a NIfTI that plugin wrote before that date was written without negating x and y (rotated 180° about Z) — export the image again. A tool that reads only the voxel array, ignoring the header, does no such conversion.
• Why half a voxel? The NIfTI standard places a voxel by its centre; this plugin — like every format of the Image Exporter and Dragonfly's own DICOM import — puts voxel 0 at the grid corner. Images and label maps from this family of plugins therefore overlay each other exactly; against data from elsewhere there can be half a voxel between them.
• nnU-Net complains the labels are not consecutive: tick Renumber consecutively 1..K (for machine learning) and export again, and use the JSON's labels block as the labels of your dataset.json.
• A warning about more than 65535 labels: the file is written as 32-bit integers; ITK-SNAP shows label values up to 65535 only, other tools are not affected. An axis longer than 32767 voxels: NIfTI-1 cannot store it, so the export is refused (this plugin does not write NIfTI-2).
• Why does the report change my view, and then restore it? A 3-D screenshot needs the layout's 3-D view maximised, the other objects hidden and the Multi-ROI coloured by each measurement in turn (in Dragonfly's own colour map for that measurement — the label colours are never changed). Afterwards — on success, on an error, on Cancel or when the window closes — the layout, the 2-D and 3-D visibility of every object it touched, the colouring, the legends, the camera and the current view are put back, and any legend the report created is deleted; should anything not come back, the log says what. To leave the views alone entirely, untick Include a 3D screenshot per measurement.
• The report has no screenshots: there is no 3-D view in the layout, no current view, or the chosen time step is not 0 (Dragonfly colours a Multi-ROI by time step 0 only); the report states the reason. The statistics and histograms still use the chosen time step.
• The report says there are no measurements: measurements are computed in Dragonfly (its measurement tools add them to the Multi-ROI); this tab only reports them. Switch back to the Report tab after computing them and the count updates.
• Where did “Create a Report from MultiROI” go? Into this plugin's Report tab, with everything it did; installing this version removes the old plugin. Its saved settings are not carried over, so hosting account details are entered once more.
• A file got _1 appended: the folder already has that name (or another label uses it). Nothing is ever overwritten; the four NIfTI files are always renamed together.
• The part is 1000× too big in CAD: check the STL Unit. STL carries none — a file written in µm is 1000× too big in a program that assumes mm.
• The table and the options are greyed out during a job: on purpose — while a job runs, every input that decides what is written is locked; they come back when it ends. The log stays readable, and Cancel stops the job.
• The menu entry is missing: make sure the plugin is ticked in the installer / App Store and Dragonfly was fully restarted.

10. Notes & known limitations

• Multi-ROI only (not 2027.1's DenseMultiROI).
• STL: a single-slice (2-D) Multi-ROI cannot be meshed, nor can a sampling that leaves fewer than 3 samples along an axis. The surface follows the voxel boundary, with no sub-voxel grey-level snap (use Multi-ROI to Multi-Mesh (Surface Determination) for that). Windows' 260-character path limit applies.
• NIfTI: one time step per file — no 4-D files, and no NIfTI-2; at most 32767 voxels per axis. Names and colours live only in the three side files (NIfTI itself has no label table); no header extension is written. Voxel 0 at the grid corner is the convention of every other export in this product, but it has not yet been checked by a round trip through Dragonfly's own NIfTI importer.
• Report: screenshots only at time step 0; leave the views alone while they are taken. A temporary link lives until Stop sharing or until Dragonfly quits (closing this window only hides it).
• A multi-time-step (4-D) Multi-ROI can be exported at a chosen time step, but this has not yet been verified with real 4-D data in a running Dragonfly. Do not delete the Multi-ROI during an export; the plugin checks that it still exists and stops with a reason if it does not.

11. References

• The STL format: 3D Systems, StereoLithography Interface Specification (binary and ASCII forms). W. E. Lorensen, H. E. Cline, “Marching Cubes: A High Resolution 3D Surface Construction Algorithm”, SIGGRAPH 1987.
• The NIfTI-1 data format: NIfTI Data Format Working Group, nifti1.h (nifti.nimh.nih.gov); ITK / SimpleITK NIfTI I/O (the RAS / LPS conversion).
• The ITK-SNAP label description format; 3D Slicer colour tables (Colors module, CSV form); the nnU-Net dataset format (dataset.json labels).
• python-pptx 1.0.2 (MIT); openpyxl; matplotlib. Dragonfly Help: exporting an ROI as a mesh (Export as Sampled Mesh), measurements, view layouts.