Skip to content

Clean up SimCardio and Add fiber generation #124

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
CZHU20 wants to merge 6 commits into
base: source
Choose a base branch
from
Open

Clean up SimCardio and Add fiber generation #124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5992213
Clean up SimCardio Guide.
CZHU20 Jul 1, 2022
0395c61
Merge pull request #1 from CZHU20/source-simcardio
CZHU20 Jul 15, 2022
f554093
Replace with .
CZHU20 Jul 15, 2022
07f18cb
Add myocardial generation from Sid.
CZHU20 Jul 30, 2022
5fda0e4
Remove unnecessary file.
CZHU20 Jul 30, 2022
f288891
Fix minor error in cep.
CZHU20 Aug 2, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 17 additions & 44 deletions source/documentation/_simcardio_TOC.erb
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
<p><h3>SimCardio Guide</h3></p>
<p><h3>Cardiac Modeling <br> Guide</h3></p>

<li><a href="#intro">Introduction</a></li>

<li><a href="#automatic-cardiac-modeling">Cardiac Geometric Modeling Tool </a>
<li><a href="#automatic-cardiac-modeling">Cardiac Geometric <br> Modeling Tool </a>
<ul class="nav nav-stacked">
<li><a href="#auto-ml-cardiac-segmentation">Automated Image Segmentation</a>

Expand All @@ -29,51 +29,24 @@
</ul>
</li>

<li><a href="#cep-modeling">Cardiac Electro- <br>physiology Modeling</a>
<li><a href="#purkinje">Purkinje Network</a>
<ul class="nav nav-stacked">
<li><a href="#cep-intro">Introduction</a></li>
<li><a href="#cep-theory">Mathematical <br>Formulation</a></li>
<li><a href="#cep-activation-models">Cellular Acti-<br>vation Models</a></li>
<li><a href="#purkinje">Purkinje Network</a>
<ul class="nav nav-stacked">
<li><a href="#pnet-intro">Introduction</a></li>
<li><a href="#pnet-install">Plugin Installation</a></li>
<li><a href="#pnet-workflow">Plugin Workflow &<br>Usage</a></li>
<li><a href="#pnet-parameters">Plugin Parameters</a></li>
<li><a href="#pnet-issues">Plugin Issues</a></li>
</ul>
</li>
<li><a href="#cep-examples">Examples</a>
<ul class="nav nav-stacked">
<li><a href="#cep-example-block">Activation of Cardiac Tissue</a></li>
<li><a href="#cep-example-pnet">Activation of Purkinje Network</a></li>
</ul>
</li>
<li><a href="#cep-refs">References</a></li>
<li><a href="#pnet-install">Plugin Installation</a></li>
<li><a href="#pnet-workflow">Plugin Workflow &<br>Usage</a></li>
<li><a href="#pnet-parameters">Plugin Parameters</a></li>
<li><a href="#pnet-issues">Plugin Issues</a></li>
<li><a href="#pnet-example">Example</a></li>
<li><a href="#pnet-refs">References</a></li>
</ul>
</li>

<li><a href="#mechanics-modeling">Cardiac Mechanics <br> Modeling</a>
<li><a href="#fiber">Fiber Generation</a>
<ul class="nav nav-stacked">
<li><a href="#mechanics-solve">Solve Cardiac Mechanics <br> with svFSI</a>
<ul class="nav nav-stacked">
<li><a href="#mechanics-obtain-svFSI">Obtain svFSI</a></li>
<li><a href="#mechanics-mesh-gen">Model Construction & <br> Mesh Generation</a></li>
<li><a href="#mechanics-fiber-gen">Fiber Generation</a></li>
<li><a href="#mechanics-solver-input">Input File</a></li>
<li><a href="#mechanics-simulation">Run Simulation</a></li>
</ul>
</li>
<li><a href="#mechanics-theory">svFSI Structure Solver</a>
<ul class="nav nav-stacked">
<li><a href="#mechanics-kinematics">Kinematics</a></li>
<li><a href="#mechanics-struct">STRUCT: displacement- <br> based elastodynamics</a></li>
<li><a href="#mechanics-ustruct">uSTRUCT: mixed formu- <br> lation elastodynamics</a></li>
<li><a href="#mechanics-material-models">Material Models</a></li>
</ul>
</li>
<li><a href="#amechanics-refs">References</a></li>
<li><a href="#fiber-intro">Introduction</a></li>
<li><a href="#fiber-meshing">Meshing</a></li>
<li><a href="#fiber-heat">Heat Simulation</a></li>
<li><a href="#fiber-gen">Fiber Generation</a></li>
<li><a href="#fiber-debug">Troubleshooting</a></li>
<li><a href="#fiber-ref">References</a></li>
</ul>
</li>


</li>
39 changes: 11 additions & 28 deletions source/documentation/_simcardio_content.erb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,35 +15,18 @@

<section id="refs" class="subgroup"><%= partial "documentation/simcardio/cardiacModeling/refs" %></section>


<section id="cep-modeling" class="group"><%= partial "documentation/simcardio/electrophysiology/cep-modeling" %></section>
<section id="cep-intro" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/cep-intro" %></section>
<section id="cep-theory" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/cep-theory" %></section>
<section id="cep-activation-models" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/cep-activation-models" %></section>
<section id="purkinje" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/purkinje" %></section>
<section id="pnet-intro" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/pnet-intro" %></section>
<section id="purkinje" class="group"><%= partial "documentation/simcardio/electrophysiology/purkinje" %></section>
<section id="pnet-install" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/pnet-install" %></section>
<section id="pnet-workflow" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/pnet-workflow" %></section>
<section id="pnet-parameters" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/pnet-parameters" %></section>
<section id="pnet-issues" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/pnet-issues" %></section>
<section id="cep-examples" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/cep-examples" %></section>
<section id="cep-example-block" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/cep-example-block" %></section>
<section id="cep-example-pnet" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/cep-example-pnet" %></section>
<section id="cep-refs" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/cep-refs" %></section>


<section id="mechanics-modeling" class="group"><%= partial "documentation/simcardio/mechanics/mechanics-modeling" %></section>
<section id="mechanics-solve" class="subgroup"><%= partial "documentation/simcardio/mechanics/mechanics-solve" %></section>
<section id="mechanics-obtain-svFSI" class="subgroup"><%= partial "documentation/simcardio/mechanics/mechanics-obtain-svFSI" %></section>
<section id="mechanics-mesh-gen" class="subgroup"><%= partial "documentation/simcardio/mechanics/mechanics-mesh-gen" %></section>
<section id="mechanics-fiber-gen" class="subgroup"><%= partial "documentation/simcardio/mechanics/mechanics-fiber-gen" %></section>
<section id="mechanics-solver-input" class="subgroup"><%= partial "documentation/simcardio/mechanics/mechanics-solver-input" %></section>
<section id="mechanics-simulation" class="subgroup"><%= partial "documentation/simcardio/mechanics/mechanics-simulation" %></section>

<section id="mechanics-theory" class="subgroup"><%= partial "documentation/simcardio/mechanics/mechanics-theory" %></section>
<section id="mechanics-kinematics" class="subgroup"><%= partial "documentation/simcardio/mechanics/mechanics-kinematics" %></section>
<section id="mechanics-struct" class="subgroup"><%= partial "documentation/simcardio/mechanics/mechanics-struct" %></section>
<section id="mechanics-ustruct" class="subgroup"><%= partial "documentation/simcardio/mechanics/mechanics-ustruct" %></section>
<section id="mechanics-material-models" class="subgroup"><%= partial "documentation/simcardio/mechanics/mechanics-material-models" %></section>
<section id="mechanics-refs" class="subgroup"><%= partial "documentation/simcardio/mechanics/mechanics-refs" %></section>

<section id="pnet-example" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/pnet-example" %></section>
<section id="pnet-refs" class="subgroup"><%= partial "documentation/simcardio/electrophysiology/pnet-refs" %></section>

<section id="fiber" class="group"><%= partial "documentation/simcardio/fiberGeneration/fiber" %></section>
<section id="fiber-intro" class="subgroup"><%= partial "documentation/simcardio/fiberGeneration/fiber_intro" %></section>
<section id="fiber-meshing" class="subgroup"><%= partial "documentation/simcardio/fiberGeneration/fiber_meshing" %></section>
<section id="fiber-heat" class="subgroup"><%= partial "documentation/simcardio/fiberGeneration/fiber_heat" %></section>
<section id="fiber-gen" class="subgroup"><%= partial "documentation/simcardio/fiberGeneration/fiber_gen" %></section>
<section id="fiber-debug" class="subgroup"><%= partial "documentation/simcardio/fiberGeneration/fiber_debug" %></section>
<section id="fiber-ref" class="subgroup"><%= partial "documentation/simcardio/fiberGeneration/fiber_ref" %></section>
21 changes: 10 additions & 11 deletions source/documentation/simcardio/_intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,21 @@
#Introduction
# Cardiac Modeling Guide

Human heart is an intrinsic multi-physics system. It's normal function requires synchronization and coupling of cardiac electrophysiology, tissue (myocardium) mechanics, and hemodynamics. Among the three physics, cardiac mechanics plays a central role, as it serves as the bridge between electrophysiology and blood flow. In a physiological setting, the myocardial cells (myocytes) in the heart tissue initiate and propagate an electrical impulse (action potential) that travels through the heart and drives the contraction of the cardiac muscle, which, in turn, propels the blood to sustain whole body circulation.

The SimVascular <strong>SimCardio</strong> software suite includes a machine learning-based tool to automatically segment heart chambers from medical data and create patient-specific cardiac models, a finite element solver for performing multi-physics cardiac simulations, and python-based plugins to interactively create cardiac models, Purkinje network and set solver parameters from within the main SimVascular GUI application. While some of the interactive plugins are under development, the software allows flexibility to use scripting and perform simulations on high performance clusters.
Here we present a software suite for cardiac modeling, which includes a machine learning-based tool to automatically segment heart chambers from medical data and create patient-specific cardiac models, a finite element solver for performing multi-physics cardiac simulations, and python-based plugins to interactively create cardiac models, Purkinje network and set solver parameters from within the main SimVascular GUI application. While some of the interactive plugins are under development, the software allows flexibility to use scripting and perform simulations on high performance clusters.


####[<strong>Cardiac Geometric Modeling Tool</strong>](http://simvascular.github.io/docsSimCardio.html#automatic-cardiac-modeling):
This **SimVascular** tool provides an automated workflow to generate CFD-ready models from medical images. It uses pre-trained deep neural network models to automatically generate segmentations for major cardiac structures, the four heart chambers, aorta and pulmonary arteries. The automatic cardiac segmentation tool utilized an ensemble of two-dimensional (2D) convolutional neural networks (CNNs) for automatic segmentation of cardiac structures from three-dimensional (3D) patient images and demonstrated state-of-the-art performance than prior approaches when evaluated on a benchmark dataset containing both magnetic resonance (MR) and computed tomography(CT) scans. This tool can be used from both the SimVascular&#39;s Python plugin in the GUI or from the command line version of the SimVascular Python.

###Cardiac Segmentation and Geometric Modeling

The SimVascular <strong>Cardiac Image Segmentation Tool</strong> uses pre-trained deep neural network models to automatically generate segmentations for major cardiac structures, the four heart chambers, aorta and pulmonary arteries. The automatic cardiac segmentation tool utilized an ensemble of two-dimensional (2D) convolutional neural networks (CNNs) for automatic segmentation of cardiac structures from three-dimensional (3D) patient images and demonstrated state-of-the-art performance than prior approaches when evaluated on a benchmark dataset containing both magnetic resonance (MR) and computed tomography(CT) scans. This tool can be used from both the SimVascular&#39;s Python plugin in the GUI or from the command line version of the SimVascular Python.



###Multi-physics Finite Element Solver

####[<strong>Multi-Physics Finite Element Solver</strong>](http://simvascular.github.io/docssvFSI.html):
<strong>svFSI</strong> is a new multi-physics finite element solver designed for computational modeling of the whole heart dynamics. As the next generation underlining solver for the <strong>SimVascular</strong> software, <strong>svFSI</strong> is capable of simulating myocardial electrical activity using state-of-the-art cellular activation models, employ nonlinear hyperelastic material models to simulate tissue mechanics and activation coupling strategies, and perform large deformation fluid-structure interaction (FSI) to simulate the dynamics between the heart tissue and blood flow. <strong>svFSI</strong> could also be used to perform blood flow simulations by imposing the ventricular wall motion extracted from medical image data.

<strong>svFSI</strong> is compatible with several mesh formats and can read a wide range of 2D and 3D element types. <strong>svFSI</strong> could be coupled to <a href="https://trilinos.github.io/index.html">Trilinos</a> linear solver library providing a wide choice of linear solvers and preconditioners for various applications. The methods employed are widely popular among the scientific community and continue to evolve through research and development. The solver is parallelized using MPI for inter-process communication and was demonstrated to scale efficiently on large supercomputing clusters. ParMETIS is used for partitioning the computational domains. Simulation results are outputted into VTK format that can be easily visualized in the free software <a href="https://www.paraview.org"> Paraview</a>.

The source code of <strong>svFSI</strong> is available on <a href="https://github.com/SimVascular/svFSI">GitHub</a> as part of the SimVascular project and the precompiled installers can be downloaded from <a href="https://simtk.org/projects/simvascular#">SimTK</a> website. A variety of examples are also available on <a href="https://github.com/SimVascular/svFSI-Tests">GitHub</a> for the users to get started quickly on using the solver. We recommend users to navigate through all the examples under a particular physics to educate themselves with the variety of options that the solver could accommodate. We also recommend users to use the existing input files as templates and make suitable modifications that meet their needs.
####[<strong>Purkinje Network Plugin</strong>](http://simvascular.github.io/docsSimCardio.html#purkinje):
SimVascular provides a Purkinje plugin that can be used to generate Purkinje network on arbitrary patient-specific cardiac models. Our Purkinje plugin uses a fractal-tree-based method to generate the network and provides a simple interface to adjust the parameters that control the network density and coverage. The Purkinje mesh is then exported in vtu format compatible with [**svFSI**](http://simvascular.github.io/docssvFSI.html) for the ensuing electrophysiology simulations.


####[<strong>Myocardial Fiber Orientation Generation</strong>](http://simvascular.github.io/docsSimCardio.html#fiber):
Both patient-specific cardiac mechanics modeling and electrophysiology modeling requires myocardial fiber orientation as an input. Here, we provide a pipeline to use rule-based algorithm to assign myocardial fiber orientation to patient-specific geometries. This pipeline takes advantage of existing SimVascular meshing tools and svFSI modeling capability.
12 changes: 0 additions & 12 deletions source/documentation/simcardio/cardiacModeling/_auto-ml-cardiac-segmentation.md
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion source/documentation/simcardio/cardiacModeling/_mesh-intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Mesh Generation
## Mesh Generation

The <strong>Cardiac Geometric Modeling Tool</strong> can be used to generate left ventricle (LV) meshes from
segmentation results. These meshes can then be used CFD modeling of LV flow combined with patient medical imaging data.
Expand Down
6 changes: 3 additions & 3 deletions source/documentation/simcardio/cardiacModeling/_mesh-lv-surface.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Constructing LV Surface Meshes ##
### Constructing LV Surface Meshes

### Using SimVascular Python Shell
#### Using SimVascular Python Shell

The SimVascular
<a href='http://simvascular.github.io/docsPythonInterface.html#python_shell'> Python Shell </a>
Expand Down Expand Up @@ -28,7 +28,7 @@ surface_main.py </a> Python surface generation script using the following comman
</code></pre>


###Using SimVascular Python Console
#### Using SimVascular Python Console

The SimVascular GUI <a href='http://simvascular.github.io/docsPythonInterface.html#console'> Python Console </a>
can be used for surface generation. Use the Python console <strong>Text Editor</strong> mode to enter the following Python commands
Expand Down
2 changes: 1 addition & 1 deletion source/documentation/simcardio/cardiacModeling/_mesh-motion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## Mesh Motion
### Mesh Motion

Once meshes have been registered the displacement of each mesh vertex over the whole cardiac cycle can be computed.
The series of registered meshes are interpolated using cubic splines to obtain mesh displacements with a temporal resolution
Expand Down
2 changes: 1 addition & 1 deletion source/documentation/simcardio/cardiacModeling/_mesh-register.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## Mesh Registration ##
### Mesh Registration

We can simulate the LV flow over time by tracking the deformation of the heart from time-resolved imaging and impose this motion
to the fluid domains inside the heart, which leads to a deforming-domain CFD problem. To be able to track the deformation of the
Expand Down
6 changes: 3 additions & 3 deletions source/documentation/simcardio/cardiacModeling/_mesh-volume.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
## Volumetric Meshing
### Volumetric Meshing

###Using SimVascular Python Shell
#### Using SimVascular Python Shell

The volumetric meshing script
<a href="https://github.com/SimVascular/SimVascular/tree/master/Python/site-packages/sv_auto_lv_modeling/modeling/volume_mesh_main.py">
Expand Down Expand Up @@ -30,7 +30,7 @@ volume\_mesh\_main.py </a> is used to generate a finite element mesh.
</code></pre>


###Using the SimVascular Python Console
#### Using the SimVascular Python Console

Within the Python plugin, we can use the <strong>Text Editor</strong> mode and enter the following lines to create a Python script.

Expand Down
2 changes: 1 addition & 1 deletion source/documentation/simcardio/cardiacModeling/_refs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# References
## References

<a id="ref-1"> <a href="https://doi.org/10.1115/1.4048032">
[1] Kong, F., and Shadden, S. C. (2020). **Automating Model Generation for Image-based Cardiac Flow Simulation**.
Expand Down
2 changes: 1 addition & 1 deletion source/documentation/simcardio/cardiacModeling/_seg-inputs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## Input Requirements ##
### Input Requirements

The preferred input format of the image volumes is <b>.nii.gz</b>, <b>.nii</b> or <b>.vti</b> files.
The segmentation method requires an image to have an identity orientation matrix.
Expand Down
2 changes: 1 addition & 1 deletion source/documentation/simcardio/cardiacModeling/_seg-intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Automated Image Segmentation
## Automated Image Segmentation

The SimVascular <strong>Cardiac Geometric Modeling Tool</strong> uses pre-trained deep neural network models to automatically
generate segmentations of major cardiac structures: the four heart chambers, aorta and pulmonary arteries. The segmentation tool
Expand Down
2 changes: 1 addition & 1 deletion source/documentation/simcardio/cardiacModeling/_seg-pre-trained-models.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## Pre-Trained Models ##
### Pre-Trained Models

We used the image and ground truth data provided by <a href='https://zmiclab.github.io/projects/mmwhs/'>MMWHS</a> to train our models.
Our segmentation models were trained simultaneously on CT and MR data. The trained weight data can be downloaded from
Expand Down
Loading