Metadata-Version: 2.5
Name: al-dvc
Version: 0.10.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'
Requires-Dist: numpy<2.5; extra == 'gpu'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/zachtong/pyALDVC/main/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="https://raw.githubusercontent.com/zachtong/pyALDVC/main/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 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:

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

Confocal scan of the MATLAB example (hydrogel indentation), 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 |
| Statistics | mean and std of uniform strain (script) | tables, histograms, regions, confidence intervals, series over frames, profiles, extensometer, noise floor, rigid-body motion removed |
| 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="https://raw.githubusercontent.com/zachtong/pyALDVC/main/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="https://raw.githubusercontent.com/zachtong/pyALDVC/main/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="https://raw.githubusercontent.com/zachtong/pyALDVC/main/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="https://raw.githubusercontent.com/zachtong/pyALDVC/main/assets/videos/rotation_frame_animation.gif" alt="Synthetic rotation: frames animation with smooth deformation on the deformed lattice" width="90%"/>
</p>

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

<p align="center">
  <img src="https://raw.githubusercontent.com/zachtong/pyALDVC/main/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="https://raw.githubusercontent.com/zachtong/pyALDVC/main/assets/videos/indentation_frame_smooth_animation.gif" alt="Hydrogel indentation: frames animation with smooth deformation" width="90%"/>
</p>
<p align="center">
  <img src="https://raw.githubusercontent.com/zachtong/pyALDVC/main/assets/videos/indentation_sweep_x.gif" alt="Slice sweep along x" width="90%"/>
</p>
<p align="center">
  <img src="https://raw.githubusercontent.com/zachtong/pyALDVC/main/assets/videos/indentation_sweep_y.gif" alt="Slice sweep along y" width="90%"/>
</p>
<p align="center">
  <img src="https://raw.githubusercontent.com/zachtong/pyALDVC/main/assets/videos/indentation_sweep_z.gif" alt="Slice sweep along z" width="90%"/>
</p>

## Install

With conda ([Miniforge](https://github.com/conda-forge/miniforge) if the machine has none yet):

```bash
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](https://github.com/zachtong/pyALDVC/releases) ships a portable Windows bundle: unzip, double-click `pyALDVC.exe`.

Read the [user guide](https://github.com/zachtong/pyALDVC/blob/main/docs/user_guide.md) 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

```bibtex
@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.
