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.

Code Overview

The tubegen command may be found in $G/bin/tubegen. The source code for the program lives in $G/src/tubegen, but it is just a simple command-line interface to the streamtube library, the source of which is located at $G/src/streamtube. The program generates a *.sm file, which brainapp reads in order to visualize and interact with the streamtubes, as well as several other output files.

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 .

Command-Line Arguments

Current Values

To get some degree of consistency across our results, we use the following arguments:

$(G)/bin/tubegen
 -dt voxel_models/tensors
 -t2 voxel_models/I0
 -out aggregate_models/tube_12.sm
 -ODE 0
 -cs 10
 -seed 1 1 1
 -stepsize 1.0
 -radius 0.3
 -al 0.1
 -dth .5
 -t2thresh -40
 -Longshort 1
 -cl .1
 -cd 1.7

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 Parameters
ODE	n	ODE method. n=0 ⇒ rk2; n=1 ⇒ rk4	0
cs	n	Max tube length in mm	20
seed	f f f	Number of seed points to place in each voxel along each dimension (i.e. 1 1 1 generates one streamtube per voxel; 10 10 5 generates 500 streamtubes per voxel)	10.0 10.0 5.0
stepsize	f	Stepsize in mm	1.0
radius	f	Streamtube radius in mm	1.0
al	f	Low threshold for linear anisotropy for terminating integration	0.1
dth	f	Low threshold on inter-tube distances, in mm, for terminating integration	0.5
t2thresh	f	T2 low threshold for terminating integration	-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
Streamtube Culling
cl	f	Min average Linear Anisotropy	0.3
cd	f	Min distance between tubes in mm	2.0

Obscure Arguments

To keep this page from getting cluttered, the table of obscure arguments is on a sub-page. Please see /Obscure Arguments for this table.

Output Files

In addition to the .sm file that you specify with the "out" argument, tubegen also generates several corresponding files in the same directory.

*.size

A plain-text file containing a single number, n, specifying the total number of streamtubes described by these files.

*.data

A plain-text file [specifying colored streamlines]. First line is the number n and should agree with *.size. This is followed by n groups of lines that define one streamline each. The first line of a streamline definition is a single integer k, which gives the number of points on the streamline. This is followed by k lines of 6 space-separated floating-point numbers each. The first three numbers are the coordinates of a point, and the following three are an RGB [0.0, 1.0] color for that point.

*.nocr

A plain-text file [specifying densely-sampled streamlines with no color]. Its format is identical to *.data but the color coordinates are all "0 0 0 ".

*.info

A plain-text file that specifies [some scalar value, maybe length?] for each of the streamlines. It contains n lines of one floating-point number each.

*.sm

A plain-text file [specifying the streamlines]. First line is [a big number]. Each subsequent line is either blank or contains three space-separated floating-point numbers. Each three-number line represents the coordinates of a point in space. The three-number lines are grouped into "paragraphs", each separated from the next one by a single blank line.

*.wrl

A VRML file specifying the shapes and colors of the rendered tubes.

For computing tract statistics, several other files may be generated, all of which have the same format as the *.info file.

*.ad

Mean axial (parallel) diffusivity of each streamline.

*.rd

Mean radial (perpendicular) diffusivity of each streamline.

*.md

Mean [magnitude of D XOR mean diffusivity = Trace(D)/3]

*.fa

Mean fractional anisotropy of each streamline.

streamtube Library

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

Publications

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

See Also

• Diffusion Processing Pipeline
• Brainapp