Diff for "Installation" - Free Surfer Wiki

⇤ ← Revision 3 as of 2005-08-11 18:18:51 →

Size: 10461

Editor: NickSchmansky

Comment:

← Revision 17 as of 2010-11-17 18:57:37 → ⇥

Size: 331

Editor: KrishSubramaniam

Comment:

Deletions are marked like this.

Additions are marked like this.

[[Navigation(children)]]

<<Navigation(children)>>

[[TableOfContents]]

= Registration =

FreeSurferRegistration

= Download =

FreeSurferDownload

= Mac OS X Installation =

FreeSurferMacOsInstall

= Linux Installation =

FreeSurferLinuxInstall

= Configuration =

FreeSurferConfiguration

= FreeSurfer Installation =

* [[LinuxInstall|Linux Installation]]

* [[MacOsInstall|Mac OS X Installation]]

== INSTALL file for FreeSurfer distribution ==
Send questions/comments to analysis-bugs@nmr.mgh.harvard.edu.

FreeSurfer is copyright (c) CorTechs, 1999. All rights reserved.

FreeSurfer is being distributed with executables for
Linux/Intel, Darwin/Mac OS X, and SunOS. This is an alpha release and
has not been extensively tested. The software is offered "as is"
without any guarantees and should not be used for clinical
applications. See license.freesurfer for additional restrictions. See
docs/license.afni for restrictions on and citations for the use of the
AFNI software package and how to cite it. See docs/license.minc for
restrictions on and citations for the use of the MINC software
package.

Note: These instructions are for installing a new distribution of
FreeSurfer. If you want to update an existing FreeSurfer distribution,
you should download the snapshot update version from:

http://surfer.nmr.mgh.harvard.edu/download.html

Instructions for updating an existing installation are at FreeSurferUpdate.

== Unpacking FreeSurfer ==

The distribution consists of the following files which can either be
downloaded from http://surfer.nmr.mgh.harvard.edu or obtained from a
CDROM.

If you downloaded the distribution, unpack the tarball with this
command:

  `tar zxvf <the-file-you-downloaded>`

This will create a directory called freesurfer, which will henceforth
be referred to as DISTDIR.

If you are getting the files from a CDROM, the top level of the CDROM
should have the following files in it. Use this directory as DISTDIR.

In DISTDIR are the following files:

  `INSTALL` -- this file [[BR]]
  `license.freesurfer` -- license agreement [[BR]]
  `freesurfer.tar.gz` -- FreeSurfer tree[[BR]]
  `talairach.tar.gz` -- MNI 305 talairach brain[[BR]]
  `minc.tar.gz` -- MNI MINC tools/binaries[[BR]]
  `bert.raw.tar.gz` -- FreeSurfer tutorial data[[BR]]
  `bert.func.tar.gz` -- FreeSurfer functional tutorial data[[BR]]
  `bert.recon.tar.gz` -- reconstructed FreeSurfer tutorial data[[BR]]
  `average7.tar.gz` -- contains average labels for checking spherical morph[[BR]]

== To install FreeSurfer from tar files ==

1. Obtain a license key from http://surfer.nmr.mgh.harvard.edu/download.html or from a previous installation. If you are using a previous installation, the license file should be freesurfer/.license.

2. cd to the directory just above where you want FreeSurfer to be installed (the ParentDir). You will need about 1G of space on this disk partition.

3. Enter the command:

     `tar xvfz DISTDIR/freesurfer.tar.gz`

This will create a directory called freesurfer.

4. The default subjects directory (the directory in which your subjects' data will be placed) is freesurfer/subjects. You may wish set to up your installation differently, e.g. if you have a large external hard drive you want to use for subject data. See below for details. Regardless, cd into your subjects directory and enter the commands:

     `tar xvfz DISTDIR/average7.tar.gz` [[BR]]
     `tar xvfz DISTDIR/bert.recon.tar.gz`

This will populate your subjects directory with 'average7', and the FS tutorial's sample data set 'bert'.

== MINC installation ==

FreeSurfer uses some of the tools developed at the Montreal Neurological Institue (MNI) (http://www.bic.mni.mcgill.ca) to align antomical volumes (using minctracc) and to compute the Talairach transform (using mritotal). You must have the MNI tools installed to be able to access this functionality through FreeSurfer.

The tools can be downloaded and installed directly from the MNI. As a service to our users, we also offer binaries for the MNI tools. Unfortunately, once the MNI binaries have been created, they will not work unless they are located in the same directory where they were compiled. Accordingly, if you want to install the binaries we supply, you will have to put them in the same place we put them. Also, perl must be in the same place as on our system.

=== To install our binaries ===

1. Create a symbolic link to your perl in the location that matches ours. Execute the following commands. Note that you may need to execute some of them with root permission; su to root, use sudo, or talk to your system administrator.

     `cd /usr`[[BR]]
     `mkdir -p pubsw/bin`[[BR]]
     `cd pubsw/bin`[[BR]]
     `ln -s `which perl` perl`[[BR]]

2. Untar the MNI binaries and place them into the proper location. Execute the following commands:

     `cd /usr/pubsw`[[BR]]
     `mkdir -p packages`[[BR]]
     `cd packages`[[BR]]
     `tar xvfz DISTDIR/minc.tar.gz`

=== Install MNI talairach subject ===

Those not using the functional stream can skip this step.

1. cd to your subjects directory and enter the following command:

     `tar xvfz DISTDIR/talairach.tar.gz`

This will create a directory called talairach.

== To configure FreeSurfer ==

1. Copy the license file into freesurfer/ and rename it to ".license" (no quotes) if necessary.

2. The file freesurfer/FreeSurferEnv.csh is a csh (c-shell) script that will configure your environment so that you can use FreeSurfer. It sets a few envrionment variables and performs some sanity checks. If you are comfortable writing shell scripts, you may wish to set up your system differently, but we recommend the following:

Create a file in your home directory called something like "SetUpFreeSurfer.csh" with the following contents:

     `# Local setup.` [[BR]]
     `setenv FREESURFER_HOME <full path to freesurfer/>`[[BR]]
[[BR]]
     `# Additional configurations will go here.`[[BR]]
[[BR]]
     `# Call configuration script.`[[BR]]
     `cd $FREESURFER_HOME`[[BR]]
     `source Free``Surfer``Env.csh`[[BR]]

The full path to your freesurfer directory should be something like:

     `/home/username/freesurfer`

2. If you wish to designate a non-default subjects directory, add the following line in the 'additional configurations' section, before 'cd $FREESURFER_HOME' is called:

     `setenv SUBJECTS_DIR <full path to subject dir>`

3. If you installed the MINC tools, then add the following lines to the additional configuration section:

     `setenv MINC_BIN_DIR /usr/pubsw/packages/mni/current/bin`[[BR]]
     `setenv MINC_LIB_DIR /usr/pubsw/packages/mni/current/lib`

If you did not install the MINC tools, then add the following line in the local setup section:

     `setenv NO_MINC`

4. If you do NOT intend to use the functional tools, then add the following line to the additional configuration section:

     `setenv NO_FSFAST`

If you do intend to use the functional tools, then add these lines to your `~/matlab/startup.m` file:

     `fsfasthome = getenv('FSFAST_HOME');` [[BR]]
     `fsfasttoolbox = sprintf('%s/toolbox',fsfasthome);` [[BR]]
     `path(path,fsfasttoolbox);` [[BR]]

5. Save the file. You will need to source this file every time you want to use Freesurfer.

6. Make sure you are using csh or tcsh. You can check by typing 'ps' at the command line. If you do not see csh or tcsh as one of the processes in the right hand column of output, you must change your default shell to csh or tcsh or explicitly launch csh or tcsh first.

To explicitly launch csh or tcsh (tcsh is recommended), simply enter the following command:

     `tcsh`

You may notice your prompt change. Note that some of your login files may not be run in the new shell environment. See the man pages for tcsh for details.

7. Source the script.

     `source Set``Up``Free``Surfer.csh`

You should see output like this:

     `Setting up enviroment for Free``Surfer/FS-FAST`[[BR]]
     `FREESURFER_HOME /home/freesurfer`[[BR]]
     `FSFAST_HOME /home/freesurfer/fsfast`[[BR]]
     `AFNI_DIR /home/freesurfer/afni`[[BR]]
     `FSL_DIR /home/freesurfer/fsl`[[BR]]
     `SUBJECTS_DIR /home/freesurfer/subjects`[[BR]]

If you see any warnings, you can probably safely ignore them, but make sure they are not notifying you that it can't find something you think should exist.

If you see any error messages, make sure you have performed the installation process properly, and that your `FREESURFER_HOME` setting is correct.

From now on, you only need to source the Set``Up``Free``Surfer.csh script once in a shell session to be able to run FreeSurfer. You may want to do this in our shell's login scripts (i.e. .cshrc or .tcshrc).

== To use FreeSurfer ==

See $FREESURFER_HOME/docs/Free``Surfer``Manual.pdf to get started.
See also http://surfer.nmr.mgh.harvard.edu/docs/
See also `recon-all -help`

== Mac OS X Notes ==

1. You may need to use the OS X minc 1.2 available from the MNI website. There are bugs in it, but MNI has promised a fix soon.

   http://www.bic.mni.mcgill.ca/software/distribution/#osx

2. You should use fink to install the additional libraries that FreeSurfer needs, such as `libtiff` and `libdl`. You can get fink from:

   http://fink.sourceforge.net

Once you've installed `fink`, there are two packages you'll need to install:

   `libtiff` [[BR]]
   `dlcompat-dev`

= FTP File Exchange =

Use `ftp surfer.nmr.mgh.harvard.edu`. Login as `anonymous` and password as `"email-address"`.

{{{
ftp surfer.nmr.mgh.harvard.edu
Connected to surfer.nmr.mgh.harvard.edu (132.183.202.158).
220 surfer.nmr.mgh.harvard.edu FTP server (Version wu-2.6.2-11.73.1) ready.
Name (surfer.nmr.mgh.harvard.edu:tosa): anonymous
331 Guest login ok, send your complete e-mail address as password.
Password:
230 Guest login ok, access restrictions apply.
Remote system type is UNIX.
Using binary mode to transfer files.

If you are getting files, then

   ftp> cd transfer/outgoing

If you are putting files, then

   ftp> cd transfer/incoming
}}}

Then go to a particular directory.

For those inside NMR center, go to `/space/outgoing` and put files in its subdirectory. You can get user transfered files from `/space/incoming`. It takes 5 minutes or so to actually see the files there after the transfer.

* [[Installation/FreeSurferVirtualImage|FreeSurfer Virtual Image Installation using VirtualBox]]

-  ⇤ ← Revision 3 as of 2005-08-11 18:18:51 → 
  Size: 10461
  Editor: NickSchmansky
  Comment:
+   ← Revision 17 as of 2010-11-17 18:57:37 → ⇥
  Size: 331
  Editor: KrishSubramaniam
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
-[[Navigation(children)]]
+<<Navigation(children)>>
 Line 3:
-[[TableOfContents]]
+[[DownloadAndInstall|top]] | [[Download|previous]] | [[SetupConfiguration|next]]
 Line 5:
-= Registration =

FreeSurferRegistration

= Download =

FreeSurferDownload

= Mac OS X Installation =

FreeSurferMacOsInstall

= Linux Installation =

FreeSurferLinuxInstall

= Configuration =

FreeSurferConfiguration
+= FreeSurfer Installation =
-Line 26:
+Line 8:
+ * [[LinuxInstall|Linux Installation]]
-Line 27:
+Line 10:
+ * [[MacOsInstall|Mac OS X Installation]]
-Line 28:
+Line 12:
-== INSTALL file for FreeSurfer distribution ==
Send questions/comments to analysis-bugs@nmr.mgh.harvard.edu.

FreeSurfer is copyright (c) CorTechs, 1999. All rights reserved.

FreeSurfer is being distributed with executables for
Linux/Intel, Darwin/Mac OS X, and SunOS. This is an alpha release and
has not been extensively tested.  The software is offered "as is"
without any guarantees and should not be used for clinical
applications. See license.freesurfer for additional restrictions. See
docs/license.afni for restrictions on and citations for the use of the
AFNI software package and how to cite it. See docs/license.minc for
restrictions on and citations for the use of the MINC software
package.


Note: These instructions are for installing a new distribution of
FreeSurfer. If you want to update an existing FreeSurfer distribution,
you should download the snapshot update version from:

http://surfer.nmr.mgh.harvard.edu/download.html

Instructions for updating an existing installation are at FreeSurferUpdate.


== Unpacking FreeSurfer ==

The distribution consists of the following files which can either be
downloaded from http://surfer.nmr.mgh.harvard.edu or obtained from a
CDROM.

If you downloaded the distribution, unpack the tarball with this
command:

  `tar zxvf <the-file-you-downloaded>`

This will create a directory called freesurfer, which will henceforth
be referred to as DISTDIR.

If you are getting the files from a CDROM, the top level of the CDROM
should have the following files in it. Use this directory as DISTDIR.

In DISTDIR are the following files:

  `INSTALL`            -- this file [[BR]]
  `license.freesurfer` -- license agreement [[BR]]
  `freesurfer.tar.gz`  -- FreeSurfer tree[[BR]]
  `talairach.tar.gz`   -- MNI 305 talairach brain[[BR]]
  `minc.tar.gz`        -- MNI MINC tools/binaries[[BR]]
  `bert.raw.tar.gz`    -- FreeSurfer tutorial data[[BR]]
  `bert.func.tar.gz`   -- FreeSurfer functional tutorial data[[BR]]
  `bert.recon.tar.gz`  -- reconstructed FreeSurfer tutorial data[[BR]]
  `average7.tar.gz`    -- contains average labels for checking spherical morph[[BR]]

== To install FreeSurfer from tar files ==

1. Obtain a license key from http://surfer.nmr.mgh.harvard.edu/download.html or from a previous installation. If you are using a previous installation, the license file should be freesurfer/.license.

2. cd to the directory just above where you want FreeSurfer to be installed (the ParentDir). You will need about 1G of space on this disk partition.

3. Enter the command:

     `tar xvfz DISTDIR/freesurfer.tar.gz`

This will create a directory called freesurfer.

4. The default subjects directory (the directory in which your subjects' data will be placed) is freesurfer/subjects. You may wish set to up your installation differently, e.g. if you have a large external hard drive you want to use for subject data. See below for details. Regardless, cd into your subjects directory and enter the commands:

     `tar xvfz DISTDIR/average7.tar.gz` [[BR]]
     `tar xvfz DISTDIR/bert.recon.tar.gz`

This will populate your subjects directory with 'average7', and the FS tutorial's sample data set 'bert'.

== MINC installation ==

FreeSurfer uses some of the tools developed at the Montreal Neurological Institue (MNI) (http://www.bic.mni.mcgill.ca) to align antomical volumes (using minctracc) and to compute the Talairach transform (using mritotal). You must have the MNI tools installed to be able to access this functionality through FreeSurfer.

The tools can be downloaded and installed directly from the MNI. As a service to our users, we also offer binaries for the MNI tools. Unfortunately, once the MNI binaries have been created, they will not work unless they are located in the same directory where they were compiled. Accordingly, if you want to install the binaries we supply, you will have to put them in the same place we put them. Also, perl must be in the same place as on our system.

=== To install our binaries ===

1. Create a symbolic link to your perl in the location that matches ours. Execute the following commands. Note that you may need to execute some of them with root permission; su to root, use sudo, or talk to your system administrator.

     `cd /usr`[[BR]]
     `mkdir -p pubsw/bin`[[BR]]
     `cd pubsw/bin`[[BR]]
     `ln -s `which perl` perl`[[BR]]
   
2. Untar the MNI binaries and place them into the proper location. Execute the following commands:
     
     `cd /usr/pubsw`[[BR]]
     `mkdir -p packages`[[BR]]
     `cd packages`[[BR]]
     `tar xvfz DISTDIR/minc.tar.gz`

=== Install MNI talairach subject ===

Those not using the functional stream can skip this step.

1. cd to your subjects directory and enter the following command:

     `tar xvfz DISTDIR/talairach.tar.gz`

This will create a directory called talairach.

== To configure FreeSurfer ==

1. Copy the license file into freesurfer/ and rename it to ".license" (no quotes) if necessary.

2. The file freesurfer/FreeSurferEnv.csh is a csh (c-shell) script that will configure your environment so that you can use FreeSurfer. It sets a few envrionment variables and performs some sanity checks. If you are comfortable writing shell scripts, you may wish to set up your system differently, but we recommend the following:

Create a file in your home directory called something like "SetUpFreeSurfer.csh" with the following contents:

     `# Local setup.` [[BR]]
     `setenv FREESURFER_HOME <full path to freesurfer/>`[[BR]]
[[BR]]
     `# Additional configurations will go here.`[[BR]]
[[BR]]
     `# Call configuration script.`[[BR]]
     `cd $FREESURFER_HOME`[[BR]]
     `source Free``Surfer``Env.csh`[[BR]]

The full path to your freesurfer directory should be something like:
     
     `/home/username/freesurfer`

2. If you wish to designate a non-default subjects directory, add the following line in the 'additional configurations' section, before 'cd $FREESURFER_HOME' is called:

     `setenv SUBJECTS_DIR <full path to subject dir>`

3. If you installed the MINC tools, then add the following lines to the additional configuration section:

     `setenv MINC_BIN_DIR /usr/pubsw/packages/mni/current/bin`[[BR]]
     `setenv MINC_LIB_DIR /usr/pubsw/packages/mni/current/lib`

If you did not install the MINC tools, then add the following line in the local setup section:

     `setenv NO_MINC`

4. If you do NOT intend to use the functional tools, then add the following line to the additional configuration section:

     `setenv NO_FSFAST`

If you do intend to use the functional tools, then add these lines to your `~/matlab/startup.m` file:

     `fsfasthome = getenv('FSFAST_HOME');` [[BR]]
     `fsfasttoolbox = sprintf('%s/toolbox',fsfasthome);` [[BR]]
     `path(path,fsfasttoolbox);` [[BR]]

5. Save the file. You will need to source this file every time you want to use Freesurfer.

6. Make sure you are using csh or tcsh. You can check by typing 'ps' at the command line. If you do not see csh or tcsh as one of the processes in the right hand column of output, you must change your default shell to csh or tcsh or explicitly launch csh or tcsh first.

To explicitly launch csh or tcsh (tcsh is recommended), simply enter the following command:

     `tcsh`

You may notice your prompt change. Note that some of your login files may not be run in the new shell environment. See the man pages for tcsh for details.

7. Source the script.

     `source Set``Up``Free``Surfer.csh`

You should see output like this:

     `Setting up enviroment for Free``Surfer/FS-FAST`[[BR]]
     `FREESURFER_HOME /home/freesurfer`[[BR]]
     `FSFAST_HOME     /home/freesurfer/fsfast`[[BR]]
     `AFNI_DIR        /home/freesurfer/afni`[[BR]]
     `FSL_DIR         /home/freesurfer/fsl`[[BR]]
     `SUBJECTS_DIR    /home/freesurfer/subjects`[[BR]]

If you see any warnings, you can probably safely ignore them, but make sure they are not notifying you that it can't find something you think should exist.

If you see any error messages, make sure you have performed the installation process properly, and that your `FREESURFER_HOME` setting is correct.

From now on, you only need to source the Set``Up``Free``Surfer.csh script once in a shell session to be able to run FreeSurfer. You may want to do this in our shell's login scripts (i.e. .cshrc or .tcshrc).

== To use FreeSurfer ==

See $FREESURFER_HOME/docs/Free``Surfer``Manual.pdf to get started.
See also http://surfer.nmr.mgh.harvard.edu/docs/
See also `recon-all -help`


== Mac OS X Notes ==

1. You may need to use the OS X minc 1.2 available from the MNI website. There are bugs in it, but MNI has promised a fix soon.

   http://www.bic.mni.mcgill.ca/software/distribution/#osx

2. You should use fink to install the additional libraries that FreeSurfer needs, such as `libtiff` and `libdl`. You can get fink from:

   http://fink.sourceforge.net

Once you've installed `fink`, there are two packages you'll need to install:

   `libtiff` [[BR]]
   `dlcompat-dev`

= FTP File Exchange =

Use `ftp surfer.nmr.mgh.harvard.edu`. Login as `anonymous` and password as `"email-address"`. 


{{{
ftp surfer.nmr.mgh.harvard.edu
Connected to surfer.nmr.mgh.harvard.edu (132.183.202.158).
220 surfer.nmr.mgh.harvard.edu FTP server (Version wu-2.6.2-11.73.1) ready.
Name (surfer.nmr.mgh.harvard.edu:tosa): anonymous
331 Guest login ok, send your complete e-mail address as password.
Password:
230 Guest login ok, access restrictions apply.
Remote system type is UNIX.
Using binary mode to transfer files.

If you are getting files, then 

   ftp> cd transfer/outgoing

If you are putting files, then

   ftp> cd transfer/incoming
}}}


Then go to a particular directory. 

For those inside NMR center, go to `/space/outgoing` and put files in its subdirectory. You can get user transfered files from `/space/incoming`. It takes 5 minutes or so to actually see the files there after the transfer.
+ * [[Installation/FreeSurferVirtualImage|FreeSurfer Virtual Image Installation using VirtualBox]]