| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| [wiki:Self:FsTutorial top] | [wiki:Self:FsTutorial/Overview previous] | [wiki:Self:FsTutorial/MorphAndRecon next] | [wiki:Self:DownloadAndInstall top] | [wiki:Self:Installation previous] | [wiki:Self:SetupConfiguration next] |
| Line 3: | Line 3: |
| == FreeSurfer Tutorial: Installation and Setup == | = FreeSurfer Mac OS X Installation and Setup = |
| Line 6: | Line 6: |
|
=== 1.0 Downloading software === |
|
| Line 13: | Line 11: |
| If it is not present it can be downloaded from [ftp://surfer.nmr.mgh.harvard.edu/pub/dist/X11User-Darwin.dmg ftp://surfer.nmr.mgh.harvard.edu/pub/dist/X11User-Darwin.dmg]. To launch a X terminal window, start X11 by double clicking on it in the Finder, and Terminal can be found under Applications. A new terminal can also be opened by pressing Apple-N while X11 is the primary application. | If it is not present it can be downloaded from [https://surfer.nmr.mgh.harvard.edu/pub/dist/X11User-Darwin.dmg https://surfer.nmr.mgh.harvard.edu/pub/dist/X11User-Darwin.dmg]. Intel Mac users will also need to install [https://surfer.nmr.mgh.harvard.edu/pub/dist/X11Update2006.dmg https://surfer.nmr.mgh.harvard.edu/pub/dist/X11Update2006.dmg] to avoid 'GLX' errors. To launch a X terminal window, start X11 by double clicking on it in the Finder, and the Terminal application can be found under Applications menu item on the top left of the screen. A new terminal can also be opened by pressing Apple-N while X11 is the primary application. Be sure not to confuse the X11 Terminal application with Apple's Terminal application, which does not directly support X11 applications (such as FreeSurfer's tkmedit, tksurfer and tkregister). |
| Line 15: | Line 13: |
| The FreeSurfer software is distributed through the NMR ftp site. Look for the latest version at [ftp://surfer.nmr.mgh.harvard.edu/pub/dist/ ftp://surfer.nmr.mgh.harvard.edu/pub/dist/] and save freesurfer-Darwin-tiger-full.dmg to your local machine. It contains the FreeSurfer binaries, support software, and a sample data set, and may take a few minutes to download even on a fast connection. | The FreeSurfer software is distributed through the NMR download site. Look [wiki:Self:Download here for the 'tiger' download], saving freesurfer-Darwin-tiger-<release>-full.dmg to your local machine. It contains the FreeSurfer binaries, support software, and a sample data set, and may take a few minutes to download even on a fast connection. |
| Line 19: | Line 17: |
| === 2.0 Installing software === | |
| Line 38: | Line 35: |
|
It is best to perform the setup described at this point in time (that is, add the lines to your .cshrc or .bashrc file), although you can perform this later if you want. |
|
| Line 46: | Line 45: |
| Click on '''Agree''', and the next screen will appear. Select where to install the software. The directory /Users/Shared on the selected disk will be used. | Click on '''Agree''', and the next screen will appear. Select where to install the software. The directory /Applications on the selected disk will be used. If you wish to install to a different directory, click on '''Choose''' and select an alternate installation location. |
| Line 48: | Line 47: |
| ## attachment:install-9selectdestination.jpg | attachment:install-9selectdestination.jpg |
| Line 54: | Line 53: |
| Click on '''Continue''' to confirm the disk selection. From the next screen, the default is to click on '''Upgrade''' for a simple installation of all packages in the archive: | Click on '''Continue''' to confirm the disk selection. |
| Line 58: | Line 57: |
| To customize the installation, click on '''Customize''' and this screen will appear, allowing selection of packages to install: | ## To customize the installation, click on '''Customize''' and this screen will appear, allowing selection of packages to install: |
| Line 60: | Line 59: |
| attachment:install-12custominstall.jpg | ## attachment:install-12custominstall.jpg |
| Line 62: | Line 61: |
| If not all of the packages are selectable, check in the directory /Library/Receipts for directories matching the package names. The operating system will compare the new installation against any old installations, and will prevent upgrades if the version of the package being installed is older than the one currently installed. Remove the receipt directory to reinstall a new version of the desired software packages and restart the installer by double clicking on the mpkg. | ## If not all of the packages are selectable, check in the directory /Library/Receipts for directories matching the package names. The operating system will compare the ## new installation against any old installations, and will prevent upgrades if the version of the package being installed is older than the one currently installed. Remove ## the receipt directory to reinstall a new version of the desired software packages and restart the installer by double clicking on the mpkg. |
| Line 64: | Line 63: |
| Click on '''Install''' and packages will begin to be installed on the designated hard drive. | Click on '''Install''' and the package will begin to be installed on the designated hard drive. |
| Line 80: | Line 79: |
| If you encounter errors during the installation, while still in the Installer, and Installer is still the primary application, click the '''Window -> Installer Log''' menu item to show the error log to see why installation failed. A possible error is the failure to write to the /Library/Receipts directory. This can occur if installing without Admin privileges, and the error can be safely ignored, as the Freesurfer package was installed to the /Users/Shared directory, which does not require Admin privileges to write files. Freesurfer will operate properly. | If you encounter errors during the installation, while still in the Installer, and Installer is still the primary application, click the '''Window -> Installer Log''' menu item to show the error log to see why installation failed. |
| Line 82: | Line 81: |
| Otherwise, click on '''Close''' to exit the installer and begin setting up the environment. | Otherwise, click on '''Close''' to exit the installer. |
| Line 84: | Line 83: |
|
=== 3.0 Setting up environment === The read-me screen of the installer provides directions on setting up the environment to allow running FreeSurfer, and this is reviewed next. ## attachment:install-6readme.jpg Usage of C shell (csh) or enhanced C shell (tcsh) is recommended. The shell type on your system can be checked by typing '''ps''' at the command line in an X terminal window. If csh or tcsh does not appear as one of the processes in the right hand column of output, the default shell must be changed to csh or tcsh. Otherwise, explicitly launch csh or tcsh before attempting to go further. To explicitly launch csh or tcsh (tcsh is recommended), simply enter the following command in an X terminal window: {{{ tcsh }}} The prompt may change, and some login files may not be run in the new shell environment. See the man pages for tcsh for details. If you do not have a preference for a particular shell, the default shell under Mac OS X can be permanently switched from bash to tcsh by typing the following: {{{ chsh -s /bin/tcsh }}} The file freesurfer/SetUpFreeSurfer.csh is a csh (C-shell) script that will configure the environment so that FreeSurfer can be used. It sets a few environment variables, sources other csh scripts to set up support libraries, and performs some checks that need to be passed before FreeSurfer can start. This file needs to be sourced before running any FreeSurfer binaries. This can be done manually via typing the following command in an X terminal window: {{{ source /Users/Shared/freesurfer/SetUpFreeSurfer.csh }}} Alternately, the resource file for the shell can be configured to source the file automatically each time the shell is started. In the home directory of the user who will be running FreeSurfer binaries, edit the file '''.cshrc''' if C-shell will be used, or '''.tcshrc''' for enhanced C-shell, to include the line: {{{ source /Users/Shared/freesurfer/SetUpFreeSurfer.csh }}} A sample subject directory is provided with the full installation, in /Users/Shared/freesurfer/subjects. If custom subject directories are created using mksubjectdirs or a different sample data set is used, let FreeSurfer know where to look by inserting the following line before the source command above: {{{ setenv SUBJECTS_DIR [path to subject directory] }}} Make sure to use C shell (csh) or enhanced C shell (tcsh). This can be checked by typing '''ps''' at the command line in an X terminal window. If csh or tcsh does not appear as one of the processes in the right hand column of output, the default shell must be changed to csh or tcsh. Otherwise, explicitly launch csh or tcsh before attempting to go further. To explicitly launch csh or tcsh (tcsh is recommended), simply enter the following command in an X terminal window: {{{ tcsh }}} The prompt may change, and some login files may not be run in the new shell environment. See the man pages for tcsh for details. As the shell starts up, messages are printed out showing the environment variables that have been set by the configuration scripts. The following example shows a case where the SUBJECTS_DIR has been set to something other than the default: {{{ Setting up environment for FreeSurfer/FS-FAST FREESURFER_HOME /Users/Shared/freesurfer FSFAST_HOME /Users/Shared/freesurfer/fsfast SUBJECTS_DIR /Users/Shared/freesurfer/subjects FUNCTIONALS_DIR /Users/Shared/freesurfer/sessions MINC_BIN_DIR /Users/Shared/freesurfer/lib/mni/bin MINC_LIB_DIR /Users/Shared/freesurfer/lib/mni/lib QTDIR /Users/Shared/freesurfer/lib/qt LIBS_DIR /Users/Shared/freesurfer/lib/misc }}} If any warnings appear, it's usually safe to ignore them, but make sure that they are not stating that a file or directory that should exist cannot be found. If any error messages appear, check that the installation process was successfully completed. === 4.0 Practice data === A public distribution data set is available to run the tutorials. It contains 40 subjects, and occupies about 21G of disk-space. The file is available from the [ftp://surfer.nmr.mgh.harvard.edu/pub/dist distribution site], and is called [ftp://surfer.nmr.mgh.harvard.edu/pub/dist/buckner_public_distribution.tar.gz buckner_public_distribution.tar.gz]. Once the file is downloaded, move the file to the $FREESURFER_HOME/subjects directory, and uncompress and install with the following command: {{{ tar zxvf buckner_public_distribution.tar.gz }}} The downloaded file can then be deleted. To setup the environment variables SUBJECTS_DIR and SUBJECTS to point to this data, type the following command or include in your .cshrc or .tcshrc file: {{{ source $FREESURFER_HOME/subjects/buckner_public_distribution/sample_group_study/scripts/subjects.csh }}} |
[wiki:Self:SetupConfiguration Setup and configuration of the environment is described next.] |
[wiki:DownloadAndInstall top] | [wiki:Installation previous] | [wiki:SetupConfiguration next]
FreeSurfer Mac OS X Installation and Setup
This page details how to install FreeSurfer on a Mac OS X machine, from download to set up. The full installation package provided by MGH includes support libraries and a sample data set.
Prerequisite: The Max OS X machine must have the X11 package installed before installing FreeSurfer. It will appear in the Finder under Applications -> Utilities -> X11.
attachment:install-x.jpg
If it is not present it can be downloaded from [https://surfer.nmr.mgh.harvard.edu/pub/dist/X11User-Darwin.dmg https://surfer.nmr.mgh.harvard.edu/pub/dist/X11User-Darwin.dmg]. Intel Mac users will also need to install [https://surfer.nmr.mgh.harvard.edu/pub/dist/X11Update2006.dmg https://surfer.nmr.mgh.harvard.edu/pub/dist/X11Update2006.dmg] to avoid 'GLX' errors. To launch a X terminal window, start X11 by double clicking on it in the Finder, and the Terminal application can be found under Applications menu item on the top left of the screen. A new terminal can also be opened by pressing Apple-N while X11 is the primary application. Be sure not to confuse the X11 Terminal application with Apple's Terminal application, which does not directly support X11 applications (such as FreeSurfer's tkmedit, tksurfer and tkregister).
The FreeSurfer software is distributed through the NMR download site. Look [wiki:Download here for the 'tiger' download], saving freesurfer-Darwin-tiger-<release>-full.dmg to your local machine. It contains the FreeSurfer binaries, support software, and a sample data set, and may take a few minutes to download even on a fast connection.
Once the dmg has been downloaded, double click on it in the Finder to expand the package, which will result in the following:
attachment:install-4mpkg.jpg
Double click on the mpkg and the installation wizard will launch as a guide through the set up.
After the package integrity has been verified, the introductory screen will appear.
attachment:install-5intro.jpg
Click on Continue, and read the explanatory text on the Read Me screen, as it contains information useful during the next stage of the installation:
attachment:install-6readme.jpg
It is best to perform the setup described at this point in time (that is, add the lines to your .cshrc or .bashrc file), although you can perform this later if you want.
Click on Continue, and read the end user license agreement, scrolling down using the bar along the right side of the window.
Click on Continue and a window will appear with the option to agree or disagree to the license.
Click on Agree, and the next screen will appear. Select where to install the software. The directory /Applications on the selected disk will be used. If you wish to install to a different directory, click on Choose and select an alternate installation location.
attachment:install-9selectdestination.jpg
Click on the hard drive on which to install the software; that icon will highlight (if it has not been already selected, which may occur if only one disk is installed).
Click on Continue to confirm the disk selection.
attachment:install-11easyinstall.jpg
Click on Install and the package will begin to be installed on the designated hard drive.
The installer may then optimize the hard drive for performance.
Once the optimization is finished, the installation process is successfully concluded:
attachment:install-19success.jpg
If you encounter errors during the installation, while still in the Installer, and Installer is still the primary application, click the Window -> Installer Log menu item to show the error log to see why installation failed.
Otherwise, click on Close to exit the installer.
[wiki:SetupConfiguration Setup and configuration of the environment is described next.]