创建合成图像(Create Synthetic Images)插件用户手册

Create Synthetic Images - User Manual

Dragonfly Prototype Apps · Create Synthetic Images...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

5.1 Generator(生成器)区

5.2 Output size(输出尺寸)区

5.3 Output(输出)区与操作按钮

6. 使用步骤

7. 参数说明

7.1 通用参数(所有生成器共用)

7.2 各生成器参数

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Create Synthetic Images(创建合成图像) 是 Dragonfly 的一个 Prototype Apps 插件,用于生成多种类型的二维 / 三维合成图像数据,并直接以 Channel(通道) 的形式导入当前 Dragonfly 会话。插件内置 26 种生成器,分为六大类:

• 形状与体模(Shapes & Phantoms) — Shepp-Logan 体模、球 / 圆盘、立方体 / 正方形、圆柱体、同心壳体模,共 5 种;
• 噪声(Noise) — 高斯噪声、均匀噪声、椒盐噪声、值噪声分形(fBm),共 4 种;
• 多孔与颗粒(Porous & Particles) — 相关斑点(多孔介质)、重叠球、多分散球、随机球(RSA)、点阵球堆积、纤维 / 圆柱网络,共 6 种;
• 微结构(Microstructure) — Voronoi 晶界、Voronoi 晶粒(标签图)、Sierpinski 泡沫(分形)、随机 Cantor 尘(分形),共 4 种;
• 细胞与斑点(Cells & Blobs) — 二值斑块(细胞)、荧光斑点 / 细胞核,共 2 种;
• 测试图案(Test Patterns) — 渐变、棋盘格、正弦光栅、Siemens 星、同心环,共 5 种。

底层引擎全部是许可宽松的开源库:numpy / scipy(BSD 许可)、scikit-image(BSD 许可,Dragonfly 随附 0.19.3)、PoreSpy(MIT 许可,Dragonfly 随附 2.4.2;Gostick 等 2019,JOSS,doi:10.21105/joss.01296)。分形噪声(fBm)采用插件自带的 numpy + scipy 值噪声实现,不依赖任何额外的噪声库。插件代码对随附版本与更新版本的 porespy / scikit-image 均做了兼容适配。

选择一个生成器并设置其参数,选择二维或三维及输出尺寸,点击 Generate + Import,结果就会作为一个新 Channel 发布到 Dragonfly 中,同时面板内会显示中间切片的灰度预览。二值 / 标签类生成器产生掩码或标签图(可用 LUT 上色),噪声 / 体模 / 图案类生成器产生浮点灰度图。

2. 适用场景

• 算法测试与教学演示 — 用参数可控、结构已知的图像演示或验证滤波、分割、骨架化、可视化等功能;
• 制作已知真值(ground truth)数据 — 为分割 / 测量 / 重建流程生成结构完全可控的测试数据,例如已知孔隙率的多孔介质、已知晶粒数的 Voronoi 标签图、已知半径的球体堆积;
• 在没有真实数据时快速验证工作流 — 拿到新脚本、新 recipe 或新插件时,先用合成数据把流程跑通;
• 成像与显示链路测试 — Siemens 星、正弦光栅、棋盘格、渐变等经典测试图案可用于评估分辨率、插值和窗宽窗位显示效果;
• 可重复实验 — 所有随机生成器都受 Seed(随机种子)控制,同样的参数加同样的种子得到完全相同的图像。

3. 安装与启用

本插件通过 Prototype Labs & Apps Full Package(完整安装包) 安装:

1. 将完整安装包 zip 解压到任意位置(建议较短的路径,如 C:\PL\,避免 Windows 260 字符路径限制);

2. 双击 `Install_FullPackage.bat`;

3. 在弹出的安装对话框中勾选 Create Synthetic Images...(在 Generators & Utilities 分组下)。注意:所有插件默认不勾选,需要手动勾选;

4. 点击 Install,等待控制台安装完成;

5. 完全重启 Dragonfly(彻底退出后重新打开)。菜单只在 Dragonfly 启动时扫描,不重启不会出现新菜单项。

重启后,菜单栏出现 Prototype Apps ▸ Create Synthetic Images...,点击即可打开插件面板(一个可停靠 / 可浮动的窗口)。

以后修改启用状态: 打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部的 "Prototype Apps (Full Package)" 列表中勾选或取消勾选本插件,重启 Dragonfly 生效。也可以随时重新运行安装器(%LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat),上次的选择会作为默认值。卸载整个包用同目录下的 `Uninstall_FullPackage.bat`。

安装全部位于当前用户目录(%LOCALAPPDATA%)下,不需要管理员权限。停用插件不会删除任何已有设置,重新启用立即可用。

4. 运行环境与首次配置

本插件是整个 Prototype Apps 系列中最轻量的插件之一:没有 Setup Environment 步骤,不建虚拟环境,不下载任何内容,点开即用。原因是它需要的全部依赖(numpy、scipy、scikit-image、porespy)都已经随 Dragonfly 2025.1 / 2027.1 一起发布。

• 联网:不需要。 完全离线可用;
• GPU:不需要。 全部生成器在 CPU 上运行;
• WSL / 外部程序:不需要。
• Python 环境: 生成过程作为 Dragonfly 自带 Python(`Python_env\python.exe`)的子进程运行,与 Dragonfly 界面进程隔离,不会因数值库加载而影响 Dragonfly 本身。面板 Engine 一行会显示 Uses Dragonfly's own Python - no setup needed.(使用 Dragonfly 自带 Python,无需配置);
• 临时文件: 每次生成会在系统临时目录下创建一个 synth_ 开头的作业文件夹,存放 config.json、status.json、results.json、生成结果 synth_output.npy 和子进程日志 runner_stdout.log,便于排查问题;
• 配置记忆: 面板会把上次使用的 Channel 名称保存在插件代码目录下的 synth_config.json 中,下次打开自动恢复。

子进程启动时插件会自动重建 Dragonfly 的 DLL 搜索路径,保证 Pillow / porespy 等库能在全新子进程中正常加载,用户无需任何手动设置。

5. 界面说明

面板从上到下依次为:说明文字、Generator(生成器) 区、Output size(输出尺寸) 区、Output(输出) 区、Generate + Import 按钮、预览区、状态行和日志框。所有控件与实际代码一一对应。

5.1 Generator(生成器)区

• 生成器下拉框 — 列出全部 26 种生成器,显示格式为 分组 / 名称(例如 Porous & Particles / Correlated blobs (porous)),按分组和名称排序;
• 说明行(灰色文字) — 显示当前生成器的简介、输出类型(binary / float / label)和参考出处;
• 参数表单(动态) — 随所选生成器自动重建:整数参数为整数微调框,小数参数为 3 位小数的微调框(步长 0.05),枚举参数(如点阵类型、渐变方向)为下拉框。各生成器的具体参数见第 7 章。

5.2 Output size(输出尺寸)区

• Dimensionality(维度) — 2D / 3D 两个单选按钮,默认 3D。可用性随生成器变化:Shepp-Logan 体模和 Siemens 星仅支持 2D;圆柱体和纤维 / 圆柱网络仅支持 3D;其余 22 种同时支持 2D 和 3D;
• Z (slices) — 切片数,范围 1–4096,默认 64;仅在 3D 时可编辑;
• Y — 高度像素数,范围 2–8192,默认 128;
• X — 宽度像素数,范围 2–8192,默认 128;
• Voxel spacing(体素间距) — 范围 0.0001–100000(4 位小数),默认 1.0;同一数值同时应用到 X / Y / Z 三个方向(各向同性);
• Seed(随机种子) — 范围 0–2000000000,默认 0;控制所有随机生成器的可重复性。

5.3 Output(输出)区与操作按钮

• Channel name(通道名称) — 文本框,默认 `Synthetic`;实际生成的 Channel 名为 <通道名称> - <生成器名称>,例如 Synthetic - Correlated blobs (porous)。该名称会被记住,下次打开面板自动填入;
• Engine(引擎)行 — 状态提示:正常显示 Uses Dragonfly's own Python - no setup needed.;若在 Dragonfly 之外运行则显示 Dragonfly Python not found (run inside Dragonfly).;
• Generate + Import 按钮(蓝色) — 开始生成并导入;运行期间按钮禁用,防止重复提交;
• 预览区 — 生成完成后显示结果的中间切片(3D 取 Z 向中间层,2D 直接显示),灰度归一化缩放,初始提示为 Preview (mid-slice) appears here after Generate.;
• 状态行与日志框 — 状态行显示成功(Imported new Channel: ...)或失败原因;只读日志框实时输出进度百分比和子进程消息。

6. 使用步骤

基本流程(适用于全部 26 种生成器):

1. 打开 Prototype Apps ▸ Create Synthetic Images...;

2. 在 Generator 下拉框中选择一个生成器,阅读灰色说明行确认输出类型;

3. 在参数表单中调整该生成器的参数(直接使用默认值也可以得到合理结果);

4. 在 Output size 区选择 2D 或 3D(部分生成器会自动锁定),设置 X / Y(以及 3D 时的 Z)尺寸;首次尝试建议保持默认的 128×128×64,确认效果后再放大;

5. 按需设置 Voxel spacing(生成的 Channel 的体素间距)和 Seed(想要可重复结果时固定一个种子;换个种子可得到同一结构的另一次随机实现);

6. 在 Channel name 中输入名称前缀(默认 Synthetic);

7. 点击 Generate + Import。日志框会显示 === Generate '<生成器>' (尺寸) === 以及进度(10% 生成中、85% 写出结果);

8. 完成后,状态行显示 Imported new Channel: <名称> (形状),面板中出现中间切片预览,同时新 Channel 已发布到 Dragonfly 的数据列表中,可直接在 2D / 3D 视图中查看。

示例 A — 为分割算法生成已知孔隙率的三维多孔介质: 选择 Porous & Particles / Correlated blobs (porous),设 Porosity=0.5、Blobiness=1,选 3D、128×128×64,点 Generate + Import;得到的二值 Channel 中孔隙率约为设定值,可用于验证阈值分割和孔隙率测量流程。

示例 B — 生成晶粒真值标签图: 选择 Microstructure / Voronoi grains (label map),设 Number of grains=40;输出为每个晶粒一个整数标签(1–40)的标签图,可作为晶粒统计算法的真值。

示例 C — 生成分辨率测试卡: 选择 Test Patterns / Siemens star(仅 2D),设 Spokes=36,输出经典的星形分辨率测试图,用于评估重采样和显示效果。

生成在后台线程和子进程中运行,期间可以继续使用 Dragonfly;单次生成最长运行 30 分钟,超时会自动终止并报 processing timed out。关闭面板会终止正在运行的生成任务。

7. 参数说明

本章列出面板通用参数和全部 26 种生成器的专有参数。表中默认值与界面完全一致。

7.1 通用参数(所有生成器共用)

7.2 各生成器参数

形状与体模(Shapes & Phantoms)

噪声(Noise)

多孔与颗粒(Porous & Particles)

微结构(Microstructure)

细胞与斑点(Cells & Blobs)

测试图案(Test Patterns)

8. 输出结果

每次生成产生 一个新的 Dragonfly Channel,自动发布到当前会话的数据列表中:

• 名称 — <Channel name> - <生成器名称>,例如 Synthetic - Checkerboard;
• 数据类型 — 统一为 32 位浮点(float32)。二值生成器的前景值为 255、背景为 0;标签图(Voronoi grains)的取值为 1 到晶粒数的整数标签;噪声 / 体模 / 图案类为连续浮点值(多数在 0–1 区间);
• 几何 — 体素间距取面板中的 Voxel spacing(三向同值),原点为 (0,0,0);2D 结果作为单切片(Z=1)的 Channel 导入;
• 查看方式 — 在 Dragonfly 数据列表中像普通 Channel 一样操作:拖入 2D / 3D 视图、调窗宽窗位、套 LUT(对二值 / 标签图尤其建议用 LUT 上色)、做渲染或后续分割 / 测量。

面板内还提供中间切片灰度预览(自动归一化到显示范围),以及日志框中的 vmin / vmax 等信息(写在作业文件夹的 results.json 中)。生成的中间文件(synth_output.npy 等)保存在系统临时目录的 synth_ 作业文件夹中,不影响 Dragonfly 项目;需要时可手动清理临时目录。

如果需要把二值结果变成 ROI 进行后续处理,可在 Dragonfly 中对该 Channel 做阈值分割(前景值为 255,阈值取任意 0–255 之间的值即可)。

9. 常见问题与故障排除

问 1:菜单里找不到 Prototype Apps ▸ Create Synthetic Images...?

答:先确认安装时勾选了本插件(安装器中所有插件默认不勾选),再确认安装后完全重启过 Dragonfly(菜单只在启动时扫描)。也可打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager 检查本插件是否勾选,修改后重启生效。

问 2:Engine 一行显示 `Dragonfly Python not found (run inside Dragonfly).`,点 Generate 报 `could not locate Dragonfly's Python`?

答:说明面板不是在 Dragonfly 内部运行,或者当前环境无法定位 Dragonfly 自带的 Python_env\python.exe。本插件必须作为 Dragonfly 菜单项在 Dragonfly 内使用,请从 Prototype Apps 菜单打开。

问 3:生成失败,如何查原因?

答:失败时状态行显示 Failed: <原因>,日志框会打印子进程的错误分类、消息和回溯(traceback)。更多细节可查看临时目录下 synth_ 作业文件夹中的 runner_stdout.log 与 status.json。常见原因是尺寸设得过大导致内存不足——先降低 X / Y / Z 再试。

问 4:大尺寸 3D 生成很慢,甚至报 `processing timed out`?

答:单次生成的时间上限是 30 分钟,超时自动终止。porespy 类生成器(如多分散球、纤维网络)在大体积下计算量较大;建议先用 128×128×64 这类中等尺寸验证参数,再逐步放大。内存占用约为 每体素 4 字节(float32),例如 1024³ 体积约需 4 GB,请量力设置。

问 5:同样的参数,两次生成的结果不一样?

答:检查 Seed 是否一致。所有随机生成器(噪声、斑点、球堆积、Voronoi、Cantor 尘等)都由 Seed 决定,同参数 + 同种子 + 同尺寸的结果逐像素一致;确定性图案(棋盘、渐变、Siemens 星等)与种子无关。

问 6:生成的二值图在视图里看起来一片黑或一片白?

答:二值结果的取值只有 0 和 255,请在 Dragonfly 中调整窗宽窗位,或直接套一个 LUT 上色;标签图(Voronoi grains)建议使用彩色 LUT 区分晶粒。

问 7:Sierpinski 泡沫把 Iterations 调大后图像没有变得更细?

答:Dragonfly 随附的 porespy 2.4.2 版本下,该生成器 2D 最多生效 6 次迭代、3D 最多 4 次(结果再重采样到请求的尺寸);这是随附库版本的限制,更高迭代数不会报错但不再增加细节。

10. 注意事项与已知限制

• 输出统一为 float32 Channel:二值结果以 0 / 255 表示,标签图以整数值浮点存储;插件不直接生成 ROI / MultiROI 对象,需要时请对结果做阈值分割;
• 体素间距为各向同性(一个数值同时用于 X / Y / Z),不支持逐轴设置;原点固定为 (0,0,0);
• 2D 结果以单切片 Channel 导入(Z=1);
• 面板没有单独的取消按钮:生成运行期间 Generate 按钮禁用,任务在完成、30 分钟超时或关闭面板时结束(关闭面板会终止子进程);
• 界面允许的最大尺寸(8192×8192×4096)远超常规内存承受能力,请根据机器内存合理设置(float32 每体素 4 字节);
• porespy 版本差异:插件已对随附的 porespy 2.4.2 与更新版本做了参数适配,个别生成器(Sierpinski 泡沫、Cantor 尘)在 2.4.2 下先按库允许的网格生成、再重采样到请求尺寸,边缘可能有轻微插值痕迹;
• 生成的中间 .npy 文件留在系统临时目录中,由操作系统的临时文件机制清理;不会写入 Dragonfly 项目文件夹。

11. 参考资料

• PoreSpy(MIT 许可)— 多孔介质与颗粒类生成器引擎:https://porespy.org ;引文:Gostick et al., 2019, Journal of Open Source Software, doi:10.21105/joss.01296;
• scikit-image(BSD 许可)— Shepp-Logan 体模与二值斑块:https://scikit-image.org ;
• numpy / scipy(BSD 许可)— 形状、图案、Voronoi 晶粒、荧光斑点与 fBm 分形噪声;
• Shepp, L.A. & Logan, B.F., 1974 — Shepp-Logan CT 体模的原始出处。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation and Enabling

4. Runtime Environment and First-Run Setup

5. User Interface

5.1 Generator group

5.2 Output size group

5.3 Output group and actions

6. Step-by-Step Usage

7. Parameter Reference

7.1 Shared parameters (all generators)

7.2 Per-generator parameters

8. Output

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

1. Overview

Create Synthetic Images is a Dragonfly Prototype Apps plugin that generates many kinds of synthetic 2D / 3D image data and imports them straight into the current Dragonfly session as Channels. It ships 26 generators organised into six families:

• Shapes & Phantoms — Shepp-Logan phantom, sphere / disk, cube / square, cylinder, concentric-shells phantom (5 generators);
• Noise — Gaussian, uniform, salt & pepper, value-noise fractal (fBm) (4 generators);
• Porous & Particles — correlated blobs (porous), overlapping spheres, polydisperse spheres, random spheres (RSA), lattice sphere packings, fiber / cylinder networks (6 generators);
• Microstructure — Voronoi grain edges, Voronoi grains (label map), Sierpinski foam (fractal), random Cantor dust (fractal) (4 generators);
• Cells & Blobs — binary blobs (cells), fluorescence spots / nuclei (2 generators);
• Test Patterns — gradient ramp, checkerboard, sinusoidal grating, Siemens star, concentric rings (5 generators).

All engines are permissively licensed open source: numpy / scipy (BSD), scikit-image (BSD; Dragonfly bundles 0.19.3) and PoreSpy (MIT; Dragonfly bundles 2.4.2; Gostick et al. 2019, JOSS, doi:10.21105/joss.01296). The fractal (fBm) noise is a self-contained numpy + scipy value-noise implementation, so no extra noise library is required. The plugin code is written to work with both the bundled and newer releases of porespy / scikit-image.

Pick a generator and its parameters, choose 2D or 3D and the output size, click Generate + Import, and the result is published as a new Channel while a mid-slice grayscale preview appears in the panel. Binary / label generators produce a mask or label map (colour it with a LUT); noise / phantom / pattern generators produce a float grayscale image.

2. Use Cases

• Algorithm testing and teaching demos — demonstrate or validate filtering, segmentation, skeletonisation, visualisation and other features on images with fully known, parameter-controlled structure;
• Producing known ground truth — generate test data with exactly controlled structure for segmentation / measurement / reconstruction pipelines, e.g. porous media with a known porosity, Voronoi label maps with a known grain count, sphere packings with a known radius;
• Quickly validating a workflow when no real data is at hand — smoke-test a new script, recipe or plugin on synthetic data first;
• Imaging and display chain tests — classic targets such as the Siemens star, sinusoidal gratings, checkerboards and gradients help evaluate resolution, interpolation and window-levelling;
• Reproducible experiments — every random generator is driven by the Seed; identical parameters plus an identical seed give an identical image.

3. Installation and Enabling

The plugin is installed via the Prototype Labs & Apps Full Package:

1. Unzip the Full Package anywhere (prefer a short path such as C:\PL\ to avoid the Windows 260-character path limit);

2. Double-click `Install_FullPackage.bat`;

3. In the installer dialog, tick Create Synthetic Images... (under the Generators & Utilities group). Note: all plugins are unticked by default — you must tick it;

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

5. Fully restart Dragonfly (quit completely, then reopen). Menus are only discovered at Dragonfly startup.

After the restart, the menu bar shows Prototype Apps ▸ Create Synthetic Images...; clicking it opens the plugin panel (a dockable / floatable window).

Changing your choice later: open Developer ▸ Prototype Labs... ▸ Menu Item Manager — the "Prototype Apps (Full Package)" list at the bottom has a checkbox per app; tick / untick this plugin and restart Dragonfly to apply. You can also re-run the installer at any time (%LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat); your previous choices become the new defaults. To uninstall the whole package, use `Uninstall_FullPackage.bat` from the same folder.

Everything installs per-user under %LOCALAPPDATA%; no administrator rights are needed. Disabling the plugin never deletes any settings — re-enabling is instant.

4. Runtime Environment and First-Run Setup

This is one of the lightest plugins in the whole Prototype Apps line: there is no Setup Environment step, no virtual environment, and nothing to download — just click and go. Every dependency it needs (numpy, scipy, scikit-image, porespy) already ships with Dragonfly 2025.1 / 2027.1.

• Internet: not required. Fully usable offline;
• GPU: not required. All generators run on the CPU;
• WSL / external applications: not required.
• Python environment: generation runs as a subprocess of Dragonfly's own bundled Python (`Python_env\python.exe`), isolated from the Dragonfly UI process so heavy numeric libraries never destabilise Dragonfly itself. The panel's Engine row shows Uses Dragonfly's own Python - no setup needed.;
• Temporary files: each run creates a job folder starting with synth_ in the system temp directory, holding config.json, status.json, results.json, the generated synth_output.npy and the subprocess log runner_stdout.log — useful for troubleshooting;
• Remembered settings: the panel stores the last-used Channel name in synth_config.json next to the plugin code and restores it on the next open.

When the subprocess starts, the plugin automatically re-creates Dragonfly's DLL search path so that Pillow / porespy load correctly in the fresh process — no manual configuration is ever needed.

5. User Interface

From top to bottom the panel shows: an intro text, the Generator group, the Output size group, the Output group, the Generate + Import button, the preview area, a status line and a log box. Every control below matches the actual code.

5.1 Generator group

• Generator combo box — lists all 26 generators as Family / Name (e.g. Porous & Particles / Correlated blobs (porous)), sorted by family and name;
• Description line (gray text) — shows the current generator's description, output type (binary / float / label) and reference;
• Parameter form (dynamic) — rebuilt whenever the generator changes: integer parameters use integer spin boxes, real parameters use 3-decimal spin boxes (step 0.05), and enumerated parameters (e.g. lattice type, gradient axis) use drop-downs. See Chapter 7 for every parameter.

5.2 Output size group

• Dimensionality — 2D / 3D radio buttons, default 3D. Availability follows the generator: the Shepp-Logan phantom and Siemens star are 2D-only; the cylinder and the fiber / cylinder network are 3D-only; the other 22 generators support both;
• Z (slices) — number of slices, range 1–4096, default 64; editable only in 3D mode;
• Y — image height in pixels, range 2–8192, default 128;
• X — image width in pixels, range 2–8192, default 128;
• Voxel spacing — range 0.0001–100000 (4 decimals), default 1.0; the same value is applied to X, Y and Z (isotropic);
• Seed — range 0–2000000000, default 0; controls the reproducibility of every random generator.

5.3 Output group and actions

• Channel name — text field, default `Synthetic`; the created Channel is named <Channel name> - <generator name>, e.g. Synthetic - Correlated blobs (porous). The name is remembered across sessions;
• Engine row — status hint: normally Uses Dragonfly's own Python - no setup needed.; if run outside Dragonfly it shows Dragonfly Python not found (run inside Dragonfly).;
• Generate + Import button (blue) — starts generation and import; disabled while a job is running to prevent double submission;
• Preview area — after generation shows the result's middle slice (mid-Z slice for 3D, the image itself for 2D), grayscale-normalised; the initial placeholder reads Preview (mid-slice) appears here after Generate.;
• Status line and log box — the status line reports success (Imported new Channel: ...) or the failure reason; the read-only log box streams progress percentages and subprocess messages.

6. Step-by-Step Usage

Basic workflow (applies to all 26 generators):

1. Open Prototype Apps ▸ Create Synthetic Images...;

2. Pick a generator in the Generator combo and read the gray description line to confirm the output type;

3. Adjust the generator's parameters in the form (the defaults already give sensible results);

4. In Output size, choose 2D or 3D (some generators lock the choice) and set X / Y (plus Z in 3D). For a first try keep the default 128×128×64, then scale up once you are happy;

5. Optionally set Voxel spacing (the spacing of the resulting Channel) and Seed (fix a seed for reproducible results; change it for another random realisation of the same structure);

6. Enter a name prefix in Channel name (default Synthetic);

7. Click Generate + Import. The log shows === Generate '<generator>' (shape) === plus progress messages (10% generating, 85% writing output);

8. When finished, the status line shows Imported new Channel: <name> (shape), the mid-slice preview appears in the panel, and the new Channel is already published in Dragonfly's data list — drop it into any 2D / 3D view.

Example A — a 3D porous medium with known porosity for segmentation testing: choose Porous & Particles / Correlated blobs (porous), set Porosity=0.5 and Blobiness=1, pick 3D at 128×128×64, click Generate + Import; the binary Channel has approximately the requested porosity and validates threshold-segmentation and porosity-measurement pipelines.

Example B — a ground-truth grain label map: choose Microstructure / Voronoi grains (label map) and set Number of grains=40; the output assigns one integer label (1–40) per grain, ideal as ground truth for grain statistics.

Example C — a resolution test target: choose Test Patterns / Siemens star (2D only) with Spokes=36 to get the classic star target for evaluating resampling and display.

Generation runs in a background thread and subprocess, so Dragonfly stays usable meanwhile. A single run is limited to 30 minutes, after which it is terminated with a 'processing timed out' error. Closing the panel terminates a running job.

7. Parameter Reference

This chapter lists the shared panel parameters and the specific parameters of all 26 generators. Defaults match the UI exactly.

7.1 Shared parameters (all generators)

7.2 Per-generator parameters

Shapes & Phantoms

Noise

Porous & Particles

Microstructure

Cells & Blobs

Test Patterns

8. Output

Each run produces one new Dragonfly Channel, published automatically into the current session's data list:

• Name — <Channel name> - <generator name>, e.g. Synthetic - Checkerboard;
• Data type — always 32-bit float (float32). Binary generators use 255 for foreground and 0 for background; the label map (Voronoi grains) uses integer labels 1..N; noise / phantom / pattern generators produce continuous float values (mostly in 0–1);
• Geometry — the voxel spacing is the panel's Voxel spacing value (same on all axes), origin (0,0,0); 2D results are imported as a single-slice (Z=1) Channel;
• Viewing — treat it like any Channel in Dragonfly: drop it into 2D / 3D views, adjust window levelling, apply a LUT (recommended for binary / label results), render it, or feed it into segmentation / measurement workflows.

The panel additionally shows a mid-slice grayscale preview (auto-normalised for display), and the log reports details such as vmin / vmax (also written to results.json in the job folder). Intermediate files (synth_output.npy etc.) stay in the synth_ job folder in the system temp directory and never touch the Dragonfly project; clean the temp directory manually if desired.

To turn a binary result into an ROI for further processing, threshold the Channel in Dragonfly (foreground is 255, so any threshold between 0 and 255 works).

9. FAQ and Troubleshooting

Q1: I cannot find Prototype Apps ▸ Create Synthetic Images... in the menu.

A: Confirm the plugin was ticked during installation (all plugins are unticked by default), and that Dragonfly was fully restarted afterwards (menus are only scanned at startup). You can also open Developer ▸ Prototype Labs... ▸ Menu Item Manager, tick this plugin, and restart.

Q2: The Engine row says `Dragonfly Python not found (run inside Dragonfly).` and Generate reports `could not locate Dragonfly's Python`.

A: The panel is not running inside Dragonfly, or Dragonfly's bundled Python_env\python.exe could not be resolved. The plugin must be used as a Dragonfly menu item — open it from the Prototype Apps menu.

Q3: Generation failed — how do I find out why?

A: On failure the status line shows Failed: <reason> and the log box prints the subprocess's error category, message and traceback. For more detail, inspect runner_stdout.log and status.json inside the synth_ job folder in the system temp directory. The most common cause is an output size too large for the available memory — reduce X / Y / Z and retry.

Q4: Large 3D generation is slow or ends with `processing timed out`.

A: A single run is capped at 30 minutes, after which it is terminated. The porespy-based generators (e.g. polydisperse spheres, fiber networks) are computationally heavy at large volumes; validate parameters at a moderate size such as 128×128×64 first, then scale up. Memory use is about 4 bytes per voxel (float32) — a 1024³ volume needs roughly 4 GB — so size accordingly.

Q5: The same parameters give different results on two runs.

A: Check that the Seed is the same. All random generators (noise, spots, sphere packings, Voronoi, Cantor dust, ...) are driven by the seed; identical parameters + seed + size give a pixel-identical result. Deterministic patterns (checkerboard, gradient, Siemens star, ...) ignore the seed.

Q6: A binary result looks all black or all white in the view.

A: Binary outputs contain only the values 0 and 255 — adjust the window levelling or apply a LUT. For the label map (Voronoi grains) a colour LUT is recommended to distinguish grains.

Q7: Increasing Iterations for the Sierpinski foam does not make the image finer.

A: With the porespy 2.4.2 bundled in Dragonfly, this generator effectively supports at most 6 iterations in 2D and 4 in 3D (the result is then resampled to the requested size). Higher values do not fail, but add no further detail — this is a limitation of the bundled library version.

10. Notes and Known Limitations

• Output is always a float32 Channel: binary results are stored as 0 / 255, label maps as integer-valued floats; the plugin does not create ROI / MultiROI objects directly — threshold the result if you need one;
• Voxel spacing is isotropic (one value for X / Y / Z); per-axis spacing is not supported, and the origin is fixed at (0,0,0);
• 2D results are imported as single-slice Channels (Z=1);
• The panel has no dedicated cancel button: the Generate button is disabled while a job runs, and a job ends when it finishes, hits the 30-minute timeout, or the panel is closed (closing terminates the subprocess);
• The UI allows sizes up to 8192×8192×4096, far beyond typical memory — choose sizes to match your machine (4 bytes per voxel, float32);
• porespy version differences: the plugin adapts its calls to both the bundled porespy 2.4.2 and newer releases; a few generators (Sierpinski foam, Cantor dust) may generate on a library-preferred grid first and resample to the requested size under 2.4.2, which can leave slight interpolation marks at block edges;
• Intermediate .npy files remain in the system temp directory and are cleaned up by the operating system's temp mechanisms; nothing is written into the Dragonfly project folder.

11. References

• PoreSpy (MIT licence) — engine for the porous-media and particle generators: https://porespy.org ; citation: Gostick et al., 2019, Journal of Open Source Software, doi:10.21105/joss.01296;
• scikit-image (BSD licence) — Shepp-Logan phantom and binary blobs: https://scikit-image.org ;
• numpy / scipy (BSD licence) — shapes, patterns, Voronoi grains, fluorescence spots and the fBm fractal noise;
• Shepp, L.A. & Logan, B.F., 1974 — original publication of the Shepp-Logan CT phantom.