Synthetic RVE Builder（合成代表体元生成器）
Synthetic RVE Builder - User Manual
Dragonfly Prototype Apps · Synthetic RVE Builder...
版本 Version 1.0 · 2026-08-02
第一部分 中文手册
目录
1. 简介
2. 适用场景
3. 安装与启用
4. 运行环境与首次配置
5. 界面说明
6. 使用步骤
7. 参数说明
8. 输出结果
9. 常见问题与故障排除
10. 注意事项与已知限制
11. 参考资料
1. 简介
生成人工的三维微观结构，用于仿真输入、方法验证或补充训练数据。两条路径：参数化生成——什么都不需要先发布，结构完全由第 3 步的参数造出；以及样本约束合成——由一张已发布的二维切片的统计量去约束一个三维体。
本插件只负责「造」，不负责「量」。 要测量一个结构——体积分数、界面面积、三相界线、代表尺寸是否收敛——请用 Microstructure Statistics & RVE，包括测量这里刚生成出来的体数据。两者刻意分开：分析必须有输入而几乎不发布，生成通常没有输入，而存在的意义就是发布。
一张二维切片只能约束它自己那个平面。 只有当介质沿第三个方向统计各向同性时，它才足以确定一个三维体。因此插件会先测出示例自身各轴向的相关长度，比值超过阈值（默认 1.20）时给出醒目告警，并默认自动切换到各向异性模式——在层状或纤维状材料上跑各向同性模式，会把各向异性抹平，同时仍然报出一个很好看的径向 S2 误差。面外方向究竟按哪个轴取值，永远写进结果与告警里。
v1 的样本合成只有高斯随机场一种方法。 模拟退火（Yeong–Torquato）与基于图块的多点合成被刻意砍掉：本机实测，300 立方的体数据高斯随机场约 2 秒，而这两条路分别需要 4–20 小时与 21.7 小时，而高斯随机场本身已经落在它们所优化目标的百分之几以内。代码里没有为它们留任何钩子——它们不是「以后再接」，而是没有实现。
能复现的地方逐位复现，做不到的地方如实说出来。 同一个种子给出逐位相同的体数据，种子与全部参数随结果一起写入溯源记录；随机顺序添加会检测到堵塞并报出实际达到的体积分数，而不是无限重试；当要求的相关函数在物理上不可实现时，被裁掉的谱能量会作为一个数字报出来，而不是悄悄吸收掉。
2. 适用场景
- 为有限元或格子玻尔兹曼仿真造一个统计特征完全受控的输入结构。
- 在答案事先已知的合成结构上验证一条测量流程。
- 由少量真实二维切片扩充三维训练数据。
- 研究某一个参数——孔隙率、纤维长径比、喉道半径分布、粗糙度——如何传递到下游计算结果。
- 造一个真正周期的代表体元：三个方向的周期性可分别开关，可直接用于周期性边界条件。
3. 安装与启用
1. 安装 Prototype Apps 完整包（或在 App Store 中勾选本插件）。
2. 本插件默认未启用，请在 App Store 或菜单项管理器中启用。
3. 完全重启 Dragonfly（插件只在启动时被发现）。菜单位置：Prototype Apps ▸ Generators & Utilities ▸ Synthetic RVE Builder…
4. 运行环境与首次配置
无需任何安装或配置。 完全运行在 Dragonfly 自带的 Python 中，使用其已附带的 NumPy 与 SciPy。不联网、不下载、不需要 GPU、不创建虚拟环境。
面板顶部会显示当前 Dragonfly 版本能否发布通道、能否发布 MultiROI。做不到的操作会直接置灰，而不是让你点下去再报错；即使一样都发布不了，导出依然可用。第 2 步还会给出本次网格的体素数、物理盒子尺寸与峰值工作内存估计——实测：谱方法在 300 立方约 0.7 GB、512 立方约 3.4 GB，且这是在 Dragonfly 已占内存之外的额外量。那是数量级参考，不是承诺。
5. 界面说明
1. 输入
先选模式。参数化（无需输入）：只需在「结构族」里选一种——椭球 / 纤维 / 管网 / 粗糙表面 / 裂隙开度——不必先发布任何对象；可另选一个基体通道用于发布时的合成，并用「采用该对象的网格」一键把它的形状、体素尺寸与 origin 抄到第 2 步。示例约束（需要一张二维切片）：选示例通道、平面（XY / XZ / YZ）、切片序号与时间步。所有下拉框只列出已发布的对象，底部显示形状、三轴间距、origin 与时间步数。
2. 标定与预处理
「输出网格」定义要造的东西：三个方向的体素数、体素尺寸（界面用微米，核心一律用毫米，只在收集参数时换算一次）与 origin（毫米）。下面一行给出体素数、物理盒子尺寸与峰值内存估计；体素各向异性时会给出提示——所有几何判断都在毫米空间完成，各向异性网格上的球在体素里就是椭球。示例模式下这一步还负责二值化（Otsu 自动或手动阈值，加极性）与按行、列范围裁剪，并提供「测量示例」按钮：先看清示例的体积分数、阈值、各轴向衰减长度与各向异性比值，再决定合成什么。
3. 参数
上半部分是对两条路径都生效的通用设置：沿 Z / Y / X 的周期性（逐轴独立）、相标签、相名称、随机种子，以及「同时测量弦长与界面取向（较慢）」。下半部分随第 1 步的选择切换成一页：五个参数化结构族各一页，示例约束合成一页。任何一个参数改动都会立即作废上一次结果并禁用导出与发布——一张不再描述内存中体数据的结果表，比一张空表更糟。
4. 预览与质检
在同一个物理盒子内、以相同的种子在更粗的网格上生成一遍（最长边默认不超过 96 体素，抽稀后任一方向不小于 12 体素），给出中间切片图、S2 对照图与指标表。对这些解析生成器而言，草稿就是同一结构的粗采样，而不是它的一角——这一点让本插件的预览比抽稀后的测量诚实得多；但比草稿体素更细的特征不会出现在里面。预览不发布任何对象，也不启用导出按钮。
5. 运行
先复述一遍本次计划（模式、结构族或合成方法、平面、体素数、随机种子、哪几个方向周期）与预计代价，然后全尺寸生成，随时可取消。运行同样不发布任何对象，完成后自动跳到第 6 步。
6. 结果与导出
上方是中间切片图与 S2 对照图：目标 S2 与实际达到的 S2 画在同一坐标上，近场（前 3 个径向分箱）加底纹标出，因为那正是取阈层次的高斯场系统性偏离的地方，也正是比表面所在的地方。下面一行是匹配状态——目标已复现 / 目标不可实现 / 近场未复现 / 无可比对的目标——并始终附带一句「这是统计上合理的结构，而不是用户自己的结构」。再往下是指标表（分组 / 名称 / 请求值 / 实际值 / 单位 / 说明）、各向异性说明与全部告警，最后是两个发布按钮与五个导出按钮（网络图 CSV 仅在管网时可用）。
分享报告
第七个标签页 分享报告 不是流程步骤，它只把已生成的报告临时发布到互联网，不做任何计算。它通过 Cloudflare 临时快速隧道，直接从本机提供刚生成的报告，并返回一个临时的公网地址；不上传任何数据，也不需要账号，而报告页面本身就带着您的图像数据。该地址不是立刻可用的：隧道建立之后大约还要 40 秒它才开始响应（本机实测：一次为 45 秒，另有两次始终没能解析），所以状态转绿之前不要把链接发出去。分享期间，拿到链接的任何人都能读取报告，没有密码。点击停止分享、关闭窗口或退出 Dragonfly 后，该地址立即失效且永不重发。只有在本机确认地址已可访问、或明确告知无法确认时，才会把链接交给您。
6. 使用步骤
1. 第 1 步选模式：参数化就直接选结构族；示例约束则选一张已发布的切片。
2. 第 2 步定输出网格：体素数、体素尺寸与 origin；示例模式再确认阈值与极性，并点「测量示例」看清它的体积分数与各向异性。
3. 第 3 步填参数：先设周期性、相标签与随机种子，再填所选结构族或合成方法自己那一页。
4. 第 4 步先跑预览，确认形态合理、实际达到的体积分数接近目标、S2 对得上、没有大量告警。
5. 第 5 步全尺寸生成。
6. 第 6 步看匹配状态与指标表，然后发布为通道或 MultiROI，并导出 CSV / HTML / JSON 溯源记录。
7. 参数说明
输出网格与通用设置
参数 | 默认值 | 说明 |
尺寸 Z / Y / X（体素） | 128 | 范围 8–4096，三轴独立；单次网格上限 2^30 体素 |
体素尺寸 Z / Y / X（um） | 1.0 | 界面用微米，核心一律用毫米，只在收集参数时换算一次 |
原点 Z / Y / X（mm） | 0 | 发布时写入对象；当前 Dragonfly 版本写不进去会在发布信息里明确告警 |
沿 Z / Y / X 周期 | 三个都开启 | 逐轴独立；粗糙表面与裂隙是高度场，无法沿自身厚度方向周期，Z 会被忽略并告警 |
相标签 | 1 | 1–255，写入体数据的标签值 |
相名称 | Structure | 发布时的对象名与 MultiROI 标签名 |
随机种子 | 0 | 同一种子逐位可复现；比特发生器为 PCG64，并写入溯源记录 |
同时测量弦长与界面取向（较慢） | 开启 | 关闭后仍给出体积分数与两点相关；预览始终跳过这两项 |
预览最大边长（体素） | 96 | 范围 16–160；抽稀后任一方向不小于 12 体素 |
椭球
参数 | 默认值 | 说明 |
目标体积分数（0 表示按数量） | 0.3 | 0–0.95；可穿透模型按 phi = 1 − exp(−n·v/V) 一步反解个数，不做试错 |
个数（0 表示按体积分数） | 0 | 与目标体积分数二者只能给一个 |
等效球径 d50（um） | 20 | 对数正态分布的中位数 |
尺寸变异系数 | 0.2 | 0–3 |
长宽比 a/b | 1.0 | 1 与 1 即为球；体积对长宽比不变，改形状不会改掉已定的体积分数 |
长宽比 b/c | 1.0 | 同上 |
长宽比变异系数 | 0.0 | 0–3 |
取向 | 各向同性 | 另有完全对齐、绕轴分布（von Mises–Fisher）、锥内均匀 |
集中度 kappa | 0 | 仅「绕轴分布」有效，越大越集中 |
择优轴 | Z | 「完全对齐」「绕轴分布」「锥内均匀」的参考轴 |
锥半角（度） | 90 | 0.1–90，仅「锥内均匀」有效 |
重叠策略 | 可穿透（自由重叠） | 另有硬核（不重叠）、硬核并保持间隙、先放置后推开 |
间隙（um） | 0 | 仅「硬核并保持间隙」有效，是表面到表面的距离 |
尝试次数上限 | 200000 | 硬核放置用尽预算即判定堵塞，并如实报出实际达到的体积分数 |
亚采样（部分体积） | 1 | 1–4；在 k 倍细网格上栅格化、覆盖率达到一半才算入，代价按 k 的立方增长；覆盖率同时作为部分体积估计报出 |
纤维
参数 | 默认值 | 说明 |
目标体积分数（0 表示按数量） | 0.15 | 0–0.95 |
个数（0 表示按体积分数） | 0 | 与目标体积分数二者只能给一个 |
纤维半径（um） | 5.0 | 对数正态中位数；纤维画成球扫掠折线 |
半径变异系数 | 0.0 | 0–3 |
纤维长度（um，0 表示贯穿整盒） | 0（贯穿） | 默认取最长的域边长，因此纤维贯穿整盒；这一点会写进告警 |
长度变异系数 | 0.0 | 0–3 |
波状纤维 | 关闭 | 打开后按持久长度生成蠕虫状链 |
持久长度（um） | 200 | 每一步按精确的 von Mises–Fisher 转角抽样，使 ⟨cos θ⟩ = exp(−Δs/ℓp) 在任意步长下成立；小角近似在 Δs/ℓp = 0.67 时把端到端距离高估 34%，故不采用。实测的弯曲度与端到端距离会与精确离散链理论值并列给出 |
沿纤维步长（um，0 表示自动） | 0（自动） | 自动取持久长度的十六分之一，且不超过纤维长度的八分之一 |
取向 / 集中度 kappa / 择优轴 / 锥半角 | 各向同性 / 0 / Z / 90 | 含义与椭球完全相同 |
重叠策略 | 可穿透（自由重叠） | 纤维不支持「先放置后推开」，选了会直接报错说明原因 |
间隙（um） / 尝试次数上限 / 亚采样 | 0 / 200000 / 1 | 含义与椭球完全相同 |
管网
参数 | 默认值 | 说明 |
拓扑 | Voronoi 棱 | 另有 Delaunay 棱与立方点阵 |
种子点数 | 120 | 不少于 4；棱数为 0 会报错并提示提高种子点数 |
平均配位数（0 表示保留全部棱） | 0 | 修剪前先保护一棵生成树，所以按配位数减薄不会把网络打散 |
喉道半径（um） | 8.0 | 对数正态中位数 |
喉道半径变异系数 | 0.3 | 0–3 |
孔半径（um，0 表示由喉道推得） | 0 | 节点球半径；留 0 则由相邻喉道推得 |
孔半径倍数 | 1.3 | 1–5，节点球相对相邻喉道的放大倍数 |
目标体积分数（0 表示关闭） | 0（关闭） | 本模块唯一不能一步到位的地方，原因是物理的：管体互相共用节点球，不是独立放置，可穿透关系不成立。半径倍数先按实际画出的体积解析求解，再用有上限的若干次实测栅格化修正——是确定的有界序列，不是重试循环 |
体积分数迭代次数 | 3 | 0–10；两三次即可落在 2% 内；设为 1 就只保留解析解加一次栅格化 |
仅保留最大连通网络 | 关闭 | 在周期轴上可能丢掉某个节点的周期镜像，从而不再严格平铺，此时会告警 |
仅保留贯通团簇 | 关闭 | 需要同时指定贯通方向 |
贯通方向 | Z | 贯通性是在栅格化之后实测的，不是由图的连通性推定的 |
亚采样（部分体积） | 1 | 1–4，含义与椭球相同 |
粗糙表面与裂隙开度
参数 | 默认值 | 说明 |
目标体积分数（粗糙表面） | 0.5 | 0.01–0.99；按连续固体深度解析求解平均面高度，不做栅格化重试 |
Hurst 指数 | 0.8 | 0.05–0.99；功率谱按 q 的 −(2H+2) 次幂，即二维自仿射形式 |
粗糙度 Rq（um） | 5.0（粗糙表面）/ 3.0（裂隙） | 高度场整体缩放，Rq 精确命中目标值 |
转折波长（um，0 表示关闭） | 0（关闭） | 超过此波长谱变平——真实表面在自身相关长度之外并不分形 |
小尺度截止（um，0 表示关闭） | 0（关闭） | 短波长上限 |
纹理方向 Y / X | 1.0 / 1.0 | 逐轴的相关长度倍数：6.0 表示该方向上的特征长六倍，因此该方向更平滑 |
平均开度（um，裂隙） | 12.0 | 两壁之差的均值；夹掉接触处会必然抬高实际均值，故请求值与实际值分开报出 |
失配长度（um，0 表示自动） | 0（自动取平面短边的四分之一） | 超过失配波长的部分两壁同源——像劈开的岩石在长波长上是吻合的——以下相互独立；因此失配长度越长，开度越粗糙 |
允许两壁接触 | 开启 | 关闭时整体抬升开度使两壁不接触，并报出抬升量与新的平均开度 |
上壁标签（0 表示与下壁相同） | 2 | 0–255；开度本身始终是标签 0 |
示例约束合成
参数 | 默认值 | 说明 |
阈值方法 | Otsu（自动） | 另一选项为手动阈值；自动选出的阈值会写进告警 |
极性 | 相位于阈值之上 | 另一选项为相位于阈值之下 |
裁剪示例 | 关闭 | 按行、列范围裁剪；越界会被夹到全幅并告警 |
合成方法 | 高斯随机场（各向同性） | 另有各向异性、谱重采样、嵌套掩膜场；四者都是高斯场取阈，只在把相关函数搬到输出网格的方式上不同 |
目标 S2 估计方式 | 周期（假定示例可平铺） | 实测样品请改用补零 |
可容许性处理 | 裁剪负频段 | 另一选项为拟合可容许的 Debye 模型（构造上一定可容许）；无论哪种，被裁掉的频段数与能量占比都会报出 |
自动切换到各向异性模式 | 开启 | 示例各向异性超阈时自动切换，并说明为什么 |
各向异性阈值（长/短相关长度比） | 1.20 | 1.01–10 |
面外方向类比于 | 示例的行方向 | 另有列方向、两者平均、较长者、较短者；一张二维切片对此不含任何信息，所以没有正确默认值，选择本身会写进结果与告警 |
径向窗口（相关长度倍数） | 4.00 | 超过几个相关长度后实测 S2 就是噪声，而三维里这噪声被 4πr² 壳权重放大并主导谱。实测（五张示例）：半盒且无锥化时相关长度只有目标的 0.70–0.82，4 倍长度加 0.5 锥化为 0.82–0.97 |
窗口锥化比例 | 0.50 | 0–0.95；窗口与锥化都写进溯源记录 |
粗尺度掩膜相关长度（um） | 60.0 | 仅「嵌套掩膜场」有效 |
粗尺度掩膜体积分数 | 0.5 | 仅「嵌套掩膜场」有效；总体积分数约为两者之积，而不是示例自身的体积分数，这一点会告警 |
8. 输出结果
输出 | 含义 |
通道（Channel） | 生成的体数据，带体素尺寸与 origin；若在第 1 步选了基体通道（须为同一网格），结构会叠加到基体上 |
MultiROI | 同一体数据的标签形式，标签名取自相名称 |
S2 对照图 | 目标 S2 与实际达到的 S2 画在同一坐标上，近场（前 3 个径向分箱）加底纹标出 |
匹配状态 | 目标已复现 / 目标不可实现 / 近场未复现 / 无可比对的目标，并始终附带「这是统计上合理的结构，而不是用户自己的结构」 |
指标表 | 逐项给出分组 / 名称 / 请求值 / 实际值 / 单位 / 说明：体积分数、S2 近场与远场误差、相关长度、比表面、谱裁剪、取向、弦长、连通性、装填、网络、表面、裂隙 |
S2 CSV | 每个径向分箱一行：半径、目标、实际、绝对误差、归一化误差与近/远场标记 |
指标 CSV | 上述指标表的完整内容 |
HTML 报告 | 单文件，图以内联 SVG 绘制，不含任何外部请求（无 CDN、无网络字体、无远程图片、无脚本） |
JSON 溯源记录 | 种子与比特发生器、每个参数及其单位、输出形状 / 间距 / 物理尺寸 / 周期性、请求与实际体积分数、被裁掉的谱能量、全部各向异性判定与告警，以及各模块版本 |
网络图 CSV | 仅管网：节点与喉道各一行，含坐标、半径与周期位移，便于在别处重建同一网络 |
9. 常见问题与故障排除
- 提示硬核放置堵塞 —— 这不是故障，而是如实报告。随机顺序添加对球在体积分数约 0.38 附近饱和，细长体更低；报出来的是实际达到的体积分数。降低目标、改用可穿透模型，或提高尝试次数上限。
- 提示有若干个体比非周期域还宽 —— 超出网格的部分画不出来，结构里装的是被截断的体。放大域、缩小体，或把该方向设为周期。注意纤维长度默认取最长的域边长，所以默认设置下纤维本来就贯穿整盒。
- 提示被裁掉的谱能量偏大（超过 0.02）—— 要求的相关函数不是任何真实随机场的相关函数。改用可容许的 Debye 模型、缩短径向窗口，或换一张更大、更干净的示例。这个数字被报出来而不是吸收掉，正是为了让你能判断这次结果值不值得相信。
- 报错说共享径向网格只剩几个分箱 —— 比较用的分箱取示例像素与输出体素中较粗的那个，而输出盒子最短的物理方向撑不出足够多的分箱。沿最短方向放大输出盒子，或换一张至少和输出一样细的示例。
- 提示自动切换到各向异性模式 —— 这是正确行为：示例各轴向相关长度之比超过了阈值。切换之后，面外方向依然是一个假设，它按哪个轴取值写在结果里——一个建立在错误假设上、看起来却很合理的结构，比没有结构更糟。
- 平均误差很好看，近场误差却很大 —— 近场（r 为 1–3 个体素）是判断阈值与 S2 反演是否正确的地方；比表面正是 S2 在小 r 处的斜率（Debye），所以此时在这个体数据上测出的界面面积是有偏的。两个数字始终分开给出，正是为了不让远场的舒适掩盖近场的问题。
- 提示沿 Z 的周期性被忽略 —— 粗糙表面与裂隙都是高度场，无法沿自身厚度方向周期；Y、X 方向的周期性不受影响。
- 管网在图上连通，体素里却不贯通 —— 贯通性是在栅格化之后实测的：喉道半径小于一个体素就会消失。提高喉道半径或提高分辨率，不要只看图的连通性。
- 报错说示例是常量 —— 取阈无法复现一个本来就不存在的结构；报错里带着测到的体积分数，请检查阈值方法、极性与裁剪范围。
10. 注意事项与已知限制
- 整卷在内存中生成；第 2 步给出的峰值内存是数量级估计，超大网格请先用预览确定参数。单次网格上限为 2^30 体素。
- 发布始终是第 6 步的显式操作，预览与运行都不会发布任何对象；任何输入或参数改动都会立即作废上一次结果并禁用导出与发布。
- 预览是在同一物理盒子内、以相同种子在更粗网格上生成的，对这些解析生成器而言它就是同一结构的粗采样；但比草稿体素更细的特征不会出现，其数值不可作为报告值。
- 参数化模式不需要任何已发布对象；示例模式需要一张已发布通道里的切片，下拉框只列出已发布对象。
- 本插件不做测量。 体积分数、界面面积、三相界线、代表尺寸收敛与不确定度请用 Microstructure Statistics & RVE，包括测量这里生成的体数据。
- 与 Create Synthetic Images 的关系，说清楚。 那个插件基于 porespy 提供 26 个生成器，数量远多于这里；但它只用体素单位、只能发布通道、是单页的「生成即发布」面板，并且没有任何周期性。这四类结构族在它里面也都不存在：porespy 2.4.2 根本没有椭球生成器，纤维只有整数半径、单一尺寸、自由重叠的直圆柱，没有带喉道半径分布的管网，也没有粗糙表面。需要物理毫米单位、各向异性体素、逐轴周期、MultiROI 输出或样本约束合成时用本插件；只想快速拿一张体素单位的二维／三维图时用那一个。
- 样本合成只有高斯随机场。模拟退火与基于图块的多点合成没有实现，也没有留下任何钩子。
- S2 不决定连通性。 两个结构可以 S2 完全相同而贯通性完全不同，因此得到的是统计上合理的结构，不是用户自己的结构。
- 一张二维示例只约束它自己那个平面；面外方向必须由用户在五种类比方式中选一个，选择与理由都写进结果与告警。
- 每次运行只写入一个相标签（裂隙可另给上壁一个标签）。多相体数据请分次生成后自行合成；发布为通道时可以叠加到同一网格的基体通道上。
- 在周期单元里比单元本身还大的体会缠绕到自己身上——图案仍然严格平铺，但超过八个周期后平铺会被截断，并且两种情况都会告警。
11. 参考资料
「哪些参数族值得提供、生成结果该怎么报告」参考 NREL 的 MATBOX Microstructure Analysis Toolbox（BSD 2-Clause，Copyright (c) 2020, Alliance for Sustainable Energy, LLC）：https://github.com/NREL/MATBOX_Microstructure_analysis_toolbox 。未复制、移植、翻译或打包其任何源代码，运行时不需要 MATLAB、MATLAB Runtime 或 Octave。多尺度示例重建的思路参考 micro-maker（BSD 2-Clause）：https://github.com/davidt0x/micro-maker ，同样只作参考。PoreSpy（MIT）是体素生成器与两点相关测量的先例，被引用但未使用——它的生成器无法表达各向异性体素间距与周期缠绕，而这两点在这里是硬要求。
方法引用（与代码无关）：Quiblier、Adler、Roberts 与 Torquato（高斯场取阈重建，示例模块的基础）；Debye（S2 在小 r 处的斜率与比表面的关系）；Perram 与 Wertheim 1985（椭球接触函数，用于不重叠装填）；Brown 1995（波长失配的自仿射裂隙面）；Widom（随机顺序添加及其堵塞极限）。Yeong 与 Torquato（模拟退火重建）只被引用一次，用来记录 v1 刻意不实现它。
本插件不导入任何 GPL 或 LGPL 组件：edt（LGPLv3+）与 cc3d（LGPL）都在 Dragonfly 的 Python 环境里，但从不导入——距离变换一律用 scipy.ndimage.distance_transform_edt，连通域标记一律用 scipy.ndimage.label，并有测试扫描随包发布的源码守住这一点。运行时只用到 Dragonfly 自带的 NumPy 与 SciPy（均为 BSD-3-Clause）。完整声明见插件目录下的 THIRD_PARTY_NOTICES.md。
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
Generates artificial 3-D microstructures for simulation input, for method validation, or to augment training data. Two routes: parametric generation, which needs nothing published because the structure is invented from the parameters in step 3; and exemplar-constrained synthesis, where one published 2-D slice constrains the statistics of a 3-D volume.
This plugin generates; it does not measure. To measure a structure — volume fraction, interfacial area, the triple phase boundary, whether the representative size has converged — use Microstructure Statistics & RVE, including on the volume you have just generated here. The split is deliberate: analysis requires an input and barely publishes, while generation usually has no input and exists in order to publish.
A 2-D exemplar constrains its own plane and nothing else. It can only determine a 3-D volume if the medium is statistically isotropic in the third direction. The plugin therefore measures the exemplar's own axial correlation lengths, warns prominently once their ratio exceeds the limit (1.20 by default), and by default switches to the anisotropic mode — running the isotropic mode on a layered or fibrous material would flatten the anisotropy while still reporting a comfortable radial S2 error. Whatever happens, the axis the unconstrained out-of-plane direction was assumed to match is always named in the result and in a warning.
Exemplar synthesis in v1 is Gaussian-random-field only. Simulated annealing (Yeong-Torquato) and patch-based multipoint synthesis were cut on purpose: measured on this machine the GRF path reconstructs a 300-cubed volume in about two seconds, where those two need 4-20 h and 21.7 h respectively for a result that is not obviously better here — the GRF is already within a few percent of what they would be optimising. There are no hooks for them; they are not implemented rather than not wired up.
What can be reproduced is reproduced bit for bit, and what cannot be delivered is said out loud. The same seed gives a bit-identical volume, and the seed plus the full parameter set travel with the result as a provenance record. Random sequential addition detects jamming and reports the volume fraction it actually achieved instead of looping forever. Where the requested correlation is not physically realisable, the clipped spectral energy comes back as a number rather than being quietly absorbed.
2. Use cases
- Building a simulation input whose statistics you control, for finite-element or lattice-Boltzmann work.
- Validating a measurement pipeline on a structure whose answer is known in advance.
- Augmenting 3-D training data from a handful of real 2-D slices.
- Studying how one parameter — porosity, fibre aspect ratio, throat-radius spread, roughness — propagates into a downstream calculation.
- Producing a genuinely periodic RVE: periodicity is switched per axis, so the output can go straight into periodic boundary conditions.
3. Installation & enabling
1. Install the Prototype Apps package (or tick this plugin in the App Store).
2. This plugin is disabled by default — enable it in the App Store or the Menu Item Manager.
3. Restart Dragonfly completely (plugins are discovered at startup only). Menu: Prototype Apps ▸ Generators & Utilities ▸ Synthetic RVE Builder…
4. Runtime environment & first-run setup
Nothing to install or configure. It runs entirely in Dragonfly's own Python using the NumPy and SciPy it already ships. No internet, no download, no GPU, no virtual environment.
The header reports whether this build can publish Channels and publish MultiROIs. Anything it cannot do is greyed out rather than left to fail on click, and the exports stay available even when nothing can be published. Step 2 also states the voxel count, the physical box and an estimate of the peak working memory — measured: the field path holds about 0.7 GB at 300 cubed and 3.4 GB at 512 cubed, on top of what Dragonfly already holds. That is an order-of-magnitude guide, never a promise.
5. Interface
1. Inputs
Choose the mode first. Parametric (no input needed): pick a structure family — ellipsoids, fibres, tube network, rough surface, fracture aperture — and nothing has to be published; a matrix Channel may be selected for compositing at publish time, and "Use this object's grid" copies its shape, voxel size and origin into step 2. Exemplar-constrained (needs one 2-D slice): pick the Channel, the plane (XY / XZ / YZ), the slice index and the timestep. Every picker lists published objects only, and shape, spacing, origin and timestep count are shown at the bottom.
2. Calibration & Preprocessing
The output grid defines what will be built: voxel counts per axis, the voxel size (the panel is in micrometres because that is what materials users type; every core argument is in millimetres and the conversion happens in exactly one place) and the origin in mm. One line below gives the voxel count, the physical box and the peak-memory estimate; anisotropic voxels raise a notice — every inside-test is evaluated in millimetres, because a sphere on anisotropic spacing is an ellipsoid in voxels. In the exemplar mode this step also owns the binarisation (Otsu or a manual threshold, plus the polarity) and an optional row/column crop, and offers Measure the exemplar: see its volume fraction, threshold, axial decay lengths and anisotropy ratio before anything is synthesised.
3. Parameters
The upper half is common to both routes: periodicity along Z / Y / X (independent per axis), the phase label, the phase name, the random seed, and "Measure chords and interface orientation as well (slower)". The lower half switches to one page: one per parametric family, plus one for exemplar-constrained synthesis. Any parameter change drops the previous result immediately and disables the exports and the publish buttons — a results table that no longer describes the volume in memory is worse than an empty one.
4. Preview & QC
A pass over the same physical box with the same seed on a coarser grid (the longest edge stays within 96 voxels by default, and no axis shrinks below 12), showing a mid-slice, the S2 overlay and the metrics table. For these analytic generators the draft is genuinely the same structure sampled coarser rather than a corner of it — which is what makes a preview here honest in a way a decimated measurement never is — but anything finer than the draft voxel is simply missing from it. The preview publishes nothing and leaves the export buttons disabled.
5. Run
The plan is restated first (mode, family or synthesis method, plane, voxel counts, seed, which axes are periodic) together with the estimated cost; then the full-size build, cancellable at any time. The run publishes nothing either, and hands over to step 6 when it finishes.
6. Results & Export
At the top, a mid-slice and the S2 overlay: the target correlation drawn against the one the generated volume actually achieved, on the same axes, with the near field (the first 3 radial bins) shaded — that is where a level-cut Gaussian field is systematically wrong, and it is also where the specific surface comes from. Below it the match status — target reproduced / target was not realisable / near field not reproduced / no target to compare against — always accompanied by the line "this is a statistically plausible structure, not the user's structure". Then the metrics table (group / name / requested / achieved / unit / note), the anisotropy notes and every warning, and finally two publish buttons and five export buttons (the network graph CSV is enabled for a tube network only).
Share Report
A seventh tab, Share Report, is not a workflow step — it puts a finished report on the internet temporarily and does no analysis. It serves the report you just generated from this computer through a temporary Cloudflare quick tunnel and hands back a temporary public address; nothing is uploaded, no account is needed, and the page carries your image data itself. The address is not usable immediately: it only starts answering roughly 40 s AFTER the tunnel is started (measured from this machine: 45 s once, while two other tunnels never resolved at all), so do not send the link before the status turns green. While it is running anyone who has the link can read the report — there is no password. Pressing Stop sharing, closing the window or quitting Dragonfly makes the address stop working permanently; it is never reissued. The link is only offered once this machine has confirmed the address answers, or has said plainly that it could not confirm it.
6. How to use
1. Choose the mode in step 1: parametric means picking a structure family; exemplar-constrained means picking a published slice.
2. Set the output grid in step 2 — voxel counts, voxel size and origin; in the exemplar mode also confirm the threshold and the polarity, and press Measure the exemplar to see its volume fraction and its anisotropy.
3. Fill in step 3: the periodicity, the phase label and the seed first, then the page belonging to the chosen family or synthesis method.
4. Run a preview in step 4 and check the shape looks sensible, the achieved volume fraction is near the target, the S2 curves agree and there is no wall of warnings.
5. Build at full size in step 5.
6. Read the match status and the metrics table in step 6, then publish as a Channel or a MultiROI and export the CSV / HTML / JSON provenance.
7. Parameters
Output grid and common settings
Parameter | Default | Meaning |
Size Z / Y / X (voxels) | 128 | 8 to 4096, independent per axis; one grid may not exceed 2^30 voxels |
Voxel size Z / Y / X (um) | 1.0 | the panel is in micrometres, the cores are in millimetres, and the conversion happens in one place |
Origin Z / Y / X (mm) | 0 | written onto the published object; a build that cannot set it says so explicitly in the publish message |
Periodic along Z / Y / X | all three on | independent per axis; a rough surface or a fracture is a height field and cannot be periodic through its own thickness, so Z is ignored with a warning |
Phase label | 1 | 1 to 255, the label value written into the volume |
Phase name | Structure | the published object's name and the MultiROI label name |
Random seed | 0 | the same seed is bit-reproducible; the bit generator is PCG64 and both go into the provenance record |
Measure chords and interface orientation as well (slower) | on | turning it off still reports the volume fraction and the two-point correlation; a preview always skips these two |
Largest preview edge (voxels) | 96 | 16 to 160; no axis of the draft shrinks below 12 voxels |
Ellipsoids
Parameter | Default | Meaning |
Target volume fraction (0 = use the count) | 0.3 | 0 to 0.95; for the penetrable model phi = 1 - exp(-n v / V) inverts to the count in one step, with no trial and error |
Number of bodies (0 = use the fraction) | 0 | give either the fraction or the count, never both |
Equivalent-sphere d50 (um) | 20 | the median of a lognormal distribution |
Size CV | 0.2 | 0 to 3 |
Aspect ratio a/b | 1.0 | 1 and 1 is a sphere; volume is invariant to the aspect ratios by construction, so changing the shape does not undo the targeted fraction |
Aspect ratio b/c | 1.0 | as above |
Aspect ratio CV | 0.0 | 0 to 3 |
Orientation | isotropic | aligned, about an axis (von Mises-Fisher) and uniform inside a cone are the others |
Concentration kappa | 0 | used by "about an axis" only; larger is more concentrated |
Preferred axis | Z | the reference axis for aligned, about-an-axis and cone |
Cone half-angle (degrees) | 90 | 0.1 to 90, used by the cone only |
Overlap policy | penetrable (free overlap) | hard core, hard core with a clearance, and place-then-push-apart are the others |
Clearance (um) | 0 | used by "hard core with a clearance" only; it is a surface-to-surface distance |
Attempt budget | 200000 | a hard-core placement that exhausts the budget is declared jammed and reports the fraction it actually reached |
Subsampling (partial volume) | 1 | 1 to 4; rasterises on a k-times finer grid and keeps a voxel whose coverage reaches one half, at k-cubed the cost; the coverage is also reported as a partial-volume figure |
Fibres
Parameter | Default | Meaning |
Target volume fraction (0 = use the count) | 0.15 | 0 to 0.95 |
Number of bodies (0 = use the fraction) | 0 | give either the fraction or the count, never both |
Fibre radius (um) | 5.0 | a lognormal median; a fibre is drawn as a sphere-swept polyline |
Radius CV | 0.0 | 0 to 3 |
Fibre length (um, 0 = span the box) | 0 (spanning) | defaults to the longest domain edge, so the fibres span the box; that is stated in the warnings |
Length CV | 0.0 | 0 to 3 |
Wavy fibres | off | turns the straight fibres into wormlike chains of the given persistence length |
Persistence length (um) | 200 | each step turns by an exact von Mises-Fisher draw, so <cos theta> = exp(-ds / lp) holds at any step size; the small-angle shortcut overstates the end-to-end distance by 34% at ds / lp = 0.67 and is not used. The measured tortuosity and RMS end-to-end distance are reported next to the exact discrete-chain value they should match |
Step along the fibre (um, 0 = automatic) | 0 (automatic) | a sixteenth of the persistence length, and never more than an eighth of the fibre length |
Orientation / kappa / preferred axis / cone half-angle | isotropic / 0 / Z / 90 | exactly as for ellipsoids |
Overlap policy | penetrable (free overlap) | place-then-push-apart is not defined for fibres and is refused with a message saying why |
Clearance (um) / attempt budget / subsampling | 0 / 200000 / 1 | exactly as for ellipsoids |
Tube network
Parameter | Default | Meaning |
Topology | Voronoi edges | Delaunay edges and a cubic lattice are the others |
Seed points | 120 | at least 4; a topology that produces no edges is refused with a message to raise this |
Mean coordination (0 = keep all edges) | 0 | a spanning tree is protected before pruning, so thinning towards a coordination number cannot shatter the network |
Throat radius (um) | 8.0 | a lognormal median |
Throat radius CV | 0.3 | 0 to 3 |
Pore radius (um, 0 = from the throats) | 0 | the node-ball radius; left at 0 it follows from the adjoining throats |
Pore radius scale | 1.3 | 1 to 5, how much larger a node ball is than its throats |
Target volume fraction (0 = off) | 0 (off) | the one place in this plugin where a fraction is not reached in a single closed-form step, and the reason is physical: the tubes share node balls instead of being independently placed, so the penetrable relation does not hold. The radius multiplier is solved analytically against the exact drawn-body volume, then corrected by a bounded number of measured rasterising passes — a deterministic sequence, not a retry loop |
Fraction refinement passes | 3 | 0 to 10; two or three land inside 2%, and 1 keeps the pure closed-form shot plus one rasterisation |
Keep only the largest connected network | off | on a periodic axis this can drop a node whose periodic partner was kept, so the pattern may no longer tile exactly; that is warned about |
Keep only the spanning cluster | off | needs a spanning axis as well |
Spanning axis | Z | percolation is measured on the raster after rasterisation, never inferred from the graph |
Subsampling (partial volume) | 1 | 1 to 4, as for ellipsoids |
Rough surface and fracture aperture
Parameter | Default | Meaning |
Target volume fraction (rough surface) | 0.5 | 0.01 to 0.99; the mean plane height is solved on the continuous solid depth, so no rasterise-and-retry loop is involved |
Hurst exponent | 0.8 | 0.05 to 0.99; the power spectrum goes as q to the -(2H+2), the 2-D self-affine form |
Roughness Rq (um) | 5.0 (rough surface) / 3.0 (fracture) | the height field is rescaled so Rq hits the target exactly |
Roll-off wavelength (um, 0 = off) | 0 (off) | the wavelength above which the spectrum flattens — real surfaces are not fractal beyond their own correlation length |
Small-scale cut-off (um, 0 = off) | 0 (off) | the short-wavelength limit |
Lay along Y / X | 1.0 / 1.0 | a per-axis correlation-length multiplier: 6.0 means features are six times longer along that axis, which makes it smoother |
Mean aperture (um, fracture) | 12.0 | the mean of the wall separation; clipping the contact patches necessarily raises the achieved mean, so requested and achieved are reported apart |
Mismatch length (um, 0 = automatic) | 0 (a quarter of the shorter in-plane edge) | above the mismatch wavelength the two walls come from the same noise — as the two halves of a split rock match at long wavelength — and below it they are independent, so a LONGER mismatch length gives a ROUGHER aperture |
Allow the walls to touch | on | turning it off lifts the whole aperture until they do not touch, and reports the lift and the new mean aperture |
Label of the upper wall (0 = same as the lower) | 2 | 0 to 255; the aperture itself is always label 0 |
Exemplar-constrained synthesis
Parameter | Default | Meaning |
Threshold method | Otsu (automatic) | a manual threshold is the alternative; the automatic value is stated in a warning |
Polarity | phase is above the threshold | below the threshold is the alternative |
Crop the exemplar | off | row and column ranges; a range outside the exemplar is clamped to its full extent and warned about |
Synthesis method | Gaussian random field, isotropic | anisotropic, spectral resampling and a nested masked field are the others; all four are GRF level cuts and differ only in how the Gaussian correlation is carried onto the output grid |
Target S2 estimator | periodic (assumes the exemplar tiles) | use zero-padded for a measured sample |
Admissibility | clip the negative bins | fitting an admissible Debye model is the alternative and is admissible by construction; either way the clipped bin count and the clipped energy fraction are reported |
Auto-switch to the anisotropic mode | on | switches when the exemplar's anisotropy exceeds the limit, and says why |
Anisotropy limit (max/min length) | 1.20 | 1.01 to 10 |
Out-of-plane axis behaves like | the exemplar rows | the columns, the mean of both, the longer and the shorter are the others; one 2-D slice carries no information about this, so there is no right default and the choice itself is named in the result and in a warning |
Radial window (correlation lengths) | 4.00 | beyond a few correlation lengths a measured S2 is noise, and in 3-D the 4 pi r-squared shell weight makes that noise dominate the spectrum. Measured over five exemplars: a half-box window with no taper reaches only 0.70 to 0.82 of the target correlation length, while 4 lengths with a 0.5 taper reaches 0.82 to 0.97 |
Taper (fraction of the window) | 0.50 | 0 to 0.95; both the window and the taper appear in the provenance |
Coarse mask correlation length (um) | 60.0 | used by the nested masked field only |
Coarse mask volume fraction | 0.5 | used by the nested masked field only; the overall volume fraction is about the product of the two, not the exemplar's own, and that is warned about |
8. Output
Output | Meaning |
Channel | the generated volume, carrying its voxel size and origin; if a matrix Channel was chosen in step 1 (it must be on the same grid) the structure is composited onto it |
MultiROI | the same volume as labels, named from the phase name |
S2 overlay | the target correlation against the achieved one on the same axes, with the near field (the first 3 radial bins) shaded |
Match status | target reproduced / target was not realisable / near field not reproduced / no target to compare against, always with the line "this is a statistically plausible structure, not the user's structure" |
Metrics table | group / name / requested / achieved / unit / note for every reported quantity: volume fraction, the near- and far-field S2 error, correlation lengths, specific surface, spectral clipping, orientation, chords, connectivity, packing, network, surface and fracture |
S2 CSV | one row per radial bin: radius, target, achieved, absolute error, normalised error and the near/far flag |
Metrics CSV | the metrics table in full |
HTML report | one file with the plots drawn as inline SVG and no external request of any kind — no CDN, no web font, no remote image, no script |
JSON provenance | the seed and bit generator, every parameter with its unit, the output shape / spacing / extent / periodicity, requested against achieved volume fraction, the clipped spectral energy, every anisotropy verdict and warning, and the versions of the modules that produced the numbers |
Network graph CSV | tube networks only: one row per node and per throat, with coordinates, radii and periodic shifts, so the same network can be rebuilt elsewhere |
9. FAQ & troubleshooting
- It says hard-core packing jammed — that is a report, not a fault. Random sequential addition saturates near a volume fraction of 0.38 for spheres and lower for elongated bodies, and the number reported is the fraction actually achieved. Lower the target, switch to the penetrable model, or raise the attempt budget.
- It says N bodies are wider than the non-periodic domain — the part outside the grid cannot be drawn, so the structure holds a truncated body rather than the one requested. Enlarge the domain, shrink the body, or make that axis periodic. Note that the fibre length defaults to the longest domain edge, so on the defaults the fibres are meant to span the box.
- It warns that the clipped spectral energy is large (above 0.02) — the requested correlation is not the correlation of any real field. Fit the admissible Debye model instead, shorten the radial window, or use a larger and cleaner exemplar. The number is reported rather than absorbed precisely so you can decide whether the run is worth believing.
- It refuses with "the shared radial grid would hold only N bins" — the comparison bin is the coarser of the exemplar pixel and the output voxel, and the shortest physical axis of the output box cannot fill enough bins. Enlarge the output box along that axis, or supply an exemplar sampled at least as finely as the output.
- It says it auto-switched to the anisotropic mode — that is correct behaviour: the exemplar's axial correlation lengths differ by more than the limit. After the switch the out-of-plane direction is still an assumption, and the axis it was matched to is stated in the result — a plausible-looking structure built on a broken assumption is worse than none.
- The mean error looks comfortable but the near-field error is large — the near field (r of 1 to 3 voxels) is what tells you the threshold and the S2 inversion are right, and the specific surface is the small-r slope of S2 (Debye), so an interfacial area measured on this volume is biased. The two numbers are always reported separately so that far-field comfort cannot hide a near-field problem.
- It says periodicity along Z was ignored — a rough surface and a fracture are both height fields and cannot be periodic through their own thickness; Y and X are unaffected.
- The tube network is connected as a graph but does not percolate in the voxels — percolation is measured after rasterisation, and a throat thinner than one voxel simply disappears. Raise the throat radius or the resolution rather than trusting the graph.
- It refuses because the exemplar is constant — a level cut cannot reproduce a structure that has none; the message carries the volume fraction it measured, so check the threshold method, the polarity and the crop.
10. Notes & known limitations
- The whole volume is built in memory; the peak-memory figure in step 2 is an order-of-magnitude estimate, so use the preview to settle parameters on large grids. One grid may not exceed 2^30 voxels.
- Publishing is always an explicit step-6 action; neither preview nor run publishes anything, and any change to an input or a parameter drops the previous result and disables the exports and the publish buttons immediately.
- The preview is built over the same physical box with the same seed on a coarser grid, which for these analytic generators is the same structure sampled coarser — but anything finer than the draft voxel is missing from it, so its numbers must not be reported.
- The parametric mode needs no published object at all; the exemplar mode needs a slice out of a published Channel, and every picker lists published objects only.
- This plugin does not measure. Volume fraction, interfacial area, the triple phase boundary, representative-size convergence and uncertainty belong to Microstructure Statistics & RVE — including on the volumes generated here.
- How this relates to Create Synthetic Images, plainly. That plugin offers 26 generators built on PoreSpy, far more than this one; but it is voxel-unit only, publishes Channels only, is a single-page generate-and-publish panel, and nothing in it is periodic. None of these four families exists there either: PoreSpy 2.4.2 has no ellipsoid generator at all, its fibres are monodisperse straight cylinders with integer radii and free overlap, there is no tube network with a throat-radius distribution, and there is no rough surface. Use this plugin when you need physical millimetres, anisotropic voxels, per-axis periodicity, MultiROI output or exemplar-constrained synthesis; use that one when a quick voxel-unit 2-D or 3-D image is all you want.
- Exemplar synthesis is Gaussian random fields only. Simulated annealing and patch-based multipoint synthesis are not implemented and there are no hooks for them.
- S2 does not control connectivity. Two structures can share S2 exactly and percolate completely differently, so what comes out is a statistically plausible structure and not the user's structure.
- One 2-D exemplar constrains its own plane only; the out-of-plane direction has to be chosen from five ways of matching it, and both the choice and the reason are recorded in the result and in a warning.
- One run writes one phase label (a fracture may give the upper wall a second one). A multi-phase volume means generating in several runs and compositing them yourself; publishing as a Channel can composite onto a matrix Channel on the same grid.
- A body larger than the periodic cell wraps onto itself — the pattern still tiles exactly, but beyond eight periods the tiling is truncated, and both cases are warned about.
11. References
Which parametric families are worth offering, and how a generated volume should be reported, were informed by NREL's MATBOX Microstructure Analysis Toolbox (BSD 2-Clause, Copyright (c) 2020, Alliance for Sustainable Energy, LLC): https://github.com/NREL/MATBOX_Microstructure_analysis_toolbox — no source was copied, ported, translated or bundled, and no MATLAB, MATLAB Runtime or Octave is required at runtime. The idea of multiscale exemplar reconstruction came from micro-maker (BSD 2-Clause): https://github.com/davidt0x/micro-maker, also reference only. PoreSpy (MIT) is prior art for voxel-based generators and for two-point-correlation measurement and is referenced but not used — its generators cannot express anisotropic voxel spacing or periodic wrapping, and both are requirements here.
Method citations (no code relationship): Quiblier, Adler, Roberts and Torquato (Gaussian-field level-cut reconstruction, the basis of the exemplar module); Debye (the small-r slope of S2 against specific surface); Perram & Wertheim 1985 (the ellipsoid contact function used for non-overlapping packing); Brown 1995 (self-affine fracture surfaces with mismatched wavelengths); Widom (random sequential adsorption and its jamming limit). Yeong & Torquato (simulated-annealing reconstruction) is cited once only, to record that v1 deliberately does not implement it.
No GPL or LGPL component is imported: edt (LGPLv3+) and cc3d (LGPL) are both present in Dragonfly's Python environment and are never imported — every distance transform uses scipy.ndimage.distance_transform_edt and every connected-component labelling uses scipy.ndimage.label, and a test scans the shipped source to keep it that way. At runtime only Dragonfly's own NumPy and SciPy are used, both BSD-3-Clause. The full statement is in THIRD_PARTY_NOTICES.md in the plugin folder.