dolfin_warp

A set of FEniCS- and VTK-based python tools for Finite Element Digital Image Correlation/Image Registration/Motion Tracking, basically implementing the method described in [Genet, Stoeck, von Deuster, Lee & Kozerke (2018). Equilibrated Warping: Finite Element Image Registration with Finite Strain Equilibrium Gap Regularization. Medical Image Analysis.] and [Genet (2023). Finite strain formulation of the discrete equilibrium gap principle: application to mechanically consistent regularization for large motion tracking. Comptes Rendus Mécanique.].

The library has notably been used in:

• [Genet, Stoeck, von Deuster, Lee & Kozerke (2018). Equilibrated Warping: Finite Element Image Registration with Finite Strain Equilibrium Gap Regularization. Medical Image Analysis.]
• [Zou, Xi, Zhao, Koh, Gao, Su, Tan, Allen, Lee, Genet & Zhong (2018). Quantification of Biventricular Strains in Heart Failure With Preserved Ejection Fraction Patient Using Hyperelastic Warping Method. Frontiers in Physiology.]
• [Finsberg, Xi, Tan, Zhong, Genet, Sundnes, Lee & Wall (2018). Efficient estimation of personalized biventricular mechanical function employing gradient-based optimization. International Journal for Numerical Methods in Biomedical Engineering.]
• [Berberoğlu, Stoeck, Moireau, Kozerke & Genet (2019). Validation of Finite Element Image Registration‐based Cardiac Strain Estimation from Magnetic Resonance Images. PAMM.]
• [Finsberg, Xi, Zhao, Tan, Genet, Sundnes, Lee, Zhong & Wall (2019). Computational quantification of patient-specific changes in ventricular dynamics associated with pulmonary hypertension. American Journal of Physiology-Heart and Circulatory Physiology.]
• [Lee & Genet (2019). Validation of Equilibrated Warping—Image Registration with Mechanical Regularization—On 3D Ultrasound Images. Functional Imaging and Modeling of the Heart (FIMH). Cham: Springer International Publishing.]
• [Škardová, Rambausek, Chabiniok & Genet (2019). Mechanical and Imaging Models-Based Image Registration. VipIMAGE 2019. Cham: Springer International Publishing.]
• [Zou, Leng, Xi, Zhao, Koh, Gao, Tan, Tan, Allen, Lee, Genet & Zhong (2020). Three-dimensional biventricular strains in pulmonary arterial hypertension patients using hyperelastic warping. Computer Methods and Programs in Biomedicine.]
• [Gusseva, Hussain, Friesen, Moireau, Tandon, Patte, Genet, Hasbani, Greil, Chapelle & Chabiniok (2021). Biomechanical Modeling to Inform Pulmonary Valve Replacement in Tetralogy of Fallot Patients after Complete Repair. Canadian Journal of Cardiology.]
• [Berberoğlu, Stoeck, Moireau, Kozerke & Genet (2021). In-silico study of accuracy and precision of left-ventricular strain quantification from 3D tagged MRI. PLOS ONE.]
• [Castellanos, Škardová, Bhattaru, Berberoğlu, Greil, Tandon, Dillenbeck, Burkhardt, Hussain, Genet & Chabiniok (2021). Left Ventricular Torsion Obtained Using Equilibrated Warping in Patients with Repaired Tetralogy of Fallot. Pediatric Cardiology.]
• [Berberoğlu, Stoeck, Kozerke & Genet (2022). Quantification of left ventricular strain and torsion by joint analysis of 3D tagging and cine MR images. Medical Image Analysis.]
• [Patte, Brillet, Fetita, Gille, Bernaudin, Nunes, Chapelle & Genet (2022). Estimation of regional pulmonary compliance in idiopathic pulmonary fibrosis based on personalized lung poromechanical modeling. Journal of Biomechanical Engineering.]
• [Laville, Fetita, Gille, Brillet, Nunes, Bernaudin & Genet (2023). Comparison of optimization parametrizations for regional lung compliance estimation using personalized pulmonary poromechanical modeling. Biomechanics and Modeling in Mechanobiology.]
• [Genet (2023). Finite strain formulation of the discrete equilibrium gap principle: application to mechanically consistent regularization for large motion tracking. Comptes Rendus Mécanique.]
• [Škardová, Hussain, Genet & Chabiniok (2023). Effect of Spatial and Temporal Resolution on the Accuracy of Motion Tracking Using 2D and 3D Cine Cardiac Magnetic Resonance Imaging Data. Functional Imaging and Modeling of the Heart (FIMH) Cham: Springer Nature Switzerland.]
• [Peyraut & Genet (2024). Finite strain formulation of the discrete equilibrium gap principle: application to direct parameter estimation from large full-fields measurements. Comptes Rendus Mécanique.]
• [Peyraut & Genet (2025). Inverse Uncertainty Quantification for Personalized Biomechanical Modeling: Application to Pulmonary Poromechanical Digital Twins. Journal of Biomechanical Engineering.]
• [Álvarez-Barrientos, Škardová & Genet (2025). Motion Tracking with Finite Elements Meshes and Image Models. Functional Imaging and Modeling of the Heart. Springer Nature Switzerland.]

(If you use it for your own work please let me know!)

Tutorials

Interactive tutorials can be found at https://mgenet.github.io/dolfin_warp-tutorials.

Installation

A working installation of FEniCS (version 2019.1.0; including the dolfin python interface) & VTK (also including python interface) is required to run dolfin_warp. To setup a system, the simplest is to use conda: first install miniconda (note that for Microsoft Windows machines you first need to install WSL, the Windows Subsystem for Linux, and then install miniconda for linux inside the WSL), and then install the necessary packages:

conda create -y -c conda-forge -n dolfin_warp expat=2.5 fenics=2019.1.0 gnuplot=5.4 jinja2=3.1 matplotlib=3.5 meshio=5.3 mpi4py=3.1.3 numpy=1.23 pandas=1.3 pip python=3.10 scipy=1.9 vtk=9.2
conda activate dolfin_warp
conda env config vars set CPATH=$CONDA_PREFIX/include/vtk-9.2
conda activate dolfin_warp

Now, if you only need to use the library, you can install it with:

pip install dolfin_warp

But if you need to develop within the library, you need to install an editable version of the sources:

git clone https://github.com/mgenet/dolfin_warp.git
pip install -e dolfin_warp/.