Quick Guide

Quick Guide, as a brief tutorial, introduces the GUI and commonly used functions, and 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 for cardiovascular modeling/simulation pipeline.

Introduction

Once SimVascular has launched, you will see the following main window as below. Please first read Welcome page on the righ part of the main window. Click “Welcome Tutorial” to learn the main window layout and basic usage of Data Manager, Image Navigator, Display, etc.

GUI Layout

The SimVascualr main window is composed of a title, a menubar and toolbars (on the top), a status bar (on the bottom), and tool panels (in the middle). Each tool panel is a container which can include several tools. You can click a tab to show the corresponding tool, or drag-drop a tag to another place to relocate the tool.

The window title shows the names and versions of major external packages used by SimVascular. The status bar shows useful information for users, like the cursor location on the image, messages and process of data operations, computer memory usage, etc.


Menubar

The menubar contains menus to acces all functions and tools. The tools specially for cardiovascular modeling/simulation pipeline are listed on the top of Menu “Tools”.

Change tool settings: Menu -> Windows -> Preferences...

Switch between the preset GUI layouts (Perspectives): Menu -> Windows -> Open Perspective


Toolbars

There are three toolbars shown as below. They give quick access to various functions and tools.

Status Bar

The status bar is a convenient location which provides some useful information about the data you are working on or the status/progress of some ongoing data operation, crosshair center coordiantes, memory usage, etc.

Data Manager

Data Manager is normally located on the left side of the main window. It lists and organize all the loaded data in a tree structure. After data is loaded from a file, a data node (representing the data) shows in Data Manager.

To open a file (loading data into Data Manager):

Menu: File → Open File...

Attention: If you load a file by “Open File”, the data is loaded into Data Manager but not into a SimVascular Project. Therefore, SimVascular’s project management doen’s apply to it. But you are still able to use various tools with the data.

To show/hide data (in Display):

Toggle on/off the checkbox next to the corresponding data node in Data Manager

When you right click the data node, a menu pops up. It gives you many functions to deal with data nodes. Some functions are only available to data nodes in a certain type.

The functions for all types of data include:

Global Reinit: Reset 2D/3D views of Display using the maximum Cartesian space of all the data nodes in Data Manager
Save…: Save the selected data node to a file
Reinit: Reset 2D/3D views of Display using the Cartesian space of the selected data node in Data Manager
Show only selected nodes: Show the selected data nodes in Display
Toggle visibility: show ( or hide) the selected data nodes in Display if they are hidden (or visible)
Details: show more information about the selected data node in a popup dialog, such as dimensions, spacing, etc.
Remove: remove the data node from Data Manager
Opacity: change the opacity of the selected data node
Color: click the color button to change the color of the selected data node
Rename: Rename the selected data node
Copy: copy the selected data node
Paste: duplicate the copied data node in a folder in Data Manager

As shown in the figure above, the functions only for images include:

Texture Interpolation: Smoothes the image, so that no single pixels are visible anymore.
Colormap: Change the colormap for the image

DICOM Images

SimVascular provides several ways to load dicom images.

The simplest way is:

Menu: File → Open File...
Select one of dicom image
SimVascular automatically loads all the images from the same folder

The advanced way (providing more info) is to use the tool “MITK DICOM Browser”

Toolbar: MITK DICOM Browser
Go to tab: "Import"
Click "Scan directory" and select the directory which inlucdes dicome images
Some info is listed in the tables
Select an item in one of the tables
Click "Add to local storage" to add the selected one to the local storage
Click "View" to add the selected on to Data Manager, which enable you to see the image in Display.

Display

Display is a multi-window tool to show data in 2D/3D views, normally located on the right side of the main window. There are three 2D views and one 3D view. Typically imaging data is a set of scalar values (e.g. integers ranging from 0 to 4096) defined on a structured 3D grid. Note that this data may be acquired in 2D slices and resampled in some fashion. The most common use for (diagnostic) medical imaging data is for visualization. For example, a vascular surgeon may acquire image data on a patient suspected of having vascular disease. Traditionally, most surgeons and radiologists look at sets of 2D slices of image data acquired in a 3D volume. This requires the person to create a mental image of the patient’s 3D anatomy.

The demo data we are using are magnetic resonance images of the aorta and the iliac bifurcation.

Place your mouse within the 2D View windows in Display. You should find that:

Left Mouse Button: moves the crosshairs.
Right Mouse Button: zooms the 2D view
Center Mouse Button (scrolling): navigates to a certain image slice

Place your mouse within the 3D View window in Display. 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

When you move the cursor to a window, a icon menu shows up. The menu for the first icon is shown as below. From this menu, you can show/hide crosshair, or enable/disable crosshair rotation (change image slice orientation).

The second icon is to switch between single-window layout and multi-window layout. The menu for the first icon is shown as below, providing various options to change the layout.

Window Level

The right widget in Display is for “window leveling”, which is a very common technique in viewing image data. Window leveling basically creates a non-linear color mapping function to help distinguish features in the image data. Specifically, the “window” value actually defines the center of the color range, while the level defines the width of the “band” around the center. For example, the default color map of “[1 166]” corresponds to values of window = 83 and level = 164 as seen in the following color lookup table:

Scalar value Color
1 (window – 0.5*level) Black (0)
83 (window) Gray (0.5)
165 (window + 0.5*level) White (1)

Graphically, this is what window leveling does:

By changing thw window and level values, you can change the brightness and contrast of the image.

Change window value: move the vertical slider or modify the value in the first text field
Change level value: change the length of the slider or modify the value in the second text field

To access more options for window level:

Right click at the window level widege, a menu pops up.

Image Navigator

Image Navigator is normally located on the left-bottom of the main window. The volume dataset we are using for this demo is 512 x 64 x 512 voxels. You can change the location of each slice plane by moving the sliders in Image Navigator. The “Sagittal” refers to left/right direction; “Coronal” refers to posterior/anterior direction; “Axial” refers to inferior/superior direction.

Volume Rendering

An additional technique gaining popularity is known as 3D volume rendering. The user defines an opacity transfer function (which can be non-linear) and uses ray casting (or hardware acceleration) to render the 3D volume. It should be noted that 3D volume rendering is the most computationally intensive method of visualizing imaging data and usually requires very high-end graphics cards for decent performance.

Doule click the image data node and the tool “Volume Visualization” shows up. To see the image’s volume rendering:

Toggle on the checkbox "Volumerendering"
Choose a preset or click the tab "Threshold" or "Bell" to create a custom transfer function.

HELPFUL HINT: Move the cursor inside the tool, there will be tooltip showing to tell users how to use certain functions.

Project Management

To work on a modeling/simualtion case, it is required to create a SimVascular (SV) Project first. The project can organize, manage, save all the required data.

To create a project:

Menu: File → Create SV Project...
Provide a name for the new project
Provde a diretory/folder in which the project will be created
Click the button “OK”

A new project is created in Data Manager as below. It has no actual data so far. Later, data will be added or created under those data nodes according to data types.

If you add/remove data nodes, or change data of a data node inside a SV project, you need to save those changes to the underlying files.

To save SV projects:

Method 1: Toolbar -> Save SV Projects
Method 2: Menu -> File -> Save Sv Projects

You can close a project with exiting SimVascular. Make sure you save the project before closing it. After closing a project, it’s removed from Data Manager.

To close a SV project:

Right click the data node of a SV project in Data Manager
Click "Close SV Project" in the popup menu

Undo/Redo is implemented for data changes. To restore the data to the previous state, apply Undo/Redo.

Undo: Ctrl+Z
Redo: Ctrl+Y

Add Image to Project

To use an image for a project, the image is required to be added to the project.

To add a image to a project:

Right click the data node "Images" in the project "SVProject" in Data Manager
Click "Add/Replace Image" in the popup menu
Choose an image and click "Open"
"Do you want to copy the image as vti into the project?" Choose Yes or No
If Yes, "Do you wanto scale the image (for unit conversion)?": for instance, 0.1 if from mm to cm.

Then the image is added under the data node “Images”. At the same time, the image is shown in Display. If you choose to copy the image to the project, the project is portable and you can transfer the project to another computer and continue working on it.

HELPFUL HINT: If you want to add a series of DICOM images to the project, just choose one of them, SimVascular will load all the images in the same folder.

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.

Right click the data node "Paths" in the project "SVProject" in Data Manager
Click "Create Path" in the popup menu
Path Name: aorta
Subdivision Type: choose "Spacing Based"
The minimum image spacing is automatically filled for "Spacing"

A new path “aorta” is created under the data node “Paths” in Data Manager. Double click the data node “aorta” and the tool “SV Path Planning” shows up. The new path is empty and has no points so far. To add a contro point:

Image Navigator: Axial slider: 475
Place the curson into the Axial 2D View in display
Right press and move to zoom in
Method 1: Click at the center of the vessel; Ctrl+A or click the button "Add"
Method 2(interactive): Move the cursor to the center of the vessle; Ctrl + Left Click

A control point is added for the path and should appear under the Control Point List. In Display, the point is shown as a blue or red point, depending on if the point is selected. To interactively move the point:

Move the cursor to the control point, it becomes red(selected) if not selected yet
Left press on the point and move 

Continue to move down the aorta inferiorly in the Axial 2D View in increments of 25-50 using the Axial slider in Image Navigator, similarly, add the center points to the path. When you reach the bifurcation (the aorta splits into the two iliac arteries), continue your path down the LEFT iliac artery. At the same you can see the path in the 3D View.

Delete a control point in the path

Method 1: select the one you want to remove in the Control Point List and click the button "Delete"
Method 2(interactive): Move the cursor to the point you want to remove and Ctrl + Right Click

Build your path down as far as possible (you should be able to get to around Axial slider position 10 before things get harder to see.

Save SV Projects: When the data in the project change, remember to save the project by:

Click "Save SV Projects" on the tool bar

The path will be saved to a file inside the project folder.

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 contour group.

Right click the data node "Segmentations" in the project "SVProject" in Data Manager
Click "Create Contour Group" in the popup menu
Select Path: aorta
Group Name: use the path name by default

A new group “aorta” is created under the data node “Segmentations” in Data Manager. Double click the group data node “aorta"and the tool "SV 2D Segmentation” shows up. The window layout of Display changes. The left top view shows image reslice in intensity; the left bottom view shows in gradient magnitude; the right 3D view shows image intensity on the probe plane (the red square) perpendicular to the path. The new group is empty ans has no contours so far. To add create and add a contour point:

Toggle on "Convert to Spline"; Ctrl No. (12) is the number of control points you want the along contour line    
Click the button "LevelSet"; LevelSet parameter panel appears
Use the default parameter values in the panel
Click the button "LevelSet" again

A contour is created/added for the group and should appear under the Contour List. In Display, the countour is shown in red with 12 green control points on the contour line. Two more control points are inside the contour, one for shifting and the other for scaling.

To interactively modify the contour:

Move the cursor to a control point, it becomes red(selected)
Left press on the point and move 

Continue to move along the path in increments of about 5-25 using the “Reslice" slider until approximately 285, and define and add contours to the group. You may wish to additionally smooth certain contours, then selecte the contour and click the button “Smooth”. Values between 6 and 10 for Fourier number are appropriate for this section of the aorta. If a contour is abnormal because the probe plane is at the vessel bifurcation region, just delete this contour and move down the path to get a better contour.

HELPFUL HINT: When a contour is selected, some geoetry info about this contour is shown in the status bar on the bottom of the main window. The info includes area, perimeter, and the center point coordinates.

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

Toggle on "Batch Mode"
Enter "10:30:600" in List.
Click the button "LevelSet"

A number of new contours are created (at reslice positions: 10, 40, 70, 100…) and added to the group. If some are abnormal, just delete them.

To checkout the group quality for lofting:

Toggle on "Lofting Preview"

A new data node “Lofted” for lofting face is created under this group in Data Manager

HELPFUL HINT: When the data in the project change, remember to save the project by:

Click "Save SV Projects" on the tool bar

The contour will be saved to a file inside the project folder.

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

Creating a Model (with PolyData)

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

Right click the data node "Models" in the project "SVProject" in Data Manager
Click "Create Model" in the popup menu
Model Type: PolyData
Model Name: demo

A new PolyData model “demo” is created under the data node “Models” in Data Manager. Double click the model data node “demo"and the tool "SV Modeling” shows up. The new model is empty so far. To loft and create the actual model:

Click the button "Create Model..."
Choose and use "aorta" and "right_iliac" in the dialog
Number of Sampling Points: 40 (optional for PolyData)
Click the button "OK"

All the faces of the model are listed under “Face List” tab. Double click a face name to change it and change face type in (wall,cap). For the inlet and outlets, we change the names as: inflow_aorta, outflow_aorta and outflow_right_iliac. Click a face in the table and the face will highlighted in Display. To select/hightlight a face interactively from 3D view:

Move the cursor on a face in 3D View
Press key "S"

HELPFUL HINT: When a face is selected, some geoetry info (area) about this face is shown in the status bar on the bottom of the main window.

Different colors can be assigned to those faces.

Double click the table cell in the column "C" in the table.
Selecte a color for the corresponding face.

HELPFUL HINT: When the data in the project change, remember to save the project by:

Click "Save SV Projects" on the tool bar

The model will be saved to files inside the project folder.

Creating a Model (with OpenCASCADE or Parasolid)

With the two groups of contour segmentation (aorta and right_iliac), we are also able to create a model for the aorta with two branch vessels using OpenCASCADE or Parasolid, besides PolyData.

Right click the data node "Models" in the project "SVProject" in Data Manager
Click "Create Model" in the popup menu
Model Type: OpenCASCADE (or Parasolid)
Model Name: demo2

A new OpenCASCADE model “demo2” is created under the data node “Models” in Data Manager. Double click the model data node “demo2"and the tool "SV Modeling” shows up. The new model is empty so far. To loft and create the actual model:

Click the button "Create Model..."
Choose and use "aorta" and "right_iliac" in the dialog
Number of Sampling Points: 20 (default)
Click the button "OK"

To get smoother surface for the mode, click the button “Change Facet Size..” and give a smaller size.

To blend faces:

Click the tab "Blend"
Set radius for the face pair as 0.2
Click the button "Blend Faces"

HELPFUL HINT: When the data in the project change, remember to save the project by:

Click "Save SV Projects" on the tool bar

The model will be saved to files inside the project folder.

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.

Meshing Using TetGen

With the solid model “demo” (or “demo2”) ready, we are now able to create a mesh for this model using TetGen.

Right click the data node "Meshes" in the project "SVProject" in Data Manager
Click "Create Mesh" in the popup menu
Select Model: demo (or demo2)
Mesh Type: TetGen
Mesh Name: demomesh

A new TetGen mesh “demomesh” is created under the data node “Meshes” in Data Manager. Double click the mesh data node “demomesh"and the tool "SV Meshing” shows up. The new model is empty so far. To create the actual mesh:

Click the button "Estimate" to provide estimated value for "Global Max Edge Size"
Use the default parameter values
Click the button "Run Mesher"

HELPFUL HINT: The estimated edge size is about half of the radius of the smallest cap in the model.

Now the mesh is created for the model as above.

HELPFUL HINT: When the data in the project change, remember to save the project by:

Click "Save SV Projects" on the tool bar

The mesh will be saved to files inside the project folder.

Simulation

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

With the model “demo” and the mesh “demomesh” ready, we are now able to create a job for blood flow simulation.

Right click the data node "Simulations" in the project "SVProject" in Data Manager
Click "Create Simulation Job" in the popup menu
Select Model: demo
Job Name: demojob

A new job “demojob” is created under the data node “Simulations” in Data Manager. Double click the job data node “demojob"and the tool "SV Simulation” shows up. Now we start to set parameters for the job

Basic Parameters

Basic paramters include fluid material properties, cardiac cycle period and initial conditions. Just use the defult values.

Inlet and Outlet Bcs

Click “Inlets and Outlet BC” and the parameter table appears. This model has one inlet “inflow_aorta” and two outlets “outflow_right_iliac”, “outflow_aorta”. Let’s set boundary conditions for those faces.

For the inlet: inflow_aorta, we need to prepare a file “steady.flow” first. 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
1.0 -100

To set BC for the inlet:

Right click on its line (first line on the table)
Click "Set BC" on the popup menu; a setting dialog shows
BC Type: Prescribed Velocities
Analytic Shape: parabolic
Point Number: 2 (for constant flow rate, 20 for pulsatile flow rate)
Fourier Modes: 1 (for constant flow rate, 10 for pulsatile flow rate)
Period: optional (provide if it's different from the value in Basic Parameters)
Click the button "..." to select the file "steady.flow for its flow rate
Click the button "OK"

To set BC for the outlets (outflow_right_iliac, outflow_aorta):

Double click the column "BC Type" on the table
Choose "Resistance"
Double click the column "Values" on the table
Assign 16000

HELPFUL HINT: When a cap is selected, some geoetry info (area) about this cap is shown in the status bar on the bottom of the main window.

Wall Properties

Type: Rigid

Solver Parameters

There are many parameters for flow solver, but only a few is required to set explicitly. Advanced paramters are optional.

Number of Timesteps: 100
Time Step Size: 0.0004
Number of Timesteps between Restarts: 10
Step Construction : 2 # standard two iterations, enough for constant  problems.

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

To run simualtion:

Click the button "Create Data Files for Simulation"
Number of Processes: give the number of cores you need
Click the button "Run Simulation"

After the simulation is completed, all the simulation result files restart.*.* are in the folder [proj_path]/Simulations/demojob.

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

Runnning Simulation at Computer Clusters

You can also export the required data files and upload to a computer cluster to run the simulation.

To export the files:

Make sure you have created data files for this job.
Right click on the job node "demojob" in Data Manager
Click "Export Data Files"
Select a directory

A folder “demojob-sim-files” is created, which contains the required files to run the simulation.

To run the simulation at the cluster:

Make sure SimVascular flow solver is available on the cluster.
Upload the folder "demojob-sim-files" to the cluster
Login the cluster
Go to the folder "demojob-sim-files"
Run "mpiexec -n [number of processes] [solver path]/svsolver" or you need create/submit a job file as required by the cluster to run the simulation

During the simualtion, result files are saved at the folder “demojob-sim-files/[number of processes]]-procs_case/”. You can download the files back to your computer and convert them to vtp/vtu files.

Convert Results

To convert the simulation result files to .vtp and .vtu files, which we can use to show the results in ParaView.

Result Dir:  [proj_path]/Simulations/demojob/*8-procs_\_case* or Click the button "..." to select a directory
Start: 10
Stop: 100
Increment: 10
Click the button "Convert ..."
Select a directory for exporting (in this example: [proj_path]/Simulations/demojob/)

Since it is a steady case, only the last time step is needed. A new folder “demojob-converted-results” is created and contains the output files all_results_00010.vtp,…, all_results_00100.vtp, all_results_00010.vtu, …, all_results_00100.vtu, average_results.vtp.

Visualizing Results

Launch ParaView.

Open the file "all_results_00100.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)" 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.