Metadata-Version: 2.5
Name: al-dvc
Version: 0.8.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.
- **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.
- **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 |
| Large scans | whole volume in memory | local steps over sub-boxes, streamed frames, gradients on the fly when they would not fit |
| 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 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.

<p align="center">
  <img src="src/al_dvc/gui/assets/guide/overlap_correction.gif" alt="A box and its shifted copy; the overlap shrinks with the shift, and the raw curve falls below the corrected one" width="90%"/>
</p>

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

<p align="center">
  <img src="src/al_dvc/gui/assets/guide/rve_sweep.gif" alt="Concentric boxes of growing size about one centre; the correlation length settles once the box 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.
