Quickly inspect FreeSurfer cortical surfaces

To quickly inspect the surface reconstruction and parcellations produced by the cortical stream of FreeSurfer, rather than laboriously open each hemisphere at a time in tksurfer, an easier solution is to run a script that captures images, organise and present them all in a single html page that can be seen in any browser.

Before you start

Before you start, make sure you have:

  • FreeSurfer, any version released in the last 2 years. The procedure has been tested up to version 5.1.0.
  • ImageMagick, any recent version. For most Linux, ImageMagick can be installed directly from the distro’s repository. For Mac, it can be obtained with MacPorts or Fink.
  • The scripts takeshots, makehtml, shots_tksurfer.tcl, and shots_tkmedit.tcl. Put all these scripts into the same directory and make takeshots and makehtml executable.

Capturing the images

  1. Make sure recon-all finished for all your subjects. If there are no results, obviously there won’t be anything to inspect.
  2. Make sure the variable SUBJECTS_DIR is correctly set, pointing to the directory that contains the subjects, and that you have writing permissions to this directory.
  3. Prepare a text file containing a list of subjects, one per line, like this:
  4. Run the takeshots script. A typical usage is like this:
    ./takeshots -l listsubj.txt -m pial -m inflated -p aparc
    The options are:
    -l: List of subjects.
    -s: Additional subjects not in the list.
    -m: Surfaces to inspect (pial, inflated, white, sphere, etc).
    -p: Parcellations to inspect (aparc, aparc.a2005s, aparc.a2009s, etc).
    This script will create a subdirectory called ‘shots’ inside the directory of each subject, and will store a number of .tif files that are the different views of the cortical surfaces.
  5. Run the makehtml script. A typical usage is like this:
    ./makehtml -l listsubj.txt -m pial -m inflated -p aparc -d /path/to/html
    The options are identical to the previous command, with the addition of the option -d that lets you specify a directory where the html will be created. If this directory doesn’t exist, it will be created.

What you get

Open the file index.html in the directory specified in the previous step. There you’ll see all the surfaces of all the subjects, all in the same page, allowing you to quickly compare and have an idea of how good or bad they are. To see the name of the subject, hover the mouse on the corresponding image. Click on the image to see it larger. An example, using only pial and inflated surfaces, and the aparc parcellation, is here.

4 thoughts on “Quickly inspect FreeSurfer cortical surfaces

  1. Hey there,
    Thanks for your post, I found this possibility really interesting, so even as a complete newbie to UNIX I thought I might try it out. As expected, I hit a few roadblocks but I feel I’ve come to far to give up now. My current error is at the ./makehtml step and so seems to be with my ImageMagick install, but I think its just because I can’t sort out the directory paths to my freesurfer images created by ./takeshots (which worked).

    My basic error message is :
    helens-imac:tcl helen1$ ./makehtml -s DTI003 -m pial -m inflated -p aparc -d/Views
    Preparing pial images
    convert: unable to open image `/Views/pial/images/DTI003_lh_pial_aparc_inf.png’: Permission denied @ error/blob.c/OpenBlob/2646.
    convert: WriteBlob Failed `/Views/pial/images/DTI003_lh_pial_aparc_inf.png’ @ error/png.c/MagickPNGErrorHandler/1804.
    convert: unable to open image `/Views/pial/images/DTI003_lh_pial_aparc_inf.png’: No such file or directory @ error/blob.c/OpenBlob/2646.
    convert: unable to open file `/Views/pial/images/DTI003_lh_pial_aparc_inf.png’ @ error/png.c/ReadPNGImage/3992.
    convert: no images defined `/Views/pial/thumbnails/DTI003_lh_pial_aparc_inf.png’ @ error/convert.c/ConvertImageCommand/3106.
    ……..which goes on for each image.

    Do you have any suggestions? I have changed the permissions to all the relevant folders and my DYLD path is set as they instructed on the install page for ImageMagick /Applications/ImageMagick-6.8.6/lib/
    makehtml and the other scripts are in /freesurfer/lib/tcl – and I’m currently using terminal, though I have X11 to use freesurfer.

    Thanks in any case!

    • Hi Danica,

      Two possible causes for the error:

      1) Ideally there should be a space between the “-d” and the path that you specify.

      2) In the Mac (and in most Linux/Unix) normally we don’t have permissions to create new directories in the root (i.e., from “/”), so that you get an error when the script tries to create “/Views”. Try instead simply “-d Views” (so, without the “/”), or make sure it’s created in your home directory, by adding a tilde “~” at the beginning, before the slash, like this: “-d ~/Views”.

      Hope this helps!

      All the best,


      • Thanks so much for your help! When I used your suggestion, the script ran well and created the html file and relevant folders, but both are empty of images (unlike /shots in the subject folder). Since no error messages are produced, I think its a problem with the way I installed ImageMagick and how it communicates with X11 in “display”, and I’ve posted on their forum. If there is a fix, Ill let you know :)

  2. This makes me very happy! Works like a charm. The use of imagemagick kind of restricts its use to computers you can install packages on (not the case for my cluster, too bad). Very nice script though, really appreciate you taking the effort to post it!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s