Intro

SUMA is a program that adds cortical surface based functional imaging analysis to the AFNI suite of programs http://afni.nimh.nih.gov . SUMA allows the viewing of 3D cortical surface renderings, the mapping of volumetric data onto them and, in future incarnations perform surface based computations and statistical inferences. With SUMA, AFNI can simultaneously and in real-time render Functional Imaging data in 4 modes: Slice, Graph (time series), Volume and Surface. SUMA supports surface models created by FreeSurfer http://surfer.nmr.mgh.harvard.edu/ and SureFit http://stp.wustl.edu/resources/surefitnew.html programs.

Requirements

To run SUMA you need to have OpenGL libraries in addition to motif and X run-time libraries that are present on any halfway decent unix system. OpenGL libraries are common on SGI and SUN systems. On Linux systems, Mesa's implementation of OpenGL is now distributed with recent Linux distributions such as RedHat 7.3. To date, we have compiled SUMA on Linux, SGI, SUN and MacOSx. By far, the fastest rendering was with systems having OpenGL graphics cards.

Nomenclature:

> sign represents a command on the unix command line. Text in italics represents comments.

>FS> commands for FreeSurfer demos only

>SF> commands for SureFit demos only

>linux> commands for linux only

>SGI> commands for SGI only

>SUN> commands for SUN only

>MAC> commands for Mac OSX only

>SU> commands that should be executed as Super User (root)

Commands following > may appear split in the documentation but they should be typed on one line.

Click here for Table of Contents

Installing SUMA

The easiest way to install SUMA is to download the executable suitable for your system. These executables require that certain shared libraries are present on your system. You can use ldd to find out which libraries SUMA needs and whether you have them on your system.

Download SUMA

See Installation Notes and Runtime Errors for help with errors encountered when attempting to run the binaries.

You will find more detailed information in the sections for compiling SUMA on Linux, SGI, SUN and MacOSx.

Installing and viewing the demo data set

Demo data are included for testing SUMA and learning how to use it with AFNI. The demo data set is available at http://afni.nimh.nih.gov/sscc/staff/ziad/SUMA. We provide demo data sets with both FreeSurfer (http://afni.nimh.nih.gov/sscc/staff/ziad/SUMA/SUMA_demo-FS.tgz) and SureFit (http://afni.nimh.nih.gov/sscc/staff/ziad/SUMA/SUMA_demo-SF.tgz) surfaces.

Thanks to H. Heekeren and S. Marrett for providing the high quality MR data and to P. Christidis and S. Japee for cortical surface model reconstruction using FreeSurfer and SureFit.

FreeSurfer demo:

Download SUMA_demo-FS.tgz archive (right mouse button à save as)

>FS> gzip -d SUMA_demo-FS.tgz

>FS> tar -xvf SUMA_demo-FS.tar

>FS> cd SUMA_demo/SurfData/SUMA

>FS> suma -spec DemoSubj_lh.spec

(suma will read a series of surfaces and display the first one. If that works then your installation was successful. Go to SUMA's usage documentation for the extensive demo tour. See http://afni.nimh.nih.gov/sscc/staff/ziad/SUMA/SUMA_doc.htm)

SureFit demo:

Download SUMA_demo-SF.tgz archive (right mouse button à save as)

>SF> gzip -d SUMA_demo-SF.tar

>SF> tar -xvf SUMA_demo-SF.tar

>SF> cd SUMA_demo/SurfData/SURFACES

>SF> suma -spec DemoSubj_lh.spec

(suma will read a series of surfaces and display the first one. If that works then your installation was successful. Go to SUMA's usage documentation for the extensive demo tour. See http://afni.nimh.nih.gov/sscc/staff/ziad/SUMA/SUMA_doc.htm)

Errors encountered while compiling or running SUMA:

These are error messages encountered when compiling or executing SUMA (for the first time). If you encounter new errors contact Ziad S. Saad.

GLX missing: (run time error)

Message:

Xlib: extension “GLX” missing on display “:0.0”

Error: no good visual

Cause:

You do not have the GLX module loaded. See section GLX for the system you're using.

No Xm/Form.h, Xm/Frame.h: (compile time error)

Message (excerpts):

SUMA_SVmanip.c:4:49: Xm/Form.h: No such file or directory

SUMA_SVmanip.c:5:50: Xm/Frame.h: No such file or directory

make[1]: *** [SUMA_SVmanip.o] Error 1

Cause:

You are missing Motif headers. Install Motif to fix this problem.

GlwDrawingAreaWidgetClass undefined: (compile time error)

Message:

LibSUMA.a (SUMA_display.o): In function `SUMA_X_SurfaceViewer_Create':

SUMA_display.o: undefined reference to `glwDrawingAreaWidgetClass'

Cause:

You do not have libMesaGLw.a

The paths specified in SUMA_LINK_PATH in Makefile need to be modified to point to libMesaGLw.a

If you do not have libMesaGLw.a on your computer you will have to install Mesa.

cannot find -lMesaGLw: (link time error)

Message:

/usr/bin/ld: cannot find -lMesaGLw

Cause:

You do not have Mesa on your computer.

You need to add the proper link paths (SUMA_LINK_PATH variable in Makefile) to point to the where the Mesa libraries are located.

Version `GLIBC_2.2' not found

Message:

/lib/libc.so.6: version `GLIBC_2.2' not found (required by ./suma)

Cause:

The binaries you are using have been compiled with glibc libraries incompatible with the ones installed your system. If you find no binaries with the proper glibc you’ll have to compile your own.

Could not open /dev/nvidiactl

Message:

Error: Could not open /dev/nvidiactl because the permissions

are too resticitive. Please see the FREQUENTLY ASKED QUESTIONS

section of /usr/share/doc/NVIDIA_GLX-1.0/README for steps

to correct.

Cause:

I don't know why the permissions are set as such but we fixed the problem by giving everyone read permissions for /dev/nvidiactl

Crash of X-server

Message:

None whatsoever, it's the quickest way known to mankind to end your X session. This only happened on some linux systems.

Cause:

Hard to tell since the X server should not crash, bad blood suspected between some of the GL libraries, Graphics Cards and their drivers, and the window manager.

Known fixes (try some):

Install the latest version of your card's driver.

Try a different window manager.

Install XFree86.4.2 and its patches.

Use a different graphics card (see X server crash with 'w' option in SUMA_doc.htm).

Blank SUMA screen

Symptoms:

Suma appears to work correctly when launched but I get nothing but a blank screen.

Cause:

For SureFit users: Your LD_LIBRARY_PATH environment variable set to point to SureFit/Caret's specific library versions is leading SUMA to an incompatible set of libraries. To solve this problem, unsetenv LD_LIBRARY_PATH in the shell you use to run SUMA.

For others: If you have LD_LIBRARY_PATH set try the solution suggested for SureFit users. If you have downloaded SUMA binaries, this problem might be caused by incompatibilities between libraries used to compile SUMA on our machines and the libraries/hardware on yours. You will need to compile SUMA on your machine to solve that problem. See appropriate: Compiling SUMA on YOURMACHINE sections.

INSTALLATION NOTES:

Pipe command syntax:

|& is used to pipe stdout and stderr output to a logfile via the program tee. This redirection syntax works for csh and tcsh shells. For other shells the redirection syntax is different.

Using ldd to determine libraries needed by SUMA:

The command ldd will tell you which shared libraries are required by a particular program. You can use it to determine which libraries SUMA would be using and whether these libraries are found on your system.

For example:

> tar -xf SUMA_Linux-NoGLStatic.tar

> ldd ./suma

outputs:

libGLw.so.1 => not found

libGLU.so.1 => /usr/X11R6/lib/libGLU.so.1 (0x00130000)

libGL.so.1 => /usr/X11R6/lib/libGL.so.1 (0x00152000)

libXmu.so.6 => /usr/X11R6/lib/libXmu.so.6 (0x00172000)

You can see that libGLw.so is missing on this system but all the other libraries are present. In this case, we should use the binaries in SUMA_Linux-GlwStatic.tar which do not need GLw.so

Using Makefiles that do not have SUMA options:

If the Makefile that works for your computer does not have SUMA options, copy them from the Makefile that most closely fits your machine and try compiling. SUMA options are grouped together towards the end of the Makefiles. You may have to change SUMA_INCLUDE_PATH and SUMA_LINK_LIB to point to the compiler and linker to the location of GL header files and libraries.

Why not link SUMA to static libraries ?

This seems like a bad idea. For example, libGL.a is required for compilation and the nvidia driver hangs up if libGL.a is used. Some of OpenGL's libraries are hardware dependent.

What do the variables in Makefile mean ?

This only covers variables that pertain to SUMA and that the user may need to modify

INSTALLDIR: Specifies the directory where the compiled programs will be installed. It is customary to put AFNI and its auxiliary programs under /SOMETHING/abin where SOMETHING is a path accessible to different users.

SUMA_INCLUDE_PATH: Specifies path for finding header (.h) files. If you have your .h files installed in directories other than those provided in the Makefile you will need to add them manually. For example, let's assume that your motif header files are under /usr/special/ directory then you should append -I/usr/special to the current value of SUMA_INCLUDE_PATH.

SUMA_LINK_PATH: Specifies path for finding link-time libraries. Modification is similar to that in SUMA_INCLUDE_PATH, with -L instead of -I.

SUMA_LINK_LIB: Specifies the libraries that will be linked to by SUMA. You should not have to modify this line.

How to install nVIDIA drivers for linux ?

This is an example of what I had to do on my linux/redhat7.1 computer. Consult nVidia's website for more current info.

>linux> rpm -rebuild NVIDIA_kernel-1.0-2802.src.rpm

>linux> rpm -i /usr/src/redhat/RPMS/i386/NVIDIA_kernel-1.0-2802.i386.rpm

>linux> rpm -i NVIDIA_GLX-1.0-2802.i386.rpm

if you're reinstalling the driver because you reinstalled Mesa, all you need is:

>linux> rpm -i --force NVIDIA_GLX-1.0-2802.i386.rpm

More detailed documentation in /usr/share/doc/NVIDIA_GLX-1.0/README

tee:

This program echoes output to the screen and to a file. We're using tee to log make's messages when compiling SUMA. If your compilation fails doggedly, send us the log file and we'll help you fix the problem.

glibc and RedHat versions:

The files /etc/redhat-release and /proc/version contain information on the redhat and glibc versions installed on your machine. Also try the commands uname –a and rpm –q glibc

Compiling SUMA on Linux

If none of the available binary executables are appropriate or if you need to modify or utilize SUMA's code you will need to compile it on your computer. To compile SUMA you need Motif, GLX support and Mesa (OpenGL) libraries. All these libraries are available in open source format and may already be installed on your computer. If you have these libraries, or if you have a relatively recent Linux computer with an OpenGL graphics card (such as the nVIDIA cards), or if you are just plain impatient, then proceed to the section Installing SUMA.

Requirements:

Hardware:

SUMA has been compiled and tested on Linux computers. I highly recommend having an OpenGL graphics card (~$200) since it will give you real time surface manipulation. SUMA has been tested on the following platforms:

ASL 2x1Ghz/1Gb RAM, redhat 7.1, GeForce3 graphics card (works real fast)

IBM thinkpad T20 laptop 800Mhz/256Mb RAM, mandrake 8.0 (works but slow graphics)

Software:

GLX:

You must have a Linux kernel and a graphics card that support GLX which is an open-source protocol developed by SGI for sending 3D graphics commands over an X client-server connection. The program glxinfo will tell you if the GLX module is loaded or not. If you do not have glxinfo on your computer then you probably don't have GLX extension support. If glxinfo returns with messages such as:

Xlib: extension “GLX” missing on display “:0.0”

you will need to add (or uncomment) the line Load "glx" in your in /etc/X11/XF86Config-4 file and restart X.

XFree86 versions 4.x (http://www.xfree86.org) now include an implementation of the GLX extension. Most 21^st century versions of Linux come with XFree86 but you may have to load the GLX module if that's not already done. To do so, add the line: Load "glx" (if it does not already exist) in /etc/X11/XF86Config-4 and restart X.

NOTE: Do not add this line unless you have the glx modules installed, otherwise, X will not start up.

Here's an example of my Module section in /etc/X11/XF86Config-4

Section "Module"

Load "dbe"

#Below is the line needed for loading GLX

Load "glx"

Load "xie"

EndSection

Motif:

You only need the motif libXm library to compile SUMA. This library should be present on new linux systems. If you don't have it you will need to install motif. Run time libraries are what you need but it won't hurt to install the entire package. This would allow you to compile AFNI on your machine if need be. (http://www.openmotif.org/download/getem.php).

Below are sample instructions for installing Open Motif rpm for linux x86 installation.

Runtime Package:

Linux x86: openmotif-2.2.2-3_ICS.i386.rpm

Development Package:

Linux x86: openmotif-devel-2.2.2-3_ICS.i386.rpm

As su (root) execute the following commands:

>linux- su> rpm -i openmotif-2.2.2-3_ICS.i386.rpm

>linux- su> rpm -i openmotif-devel-2.2.2-3_ICS.i386.rpm

NOTE: You must install the Runtime package above before installing the Development Package.

Both runtime and development packages should be installed.

Mesa (OpenGL):

SUMA needs GL version 1.2 or newer. If you have openGL installed on your machine on you can proceed to Compiling SUMA. Do not install Mesa if you have working versions of libGL, libGLU and libGLw or libMesaGLw on your machines, you should be able to use the binaries we are distributing. We have, at times, experienced problems with multiple Mesa libraries existing simultaneously on the same system so take care to note which lib*GL* libraries exist on your system and where they reside before installing the new mesa.

NOTE: Some graphics cards, like nVIDIA, replace some of Mesa's libraries and use their own GLX extensions. If you have such cards, odds are that you will not need to install GLX module or Mesa. However, if you do, you may have to reinstate the changes needed by the card's driver. If you have an rpm for the driver, just force it to run again with the rpm option --force. See notes below.

It's easiest to install Mesa using rpm and Mesa-3.4 is good enough. For the curious, we've documented our experience with installing Mesa 4.0.2 from source distribution.

Download Mesa Libraries AND Demos from www.sourceforge.net. We have included Mesa-4.0.2 distribution (http://afni.nimh.nih.gov/sscc/staff/ziad/SUMA/Mesa) for convenience. Perform the following commands for building Mesa.

> tar -xf MesaLib-4.0.2.tar

> tar -xf MesaDemos-4.0.2.tar

> cd Mesa-4.0.2

> ./configure --prefix=/usr (for more help see ./Mesa-4.0.2/docs/INSTALL)

> make

> make install

> make check (makes sure installation went OK)

> cd widgets-mesa

> ./configure --prefix=/usr --with-motif

> make (this one might fail sometimes. If it does, follow the next 5 steps, otherwise skip them)

> cd src

> make libMesaGLwM.a (these may be there but no harm in running commands)

> make libMesaGLw.a

> make install

> cd ..

> make install (this one might fail when installing the man pages but that should not be a problem as long as it libMesaGLw.a and libMesaGLwM.a libraries were installed)

AFNI:

You need to have afni v. 2.49a or newer installed on your machine. Download the latest version of afni before installing SUMA (http://afni.nimh.nih.gov/afni/afni_howtoget.shtml)

Compiling and installing SUMA:

Downloading SUMA

SUMA is included in AFNI's source code distribution afni_src.tgz found at http://afni.nimh.nih.gov/afni/AFNI98/afni_src.tgz (right clickàsave as to download).

NOTE: Do not left click on the tgz files as this would open the binary file in your browser. Use the right mouse button à save as for saving the file to disk.

Compiling SUMA

> tar xzvf afni_src.tgz

> cd afni_src

If you have your own AFNI Makefile, read this first.

>linux> cp Makefile.linux2 Makefile

We have only included the options for making SUMA in the Makefiles that we could test. If the suggested Makefile does not work on your machine and you need to use other Makefiles from the afni distribution, you will need to add the lines from the section titled “For suma” in the Makefile.linux2.

You might want to edit the INSTALLDIR variable in Makefile, it determines where suma will be installed. You can always move the compiled program manually with the mv command. In the linux example presented here, the INSTALLDIR is set to ./linux2 where the afni programs are located. NOTE: Make sure you have write permission in INSTALLDIR).

> make suma |& tee -a Make_suma_log

Note: If you're not using csh or tcsh shells, read this.

(This will rebuild libmri.a and librickr.a which will take a couple of minutes before building suma. If make succeeds then you should find suma in INSTALLDIR.)

To test suma, install the demo data set.

If compilation fails and you don't know why …

Compiling SUMA on SGI

To install SUMA on your SGI computer you will need to compile it. We may provide binaries in the future if it proves to be a workable solution. You could start by installing SUMA since you're likely to have all the required libraries.

Requirements:

Hardware:

SUMA has been compiled and tested on an SGI Octane 2x250Mhz/512 Mb, MXI graphics. It should work on any SGI.

Software:

Motif:

You must have motif installed on your computer. Motif is necessary for compiling AFNI and SUMA. Odds are you have motif libraries on your SGI.

OpenGL:

SUMA needs GL version 1.2 or newer. OpenGL is usually present on your SGI.

AFNI:

You need to have afni v. 2.49a or newer installed on your machine. If you do not want to compile the entire AFNI package, download the latest version of afni before installing SUMA from http://afni.nimh.nih.gov/afni/afni_howtoget.shtml. Otherwise, you can compile it simultaneously with SUMA.

Compiling and Installing SUMA:

Downloading SUMA

SUMA is included in AFNI's source code distribution afni_src.tgz found at http://afni.nimh.nih.gov/afni/AFNI98/afni_src.tgz (right clickàsave as to download).

NOTE: Do not left click on the tgz files as this would open the binary file in your browser. Use the right mouse button à save as for saving the file to disk.

Compiling SUMA

> gzip -d afni_src.tgz

> tar -xvf afni_src.tgz

> cd afni_src

If you have your own AFNI Makefile, read this first.

>SGI> cp Makefile.sgi10k_6.5.gcc Makefile

We have only included the options for making SUMA in the Makefile that we could test. If the suggested Makefile does not work on your machine and you need to use other Makefiles from the afni distribution, you will need to add the lines from the section titled “For suma” in the Makefile suggested above.

You might want to edit the INSTALLDIR variable in Makefile, it determines where suma will be installed. The default is ./sgi10k_6.5. NOTE: Make sure you have write permission in INSTALLDIR).

> make suma |& tee -a Make_suma_log

Note: If you're not using csh or tcsh shells, read this.

(This will rebuild libmri.a and librickr.a which will take a couple of minutes before building suma. If make succeeds then you should find suma in INSTALLDIR. )

To test suma, install the demo data set.

If compilation fails and you don't know why …

Compiling SUMA on Mac OSX:

SUMA can be installed on Mac OSX systems. You will need Xfree86, Motif (not required) and Mesa installed. See the detailed help for installing AFNI at http://afni.nimh.nih.gov/afni/afni_darwin.shtml. With easy to install software packages for Xfree, Motif and Mesa available at http://dryden.biol.yorku.ca/darwin.html. If you have these libraries proceed to the section Installing SUMA.

Requirements:

Hardware:

SUMA has been compiled and tested on an imac G4 512Mb RAM with the standard graphics card. With the onboard graphics card, rendering is very slow.

Software:

GLX:

GLX is supported by MacOSX's Xfree86-4. The program glxinfo will tell you if the GLX module is loaded or not. If you do not have glxinfo on your computer then you probably don't have GLX extension support. If glxinfo returns with messages such as:

Xlib: extension “GLX” missing on display “:0.0”

you will need to load GLX.

Motif:

You do not need motif. But it does not hurt to have it installed along with Mesa. See the instructions provided under Install SUMA on Mac OSX for installing Motif.

Mesa (OpenGL):

SUMA needs GL version 1.2 or newer. If you have openGL installed on your machine on you can proceed to Compiling SUMA. See the instructions provided under Install SUMA on Mac OSX for installing Mesa.

AFNI:

You need to have afni v. 2.49a or newer installed on your machine. See instructions for installing AFNI on MacOSX at http://afni.nimh.nih.gov/afni/afni_darwin.shtml.

Compiling and Installing SUMA:

Downloading SUMA

SUMA is included in AFNI's source code distribution afni_src.tgz found at http://afni.nimh.nih.gov/afni/AFNI98/afni_src.tgz (right clickàsave as to download).

NOTE: Do not left click on the tgz files as this would open the binary file in your browser. Use the right mouse button à save as for saving the file to disk.

Compiling SUMA

> tar xzvf afni_src.tgz

> cd afni_src

If you have your own AFNI Makefile, read this first.

>Mac> cp Makefile.macosx_10.1 Makefile

You might want to edit the INSTALLDIR variable in Makefile, it determines where suma will be installed. You can always move the compile program manually with the mv command. The default directory is ./macosx_10.1. NOTE: Make sure you have write permission in INSTALLDIR).

> make suma |& tee -a Make_suma_log

Note: If you're not using csh or tcsh shells, read this.

(This will rebuild libmri.a and librickr.a which will take a couple of minutes before building suma. If make succeeds then you should find suma in INSTALLDIR. )

To test suma, install the demo data set.

If compilation fails and you don't know why …

Compiling SUMA on SUN:

To install SUMA on SUN SOLARIS systems computer you will need to compile it. We may provide binaries in the future if it proves to be a workable solution. You could start by installing SUMA since you're likely to have all the required libraries.

Requirements:

Hardware:

SUMA has been compiled and tested on a SUN Sparc5 SOLARIS. It should work on an SUN with OpenGL libraries.

Software:

Motif:

You must have motif installed on your computer. Motif is necessary for compiling AFNI and SUMA. Odds are you have motif libraries on your SUN.

OpenGL:

SUMA needs GL version 1.2 or newer. OpenGL is usually present on SUN.

AFNI:

Compiling and Installing SUMA:

Downloading SUMA

SUMA is included in AFNI's source code distribution afni_src.tgz found at http://afni.nimh.nih.gov/afni/AFNI98/afni_src.tgz (right clickàsave as to download).

NOTE: Do not left click on the tgz files as this would open the binary file in your browser. Use the right mouse button à save as for saving the file to disk.

Compiling SUMA

> gzip -d afni_src.tgz

> tar -xvf afni_src.tgz

> cd afni_src

If you have your own AFNI Makefile, read this first.

>SUN> cp Makefile.solaris28_gcc Makefile

You might want to edit the INSTALLDIR variable in Makefile, it determines where suma will be installed. The default is ./sgi10k_6.5. NOTE: Make sure you have write permission in INSTALLDIR).

> make suma |& tee -a Make_suma_log

Note: If you're not using csh or tcsh shells, read this.

(This will rebuild libmri.a and librickr.a which will take a couple of minutes before building suma. If make succeeds then you should find suma in INSTALLDIR. )

To test suma, install the demo data set.

If compilation fails and you don't know why …

Authors & Contributors:

AFNI & SUMA are being developed at the Statistical & Scientific Computing Core, NIMH by:

Patricia P. Christidis christip@codon.nih.gov

Robert W. Cox rwcox@codon.nih.gov

Rick R. Reynolds rickr@codon.nih.gov

Ziad S. Saad ziad@nih.gov

Additional help from:

Michael S. Beauchamp mbeaucha@nih.gov

Shruti (W.) Japee shruti@codon.nih.gov

MRI Demo Data from:

Hauke Heekeren hauke@nih.gov

Sean Marrett marrett@nih.gov

Installing and viewing the demo data set

SureFit demo:

No Xm/Form.h, Xm/Frame.h: (compile time error)

GlwDrawingAreaWidgetClass undefined: (compile time error)

cannot find -lMesaGLw: (link time error)

Could not open /dev/nvidiactl

INSTALLATION NOTES:

Pipe command syntax:

Using ldd to determine libraries needed by SUMA:

Using Makefiles that do not have SUMA options:

Why not link SUMA to static libraries ?

What do the variables in Makefile mean ?

How to install nVIDIA drivers for linux ?

tee:

glibc and RedHat versions:

Compiling SUMA on Linux

GLX:

Motif:

Mesa (OpenGL):

AFNI:

Compiling and installing SUMA:

Compiling SUMA on SGI

Motif:

OpenGL:

AFNI:

Compiling and Installing SUMA:

Compiling SUMA on Mac OSX:

GLX:

Motif:

Mesa (OpenGL):

AFNI:

Compiling and Installing SUMA:

Compiling SUMA on SUN:

Motif:

OpenGL:

AFNI:

Compiling and Installing SUMA:

Authors & Contributors:

Table of Contents: