Metadata-Version: 2.5
Name: al-dvc
Version: 0.7.0
Summary: AL-DVC: Augmented Lagrangian Digital Volume Correlation (3D) in Python
Project-URL: Homepage, https://github.com/zachtong/pyALDVC
Project-URL: Repository, https://github.com/zachtong/pyALDVC
Project-URL: Issues, https://github.com/zachtong/pyALDVC/issues
Author-email: "Zixiang (Zach) Tong" <zachtong@utexas.edu>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: ADMM,DVC,augmented-lagrangian,digital-volume-correlation,experimental-mechanics,inverse-compositional-gauss-newton,micro-CT,strain-measurement
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: h5py>=3.8
Requires-Dist: matplotlib>=3.6
Requires-Dist: numba>=0.57
Requires-Dist: numpy>=1.24
Requires-Dist: pyside6>=6.6
Requires-Dist: pyvista>=0.43
Requires-Dist: pyvistaqt>=0.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: scipy>=1.10
Requires-Dist: tifffile>=2023.1
Provides-Extra: gpu
Requires-Dist: numba-cuda[cu12]>=0.10; extra == 'gpu'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/banner.png" alt="pyALDVC banner" width="100%"/>
</p>

<p align="center">
  Full-field 3-D displacement and strain from volumetric images (micro-CT, confocal, MRI, OCT).
</p>

<p align="center">
  <a href="https://github.com/zachtong/pyALDVC/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/zachtong/pyALDVC/ci.yml?style=flat-square&label=CI" alt="CI"/></a>
  <img src="https://img.shields.io/badge/Python-3.10+-3776ab?style=flat-square&logo=python&logoColor=white" alt="Python"/>
  <img src="https://img.shields.io/badge/GUI-PySide6-41cd52?style=flat-square" alt="PySide6"/>
  <img src="https://img.shields.io/badge/GPU-CUDA%20optional-76b900?style=flat-square&logo=nvidia&logoColor=white" alt="CUDA"/>
  <img src="https://img.shields.io/badge/License-BSD--3--Clause-22c55e?style=flat-square" alt="License"/>
  <a href="https://pypi.org/project/al-dvc/"><img src="https://img.shields.io/pypi/v/al-dvc?style=flat-square&label=PyPI" alt="PyPI"/></a>
</p>

<p align="center">
  <strong>Available in 7 languages</strong><br/>
  <img src="https://img.shields.io/badge/English-✓-22c55e?style=flat-square" alt="English"/>
  <img src="https://img.shields.io/badge/简体中文-✓-22c55e?style=flat-square" alt="Simplified Chinese"/>
  <img src="https://img.shields.io/badge/繁體中文-✓-22c55e?style=flat-square" alt="Traditional Chinese"/>
  <img src="https://img.shields.io/badge/日本語-✓-22c55e?style=flat-square" alt="Japanese"/>
  <img src="https://img.shields.io/badge/Deutsch-✓-22c55e?style=flat-square" alt="German"/>
  <img src="https://img.shields.io/badge/Français-✓-22c55e?style=flat-square" alt="French"/>
  <img src="https://img.shields.io/badge/Español-✓-22c55e?style=flat-square" alt="Spanish"/>
</p>

---

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

<p align="center">
  <img src="assets/pyALDVC_demo.gif" alt="pyALDVC workflow: load volumes, draw a region of interest, run, strain post-processing, 3-D view" width="90%"/>
</p>

## 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 micro-CT scan with 79 200 nodes takes 23 s on an NVIDIA GPU, 3.6 min on a 24-core CPU.
- **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.
- **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:

| case | error (voxel) |
|---|---|
| rigid translation | 0.003 - 0.006 |
| 2 % strain | 0.004 |
| 5 deg rotation with 12 voxel motion | 0.001 - 0.006 |
| 2 % strain, noisy scan (SNR 6) | 0.012 |

Micro-CT scan of the MATLAB example, 1024 x 1024 x 306 voxels, 79 200 nodes:

| | time | agreement with the MATLAB code |
|---|---|---|
| NVIDIA RTX 5090 | 23 s | median 0.005 / 0.006 / 0.020 voxel (u, v, w) |
| 24-core CPU | 3.6 min | the same field |

## Compared with the MATLAB code

| | MATLAB ALDVC | pyALDVC |
|---|---|---|
| Method | augmented Lagrangian DVC | the same, results within 0.01 voxel |
| Interface | scripts | desktop application, 7 languages, command line |
| GPU | - | NVIDIA CUDA, one install flag |
| Region of interest | box | masks drawn on the slices, auto-segmentation, per-frame masks |
| Subset size | by hand | texture analysis suggests it from the scan |
| Cracks and holes | subsets and smoothing reach across them | subsets and smoothing stop at the boundary |
| Strain | in the run | its own window, four methods, four measures, recomputed on demand |
| 3-D view | - | slices, lattice, arrows, animations, GIF / MP4 recording |
| Formats | MATLAB | TIFF, MATLAB, NumPy, HDF5, NIfTI, NRRD, DICOM; ParaView export |
| Long sequences | - | checkpoints, resume, batch runs, sessions |
| Install | MATLAB licence | `pip install al-dvc`, or a portable Windows bundle |

## 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 window with a shifted copy of itself.** Inside a region you draw, the window slides
and the similarity of the two is traced. The shift at which it has fallen to 1/e is the correlation
length: the size of your features.

<p align="center">
  <img src="src/al_dvc/gui/assets/guide/region_window.gif" alt="A window and its shifted copy inside the analysis region, tracing the autocorrelation curve" width="90%"/>
</p>

**2. Grow the window until that length stops changing.** Below the representative volume element the
measurement is noise; above it, every window agrees.

<p align="center">
  <img src="src/al_dvc/gui/assets/guide/rve_sweep.gif" alt="Windows of growing size in the same region; the correlation length settles once the window is large enough" width="90%"/>
</p>

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

<p align="center">
  <img src="src/al_dvc/gui/assets/guide/subset.png" alt="From the 1/e correlation length to the subset size and the step" width="75%"/>
</p>

## Case studies

**Synthetic rotation**

<p align="center">
  <img src="assets/videos/rotation_frame_animation.gif" alt="Synthetic rotation: frames animation with smooth deformation on the deformed lattice" width="90%"/>
</p>

**Hydrogel indentation, micro-CT, 306 x 1024 x 1024 voxels**

<p align="center">
  <img src="assets/videos/indentation_deformed_lattice_orbit_with_arrow.gif" alt="Hydrogel indentation: deformed lattice with displacement arrows, orbit" width="90%"/>
</p>
<p align="center">
  <img src="assets/videos/indentation_frame_smooth_animation.gif" alt="Hydrogel indentation: frames animation with smooth deformation" width="90%"/>
</p>
<p align="center">
  <img src="assets/videos/indentation_sweep_x.gif" alt="Slice sweep along x" width="90%"/>
</p>
<p align="center">
  <img src="assets/videos/indentation_sweep_y.gif" alt="Slice sweep along y" width="90%"/>
</p>
<p align="center">
  <img src="assets/videos/indentation_sweep_z.gif" alt="Slice sweep along z" width="90%"/>
</p>

## Install

```bash
pip install al-dvc            # add "[gpu]" for the NVIDIA backend
al-dvc-gui
```

No Python? Every [release](https://github.com/zachtong/pyALDVC/releases) ships a portable Windows bundle: unzip, double-click `pyALDVC.exe`.

Read the [user guide](docs/user_guide.md) to get started.

## Citation

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