al-dvc 0.4.1

Full-field 3-D displacement and strain from volumetric images (micro-CT, confocal, MRI, OCT)
with a hybrid local-global solver, GPU acceleration and a complete desktop application.

Available in 7 languages

Why pyALDVC?

Subset-based DVC (IC-GN) solves every node on its own: accurate for small deformations, fragile where the field is steep, near boundaries and in noisy scans. pyALDVC couples the local 12-DOF subsets to a global finite-element compatibility step through the Augmented Lagrangian (ADMM) framework, so the field is smoother and more accurate while keeping sub-voxel precision.

pyALDVC is the Python re-implementation of the MATLAB ALDVC code (Yang, Hazlett, Landauer, Franck, Exp. Mech. 2020) and the volumetric sibling of pyALDIC. It keeps the algorithm and adds the engineering: masks and regions of interest, a coarse-to-fine initial guess, Numba and CUDA kernels, streaming I/O, ParaView export, tests against analytic ground truth, a command line and a desktop application.

Key features

Desktop application

Three columns like pyALDIC: volumes, region of interest and parameters on the left, the slice viewer and the 3-D view in the middle, run controls, results, exports and the console on the right. Load volumes, draw or auto-segment the region of interest, set parameters, run, inspect, export: no code needed. Before a run the slices preview the node lattice and one subset for the current subset size and step (hover a node to see its subset); the subset can be cubic or set per axis.

_{Synthetic open-cell foam (200 x 224 x 256 voxels) under compression with a localised vortex; the displacement magnitude forms a torus. Subset 24, step 8, 14 112 nodes, 11 s on an RTX 5090. Regenerate every asset with python scripts/make_branding.py.}

Local DVC or AL-DVC

Run independent subsets (local DVC) or the full ADMM global-local coupling (AL-DVC) with one switch; same window, same workflow. The penalty beta is tuned automatically with an L-curve.

Strain post-processing and 3-D view

Strain is a post-processing step with its own window: plane fitting, finite elements, finite differences or the solver's gradient; infinitesimal, Green-Lagrange, Euler-Almansi or Hencky measures; smoothing and edge trimming. The 3-D view shows field slices, node points, iso-surfaces, the deformed lattice and displacement arrows.

Fast on a laptop, faster on a GPU

Numba kernels read subsets in place (about 21 bytes per voxel resident, 9 with on-the-fly gradients); with pip install "al-dvc[gpu]" the local solvers run as CUDA kernels compiled for the installed NVIDIA card. The micro-CT example of the MATLAB code (1024 x 1024 x 306 voxels, 79 200 nodes) takes 23 s on an RTX 5090 and 3.6 min on a 24-core CPU, with results within 0.01 voxel of MATLAB.

Highlights

Installation

Two flavours, nothing else to pick:

pip install al-dvc           # CPU: the complete application (GUI, 3-D view, CLI)
pip install "al-dvc[gpu]"    # the same plus the CUDA backend for NVIDIA GPUs

From a clone of this repository use pip install -e . or pip install -e ".[gpu]". Requires Python >= 3.10; NumPy, SciPy, Numba, tifffile, h5py, matplotlib, PyYAML, PySide6, pyvista and pyvistaqt are installed automatically. The Numba kernels compile on first use (~10 s) and are cached on disk; call al_dvc.warmup() at application start to hide this.

Quick start

Python

import numpy as np
from al_dvc import dvcpara_default, run_aldvc, load_volume
from al_dvc.export import export_npz, export_vtk, export_report

ref = load_volume("ref.tif")           # (nz, ny, nx) array, any dtype
dfm = load_volume("deformed.tif")

para = dvcpara_default(
    winsize=32,            # subset size (voxels, per axis or scalar)
    winstepsize=16,        # node spacing
    voxel_size=(5.0, 5.0, 5.0), units="um",
)
result = run_aldvc(para, [ref, dfm])

mesh = result.dvc_mesh                  # node coordinates (N, 3) = [x, y, z], grid_shape (nz, ny, nx)
U = result.result_disp[0].U             # (N, 3) displacement in voxels
U_std = result.result_disp[0].U_std     # (N, 3) per-node standard deviation (voxels), NaN where not converged
E = result.result_strain[0]             # exx, eyy, ezz, exy, exz, eyz, principal, von_mises, ...
exx_grid = mesh.to_grid(E.field("exx")) # (nz, ny, nx) grid, NaN where unreliable

export_npz(result, "out/result.npz")
export_vtk(result, "out/vtk")           # open out/vtk/aldvc.pvd in ParaView
export_report(result, "out/report.pdf")

Masks (boolean volumes, True = material, one per frame) and multi-frame sequences. A frame's mask trims the reference subsets when the frame is the reference and, when it is the deformed frame, removes the voxels that the warped subsets would sample from it (a void that opens, a region that leaves the field of view):

result = run_aldvc(para, [ref, f1, f2, f3], masks=[mask0, mask1, mask2, mask3])
para_inc = dvcpara_default(winsize=32, winstepsize=16, reference_mode="incremental")

Long sequences can be checkpointed frame by frame and resumed after an interruption (al-dvc run --checkpoint DIR, or the checkpoint config key):

result = run_aldvc(para, provider, checkpoint_dir="scan/checkpoints")  # reuses finished frames on rerun

Large sequences stream from disk with a bounded cache:

from al_dvc.io import FileVolumeProvider
provider = FileVolumeProvider(sorted(Path("scan").glob("*.tif")), voi=para.voi)
result = run_aldvc(para, provider)

Graphical application

al-dvc-gui                 # or: al-dvc gui [session.aldvc]

A standalone PySide6 window (al_dvc.gui, layout and architecture shared with pyALDIC): volumes and parameters on the left (folding sections, inputs that only react to the wheel when focused), the slice viewer in the middle, run controls, results, exports and the console on the right. The workflow is load, draw the region of interest, set parameters, run, export: results stay in memory and each export asks where to write; the analysed box is the bounding box of the drawn region grown by the subset half-width and the search range (memory and time scale with the region, not with the scan). Mask drawing (rectangle / ellipse / polygon / brush on any slice, extruded through all slices, one slice or a range; add / cut; undo; reports/mask_tools.pdf), a 3-D view (pyvista: field slices with their own position controls, node points, iso-surface, warped lattice, displacement arrows, volume slices, selectable background; reports/view3d.pdf), a strain post-processing window (method, measure, smoothing chosen after the run, computed on demand; Ctrl+T) and an export dialog (npz, mat, CSV, ParaView, PDF report, slice images; Ctrl+E), and a batch dialog that runs several saved sessions one after another (File > Batch run..., the same as al-dvc batch; reports/batch.pdf). Sessions (.aldvc) keep volumes, parameters, export folder and display state; checkpoints (resume after an interruption) are an advanced option, and a checkpoint folder left by a different run is replaced; Help > Run self-test (or al-dvc-gui --self-test) checks an installation. Seven languages (English, Simplified and Traditional Chinese, Japanese, German, French, Spanish; View > Language, or the system locale); tools/i18n_extract.py audits the tables against the code. The kernels compile in the background after the window opens. reports/gui.pdf shows the screens.

Without Python (Windows): every release also ships a portable bundle pyALDVC-<version>-win64.zip on the releases page. Unzip it anywhere and double-click pyALDVC.exe; pyALDVC-console.exe --self-test writes an installation report. The bundle is built by tools/build_exe.py (PyInstaller, packaging/pyaldvc.spec) and checked by tests/test_frozen_bundle.py before it is attached to the release.

Command line

al-dvc synth data/synth --shape 96 96 96 --mode stretch --value 0.02   # synthetic test pair
al-dvc run --volumes data/synth -o results --winsize 24 --step 12 --export npz vtk report
al-dvc run config.yaml                                                 # see examples/scripting/
al-dvc plot results/aldvc.npz --field exx --frame 1
al-dvc batch study/*.aldvc --export npz summary report              # sessions saved by the GUI, one after another
al-dvc info scan/*.tif

GPU acceleration (optional)

pip install "al-dvc[gpu]"          # numba-cuda with the CUDA 12 wheels; needs an NVIDIA driver

With an NVIDIA GPU the local solvers (Hessian precompute, 12-DOF IC-GN, the 3-DOF ADMM passes) run as CUDA kernels compiled at first use for the installed card (any compute capability the CUDA 12 toolchain supports, Maxwell and newer; the RTX 5090 included). Results agree with the CPU kernels to about 1e-5 voxel (float32 sampling, float64 solves); the local steps are 25-40x faster on an RTX 5090 than on a 24-core CPU. Installations without the gpu flavour, without a driver or without a usable device are unaffected: backend="auto" (the default) probes CUDA once and uses the CPU kernels otherwise, and the GUI shows which backend it picked. The portable Windows bundle is CPU-only.

How it works

For a reference volume f and a deformed volume g the pipeline solves, on a regular grid of nodes:

1. Initial guess -- global rigid shift by phase correlation, then a coarse-to-fine normalised cross-correlation pyramid per node (sub-voxel peak fit, quality factors, outlier removal, inpainting).
2. Local step (subproblem 1) -- at every node an affine subset warp (9 gradient + 3 translation parameters) is fitted by IC-GN on the ZNSSD criterion. Later ADMM passes hold the gradient at the global estimate and fit only the 3 translations with a proximal penalty.
3. Global step (subproblem 2) -- a kinematically compatible field u_hat minimises beta/2 |grad(u_hat) - (F - W)|^2 + mu/2 |u_hat - (u - v)|^2 over the hex8 FEM (or finite-difference) discretisation. beta is tuned automatically by an L-curve sweep on the first frame of each reference.
4. ADMM iterations alternate 2 and 3 with scaled dual updates until the RMS displacement update drops below admm_tol (typically 2-4 steps).
5. Strain from the cumulative displacement in physical units.

Every convention (axis order, node ordering, DOF layout, warp parameters) is fixed in docs/design.md, which also records the design decisions and the differences from the MATLAB code.

Parameters

dvcpara_default(**overrides) returns a validated, immutable DVCPara. The most useful fields:

Accuracy and performance

Synthetic ground-truth validation (scripts/make_validation_report.py, speckle volumes with exact Lagrangian warps) and the throughput benchmark (scripts/benchmark_performance.py) regenerate the PDFs in reports/. Numbers from a 112x120x128 speckle volume (feature size ~4 voxels), subset 16, step 8, interior nodes:

Throughput on a 24-core workstation (Intel Core Ultra 9 285K, Numba warm, ADMM with 2-4 steps, increment tolerance 1e-3 voxel):

See reports/validation_synthetic.pdf and reports/performance.pdf for the complete tables, noise sweep, spatial-resolution study and stage timings, and reports/optimization.pdf for the optimisation study (before / after, thread scaling, the stride trade-off with and without noise, rejected experiments).

Agreement with the MATLAB ALDVC code

scripts/compare_matlab.py reruns the micro-CT example shipped with the MATLAB code (20190504_cut, 1024x1024x306, 79,200 nodes at subset 32 / step 8) on the MATLAB node positions and compares node by node (reports/matlab_crossval_ws32_st8.pdf). On the interior nodes converged in both codes:

The two IC-GN implementations minimise the same functional; the stored solutions differ along z because the scan has 7x less texture in that direction and both codes stop early there. The automatic beta equals the MATLAB value, and the ZNCC of the pyALDVC fields is never below MATLAB's. The run takes 3.6 min on a 24-core workstation (3.2 min with init_coarse_factor=2) and 23 s on an RTX 5090. See docs/design.md, section 10.

Tutorial

examples/tutorial_real_data.ipynb (and the equivalent script examples/scripting/tutorial_real_data.py) walks through a complete run: loading volumes, parameters and memory, running with a checkpoint directory, reading status codes, ZNCC and uncertainty, slice plots, exports. Without your own files it runs on a synthetic pair with a known deformation.

Project layout

src/al_dvc/
  core/     DVCPara (config.py), data structures, run_aldvc (pipeline.py)
  io/       volume loading / streaming, normalisation, gradients
  mesh/     hex8 node grid, mask trimming, shape functions
  solver/   Numba IC-GN kernels, NCC pyramid, global operators, ADMM pieces
  strain/   gradient estimators, strain measures
  utils/    outlier test, inpainting, grid interpolation, validation
  export/   npz / mat / csv / vtk / pdf report
  viz/      matplotlib slice views
  cli.py    al-dvc command line
tests/      pytest suite (unit + synthetic integration)
scripts/    report and benchmark generators
examples/   scripted workflows and config templates
docs/       design document

Testing

pytest                 # ~30 s, 100+ tests
pytest -m "not slow"   # skip the heaviest synthetic cases
PYALDVC_FROZEN_EXE=dist-exe/pyALDVC/pyALDVC-console.exe pytest tests/test_frozen_bundle.py   # after tools/build_exe.py

Citation

If you use pyALDVC, please cite the AL-DVC method paper:

J. Yang, L. Hazlett, A. K. Landauer, C. Franck. Augmented Lagrangian Digital Volume Correlation (ALDVC). Experimental Mechanics 60, 1205-1223 (2020). https://doi.org/10.1007/s11340-020-00607-3

and this software (see CITATION.cff).

License

BSD 3-Clause. Developed in Dr. Jin Yang's group at The University of Texas at Austin. Based on the MATLAB ALDVC code by Jin Yang and the pyALDIC architecture by Zixiang (Zach) Tong.