|
Size: 9742
Comment:
|
Size: 6437
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| [wiki:Self:FreeSurferWiki top] | [wiki:Self:Installation previous] | [[DownloadAndInstall|top]] | [[Installation|previous]] | [[SetupConfiguration|next]] |
| Line 3: | Line 3: |
| == FreeSurfer Mac OS X Installation and Setup == | '''Index''' <<TableOfContents>> |
| Line 5: | Line 5: |
| 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. | = Installation = '''''Important Note for macOS users:''' macOS machines require the installation of [[http://xquartz.macosforge.org/downloads/SL/XQuartz-2.7.6.dmg|XQuartz 2.7.6]].'' ---- |
| Line 7: | Line 9: |
| === 1.0 Downloading software === | === Installing XQuartz === |
| Line 9: | Line 11: |
| 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'''. | |
| Line 11: | Line 12: |
| attachment:install-x.jpg | To see what version of macOS you have, click '''Apple -> About This Mac'''. You should see something similar to the image below: |
| Line 13: | Line 14: |
| 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. | {{attachment:macversion.png}} |
| Line 15: | Line 16: |
| 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. | To see what version of XQuartz you have, click '''Applications -> Utilities -> XQuartz'''. Then '''X11 -> About X11''' |
| Line 17: | Line 18: |
| ## attachment:install-2filelisting.jpg | |
| Line 19: | Line 19: |
| === 2.0 Installing software === Once the '''dmg''' has been downloaded, double click on it in the Finder to expand the package, which will result in the following: |
{{attachment:xqfinder.png}} {{attachment:xqversion.png}} |
| Line 22: | Line 22: |
| attachment:install-4mpkg.jpg | |
| Line 24: | Line 23: |
| Double click on the '''mpkg''' and the installation wizard will launch as a guide through the set up. | If necessary, download the XQuartz installation package and double click it to install. * [[http://xquartz.macosforge.org/downloads/SL/XQuartz-2.7.5.dmg|XQuartz 2.7.5]] (macOS versions 10.6 - 10.9) * [[http://xquartz.macosforge.org/downloads/SL/XQuartz-2.7.6.dmg|XQuartz 2.7.6]] (macOS versions 10.10 and higher) ---- === Installing FreeSurfer === Download the !FreeSurfer installation package from [[DownloadAndInstall|this page]]. Double click the dmg then double click the '''freesurfer-Darwin-full.pkg''' to launch the installation wizard: {{attachment:install-5mpkg.png}} If you get this error: {{attachment:install_error.png}} Then you need to adjust your security settings to allow applications from 3rd party developers to be installed. To do this go to '''Apple -> System Preferences -> Security & Privacy -> General'''. Click the lock on the bottom left to make changes and under '''Allow applications downloaded from:''' select '''Anywhere'''. {{attachment:allow_anywhere.png}} |
| Line 27: | Line 45: |
| Line 30: | Line 47: |
| After the package integrity has been verified, the introductory screen will appear. | After the package integrity has been verified, the introductory screen will appear. Click on '''Continue''': |
| Line 32: | Line 49: |
| attachment:install-5intro.jpg | {{attachment:install-5intro.jpg}} |
| Line 34: | Line 51: |
| 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: | Next is the Read Me window. Click on '''Continue''': |
| Line 36: | Line 53: |
| attachment:install-6readme.jpg | {{attachment:readme1.png}} |
| Line 38: | Line 55: |
| Click on '''Continue''', and read the end user license agreement, scrolling down using the bar along the right side of the window. | Next is the Software License Agreement window. Click on '''Continue''': |
| Line 40: | Line 57: |
| ## attachment:install-7license.jpg | {{attachment:SLA.png}} |
| Line 42: | Line 59: |
| Click on '''Continue''' and a window will appear with the option to agree or disagree to the license. | Next is the Destination Select window. Click '''Change Install Location...''' to change the default installation disk and folder (/Applications/freesurfer). Or click '''Install''' to go with default: |
| Line 44: | Line 61: |
| ## attachment:install-8licenseclick.jpg | {{attachment:install_location.png}} |
| Line 46: | Line 63: |
| 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. | You may need to enter you password. The installation process will begin to write files and will take a few minutes to complete. |
| Line 48: | Line 65: |
| ## attachment:install-9selectdestination.jpg | {{attachment:successful.png}} |
| Line 50: | Line 67: |
| 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). | ----- |
| Line 52: | Line 69: |
| ## attachment:install-10destinationselected.jpg | = Setup and Configuration = |
| Line 54: | Line 71: |
| 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: | To begin using freesurfer, open a terminal window. The Terminal application is found under '''Applications -> Utilities -> Terminal''': |
| Line 56: | Line 73: |
| attachment:install-11easyinstall.jpg | {{attachment:terminal.png}} |
| Line 58: | Line 75: |
| To customize the installation, click on '''Customize''' and this screen will appear, allowing selection of packages to install: | Type the following lines in the terminal window to source the freesurfer environment: |
| Line 60: | Line 77: |
| attachment:install-12custominstall.jpg 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. Click on '''Install''' and packages will begin to be installed on the designated hard drive. ## attachment:install-13procfsbins.jpg ## attachment:install-14procfssupport.jpg ## attachment:install-15procdata.jpg ## attachment:install-16procminc.jpg ## attachment:install-17procfullinst.jpg The installer may then optimize the hard drive for performance. ## attachment:install-18optimisinghd.jpg 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. 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. Otherwise, click on '''Close''' to exit the installer and begin setting up the environment. === 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: |
|
| Line 92: | Line 78: |
| 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 |
export FREESURFER_HOME=/Applications/freesurfer source $FREESURFER_HOME/SetUpFreeSurfer.sh |
| Line 101: | Line 82: |
| 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. | After you source freesurfer you should see some output similar to the window below: |
| Line 103: | Line 84: |
| This can be done manually via typing the following command in an X terminal window: | {{attachment:source_freesurfer.png}} If you use freesurfer frequently and want to avoid typing the above lines of code every time you open a terminal window, you can create a file called '''.profile''' in your home directory which contains those two line. This will cause the terminal window to automatically source freesurfer every time it is opened. At this point you are ready to begin using the freesurfer software. If you haven't done so already, [[https://surfer.nmr.mgh.harvard.edu/registration.html|obtain a license]], and copy the license.txt file into your $FREESURFER_HOME (Applications/freesurfer) directory. ----- = Testing Freesurfer = See the [[DownloadAndInstall#TestyourFreeSurferInstallation|this page]] for some example commands to test that !FreeSurfer is installed and running properly. = For newer Mac OS Systems = If you receive the following error when running the test_commands.sh.15 script: |
| Line 105: | Line 101: |
| 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 |
+ cd /users/hippo/lcn/tutorial_data/tutorial_data_20190918_1558/buckner_data/tutorial_subjs/group_analysis_tutorial + mris_anatomical_stats -l lh.supramarg.label -t lh.thickness -b -f 004/stats/lh.supramarg.stats 004 lh dyld: lazy symbol binding failed: Symbol not found: ___emutls_get_address Referenced from: /Applications/freesurfer/bin/../lib/gcc/lib/libgomp.1.dylib Expected in: /usr/lib/libSystem.B.dylib dyld: Symbol not found: ___emutls_get_address Referenced from: /Applications/freesurfer/bin/../lib/gcc/lib/libgomp.1.dylib Expected in: /usr/lib/libSystem.B.dylib ./test_commands.sh.15: line 368: 87124 Abort trap: 6 mris_anatomical_stats -l lh.supramarg.label -t lh.thickness -b -f 004/stats/lh.supramarg.stats 004 lh |
| Line 112: | Line 114: |
| 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: | Then, you need to install a Freeview patch to have this work with your Mac OS version. Download the patch (~33 MB) from /autofs/cluster/pubftp/dist/freesurfer/6.0.0-patch/Freeview_6_0_0_MacOS_patch.zip follow the following instructions: 1)To download the patch, follow instructions on using the ftp file exchange from [[https://surfer.nmr.mgh.harvard.edu/fswiki/FtpFileExchange|this]] wiki page. 2) Remove your existing Freeview.app application bundle by sending it to the trash (and then emptying the trash).You can also do this from the terminal by cd'ing to the top-level ./freesurfer subdirectory and then doing |
| Line 114: | Line 120: |
| setenv SUBJECTS_DIR [path to subject directory] | rm -rf Freeview.app |
| Line 117: | Line 123: |
| 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. |
3) Copy the new Freeview.app.zip to where your old Freeview.app was located and uncompress it (so it becomes the replacement Freeview.app in your current FreeSurfer installation). |
| Line 123: | Line 125: |
| 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 }}} |
4) Remove ./freesurfer/lib/gcc/lib/libgomp.1.dylib from your existing freesurfer installation. |
| Line 136: | Line 127: |
| 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. | 5) Copy the ./freesurfer/lib/gcc/lib/libgomp.1.dylib from the patch archive to /freesurfer/lib/gcc/lib in your current freesurfer installtion. |
| Line 138: | Line 129: |
| If any error messages appear, check that the installation process was successfully completed. | 6) Try running the Freeview.app and loading a volume with it. |
| Line 140: | Line 131: |
| === 4.0 Practice data === | |
| Line 142: | Line 132: |
| 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]. | |
| Line 144: | Line 133: |
| Once the file is downloaded, move the file to the $FREESURFER_HOME/subjects directory, and uncompress and install with the following command: | |
| Line 146: | Line 134: |
| {{{ tar zxvf buckner_public_distribution.tar.gz }}} |
|
| Line 150: | Line 135: |
| The downloaded file can then be deleted. | |
| Line 152: | Line 136: |
| 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: | ## Lastly, if you intend to run recon-all (the processing script which can run for 24 hours) on your mac, we recommend setting your Power Adapter Energy Settings to 'Never' sleep, otherwise recon-all will only run when you are logged-in. This is done under '''System Preferences -> Energy Saver'''. |
| Line 154: | Line 138: |
| {{{ source $FREESURFER_HOME/subjects/buckner_public_distribution/sample_group_study/scripts/subjects.csh }}} |
## {{attachment:no_sleep.png}} ## If you came from the Quick Install page, return to that [[QuickInstall|here]].<<BR>> ## Otherwise, setup and configuration of the environment is described [[SetupConfiguration_Mac|next.]] |
Index
Contents
Installation
Important Note for macOS users: macOS machines require the installation of XQuartz 2.7.6.
Installing XQuartz
To see what version of macOS you have, click Apple -> About This Mac. You should see something similar to the image below:
To see what version of XQuartz you have, click Applications -> Utilities -> XQuartz. Then X11 -> About X11
If necessary, download the XQuartz installation package and double click it to install.
XQuartz 2.7.5 (macOS versions 10.6 - 10.9)
XQuartz 2.7.6 (macOS versions 10.10 and higher)
Installing FreeSurfer
Download the FreeSurfer installation package from this page. Double click the dmg then double click the freesurfer-Darwin-full.pkg to launch the installation wizard:
If you get this error:
Then you need to adjust your security settings to allow applications from 3rd party developers to be installed. To do this go to Apple -> System Preferences -> Security & Privacy -> General. Click the lock on the bottom left to make changes and under Allow applications downloaded from: select Anywhere.
After the package integrity has been verified, the introductory screen will appear. Click on Continue:
Next is the Read Me window. Click on Continue:
Next is the Software License Agreement window. Click on Continue:
Next is the Destination Select window. Click Change Install Location... to change the default installation disk and folder (/Applications/freesurfer). Or click Install to go with default:
You may need to enter you password. The installation process will begin to write files and will take a few minutes to complete.
Setup and Configuration
To begin using freesurfer, open a terminal window. The Terminal application is found under Applications -> Utilities -> Terminal:
Type the following lines in the terminal window to source the freesurfer environment:
export FREESURFER_HOME=/Applications/freesurfer source $FREESURFER_HOME/SetUpFreeSurfer.sh
After you source freesurfer you should see some output similar to the window below:
If you use freesurfer frequently and want to avoid typing the above lines of code every time you open a terminal window, you can create a file called .profile in your home directory which contains those two line. This will cause the terminal window to automatically source freesurfer every time it is opened.
At this point you are ready to begin using the freesurfer software. If you haven't done so already, obtain a license, and copy the license.txt file into your $FREESURFER_HOME (Applications/freesurfer) directory.
Testing Freesurfer
See the this page for some example commands to test that FreeSurfer is installed and running properly.
For newer Mac OS Systems
If you receive the following error when running the test_commands.sh.15 script:
+ cd /users/hippo/lcn/tutorial_data/tutorial_data_20190918_1558/buckner_data/tutorial_subjs/group_analysis_tutorial + mris_anatomical_stats -l lh.supramarg.label -t lh.thickness -b -f 004/stats/lh.supramarg.stats 004 lh dyld: lazy symbol binding failed: Symbol not found: ___emutls_get_address Referenced from: /Applications/freesurfer/bin/../lib/gcc/lib/libgomp.1.dylib Expected in: /usr/lib/libSystem.B.dylib dyld: Symbol not found: ___emutls_get_address Referenced from: /Applications/freesurfer/bin/../lib/gcc/lib/libgomp.1.dylib Expected in: /usr/lib/libSystem.B.dylib ./test_commands.sh.15: line 368: 87124 Abort trap: 6 mris_anatomical_stats -l lh.supramarg.label -t lh.thickness -b -f 004/stats/lh.supramarg.stats 004 lh
Then, you need to install a Freeview patch to have this work with your Mac OS version. Download the patch (~33 MB) from /autofs/cluster/pubftp/dist/freesurfer/6.0.0-patch/Freeview_6_0_0_MacOS_patch.zip follow the following instructions:
1)To download the patch, follow instructions on using the ftp file exchange from this wiki page.
2) Remove your existing Freeview.app application bundle by sending it to the trash (and then emptying the trash).You can also do this from the terminal by cd'ing to the top-level ./freesurfer subdirectory and then doing
rm -rf Freeview.app
3) Copy the new Freeview.app.zip to where your old Freeview.app was located and uncompress it (so it becomes the replacement Freeview.app in your current FreeSurfer installation).
4) Remove ./freesurfer/lib/gcc/lib/libgomp.1.dylib from your existing freesurfer installation.
5) Copy the ./freesurfer/lib/gcc/lib/libgomp.1.dylib from the patch archive to /freesurfer/lib/gcc/lib in your current freesurfer installtion.
6) Try running the Freeview.app and loading a volume with it.