al-dvc 0.10.0

Full-field 3-D displacement and strain from volumetric images (micro-CT, confocal, MRI, OCT).

Available in 7 languages

pyALDVC is the Python version of the MATLAB ALDVC code (Yang, Hazlett, Landauer, Franck, Exp. Mech. 2020) and the volumetric sibling of pyALDIC: a desktop application that turns a sequence of 3-D scans into displacement and strain fields.

Why pyALDVC

• Accurate where subset DVC breaks down. Local subsets are coupled to a global smoothness step, so steep gradients, boundaries and noisy scans stay sub-voxel accurate.
• Cracks and holes stay sharp. A subset that meets a boundary keeps only the material on its own side of it, and the smoothing never crosses it, so a displacement jump survives instead of being averaged away.
• Fast. A 1024 x 1024 x 306 confocal scan with 79 200 nodes takes 23 s on an NVIDIA GPU, 3.6 min on a 24-core CPU.
• Big scans fit. A masked 1024^3 run peaks at 14 GB of volume memory instead of 53, so it runs on a 32 GB workstation; drawing and browsing stay responsive because a local change no longer costs a pass over the whole volume.
• Point and click. Load the scans, draw the region of interest on the slices, run, look, export. No code.
• Knows your data. The texture analysis measures your scan and suggests the subset size and step.
• See it in 3-D. Field slices, the deformed lattice, displacement arrows; animations recorded as GIF or MP4.
• Strain included. Four gradient methods and four strain measures, computed after the run in their own window.
• Statistics built in. Mean with its confidence interval, spread and noise floor of any field, in regions drawn on the slices, with the rigid-body motion removed exactly (fitted over a grip if needed, and shown in the main window); series over frames, profiles, a virtual extensometer, exports that state their definitions.
• Every format. TIFF, MATLAB, NumPy, HDF5, NIfTI, NRRD, DICOM in; NumPy, MATLAB, CSV, ParaView and a PDF report out.

Accuracy and speed

Synthetic volumes with a known deformation (subset 16, step 8), displacement error at the interior nodes:

Confocal scan of the MATLAB example (hydrogel indentation), 1024 x 1024 x 306 voxels, 79 200 nodes:

Compared with the MATLAB code

Texture analysis

A subset too small drifts, a subset too large blurs the field. pyALDVC measures the texture of your scan and tells you what to use. The same guide is built into the application, under Help.

1. Compare a box with a shifted copy of itself, and divide out the overlap. The shift at which the similarity has fallen to 1/e is the correlation length: the size of your features. Shifting makes the two overlap less, which would pull the curve down on its own, so every lag is divided by the number of voxel pairs that still contribute.

2. Grow the box until that length stops changing. Pick a centre, analyse concentric cubes around it, each on its own voxels alone. Below the representative volume element the measurement is noise; above it, every size agrees.

3. The subset follows. Four correlation lengths per axis, stepped by half a subset: a recommended start, not a guarantee. One click writes it into the run.

Case studies

Synthetic rotation

Hydrogel indentation, confocal microscopy, 1024 x 1024 x 306 voxels

Install

With conda (Miniforge if the machine has none yet):

conda create -n pyaldvc python=3.12 -y
conda activate pyaldvc
pip install al-dvc            # NVIDIA GPU: pip install "al-dvc[gpu]"
al-dvc                        # opens the application; al-dvc --help lists the commands

• conda only provides Python; al-dvc and its dependencies come from PyPI, so do not conda install numpy, scipy and the like into this environment afterwards. Python 3.10 to 3.12 are tested in CI.
• pip install al-dvc is the complete application: GUI, 3-D view and command line.
• [gpu] installs the CUDA 12 libraries as pip packages: the machine needs an NVIDIA driver, not the CUDA Toolkit.
• Check the install with al-dvc --self-test: six checks, each [ok] or [FAIL], saved to pyaldvc_self_test.txt. The compute-backend line names the GPU when one is used.
• Optional: pip install nibabel pynrrd pydicom reads NIfTI, NRRD and DICOM; pip install imageio imageio-ffmpeg exports 3-D animations as MP4 (GIF needs nothing). Without them the application says what to install when you need it.
• Update with pip install -U al-dvc.

No Python? Every release ships a portable Windows bundle: unzip, double-click pyALDVC.exe.

Read the user guide to get started.

Citation

Software (concept DOI, always the latest version; each release also has its own):

Tong, Z., Yang, J. pyALDVC: Augmented Lagrangian Digital Volume Correlation in Python. Zenodo. https://doi.org/10.5281/zenodo.22883767

@software{tong_pyaldvc,
  author    = {Tong, Zixiang and Yang, Jin},
  title     = {{pyALDVC}: Augmented Lagrangian Digital Volume Correlation in Python},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.22883767},
  url       = {https://github.com/zachtong/pyALDVC}
}

The method:

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

License

BSD 3-Clause. Developed in Dr. Jin Yang's group at The University of Texas at Austin.