Quick Guide

Introduction

Quick Guide, as a very brief tutorial, teaches users how to visualize medical imaging data, create a model, generate mesh and run simulation with SimVascular for a simple case. It only covers very basic steps. After learning with this guide, you can check other guides for more explanation/details and advanced options: Imaging Guide, Modeling Guide, Meshing Guide, and Solver Guide(svPre, svSolver).

Getting Started

Launching

When you first launch SimVascular, you will see the following windows:background window and startup window.

The Startup Window will automatically disappear once SimVascular has loaded. The black Background Window will remain open, running in the background, for the entirety of your session.

WARNING: Do not close the black Background Window!

Overview

Once SimVascular has loaded, you will see the following main window:

BOX A | Menu Bar: The menu bar that is enclosed by box “A” (top left corner) includes some file options. These functions will be used to load/save files such as paths and groups that you have created in SimVascular. It also provides view control and you can show/hide tabs in BOX B and BOX D by toggling on/off in the Image Menus and Work Menus.

BOX B | Display Options: The area that is enclosed by box “B” (top right corner) includes all of the display options. The tabs that are included in this pane allow you to change the settings for displaying your medical imaging data.

BOX C | Display Windows: The area that is enclosed by box “C” (left half) houses the display windows. The top display window (the largest window) is the 3D display. This is where operations, such as rotating medical imaging data and creating geometric models in three-dimensional space, will be performed. The smaller, bottom two windows are 2D windows that will be useful for 2D operations such as image segmentation.

BOX D | Functional Toolbox: The area that is enclosed by box “D” (bottom right corner) includes the main functional components of SimVascular. The tabs that are housed within this pane will allow you to build a solid, 3D model from medical imaging data, mesh that solid model into a 3D volumetric finite element mesh, apply boundary conditions to your finite element mesh, and create the files that are needed to initialize your flow simulation. It will also help you post-process the files that you generate in your flow simulation.

HELPFUL HINT: The red arrows indicate panes within the window that can be resized. Just simply click and drag on the pane borders to resize each pane. For your convenience, you can enlarge or hide some panes.

Creating a Working Directory

It is recommended that the files that are created for each project are all saved in directories outside of the directory containing the imaging data. Create a new directory for these project files in a convenient place on your hard drive. Make sure that the project directory file name does not have any spaces in it or this may cause problems in future steps. To create a project directory:

Menu: File → Select Project Directory
Find the working directory “demo”, click the button “OK”
“Create a directory?” Click, “Yes.”
“Set default filenames using project directory name?” Select, “Yes.”

Visualizing Imaging Data

Loading Medical Imaging Data

The demo data we are using are magnetic resonance images of the aorta and the iliac bifurcation, shown below in blue.


Menu: File → Load Image (VTI)
Choose the file: sample_data/image_data/vti/sample_data-cm.vti, and click “Open.” 

Visualizing Medical Imaging Data

Once your data (VTI) has loaded, a blue box outline should now appear in the 3D window.

Place your mouse within the 3D window. You should find that the:

Left Mouse Button: rotates the 3D volume
Right Mouse Button: zooms the 3D volume
Center Mouse Button (or ‘shift’ + left mouse button): translates the 3D volume

The volume dataset we are using for this demo is 512 x 64 x 512 voxels. You can turn on any of the checkboxes labeled “L/R”, “P/A”, and “I/S”, and change the location of each plane by moving the scale bars to see the slices. The “L/R” refers to left/right direction; “P/A” refers to posterior/anterior direction; “I/S” refers to inferior/superior direction. You should see something similar to the image below in the 3D display window:

Move the cursor (i.e. arrow pointer) into the 3D display window. By holding down the up/down/left/right arrow keys, you change the brightness of the image.

Turn off all the image planes in the view window (i.e. remove checks for “L/R”, “P/A”, and “I/S” planes). Click on the “point cloud” checkbox to threshold the image data under the “Volume Properties” tab. The default minimum value for thresholding is 128 and the default maximum value for thresholding is 334.0. You should see something similar to the following image:

The point clouds can give an approximate 3-D view on the vessels. There are many ways/options to visualize imaging data, such as volume rendering, maximum intensity projection (MIP), resampling data, etc. Please refer to Imaging Guide.

Geometric Modeling

To create 3-D models, paths along the vessels of interest need to be specified first. 2D segmentations (contours) are then generated along each of the paths. Using these segmentations, a separate solid model is created for each vessel, and these are all unioned together to create the final model.

Creating a Path

To create a geometric model for a vessel, you need to first create a path, which you can regard as a centerline of the vessel.

Tab: Paths → General
Path ID: 100 (any positive integer)
Path Name: aorta (no spaces!)
Num. of Spline Pts: 300 (the total number of points to include on the path)
Click the button “Create New Path”

A new path aorta appears under the “All Paths” in the path treeview. We’ll find some center points of the vessel based on the imaging data and add them into the path. The highlighted region in the 3-D display window is the intersection of the aorta.

Tab: Paths → Manual
Toggle on: Display Options → Show Cursor, Attach Image Axis → S
I/S slider: 475
Move L/R and P/A sliders, locate the 3-D cursor at the center of the aorta.
Click “Add Point to End of Path”

HELPFUL HINT: Don’t complete hide Display Options pane, otherwise the volume visualization scale bars in the Volume Properties tab can’t be automatically updated.

The point should appear under aorta in the path treeview.

Continue to move down the aorta inferiorly (from “S” to “I”) in increments of 25-50 using the I/S slider, center the 3-D cursor inside the aorta and add the center points to your path. When you reach the bifurcation (the aorta splits into the two iliac arteries), continue your path down the LEFT iliac artery:

HELPFUL HINT: To delete a point in the path, select the one you want to remove in the path treeview, then click Additional Options → Delete currently selected point.

Build your path down as far as possible (you should be able to get to around I/S slider position 10 before things get harder to see. To visualize the current path:

Tab: Paths → Manual
Toggle on: Display Options → Show Points, Show Spline

To save paths:

Menu: File → Save Paths
Make sure you are in the correct project directory.
Enter the desired name “demo” for the file under “File name:” with the ending “.paths”
Click on the “Save” button.  

HELPFUL HINT: You can check more details on Path Planning in the Modeling Guide.

2-D Segmentation

Along the path we created, a group of contours of the aorta vessel wall can be defined based on the imaging data. First, create a group.

Tab: 2D Segmentation → General
Group Name: aorta
Click the button “Create New Group”

In the group treeview, a group with the name aorta appears.

To visualize 2-D segmentations (contours):

Tab: 2D Segmentation → Create Vessel
Click the button “Select Current Path”, double-click “100 : aorta”

In the 3D display window:
Toggle on: Display Options → Branch Controls → Show Path, Intensity Probe
Toggle on: 3-D Window → Show 3-D & 2-D Reslice

In the 2-D Intensity window:
Toggle on: Display Options → Views → Parallel projection
Toggle on: Display Options → Level Set → segmentation

In the 2-D Potential window:
Toggle on: Display Options → Level Set → segmentation

Now under the 3D Display Window, there are two more 2D Display Windows showing image intensity and potential on the probe plane (the green square on the 3D Display Window).

Tab: 2D Segmentation → Create Vessel → Level Set
Use the default parameter values in the tab
Click the text field “Center: X” and push the key “Enter”
Click the button “Add Current Segmentation to Group”

A segmentation (contour) of the aorta on the probe plane is defined and added to the group aorta, as shown in the group treeview.

Continue to move along the path in increments of about 5-10 using the “Current Position” slider until approximately 285, and define and add segmentations to the group. You may wish to additionally smooth certain contours, using the ‘Fourier Smooth Button’. Values between 6 and 10 for fourier smoothing are appropriate for this section of the aorta. If a segmentation is abnormal because the probe plane is at the vessel bifurcation region, just skip this segmentation and move down the path to get a better segmentation.

To speed up modeling, SimVascular can perform batch segmentations. To perform batch segmentation:

Enter "155-285 by 10" in the batch segmentation text box.
Select "Add to Group" and "Smooth" check boxes.
Click "Batch Segmentation."

Similarly, we create a path and a group of segmentations for the right iliac artery.

To show all the paths and the segmentations for the aorta and the right iliac artery in the 3D Display Window:

Tab: Paths → Manual
Toggle on: Display Options → Show All Paths

Tab: 2D Segmentation
Select the groups “aorta” and “right_iliac” in the group tree view
Click the button “Display Groups” and choose a color

To save groups:

Menu: File → Save Groups
Make sure you are the folder groups under the project directory.
Click on the “Save” button.  

HELPFUL HINT: You can check more details on 2D segmentation in the Modeling Guide.

Creating a Model (with Parasolid)

With the two groups of segmentation, we are now able to create a model for the aorta with two branch vessels using Parasolid.

Tab: Segmentation → 2D Segmentation
Select the groups aorta and right_iliac in the group tree view
Click the button “Model Operations → Use Surface”

Tab: Model → Parasolid → Create Model
Click on the “Create Pre-Op Solid Model” button
“Model Name”: demo
“Recreate all solids?”: Yes
“Create missing solids using defaults?”: Yes 
Click “File Input/Output → Save Model” to the file demo.xmt_txt

Now a 3D model is shown in the 3D Display Window. Here we only consider two branch vessels for this case. The other branches are ignored for this simple case.

All the faces of the model are listed under “Face Id”. You can move the cursor to a face of interest in the 3D display window and hit “p” in the keyboard, and the face will be highlighted in yellow and the corresponding face id/name is highlighted in the list under “Face Id”. If our model is displayed as faces (look for the “X” under “Show Faces”), then we can also select the faces in the list and they will be highlighted on our screen. However, if our model is displayed as a full model (look for the “X” under “Show Model”), we only have one selectable surface in the 3D window which is the entire solid. We can also change the names of the faces on our model. For the inlet and outlets, we change the names as: inflow_aorta, outflow_aorta and outflow_right_iliac.

Tab: Model → Parasolid
Select the inlet face in the list and change color to green
Enter inflow_aorta for surf name, and click “Set Value”

Now the inlet face name is changed to inflow_aorta in the list. Similarly, we change the names of the two outlet faces. As we changed the face names, we need to save the model again.

File Input/Output → Save Model
Save to the file demo.xmt_txt

HELPFUL HINT: You can check more details on ParaSolid modeling in the Modeling Guide.

Creating a Model (with PolyData)

With the two groups of segmentation, we are now able to create a model for the aorta with two branch vessels using PolyData.

Tab: Segmentation → 2D Segmentation
Select the groups aorta and right_iliac in the group tree view
Click the button “Model Operations → Use Surface”

Tab: Model → PolyData → Create Model
Use the default parameter values/options (To change lofting options, go to Segmentation → Lofting Parameters)
Click on the “Create Pre-Op Solid Model” button
“Model Name”: demo
Click “File Input/Output → Save Model” to the file demo.vtp

A geometric model is created for the blood vessels.

Click the button “Save Result”

A model file demo.vtp is created in the projector folder.

Tab: Model → PolyData → Face Manipulation
Click the button “Extract Boundaries”

All the faces of the model are listed under Face Id.

All the faces of the model are listed under “Face Id”. You can move the cursor to a face of interest in the 3D display window and hit “p” in the keyboard, and the face will be highlighted in yellow and the corresponding face id/name is highlighted in the list under “Face Id”. If our model is displayed as faces (look for the “X” under “Show Faces”), then we can also select the faces in the list and they will be highlighted on our screen. However, if our model is displayed as a full model (look for the “X” under “Show Model”), we only have one selectable surface in the 3D window which is the entire solid. We can also change the names of the faces on our model. For the inlet and outlets, we change the names as: inflow_aorta, outflow_aorta and outflow_right_iliac.

Tab: Model → PolyData
Select the inlet face in the list and change color to green
Enter inflow_aorta for surf name, and click “Set Value”

Now the inlet face name is changed to inflow_aorta in the list. Similarly, we change the names of the two outlet faces and the wall. As we changed the face names, we need to save the model again.

File Input/Output → Save Model
Save to the file demo.vtp

Meshing

Discretization, also known as grid or mesh generation, is defined as the process of breaking up a physical domain into smaller sub-domains (usually called elements). Discretization is necessary in order to facilitate the numerical solution of partial differential equations. SimVascular provide two ways for meshing. If a model is created by Parasolid, use MeshSim; if a model is created with PolyData, use TetGen.

Meshing Using MeshSim

Tab: MeshSim → Mesh
Type: Parasolid
File: demo.xmt_txt
Global Max Edge Size: 0.3  (absolute)
Click “Run Mesher”
“Creating mesh can take a long time. Continue anyway?”: "Yes"
“Use currently selected meshing options?...”: "Yes"

Now the mesh is created for the model as below.

To output mesh data files (later used for simulation):

Click “Write Files”

All mesh data files are in the folder mesh-complete under the project folder demo.

HELPFUL HINT: You can check more details on MeshSim meshing in the Meshing Guide.

Meshing Using TetGen

Tab: TetGen → Mesh Options
File: <project folder>/demo.vtp
Set maximum edge size for equilateral tetrahedron: 0.3
Click “Run Mesher (Internal)”

Now the mesh is created for the model as below.

To output mesh data files (later used for simulation):

Click “Write Files”

All mesh data files are in the folder mesh-complete under the project folder demo.

HELPFUL HINT: You can check more details on TetGen meshing in the Meshing Guide.

Simulation

Now we’ll use SimVascular/Solver for three-dimensional blood flow numerical simulations (solving Navier-Stokes equations in an arbitrary domain).

Inflow Boundary Conditions

For the boundary condition of the inlet face: inflow_aorta, we need to create a file steady.flow in the folder flow-files under the project folder. It contains the data for the flow rate with respect to time. Here we assume the flow rate is constant.

steady.flow

0.0 -100
0.2 -100

The first column is time (s), the second is flow rate (cm^3/s).

Use the inflow file to create boundary condition file for the inlet.

Tab: Simulations → Inflow BC
Analytic Shape of Profile: parabolic
Mesh Face File (vtk): <project folder>/mesh-complete/mesh-surfaces/inflow_aorta.vtp
Flow Rate File: <project folder>/flow-files/steady.flow
Period: 0.2 
Viscosity: 0.04 g/(cm*s)
Density: 1.06 g/cm^3
Num of period: 1 (always 1, later use solver.inp to loop)
Num pts in period: 2 (for constant flow rate, 20 for pulsatile flow rate)
Num fourier modes: 1 (for constant flow rate, 10 for pulsatile flow rate)
Click “CREATE 3-D FLOW SOLVER BC FILE” 

The inflow boundary condition file bct.dat is created in the project folder.

Solver Input Files

We continue to create other required input files for simulation.

Tab: Simulations  → Create 3-D Solver Files
Click “Create File” to output numstart.dat in the project folder.

Manually write presolver script file demo.cvpre in the text area:

mesh_and_adjncy_vtu mesh-complete/mesh-complete.mesh.vtu
noslip_vtp mesh-complete/walls_combined.vtp
prescribed_velocities_vtp mesh-complete/mesh-surfaces/inflow_aorta.vtp
zero_pressure_vtp mesh-complete/mesh-surfaces/outflow_aorta.vtp
zero_pressure_vtp mesh-complete/mesh-surfaces/outflow_right_iliac.vtp
set_surface_id_vtp mesh-complete/mesh-complete.exterior.vtp 1
set_surface_id_vtp mesh-complete/mesh-surfaces/outflow_aorta.vtp 2
set_surface_id_vtp mesh-complete/mesh-surfaces/outflow_right_iliac.vtp 3
write_geombc geombc.dat.1
write_restart restart.0.1


Click “Save PreSolver scriptfile”. 
Click “Run PreSolver” 

Two more solver files geombc.dat.1 and restart.0.1 are created in the project folder.

Open a text editor and manually write the solver input file solver.inp in the project folder. Most parameters are already assigned default values for cardiovascular simulation. For a simple case, users just need to add about one dozen of lines for the parameters that must be set up in solver.inp.

solver.inp

Number of Timesteps: 500   
Time Step Size: 0.0004  # should be small enough 
Number of Timesteps between Restarts: 50   #output every 50 timesteps

Viscosity: 0.04 
Density: 1.06

Number of Coupled Surfaces: 2 # Both outlets have coupling between flow rate and pressure 
Number of Resistance Surfaces: 2   # Both outlets have resistance
List of Resistance Surfaces: 2 3  #  ID list of the two outlets, defined in dem .cvpre
Resistance Values : 16000 16000  # Resistance values for the two outlets

Time Integration Rho Infinity: 0.0 # maximal numerical dissipation 
Number of Force Surfaces: 1 
Surface ID's for Force Calculation: 1  # ID is defined in .cvpre

Step Construction : 0 1 0 1 # standard two iterations, enough for constant  problems.
#For pulsatile problems, at least three iterations. For deformable wall problems,  at least 4 iterations.

HELPFUL HINT: Step Construction together with Time Step Size and the quality of the spatial discretization given by the finite element mesh, will completely determine the performance of the linear solver of equations. The better chosen these parameters are, the faster and more accurately our simulation will run.

Running Simulation

Create a folder "simulation" in the project folder
Copy the five files bct.dat, numstart.dat, geombc.dat.1, restart.0.1, solver.inp to the folder "simulation"

Tab: Simulations → Run Solver → localhost
Click “Select Run Dir:” and choose the folder simulation
Toggle off “Append Date and Time to Run Dir”
Click “Select Log Dir:” and choose a log folder
Click “whoami” and your user name is shown
Choose the number of processors. Use 1 here.
Click “Run Simulation” 

Now SimVascular/Solver is running. To check the progress of simulation:

Click the first “Start Tail” button
Go to the tab “Console”

In the console, the first column is the time step number, the second is the time used in seconds, and the third column is the nonlinear residual which gives you an idea of how accurate the solution is.

After the simulation is completed, all the simulation results files restart..1 are in the folder *simulation.

HELPFUL HINT: If you choose more than one processors, for example, 4 processors are used. SimVascular will create a new folder 4-procs_case in the folder simulation. All the simulation result files restart.*.* are in the folder 4-procs_case.

Convert the simulation files to .vtu files, which we can use to show the results in ParaView.

Tab: Simulations → Create VTU Files
Select the folder simulation for the “Input Files/Dir:”
Enter a file name for the “Output Files/Dir:”: steady.vtu
Start: 500
Stop: 500
Click “Convert Files Only”

Since it is a steady case, only the last time step is needed. The output file steady.vtu is created in the folder simulation.

HELPFUL HINT: You can check more details on using SimVascualr/Solver for simulation in the svSolver Guide.

Visualizing Results

Launch ParaView.

Open the file *steady.vtu* with ParaView.
Click the button “Apply”

The pressure result is displayed in the display window. In order to visualize the velocities in the lumen, we need to use a volume render visualization technique.

To do this, we must calculate the scalar quantity representing the magnitude of the velocity.

Click the calculator tool button
Result Array Name: vel mag (cm/s)
Enter "mag(velocity_00500)" just above the calculator pane
Click the button “Apply”
Representation: Volume

You should get a similar volume rendering result as the figure above. Click the button “Edit” to get different visual effects.