SPAM DVC 数字体积相关 插件用户手册

SPAM DVC (Panel) - User Manual

Dragonfly Prototype Apps · SPAM DVC (Panel)...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

SPAM DVC（英文菜单名 SPAM DVC (Panel)...）是一个集成在 Dragonfly 内部的数字体积相关（Digital Volume Correlation，DVC）分析插件。它在两个已经空间对齐的三维图像（参考态 / 变形态）之间计算位移场与应变场，从而无损地量化样品内部的三维变形与应变分布。计算结果以新的 DVC_* Channel 形式写回 Dragonfly 场景，可直接进行 2D/3D 可视化与定量测量。

插件以可停靠面板（OrsPlugin）的形式直接运行在 Dragonfly 进程内：数据在进程内直接读写（无需 TCP、无需在 Python Console 启动任何 server），图像显示完全交给 Dragonfly 自身的 2D/3D 视图。每次运行还可选地生成一份 Word（.docx）分析报告，包含参数、切片图、统计数据与结果解读。

底层引擎 / 算法。 计算内核为开源软件包 SPAM（Software for the Practical Analysis of Materials），一个由 spam-project 团队（法国格勒诺布尔，E. Andò、O. Stamati 等人）开发维护、以 Python + C++ 实现的材料图像分析软件包，广泛用于 X 射线 CT 图像的 DIC/DVC 全场变形测量。本插件使用其 spam.DIC（相关计算）、spam.deformation（变形场/应变）与 spam.mesh（网格）模块，提供两种 DVC 算法：局部子集法（Local Subset） 与 全局有限元法（Global FEM），二者均在 WSL2 中执行。

SPAM 内核在 Linux（WSL2）下运行，避免了在 Windows 下编译 SPAM 的困难。整个 DVC 任务运行在后台工作线程，计算期间 Dragonfly 界面不会卡顿。

许可证要点：SPAM 为 GPL 协议的开源软件。官方文档 https://www.spam-project.dev/ ，源码托管于 GitLab https://gitlab.com/spam-project/spam 。请在使用其计算结果时遵守相应的开源许可与引用要求。

2. 适用场景

本插件适用于原位（in-situ）CT 实验——即对同一样品在加载前后（或多个变形阶段）分别成像，量化其内部的位移与应变。典型应用包括：

• 材料力学：对岩石、土壤、泡沫、复合材料、增材制造（AM）件进行压缩 / 拉伸试验时的内部变形与应变测量。
• 生物力学：骨骼、组织等在加载下的应变分布研究。
• 工业 CT 质量分析：量化内部变形与应变，评估缺陷、裂纹演化与界面滑移。
• 时间序列研究：蠕变、疲劳等多阶段加载过程中的变形场演化对比。

可靠的 DVC 结果要求图像具备足够丰富且稳定的三维灰度纹理——来自材料天然微结构（孔隙、骨小梁、颗粒等）或人工掺入的示踪颗粒。参考态与变形态应为同一样品、同一分辨率的两期扫描，且已在 Dragonfly 中完成空间配准 / 对齐（详见第 6 章）。

3. 安装与启用

本插件随 Prototype Apps 完整安装包（Full Package） 分发，属于 Measurements & Analysis（测量与分析） 分组。安装分为 Dragonfly 插件侧与 WSL2 计算侧两部分；本章讲插件侧的安装与启用，计算环境的配置见第 4 章。

3.1 通过 Full Package 安装

1. 将完整安装包解压到任意较短的目录（如 C:\PL\，避免路径过长）。

2. 双击 Install_FullPackage.bat。

3. 在弹出的对话框中选择核心安装模式（Fresh 全新安装 / Compatible 兼容安装，二者只影响 Prototype Labs 核心的 block 与 recipe，不影响任何插件的环境和设置），并在 Prototype Apps 列表中勾选 SPAM DVC。

4. 点击 Install，等待控制台完成。

5. 完全退出并重启 Dragonfly（菜单只在启动时被扫描）。

默认状态下，SPAM DVC 这类插件在安装列表中是未勾选（关闭）的——轻量菜单项默认开启，所有插件默认关闭。因此需要在安装时手动勾选它，才会被部署。

3.2 菜单位置

重启 Dragonfly 后，插件出现在 Prototype Apps ▸ SPAM DVC (Panel)...。点击它即在 Dragonfly 右侧打开一个可停靠、可折叠、可浮动的 SPAM DVC 面板（标题页签 “SPAM DVC”）。

3.3 以后修改勾选（Menu Item Manager）

安装之后如需启用或停用本插件，最方便的方式是在 Dragonfly 内操作：打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager，在底部的 “Prototype Apps (Full Package)” 列表里为 SPAM DVC 勾选（部署）或取消勾选（移除菜单项），然后重启 Dragonfly 生效。

停用从不删除插件已搭好的 WSL 计算环境，重新启用即可立即使用。也可以随时重跑安装器修改勾选（上次的选择即为默认值）。

3.4 卸载

双击 Uninstall_FullPackage.bat 可移除所有 Full Package 的菜单项、插件与中央存储；它会保留 Prototype Labs 核心以及所有插件环境（venv / 下载内容 / WSL 发行版），并在结束时列出这些路径，便于需要腾出磁盘空间时手动删除。

4. 运行环境与首次配置

与许多 Prototype Apps 插件不同，SPAM DVC 的计算不在 Dragonfly 自带 Python 内进行，也没有 “Setup Environment” 按钮；它的重型计算内核（SPAM）运行在 WSL2（Windows Subsystem for Linux 2） 里。插件侧本身无需任何下载（生成报告所需的 python-docx 已随插件以纯 Python 副本内置），但计算侧必须一次性准备好 WSL2 + SPAM 环境。

4.1 前置条件

• WSL2：必需。若尚未安装，请在管理员 PowerShell 中执行 wsl --install --no-distribution 后重启；已有 WSL 的电脑执行 wsl --update 升级。
• 联网：使用随附的预打包 WSL 环境时无需联网下载（rootfs 约 1.5 GB，随分发包离线提供）。
• GPU：不需要。DVC 计算为 CPU 运算。
• 外部软件：Global FEM 模式若要使用非结构化网格，需在 WSL 内额外安装 Gmsh（常规分析无需）。

4.2 方式 A：使用随附的一键 WSL 安装包（推荐）

把分发包中的 SpamDVC-WSL-Package 整个拷到目标电脑，双击其中的 install_spam_dvc_wsl.bat。安装器会：

1. 导入名为 SpamDVC 的计算发行版（内含改版 SPAM 0.8.1.4 + spambind + venv + worker）；

2. 进行冒烟自检（验证默认用户、import spam.DIC/deformation/mesh、worker 可启动）；

3. 创建 Windows↔WSL 数据交换目录 C:\DVCJobs；

4. 写入插件配置文件 %LOCALAPPDATA%\SpamDvc\wsl_config.json。

完成后，打开面板时 “Backend Engine (WSL2)” 的四个字段会根据该配置文件自动预填正确的值，无需手动设置。

4.3 方式 B：自建 WSL 环境（不使用分发包时）

在任一 WSL2 发行版中创建 Python 虚拟环境并安装 spam（pip 包或源码编译，参见 SPAM 官方文档），把插件提供的 spam_dvc_worker.py 拷入 WSL（例如 /home/<用户>/spam_dvc_worker.py），然后在面板 “Backend Engine (WSL2)” 中手动填写四个字段（含义见 5.5 节）。

若面板 WSL 字段仍显示旧的硬编码默认值（如 Distro=Ubuntu），说明未读到 %LOCALAPPDATA%\SpamDvc\wsl_config.json：请先运行 WSL 分发包安装器，或手动填写四项配置。面板设置不保存，每次打开会恢复默认 / 预填值。

4.4 安装位置

• 配置文件：%LOCALAPPDATA%\SpamDvc\wsl_config.json（面板 WSL 字段的预填来源）。
• 作业交换目录：C:\DVCJobs（Windows 与 WSL 经 /mnt/c/... 交换数据，由 WSL 安装器创建）。
• WSL 发行版：默认名为 SpamDVC（内含 /home/dragonfly/spam_env 的 Python 与 spam_dvc_worker.py）。

5. 界面说明

面板顶部始终有一条红色提示，提醒你在做 DVC 之前先在 Dragonfly 中用刚性配准对齐两个体数据（若几何不同，插件会先把变形态重采样到参考态网格，再测残余的局部变形）。提示之下是一个可滚动的表单，按分组排列如下。

5.1 Input (from Dragonfly) — 输入区

Channel 与 ROI 列表自动从当前会话刷新（约每 2.5 秒轮询一次，跟随工程变化，无需手动刷新按钮）。三个下拉框：

• Reference Channel：参考态（未变形）体数据。
• Deformed Channel：变形态（加载后）体数据。
• Processing ROI (optional)：可选的处理 ROI，默认 (none / full volume)。选择后程序用其包围盒裁剪分析区域，可显著加速、省内存。

每个条目显示为 标题 [Z×Y×X] 的形式，便于按尺寸辨认。

5.2 DVC Parameters — 通用参数区

• DVC Mode：下拉框，Local Subset (WSL2)（默认）或 Global FEM (WSL2)。
• Subset size (Local)：文本框，默认 40。局部相关窗口边长（体素）。
• Node step：文本框，默认 15。计算节点间距（体素）。
• Margin (Local)：文本框，默认 1。节点距体积边界的收缩量（体素）。
• Compute strain fields：复选框，默认勾选。是否在位移场之后继续计算应变场。
• Resample deformed → reference geometry (if mismatched)：复选框，默认勾选。当两体几何不同时，把变形态重采样到参考态网格。
• Auto-align mismatched volumes (crop to common size)：复选框，默认勾选。两体尺寸不一致时裁剪到公共体素尺寸（仅裁剪，非配准）。
• Align anchor：下拉框，Center（默认）或 Origin，控制上面裁剪的锚点。
• Grayscale preprocess：下拉框，默认 None；另有 Histogram match (def→ref)、Min-max [0,1]、Standardize (ZNCC)。

5.3 Global FEM Parameters — 全局有限元参数区（仅 Global 模式生效）

• Mesh type：下拉框，当前仅 structured（规则六面体结构化网格）。
• Element size：文本框，默认留空（占位提示 “blank = auto from node step”），即自动取 Node step。
• Use Gmsh (optional)：复选框，默认不勾。需非结构化网格时启用（WSL 内须装 Gmsh）。
• Global Gaussian pre-blur：复选框，默认勾选。计算前对图像做高斯平滑。
• Max iterations：文本框，默认 20。全局迭代上限。
• Convergence criterion：文本框，默认 0.01。收敛判据。
• Enable elasticity regularisation：复选框，默认勾选。弹性力学正则化。
• Young's modulus：文本框，默认 0.0001。正则化强度（经验参数，无物理单位）。

5.4 Backend Engine (WSL2) — 计算后端区

四个文本框，默认值来自 wsl_config.json（无该文件时用硬编码默认值）：

• WSL Python Path：WSL 内 Python 解释器绝对路径（默认 /home/dragonfly/spam_env/bin/python）。
• WSL Worker Path：worker 脚本在 WSL 内的绝对路径（默认 /home/dragonfly/spam_dvc_worker.py）。
• Win Job Root：Windows 作业目录（默认 C:\DVCJobs）。
• WSL Distro：发行版名称（默认 Ubuntu，使用分发包后一般为 SpamDVC）。

5.5 Output — 输出区

• Output dir (.npz/.json)：文本框，结果汇总目录（默认 C:\DVCJobs\output）。
• Generate .docx report after each run：复选框，默认勾选。每次运行成功后在 Output dir 生成图文分析报告。
• Report in Chinese (中文报告)：复选框，默认不勾（即英文报告）；勾选则生成中文报告。

5.6 Run / Stop 与日志

• Run DVC（蓝色按钮）：开始一次 DVC 计算（在后台线程运行）。
• Stop（红色按钮，运行时才可用）：请求中断；已在进行的 WSL 子进程可能仍会跑到完成。
• 底部日志区（只读）：实时显示作业目录创建、WSL worker 启动、进度百分比、结果回写等信息，也是排障的首要窗口。

6. 使用步骤

6.1 数据准备：先配准，再 DVC

这是最重要的前提。 DVC 只测量“已对齐状态下的小变形”。两个体数据之间的整体平移 / 旋转必须先在 Dragonfly 中通过刚性配准（rigid registration）/ 手动对齐消除，否则结果将是噪声或假位移。请注意：

• 参考态与变形态应为同一样品、同一分辨率的两期扫描；
• 两个 Channel 的体素尺寸（spacing）应一致；
• 务必使用刚性配准——可变形配准会把 DVC 本要测量的变形也一并消掉；
• Dragonfly 的配准只改变几何（origin / orientation / spacing），不改写体素网格，因此本插件在几何不一致时会自动把变形态重采样到参考态网格（见 “Resample” 复选框）。

6.2 端到端操作步骤

1. 在 Dragonfly 中完成参考态 / 变形态两个体数据的空间配准 / 对齐。

2. 打开面板：Prototype Apps ▸ SPAM DVC (Panel)...，面板停靠在 Dragonfly 右侧。

3. 在 “Input (from Dragonfly)” 中选择 Reference Channel 与 Deformed Channel（列表自动刷新，无需按钮）；可选择一个 Processing ROI 以缩小分析区域。

4. 选择 DVC Mode（首次可保持 Local Subset），并按第 7 章设置参数（首次可全部保持默认）。

5. 确认 “Backend Engine (WSL2)” 四项配置正确（使用分发包时已自动预填），并按需设置 “Output dir” 与报告选项。

6. 点击 Run DVC。日志区依次出现任务目录创建、WSL worker 启动、进度百分比等信息；计算期间可继续在 Dragonfly 中操作，或点 Stop 中断。

7. 完成后日志提示成功，Dragonfly 数据列表中出现 DVC_* 结果 Channel（含义见第 8 章）；若勾选了报告选项，Output dir 中同时生成 <数据名>_<时间戳>.docx 分析报告。

输入要求 → 操作 → 得到什么：输入为两个已对齐、含足够灰度纹理的三维 Channel；操作为选数据、设参数、Run DVC；得到的是写回场景的 DVC_* 位移 / 应变 Channel（可直接可视化与测量），以及作业目录中的 .npz/.json 结果文件和可选的 .docx 报告。

7. 参数说明

下表列出面板中所有 DVC 参数的默认值与含义。除特别说明外，长度单位均为体素（voxel）。

7.1 按数据类型的调参建议

8. 输出结果

8.1 写回 Dragonfly 的结果 Channel

计算完成后自动创建以下 DVC_* Channel（与参考数据同几何，可直接叠加显示、做剖面与定量测量）。具体生成哪些取决于算法与 “Compute strain fields” 是否勾选：

建议查看方式：对结果 Channel 套用伪彩色 LUT 并叠加在参考体灰度图上；用 Dragonfly 的剖面 / 直方图工具做定量分析；3D 渲染观察变形分布的空间形态。

8.2 输出文件

每次任务在 Job Root（C:\DVCJobs）下生成独立作业目录，其中包含本次任务的输入数据与完整参数（ref.npy/def.npy/params.json，可用于复现）、运行状态与进度 status.json（出错时含完整 traceback，排障首选），以及位移 / 应变结果文件。

同时在 Output dir（默认 C:\DVCJobs\output）保存：汇总数组 .npz 与对应 _meta.json（便于用 Python / MATLAB 后续处理）。

8.3 可选的 .docx 分析报告

若勾选了 “Generate .docx report after each run”，会在 Output dir 生成一份名为 <数据名>_<时间戳>.docx 的图文报告，共 8 个章节：1) 报告摘要与关键结论；2) 关于 DVC；3) 关于 SPAM 计算软件；4) 分析方法与参数设定；5) 输入数据概况（含切片图 / 直方图）；6) 分析结果（位移场、应变统计、逐字段应变图）；7) 结果解读指引；8) 输出文件与计算环境。报告语言由 “Report in Chinese” 复选框决定（默认英文）。

报告生成在后台工作线程进行，属 best-effort：即使生成失败也只写日志，不影响 DVC 结果与 Channel 写回。

9. 常见问题与故障排除

10. 注意事项与已知限制

• 必须先配准：DVC 只测小变形，两体之间的整体平移 / 旋转必须先用刚性配准消除；可变形配准会抹掉待测变形。
• 输入仅限从 Dragonfly 选择：本插件当前只支持从 Dragonfly 会话中选取参考态 / 变形态 Channel，不提供直接读取磁盘文件或合成数据的输入模式。
• 面板设置不保存：每次打开面板会恢复默认 / 预填值；使用分发包可通过 wsl_config.json 免除重复填写 WSL 字段。
• Global FEM 仅支持结构化网格：目前 Mesh type 仅 structured；非结构化网格需在 WSL 内额外安装 Gmsh 并勾选 Use Gmsh。
• 位移 / 应变单位为体素：DVC_Disp_Mag 等以体素为单位；如需物理单位请结合体素尺寸自行换算。
• Stop 为软中断：点 Stop 后，已在进行的 WSL 子进程可能仍会跑到完成后才停止。
• 典型应变量级：弹性阶段约 0.1%–1%，塑性阶段可达 10%–50%；若测得应变远超预期，应首先怀疑配准 / 参数问题。

11. 参考资料

• SPAM 官方文档：https://www.spam-project.dev/
• SPAM 源码（GitLab）：https://gitlab.com/spam-project/spam
• 计算内核版本：SPAM 0.8.1.4（本地修改版）+ spambind 0.8.2，运行于 WSL2 Ubuntu；许可证 GPL。
• 适用 Dragonfly 版本：2025.1 / 2027.1（均为 PyQt6 6.7.1、Python 3.10.13）。
• 完整安装 / 启用说明：随包 Full Package README 及安装对话框；插件分组 Measurements & Analysis。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation and Enablement

4. Runtime Environment and First-Time Setup

5. User Interface

6. Workflow

7. Parameter Reference

8. Outputs

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

1. Overview

SPAM DVC (menu entry SPAM DVC (Panel)...) is a Digital Volume Correlation (DVC) analysis plugin integrated inside Dragonfly. It computes displacement and strain fields between two spatially aligned 3D images (a reference state and a deformed state), non-destructively quantifying internal 3D deformation and strain inside a sample. Results are written back into the Dragonfly scene as new DVC_* Channels, ready for 2D/3D visualization and quantitative measurement.

The plugin runs as a dockable panel (OrsPlugin) directly inside the Dragonfly process: data is read and written in-process (no TCP, no server to start in the Python Console), and image display is left entirely to Dragonfly's own 2D/3D views. Optionally, each run also produces a Word (.docx) analysis report with parameters, slice images, statistics, and interpretation.

Underlying engine / algorithm. The compute kernel is the open-source package SPAM (Software for the Practical Analysis of Materials), a Python + C++ materials-image analysis package developed and maintained by the spam-project team (Grenoble, France; E. Andò, O. Stamati, et al.), widely used for DIC/DVC full-field deformation measurement on X-ray CT images. The plugin uses its spam.DIC (correlation), spam.deformation (deformation/strain) and spam.mesh (mesh) modules and offers two DVC algorithms: Local Subset and Global FEM, both run in WSL2.

The SPAM kernel runs under Linux (WSL2), avoiding the difficulty of compiling SPAM on Windows. The whole DVC job runs on a background worker thread, so the Dragonfly UI stays responsive during computation.

License note: SPAM is open-source software under the GPL license. Official docs: https://www.spam-project.dev/ ; source on GitLab: https://gitlab.com/spam-project/spam . Please honor the corresponding open-source license and citation requirements when using its computed results.

2. Use Cases

This plugin is ideal for in-situ CT experiments, where the same sample is imaged before and after loading (or across several deformation stages) to quantify internal displacement and strain. Typical applications include:

• Mechanics of materials: internal deformation and strain measurement during compression/tension tests on rocks, soils, foams, composites, and additive-manufactured (AM) parts.
• Biomechanics: strain-distribution studies of bone or tissue under loading.
• Industrial CT quality studies: quantifying internal deformation and strain, assessing defects, crack evolution and interface slip.
• Time-series studies: evolution of the deformation field across multiple loading stages (creep, fatigue).

Reliable DVC results require sufficiently rich and stable 3D grayscale texture — from the material's natural microstructure (pores, trabeculae, grains) or from artificially added tracer particles. The reference and deformed volumes should be the same sample at the same resolution, imaged at two stages, and already spatially registered/aligned in Dragonfly (see Chapter 6).

3. Installation and Enablement

The plugin ships with the Prototype Apps Full Package and belongs to the Measurements & Analysis group. Installation has a Dragonfly-plugin side and a WSL2 compute side; this chapter covers the plugin side, while the compute environment is covered in Chapter 4.

3.1 Install via the Full Package

1. Unzip the Full Package to any short folder (e.g. C:\PL\, to avoid path-too-long issues).

2. Double-click Install_FullPackage.bat.

3. In the dialog, pick the core install mode (Fresh = wipe & install / Compatible = keep your own blocks & recipes; this only affects the Prototype Labs core, not any plugin's environment or settings), and tick SPAM DVC in the Prototype Apps list.

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

5. Quit and restart Dragonfly completely (menus are scanned only at startup).

By default, plugins like SPAM DVC are unticked (OFF) in the install list — the light menu items are ON and all plugins are OFF. You must tick it manually at install time for it to be deployed.

3.2 Menu location

After restarting Dragonfly, the plugin appears under Prototype Apps ▸ SPAM DVC (Panel).... Clicking it opens a dockable, collapsible, floatable SPAM DVC panel on the right of Dragonfly (tab title "SPAM DVC").

3.3 Change your choices later (Menu Item Manager)

To enable or disable the plugin after installation, the easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager, and in the "Prototype Apps (Full Package)" list at the bottom, tick (deploy) or untick (remove the menu entry) SPAM DVC, then restart Dragonfly to apply.

Disabling never deletes the plugin's WSL compute environment; re-enable is instant. You can also re-run the installer anytime to change your choices (your previous selection becomes the new default).

3.4 Uninstall

Double-click Uninstall_FullPackage.bat to remove all Full-Package menu items, plugins and the central store. It keeps the Prototype Labs core and every plugin environment (venv / downloads / WSL distro), and lists their paths at the end so you can delete them manually to reclaim disk space.

4. Runtime Environment and First-Time Setup

Unlike many Prototype Apps plugins, SPAM DVC does not compute inside Dragonfly's own Python and has no "Setup Environment" button; its heavy compute kernel (SPAM) runs inside WSL2 (Windows Subsystem for Linux 2). The plugin side needs no downloads (python-docx for the report is vendored as a pure-Python copy inside the plugin), but the compute side must have a WSL2 + SPAM environment prepared once.

4.1 Prerequisites

• WSL2: required. If not installed, run wsl --install --no-distribution in an admin PowerShell and reboot; on PCs that already have WSL run wsl --update.
• Internet: not required for downloads when using the shipped prebuilt WSL environment (rootfs ~1.5 GB, provided offline in the distribution package).
• GPU: not required. DVC computation is CPU-based.
• External software: Global FEM with an unstructured mesh additionally requires Gmsh inside WSL (not needed for normal analysis).

4.2 Option A: use the shipped one-click WSL installer (recommended)

Copy the SpamDVC-WSL-Package folder from the distribution to the target PC and double-click install_spam_dvc_wsl.bat. The installer will:

1. import a compute distro named SpamDVC (a modified SPAM 0.8.1.4 + spambind + venv + worker);

2. run a smoke self-check (verifying the default user, import spam.DIC/deformation/mesh, and that the worker starts);

3. create the Windows↔WSL job-exchange folder C:\DVCJobs;

4. write the plugin config file %LOCALAPPDATA%\SpamDvc\wsl_config.json.

Afterwards, the four "Backend Engine (WSL2)" fields in the panel are auto-filled from that config file, with no manual setup needed.

4.3 Option B: build your own WSL environment (without the package)

Create a Python virtual environment in any WSL2 distro and install spam (pip package or compiled from source, see the official SPAM docs), copy the plugin's spam_dvc_worker.py into WSL (e.g. /home/<user>/spam_dvc_worker.py), then fill in the four "Backend Engine (WSL2)" fields manually (meanings in §5.4).

If the panel WSL fields still show the old hard-coded defaults (e.g. Distro = Ubuntu), it means %LOCALAPPDATA%\SpamDvc\wsl_config.json was not read: run the WSL package installer, or fill the four fields manually. Panel settings are not saved and revert to defaults / prefill each time it opens.

4.4 Install locations

• Config file: %LOCALAPPDATA%\SpamDvc\wsl_config.json (source of the panel WSL prefill).
• Job-exchange folder: C:\DVCJobs (Windows and WSL exchange data via /mnt/c/..., created by the WSL installer).
• WSL distro: named SpamDVC by default (contains the /home/dragonfly/spam_env Python and spam_dvc_worker.py).

5. User Interface

A red note is always shown at the top of the panel, reminding you to align the two volumes in Dragonfly with rigid registration first (if their geometry differs, the plugin resamples the deformed volume onto the reference grid before measuring the residual local deformation). Below it is a scrollable form arranged into the following groups.

5.1 Input (from Dragonfly)

The Channel and ROI lists refresh automatically from the live session (polled about every 2.5 s, following the current project — no manual Refresh button needed). Three dropdowns:

• Reference Channel: the reference (undeformed) volume.
• Deformed Channel: the deformed (post-load) volume.
• Processing ROI (optional): an optional ROI, default (none / full volume). When selected, the analysis is cropped to its bounding box, which can significantly speed things up and save memory.

Each entry is shown as Title [Z×Y×X] for easy identification by size.

5.2 DVC Parameters (common)

• DVC Mode: dropdown, Local Subset (WSL2) (default) or Global FEM (WSL2).
• Subset size (Local): text field, default 40. Edge length of the local correlation window (voxels).
• Node step: text field, default 15. Spacing between compute nodes (voxels).
• Margin (Local): text field, default 1. How far nodes shrink from the boundary (voxels).
• Compute strain fields: checkbox, checked by default. Whether to compute the strain field after displacement.
• Resample deformed → reference geometry (if mismatched): checkbox, checked by default. Resamples the deformed volume onto the reference grid when geometries differ.
• Auto-align mismatched volumes (crop to common size): checkbox, checked by default. Crops to a common voxel size when the two volumes differ (crop only, not registration).
• Align anchor: dropdown, Center (default) or Origin, controlling that crop's anchor.
• Grayscale preprocess: dropdown, default None; also Histogram match (def→ref), Min-max [0,1], Standardize (ZNCC).

5.3 Global FEM Parameters (used in Global mode)

• Mesh type: dropdown, currently only structured (regular hexahedral structured mesh).
• Element size: text field, default blank (placeholder "blank = auto from node step"), i.e. auto = Node step.
• Use Gmsh (optional): checkbox, unchecked by default. Enable when an unstructured mesh is needed (Gmsh must be installed in WSL).
• Global Gaussian pre-blur: checkbox, checked by default. Gaussian smoothing before computation.
• Max iterations: text field, default 20. Global iteration cap.
• Convergence criterion: text field, default 0.01. Convergence threshold.
• Enable elasticity regularisation: checkbox, checked by default. Elastic-mechanics regularization.
• Young's modulus: text field, default 0.0001. Regularization strength (empirical, no physical unit).

5.4 Backend Engine (WSL2)

Four text fields, with defaults from wsl_config.json (falling back to hard-coded defaults if absent):

• WSL Python Path: absolute path of the Python interpreter inside WSL (default /home/dragonfly/spam_env/bin/python).
• WSL Worker Path: absolute path of the worker script inside WSL (default /home/dragonfly/spam_dvc_worker.py).
• Win Job Root: the Windows job folder (default C:\DVCJobs).
• WSL Distro: distro name (default Ubuntu; usually SpamDVC after using the package).

5.5 Output

• Output dir (.npz/.json): text field, results collection directory (default C:\DVCJobs\output).
• Generate .docx report after each run: checkbox, checked by default. Generates a graphical report in the Output dir after each successful run.
• Report in Chinese (中文报告): checkbox, unchecked by default (i.e. English report); tick to produce a Chinese report.

5.6 Run / Stop and log

• Run DVC (blue button): starts a DVC computation (runs on a background thread).
• Stop (red button, enabled only while running): requests an abort; an in-progress WSL subprocess may still run to completion.
• The read-only log area at the bottom shows job-folder creation, WSL worker startup, progress percentage, result write-back, etc., and is the first place to look when troubleshooting.

6. Workflow

6.1 Data prep: register first, then DVC

This is the most important prerequisite. DVC only measures "small strains in an already-aligned state." Any overall translation/rotation between the two volumes must first be removed in Dragonfly by rigid registration / manual alignment, otherwise the result will be noise or false displacement. Note:

• the reference and deformed volumes should be the same sample at the same resolution, scanned at two stages;
• the voxel size (spacing) of the two Channels should match;
• use rigid registration upstream — deformable registration would remove the very deformation DVC measures;
• Dragonfly registration only changes geometry (origin / orientation / spacing), not the voxel grid, so the plugin resamples the deformed volume onto the reference grid when geometries differ (see the "Resample" checkbox).

6.2 End-to-end steps

1. In Dragonfly, spatially register/align the reference and deformed volumes.

2. Open the panel: Prototype Apps ▸ SPAM DVC (Panel)...; it docks on the right of Dragonfly.

3. Under "Input (from Dragonfly)", select the Reference Channel and Deformed Channel (the lists refresh automatically, no button needed); optionally select a Processing ROI to shrink the analysis region.

4. Choose the DVC Mode (Local Subset is fine the first time) and set parameters per Chapter 7 (you can keep all defaults the first time).

5. Confirm the four "Backend Engine (WSL2)" fields are correct (auto-filled when using the package), and set the "Output dir" and report options as needed.

6. Click Run DVC. The log shows job-folder creation, WSL worker startup, progress percentage, etc.; you can keep working in Dragonfly during computation, or click Stop to abort.

7. When finished, the log reports success and DVC_* result Channels appear in the Dragonfly data list (meanings in Chapter 8); if the report option is checked, a <dataname>_<timestamp>.docx report is also generated in the Output dir.

Inputs → action → outputs: inputs are two aligned 3D Channels with sufficient grayscale texture; the action is select data, set parameters, Run DVC; the outputs are the DVC_* displacement/strain Channels written back to the scene (ready for visualization and measurement), plus .npz/.json result files in the job folder and an optional .docx report.

7. Parameter Reference

The table below lists every DVC parameter in the panel with its default and meaning. Unless noted, all lengths are in voxels.

7.1 Tuning advice by data type

8. Outputs

8.1 Result Channels written back to Dragonfly

After computation the following DVC_* Channels are created automatically (same geometry as the reference data, so they can be overlaid, sliced, and measured quantitatively). Which ones appear depends on the algorithm and whether "Compute strain fields" is checked:

Suggested viewing: apply a pseudo-color LUT to a result Channel and overlay it on the reference grayscale volume; use Dragonfly's slice/histogram tools for quantitative analysis; 3D-render to see the spatial form of the deformation distribution.

8.2 Output files

Each job creates its own directory under the Job Root (C:\DVCJobs), containing this job's input data and full parameters (ref.npy/def.npy/params.json, for reproducing the analysis), the run state and progress status.json (with a full traceback on error — first stop for troubleshooting), and the displacement/strain result files.

The Output dir (default C:\DVCJobs\output) also stores a summary array .npz and its _meta.json (for later Python / MATLAB processing).

8.3 The optional .docx analysis report

If "Generate .docx report after each run" is checked, a graphical report named <dataname>_<timestamp>.docx is created in the Output dir, with 8 sections: 1) Summary and key findings; 2) About DVC; 3) About the SPAM software; 4) Methodology and parameters; 5) Input data overview (with slice images / histograms); 6) Analysis results (displacement field, strain statistics, per-field strain maps); 7) Interpretation guide; 8) Output files and compute environment. The report language is set by the "Report in Chinese" checkbox (English by default).

The report is generated on a background worker thread and is best-effort: even if it fails, it only logs a message and does not affect the DVC results or Channel write-back.

9. FAQ and Troubleshooting

10. Notes and Known Limitations

• Register first: DVC only measures small strains; any overall translation/rotation between the two volumes must be removed by rigid registration first — deformable registration would erase the deformation to be measured.
• Input only from Dragonfly: the plugin currently only selects the reference/deformed Channels from the live Dragonfly session; there is no direct file-input or synthetic-data input mode.
• Panel settings are not saved: each open reverts to defaults / prefill; using the package lets wsl_config.json avoid re-entering the WSL fields.
• Global FEM supports structured meshes only: currently Mesh type is structured; an unstructured mesh requires Gmsh in WSL plus ticking Use Gmsh.
• Displacement/strain units are voxels: DVC_Disp_Mag etc. are in voxels; convert to physical units using the voxel size if needed.
• Stop is a soft cancel: after clicking Stop, an in-progress WSL subprocess may keep running until it completes.
• Typical strain magnitudes: elastic stage ~0.1%–1%, plastic stage 10%–50%; if measured strains are far beyond expectation, suspect registration/parameter problems first.

11. References

• SPAM official docs: https://www.spam-project.dev/
• SPAM source (GitLab): https://gitlab.com/spam-project/spam
• Compute kernel version: SPAM 0.8.1.4 (locally modified) + spambind 0.8.2, running on WSL2 Ubuntu; license GPL.
• Supported Dragonfly versions: 2025.1 / 2027.1 (both PyQt6 6.7.1, Python 3.10.13).
• Full install / enable instructions: the Full Package README and the install dialog; plugin group Measurements & Analysis.