FreeSurfer v7 installation A-Z (MacOS)

TL;DR

1. pkg 파일 버전에 맞게 설치

2. 설치 과정에서 system setting 의 보안 예외 설정

3. 환경변수 설정

   $ export FREESURFER_HOME=/Applications/freesurfer/7.1.1
   $ export SUBJECTS_DIR=$FREESURFER_HOME/subjects

4. 단축어 설정

   alias freesurfer="source $FREESURFER_HOME/SetUpFreeSurfer.sh"

5. 터미널 설정

   # .bash_profile 또는 .zshrc 도 무관
   vi ~/.bashrc
   
   # vim 사용방법 확인하여 아래 내용 추가
   # freesurfer
   export FREESURFER_HOME="/Applications/freesurfer/7.4.1"
   export SUBJECTS_DIR=$FREESURFER_HOME/subjects
   alias freesurfer="source $FREESURFER_HOME/SetUpFreeSurfer.sh"

6. 테스트

   # 터미널 재실행 또는 `source ~/.{터미널 설정 파일}`
   $ source ~/.bashrc
   
   # 실행 확인
   $ freesurfer        # freesurfer 안내사항 출력
   $ freeview          # freeview 실행

   • 터미널 종료 후 재실행 해도 명령어가 작동되면 된다.
   • 이후 테스트는 튜토리얼에서 확인. 같은 방식으로 export TUTORIAL_DATA='실행경로' 추가해주면 된다.

준비

FreeSurfer Download and Install

FreeSurfer Release 7 System Requirements

Summary of Requirements:
See list of supported operating systems for each release below.
    Intel processor supporting AVX instructions
    RAM: 8GB for recon, 16GB suggested for viewing graphics
    Graphics card: 3D graphics card with its own graphics memory & accelerated OpenGL drivers
    Size of installed image: 16GB
    Typical size of a processed subject: 300MB
    Other requirements: Matlab (only needed to run FS-FAST, the fMRI analysis stream)

아래 환경에서 설정했다. Matlab 이외의 프로그램은 필요하지 않다.¹ - MATLAB

¹ 튜토리얼 진행 중 문제 발견시 추가 예정 (24.03.14)

local environment

1. 설치

공식 가이드 (step by step installation demo) 를 따라하면 웬만한 과정은 다 해결 된다.

최신 버전의 패키징 파일을 다운로드 한다.

1.1. 다운로드

MacOS Install & Setup 에 자세한 스크린샷이 첨부되어 있다.

image

• 최신인 버전 7.4.1을 다운로드 한다. 맥은 설치 전과정을 담은 pkg 파일을 제공한다.
• Virtual Box도 제공하지만 설치시점인 2024년에는 m1을 지원하지 않는다.
• 수동 설치(manual install)를 위해 .tar 파일을 다운로드 했을 시 패키징 프로그램 .pkg의 기본 경로와 겹치지 않도록 압축 해제해야 한다.²
  • pkg 파일은 /Applications/freesurfer 아래에 각 버전을 명시한 폴더를 만들고 그 안에 freesurfer의 실제 파일을 설치한다.
  • e.g. /Applications/freesurfer/7.4.1/

² “Please do not expand any tar archive such that the path to FREESURFER_HOME is /usr/local/freesurfer on linux or /Applications/freesurfer on MacOS. Those paths are overwritten by the installer packages so manual installs there may not be preserved.”

1.2. 인증

pkg파일을 열면 중간쯤 설치되다가 멈추거나 보안 오류를 발생시킨다. 윈도우에서도 그렇듯 알 수 없는 개발자가 만든 프로그램은 OS에서 설치되지 않게 막아뒀는데 애플의 경우 그 과정이 조금 까다롭다. 이 프로그램도 앱스토어에 등록되지 않은 인증서 없는 프로그램이라 설치가 막힌 것다. 보안상 문제 없는 프로그램이므로 시스템 설정에 가서 예외 처리를 해주면 된다.

1. 시스템 설정

   

   system settings

2. privacy & security 이동

3. allow applications downloaded from ~ 하단에 이슈가 발생한 프로그램이 보이는데 open anyway 누르고 진행하면 된다.

   privacy & security	open anyway

1.3. 위치 지정

1. pkg 파일이 마저 열리면 continue 계속해서 눌러주면 된다. 따로 설정할 건 없다.
   • 설치 디스크 설정을 할 수 있는 부분이 나오는데 특별한 경우가 아닌 이상 본체에 설치한다.
2. 다 설치되면 pkg 파일을 지울건지 말건지 물어보는데 쓸 일 없으므로 지워줘도 된다.

삭제

만약 제대로 설치하지 못했거나 지우고 싶을 경우 아래 명령어를 사용하면 된다.

$ sudo /Applications/freesurfer/7.1.4/uninstall.sh

• $ 는 제외하고 입력
• 버전이 다를 경우 /7.1.4/ 자리에 해당하는 버전을 넣으면 된다. (e.g. /7.1.5/)
• 관리자 권한³으로 freesurfer가 설치 된 위치⁴에 있는 제거 파일⁵을 실행하겠다는 뜻이다.

³ sudo

⁴ /Applications/freesurfer/7.1.4/

⁵ uninstall.sh

2. 환경변수 설정

• 구글링 해보면 이부분에서 걸리는 경우가 많던데 환경변수 설정 문제인 경우가 많았다.
• 가장 앞의 $ 는 CLI (터미널 환경) 의 명령어를 입력 받는 줄임을 알리는 표기이므로 무시하면 된다.

2.1. 개요

단계는 단순하다.

1. 우리는 설치한 freesurfer를 터미널에서 사용하고 싶다.
2. 그러려면 단축어 설정(alias)이 필요한데
3. 단축어 설정을 하려면 정확히 어떤 파일을 실행해야 하는지 명시해야 한다.
4. 그리고 이 과정을 매번 반복할 수 없으니 터미널을 실행할 때마다 자동으로 세팅되게 해줘야 한다.

2.2 명령어

아래 내용을 알면 입력만 하고 넘어가도 된다.

• 환경변수
• export
• source
• echo

공식 문서

# After the installer program exits, use the terminal window to setup the environment 
# with the same commands listed above except that the path 
# for FREESURFER_HOME is now /Applications/freesurfer/7.1.1.

$ export FREESURFER_HOME=/Applications/freesurfer/7.1.1
$ export SUBJECTS_DIR=$FREESURFER_HOME/subjects
$ source $FREESURFER_HOME/SetUpFreeSurfer.sh
-------- freesurfer-darwin-macOS-7.1.1-20200429-3a03ebd --------
Setting up environment for FreeSurfer/FS-FAST (and FSL)
WARNING: /Users/synpro/freesurfer/fsfast does not exist
FREESURFER_HOME   /Applications/freesurfer/7.1.1
FSFAST_HOME       /Users/synpro/freesurfer/fsfast
FSF_OUTPUT_FORMAT nii.gz
SUBJECTS_DIR      /Applications/freesurfer/7.1.1/subjects
MNI_DIR           /Users/synpro/freesurfer/mni

$ which freeview
/Applications/freesurfer/7.1.1/bin/freeview

입력

터미널에서 아래 명령어들을 입력해주면 된다.

# `export` 는 환경변수를 명시해주는 명령어다.
# 7.1.4 가 아니라 다른 버전을 설치했을 시 해당 부분 변경

export FREESURFER_HOME=/Applications/freesurfer/7.1.4
export SUBJECTS_DIR=$FREESURFER_HOME/subjects
source $FREESURFER_HOME/SetUpFreeSurfer.sh

보충

1. FREESURFER_HOME
   • export FREESURFER_HOME=/Applications/freesurfer/7.1.1
     • 실행하고자 하는 파일이 어디에 있는가? == 설치 위치 명시
     • 설치 경로를 매번 적어줄 수 없으니 FREESURFER_HOME 에 저장해두고 쓴다.
       • e.g. 하단의 $FREESURFER_HOME
     • 확인하고 싶으면 터미널에 echo $FREESURFER_HOME 을 입력해본다./Applications/freesurfer/7.1.1 가 출력되면 넘어간다.
2. SUBJECTS_DIR
   • export SUBJECTS_DIR=$FREESURFER_HOME/subjects
     • freesurfer는 데이터를 subjects에 보관한다. 해당 위치가 아니라 다른 위치의 데이터를 사용하고 싶으면 = 이후에 원하는 경로를 입력하면 된다.
     • 위 명령어에서 $FREESURFER_HOME 는 변수로 저장한 설치 위치를 가져오겠다는 의미다.
     • 터미널을 열때마다 export해서 바꿔줄 수 있으니 웬만하면 기본 경로로 해주고 그때그때 바꿔쓰자.
3. SetUpFreeSurfer.sh
   • source $FREESURFER_HOME/SetUpFreeSurfer.sh
     • 실제로 freesurfer를 실행하는 파일이다. 사전 설정 없이 /Applications/freesurfer/7.1.1/SetUpFreeSurfer.sh만 실행해도 해당 터미널에서 freesurfer는 실행된다. 모두 번거로우니 위 과정을 거치는 것이다.
     • 공식 문서의 ------- 아래는 freesurfer를 실행하는 환경을 말한다. 앞에서 세팅한 FREESURFER_HOME, SUBJECTS_DIR 를 확인할 수 있다.
       • 다른 경로 FSFAST_HOME, FSF_OUTPUT_FORMAT, MNI_DIR 모두 같은 방법으로 설정하면 된다.

2.3 단축어

• 공식문서는 이렇게 설명하고 있다.
• 터미널에서 단어를 입력할 경우 파일을 실행하게 하는 일종의 ’바로가기’를 alias 라고 한다.
• 위에서 경로와 파일을 명시해줬으니 어떤 이름으로 실행하게 할지만 알려주면 된다.

alias freesurfer="source $FREESURFER_HOME/SetUpFreeSurfer.sh"

1. alias freesurfer =
   • freesurfer 라는 명령어를 입력할 경우
2. $FREESURFER_HOME/SetUpFreeSurfer.sh
   • 실제로 freesurfer를 여는 파일을
3. source
   • 실행하겠다

위와 같은 뜻이다. 명령어를 실행하고 freesurfer 를 입력하면 되는데 너무 길다면 alias freesurfer 의 freesurfer 대신 다른 명칭을 적으면 된다.

3. 터미널 설정

• 자동실행을 위한 과정이다. 2번 과정을 다하고 터미널을 끄면 모든게 초기화된다. 매번 세팅을 새로하는 사람이라면 좋겠지만 터미널을 닫고 여는 일이 잦은 사람이라면 불편하지 않을 수 없다.
• 그렇다고 모르는 명령어를 입력하자니 걱정될 사람들을 위해 위와 같이 자세히 적어두었다. 2번을 다 이해했다면 터미널 세팅을 열고 바꾸기만 하면 되니 편하게 복사해서 붙여넣자.

bash를 기본으로 하고, vim을 사용할 줄 모른다는 전제로 적는다.

3.1. 터미널 설정 파일 확인

1. vi ~/.bash_profile 명령어로 터미널 설정 파일을 연다.

   • ~/.bash_profile : 터미널 세팅
   • bash_profile 대신 bashrc 써도 상관 없다! 둘의 차이점을 안다면 편한대로 작성하자!
     • 참고: [17] 리눅스 - Bash 쉘 스크립트 작성 (bash shell, alias, history, 명령 재실행)
       • ~/.bash_profile : 각 사용자에게 적용되는 환경 설정과 시작 프로그램을 지정하는 파일
       • ~/.bashrc : 각 사용자의 별명과 함수들을 정의하는 파일
   • zsh 을 기본 터미널로 써도 괜찮다. zsh을 열때 bash 설정을 참조하도록 설정되어 있을 것이다.
   • 터미널에 cat ~/.zshrc | grep bash 를 입력했을 때 출력⁶이 뭐라도 보인다면 문제 없다.⁷

⁶ if [ -f ~/.bash_profile ]; then . ~/.bash_profile; fi 등

⁷ 터미널 설정 파일에 bash쉘 설정파일을 참조하는게 있는지 확인하는 명령어다.

3.2. 터미널 설정 변경

vi/vim을 사용할 줄 모른다면 아무것도 누르지말고 아래를 따라한다. 안다면 2.5 내용을 붙여넣기만 하면 된다.

1. 영문인지 키보드 상태 확인한다.⁸

2. Press ENTER or type command to continue 보고 엔터

3. 최하단의 Normal 을 보고 a 를 눌러 입력모드로 진입한다.⁹

   막 켜졌을 때	a눌렀을 때`

4. 화살표 눌러 최하단으로 이동

5. 아래 내용 붙여넣기¹⁰

   # freesurfer
   export FREESURFER_HOME="/Applications/freesurfer/7.4.1"
   export SUBJECTS_DIR=$FREESURFER_HOME/subjects
   alias freesurfer="source $FREESURFER_HOME/SetUpFreeSurfer.sh"

6. esc 누르고 :wq 입력한 후에 엔터

   

   bash_profile

7. 터미널로 돌아갔는지 확인

⁸ 한글이면 영문으로 변경

⁹ Insert 상태가 되지 않았을 때에는 뭘 눌러도 입력되지 않는다. 주의할 것.

¹⁰ 경로나 버전이 다르다면 당연히 바꿔줘야 한다.

3.3. 확인

1. 터미널을 닫았다가 다시 열거나 source ~/.bash_profile 또는 source ~/.zshrc 입력하여 설정을 적용한다.
2. 설정한 단축어인 freesurfer를 입력했을 때 /Applications/freesurfer/7.1.1/SetUpFreeSurfer.sh 를 실행했던 결과와 같은 결과¹¹가 나오면 성공
   • freeview는 freesurfer가 실행되어 있으면 함께 사용할 수 있다.

¹¹ freesurfer 정보가 나온다.

후기

뭐 이렇게까지 적어놨나 싶지만 공식문서에서 여러 경우의 수를 고려했던 모양인지 단순한 문제를 복잡하게 적어두기도 했고, 이런 문제나 또 이런 문제도 발견해서 세팅하는 김에 가볍게 적었다. 다 아는 내용이라면 넘어가자. 연구실에서 WSL 환경도 세팅 중이니 끝나면 따로 가이드를 적어보겠다.

4. 이슈들

문제들은 확인되는대로 보충한다. (2024.03.14)

0. M1

IS APP SILICON READY?

• 이슈라기보다는 확인 중인 내용인데, application의 get info에서 보면 kind에 intel이라고 적혀있다. 그래도 아직까진 문제없이 돌아가니 튜토리얼 진행하면서 안되는 부분을 발견하면 적겠다.
  • 위에도 적었지만 우선 MATLAB은 M1 칩과 호환된다: Is MATLAB Apple silicon ready?: Yes, Native Apple Silicon support (R2023b)
• 의견들
  • m1 관련 내용은 반년 전까지 누군가 업데이트 해둔게 있다: https://github.com/neurolabusc/AppleSiliconForNeuroimaging M1을 권장하지는 않지만 이미 쓰고 있는데 어쩌겠나.
  • (v 7.1.1) Apple Silicon M1 compatibility - FreeSurfer YES; everything else no

1. freeview가 갑자기 꺼질 때

• 라이센스 추가했는지 확인
  • https://neurostars.org/t/freeview-quit-unexpectedly/26134

2. sefmentation fault: 11

/Applications/freesurfer/7.2.0/bin/freeview: line 2: 2150 Segmentation fault: 11 
$FREESURFER_HOME/Freeview.app/Contents/MacOS/freeview “$@”

• https://neurostars.org/t/problem-installing-freesurfer-in-mac/20552/18

놀랍게도 보조 모니터 이슈다. freeview까지 본체로 이동할 필요는 없고 터미널만 원래 모니터로 이동시키면 해결 된다.