Full-field displacement and strain measurement with adaptive mesh refinement,
ADMM global–local optimization, and a built-in desktop GUI.
🌍 Now available in 8 languages
Standard subset-based DIC (IC-GN) solves each node independently — accurate for small deformations, but struggles with large displacement gradients, discontinuities, and noisy images. pyALDIC uses an Augmented Lagrangian (ADMM) framework that couples local IC-GN subproblems with a global FEM regularizer, producing smoother, more accurate fields while maintaining sub-pixel precision.
A complete desktop application built with PySide6. Three-column layout with image list, ROI tools, and parameter controls on the left — interactive zoom/pan canvas in the center — run controls, field overlay, and console log on the right. Load images, draw ROIs, configure parameters, run DIC, and visualize results — all without writing a single line of code.
End-to-end GUI walkthrough — click the full-HD MP4 for maximum clarity.
Quadtree mesh refinement with 5 built-in criteria: mask boundary, ROI edge, brush region, manual selection, and posterior error. Concentrates computational effort where it matters — near boundaries, discontinuities, and high-gradient regions.
Run traditional local IC-GN (fast, independent nodes) or full AL-DIC with ADMM global–local coupling (regularized, smoother). Switch between modes with a single parameter — same GUI, same workflow.
Accumulative mode — every frame compared to the first reference (best for small, monotonic deformation). Incremental mode — each frame compared to the previous (handles large cumulative deformation with automatic displacement composition and mask warping).
Accumulative vs incremental tracking — demo coming soon
Near mask boundaries, standard square subsets include invalid pixels. pyALDIC automatically detects partially masked subsets, splits them using connected-component analysis, and solves IC-GN on the valid region only — with Hessian conditioning checks to ensure reliability.
For large inter-frame displacement (> 50 px) or discontinuous fields (cracks, shear bands), the default FFT-every-node search becomes slow and error-prone near discontinuities. Select Starting Points in the Initial-Guess panel, place one or more points per connected mask region on the canvas (manually or via Auto-place), and pyALDIC bootstraps each point with a single-point cross-correlation, then propagates the displacement field along mesh neighbours using F-aware (first-order) extrapolation. On a 512×512 speckle with 100 px rigid translation, this is ~3× faster than FFT with auto-expand, and crucially doesn't pick the wrong side of a crack. Every region must hold at least one point (yellow → green) before the Run button enables.
The classical whole-field initial-guess method is also built in. Each node carries its own FFT cross-correlation against the deformed image, and the peak of the combined cross-power spectrum pins down the rigid-body component in one pass. Choose it when deformation is small-to-moderate and the mesh is dense — one FFT over the whole field is cheaper than per-node searches.
Full-field displacement and strain overlay with configurable colormaps, alpha blending, and deformed configuration display. Export to MATLAB .mat, NumPy .npz, CSV, PNG field maps, animated GIF/MP4, and PDF reports.
GUI visualization and export — demo coming soon
| pyALDIC | Ncorr | DICe | VIC-2D | MatchID | |
|---|---|---|---|---|---|
| Formulation | Hybrid local + global (ALDIC) | Local (subset) | Local (subset) | Local (subset) | Local (subset) |
| Grid | Adaptive refined grid | Uniform grid | Uniform grid | Uniform grid | Uniform grid |
| GUI | Built-in desktop | Built-in desktop¹ | Built-in desktop | Built-in desktop | Built-in desktop |
| Platform | Windows, macOS, Linux | Windows, macOS, Linux¹ | Windows, macOS, Linux | Windows only | Windows only |
| Latest release² | v0.3 (2026) | v1.2.2 (2017) | v3.0-beta (2023) | VIC-2D 7 (2022) | MatchID 2D (2026) |
| Cost | Free | Free¹ | Free | Commercial | Commercial |
¹ Requires a MATLAB license.
² Compiled from public web sources and may be inaccurate. Last verified: 2026-04-20.
pyALDIC implements the Augmented Lagrangian DIC (AL-DIC) method. Quantitative accuracy, convergence, and noise-robustness characterization — including synthetic-speckle ground-truth studies and comparisons against classical subset-based DIC — are reported in the peer-reviewed literature:
-
Yang, J. & Bhattacharya, K. Augmented Lagrangian Digital Image Correlation. Experimental Mechanics 59, 187–205 (2019). doi:10.1007/s11340-018-00457-0 — original AL-DIC paper, 145+ citations.
-
Tong, Z. et al. 3D Stereo Adaptive Mesh Augmented Lagrangian Digital Image Correlation. Experimental Mechanics (2025). doi:10.1007/s11340-025-01225-7 — 3D stereo extension of the AL-DIC framework.
The AL-DIC method was also independently evaluated in the community benchmark DIC Challenge 2.0 — Reu et al., "DIC Challenge 2.0: developing images and guidelines for evaluating accuracy and resolution of 2D analyses: focus on the metrological efficiency indicator", Experimental Mechanics. doi:10.1007/s11340-021-00806-6
| Config | Nodes | Solver Time | Throughput | Pipeline FPS† |
|---|---|---|---|---|
| 256², step=8 | 784 | 0.04 s | ~20,000 POIs/s | ~5 |
| 512², step=8 | 3,600 | 0.17 s | ~22,000 POIs/s | ~1 |
| 512², step=4 | 14,400 | 0.57 s | ~25,000 POIs/s | ~0.2 |
| 1024², step=4 | 61,504 | 2.7 s | ~23,000 POIs/s | ~0.06 |
†Solver Time = IC-GN + ADMM (3 iterations), excluding precomputation. Pipeline FPS = full per-frame pipeline (FFT init + IC-GN + ADMM), excluding strain. Numba JIT, post-warmup; first run adds ~0.5 s for compilation. Using Local DIC mode (no ADMM) is ~3× faster.
Three equivalent paths; requires Python >= 3.10.
From PyPI (recommended):
pip install al-dicFrom a GitHub Release wheel (useful behind firewalls, or for installing a specific past version):
- Download
al_dic-<version>-py3-none-any.whlfrom the releases page. - Install locally:
pip install ./al_dic-<version>-py3-none-any.whlFrom source (editable install with test dependencies):
git clone https://github.com/zachtong/pyALDIC.git
cd pyALDIC
pip install -e ".[dev]"al-dic
# or
python -m al_dicProgrammatic API
from pathlib import Path
from al_dic.core.config import dicpara_default
from al_dic.core.pipeline import run_aldic
from al_dic.io.io_utils import load_images, load_masks
from al_dic.export.export_npz import export_npz
from al_dic.export.export_mat import export_mat
# Load images and masks
images = load_images("path/to/images", pattern="*.tif")
masks = load_masks("path/to/masks", pattern="*.tif")
# Configure and run
para = dicpara_default(winsize=32, winstepsize=16)
result = run_aldic(para, images, masks, compute_strain=True)
# Access results
for i, fr in enumerate(result.result_disp):
print(f"Frame {i}: max disp = {abs(fr.U).max():.4f} px")
# Export to .npz and .mat
out = Path("output")
fields = ["disp_u", "disp_v", "strain_exx", "strain_eyy", "strain_exy"]
export_npz(out, "result", "run01", result, fields=fields)
export_mat(out, "result", "run01", result, fields=fields)Project Structure
src/al_dic/
├── core/ Pipeline, config, data structures, frame scheduling
├── gui/ PySide6 GUI application
│ ├── controllers/ Image, ROI, pipeline, visualization controllers
│ ├── dialogs/ Batch import, export dialogs
│ ├── panels/ Canvas area, left/right sidebars
│ └── widgets/ Image list, parameter panel, ROI toolbar, frame nav
├── io/ Image I/O and utilities
├── mesh/ Quadtree mesh generation, refinement criteria
│ └── criteria/ Mask boundary, ROI edge, brush region, manual selection
├── solver/ IC-GN, ADMM (Subpb1/Subpb2), FFT search, FEM assembly
├── strain/ Strain computation, deformation gradient, smoothing
└── utils/ Interpolation, outlier detection, mask warping
tests/ 86 test files, 800+ tests
Testing
# Run all tests
pytest
# Run with parallel workers
pytest -n auto
# Run specific module
pytest tests/test_solver/test_icgn_solver.pypyALDIC is developed in Dr. Jin Yang's group at The University of Texas at Austin.
Beyond pyALDIC itself, the authors have contributed to community-wide DIC standards:
- Jin Yang — co-editor of A Good Practices Guide for Digital Image Correlation, 1st edition (2018) and 2nd edition (2025), published by the International Digital Image Correlation Society (iDICs).
- Zixiang Tong — co-editor of A Good Practices Guide for Digital Image Correlation, 2nd edition (2025).
Come say hi — questions, bug reports, feature ideas, and general discussion are all welcome.
GitHub Discussions — the long-form, searchable Q&A home for pyALDIC.
- Q&A — how do I use pyALDIC for X?
- Ideas — feature proposals and design talk
- Show and tell — share your experiments and figures
- Announcements — release notes and news
Both English and 中文 posts are welcome; please tag Chinese posts with [中文] in the title for easy filtering.
| Audience | Platform | Join |
|---|---|---|
| 🌍 International | Discord | discord.gg/Uh9RXvZt6n |
| 🇨🇳 中文用户 | QQ 群 | 群号 1061177356 |
GitHub Issues — use the bug-report template. Usage questions should go to Discussions, not Issues.
For research collaboration, confidential data, or one-on-one consulting: zachtong@utexas.edu.
If you use pyALDIC in your research, please cite:
@software{tong2026pyaldic_software,
author = {Tong, Zixiang and Yang, Jin},
title = {pyALDIC: Augmented Lagrangian Digital Image Correlation in Python},
year = {2026},
doi = {10.5281/zenodo.19521071},
url = {https://github.com/zachtong/pyALDIC}
}Contributions are welcome! See CONTRIBUTING.md for guidelines.
- Based on the AL-DIC MATLAB implementation by Dr. Jin Yang
- Developed at The University of Texas at Austin
BSD 3-Clause. See LICENSE for details.