Tubegen

tubegen is a program that generates "streamtubes" from a tensor field. We define streamtubes as integral paths in the interpolated field of principle eigenvectors of the diffusion tensors. Many of our studies with clinical neuroscience collaborators use streamtubes as a proxy for axon tracts in the brain's white matter and involve computing measures over the streamtubes. We also do HCI and visualization research motivated by the fundamental difficulties of interacting with a complex jumble of tubes.

We use this program extensively in the diffusion MRI project and it is generally run at the end of the diffusion processing pipeline.

Technical Details

We use 2nd-order Runge-Kutta numerical integration with tricubic b-spline interpolation of the principle eigenvectors; the citation we've used for this process is:

Peter J. Basser, Sinisa Pajevic, Carlo Pierpaoli, Jeffrey Duda, and Akram Aldroubi. In vivo fiber tractography using DT-MRI data. Magnetic Resonance in Medicine, 44:625632, 2000. (PDF)

Once you've generated a bunch of streamtubes, it makes sense to remove some so that you get a visually or statistically representative set. The full streamtube process, including termination conditions, culling, and terminology, is described in Song's 2003 TVCG article .

tubegen may be found in $G/bin/tubegen. It generates a *.sm file, which brainapp reads in order to visualize and interact with the streamtubes.

Command-Line Arguments

Common Arguments

arg	params	description	defaults
Input Files
dt	str	Diffusion tensor image path	/u/sz/diffusion/data/susumu/mri/Diff
t2	str	T2-weighted image path	/u/sz/diffusion/data/susumu/mri/T2
FA	str	Fractional Anisotropy image	./d2mem/FA
Output Files
out	str	output sm file	/map/gfx0/common0/diffusion/Interface/bin/tubegen/1.sm
Integration
ODE	n	ode method, 0:rk2, 1:rk4	0
cs	n	Max tube length	20
seed	f f f	sample space along each dimension	10.0 10.0 5.0
stepsize	f	Stepsize in mm	1.0
radius	f	streamtube radius	1.0
al	f	Low threshold for linear anisotropy	0.1
dth	f	Low threshold on distances in mm	0.5
t2thresh	f	t2 low threshold	-1.0
Longshort	n	For integration, start from long one? (1) or short one(0), or longest of the two (2), or mean of the two (3)	0
Culling
cl	f	Min Average Linear Anisotropy	0.3
cd	f	Min Distance between tubes in mm	2.0

Obscure Arguments

arg	params	description	defaults
Output Files
SAVESM	n	Save sm file	1
Output Mesh Control
NUMPTR	n	Number of points on a ring	6
MESHNOVSIZE	n	Mesh coords not affected by vsize	0
OUTFA	n	output FA as red color	0
Integration
USROI	n	use region of interest for seed points generation	0
ROI	f f f f f f	region of interest, specify center point and edge length	0.0 0.0 0.0 0.0 0.0 0.0
chi0thresh	f	isotropy model Chisqr threshold	2.0
chi1thresh	f	isotropy model Chisqr threshold	2.0
chi2thresh	f	isotropy model Chisqr threshold	2.0
Culling
wd	n	Gaussian weighted distance: end points get higher weight.	0
USECUTOFFROI	n	use cutoff ROI	0
ROICUTOFF	f f f f f f	Cut off ROI, only streamtubes running through this ROI are kept	0.0 0.0 0.0 0.0 0.0 0.0
Statistical Options
chi0	str	chisqr for isotropic model	/u/sz/diffusion/data/susumu/mri/Diff
Partial Volume
pv	str	Partial volume between iso and wm image path	/u/sz/diffusion/data/susumu/mri/Diff
pv1thresh	f	partial volume threshold for tracking	0.5
pvwm	str	Partial volume between wm image path	/u/sz/diffusion/data/susumu/mri/Diff
Unknown
cr	f	Compress ratio, 0 means no compression	0.3
randlen	f	random jittering diameter, coupled with seed	1.0
randseed	f	srand? 0: no srand, -1 srand(time), other:srand(other)	0.0
ColSeed	n	seed ColA data mask for seeds	0
Colmask	str	Col mask image path	nomask
ColmaskVx	f f f	Vx of the mask Coord	0.0 0.0 0.0
ColmaskVy	f f f	Vx of the mask Coord	0.0 0.0 0.0
ColmaskCtr	f f f	Ctr of the mask Coord	0.0 0.0 0.0
ColDTICtr	f f f	Ctr of the DTI Coord	0.0 0.0 0.0
ColDTIvsize	f f f	vsize of the DTI Coord	0.0 0.0 0.0
Colmaskvsize	f f f	vsize of the mask Coord	0.859376 0.859376 3.0
ColS	n	Number of random points used in a voxel in Colseeding	4
SS	n	Using the tubes generated for the seed points of the Second Start	0
flatdir	n	trace on a plane perpendicular to flatdir. 0: 1 0 0; 1: 0 1 0; 2: 0 0 1	-1
SEG	str	Segmentation image	NoSegFile
SF	str	Seed-points file	NoSeedsFile
OUTSF	str	Output seed-points file	NoSeesFile
USESF	n	Use seed-points file	0
GMCON	n	GM constaint extension step, 0 means no constraint	0
CROSSMIDBRAIN	n	Col lesion test, keep only the tubes across midbrain	0
MIDBRAIN	n n n	Definition of midbrain	0 45 45
FASAMPLING	n	sample according to FA	0
Multicompartment Input Files
MC	n	Multicompartment	0
dt1	str	First diffusion tensor image path in multi compartemnt model	/u/sz/diffusion/data/susumu/mri/Diff
dt2	str	Second diffusion tensor image path in multi compartment model	/u/sz/diffusion/data/susumu/mri/Diff
Multicompartment Statistical Options
chi1	str	chisqr for single compartemnt model	/u/sz/diffusion/data/susumu/mri/Diff
chi2	str	chisqr multi compartemnt model	/u/sz/diffusion/data/susumu/mri/Diff

Output Files

In addition to the .sm file that you specify with the "out" argument, tubegen also generates corresponding .data, .info, .nocr, .size, and .wrl files in the same directory as the specified output.

It sure would be nice to know what all of them are and how they're structured...

streamtube Library

$G/src/streamtube/streamtube is where the top-level streamtube library lives. This depends on a bunch of helper libraries located in the directories above there with bullshit names like "magnetite" and "fibrolite".

Publications

• Streamtube generation and culling:
  • Zhang-2003-VDT‌ --- TVCG '03
• Tract-of-interest metrics:
  • Lee-2006-QTM‌ --- ISMRM '06 poster
  • Laidlaw-2007-QTI‌ --- Views Radiology '07 short article
  • Correia-2008-QTM‌ -- Neuroimage '08 full clinical article

See Also

• Diffusion Processing Pipeline
• Brainapp