CIBC:Documentation:SCIRun:Tutorial:BioFEM
Contents
Introduction
BioFEM is a SCIRun PowerApp that computes the electric field in a volume produced by a set of dipoles. BioFEM computes a solution to the bioelectric field forward problem. BioFEM also computes voltage values at electrode positions, which can be compared with values recorded via ECG or EKG.
BioFEM requires these inputs:
- A discretized volume with associated volume element conductivities.
- A dipole.
- The positions of a set of measurement electrodes.
Appendix A gives instructions for preparing these data. This tutorial, however, uses BioFEM to process and visualize the Utah Torso data set. No data set preparations are needed to run this tutorial. The Utah Torso data set is part of the SCIRun sample data set collection, and can be downloaded from the SCI Software site.
Getting Started
This section demonstrates how to start BioFEM. Subsequent sections demonstrate how to load, process, and visualize data.
Preparations
Before starting BioFEM, the environment variables SCIRUN_DATA and SCIRUN_DATASET must be set.
SCIRUN_DATA points to the sample data sets directory. This tutorial assumes the SCIRun sample data directory is /usr/sci/data/SCIRunData/1.24.2. So, SCIRUN_DATA is set to (for a csh-like shell):
setenv SCIRUN_DATA /usr/sci/data/SCIRun/SCIRunData/1.24.2
SCIRUN_DATASET points to a specific data set directory within the data directory.
The Utah Torso data set exists in high resolution and low resolution versions.
To use the high resolution data set, SCIRUN_DATASET must be set to "utahtorso":
setenv SCIRUN_DATASET utahtorso
To use the low resolution dataset, SCIRUN_DATASET must be set to "utahtorso-lowres":
setenv SCIRUN_DATASET utahtorso-lowres
This tutorial uses the low resolution data set.
Launching BioFEM
Change the working directory (using the cd command) to the directory containing the BioFEM executable. This directory will be /usr/local/SCIRun/bin/ if SCIRun has been installed via RPM. Then type ./BioFEM to start BioFEM:
cd /usr/local/SCIRun/bin
./BioFEM
BioFEM takes a few moments to start up, then displays the window shown in Figure 1. The BioFEM command accepts one optional argument, which is the name of a session file:
./BioFEM mysession.ses
where mysession.ses has been previously created by BioFEM. See below for information on sessions.
BioFEM Application Window
User Interface Organization
The BioFEM window contains two panes: the Rendering Pane and the Visualization Pane. The Rendering Pane is on the left side of the window. All data interaction and visualization is performed in the Rendering Pane. The Visualization Pane is on the right side of the window. The Visualization Pane guides the user through the application, and controls visualization parameters for the Rendering window. The panes may be detached from one another by clicking on the pane detachment/attachment controls—these are the vertical dashed lines separating the panes. When separated, the panes appear as displayed in Figure 2. Detaching the Rendering window allows it to be viewed at maximum resolution. Panes are re-attached by clicking on the pane detachment/attachment controls.
The Rendering window contains two top-level menus: File and Help. The File menu, displayed in Figure 3 contains the following items:
Load Session...
Loads a previously saved session.
Save Session...
Saves a session, which can be resumed later.
Save Session As...
Saves a session under a new name.
Save Image...
Saves the content of the Rendering pane as an image.
Restore Panes
Restores any closed or hidden Panes
Quit
Quits BioFEM.
The user is not required to complete all processing steps before exiting BioFEM. A BioFEM session can be stopped and resumed using File menu items Save Session... (or Save Session As...) and Load Session.., respectively. After loading a saved session with Load Session..., resume processing and visualization by clicking Execute.
The Help menu, shown in Figure 4, contains these items:
Show Tooltips
A checkbox that toggles tooltips on and off.
Help Contents
Provides help on the BioFEM application.
About BioFEM
Provides information about BioFEM.
A Progress Indicator and an Execute button are found at the bottom of the Visualization Pane. The Execute button starts the current processing step. The Execute button is pressed after parameters for the current processing step have been set. The Progress Indicator and the text above show information about the current state of processing, and suggest the next processing step. It can also indicate when modules are dynamically compiling or when they are in an execution state.
Initial Processing and Visualization
After starting BioFEM, the Visualization pane displays the contents of the Data Selection tab. Verify that the Utah Torso Lowres radio button is selected.
Click Execute to begin initial processing. During this step, a solution to the forward problem is computed. This may take a few minutes. As the powerapp progresses, the residual plot in the Data Seletion tab will converge. The Progress Indicator is "busy" during this time. The Progress Indicator shows "COMPLETE" when processing is finished.
Perform these steps to view results in the Rendering window:
- Click on the tab labeled "Viewer Options".
- Click on the Views pop-up menu, select menu item "Look down -Y axis", then select sub-menu item "Up vector +Z".
The Rendering window should look like the Rendering window shown in Figure 5. The Rendering window displays the outer boundary of the torso volume, the set of measurement electrodes, the zero-voltage isosurface, and streamlines that follow voltage gradients. The electrodes, isosurface, and streamlines are color coded to show negative voltages blue and positive voltages red.
Interaction with the Rendering window is performed with the mouse. The Rendering window's scene can be translated, zoomed, rotated, etc. Table 1 shows all mouse actions. See also [6.3 of User's Guide (Mouse Control in the Viewer Window)] for more information.
Table 1: Rendering Window's Mouse Controls
| Modifier Key | Mouse Button | Renderer Window Action | |
|---|---|---|---|
| Scene Controls |
none | Left | Translate scene |
| Middle | Rotate scene | ||
| Right | Zoom scene | ||
| Control | Left | Translate scene in Z-direction | |
| Middle | Rotate the camera view about the eye point | ||
| Right | Unicam movement | ||
| Rake Widget Controls |
Shift | Left | Position and orient rake widget |
| Middle | Toggle widget's modes | ||
| Right | Display widget help window |
Visualization
Viewer Options Tab
Figure 6 displays the Visualization Pane's Viewer Options tab. The Viewer Options tab provides controls for changing the properties of the Rendering Window. Hovering the mouse pointer over a control (e.g., Views pop-up menu button) displays a tooltip describing a control.
Vis Options Tab
Figure 7 displays the Visualization Pane's Vis Options tab. Controls in the Vis Options tab allow selection of visualization type, visualization parameters, and colormap. Visualizations can be viewed individually or together. For example, Figure 5 displays concurrent visualization of streamlines, zero-voltage iso-surface, and electrodes.
Visualization types and use of colormaps are demonstrated in the following sections.
IsoSurface Visualization
An iso-surface is a surface of constant value. Figure 8 displays an iso-potential surface of value 0. Produce the visualization in Figure 8 by selecting the checkbox labeled "Show Isopotential Surface" (from the Vis Options tab), and moving the Electric Potential value slider to 0.
The checkbox labeled "Smooth Faces" turns surface smoothing on and off. Smoothing improves iso-surface appearance, but hides iso-surface mesh details.
The checkbox labeled "Continuous Updates" forces the isosurface to change continuously as the slider is moved. When unchecked, the isosurface will only update upon release of the slider.
Streamlines Visualization
Streamlines are traces of paths taken by particles along voltage gradients. The rake widget is used to establish (or seed) initial particle positions within the electric field. Particles follow paths that start on one end of the dipole, pass through the rake, and end on the other side of the dipole. Figure 9 shows streamlines visualization.
Streamlines visualization is controlled with the rake widget and settings in the Vis Options tab.
The rake widget's position and orientation determine streamline paths. The mouse is used to translate, rotate, and resize the rake widget. In each case, the Shift key and left mouse button are pressed while dragging a component of the rake. Drag the rake's gray bar to translate the rake, drag a rake's blue spheres to rotate the rake, and drag the rake's green ends to resize the rake. Streamlines are redrawn after the rake is moved.
The slide bar labeled Number of Field Lines in the Vis Options tab selects the number of seed points along the rake widget. Seed points are evenly spaced along the rake.
Streamlines are computed using a fast or an adaptive algorithm. Select an algorithm using the radio buttons labeled Fast Tracking or Adaptive Tracking. The fast method walks a mesh directly. The fast method's accuracy is determined by a model's accuracy. The adaptive (slower) method interpolates between cells in a model. The adaptive method walks over discontinuities, producing a smoother streamline appearance.
Electrodes Visualization
Visualize electrodes by checking the "Show Electrodes" checkbox in the Vis Options tab. Electrodes are displayed as spheres. Voltage values are computed at each electrode position and are color coded. Figure 10 shows electrodes visualization.
Colormap Selection
Voltage values are color coded using a colormap. Six colormaps are available (Figure 7). A colormap is selected from the Visualization pane's Vis Option tab. Figure 11 displays the utahtorso-lowres model colored with the Blue-to-Red colormap selected, rather than the default Inverse Rainbow coloring.
Appendix A: Data Formats and Preparation
Users may want to use BioFEM to analyze their own data sets. Before doing so, the user must convert their data to the form used by BioFEM. This section discusses the preparation and conversion of data stored in text-based files to the form used by BioFEM.
BioFEM requires these binary inputs:
- A discretized volume with associated volume element conductivities.
- A dipole source.
- The positions of a set of measurement electrodes.
Binary inputs are in SCIRun's persistant file object format. To create these binary inputs, input data are first prepared as text files, then converted to SCIRun's persistant file object format using the instructions given below. The converted files can then be used as inputs to BioFEM.
Conversion of text inputs to SCIRun's persistant file object format is performed by command line converter programs and SCIRun networks. The following sections discuss the preparation of text file inputs and their conversion to SCIRun's persistant file object format. Reference will be made to [Chapter 7 of the SCIRun User's Guide], which is a complete reference to text file formats and command line converter programs.
Preparing Volume Data
Volume data are stored in four text files: one file contains mesh node locations, one file contains mesh connectivity data, one file contains conductivity data, and one file contains conductivity index data.
Prepare Mesh Data
Prepare a node location ("pts") file and a node connectivity ("quad", "tet", or "hex") file. Sections 7.4.1 and 7.4.2 of the SCIRun User's Guide describe these file formats. The node location and node connectivity files specify the discretization of a volume into elements.
Create a SCIRun field object using the appropriate converter program (converter programs are located in directory SCIRun/bin/StandAlone/convert). For example, use TextToTetVolField to create a field from a "pts" file and a "tet" file.
The command:
TextToTetVolField torso-mesh.pts torso-mesh.tets torso-mesh.tv.fld
creates the SCIRun field file torso-mesh.tv.fld. File torso-mesh.tv.fld contains only mesh data. Conductivity data are created in steps that follow. File torso-mesh.tv.fld is used in a SCIRun network discussed later. A.1.2 Prepare Conductivity Data
Construct a tensor data file. The tensor data file's first line contains two values: the number of tensors followed by the number of values per tensor, which should always be the value 9. Each remaining line contains data for one tensor. Tensor data on each line are given in row-wise order.
Here are data for 6 tensors:
6 9
0.000 0.000 0.000 0.000 0.000 0.000 0.000 0.000 0.000
0.045 0.000 0.000 0.000 0.045 0.000 0.000 0.000 0.045
0.300 0.000 0.000 0.000 0.300 0.000 0.000 0.000 0.300
0.200 0.000 0.000 0.000 0.200 0.000 0.000 0.000 0.200
0.096 0.000 0.000 0.000 0.096 0.000 0.000 0.000 0.096
0.300 0.000 0.000 0.000 0.300 0.000 0.000 0.000 0.300
0.680 0.000 0.000 0.000 0.680 0.000 0.000 0.000 0.680
0.045 0.000 0.000 0.000 0.045 0.000 0.000 0.000 0.045
0.680 0.000 0.000 0.000 0.680 0.000 0.000 0.000 0.680
0.0129 0.000 0.000 0.000 0.0129 0.000 0.000 0.000 0.0129
Each tensor is implicitly numbered (indexed) starting with 0.
Prepare a tensor index file. A tensor index file assigns tensors in a tensor data file to volume elements defined in a node connectivity file. The first line of the tensor index file contains the number of tensor index values, which must equal the number of volume elements. Each remaining line contains the index of a tensor in the tensor data file. The first index value assigns a tensor to the first volume element, the second index value assigns a tensor to the second volume element, and so on.
Here is the first part of a tensor index file:
51419
3.000000
4.000000
3.000000
3.000000
3.000000
3.000000
4.000000
4.000000
3.000000
3.000000
.
.
.
Above, volume elements 0, 2–5, 8, and 9 are assigned the fourth tensor in the tensor data file. Volume elements 1, 6, and 7 are assigned the fifth tensor.
Create SCIRun data objects containing conductivity data and indicies using converter programs TextToDenseMatrix and TextToColumnMatrix.
Here are the commands:
TextToDenseMatrix torso-conductivity-table.txt torso-conductivity-table.dmat
TextToColumnMatrix torso-conductivity-indices.txt torso-conductivity-indicies.cmat
These commands create files torso-conductivity-table.dmat and torso-conductivity-indicies.cmat respectively. Files torso-conductivity-table.dmat and torso-conductivity-indicies.cmat are used in a SCIRun network below.
Generating the Final Field
Execute the SCIRun network displayed in Figure A1. This network combines files torso-mesh.tv.fld, torso-conductivity-table.dmat, and torso-conductivity-indicies.cmat, into a SCIRun volume field object that can be used in BioFEM. Network that creates a complete SCIRun volume field
Figure A1: Network that creates a complete SCIRun volume field
Preparing a Dipole Field
Prepare a "pts" file specifying the location of a dipole source. The file will contain one location.
For example:
1
59.699700 -40.050700 331.581000
Create a partial (position information only) SCIRun dipole field using TextToPointCloudField.
For example:
TextToPointCloudField dipole.pts dipole-pts.fld
File dipole-pts.fld contains position information only. File dipole-pts.fld will be used in a SCIRun network described later.
Prepare a file specifying the dipole's orientation and magnitude. The file will contain the components of a vector representing the dipole's orientation and magnitude.
For example:
1 3
-387.386000 -380.386000 666.388000
Create a SCIRun matrix file containing the dipole's orientation and magnitude using converter program TextToDenseMatrix:
TextToDenseMatrix dipole-mat.txt dipole.mat
Create a complete SCIRun dipole field from files dipole-pts.fld and dipole.mat using the network displayed in Figure A2.
Prepare Measurement Electrodes
Prepare a "pts" file. Each "pts" file line specifies the coordinates of one electrode.
Create a SCIRun point cloud field using converter TextToPointClouldField.
The command:
TextToPointCloudField electrodes.pts electrodes.pc.fld
creates the SCIRun field electrodes.pc.fld from the file electrodes.pts.
