tMCimg uses a Monte-Carlo algorithm to model the transport of photons through 3D highly volumes with spatially varying optical properties and arbitrary boundary conditions. Both highly-scattering tissues (e.g. white matter) and weakly scattering tissues (e.g. cerebral spinal fluid) are supported. Using the clinical structural information provided by MRI, X-ray CT, or ultrasound, accurate solutions to the photon migration forward problem are found in times ranging from minutes to hours, depending on the optical properties and the computing resources available.
This section describes the purpose of the tMCimg application, and the basic algorithm/method implemented in the software.
Light transport in highly-scattering medium, such as human tissue, is a complex process. The photons go through a large number of scattering and absorption events when traveling through the volume. Monte-Carlo is a statistical approach which models the light transport process in such scenario.
With this software package, we provide an efficient implementation of the Monte-Carlo method for modeling the light transport process in arbitrarily-shaped 3D target (represented by voxelized space), for both high or low-scattering medium. This program is not only able ot compute the static distributions of photons in complex media, but also capable of modeling the temporal propagation of light in such media, which is critically important for data analysis in time-domain optical imaging systems.
The details of our implementation and validation of this code can be found in the following paper [Boas2002, see Reference Section]. If you use this code in your research, the authors of the paper are appreciated if you can add the citation in your related publications.
The source code of tMCimg is currently maintained at our ORBIT gforge website under the project name "Brain Dynamo". The URL of the project
https://orbit.nmr.mgh.harvard.edu/projects/braindynamo/
You can download the released versions of this software can be found at
https://orbit.nmr.mgh.harvard.edu/frs/?group_id=29
The latest development version are accessible via CVS (concurrent version control) system at
https://orbit.nmr.mgh.harvard.edu/scm/?group_id=29
sudo apt-get install cvsif you are using Redhat-based GNU/Linux systems (such as Fedora, CentOS etc), you can do this by
sudo yum install cvsIf your operation system is Windows, we recommend you to install TortoiseCVS.
This project's CVS repository can be checked out through anonymous (pserver) CVS with the following instruction set. The module you wish to check out must be specified as the modulename. When prompted for a password for anonymous, simply press the Enter key.
cvs -d :pserver:anonymous@orbit.nmr.mgh.harvard.edu:/cvsroot/braindynamo login cvs -d :pserver:anonymous@orbit.nmr.mgh.harvard.edu:/cvsroot/braindynamo checkout montecarlo
If you are using Windows, please check out TortoiseCVS website for the tutorial how to download code using the GUI (basically, right click on the file explorer, and select menu CVS\CVS checkout...).
Only project developers can access the CVS tree via this method. SSH must be installed on your client machine. Substitute modulename and developername with the proper values. Enter your site password when prompted.
export CVS_RSH=ssh cvs -d :ext:developername@orbit.nmr.mgh.harvard.edu:/cvsroot/braindynamo checkout montecarlo
This section details the instructions to install the software on various commonly used operating systems. Because this program only uses the standard ANSI C implementations, the compilation of the code is relatively straightforward on various operating systems. It normally requires a minimum installation of a standard C/C++ compiler and the related libraries.
In order to compile tMCimg on windows you need to have a C compiler installed; two of the commonly uesd ones:
The following instructions have been tested for Borland C++ Compiler v.5.5.1 on Windows XP:
1. In a DOS shell, check the values of the environment variables CC_ROOT_PATH, CC_INCLUDE_PATH, and CC_LIB_PATH by typing
echo %CC_ROOT_PATH% echo %CC_INCLUDE_PATH% echo %CC_LIB_PATH%
If the paths in these variable do not match the paths of your compiler then open the install_win.bat file in a text editor and set them to reflect the installation paths of your Borland C++ compiler.
2. Then run install_win.bat by typing
call install_win.bat in
at the DOS prompt. This should create the makefiles specific to the Windows and Borland C++ Compiler environment.
3. Now you're ready to compile: from the root montecarlo directory type make, make opt (for best performance) or make debug (to be able to the load and run in a debugger)
To compile the code from source, you need to have gcc installed in your system. This can be done by sudo apt-get install build-essential in Debian based systems (such as Ubuntu), or sudo yum install gcc in Fedora/Redhat based distributions.
To compile tMCimg first create the makefiles for the linux environment by running the install_linux.sh shell script from the root montecarlo directory. Then type make, make opt (for best performance) or make debug (to be able to the load and run in a debugger)
After downloading the montecarlo module you should have a directory structure like this:
montecarlo | | bin/ CVS/ example/ makefile obj/ src/
Go to the root directory under ./montecarlo and type make on the command line. This should create the tMCimg executable under ./bin.
cd <path name to root>/montecarlo make
To run tMCimg you have to have two files: a config file with a .inp extension and a segmentation file. tMCimg takes one argument, the .inp file which has a reference to the segmentation file. See 4 for explanation of how to create a config file
Example:
We have the config file babyXX2.inp and a segmentation file baby_XXwks.bin. The reference to baby_XXwks.bin is in babyXX2.inp. To run you can do the following
cd ./montecarlo ./bin/tMCimg babyXX2
line 1: number of photons line 2: seed for generating random path for each photon line 3: 3D coordinates of the source in mm line 4: vector showing initial direction of photons as they enter the medium from the source. line 5: temporal gates: start, stop and step size (in s). If the step size is bigger than start minus stop time, then tMCimg will record only one time period line 6: pathname of tissue segmentation file line 7: the first two numbers specify the voxel size (in mm) and volume dimension along x axis, respectively; the last 2 numbers: start/end indices along the x axis, the photon propagation and fluence recording will be limited to that region line 8: same for y axis line 9: same for z axis line 10: number of tissue types line 11: properties of tissue 1: scattering (mus); anisotropy (g); absorption (mua); refraction (n) . . . . . . . line 11+m: same for tissue m line 11+m+1: number of detectors and radius of detector (in mm) line 11+m+2: 3D coordinates of detector 1 (in mm) . . . . . . . line 11+m+2+n: 3D coordinates of detector n (in mm )
10000000 -- number of photons -4896744 -- seed for generating random path for each photon 242 110 107 -- source 3D coordinates in mm -1 0 0 -- vector showing initial direction of photons as they enter the medium from the source. 0 5e-9 6e-9 -- temporal gates: start, stop and step size (in s) baby_XXwks.bin -- tissue segmentation file 1 308 1 308 -- along x axis: voxel size in mm, x dimension last 2 numbers: start/end indices of the region-of-interest in x dimension 1 308 1 308 -- same for y axis 1 308 1 308 -- same for z axis 4 -- number of tissue types 0.75 0.01 0.009 1 -- properties of tissue 1: scattering (mus), anisotropy (g), absorption (mua), refraction (n) 0.5 0.01 0.002 1 -- same for tissue 2 0.5 0.01 0.005 1 -- same for tissue 3 0.5 0.01 0.005 1 -- same for tissue 4 11 2 -- number of detectors, radius of detector 245 110 116 -- detector 1 3D coordinates in mm 247 110 126 -- detector 2 3D coordinates in mm 247 110 136 -- detector 3 3D coordinates in mm 247 110 146 -- detector 4 3D coordinates in mm 246 110 156 -- detector 5 3D coordinates in mm 243 110 166 -- detector 6 3D coordinates in mm 241 110 176 -- detector 7 3D coordinates in mm 238 110 186 -- detector 8 3D coordinates in mm 235 110 195 -- detector 9 3D coordinates in mm 230 110 203 -- detector 10 3D coordinates in mm 225 110 212 -- detector 11 3D coordinates in mm
The montecarlo module available on orbit includes sample data for running tMCimg; that is segmentation and config files. They are included with the under ./example/sphere.
To run tMCimg on the example data, simply do the following from the root montecarlo directory (on Linux):
cd ./example/sphere ./runmc40.sh ./runmc80.sh
This will create data for the 2 separate examples; one for the 40x40x40 segmented sphere with 2 tissue types, 1 source and 1 detector and one for the 80x80x80 segmented sphere with 2 tissue types, 1 source and 1 detector. After running the scripts (which run tMCimg) you can examine the outputs (the .2pt and .his files) in Matlab.
In this section, we demonstrate how to prepare and run a simulation session using Matlab and tMCimg. We will generate a 100x100x100 volume with 4 tissue types, and place 5 optodes on the surface and run tMCimg with 5 million photons on each optode.
a) Generate a 100x100x100 segmentation volume with 4 tissue types. Name it seg.bin
seg = zeros(100,100,100); seg(:,:,10:25) = 1; seg(:,:,26:50) = 2; seg(:,:,51:75) = 3; seg(:,:,76:end) = 4; fid = fopen('seg.bin', 'wb'); fwrite(fid, seg, 'uint8'); fclose(fid);
b) Position the source and 4 detectors at the following locations
s1: (50, 30, 10) d1: (50, 35, 10) d2: (50, 25, 10) d3: (55, 30, 10) d4: (45, 30, 10)
generating 5 million photons and one time gate.
Create the .inp config files for all optodes for which you want to create a 2pt fluence file. For instance, for source 1, you can create a file named sample.s1.inp. (The file name is arbitrary for tMCimg as long as it has a .inp extension. But it's a good idea to include the optode type and number to know which optode the config file uses as the source.)
Here's what the contents of two of the 5 input files - sample.s1.inp and sample.d1.inp - might look like:
sample.s1.inp:
5000000 -75126705 50.0 30.0 10.0 0.0 0.0 1.0 0 5.000000e-09 5.000000e-09 ./seg.bin 1 100 1 100 1 100 1 100 1 100 1 100 4 0.660000 0.001000 0.019100 1.000000 0.860000 0.001000 0.013600 1.000000 0.010000 0.001000 0.002600 1.000000 1.100000 0.001000 0.018600 1.000000 4 1 50.0 35.0 10.0 50.0 25.0 10.0 55.0 30.0 10.0 45.0 30.0 10.0
sample.d1.inp:
5000000 -25509511 50.0 35.0 10.0 0.0 0.0 1.0 0 5.000000e-09 5.000000e-09 ./seg.bin 1 100 1 100 1 100 1 100 1 100 1 100 4 0.660000 0.001000 0.019100 1.000000 0.860000 0.001000 0.013600 1.000000 0.010000 0.001000 0.002600 1.000000 1.100000 0.001000 0.018600 1.000000 4 1 50.0 30.0 10.0 50.0 25.0 10.0 55.0 30.0 10.0 45.0 30.0 10.0
Then on the command line in whichever shell you're running, run tMCimg for each optode you need. In this example there are 5 optodes, so to get fluence data for all the optodes run tMCimg 5 times, without including the .inp extension, like this:
tMCimg sample.s1 tMCimg sample.d1 tMCimg sample.d2 tMCimg sample.d3 tMCimg sample.d4
This will generate the .2pt and .his files for all 5 optodes.
The bug reporting and discussion forum are still works in progress, soon to be revisited.
The project is licensed under a BSD license (please read the details in the LICENSE). This means that users can not only use the program, but also can be involved in the collaborative development of the program. The maintainer of this software are very excited to see more developers contribute to this software.
The latest code can be accessed from our CVS repository at https://orbit.nmr.mgh.harvard.edu/scm/?group_id=29 where the module name is "montecarlo". One can also browse the latest source code from https://orbit.nmr.mgh.harvard.edu/plugins/scmcvs/cvsweb.php/montecarlo/?cvsroot=braindynamo
Users can download the program without creating a gforge account. However, if one wants to be involved in the development, one can consider the following: