CardiacSimu : A Feasible Tool for Electrophysiological Study

Version 0.0.3.1

CardiacSimu in two minutes

Installation
Since the CardiacSimu is maintained by GNU make, it is really simple to run cardiacsimu in a GNU Linux or Unix like system. Try $make all in the top of our source location. And all executable file of CardiacSimu is prepared in ./bin. But be caution, following libraries or tools should be installed before: gcc and make (in debian/ubuntu they are in build-essential package). gtk+-2.0. Libraries for OpenGL: mesa-common-dev, libgl1-mesa-dev, libglu1-mesa-dev, freeglut3-dev and glew. gnuplot. doxygen and graphviz (optional, for html documentation generation). HTML help workshop (optional, for chm documentation generation). texlive (optional, for pdf documentation generation). 7-Zip or p7zip (optional, for auto wraping meta data during simulation). If CardiacSimu is built successfully in your computer, your bin directory should contains following files: executable binaries (hrteditor, slicer, solver, stl2geo, viewer), scripts (calcEcg.sh, dpl2isop.sh, dspisoc.sh, dspprop.sh, plotAP, plotEcg) and a configure file (project.config). If you want to use CardiacSimu in windows, you should use code::blocks + mingw to build slicer, solver and viewer. To build hrteditor, you should firstly download gtk+-2.x.x.x-bundle from the website and unpack it to C:\Program Files\gtk+-bundle. Then use code::blocks to build it. The code::blocks's project files are all in wincb folder. You could load cardiacsimu-win.workspace file into code::blocks to open them all. If CardiacSimu is built successfully, the executable binaries (hrteditor, slicer, solver, viewer) are in bin fold. The scripts and configure file should be manually copied into bin fold. And in windows, gnuplot script could not be used. Fortunately, there are dozens of tools could be used to explore data in csv file. You could use msys to invoke corresponding tool (solver etc.) to do simulation.
Step 0: Getting the anatomical model
To run simulation, you should have a anatomical model represented as stl file in ./bin, and right now you can find one here.
Step 1: Making simulating model from anatomical model
use $slicer stlfile to get simulating model (in hrt file shared the same name with stl file), before the partition, you can define the scale on i,j,k coordination axis in element segment (element::scale) in configure file. After the partition, you should copy the radius of sphere element into element segment (element::radius). configure file is in your ./bin fold named project.config, if not, just copy it from ./config to ./bin. See the figure in the left, the grey one is the original anatomical model and red one, composed by many little sphere elements, is the partition result.
Step 2: Defining special conducting system according some clinic literature or your animal experiment discovering
use $hrteditor hrtfile to define special conduction system in simulating model and use $viewer -hrt hrtfile and $viewer -stl stlfile -hrt hrtfile to investigate results. You can investigate the location of special conducting system by using viewer with -hrt argument. Right figure indicates the definition used in my research, according to some literature (Harrild 2000), we defined SN (sinus node, little grey part connect BB and CT), BB (bachman bundle, blue fiber), FOL (fossa ovalis limbus, green fiber in circle), FO (fossa ovalis, red parts in FOL), Pects (pectinate muscle, purple), CT(crista terminalis, yellow fiber connected all pects), IB (intercaval bundle, yellow fiber connect FOL and CT) and Isthmus (right atria floor isthmus, red parts at the bottom of right atrium).
Step 3: Defining simulation profile in configure file if you need (e.g. simulate step, conductivity velocity, conductance, etc)
You can find these configurable items in simulation segment in configure file :).
Step 4: Propagation simulating
use $solver -propagation-simu to simulate propagation. When this step is fulfilled, you can find several dpl file and xct file in ./bin directory. Be caution, you should leave enough disk free space for the propagation simulation. To inspect activation propagation in a transparent 3D scene use $bash dspprop.sh. The figure in left give the propagation snapshot in 10ms step. To inspect isochronal map in a transparent 3D scene, use $bash dspisoc.sh. The figure in right give the isochronic maps in a reentry condition.
Step 5: Calculate Ecg (optional)
To calculate ecg, you should first locate simulating model to a proper position and orientation in a torso model, which represents the torso shell with vertexes and meshes. The position (xyz coordination) and orientation (Eulerian angles) of simulating model can be configured in anatomical segment (anatomical::atriumintorso). To calculate ecg, you should also define the leads position, which can also configured in anatomical segment (anatomical::limbtriindex and anatomical::precordialtriindex). anatomical::limbtriindex defines the xyz coordination of limb leads (left arm in la, right arm in ra and left leg in ll). anatomical::precordialtriindex defines the triangle mesh index of torso model for each precordial lead to settle. To view the location result you need used $viewer -stl stlfile -torso. Left figure gives the location configuration in my research. Silver spheres are the vertex of torso model, red spheres are the precordial leads and yellow ones are the limb leads. Till now, you can use $bash calcEcg.sh to calculate ECG waveform on limb leads and precordial leads. The ECG waveform is stored in csv file, you can use any software (Excel, Matlab etc) to investigate. Or use $gnuplot plotEcg to export ECG waveform in ecg.png.
How to remove CardiacSimu from your system?
CardiacSimu will only existed in the directory where you initial keep the download archive, and whole software will be remove if you delete this directory.

Operating steps recorded

The recorded shell operating in my computer is provided, as a supplementation for a quick heads up. These script is made by script and one can replay it by scriptreplay XX.t.txt XX.v.txt. XX.t.txt and XX.v.txt is a pair of scripts provided in each archive.

• Setup whole staffs from downloaded archives in develope page (link).
• Generate action potential waveform (link).
• Coming back soon...

For development

How to use configure file?
In CardiacSimu, simulation tasks as well as investigation tasks are configurable by using configure file named "project.config". You can find a template in /config fold and it will be copied to /bin fold after CardiacSimu is built successfully. A detail investigation to the configure file, you can find it is presented as following structure: simulation = ( ap = ( model = nygren_atrial_model_1998 ) ...... conductivity = ( velocity = ( units = mm/ms bulk = 6.125 ...... ) ) ) To retrieve the value of a certain node in CardiacSimu could be like this: string strPathCBulk[] = {"simulation", "conductivity", "velocity", "bulk"}; configContainer::tryGetEntry(strPathCBulk, 4, Config::enDouble, &cVBulk); You can add additional segments in configure file and use it to control simulation. You can also share the configure file as well as simulation materials (e.g. *.hrt) with friends.
How to get the updated document for develop?
The answer is not here :), but no panic please. In the project layout of CardiacSimu (not included in the distributed source package), there is a fold named doc composed of 4 subfolds, one for a particular tool in CardiacSimu. The document for develop of CardiaSimu is automatically maintained by Doxygen. And to recreated it is a piece of cake. Just get into these subfolds, e.g. solver and run $doxygen. A new fold named html will be created, browse into it and find the index.html. It includes all help information. Before you generate the help document, please configure binary location of Graphviz in doxyfile. If you are under Window, you can use HTML Help Workshop to convert html index file into chm file. Before that, you should configure binary location of hhc.exe in doxyfile. But be caution, the HTML Help Workshop has a memory leakage problem, which might crash on working with huge number of html files.