二维数字图像相关 (muDIC) 插件用户手册

Digital Image Correlation 2D (muDIC) - User Manual

Dragonfly Prototype Apps · Digital Image Correlation 2D (muDIC)...

版本 Version 1.0 · 2026-07-09

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

二维数字图像相关 (muDIC) 是一个 Dragonfly 插件,对二维图像序列执行全场数字图像相关 (Digital Image Correlation, DIC) 分析。你选择一个 Channel(其 Z 轴或 T 轴是一组连续的二维帧图像),设置参考帧序号、网格单元尺寸、可选的 ROI 范围与应变度量方式,点击 Compute DIC;插件会在参考帧上构建一张 Q4 四边形网格,运行相关分析,得到每一帧相对参考帧的位移场(u、v)与应变场(exx、eyy、exy),并将这些场重新采样回原图像素栅格后作为新的 Channel 发布到 Dragonfly 场景中。

底层计算引擎为开源库 muDIC(项目地址 github.com/PolymerGuy/muDIC,MIT 许可证)。其标准处理管线是:图像序列 → 构建 Q4 网格 (Mesher) → 装配相关输入 (DICInput) → 运行分析 (DICAnalysis().run()) → 提取场 (Fields)。muDIC 依赖 numpy(BSD)、scipy(BSD)、matplotlib(PSF/BSD 风格许可证)。

本插件专注于二维表面变形。它与用于三维体积相关 (Digital Volume Correlation, DVC) 的 SPAM-DVC 插件是两个不同的工具:muDIC 处理二维图像序列的面内变形,SPAM-DVC 处理三维体数据之间的体积变形。

许可证要点:插件代码遵循与 DragonflyPrototypeLabs 仓库相同的条款;计算引擎 muDIC 为 MIT 许可证(宽松);numpy / scipy 为 BSD;matplotlib 为 PSF/BSD 风格许可证。所有依赖均为宽松开源许可,不含 GPL 组件。

2. 适用场景

本插件适用于材料力学与实验力学中的二维全场变形测量,即从一组随加载/时间变化的表面图像中提取位移与应变分布。典型用途包括:

• 拉伸 / 压缩试验的表面应变分布测量与可视化;
• 裂纹尖端场分析(裂纹附近的位移与应变集中);
• 复合材料与薄板金属变形研究;
• 原位加载 (in-situ) CT 或显微成像序列的表面变形分析;
• 任何具有随机散斑或天然纹理、且随载荷逐帧记录的二维图像序列的变形定量。

输入的图像序列应具有足够的表面纹理或散斑图案,以便相关算法在相邻帧之间跟踪局部灰度模式。纯净、无纹理的区域无法可靠地相关。

3. 安装与启用

本插件随 Prototype Apps 完整安装包 (Full Package) 分发。按以下步骤安装:

1. 将完整安装包解压到任意较短的目录(例如 C:\PL\,避免过深的路径导致 Windows 路径过长报错)。

2. 双击运行 `Install_FullPackage.bat`。

3. 在弹出的对话框中选择核心安装模式(Fresh 全新安装 / Compatible 兼容安装),并勾选要启用的 Prototype Apps。

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

5. 完全重启 Dragonfly(彻底退出后重新打开)。

重要:在安装器的应用列表里,所有插件默认为未勾选(关闭)状态。要使用本插件,你必须在安装时手动勾选 “Digital Image Correlation 2D (muDIC)...”,否则重启后菜单中不会出现它。

重启后,插件出现在 Dragonfly 主菜单的 Prototype Apps ▸ Digital Image Correlation 2D (muDIC)...(位于 “Measurements & Analysis” 分组)。点击即可打开一个可停靠(浮动)的面板。

以后修改是否启用

最方便的方式是在 Dragonfly 内修改:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部的 “Prototype Apps (Full Package)” 列表里勾选=部署本插件、取消勾选=移除其菜单项,然后重启 Dragonfly 生效。停用从不删除插件已搭好的计算环境,重新启用后立即可用。也可以随时重跑安装器(会记住上次的勾选作为默认值)。

卸载

双击 `Uninstall_FullPackage.bat` 即可移除所有 Full Package 的菜单项与插件。卸载会保留每个插件已搭建的计算环境(venv),需要腾出磁盘空间时可按脚本结束时列出的路径手动删除。

4. 运行环境与首次配置

为避免污染 Dragonfly 自带的 Python,本插件把繁重的计算隔离在一个专用虚拟环境 (venv) 中运行。这个环境不随安装器下载,而是在首次使用时由你在面板里手动构建一次。

Setup Environment 具体做什么

在面板的 “Environment (muDIC venv)” 分组里点击 Setup Environment 按钮后,插件会:

1. 在插件的安装代码目录内创建一个名为 venv 的虚拟环境,默认以 Dragonfly 自带的 Python 作为基础解释器(Dragonfly 2025.1 / 2027.1 均内置完整的 CPython 3.10,其标准库 venv 与 pip 可用,因此无需另外安装 Python);

2. 升级该 venv 内的 pip、setuptools、wheel;

3. 从默认 PyPI 源联网安装 muDIC + numpy + scipy + matplotlib(不含 CUDA);

4. 做一次导入自检,确认各库可用;

5. 记录该 venv 的 Python 解释器路径,供后续计算直接调用。

配置成功后,“Status” 一行会显示 Ready: <venv 内 python 的路径>;配置前显示提示 “Not set up - click 'Setup Environment'...”。这一步只需执行一次,之后每次计算都会复用同一个环境。

联网 / GPU / WSL / 外部软件需求

环境安装位置

venv 建立在本插件的安装代码目录内,即 %LOCALAPPDATA%\comet\<Dragonfly 版本>\pythonUserExtensions\GenericMenuItems\MuDIC\venv。计算时产生的临时作业目录(输入 input.npy、中间 status.json、结果 results.json 与各场的 .npy)位于系统临时目录下、以 mudic_ 为前缀的文件夹中。

失败时的替代方案

如果默认的 Dragonfly 自带 Python 无法构建 venv(例如缺少标准库 venv 模块),可在面板的 Base Python 字段填入另一个 CPython 3.10 或更高版本的解释器路径(例如 C:\Python312\python.exe),或形如 py -3.11 的启动器命令,再重新点击 Setup Environment。留空即表示使用当前 Dragonfly 的 Python。

5. 界面说明

面板从上到下由若干分组构成,逐一说明如下。

输入图像序列 (Input image sequence)

• Channel 下拉框:列出当前 Dragonfly 场景中的所有 Channel,每项显示标题与形状(如 名称 (30x512x512))。选择一个其 Z/T 轴为一组二维帧的 Channel 作为输入。
• Refresh 按钮:重新读取场景中的 Channel 列表(在 Dragonfly 中新载入图像后点击刷新)。

DIC 参数 (DIC parameters)

• Reference frame index(参考帧序号,数值框):沿 Z/T 轴的未变形参考帧的序号;所有位移都相对该帧测量。取值范围随所选 Channel 的帧数自动限定,默认 0。
• Mesh element size (px)(网格单元尺寸,数值框):Q4 网格单元的边长(像素)。范围 4–256,步长 2,默认 16。数值越小,场越精细但越易受噪声影响;越大则越平滑。
• Strain measure(应变度量,下拉框):从位移梯度推导应变的方式,可选 Engineering(工程/小应变)、Green-Lagrange、True(对数/真实应变),默认 Green-Lagrange。

ROI 范围 (ROI extent)

• Limit correlation to a rectangular ROI(复选框):默认未勾选,表示对整帧进行相关。勾选后可将相关限制在一个矩形像素窗口内。
• Extent(四个数值框 y0 / y1 / x0 / x1):矩形 ROI 的像素边界。仅在勾选上面的复选框时可编辑;上限随所选 Channel 的高/宽自动设置,默认覆盖整帧。

发布结果通道 (Publish result channels)

• Displacement u, v(复选框):是否发布位移分量 u、v(2 个逐帧堆栈 Channel),默认勾选。
• Strain exx, eyy, exy(复选框):是否发布应变分量 exx、eyy、exy(3 个逐帧堆栈 Channel),默认勾选。

环境 (Environment: muDIC venv)

• Base Python(文本框):可选,填入用于构建 venv 的基础解释器路径或命令;留空表示使用当前 Dragonfly 的 Python。
• Status:显示环境是否就绪(Ready 加路径 / 尚未配置的提示)。

操作按钮与输出区

• Setup Environment 按钮:构建 venv 并安装依赖(见第 4 章)。
• Compute DIC 按钮:用当前参数运行二维 DIC 计算。
• 摘要行:计算完成后显示引擎名称、帧数、参考帧、单元尺寸、应变度量与最大位移幅值等汇总信息。
• 日志文本框:只读,显示进度、发布的 Channel 名称以及错误信息。

6. 使用步骤

完整的端到端工作流如下。

输入要求

在 Dragonfly 中载入一个二维图像序列作为 Channel:其 Z 轴(或 T 轴)是一组连续的二维帧,至少 2 帧,通常第一帧或某一帧为未变形的参考状态。图像应含有可供跟踪的散斑或纹理。

首次配置(仅一次)

1. 打开 Prototype Apps ▸ Digital Image Correlation 2D (muDIC)...。

2. (可选)在 Base Python 填入自定义解释器;通常留空即可。

3. 点击 Setup Environment,等待日志显示 “Environment ready” 且 Status 变为 Ready。

运行一次 DIC 分析

1. 在 Channel 下拉框选择要分析的图像序列(如需要,先点 Refresh 刷新列表)。

2. 设置 Reference frame index(参考帧序号)。

3. 设置 Mesh element size (px)(网格单元尺寸);先用默认 16,视需要调整。

4. 选择 Strain measure(应变度量);默认 Green-Lagrange。

5. (可选)勾选 Limit correlation to a rectangular ROI 并填入 y0/y1/x0/x1,把计算限制在感兴趣的矩形区域。

6. 在 Publish result channels 中选择要发布位移和/或应变。

7. 点击 Compute DIC,在日志区观察进度。

8. 计算完成后,新的结果 Channel 会自动出现在 Dragonfly 场景中(无需重启),摘要行显示统计信息。

提示:先用较大的单元尺寸(如 32)和整帧运行一次做快速预览,确认结果合理后再减小单元尺寸或限定 ROI 以获得更精细的场。

7. 参数说明

关于应变度量的推导(基于位移梯度 du/dx、du/dy、dv/dx、dv/dy):Engineering 取小应变近似,exx=du/dx、eyy=dv/dy、exy=0.5(du/dy+dv/dx);Green-Lagrange 包含二次项,适合较大变形;True(对数/Hencky) 对法向应变取对数拉伸,剪切分量按工程应变处理。

8. 输出结果

计算完成后,插件把拟合得到的位移/应变场重新采样回与输入帧对齐的完整像素栅格,并作为新的 Channel 发布(保持源 Channel 的空间几何,即像素间距 spacing 与原点 origin)。发布的对象根据勾选情况包括:

每个输出都是与输入同形状的 (帧数, 高, 宽) 堆栈,参考帧对应的那一层为零(参考状态无位移/应变)。

如何查看

• 在 Dragonfly 场景/对象树中找到上述新 Channel;
• 为其应用色图 (colormap / LUT) 以可视化位移或应变的空间分布;
• 逐帧浏览堆栈,观察随加载/时间的变化;
• 结合 Dragonfly 的测量与统计工具进一步分析。

此外,面板底部的摘要行会报告本次计算所用的引擎、帧数、参考帧、单元尺寸、应变度量以及最大位移幅值;日志区列出实际发布的 Channel 名称。

9. 常见问题与故障排除

Q1:菜单里找不到本插件

A:请确认安装时勾选了 “Digital Image Correlation 2D (muDIC)...”(所有插件默认未勾选),并且安装后完全重启了 Dragonfly(菜单只在启动时扫描)。也可在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 中勾选后重启。

Q2:点击 Compute DIC 提示环境未配置

A:日志出现 “environment not set up. Click 'Setup Environment' first.” 表示尚未构建 venv。请先在面板里点击 Setup Environment 并等待其完成(首次需联网)。若 Status 一直不显示 Ready,查看日志中的错误信息。

Q3:Setup Environment 失败

A:常见原因是基础 Python 缺少标准库 venv,或联网/PyPI 访问受阻。日志会给出错误码与提示。可在 Base Python 字段指定另一个 CPython 3.10+ 的解释器(如 C:\Python312\python.exe)后重试;并确保安装期间网络可访问 PyPI。

Q4:提示内存不足 (Out of memory)

A:当帧数很多或分辨率很高时可能耗尽内存。日志会提示 “Out of memory - try a smaller ROI or fewer frames.”。可勾选 ROI 只处理感兴趣的矩形区域、减少参与的帧数,或适当增大网格单元尺寸以降低计算量。

Q5:结果场几乎全为零或明显不合理

A:请检查:输入序列是否确有帧间变形;图像是否具备足够的散斑/纹理供跟踪;参考帧序号是否选对;网格单元尺寸是否过大(过大则丢失细节)或过小(过小则噪声大)。先用整帧、默认单元尺寸预跑一次再逐步细化。

Q6:下拉框里没有 Channel

A:说明当前场景没有可用的图像序列。请先在 Dragonfly 中载入一个 Z/T 轴为二维帧序列的图像,再回到面板点击 Refresh。

10. 注意事项与已知限制

• 本插件为二维面内 DIC;三维体积相关请使用 SPAM-DVC 插件。
• 输入至少需 2 帧;单帧无法进行相关分析。
• 计算质量依赖图像的散斑/纹理质量;无纹理区域无法可靠相关。
• 参考帧对应的输出层恒为零(定义为未变形基准)。
• 位移单位为像素 (px);若需换算为物理长度,请结合源图像的像素间距 (spacing) 自行换算。
• 网格单元尺寸在精度与噪声之间权衡:小=细节多但噪声大,大=平滑但可能漏掉局部集中。
• 首次使用需联网一次以安装依赖;安装内容仅进入插件专用 venv,不会改动 Dragonfly 自带的 Python。
• 全部计算在 CPU 上完成,不使用 GPU;大数据集可能耗时较长。

11. 参考资料

• muDIC 项目主页(MIT 许可证):https://github.com/PolymerGuy/muDIC
• numpy:https://numpy.org(BSD)
• scipy:https://scipy.org(BSD)
• matplotlib:https://matplotlib.org(PSF/BSD 风格许可证)
• 完整安装 / 启用 / 卸载说明:见 Prototype Apps 完整安装包根目录的 UserManual_用户手册.docx 总手册。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation & Enabling

4. Environment & First-Run Setup

5. Interface Guide

6. Usage Steps

7. Parameter Reference

8. Outputs

9. FAQ & Troubleshooting

10. Notes & Known Limitations

11. References

1. Overview

Digital Image Correlation 2D (muDIC) is a Dragonfly plugin that performs full-field Digital Image Correlation (DIC) on a 2D image sequence. You pick a Channel whose Z (or T) axis is a stack of consecutive 2D frames, set the reference frame index, mesh element size, an optional ROI extent, and a strain measure, then click Compute DIC. The plugin builds a Q4 quadrilateral mesh on the reference frame, runs the correlation analysis, and produces per-frame displacement fields (u, v) and strain fields (exx, eyy, exy) relative to the reference. These fields are resampled back onto the original pixel grid and published as new Channels in the Dragonfly scene.

The underlying compute engine is the open-source library muDIC (project: github.com/PolymerGuy/muDIC, MIT license). Its standard pipeline is: image stack → build Q4 mesh (Mesher) → assemble correlation input (DICInput) → run analysis (DICAnalysis().run()) → extract fields (Fields). muDIC depends on numpy (BSD), scipy (BSD), and matplotlib (PSF/BSD-style).

This plugin is dedicated to 2D surface deformation. It is a different tool from the SPAM-DVC plugin, which performs Digital Volume Correlation (DVC) on 3D data: muDIC handles in-plane deformation of a 2D image sequence, while SPAM-DVC handles volumetric deformation between 3D volumes.

License summary: the plugin code follows the same terms as the DragonflyPrototypeLabs repository; the muDIC engine is MIT-licensed (permissive); numpy / scipy are BSD; matplotlib is PSF/BSD-style. All dependencies are permissive open-source with no GPL components.

2. Use Cases

The plugin targets 2D full-field deformation measurement in materials and experimental mechanics - extracting displacement and strain distributions from a set of surface images recorded under changing load or time. Typical uses include:

• Tensile / compression tests - measuring and visualizing the surface strain field;
• Crack-tip fields - displacement and strain concentration near a crack;
• Composites and sheet-metal deformation studies;
• In-situ loading CT or microscopy image sequences - surface deformation analysis;
• Any 2D image sequence with random speckle or natural texture recorded frame-by-frame under load.

The input sequence should have enough surface texture or speckle pattern for the correlation algorithm to track local grayscale patterns between adjacent frames. Clean, texture-free regions cannot be correlated reliably.

3. Installation & Enabling

The plugin ships with the Prototype Apps Full Package. Install it as follows:

1. Unzip the Full Package to any short path (e.g. C:\PL\) to avoid Windows path-too-long errors from deep folders.

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, choose the core install mode (Fresh = clean install / Compatible = keep your own blocks & recipes) and tick the Prototype Apps you want to enable.

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

5. Fully restart Dragonfly (quit completely, then reopen).

Important: in the installer's app list, all plugins are unticked (OFF) by default. To use this plugin you must manually tick "Digital Image Correlation 2D (muDIC)..." at install time, otherwise it will not appear in the menu after restart.

After the restart, the plugin appears under the Dragonfly menu at Prototype Apps ▸ Digital Image Correlation 2D (muDIC)... (in the "Measurements & Analysis" group). Clicking it opens a dockable (floating) panel.

Changing your choices later

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 this plugin, untick = remove its menu entry, then restart Dragonfly to apply. Disabling never deletes the plugin's built environment; re-enabling is instant. You can also re-run the installer anytime (it remembers your previous choices as the new defaults).

Uninstall

Double-click `Uninstall_FullPackage.bat` to remove all Full-Package menu items and plugins. Uninstalling keeps each plugin's built environment (venv); to reclaim disk space, delete it manually using the paths listed at the end of the script.

4. Environment & First-Run Setup

To avoid polluting Dragonfly's bundled Python, the plugin isolates the heavy compute in a dedicated virtual environment (venv). This environment is not downloaded by the installer; instead you build it once, from the panel, on first use.

What Setup Environment does

When you click the Setup Environment button in the panel's "Environment (muDIC venv)" group, the plugin:

1. Creates a venv inside the plugin's installed code directory, using Dragonfly's own Python as the default base interpreter (Dragonfly 2025.1 / 2027.1 both bundle a full CPython 3.10 whose stdlib venv + pip work, so no separate Python install is needed);

2. Upgrades pip, setuptools, and wheel inside that venv;

3. Installs muDIC + numpy + scipy + matplotlib from the default PyPI index over the internet (no CUDA);

4. Runs an import self-check to confirm the libraries are usable;

5. Records the venv's Python interpreter path for subsequent computations.

On success, the "Status" line shows Ready: <path to the venv's python>; before setup it shows the hint "Not set up - click 'Setup Environment'...". This step runs only once; every later computation reuses the same environment.

Internet / GPU / WSL / external software

Where the environment is installed

The venv is created inside the plugin's installed code directory: %LOCALAPPDATA%\comet\<Dragonfly version>\pythonUserExtensions\GenericMenuItems\MuDIC\venv. Temporary job files produced during a computation (input input.npy, intermediate status.json, result results.json, and per-field .npy files) live in a folder prefixed with mudic_ under the system temp directory.

Fallback when setup fails

If the default Dragonfly Python cannot build the venv (e.g. its stdlib venv module is missing), enter the path of another CPython 3.10 or newer interpreter (e.g. C:\Python312\python.exe) or a launcher command such as py -3.11 in the panel's Base Python field, then click Setup Environment again. Leaving it blank uses the current Dragonfly's Python.

5. Interface Guide

The panel is organized top-to-bottom into several groups, described below.

Input image sequence

• Channel dropdown: lists every Channel in the current Dragonfly scene, each showing its title and shape (e.g. name (30x512x512)). Select a Channel whose Z/T axis is a stack of 2D frames.
• Refresh button: re-reads the Channel list from the scene (click after loading a new image in Dragonfly).

DIC parameters

• Reference frame index (spinbox): index of the undeformed reference frame along the Z/T axis; all displacement is measured relative to it. Range auto-limited by the selected Channel's frame count; default 0.
• Mesh element size (px) (spinbox): Q4 mesh element edge length in pixels. Range 4-256, step 2, default 16. Smaller = finer but noisier field; larger = smoother.
• Strain measure (dropdown): how strain is derived from the displacement gradient - Engineering (small strain), Green-Lagrange, or True (logarithmic); default Green-Lagrange.

ROI extent

• Limit correlation to a rectangular ROI (checkbox): unticked by default (full frame). Tick it to confine correlation to a rectangular pixel window.
• Extent (four spinboxes y0 / y1 / x0 / x1): pixel bounds of the rectangular ROI. Editable only when the checkbox is ticked; upper limits are set from the selected Channel's height/width and default to the full frame.

Publish result channels

• Displacement u, v (checkbox): whether to publish displacement components u, v (2 per-frame stack Channels); ticked by default.
• Strain exx, eyy, exy (checkbox): whether to publish strain components exx, eyy, exy (3 per-frame stack Channels); ticked by default.

Environment (muDIC venv)

• Base Python (text field): optional; the base interpreter path or command used to build the venv; blank = the current Dragonfly's Python.
• Status: shows whether the environment is ready (Ready + path, or a not-set-up hint).

Action buttons & output area

• Setup Environment button: builds the venv and installs dependencies (see Chapter 4).
• Compute DIC button: runs the 2D DIC computation with the current parameters.
• Summary line: after a computation, reports the engine, frame count, reference frame, element size, strain measure, and max displacement magnitude.
• Log text box: read-only; shows progress, published Channel names, and error messages.

6. Usage Steps

The complete end-to-end workflow is as follows.

Input requirements

Load a 2D image sequence as a Channel in Dragonfly: its Z axis (or T axis) is a stack of consecutive 2D frames, at least 2 frames, with one frame (often the first) representing the undeformed reference state. The images should contain trackable speckle or texture.

First-time setup (once)

1. Open Prototype Apps ▸ Digital Image Correlation 2D (muDIC)....

2. (Optional) Enter a custom interpreter in Base Python; usually leave it blank.

3. Click Setup Environment and wait until the log shows "Environment ready" and Status becomes Ready.

Run a DIC analysis

1. In the Channel dropdown, select the image sequence to analyze (click Refresh first if needed).

2. Set the Reference frame index.

3. Set the Mesh element size (px); start with the default 16 and adjust as needed.

4. Choose the Strain measure; default is Green-Lagrange.

5. (Optional) Tick Limit correlation to a rectangular ROI and enter y0/y1/x0/x1 to confine computation to a region of interest.

6. In Publish result channels, choose displacement and/or strain.

7. Click Compute DIC and watch progress in the log area.

8. When finished, the new result Channels appear automatically in the Dragonfly scene (no restart needed), and the summary line shows statistics.

Tip: do a quick preview with a larger element size (e.g. 32) over the full frame first; once the result looks reasonable, decrease the element size or confine the ROI for a finer field.

7. Parameter Reference

About how strain is derived (from the displacement gradients du/dx, du/dy, dv/dx, dv/dy): Engineering uses the small-strain approximation, exx=du/dx, eyy=dv/dy, exy=0.5(du/dy+dv/dx); Green-Lagrange includes quadratic terms and suits larger deformation; True (logarithmic/Hencky) takes the log of the normal stretch, with the shear component treated as engineering shear.

8. Outputs

When the computation finishes, the plugin resamples the fitted displacement/strain fields back onto the full pixel grid aligned with the input frames and publishes them as new Channels (preserving the source Channel's spatial geometry - pixel spacing and origin). Depending on your selections, the published objects are:

Each output is a (frames, H, W) stack matching the input shape, and the layer corresponding to the reference frame is zero (the reference state has no displacement/strain).

How to view

• Find the new Channels in the Dragonfly scene / object tree;
• Apply a colormap (LUT) to visualize the spatial distribution of displacement or strain;
• Scrub through the stack frame-by-frame to observe the change under load/time;
• Combine with Dragonfly's measurement and statistics tools for further analysis.

In addition, the summary line at the bottom of the panel reports the engine, frame count, reference frame, element size, strain measure, and max displacement magnitude used for this run; the log area lists the actually published Channel names.

9. FAQ & Troubleshooting

Q1: I can't find the plugin in the menu

A: Make sure you ticked "Digital Image Correlation 2D (muDIC)..." during installation (all plugins are unticked by default), and that you fully restarted Dragonfly afterwards (menus are scanned only at startup). You can also enable it via Developer ▸ Prototype Labs... ▸ Menu Item Manager and restart.

Q2: Compute DIC says the environment is not set up

A: The log message "environment not set up. Click 'Setup Environment' first." means the venv has not been built. Click Setup Environment first and wait for it to finish (internet is needed the first time). If Status never turns Ready, check the error message in the log.

Q3: Setup Environment fails

A: Common causes are a base Python missing the stdlib venv module, or blocked internet/PyPI access. The log shows an error code and hint. Point the Base Python field at another CPython 3.10+ interpreter (e.g. C:\Python312\python.exe) and retry, and make sure PyPI is reachable during setup.

Q4: It reports Out of memory

A: With many frames or very high resolution, memory can run out. The log shows "Out of memory - try a smaller ROI or fewer frames." Tick the ROI to process only the region of interest, reduce the number of frames involved, or increase the mesh element size to lower the compute load.

Q5: The result field is nearly all zeros or clearly unreasonable

A: Check that the input sequence actually contains frame-to-frame deformation; that the images have enough speckle/texture to track; that the reference frame index is correct; and that the mesh element size is neither too large (loses detail) nor too small (noisy). Do a preview run over the full frame at the default element size, then refine gradually.

Q6: The Channel dropdown is empty

A: There is no usable image sequence in the current scene. Load an image whose Z/T axis is a 2D frame sequence in Dragonfly, then return to the panel and click Refresh.

10. Notes & Known Limitations

• This plugin is 2D in-plane DIC; for 3D volume correlation use the SPAM-DVC plugin.
• The input needs at least 2 frames; a single frame cannot be correlated.
• Result quality depends on the image's speckle/texture quality; texture-free regions cannot be correlated reliably.
• The output layer for the reference frame is always zero (defined as the undeformed baseline).
• Displacement is in pixels (px); to convert to physical length, use the source image's pixel spacing yourself.
• The mesh element size trades accuracy against noise: small = more detail but noisier, large = smoother but may miss local concentrations.
• First use requires internet once to install dependencies; installed content goes only into the plugin's dedicated venv and does not modify Dragonfly's own Python.
• All computation runs on the CPU, not the GPU; large datasets can take a while.

11. References

• muDIC project (MIT license): https://github.com/PolymerGuy/muDIC
• numpy: https://numpy.org (BSD)
• scipy: https://scipy.org (BSD)
• matplotlib: https://matplotlib.org (PSF/BSD-style)
• Full install / enable / uninstall guide: see the UserManual_用户手册.docx overview manual in the root of the Prototype Apps Full Package.