Differences between revisions 64 and 65
Deletions are marked like this. Additions are marked like this.
Line 153: Line 153:
<<BR>><<BR>>Right click with the mouse on the desktop and select “Open Terminal”.

<<BR>>12. Some extensions have been installed in the VM to make it easier to work with. These will allow: (1) bi-directional cut and paste between the host machine and the Ubuntu linux window; (2) drag and dropping files between the host machine and the Ubuntu linux window; and (3) resizing the Ubuntu linux
window;. Change these settings while the VM is running.
<<BR>>{{attachment:Img17.1.png||height="126"}}
<<BR>>Try selecting a specific “Resize to ...” dimension available in the pull down menu. With Auto-resize set, it works on some hosts to manually resize the Ubuntu linux window by dragging on a corner to enlarge it. But this may not work with some host graphics hardware if the window is re-sized to non-standard dimensions. Re-sizing only takes effect after you login.
<<BR>>{{attachment:Img17.2.png||height="403"}}

<<BR>>13. To drag and drop files from the host machine into the VM, first single click on the file cabinet icon on the left hand side of the desktop in the Ubuntu linux window. This will open the Ubuntu “Files” application which is the equivalent of the “Finder” (MacOS) or “Explorer” (Windows) in Linux. It will display the files in the home directory for userid developer.
<<BR>>{{attachment:Img18.png||height="504"}}

<<BR>>14. You can (single click and drag) a file from the host machine, e.g., from MacOS Finder, Windows Explorer) window, into the Files application in the Ubuntu desktop. You will see the name of the file while dragging as the mouse hovers over the Files window.
Note that permissions may prevent drag and drop from working on Windows.
<<BR>>{{attachment:Img19.1.png||height="252"}}
<<BR>>When you release the mouse the license.txt file icon appears in the Files window. This is simply an example, you should already have the license for your system, but this would allow you to add your own data into the system from your computer easily if you wish.
<<BR>>{{attachment:Img19.2.png||height="252"}}

<<BR>>15. <<BR>><<BR>>Right click with the mouse on the desktop and select “Open Terminal”.
Line 155: Line 172:

<<BR>>12. A new terminal window should appear with some !FreeSurfer variables set. If there is a warning at the top that indicates there is no !FreeSurfer license, you may not have the correct VM Image File - contact the course organizers to fix this. In the example image below, no license was
<<BR>>A new terminal window should appear with some !FreeSurfer variables set. If there is a warning at the top that indicates there is no !FreeSurfer license, you may not have the correct VM Image File - contact the course organizers to fix this. In the example image below, no license was
Line 160: Line 176:
<<BR>>13. Power off the virtual machine by closing the !VirtualBox Ubuntu window. On Mac OS this is the red circle in upper left hand corner of the window. On Windows this is the X in the upper right hand corner of the window. Check the entry for “Power Off” <<BR>>16. Power off the virtual machine by closing the !VirtualBox Ubuntu window. On Mac OS this is the red circle in upper left hand corner of the window. On Windows this is the X in the upper right hand corner of the window. Check the entry for “Power Off”
Line 163: Line 179:
<<BR>>14. Now that you have verified the VM runs as is “out of the box”, some changes should be made to the VM to better run !FreeSurfer. <<BR>>17. Now that you have verified the VM runs as is “out of the box”, some changes should be made to the VM to better run !FreeSurfer.
Line 169: Line 185:
<<BR>>15. The VM has only ~4GB of RAM “out of the box”. To the right hand side of the slider under the red part of the bar, you see the maximum amount of RAM available to the VM. <<BR>>18. The VM has only ~4GB of RAM “out of the box”. To the right hand side of the slider under the red part of the bar, you see the maximum amount of RAM available to the VM.
Line 174: Line 190:
<<BR>>16. Performance can similarly be improved by increasing the number of CPUs or cores allocated to the VM. Click on the “Processor” tab next to the “Motherboard” tab. The VM has 1 CPU allocated “out of the box”. To the right hand side of the slider under the red part of the bar, you see the maximum amount of CPUs available to the VM. <<BR>>19. Performance can similarly be improved by increasing the number of CPUs or cores allocated to the VM. Click on the “Processor” tab next to the “Motherboard” tab. The VM has 1 CPU allocated “out of the box”. To the right hand side of the slider under the red part of the bar, you see the maximum amount of CPUs available to the VM.
Line 176: Line 192:
<<BR>>The recommendation is to allocate 2-4 CPUs to the VM for running !FreeSurfer. If the total CPUs available are 2, then allocate 2 CPUs to the VM and try not to run other CPU intensive programs on the host. A rule of thumb is not to allocate more than 1/2 of the available CPU’s from the host to the VM. The “Execution Cap” is fine as is at 100%. <<BR>>The recommendation is to allocate 2-4 CPUs to the VM for running !FreeSurfer. If the total CPUs available are 2, then allocate 2 CPUs to the VM and try not to run other CPU intensive programs on the host. A rule of thumb is not to allocate more than 1/2 of the available CPU’s from the host to the VM. The “Execution Cap” is fine as is at 100%. Click "OK" to save changes.
Line 178: Line 194:

<<BR>>17. The guest extensions are installed in the VM. These allow for: (1) bi-directional cut and paste between the host machine and the Ubuntu linux window; (2) drag and drop files between the host machine and the Ubuntu linux window; (3) resize the Ubuntu linux
window;. Change these settings while the VM is running.
<<BR>>{{attachment:Img17.1.png||height="126"}}
<<BR>>Try selecting a specific “Resize to ...” dimension available in the pull down menu. With Auto-resize set, it works on some hosts to manually resize the Ubuntu linux window by dragging on a corner to enlarge it. But this may not work with some host graphics hardware if the window is re-sized to non-standard dimensions. Re-sizing only takes effect after you login.
<<BR>>{{attachment:Img17.2.png||height="403"}}

<<BR>>18. To drag and drop files from the host machine into the VM, first single click on the file cabinet icon on the left hand side of the desktop in the Ubuntu linux window. This will open the Ubuntu “Files” application which is the equivalent of the “Finder” (MacOS) or “Explorer” (Windows) in Linux. It will display the files in the home directory for userid developer.
<<BR>>{{attachment:Img18.png||height="504"}}

<<BR>>19. You can (single click and drag) a file from the host machine, e.g., from MacOS Finder, Windows Explorer) window, into the Files application in the Ubuntu desktop. You will see the name of the file while dragging as the mouse hovers over the Files window.
Note that permissions may prevent drag and drop from working on Windows.
<<BR>>{{attachment:Img19.1.png||height="252"}}
<<BR>>When you release the mouse the license.txt file icon appears in the Files window. This is simply an example, you should already have the license for your system, but this would allow you to add your own data into the system from your computer easily if you wish.
<<BR>>{{attachment:Img19.2.png||height="252"}}

FreeSurfer Course Installation Instructions

Downloading & Installing Virtualbox
The first step in getting ready for the FreeSurfer Course is downloading VirtualBox. It is a virtual machine software, able to easily replicate the environment and user interface of another computer, in this case one with FreeSurfer pre-installed. First, you will need to download the file that contains the Image (more information forthcoming), and then follow the instructions on how to set up the virtual machine. These steps differ for MacOS and Windows, so instructions for both are below. Make sure to set up the Virtual Machine and download the tutorial data as well; instructions on both are below the install instructions.
If you are unable to complete these instructions due to your machine not meeting requirements or other technical issues, you will likely not be able to complete the course on that device, and should contact the course organizers for assistance or to cancel your course registration.

Note: Any computers with ARM-based processors, including M1 and M2 Macs, will not work with VirtualBox.

Table of Contents:
Installing on Windows
Installing on Mac
Decompressing the Image
Setting up the Virtual Machine
Retrieving Tutorial Data



Installing On Windows

1. Navigate to the VirtualBox website, https://www.virtualbox.org/wiki/Downloads, and download the latest version of VirtualBox.
WinInstall1.png


2. Save the installer and wait for the download to finish.
WinInstall2.png


3. Locate the installer in the Downloads folder and double click on it to launch it.
WinInstall3.png


4. Choose to install the default setup/configuration with the default options
WinInstall4.png


5. Allow the network connection to be reset and start the installation.
WinInstall5.png


6. Allow the installation to progress and complete. Then click the finish button.
WinInstall6.png


7. VirtualBox should automatically launch and display an empty window (containing no virtual machines).
WinInstall7.png


8. You are now ready for the next step, Decompressing the Image.



Installing on Mac


Reminder: Any ARM based computers, including M1 and M2 Macs, will not work with VirtualBox, or our planned course.


1. Navigate to the VirtualBox website, https://www.virtualbox.org/wiki/Downloads, and download the latest version of VirtualBox.
MacInstall1.png


2. Allow downloads from the VirtualBox web site.
MacInstall2.png


3. Open the download archive when it finishes.
MacInstall3.png


4. Double click on the VirtualBox package installer
MacInstall4.png


5. Give the installer permission to run scripts.
MacInstall5.png


6. Allow the installer to continue.
MacInstall6.png


7. Pick a destination for the VirtualBox application. The default install location in the Applications folder should be fine (in the photo below, we are saving it to an external disk named “external_BigSur)”. Your hard drive will be named differently, e.g., Macintosh HD, etc.
MacInstall7.png


8. Authenticate using your login credentials to allow the installation.
MacInstall8.png


9. VirtualBox will issue a notification that the kernel extension it installed is currently blocked from running. Click OK. If this warning does not pop up for you, you will need to go to your System Preferences (under the Apple icon), then the Security and Privacy settings to follow the instructions in steps 10-11.
MacInstall9.png


10. After the notification the install completed, go into the system security and privacy settings and authenticate with your login credentials.
MacInstall10.png


11. With the preferences unlocked, select allow to enable the VirtualBox extension to load.
MacInstall11.png


12. You may be prompted to restart the machine in order for the VirtualBox kernel extension to load and run. If so, select "Restart" when prompted.
MacInstall12.png


13. Check the VirtualBox application appears in the Applications folder (or wherever you saved it).
MacInstall13.png


14. You are now ready for the next step below, Decompressing your VM Image.



Decompressing the Image

If you are participating in the Virtual FreeSurfer course, you will be provided with a link to download the Virtual Machine (VM) "Image" (a virtual computer set-up that will allow you to work with FreeSurfer and the course data + tutorials). This download will be a zipped/compressed file. The instructions below show you how to unzip/decompress the file.


1. Once it is provided by the course organizers, download & locate the compressed VM Image file (FS_7_3_2_course_ubuntu_18_04_06.ova.7z).


2. If you do not already have one, download software to unzip or decompress the VM Image file. It must be 7zip compatible archival software.

  • For Windows, Win-RAR can be used. Note: There is a free version for 40 days with no payment information necessary that can be used.
    For Mac, the Unarchiver can be used.


3. After you have successfully installed or located software to decompress the VM Image file, you will want to use it on the file downloaded in Step #1 of this section. Locate the compressed VM Image file (FS_7_3_2_course_ubuntu_18_04_06.ova.7z) and right click on it, choose "Open With", and choose the software you have for decompressing the file. Alternatively, you can potentially open the software first & navigate to the compressed file (i.e. click the "Extract to" button in Win-RAR).
Arch1.png


4. You will be prompted for a password. Enter the 7-zip archive password given to you from the course organizers. Once entered, the file should start decompressing/unzipping. After this completes, there should be another VM Image file which ends with the .ova file extension (FS_7_3_2_course_ubuntu_18_04_06.ova). This .ova file is what you will open with VirtualBox in the next step.


5. You are now ready to set up your Virtual Machine using VirtualBox.



Setting up the Virtual Machine


1. Open the VirtualBox application. If you just finished installing VirtualBox for the first time, then you will see no machine images are available to run on the left hand side of the GUI.
Img1.1.png

Select “Preferences” from the VirtualBox application pull down menu.
Img1.2.png


2. Create a DEFAULT MACHINE FOLDER path/location on an (external or internal) drive where you have at least 30G of free disk space for VirtualBox to store the virtual machine. In the example below, the path under /Volumes/... was manually created on a different drive than the boot drive in order to enhance performance. External drives w/o a USB 3.0 or faster connection are not recommended.
Img2.png


3. An appliance file will be used to create an Ubuntu Linux image to run. From the “File” pull down menu select “Import appliance”.
Img3.1.png
Use the “Choose” icon to navigate to the decompressed VM Image file (FS_7_3_2_course_ubuntu_18_04_06.ova). The file name in the example below may be different than the one given to you by the course organizers.
Img3.2.png


4. Once the path/filename of the appliance file is listed in the “File” field, then select “Continue” or "Next".
Img4.png


5. You will be presented with a window showing the current settings for the virtual appliance. Change the entry for “MAC address policy” to be “Generate new MAC addresses for all network adapters”.
Img5.png


6. Select “Import” to create the virtual machine.
Img6.png


7. Wait for all steps in the import process to finish.
Img7.png


8. There should now be an entry for the virtual machine on the left hand side of the GUI with the current virtual machine configuration displayed on the opposite side.
Img8.png


9. Start the virtual machine by clicking on the “Start” icon in the VirtualBox application.
Img9.1.png

The Ubuntu boot menu should appear with the 1st choice, “Ubuntu”, highlighted. Hit return or wait for it to automatically boot.
Img9.2.png


10. If the virtual machine fails to boot contact the FreeSurfer team. Otherwise, click on the user “developer” to log in. Enter the VM login password that was provided to you by the course organizers.
Img10.1.png

Enter the password.
Img10.2.png


11. A blank desktop should appear after you login.
Img11.1.png


12. Some extensions have been installed in the VM to make it easier to work with. These will allow: (1) bi-directional cut and paste between the host machine and the Ubuntu linux window; (2) drag and dropping files between the host machine and the Ubuntu linux window; and (3) resizing the Ubuntu linux window;. Change these settings while the VM is running.
Img17.1.png
Try selecting a specific “Resize to ...” dimension available in the pull down menu. With Auto-resize set, it works on some hosts to manually resize the Ubuntu linux window by dragging on a corner to enlarge it. But this may not work with some host graphics hardware if the window is re-sized to non-standard dimensions. Re-sizing only takes effect after you login.
Img17.2.png


13. To drag and drop files from the host machine into the VM, first single click on the file cabinet icon on the left hand side of the desktop in the Ubuntu linux window. This will open the Ubuntu “Files” application which is the equivalent of the “Finder” (MacOS) or “Explorer” (Windows) in Linux. It will display the files in the home directory for userid developer.
Img18.png


14. You can (single click and drag) a file from the host machine, e.g., from MacOS Finder, Windows Explorer) window, into the Files application in the Ubuntu desktop. You will see the name of the file while dragging as the mouse hovers over the Files window. Note that permissions may prevent drag and drop from working on Windows.
Img19.1.png
When you release the mouse the license.txt file icon appears in the Files window. This is simply an example, you should already have the license for your system, but this would allow you to add your own data into the system from your computer easily if you wish.
Img19.2.png


15.

Right click with the mouse on the desktop and select “Open Terminal”.
Img11.2.png
A new terminal window should appear with some FreeSurfer variables set. If there is a warning at the top that indicates there is no FreeSurfer license, you may not have the correct VM Image File - contact the course organizers to fix this. In the example image below, no license was found.
Img12.png


16. Power off the virtual machine by closing the VirtualBox Ubuntu window. On Mac OS this is the red circle in upper left hand corner of the window. On Windows this is the X in the upper right hand corner of the window. Check the entry for “Power Off”
Img13.png


17. Now that you have verified the VM runs as is “out of the box”, some changes should be made to the VM to better run FreeSurfer. With the VM still powered off, click on the “Settings” icon as the top of the VirtualBox window.
Img14.1.png

Click on the “System” icon to display the amount of RAM or “Base Memory” the VM can use from the host machine.
Img14.2.png


18. The VM has only ~4GB of RAM “out of the box”. To the right hand side of the slider under the red part of the bar, you see the maximum amount of RAM available to the VM.
Img15.1.png
The recommendation is to allocate 8-12GB of RAM to the VM for running FreeSurfer. If the total RAM listed for your machine is 16GB, then increase the RAM to 8GB before running Freesurfer. A rule of thumb is not to allocate more than 1/2 of the available host RAM to the VM. In the example below, the machine shows a total of 32GB of RAM (32,768 MB) and we have moved the slider so that VM can use 8GB (8,192 MB), in the first example, and 12GB (12,241 MB) in the second example.
Img15.2.png


19. Performance can similarly be improved by increasing the number of CPUs or cores allocated to the VM. Click on the “Processor” tab next to the “Motherboard” tab. The VM has 1 CPU allocated “out of the box”. To the right hand side of the slider under the red part of the bar, you see the maximum amount of CPUs available to the VM.
Img16.1.png
The recommendation is to allocate 2-4 CPUs to the VM for running FreeSurfer. If the total CPUs available are 2, then allocate 2 CPUs to the VM and try not to run other CPU intensive programs on the host. A rule of thumb is not to allocate more than 1/2 of the available CPU’s from the host to the VM. The “Execution Cap” is fine as is at 100%. Click "OK" to save changes.
Img16.2.png


20. Now you are ready to download the Tutorial Data, and test your systems functionality.



Retrieving Tutorial Data


1. At this point, the Ubuntu virtual machine should run including running the FreeView application from the terminal command line, e.g., display a volume (*.mgz file). Go back and review the previous documentation to setup and run the VM if this is not the case.

The tutorial data download archive needs ~8G of space and the uncompressed data needs ~14G of space. Find the location of the virtual machine folder on the host by right clicking on the entry for the virtual machine in the Virtual Box sidebar. On the Mac select “show in Finder” and on Windows select “show in Explorer”.
Tut1.png
Check the disk where the VirtualBox folder resides has a least another ~25G of free space available. If that is not the case, then you will need to setup a new copy of the VM on a disk partition with more space. Alternately, you can clone your existing VM to another disk partition with more space. (See the VirtualBox documentation on how to clone a VM).


2. Open a new terminal window and check there are no reports of a missing license file. Per the instructions in the previous documents, the environment variable FS_LICENSE should point to your license file, e.g., license.txt.
Tut2.png


3. Run the setup_tutorial_data command to download and setup the tutorial data for use with the FreeSurfer 7.2.0 release. The download may take 20-30 minutes depending upon your network connection. See the “eta” estimate to the right hand side of the progress bar for the “estimated time of arrival”.
Tut3.png


4. Example terminal output is shown below for the completed download of the tutorial data. Note the archive name, tutorial_data_20211231_2058, may be different if the data has changed.
Tut4.png


5. Close the current terminal window by clicking on the red X in the upper right hand corner of the toolbar.
Tut5.1.png
Open a new terminal window and check the last line of output is “Environment has been set for tutorial data”. Stop, do not proceed and check with the FreeSurfer team if this is not the case.
Tut5.2.png


6. Run the test_tutorial_data command to test if your setup can run the tutorial commands. The test may take 20-30 minutes on a typical machine. You will see 80+ FreeView commands run and the FreeView GUI will automatically open and close. Do not manually close the FreeView window or interrupt the test.
Tut6.png


7. Example test output while running …
Tut7.png


8. Check the test ends by displaying “SUCCESS” If you do not get this result, e.g., the test exits prematurely or exits with an error, then check with the FreeSurfer team. Successful output for the end of the test is shown below.
Tut8.png


9. Lastly, run the setup_tutorial_data command again to reset the tutorial data to a clean state. The previously downloaded tutorial data will be used unless the tutorial data has changed since the last download. When the command finishes you should be able to run the tutorial commands from scratch. Run this command to reset the data before day 1 of the FreeSurfer course. Make sure any new terminal window reports “Environment has been set for tutorial data””.
Tut9.png

You are now prepared for the course! There are other tutorials here (link pending) if you wish to try out your system before the course or if you wish to go over more material, but this is optional.

CourseDescription/Remote_Qualify (last edited 2024-03-18 14:43:31 by NathanDraudt)