Email questions/comments to yeoyeo02 at gmail dot com
*Matlab Version 1.5.1 available*
Spherical Demons is an algorithm that registers spherical images. It extends the Demons algorithm in Euclidean space to the sphere. We use it to perform fast diffeomorphic landmark-free surface registration of 2D closed surfaces. It assumes the 2D closed surfaces are spherically parameterized and represented as spherical images. Each point on the sphere has some features describing the geometry of the original surface. For example, in the case of cortical surfaces, the features we use are mean curvature of the inflated cortical surface, sulcal depth (average convexity) and curvature of the original cortical surface. We have shown that registration between a subject mesh and an atlas takes less than 5 mins on a Xeon 3.2GHz single processor machine, which is more than 10 times faster than the popular, freely-available FreeSurfer. Our experiments also show that Spherical Demons is at least as accurate as FreeSurfer. See papers below for more details.
We provide 5 example surfaces distributed with our code (under example_surfaces folder). They are part of the publicly available oasis dataset.
Note: Our default smoothness settings give good sulci/gyri parcellation and Brodmann areas alignment. However, the co-registered surfaces might not "look very registered". If you want the surfaces to "look very registered", you can play around with the registration smoothness parameters reg_parms inside CoregisterSurfaces.m. The comments in the ".m" file discuss this. However, in our experience, under such non-linear situation where the registered surfaces "look very registered", the parcellation and Brodmann areas alignment performance suffers due to overfitting (see a discussion of this phenomenon in our other paper here).
B.T.T. Yeo*, M.R. Sabuncu*, T. Vercauteren, N. Ayache, B. Fischl, P. Golland. Spherical Demons: Fast Diffeomorphic Landmark-Free Surface Registration. IEEE Transactions on Medical Imaging, 29(3):650--668, 2010. [pdf]
B.T.T. Yeo, M. Sabuncu, T. Vercauteren, N. Ayache, B. Fischl, P. Golland. Spherical Demons: Fast Surface Registration. Proceedings of the International Conference on Medical Image Computing and Computer Assisted Intervention (MICCAI), volume 5241 of LNCS, 745--753, 2008 [pdf] Runner-Up, MICCAI Young Scientist Award
Download Spherical Demons version 1.5.1 (SDv1.5.1-svn593.tar.gz)
Unzip SDv1.5.1-svn593.tar.gz (In linux, type "tar -xvzf SDv1.5.1-svn593.tar.gz")
In matlab, type "add_all_paths" INSIDE the SDv1.5.1-svn593 folder. Note that you have to redo this step every time you restart matlab, unless you ask matlab to save the paths permanently. For example, in linux, you can include add_all_paths in startup.m
If you have NEVER used mex do the following (if you have, go to step 5):
type "mex -setup" in matlab
On prompt by matlab, in linux, choose any of the compilers you like
If prompted by matlab about whether to overwrite <prefdir>/mexopts.sh, type "y" to agree
On my machine, matlab now says <some_path>/<some_opts>.sh being copied to <prefdir>/mexopts.sh. Note that <prefdir> is the directory returned by matlab function prefdir.
In matlab, type "compile_all" INSIDE the SDv1.5.1-svn593 folder
In matlab, type "CoregisterSurfaces" INSIDE the SDv1.5.1-svn593/SphericalDemons/ReleaseSampleCode folder. Program will start co-registering the 5 example surfaces provided with the code. Since each registration takes 5 minutes and we set the default at 2 rounds of registration, the whole process should take about 5min x 5 x 2 = 1 hr.
There are a lot of comments in CoregisterSurfaces.m. Read them!
There are also utilities in the SphericalDemons/freesurfer folder for pairwise registration (mris_SD_pairwise_register.m), for registration to an atlas (mris_SD_register.m) and constructing a template (mris_SD_make_template.m), as well as example atlases constructed from 39 in vivo subjects (?h.DW.Atlas1to39.2.10.mat)
Difference between version 1.5.1 and 1.5
Functionality unchanged.
Certain minor bugs and instabilities of functions in BasicTools and AnalysisTools directories were fixed.
Difference between version 1.5 and 1.4
New optional and recommended routine SD_NormalizeAtlasWarps.m to be called before SD_CreateAtlasFromRegisteredSurfaces.m. See updated CoregisterSurfaces.m for example. Briefly, this routine subtracts the average warps (over all the subjects) from each subject's warp and OVERWRITES the subject's warp. This ensures no "drift" of the atlas space and the atlas coordinates remain unbiased.
New optional routine SD_CreateAtlasFromRegisteredSurfacesIncremental.m thanks to Andersen Winkler from Yale. The routine is a memory efficient, but slower version of SD_CreateAtlasFromRegisteredSurfaces.m, that reads in the subjects one at a time. This allows an atlas to be built from hundreds of subjects.
Difference between version 1.4 and 1.3
Fixed bug in mris_SD_pairwise_register.m and mris_SD_register.m (the bug was really in SD_registerAtlas2SphereMultiRes.m), which is problematic when there are huge rotation (e.g. conformally-mapped surfaces). Thanks to Wen Li from Iowa for pointing it out. It shouldn't affect freesurfer surfaces much, but rerunning the registration with the new code might improve things.
I also removed min_heap from this version. This is not a critical utility, and some people have difficulties compiling it.
Difference between version 1.3 and 1.2
Fixed bug in mris_SD_pairwise_register.m (the bug was really in SD_registerPairOfSpheres.m) for pairwise registration. The code was only using the highest resolution features from the moving image for registration with the fixed image. Surprisingly, this was not a big problem with the freesurfer surfaces, but was found to be problematic with the conformally-mapped surfaces. The bug does not affect the other two functions for atlas construction and registration to an atlas. Thanks to Wen Li from Iowa for pointing it out.
Difference between version 1.2 and 1.1
Add functionality in SphericalDemons/freesurfer folder for pairwise registration (mris_SD_pairwise_register.m), for registration to an atlas (mris_SD_register.m) and constructing a template (mris_SD_make_template.m)
Example atlas constructed from 39 invivo subjects in same folder (?h.DW.Atlas1to39.2.10.mat)
Tested on Linux (Debian 64bits, 32bits, Ubuntu 32bits), Windows XP 64bits (works with Visual Studio, but NOT LCC), PowerMac G5.
Comes with 5 example surfaces, under "example_surfaces" folder inside SDv1.4-svn593 folder. They are part of the publicly available oasis dataset.
Assumes FreeSurfer surface format and data directory structure. Default parameter settings assume existence of FreeSurfer surface: ?h.sphere with accompanying feature vector files: ?h.inflated.H, ?h.sulc and ?h.curv.
Code from other sources:
Code in kd_tree code provided by Guy Shechter found on matlab central. Copyrights of those files belong to him.
For convenience, we also distribute a few FreeSurfer .m files (read_surf, read_curv, read_fscolorlut, fread3). The copyrights of those files belong to FreeSurfer.
Spherical Demons version 1.5 (SDv1.5-svn593.tar.gz)
Instructions same as version 1.5.1
Spherical Demons version 1.4 (SDv1.4-svn593.tar.gz).
Instructions same as version 1.5
Spherical Demons version 1.3 (SDv1.3-svn593.tar.gz).
Instructions same as version 1.4
Spherical Demons version 1.2 (SDv1.2-svn593.tar.gz).
Instructions same as version 1.3
Spherical Demons version 1.1 (SDv1.1-svn593.zip).
Instructions same as version 1.2
Spherical Demons version 1.0 (SDv1.0-svn569.zip).
Instructions same as version 1.1, except that before if you are in linux, in a text editor, open up <prefdir>/mexopts.sh. Search and remove all instances of "-ansi". This is because the -ansi format does not allow the use of "//" as a comment in .c files. ***Note that if the mexopts.sh file is not in your <prefdir>, it is probably because your <prefdir> has changed since the last time you use "mex -setup". You can either rerun "mex -setup" or try to find the mexopts.sh and move it to your current <prefdir>***
Release comments same as version 1.1.
A preliminary version is now available. Unfortunately, the ITK code does not work well, so if you need to register real data or surfaces, the matlab code is the best bet!
Acknowledgments
Support for this research is provided in part by the NAMIC (NIH NIBIB NAMIC U54-EB005149), the NAC (NIT CRR NAC P41-RR13218), the mBIRN (NIH NCRR mBIRN U24-RR021382), the NIH NINDS R01-NS051826 grant, the NSF CAREER 0642971 grant, NCRR (P41-RR14075, R01 RR16594-01A1), the NIBIB (R01 EB001550, R01EB006758), the NINDS (R01 NS052585-01) and the MIND Institute. Additional support was provided by The Autism & Dyslexia Project funded by the Ellison Medical Foundation. B.T. Thomas Yeo is funded by the A*STAR, Singapore. Short visits of B.T. Thomas Yeo and Nicholas Ayache between MIT and INRIA were partially funded by the CompuTumor associated teams funding.