[Camino-users] Multiple tractography updates in r1020

[Philip A Cook]

Hi all,

I have just committed a fairly substantial update to the tractography code in r1020.

I've done some tests but when dealing with geometry there are so many permutations, so please be on the look out for strange behavior.

I've addressed some feature requests, such as allowing arbitrary integer labels in track / procstreamlines. I haven't yet been able to fix conmap, sorry about that. 


A summary of the major additions:

- Expanded NIfTI support and better handling of the header transformations in track / procstreamlines etc. track / procstreamlines will now output NIfTI rather than Analyze (unless you input Analyze files). 

- For any program requiring -voxeldims and -datadims, you can now pass "-header image.nii" and the voxel and data dimensions will be set automatically (as will the voxel to physical transform, but not all programs make use of that).

- Support writing of compressed NIfTI images directly

- Streamlines output from track / procstreamlines / vtkstreamlines are now stored in the physical space of the image, according to the NIfTI transform.

- For tracking, seed points are now defined in physical space. For example, if you have a T1 image of 1mm resolution aligned to a DT image of 2mm resolution, you can draw seed ROIs in your 1mm space and then pass them to track with something like:

nii2dt -inputfile 2mm_dt.nii.gz | track -inputmodel dt -seedfile 1mmT1_seeds.nii.gz -header 2mm_DT.nii.gz > tracts.Bfloat

The seed points defined in the 1mm image will now be correctly placed in the DT image.

- For tracking, ROIs can now take any 32-bit integer value. ROI indices no longer have to be contiguous 1,2,3,...,N or M, M+1,...,M+N. Output is processed by region ID, not by region number. Thus if your seed ROI contains labels 2, 4, 6, the output will be so numbered. The output numbering 

- procstreamlines will no longer resample tracts by default. This will save disk space and speed up processing. Resampling was done before to improve precision of ROI filtering, but the best way to control this is to track with an acceptable step size.


How we handle images in track / procstreamlines

The old way: Data / ROIs were assumed to have the same orientation and the same origin at (0,0,0). Effectively this meant that you had to make all your images in the same voxel space. Output was dumped to a .img file and a .hdr file was created with the appropriate voxel and data dimensions.


The new way: The physical space, and hence the format of the output images, are defined by the input images. That is, if you pass an Analyze hdr / img pair, you'll get Analyze output, and if you pass a .nii image you'll get .nii output. Don't mix and match image formats, it will likely cause problems.


Example of the new way: Images in the same voxel space.

If your images are in the same voxel space, for example you've drawn an ROI on an FA image in your diffusion space, then you can pretty much do the same thing as before:

snap subj_tp_fa.nii.gz 

[draw some ROIs]

track -inputmodel dt -inputfile subj_tp_dt.Bdouble -seedfile subj_tp_fa_rois.nii.gz | procstreamlines -seedfile subj_tp_fa_rois.nii.gz -outputacm -outputroot subj_tp_

This is the same command line that you would have used previously. As before, the diffusion space is assumed to be the same as the seed space, so the data and voxel dimensions are taken from subj_tp_fa_rois.nii.gz. The key difference is that the tracts are output in the physical space. These tracts are then read by procstreamlines, which computes the ACM, again using subj_tp_fa_rois.nii.gz as the definition of physical space. 

The key difference you'll notice is the output: subj_tp_acm_sc.nii.gz is NIfTI, not Analyze, and it will have the same header transform as subj_tp_fa.nii.gz.

Side note: the decision to gzip the output is inferred from the image that is used to define the physical space. If I had used a .nii image, the output would not be compressed unless I additionally passed -gzip. The endianness of the output is also inferred from the input.


Example of the new way: Images in different voxel space

As above, imagine a T1 image at 1mm resolution and a DT image at 2mm resolution. Let's further imagine that the images have different voxel to physical transforms, but they are aligned such that point (x,y,z) in physical space is the same point anatomically in both images.

nii2dt -inputfile 2mm_dt.nii.gz | track -inputmodel dt -seedfile 1mmT1_seeds.nii.gz -header 2mm_DT.nii.gz | procstreamlines -header 1mmT1_seeds.nii.gz -outputacm -outputroot 1mm_

Because the output of track is in physical space, we can construct our ACM directly in the 1mm image space (which shares the same physical space, but not the same voxel space).


Things that have been deprecated and removed:

-directional, this option to track let you define connectivity in one plane, eg tracts to the left hemisphere only. This feature became redundant once we added exclusion ROIs. To get connectivity to one hemisphere, use an exclusion ROI and truncate anything that crosses to the other hemisphere. 

-outputtracts oogl, use VTK. If anyone is still using Geomview, we can potentially bring this option back but as a separate program, like vtkstreamlines

-outputtracts voxels, we keep everything in physical space.

-seedindex, this spawns too many processes, better to use -regionindex to parallelize. 

-seedpointvox and -seedpointmm, seed ROIs should be image based to ensure that they are placed correctly.