-
Notifications
You must be signed in to change notification settings - Fork 12
Expand file tree
/
Copy pathdocsSimCardio.html
More file actions
1649 lines (1272 loc) · 98.8 KB
/
docsSimCardio.html
File metadata and controls
1649 lines (1272 loc) · 98.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="author" content="">
<title>SimVascular Docs</title>
<link href="css/bootstrap.css" rel="stylesheet" type="text/css" />
<link href="css/shop-item.css" rel="stylesheet" type="text/css" />
<link href="css/codestyle.css" rel="stylesheet" type="text/css" />
<link rel="stylesheet" href="font-awesome-4.1.0/css/font-awesome.min.css">
<link rel="stylesheet" href="https://code.ionicframework.com/ionicons/1.5.2/css/ionicons.min.css">
<link rel="shortcut icon" href="img/favicon.ico">
<!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body>
<!-- Navigation -->
<nav class="navbar navbar-inverse navbar-fixed-top" role="navigation">
<div class="container">
<!-- Brand and toggle get grouped for better mobile display -->
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-main-collapse">
<i class="fa fa-bars" id="barIcon"></i>
</button>
<a class="navbar-brand" id="brandName" href="index.html">
<img src="img/svlogo/svLogoSmallText.png" alt="...">
</a>
</div>
<!-- Collect the nav links, forms, and other content for toggling -->
<div class="collapse navbar-collapse navbar-right navbar-main-collapse">
<ul class="nav navbar-nav">
<!-- USER GUIDES -->
<li>
<a href="#" id="dropdownMenu1" data-toggle="dropdown">
<b><span class="fa fa-user"></span> User Guides</b>
</a>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsQuickGuide.html"><b><span class="icon ion-ios7-bolt"></span> Getting Started</b></a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsModelGuide.html"><b><span class="icon ion-settings"></span> Modeling</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsMeshing.html"><b><span class="icon ion-ios7-keypad"></span> Meshing</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsFlowSolver.html"><b><span class="icon ion-play"></span> Simulation</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docssvFSI.html"><b><span class="icon ion-plus-round"></span> svFSI</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsSimCardio.html"><b><span class="icon ion-plus-round"></span> SimCardio</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsROMSimulation.html"><b><span class="icon ion-plus-round"></span> ROM Simulation</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsGenBC.html"><b><span class="icon ion-refresh"></span> GenBC</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsPythonInterface.html"><b><span class="icon ion-refresh"></span> Python Interface</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="docsReferences.html"><b><span class="icon ion-refresh"></span> References </b></a></li>
</ul>
</li>
<!-- CLINCAL CASES -->
<li>
<a href="#" id="dropdownMenu1" data-toggle="dropdown">
<b><i class="fa fa-stethoscope"></i> Clinical Cases</b>
</a>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="clinicalCase3.html"><b><span class="fa fa-user-md"></span> Coronary Normal</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="clinicalCase1.html"><b><span class="fa fa-user-md"></span> Aortofemoral Normal - 1</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="clinicalCase2.html"><b><span class="fa fa-user-md"></span> Aortofemoral Normal - 2</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="clinicalCase4.html"><b><span class="fa fa-user-md"></span> Healthy Pulmonary</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://simtk.org/projects/sv_tests"><b><span class="fa fa-user-md"></span> All demo projects</b></a></li>
</ul>
</li>
<!-- DEVELOPER GUIDES -->
<li>
<a href="#" id="dropdownMenu1" data-toggle="dropdown">
<b><span class="fa fa-caret-square-o-right"></span> Developer Guides</b>
</a>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/SimVascular/SimVascular/wiki/wiki_for_developers"><b><span class="fa fa-file-text-o"></span> Compile Source Code</b></a></li>
</ul>
</li>
<!-- svCOMMUNITY -->
<li>
<a href="#" id="dropdownMenu1" data-toggle="dropdown">
<b><i class="fa fa-users"></i> svCommunity</b>
</a>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://simtk.org/forums/viewforum.php?f=188"><b><span class="fa fa-users"></span> Public Forum</b></a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/SimVascular/SimVascular/wiki/"><b><span class="fa fa-file-text-o"></span> Wiki</b></a></li>
<li role="presentation" class="divider"></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://simtk.org/mailman/listinfo/simvascular-news"><b><span class="fa fa-sign-in"></span> Join News Mailing List</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://simtk.org/pipermail/simvascular-news/"><b><span class="fa fa-pencil-square-o"></span> News Mailing List Archive</b></a></li>
<li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/SimVascular/SimVascular/issues"><b><span class="fa fa-bug"></span> Report bugs and request features</b></a></li>
</ul>
</li>
<!-- REFERENCES -->
<li>
<a href="docsRefs.html" id="dropdownMenu1" >
<b><span class="icon ion-document-text"></span>References</b>
</a>
</li>
<!-- Archives -->
<li>
<a href="#" id="dropdownMenu1" data-toggle="dropdown">
<b> Archives</b>
</a>
<ul class="dropdown-menu" role="menu" aria-labelledby="dropdownMenu1">
<li role="presentation"><a role="menuitem" tabindex="-1" href="archiveQuickGuideSV2.html"><b>SimVascular 2.0</b></a></li>
</ul>
</li>
<!-- <li><a href="docsQuickGuide.html" id="btnQuickGuide"><b><span class="icon ion-ios7-bolt"></span> Quick Guide</b></a></li>
<li><a href="docsModelGuide.html" id="btnModelGuide"><b><span class="icon ion-settings"></span> Modeling</b></a></li>
<li><a href="docsMeshing.html" id="btnMeshing"><b><span class="icon ion-ios7-keypad"></span> Meshing</b></a></li>
<li><a href="docsPresolver.html" id="btnPresolver"><b><span class="icon ion-log-in"></span> svPre</b></a></li>
<li><a href="docsFlowSolver.html" id="btnFlowSolver"><b><span class="icon ion-play"></span> svSolver</b></a></li>
<li><a href="docsRefs.html" id="btnRefs"><b><span class="icon ion-document-text"></span> References</b></a></li>
<li><a href="clinicalCase1.html" id="btnRefs"><b>Case Studies</b></a></li> -->
</ul>
</div>
<!-- /.navbar-collapse -->
</div>
<!-- /.container -->
</nav>
<!-- Page Content -->
<!--Nav Bar -->
<div class="row">
<div class="col-xs-1 col-sm-1 hidden-md hidden-lg">
</div>
<!-- ONE COLUMN OF SPACE -->
<nav class="hidden-xs hidden-sm col-md-2 col-lg-2 bs-docs-sidebar">
<ul id="sidebar" class="nav nav-stacked fixed manSimCardio"> <p><h3>SimCardio Guide</h3></p>
<li><a href="#intro">Introduction</a></li>
<li><a href="#automatic-cardiac-modeling">Cardiac Geometric Modeling Tool </a>
<ul class="nav nav-stacked">
<li><a href="#auto-ml-cardiac-segmentation">Automated Image Segmentation</a>
<ul class="nav nav-stacked">
<li><a href="#seg-intro">Introduction</a></li>
<li><a href="#seg-inputs">Input Requirements</a></li>
<li><a href="#seg-pre-trained-models">Pre-Trained Models</a></li>
<li><a href="#seg-predict">Segmenting Image Data</a></li>
<li><a href="#seg-visualize">Visualization</a></li>
</ul>
</li>
<li><a href="#auto-meshing">Mesh Generation</a>
<ul class="nav nav-stacked">
<li><a href="#mesh-intro">Introduction</a></li>
<li><a href="#mesh-lv-surface">Constructing Surface <br>Meshes</a></li>
<li><a href="#mesh-volume">Volumetric Meshing</a></li>
<li><a href="#mesh-register">Mesh Registration</a></li>
<li><a href="#mesh-motion">Mesh Motion</a></li>
</ul>
</li>
<li><a href="#refs">References</a></li>
</ul>
</li>
<li><a href="#cep-modeling">Cardiac Electro- <br>physiology Modeling</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>
</ul>
</li>
<li><a href="#mechanics-modeling">Cardiac Mechanics <br> Modeling</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>
</ul>
</li>
</ul>
</nav>
<!--Main Content -->
<div class="col-xs-10 col-sm-10 col-md-9 col-lg-9" id="manualContent">
<!-- ACTUAL CONTENT -->
<div class="manSimCardio"><section id="intro" class="group"><h1>Introduction</h1>
<p>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.</p>
<p>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.</p>
<h3>Cardiac Segmentation and Geometric Modeling</h3>
<p>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’s Python plugin in the GUI or from the command line version of the SimVascular Python.</p>
<h3>Multi-physics Finite Element Solver</h3>
<p><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.</p>
<p><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>.</p>
<p>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.</p>
</section>
<section id="automatic-cardiac-modeling" class="group"><h1>Cardiac Geometric Modeling Tool</h1>
<p>The SimVascular <strong>Cardiac Geometric Modeling Tool</strong> is used to extract major cardiac structures from time-resolved imaging data
using automatic machine learning techniques. Volumetric meshes created from segmentation geometry are registered with image
data to extract heart wall motion that can be later used in multi-physics simulations of the heart using the <strong>svFSI</strong> solver.</p>
<p>The <strong>Cardiac Geometric Modeling Tool</strong> is implemented as the
<a href="https://github.com/SimVascular/SimVascular/tree/master/Python/site-packages/sv_auto_lv_modeling">
<b>sv_auto_lv_modeling</b> </a> Python package included with the SimVascular
application.</p>
</section>
<section id="seg-intro" class="subgroup"><h1>Automated Image Segmentation</h1>
<p>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
uses an ensemble of two-dimensional (2D) convolutional neural networks (CNNs) for automatic segmentation of cardiac structures from
three-dimensional (3D) patient images. It has been shown to have superior performance compared to prior approaches when evaluated on
a benchmark dataset containing both magnetic resonance (MR) and computed tomography (CT) image data <a href="#ref-1">[1]</a>.
The tool can be used from both the SimVascular GUI Python console and from the command line within the SimVascular Python
environment. </p>
</section>
<section id="seg-inputs" class="subgroup"><h2>Input Requirements</h2>
<p>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. </p>
<div style="background-color: #F0F0F0; padding: 10px; border: 1px solid #e6e600; border-left: 6px solid #e6e600">
The VTK version used by SimVascular does not written a <b>.vti</b> file with an orientation matrix. Image <b>.vti</b> files
written by SimVascular must therefore be reoriented to have an identity orientation matrix when used for segmentation.
</div>
<p><br>
The directory containing the input image data should be organized as follows</p>
<pre><code>image_dir
|__ patient_id (optional)
|__ image_volume0.vti
|__ image_volume1.vti
|__ image_volume2.vti
|__ ...
</code></pre>
</section>
<section id="seg-pre-trained-models" class="subgroup"><h2>Pre-Trained Models</h2>
<p>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
<a href='https://drive.google.com/open?id=162Xr5OezSZL-0K3aoYO7WnHWuGTEXkkj'>here</a>.</p>
</section>
<section id="seg-predict" class="subgroup"><h2>Segmenting Image Data</h2>
<h3>Segmenting using the SimVascular Python shell</h3>
<p>3D CT or MR image volumes can be segmented within the SimVascular
<a href='http://simvascular.github.io/docsPythonInterface.html#python_shell'> Python Shell </a> using the
<a href="https://github.com/SimVascular/SimVascular/blob/master/Python/site-packages/sv_auto_lv_modeling/segmentation/prediction.py">
prediction.py </a> Python script. For example</p>
<pre><code class='language-shell' lang='shell'>
data_path=/path/to/data
sv_python_dir=/usr/local/bin
script_dir=SimVascular/Python/site-packages/sv_auto_lv_modeling
patient_id=WS01
image_dir=$data_path/01-Images
output_dir=$data_path/02-Segmnts
weight_dir=$data_path/Weights
${sv_python_dir}/simvascular --python -- $script_dir/segmentation/prediction.py \
--pid $patient_id \
--image $image_dir \
--output $output_dir \
--model $weight_dir \
--view 0 1 2 \ # 0 for axial, 1 for coronal, 2 for sagittal
--modality ct # ct or mr
</code></pre>
<h3>Segmenting using the SimVascular GUI Python Console</h3>
<p>Image segmentation can also be performed from within the SimVascular GUI
<a href='http://simvascular.github.io/docsPythonInterface.html#console'> Python console </a>.
Use the Python console <strong>Text Editor</strong> mode to enter the following Python commands </p>
<pre><code class='language-python' lang='python'>
from auto_lv.auto_lv import Segmentation
data_path='/path/to/data'
seg = Segmentation()
seg.set_modality('ct')
seg.set_patient_id ('WS01')
seg.set_image_directory (data_path+'/01-Images')
seg.set_output_directory (data_path+'/02-Segmnts')
seg.set_model_directory ([data_path+'/Weights'])
seg.set_view ([2])
seg.generate_segmentation()
</code></pre>
<p>and execute them.</p>
</section>
<section id="seg-visualize" class="subgroup"><h2>Visualizing Segmentation Results</h2>
<p>Segmentation results can be visualized using SimVascular by first creating a SimVascular project. The segmentation results <b>.vti</b> file
is then added as an image by right-clicking <strong>Images</strong> under the <b>SV Data Manager</b> and selecting the
<strong>Add/Replace Image</strong> menu item. The following two pictures show an example of CT image and the segmentation results.</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/cardiacModeling/images/images.png">
<figcaption class="svCaption"> CT image data. </figcaption>
</figure>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/cardiacModeling/images/segmentation.png">
<figcaption class="svCaption"> Segmentation results of the CT image data. </figcaption>
</figure>
<p>Segmentation results can be visualized using ParaView. </p>
</section>
<section id="mesh-intro" class="subgroup"><h1>Mesh Generation</h1>
<p>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.
The <strong>LV Mesh Generation</strong> tool is used to automatically generate meshes for simulation. It takes as input a
segmentation and outputs reconstructed LV surface meshes. </p>
<p>Python scripts are provided for extracting a series of surfaces representing heart wall motion by registering surface meshes
to time-resolved imaging data using the <a href='https://simpleelastix.github.io/'>SimpleElastix</a> medical image registration software.
These time-series surface meshes can also be interpolated temporally to obtain the resolution needed for simulations.</p>
</section>
<section id="mesh-lv-surface" class="subgroup"><h2>Constructing LV Surface Meshes</h2>
<h3>Using SimVascular Python Shell</h3>
<p>The SimVascular
<a href='http://simvascular.github.io/docsPythonInterface.html#python_shell'> Python Shell </a>
can be used to run the
<a href="https://github.com/SimVascular/SimVascular/tree/master/Python/site-packages/sv_auto_lv_modeling/modeling/surface_main.py">
surface_main.py </a> Python surface generation script using the following commands</p>
<pre><code class='language-shell' lang='shell'>
# Path to SimVascular executable
data_path=/path/to/data
sv_python_dir=/usr/local/bin
script_dir=SimVascular/Python/site-packages/sv_auto_lv_modeling
# Path to the segmentation results
p_id=WS01
input_dir=$data_path/02-Segmnts/$p_id
# Path to the outputed surface meshes
output_dir=$data_path/03-Surfaces/$p_id
model_script=$script_dir/modeling/surface_main.py
# Construct LV surface meshes with tagged boundary faces
${sv_python_dir}/simvascular --python \
-- ${model_script} \
--input_dir ${input_dir} \
--output_dir ${output_dir} \
--edge_size 3.5 # maximum edge size for the mesh
</code></pre>
<h3>Using SimVascular Python Console</h3>
<p>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 </p>
<pre><code class='language-python' lang='python'>from sv_auto_lv_modeling.auto_lv import Modeling
data_path='/path/to/data'
surf = Modeling()
surf.set_segmentation_directory(data_path+'/02-Segmnts/WS01')
surf.set_output_directory (data_path+'/03-Surfaces/WS01')
surf.set_max_edge_size (3.5)
surf.generate_lv_modes ()
</code></pre>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/cardiacModeling/images/surface.png">
<figcaption class="svCaption" >Automatically created LV meshes at diastole and systole.</figcaption>
</figure>
</section>
<section id="mesh-volume" class="subgroup"><h2>Volumetric Meshing</h2>
<h3>Using SimVascular Python Shell</h3>
<p>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">
volume_mesh_main.py </a> is used to generate a finite element mesh.</p>
<pre><code class='language-shell' lang='shell'>
# Path to SimVascular executable
data_path=/path/to/data
sv_python_dir=/usr/local/bin
script_dir=SimVascular/Python/site-packages/sv_auto_lv_modeling
p_id=WS01
# Path to the surface meshes
input_dir=$data_path/04-SurfReg/$p_id
# Path to the outputted volume meshes
output_dir=$data_path/05-VolMesh/$p_id
volume_mesh_script=$script_dir/modeling/volume_mesh_main.py
# Volumetric Meshing using SimVascular
${sv_python_dir}/simvascular --python \
-- ${volume_mesh_script} \
--input_dir $input_dir \
--output_dir $output_dir \
--phase 0 \ # the phase id in $input_dir to generate a volumetric mesh
--edge_size 3.5
</code></pre>
<h3>Using the SimVascular Python Console</h3>
<p>Within the Python plugin, we can use the <strong>Text Editor</strong> mode and enter the following lines to create a Python script.</p>
<pre><code class='language-python' lang='python'>
from sv_auto_lv_modeling.auto_lv import VolumeMesh
data_path='/path/to/data'
vol = VolumeMesh()
vol.set_output_directory (data_path+'/05-VolMesh/WS01')
vol.set_max_edge_size (3.5)
vol.set_surface_model_filename (data_path+'/04-SurfReg/WS01/WS01_0.vti.vtp')
vol.generate_volume_mesh()
</code></pre>
</section>
<section id="mesh-register" class="subgroup"><h2>Mesh Registration</h2>
<p>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
generated LV mesh over time, we need to building point-corresponded LV meshes from segmentations at all time frames. We generate a
surface mesh at one time frame and propagated to the others using the displacement field obtained from registering the corresponding
segmentations.</p>
<p>The
<a href="https://github.com/SimVascular/SimVascular/blob/master/Python/site-packages/sv_auto_lv_modeling/modeling/elastix_main.py">
elastix_main.py </a> script is used to perform the registration. It uses uses the
<a href='https://github.com/SuperElastix/SimpleElastix'>SimpleElastix</a> software for registration.</p>
<div style="background-color: #F0F0F0; padding: 10px; border: 1px solid #e6e600; border-left: 6px solid #e6e600">
For code compatibility you will need to use <b>SimpleElastix</b> commit 8244e0001f4137514b0f545f1e846910b3dd7769.
</div>
<p><br></p>
<pre><code class='language-shell' lang='shell'>
# Use SimpleElastix to register surface meshes
data_path=/path/to/data
sv_python_dir=/usr/local/bin
script_dir=SimVascular/Python/site-packages/sv_auto_lv_modeling
# Path to the ct/mr images or segmentation results
p_id=WS01
image_dir=$data_path/01-Images/$p_id
mask_dir=$data_path/02-Segmnts/$p_id
# Path to the unregistered surface mesh
surface_dir=$data_path/03-Surfaces/$p_id
# Path to the registered surface meshes
output_dir=$data_path/04-SurfReg/$p_id
# Phase ID of the surface mesh used as the registration source
start_phase=0
# Registration with SimpleElastix
python $script_dir/modeling/elastix_main.py \
--image_dir $mask_dir \
--mask_dir $mask_dir \
--output_dir $output_dir \
--start_phase $start_phase \
--surface_dir $surface_dir \
--image_file_extension vti \
--edge_size 3.5
</code></pre>
</section>
<section id="mesh-motion" class="subgroup"><h2>Mesh Motion</h2>
<p>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
suitable for simulations. </p>
<p>The
<a href="https://github.com/SimVascular/SimVascular/blob/master/Python/site-packages/sv_auto_lv_modeling/modeling/elastix_main.py">
interpolation.py </a> script is used to interpolate meshes and compute the mesh motion. It writes out a <b>.dat</b> file for each
boundary face that can used in svFSI to set up the displacement boundary conditions</p>
<pre><code class='language-shell' lang='shell'>
# Generate motion.dat File for svFSI
data_path=/path/to/data
sv_python_dir=/usr/local/bin
script_dir=SimVascular/Python/site-packages/sv_auto_lv_modeling
# Phase ID should be the same as the one used in volume_mesh.sh
phase_id=0
p_id=WS01
# Path to the registered surface meshes
input_dir=$data_path/04-SurfReg/$p_id
# Path to the outputted volumetric meshes
output_dir=$data_path/05-VolMesh/$p_id
# Number of interpolations between adjacent phases
num=99
# Number of cardiac cycles
cyc=1
# Cycle duration in seconds
period=1.25
# Write boundary conditions for FSI simulations
python $script_dir/modeling/svfsi/interpolation.py \
--input_dir $input_dir \
--output_dir $output_dir \
--num_interpolation $num \
--num_cycle $cyc \
--duration $period \
--phase $phase_id
</code></pre>
<p><br><br><br><br></p>
</section>
<section id="refs" class="subgroup"><h1>References</h1>
<p><a id="ref-1"> <a href="https://doi.org/10.1115/1.4048032">
[1] Kong, F., and Shadden, S. C. (2020). <strong>Automating Model Generation for Image-based Cardiac Flow Simulation</strong>.
ASME. J Biomech Eng. </a> </p>
<p><br><br><br><br><br></p>
</section>
<section id="cep-modeling" class="group"><h1>Cardiac Electrophysiology Simulation Guide</h1>
</section>
<section id="cep-intro" class="subgroup"><h2>Introduction</h2>
<p>The electrical activity in a heart is initiated at the sinoatrial node, which is located at the right atrium of the heart. A small cluster of pacemaker cells periodically emits electrical signals into the heart’s conduction system. These signals first travel at a high speed through a network of special cells that allows the signals to reach the whole heart rapidly. Finally, they travel into the ventricular muscles, and cause the entire heart to contract almost simultaneously. The electrical signals travel between cells through a process called depolarization, during which voltage-sensitive protein channels on the cell membrane open to allow positively charged ions to move in and out of the cell, leading to ionic currents.</p>
</section>
<section id="cep-theory" class="subgroup"><h2>Mathematical Model of Cardiac Electrophysiology</h2>
<p>The propagation of electrical signal in the heart is governed by a reaction-diffusion like equation,</p>
<p>$$\frac{\partial V}{\partial t} + \frac{I_{ion} - I_{app}(t)}{C_m} = \nabla \cdot\left( \mathbf{D}\nabla V \right) $$
$$ \mathrm{in~} \Omega^E\times(0,T] \nonumber$$
$$(\mathbf{D}\nabla V) \cdot \mathbf{N}=0 \mathrm{~on~} \partial\Omega^E\times(0,T]$$</p>
<p>$V$ is the local transmembrane potential. $C_m$ is the local membrane capacitance per unit area. $I_{ion}$ and $I_{app}$ are the ionic current flux (current per unit area) and applied external current flux, respectively. Here, $\mathbf{D}$ dictates the propagation velocity of the electrical signal and has the similar physical meaning as the diffusivity. It is calculated as</p>
<p>$$
\mathbf{D} =\frac{\sigma}{\chi C_m}
$$</p>
<p>$\sigma$ is the conductivity tensor and has the unit $S/m$. $\chi$ is the ratio of membrane area over tissue volume. Then, $\mathbf{D}$ is a tensor with the dimension $Length^2/Time$.</p>
<p>The above equation is the mono-domain description of the cardiac electrophysiology, i.e. we don’t solve the intra- and extra-cellular electrical signal propagation separately. The mono-domain and multi-domain conductivities are connected through the following relation,</p>
<p>$$ \sigma = \frac{\sigma_i\sigma_e}{\sigma_i + \sigma_e} $$</p>
<p>where $\sigma_i$ and $\sigma_e$ are the intra- and extra-cellular conductivity tensors <a href="#ref-1">[1]</a>. It is commonly assumed that the conductivity is transversely isotropic,</p>
<p>$$ \mathbf{\sigma} = \sigma_f \mathbf{f}\otimes \mathbf{f} + \sigma_s (\mathbf{I}-\mathbf{f}\otimes \mathbf{f}) $$</p>
<p>where $\sigma_f$ and $\sigma_s$ are the conductivities along the fiber direction and in the transverse plane. $\mathbf{f}$ is the fiber direction vector.</p>
<p>In <strong>svFSI</strong>, we directly specify $\mathbf{D}$ in the input file. We choose a slightly different form to enforce the transverse isotropy of the conductivity tensor,</p>
<p>$$ \mathbf{D} = D_{iso}\mathbf{I} + \sum_{n=1}^{nsd}D_{ani,n}\mathbf{fN}_n\otimes\mathbf{fN}_n $$</p>
<p>Here, $nsd$ is the dimension, and $\mathbf{fN_n}$ is the local orthonormal coordinate system built by fiber direction and sheet direction. To connect with the previous expression, we have $D_f=D_{iso}+D_{ani}$ and $D_s=D_{iso}$.</p>
</section>
<section id="cep-activation-models" class="subgroup"><h2>Cellular Activation Models</h2>
<p>Depending on how the depolarization and repolarization within a single cardiac myocyte is described, the electrophysiology models can be roughly divided into two categories: biophysics-based ionic models (such as the ten Tusscher-Panfilov (TTP) model<a href="#ref-2">[2]</a><a href="#ref-3">[3]</a>), and phenomenological models (such as the Aliev-Panfilov (AP), Fitzhugh-Nagumo (FN) models<a href="#ref-4">[4]</a>).</p>
<h3>Biophysics-based Ionic Models</h3>
<p>Between cardiac myocytes, the propagation of the electrical signal is enabled by the transmembrane motion of different ions, such as $K^+$, $Na^+$ and $Ca^{2+}$ during depolarization and repolarization of the myocytes. Cellular biophysics-based activation models are designed to capture these ionic movements. One of the popular biophysics-based ionic models, the TTP model <a href="#ref-3">[3]</a> is implemented in <strong>svFSI</strong>. Here, we will briefly illustrate the ionic currents involved in the TTP model.</p>
<p>In the TTP model, the ionic current is expressed as</p>
<p>$$ I_{ion} = I_{Na} + I_{Kl} + I_{to} + I_{Kr} + I_{Ks} + I_{CaL} + I_{NaCa} + I_{NaK} + I_{pCa} + I_{pK} + I_{bCa} + I_{bNa} $$</p>
<p>The governing equations for each current can be found in <a href="#ref-3">[3]</a>.</p>
<p>Since, intracellular calcium concentration is the driving factor behind excitation-contraction coupling, we focus on the calcium dynamics here. In the TTP model,the following calcium concentrations are included:</p>
<ul>
<li> $Ca_{itotal}$: total (free+buffered) cytoplasmic $Ca^{2+}$ concentration.</li>
<li> $Ca_{SRtotal}$: total SR $Ca^{2+}$ concentration.</li>
<li> $Ca_{SStotal}$: total dyadic space $Ca^{2+}$ concentration.</li>
<li> $Ca_i$: free cytoplasmic $Ca^{2+}$ concentration.</li>
<li> $Ca_{SR}$: free SR $Ca^{2+}$ concentration.</li>
<li> $Ca_{SS}$: free dyadic space $Ca^{2+}$ concentration.</li>
</ul>
<p>Sarcoplasmic reticulum (SR) is a membrane structure within the muscle cell, whose main function is to store $Ca^{2+}$. Dyadic space is the region bounded by the T-tubule and SR. $Ca^{2+}$ ions are considered buffered if they are bound to negatively charged proteins (called buffers). Otherwise they are considered free. The action potential transmitted through the gap junction cause the current myocyte to depolarize. The depolarization opens the L-type (long-lasting) Ca channel located on the surface membrane. A small amount of $Ca^{2+}$ enters the myocyte due to potential, leading to a sharp increase of $Ca^{2+}$ in the dyadic space, which is a small region. This increase triggers the SR to release a large amount of $Ca^{2+}$ (calcium-induced calcium release) to enable the excitation-contraction. During diastole, calcium is removed from the cytoplasm through two ways. Ca is pumped (1) back into the SR and (2) out of the cell, mainly by the sodium-calcium exchange (NCX).</p>
<p>For the TTP model in <strong>svFSI</strong>, the following units have to be used: time in [ms], length [mm], amount of substance [mmol], voltage [mV]. Mass can be in [g].</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/Calcium.png">
<figcaption class="svCaption" >Structures involved in $Ca^{2+}$ cycling<a href="#ref-6">[6]</a>.</figcaption>
</figure>
<h3>Phenomenological Models</h3>
<p>Phenomenological models are derived based on some observations of the full ion model <a href="#ref-4">[4]</a>. Instead of following the transmembrane ionic currents, they use an oscillation system with a fast ($V$) and a slow ($r$) variable to mimic the behaviors of the action potentials. The oscillators, without considering the diffusion term, are modeled as</p>
<p>$$ \frac{\mathrm{d}V}{\mathrm{d}t}=f^{V}(V,r) $$
$$ \frac{\mathrm{d}r}{\mathrm{d}t}=f^{r}(V,r) $$</p>
<p>Note that this set of equations describes the electrophysiology in a single cardiac myocyte, and the choice of $f^V$ and $f^r$ will determine if this is a pacemaker cell or a non-pacemaker cell.</p>
<p>The FitzHugh-Nagumo (FN) model describes the pacemaker cells with</p>
<p>$$ f^V = c[V(V-\alpha)(1-V)-r] $$
$$ f^r = V-br+a $$</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/FN_model.png">
<figcaption class="svCaption" >Action potential calculated from FitzHugh-Nagumo model.</figcaption>
</figure>
<p>The Aliev-Panfilov (AP) model describes the non-pacemaker cells with</p>
<p>$$ f^V = cV(V-\alpha)(1-V)-Vr $$</p>
<p>$$ f^r = \left( \gamma+\frac{\mu_1r}{\mu_2+V}\right)[-r-cV(V-b-1)] $$</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/AP_model.png">
<figcaption class="svCaption" >Action potential calculated from Aliev-Panfilov model.</figcaption>
</figure>
<p>Note that $V$ and $t$ are non-dimensional values here. The following equations are used to recover the physiological action potential and time:</p>
<p>$$ \mathrm{FitzHugh-Nagumo model}: V^{fhn}=(65V-35)mV; ~~ t^{fhn} = (220t) ms $$</p>
<p>$$ \mathrm{Aliev-Panfilov model}: V^{ap}=(100V-80)mV; ~~ t^{ap} = (12.9t) ms $$</p>
<p>Another class of phenomenological models exists that include additional variables to account for intra-cellular calcium kinetics. One such model is the Bueno-Orovio (BO) model <a href="#ref-5">[5]</a> that can serve as a trade-off between the complex TTP model and the simplified phenomenological AP model.</p>
<h3>Activation Models Available in svFSI</h3>
<p>The following table provides a summary of all the available electrophysiology models in <strong>svFSI</strong>.</p>
<p><table class="table table-bordered">
<caption>Available cardiac electrophysiology models.</caption>
<thead>
<tr>
<th>Electrophysiology Model</th>
<th>Input Keyword</th>
</tr>
</thead>
<tr>
<td>Aliev-Panfilov model<a href="#ref-4">[4]</td>
<td>“ap”, “aliev-panfilov”</td>
</tr>
<tr>
<td>Fitzhugh-Nagumo model<a href="#ref-4">[4]</a></td>
<td>“fn”, “fitzhugh-nagumo”</td>
</tr>
<tr>
<td>Bueno-Orovio-Cherry-Fenton model<a href="#ref-5">[5]</a></td>
<td>“bo”, “bueno-orovio”</td>
</tr>
<tr>
<td>tenTusscher-Panfilov model<a href="#ref-3">[3]</a></td>
<td>“ttp”, “tentusscher-panfilov”</td>
</tr>
</table></p>
</section>
<section id="purkinje" class="subgroup"><h2>Purkinje Network Plugin Tutorial</h2>
</section>
<section id="pnet-intro" class="subgroup"><h2>Introduction</h2>
<p>The electrical activity in the heart tissue triggers muscle contraction and pumps blood into the systemic circulation. Under normal conditions, the electrical signal originates at the sinoatrial node located in the right atrium and reaches the atrioventricular node, which is the only electrical joint between the atria and the ventricles. <a href="#ref-7">[7]</a> The bundle of His connects the atrioventricular node to a fast conducting network of fibers, called the Purkinje network, located beneath the inner-most layer of the heart wall. Purkinje cells are larger than the cardiomyocytes and conduct the excitation wave faster than any other cell on the heart tissue. <a href="#ref-7">[7]]</a> The network not only synchronizes contraction between the left and the right ventricles but also allows the trajectory to follow a sequence beginning at the ventricular apex, spreading through the free-wall and eventually to the basal plane. Modeling the Purkinje network in cardiac electrophysiology simulations is therefore essential to achieve a realistic activation pattern and tissue contraction.</p>
<p>SimVascular provides a <strong>Purkinje plugin</strong> 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 <a href="#ref-8">[8]</a> 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 <strong>SimVascular/svFSI</strong> for the ensuing electrophysiology simulations.</p>
<p>In the following sections, we describe steps to download and install the Purkinje plugin, provide a workflow for creating Purkinje network using the plugin.</p>
</section>
<section id="pnet-install" class="subgroup"><h2>Plugin Installation</h2>
<p>The installer for the Purkinje plugin can be found on the <a href="https://simtk.org/projects/simvascular/">Simtk</a> website. The installer installs the shared libraries, the setup.sh script and a Python script in, <br/></p>
<p><code> <font color="black"> /usr/local/sv/svplugins/<strong>SVDATE</strong>/Purkinje-Plugin/<strong>PLUGINDATE</strong> </font> </code></p>
<p>Make sure that the SVDATE matches with the date of the installed SimVascular application. If there is a mismatch, you may rename the SVDATE folder to match with the installed SimVascular application. The setup.sh script sets the SV<em>CUSTOM</em>PLUGINS and SV<em>PLUGIN</em>PATH environment variables. The SV<em>CUSTOM</em>PLUGINS environment variable defines the name of the plugin (e.g. org<em>sv</em>gui<em>qt</em>purkinjenetwork) and the SV<em>PLUGIN</em>PATH environment variable defines the location of the plugin shared library (e.g. liborg<em>sv</em>gui<em>qt</em>purkinjenetwork.so).</p>
<p>If successfully installed, the Purkinje Network tool icon automatically shows up on the main toolbar when the SimVascular application is launched.</p>
</section>
<section id="pnet-workflow" class="subgroup"><h2>Purkinje Plugin Workflow & Usage</h2>
<p>The Purkinje plugin can be applied only on a SimVascular generated mesh and not on the model. Therefore, it is recommended that the user first create a mesh either by following the regular workflow (i.e., Image, Path, Segmentation, Model and Mesh) or by importing a solid model using the Models tool. In the example below, we use the latter approach and load the left ventricular endocardium directly into the SV project. We then mesh the volume before using the plugin to generate Purkinje network.</p>
<!-- Modeling & Meshing -->
<h3>Create SV mesh</h3>
<p>After creating an SV project, right-click on the Models tab to import a left ventricular solid model (.vtp) and run the Global Reinit command. During the import, extract faces on the model using the default settings.</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/create-project.png">
<figcaption class="svCaption" >Create a project or open an existing one.</figcaption>
</figure>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/import-model.png">
<figcaption class="svCaption" >Import .vtp surface file that you want to create a Purkinje network on.</figcaption>
</figure>
<p>Rename the surfaces in the imported solid model and select types from the drop down menu. Optionally assign colors to each surface to identify them easily. Identify the endocardium of the left ventricle and set it as a wall.</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/rename-surfaces.png">
<figcaption class="svCaption" >Rename the surfaces and set types to wall/cap where appropriate.</figcaption>
</figure>
<p>The imported left ventricular model may appear as shown below,</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/imported-renamed-model.png">
<figcaption class="svCaption" >Imported left ventricular endocardium for creating the Purkinje network.</figcaption>
</figure>
<p>We now mesh the model before adding the Purkinje network tool. Create a new mesh under Meshes tab and open the SV Meshing window. Enter an appropriate max. edge size, deselect the Volume Meshing and run the mesher. Once the surface mesh is successfully generated, a window pops up with information about the mesh.</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/create-mesh.png">
<figcaption class="svCaption" >Create a mesh under Meshes tab.</figcaption>
</figure>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/mesh-params.png">
<figcaption class="svCaption" >Set mesh Global Max Edge Size and run the mesher.</figcaption>
</figure>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/mesh-stats.png">
<figcaption class="svCaption" >Once the mesh is successfully generated, the mesh stats window pops up.</figcaption>
</figure>
<h3>Plugin workflow</h3>
<p>Here we provide a brief overview of the workflow to generate Purkinje network. Once the mesh is created, activate the Purkinje plugin so that it displays the triangular surfaces of the mesh. Purkinje network can then be created using the following steps:</p>
<ol>
<li>Select a face on the mesh </li>
<li>Select the network starting point on the face </li>
<li>Set network generation parameters</li>
<li>Generate the network</li>
<li>Display the network</li>
<li>Repeat the above steps until satisfied</li>
<li>Export the network data</li>
</ol>
<p>Below we provide a detailed description of the above steps with illustrations.</p>
<p>First, activate the Purkinje Network tool on the SimVascular toolbar that brings up the Purkinje Network tool panel. If the Purkinje Network window is already visible upon launching the SimVascular application, it is recommended to close the window and reactivate it only after an SV project has been created or loaded into the Data Manager.</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/purkinje-tool.png">
<figcaption class="svCaption" >Activate Purkinje tool by clicking the Purkinje Network icon shown on the toolbar.</figcaption>
</figure>
<p>A mesh face is selected by moving the mouse cursor over a face and pressing the <strong>s</strong> key. Select the endocardium face you want to generate the Purkinje network on. The selected face mesh is highlighted in yellow and its name is displayed in the Mesh Surface text box.</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/select-surface.png">
<figcaption class="svCaption" >Select the surface to generate the Purkinje network on.</figcaption>
</figure>
<p>Provide a starting point of the Purkinje network by moving the mouse cursor to a node on the highlighted face mesh and pressing Ctrl(Cmd for OSX)+left-click. A red sphere marks the selected node and a red line segment showing the direction of the network is displayed. Adjust the starting point and direction by repeating the selection.</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/select-point.png">
<figcaption class="svCaption" >Select the starting point and direction of the Purkinje network.</figcaption>
</figure>
<p>Adjust the control parameters of the Purkinje network and generate by selecting the Create Network button. The network is displayed by checking the Show Network box. You can repeat the selection of the initial point and network creation until the results are satisfactory. A detailed description of the network control parameters is provided <a href="#parameters">below</a>.</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/create-network.png">
<figcaption class="svCaption" >Create the Purkinje network after adjusting parameters.</figcaption>
</figure>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/display-network.png">
<figcaption class="svCaption" >Purkinje network is overlaid on the mesh in the Display window.</figcaption>
</figure>
<p>The network is saved in .vtu format under the Purkinje-Network sub-folder of the project directory. Additionally you can find the .txt files that contain the information of end nodes, position coordinates, and network connectivity under the same folder. Further details about the contents of each file is provided <a href="#output">below</a>.</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/purkinje-paraview.png">
<figcaption class="svCaption" >The Purkinje network visualized in Paraview .</figcaption>
</figure>
<h3>Output Description</h3>
<p>The Purkinje Network tool writes a set of files in the Purkinje-Network sub-folder within the SimVascular project directory. The files are prefixed with the name of the selected face. The files and their contents are described below:</p>
<ul>
<li> <code> <font color="black"> FACENAME.vtp </font> </code> - triangular surface on which the network is generated. </li>
<li> <code> <font color="black">FACENAME.vtu </font> </code> - network mesh represented as polylines of $n$ segments and $(n+1)$ nodes.</li>
<li> <code> <font color="black">FACENAME_endnodes.txt </font> </code> - indices of nodes at the ends of network segments (i.e. not connected to other nodes).</li>
<li> <code> <font color="black">FACENAME_ien.txt </font> </code> - network connectivity.</li>
<li> <code> <font color="black">FACENAME_xyz.txt </font> </code> - network nodal coordinates.</li>
</ul>
</section>
<section id="pnet-parameters" class="subgroup"><h2>Network Control Parameters</h2>
<p>The Purkinje network is generated using a Python script. The inputs to the script include a triangular surface, the network starting point, a second point defining the direction of the first network branch, and the parameters used to control the shape, density and spread of the network <a href="#ref-2">[2]</a>. These parameters are described below:</p>
<ul>
<li>Starting point - initial node of the network.</li>
<li>Second point - defines the direction along which the network’s initial branch will grow.</li>
<li>Number of branch generations - denotes the maximum number of network branches generated from the initial node.</li>
<li>Average branch length - the length of each branch is calculated from a random normal distribution with a mean length, $L$ and a variance, $0.4 L^2$.</li>
<li>Branch angle - the angle between direction of the previous branch and a new branch.</li>
<li>Repulsive parameter - regulates the branch curvature (higher value leads to greater repulsion between the branches).</li>
<li>Branch segment length - an approximate length of the segments that compose one branch.</li>
</ul>
</section>
<section id="pnet-issues" class="subgroup"><h2>Known Issues</h2>
<ol>
<li>SimVascular does not record that the plugin was added to a project. The plugin must be added to the project every time a project is opened. The project **Purkinje-Network** directory is saved between project sessions.</li>
<li>The tool may not work if the Purkinje Network tool is added to a project before a mesh is created or loaded. </li>
<li>The Purkinje Network tool does not know when the mesh changes. If the mesh is changed then the project must be saved and then reopened.</li>
<li>There is no error reporting from the Python script. Users must check the console window for errors.</li>
<li>The vtu mesh generated by the plugin cannot be read by svFSI as it is in ASCII format. A temporary solution is to export a regular appended/binary vtu from Paraview.</li>
</ol>
</section>
<section id="cep-examples" class="subgroup"><h2>Examples</h2>
<p>In this section, we will provide two examples of cardiac electrophysiology modeling. The first example is a widely used benchmark test, activation of a block of cardiac tissue <a href="#ref-1">[1]</a>. The second example is the propagation of action potential in the Purkinje fibers. More examples are available on <a href="https://github.com/SimVascular/svFSI-Tests/tree/master/08-cep">GitHub</a>.</p>
</section>
<section id="cep-example-block" class="subgroup"><h2>Activation of a Myocardial Block</h2>
<p>The computational domain is a rectangular block, with dimensions of $3\times 7\times 20 mm$. A small cluster of cells located at one corner of the block (marked as S) will recive an initial stimulus, and the TTP model is used to model the activation of the rest of the domain. The entire simulation set-up along with results can be found on <a href="https://github.com/SimVascular/svFSI-Tests/tree/master/08-cep/03-benchmark_tTP">GitHub</a>.</p>
<figure>
<img class="svImg svImgMd" src="documentation/simcardio/electrophysiology/images/cuboid.png">
<figcaption class="svCaption" >Computational domain of example 1.[reference]</figcaption>
</figure>
<p>Here is the breakdown of the input file for this study.</p>
<pre class="highlight plaintext"><code>
# File svFSI.inp
#----------------------------------------------------------------
# General simulation parameters
Continue previous simulation: f
Number of spatial dimensions: 3
Number of time steps: 100000
Time step size: 0.01
Spectral radius of infinite time step: 0.50
Searched file name to trigger stop: STOP_SIM
Save results to VTK format: 1
Name prefix of saved VTK files: result
Increment in saving VTK files: 100
Start saving after time step: 1
Increment in saving restart files: 100
Convert BIN to VTK format: 0
Verbose: 1
Warning: 1
Debug: 0
#----------------------------------------------------------------
# Mesh data
Add mesh: msh {
Mesh file path): mesh/h0.1/mesh-complete.mesh.vtu
Add face: X0 {
Face file path: mesh/h0.1/mesh-surfaces/X0.vtp
}
Add face: X1 {
Face file path: mesh/h0.1/mesh-surfaces/X1.vtp
}
Add face: Y0 {
Face file path: mesh/h0.1/mesh-surfaces/Y0.vtp
}
Add face: Y1 {
Face file path: mesh/h0.1/mesh-surfaces/Y1.vtp
}
Add face: Z0 {
Face file path: mesh/h0.1/mesh-surfaces/Z0.vtp
}
Add face: Z1 {
Face file path: mesh/h0.1/mesh-surfaces/Z1.vtp
}
Fiber direction: (1, 0, 0)
# Here we also need to supply a domain information to separate
# pacemaker cells and non-pacemaker cells. domain_info.dat
# is a plaintext file store the domain ID of each element.
# id == 1: non-pacemaker cells
# id == 2: pacemaker cells (recivies stimulus)
Domain file path: mesh/h0.1/domain_info.dat
}
#----------------------------------------------------------------
# Equations
Add equation: CEP {
Coupled: 1
Min iterations: 1
Max iterations: 5
Tolerance: 1e-6
# Here domain id == 1 are non-pacemaker cells
Domain: 1 {
Electrophysiology model: TTP
Conductivity (iso): 0.012571
Conductivity (ani): 0.082715