Tubegen

tubegen is a program that generates "streamtubes" from a tensor field. Streamtubes are tubes of a particular radius around streamlines, 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.

To submit bugs and feature requests, go to the bug page.

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.

The basic sequence of the program is as follows:

1. Generate a set of seed points
2. Generate a set of streamlines advected from those points
3. Throw away the streamlines that are too short, have too low anisotropy (tubegen uses linear, not fractional, anisotropy in the current version), etc.
4. Compute a pairwise curve distance between all the remaining curves and throw away curves that are too close to others.
5. Generate a streamtube model (a curvy cylindrical shape around each streamline).

Technical Details

We use 2nd- (or 4th-) 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
Output Files
out	str	Output .sm file. Note that even if you use the -SAVESM 0 to avoid generating tubes from the streamlines, this argument still must be specified and must end in ".sm".	/map/gfx0/common0/diffusion/Interface/bin/tubegen/1.sm
Integration Parameters
ODE	n	ODE method. n=0 ⇒ rk2; n=1 ⇒ rk4	0
cs	n	Min tube length in mm	20
seed	f f f	Size of voxel group in the imaging volume in which to place one integration seed each. i.e. 1 1 1 generates one streamtube per voxel; 0.5 0.5 0.5 generates 8 streamtubes per voxel, 2 2 2 generates one streamtube per cube of 8 voxels.	10.0 10.0 5.0
stepsize	f	Stepsize 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. Set this to 0 to avoid an O(n2) pairwise distance check.	2.0
Mesh Generation
radius	f	Streamtube radius in mm	1.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 ". It has the same number, n, of streamlines, but k is generally higher for each streamline.

*.info

A plain-text file that specifies linear anisotropy for each of the streamlines. It contains n lines of one floating-point number each.

*.sm

A plain-text file specifying the shapes and colors of the rendered tubes in a custom mesh format. It is broken into three sections, separated by single blank lines: the first specifies the vertices, the second specifies faces, and the third specifies vertex colors. Comment lines begin with a hash sign ("#").

First section (vertices)

The first line is a big integer, specifying the number of vertices. 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. These lines are grouped into "paragraphs", each separated from the next one by a single blank line; this may or may not be meaningful.

Second section (faces)

The first line is a big integer, specifying the number of faces. Each subsequent line is three space-separated integers, the indices into the vertex list of the vertices of the face. These integers range in value from 0 to one less than the number specified at the beginning of the first section.

Third section (colors)

The first two lines each have a single "zero" character on them. Each subsequent line is three space-separated floating-point numbers in [0.0, 1.0][, representing an RGB color]. The number of three-number lines is equal to the number specified at the beginning of the first section.

*.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

This may specify the average magnitude of D or the average mean diffusivity; not certain which.

*.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