Thursday, February 8, 2018

Connectome Workbench: making a surface version of a volumeric image

This is a tutorial for making a surface version of a volumetric (NIfTI) image (e.g., a ROI) for visualizing with the Connectome Workbench. This post replaces a tutorial I wrote back in 2013, and assumes a bit of familiarity with Workbench. If you're using Workbench for the first time I suggest that you complete the tutorial in this post before trying this one.

First, a warning: as advertised, the steps in this post will make a surface version of a volumetric image. However, the surface version will be an approximation, and likely only suitable for visualization purposes (e.g., making an illustration of a set of ROIs for a talk). If you have an entire dataset that you want to prepare for surface analysis (e.g., running GLMs), you need different procedures (e.g., SUMA, FreeSurfer). Again, I suggest the directions in this post (wb_command -volume-to-surface-mapping) be used cautiously, for quick visualizations, and accompanied by careful confirmation that the mapping produced a reasonable result.

needed files

Before we can make a surface version of a volumetric image, we need to know what it's aligned to, so that we can pick the proper corresponding surface template. Recall that gifti surface files (*.surf.gii) are sort of the underlay anatomy for surface images (e.g., in my Getting Started post on Workbench we load surf.gii files to get a blank brain), so we'll need gifti surface files that will work with our volumetric image (and to serve as the underlay when we're ready to plot the converted volumetric ROI).

For this demo, we'll use fakeBrain.nii.gz (it should let you download without signing in; this is the same NIfTI as shown in other posts), which is aligned to MNI. One MNI dataset with the necessary surface files is the HCP 1200 Subjects Group Average Data; this post describes the files and gives the direct ConnectomeDB download link.

The HCP 1200 Subject Group Average download contains multiple *.surf.gii for each hemisphere, including midthickness, pial, and very_inflated. We can use any of these for visualization in Workbench, but which we pick for the volume to surface conversion does make a difference in what the resulting surface image will look like. It seems best to start with the midthickness surface for the conversion, then try others if the projection seems off.

using wb_command

The wb_command -volume-to-surface-mapping function does the conversion. wb_command.exe (on my Windows machine; file extension may vary) should be in the same directory as wb_view.exe, which you use to start the Workbench GUI. Don't double-click wb_command.exe - it's a command line program. Instead, open up a command prompt and navigate to the directory containing wb_command.exe (on my machine, /bin_windows64/). If you  type wb_command at the prompt it should print out some version and help information; if not, check if you're in the correct directory, and try ./wb_command if you're on a linux-type system.

Now we're ready: we give the function our input NIfTI (fakeBrain.nii.gz), our surface gifti (, the output file we want it to make (demoL.shape.gii), and the options for it to use (-trilinear). Since surface gifti files are just for one hemisphere, we have to do the command twice, once for each. (I included the full path to each file below; update for your machine.)

 wb_command -volume-to-surface-mapping d:/temp/fakeBrain.nii.gz d:/Workbench/HCP_S1200_GroupAvg_v1/ d:/temp/demoL.shape.gii -trilinear  
 wb_command -volume-to-surface-mapping d:/temp/fakeBrain.nii.gz d:/Workbench/HCP_S1200_GroupAvg_v1/ d:/temp/demoR.shape.gii -trilinear  

We now have demoL.shape.gii and demoR.shape.gii, surface versions of fakeBrain.nii.gz, which can be viewed in Workbench (or other gifti-aware programs). Check the surface projection carefully: does the ROI align properly with the anatomy? If not, try a different .surf.gii or fitting option (e.g., -enclosing) in the wb_command call; these can make a big difference.

Below the jump are the surface images from the above commands, plotted on the S1200 midthickness in Workbench.



  1. Some nits to pick: First, terminology: The voxels that get considered as important often do not have their exact values preserved, so it is more like a resampling than a conversion. We have been calling it "mapping" for many years. Of course, the problems of using group-average surfaces make it a rather lossy process, and I would be even less inclined to call it a "conversion" in this case. Thank you for alluding to these problems in the intro.

    The different interpolation options aren't changing the alignment, only how it turns voxel values into surface values - they serve different purposes (trilinear and cubic for continuous data (though we don't really use them anymore, in favor of ribbon mapping), enclosing voxel for integer data (but see -volume-label-to-surface-mapping to use ribbon mapping for this also)). Different surfaces will definitely change your alignment, but as midthickness runs through the center of cortex in individuals, it makes the most sense for individual data, if you decide you want to use point interpolation rather than ribbon mapping (fewer arguments to the command, I suppose).

    We have argued for a long time that surface-based analysis is the way forward (the HCP-MMP1.0 wouldn't exist without it), so hopefully this kind of "visualization of volume-based group results" use becomes less relevant over time.

    1. Thanks for the comments! I assume by ribbon mapping you're referring to -volume-to-surface-mapping -ribbon-constrained; it wasn't clear to me how to use this option for the above example: Are suitable files for and included in the HCP 1200 Subject Group Average (which ones)? Would I use the -volume-roi option, and if so, how? (The command above has fakeBrain.nii.gz in the slot.)

    2. Again, group average surfaces are not recommended for mapping to or from volume space for analytical purposes, so I wouldn't really call anything in the group average dataset "suitable" (to put a finer point on it, we aren't sure there is any method truly "suitable" for mapping group average volume results to the surface - you can usually get away with it for visualization because of how blurry the volume results are). The -volume-roi option's purpose is to exclude problematic voxels (noisy or otherwise disruptive), which we use in the HCP pipelines to exclude large veins (this exclusion is possible because we map the individual data to individual surfaces before analysis). It is not required, and I don't see it being useful in this specific example.

      In individuals, the outer and inner surfaces to the -ribbon-constrained option should generally be the white and pial surfaces (to capture the entire cortical ribbon). I believe the group average dataset also contains group average white and pial, so you could try to use them, but they don't fare any better after group averaging than the midthickness does.