al-dic 0.4.0

AL-DIC: Augmented Lagrangian Digital Image Correlation with adaptive quadtree mesh

Full-field displacement and strain measurement with adaptive mesh refinement,
ADMM global–local optimization, and a built-in desktop GUI.

---

Why pyALDIC?

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.

---

Key Features

User-Friendly GUI

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.

Adaptive Spatial Refinement

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.

Dual Solver: Local DIC + AL-DIC

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.

Dual Tracking Modes

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

Window Splitting (Masked Subsets)

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.

Starting Points (Seed Propagation)

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.

FFT Initial Guess

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.

Visualization & Export

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

---

Comparison with DIC Tools

	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.}

---

Accuracy

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

Performance

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.

---

Quick Start

Installation

Three equivalent paths; requires Python >= 3.10.

From PyPI (recommended):

pip install al-dic

From a GitHub Release wheel (useful behind firewalls, or for installing a specific past version):

1. Download al_dic-<version>-py3-none-any.whl from the releases page.
2. Install locally:

pip install ./al_dic-<version>-py3-none-any.whl

From source (editable install with test dependencies):

git clone https://github.com/zachtong/pyALDIC.git
cd pyALDIC
pip install -e ".[dev]"

Launch GUI

al-dic
# or
python -m al_dic

Programmatic 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.py

---

About the Authors

pyALDIC 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).

---

Citation

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}
}

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Acknowledgments

• Based on the AL-DIC MATLAB implementation by Dr. Jin Yang
• Developed at The University of Texas at Austin

License

BSD 3-Clause. See LICENSE for details.