Tubegen
tubegen is a program that generates "streamtubes" from a tensor field. We use this program extensively in the diffusion MRI project and it is generally run at the end of the diffusion processing pipeline. 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.
Streamtubes are integral paths in the interpolated field of principle eigenvectors of the diffusion tensors. 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:
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
| arg | params | description | defaults |
|---|---|---|---|
| MC | n | Multicompartment | 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 |
| wd | n | Gaussian weighted distance: end points get higher weight. | 0 |
| dt | str | Diffusion tensor image path | /u/sz/diffusion/data/susumu/mri/Diff |
| dt1 | str | 1nd diffusion tensor image path in multi compartemnt model | /u/sz/diffusion/data/susumu/mri/Diff |
| dt2 | str | 2nd diffusion tensor image path in multi compartment model | /u/sz/diffusion/data/susumu/mri/Diff |
| chi0 | str | chisqr for isotropic model | /u/sz/diffusion/data/susumu/mri/Diff |
| 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 |
| t2 | str | T2-weighted image path | /u/sz/diffusion/data/susumu/mri/T2 |
| 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 |
| out | str | output sm file | /map/gfx0/common0/diffusion/Interface/bin/tubegen/1.sm |
| cr | f | Compress ratio, 0 means no compression | 0.3 |
| radius | f | streamtube radius | 1.0 |
| randlen | f | random jittering diameter, coupled with seed | 1.0 |
| randseed | f | srand? 0: no srand, -1 srand(time), other:srand(other) | 0.0 |
| al | f | Low threshold for linear anisotropy | 0.1 |
| cs | n | Max tube length | 20 |
| cl | f | Min Average Linear Anisotropy | 0.3 |
| cd | f | Min Distance between tubes in mm | 2.0 |
| dth | f | Low threshold on distances in mm | 0.5 |
| seed | f f f | sample space along each dimension | 10.0 10.0 5.0 |
| stepsize | f | Stepsize in mm | 1.0 |
| t2thresh | f | t2 low threshold | -1.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 |
| USROI | n | use region of interest for seed points generation | 0 |
| USECUTOFFROI | n | use cutoff ROI | 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 |
| 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 |
| ODE | n | ode method, 0:rk2, 1:rk4 | 0 |
| flatdir | n | trace on a plane perpendicular to flatdir. 0: 1 0 0; 1: 0 1 0; 2: 0 0 1 | -1 |
| 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 |
| OUTSF | str | Output seed-points file | NoSeesFile |
| USESF | n | Use seed-points file | 0 |
| SF | str | Seed-points file | NoSeedsFile |
| 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 |
| SEG | str | Segmentation image | NoSegFile |
| FA | str | Fractional Anisotropy image | ./d2mem/FA |
| SAVESM | n | Save sm file | 1 |
| 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 |
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