FreeSurfer 7.3.2 のインストールと脳領域のセグメンテーション（Ubuntu 上）

FreeSurfer は，頭部 MRI 画像から大脳皮質表面の再構成と脳領域のセグメンテーションを行うソフトウェアである。このページでは FreeSurfer 7.3.2（2022 年 8 月公開）を Ubuntu 22.04 上にインストールし，recon-all による処理を行う手順を説明する。FreeSurfer には版数の新しい 8 系列（8.2.0，2026 年 3 月公開）と，バージョン 7 系列の最終版 7.4.1（2023 年 6 月公開）がある。研究データを処理する場合，同一の研究内では同じバージョンで統一して処理する必要がある。最新の公開状況は FreeSurfer Version 8 & 7 Releases のページで確認できる。

動作環境

CPU: AVX，SSE 命令に対応した Intel 系プロセッサ
メモリ: recon-all の実行には 16 GB 以上（7 系列の場合）
インストール後のディスク使用量: 約 16 GB から 19 GB。処理済み被験者 1 名あたり約 300 MB
三次元表示には，OpenGL に対応したグラフィックス環境が必要

FreeSurfer のライセンスファイルの取得

FreeSurfer の実行には license.txt というライセンスファイルが必要である。取得は無償である。

FreeSurfer Wiki の Web ページを開く
https://surfer.nmr.mgh.harvard.edu/fswiki
「Download and Install」（Installation guide）をクリック
「Follow this link to obtain a license key」をクリック

登録ページの URL は次の通りである。
https://surfer.nmr.mgh.harvard.edu/registration.html
フォームに記入する。記入と確認が終わったら「I agree」をクリックする。
ライセンス条項は利用者で確認すること。
電子メールで license.txt が送られてくるので保存する。このファイルは，インストール後に $FREESURFER_HOME の直下（例: /usr/local/freesurfer/7.3.2/license.txt）に置く。

FreeSurfer のダウンロード

FreeSurfer Version 8 & 7 Releases の Web ページを開く
https://surfer.nmr.mgh.harvard.edu/fswiki/rel7downloads
7.3.2 release の表から，使用している Ubuntu のバージョンに合う deb 形式のインストーラを選ぶ。Ubuntu 22.04 では freesurfer_ubuntu22-7.3.2_amd64.deb である。
ファイルサイズは約 6.6 GB である。ダウンロードには時間がかかる。

端末で次のコマンドを実行してダウンロードすることもできる。

cd /tmp
wget https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/7.3.2/freesurfer_ubuntu22-7.3.2_amd64.deb

FreeSurfer のインストール

Ubuntu のシステム更新

Ubuntu で OS のシステム更新を行うときは，端末で，次のコマンドを実行する。これは、パッケージ情報を最新の状態に保ち、インストール済みのパッケージをセキュリティアップデートやバグ修正を含めて更新するためである。

Ubuntu のインストールはこちらの別ページで説明する。

# パッケージリストの情報を更新
sudo apt update
# インストール済みのパッケージを包括的に更新 (依存関係も考慮)
sudo apt full-upgrade
# カーネル更新等で実際に再起動が必要な場合のみ実行を推奨
# sudo shutdown -r now

インストール

端末で，次のコマンドを実行する。apt を用いると，deb パッケージが必要とする依存パッケージも同時にインストールされる。

cd /tmp
sudo apt install ./freesurfer_ubuntu22-7.3.2_amd64.deb

インストール先は /usr/local/freesurfer/7.3.2 である。

ライセンスファイルの配置

電子メールで受け取った license.txt を，インストールディレクトリの直下にコピーする。

sudo cp ~/Downloads/license.txt /usr/local/freesurfer/7.3.2/license.txt

環境変数の設定

FreeSurfer のコマンドを使う前に，FREESURFER_HOME を設定し，設定用スクリプト SetUpFreeSurfer.sh を読み込む。

export FREESURFER_HOME=/usr/local/freesurfer/7.3.2
source $FREESURFER_HOME/SetUpFreeSurfer.sh

端末を開くたびに自動で設定されるようにするには，上記の 2 行を ~/.bashrc の末尾に追加する。

設定が済んだことは，次のコマンドで確認できる。

which recon-all
freeview --version

SUBJECTS_DIR の設定

SUBJECTS_DIR は，被験者ごとの処理結果が格納されるディレクトリである。既定値は $FREESURFER_HOME/subjects であるが，この場所は書き込みに管理者権限が必要である。ホームディレクトリの下など，書き込み権限のあるディレクトリを指定して使う。

export SUBJECTS_DIR=$HOME/freesurfer_subjects
mkdir -p $SUBJECTS_DIR

recon-all による脳領域のセグメンテーション

処理の概要

FreeSurfer での脳の領域抽出（セグメンテーション）は，内部的には次の3手順を踏む。

頭蓋骨の除去（skull stripping）
入力：頭部 MRI ボリューム画像データ (mgz 形式ファイル)，出力：頭蓋骨除去後の頭部ボリューム画像データ (mgz 形式ファイル)
白質面，軟膜面（皮質表面），膨張面の生成と皮質下構造のセグメンテーション
出力：セグメンテーション結果のボリューム画像データと，サーフェス（ポリゴン）データ
サーフェスの球面へのマッピングと皮質の領域分割（parcellation）
出力：球にマッピングされたサーフェスデータ，アトラスに基づく皮質の領域分割データ

recon-all コマンドを使って，上記の3手順を一括実行できる（後述のように，一括実行せずに順次実行もできる）。

recon-all -all -s サブジェクト名

【入力】

頭部 MRI ボリューム画像データ($SUBJECTS_DIR/サブジェクト名/mri/orig/001.mgz)

【出力】

頭蓋骨除去後の頭部ボリューム画像データ(mri/brainmask.mgz)
皮質下構造のセグメンテーション結果(mri/aseg.mgz)，皮質の領域分割結果(mri/aparc+aseg.mgz, mri/aparc.a2009s+aseg.mgz)
白質面，軟膜面，膨張面のサーフェスデータ(surf/?h.white, surf/?h.pial, surf/?h.inflated)
球にマッピングされたサーフェスデータ(surf/?h.sphere)
領域ごとの体積，皮質厚などの統計値(stats/*.stats)

recon-all コマンドで，上記の3手順を一括実行せずに，1手順ずつ順次実行することもできる。

手順1：コマンド「recon-all -autorecon1 -s サブジェクト名」
手順2：コマンド「recon-all -autorecon2 -s サブジェクト名」
手順3：コマンド「recon-all -autorecon3 -s サブジェクト名」

* 一括実行では，手順の切り替えのために実行結果を待つ必要がないため，途中で結果を確認する必要がない場合は一括実行を使う。

* 1 名分の一括実行には，計算機の性能にもよるが数時間から半日程度を要する。-parallel と -openmp を付けると，左右半球の処理などが並列実行され，処理時間を短縮できる。

recon-all -all -s サブジェクト名 -parallel -openmp 4

サンプルデータを用いた実行例

FreeSurfer には bert というサンプルデータ（被験者データ）が付属する。格納場所は $FREESURFER_HOME/subjects/bert である。ここでは bert の元画像 001.mgz をコピーして処理する。

3手順の一括実行

サブジェクト名を bert1 として，設定と前処理を行う。端末で，次のコマンドを実行する。

export FREESURFER_HOME=/usr/local/freesurfer/7.3.2
source $FREESURFER_HOME/SetUpFreeSurfer.sh
export SUBJECTS_DIR=$HOME/freesurfer_subjects
mkdir -p $SUBJECTS_DIR/bert1/mri/orig
cp $FREESURFER_HOME/subjects/bert/mri/orig/001.mgz $SUBJECTS_DIR/bert1/mri/orig/
freeview -v $SUBJECTS_DIR/bert1/mri/orig/001.mgz &

セグメンテーションを実行する。

recon-all -all -s bert1

正常終了したときは，次の形式のメッセージが表示される。

recon-all -s bert1 finished without error at ...

3手順の順次実行

サブジェクト名を bert3 として，設定と前処理を行う。端末で，次のコマンドを実行する。

export FREESURFER_HOME=/usr/local/freesurfer/7.3.2
source $FREESURFER_HOME/SetUpFreeSurfer.sh
export SUBJECTS_DIR=$HOME/freesurfer_subjects
mkdir -p $SUBJECTS_DIR/bert3/mri/orig
cp $FREESURFER_HOME/subjects/bert/mri/orig/001.mgz $SUBJECTS_DIR/bert3/mri/orig/
freeview -v $SUBJECTS_DIR/bert3/mri/orig/001.mgz &

セグメンテーションを3手順で実行する。

recon-all -autorecon1 -s bert3
recon-all -autorecon2 -s bert3
recon-all -autorecon3 -s bert3

自前の MRI 画像を処理する場合

DICOM ファイルや NIfTI ファイルを入力にするときは，-i オプションで入力ファイルを指定する。001.mgz への変換は recon-all が行う。

recon-all -i 入力ファイル名 -s サブジェクト名 -all

出力結果の確認

表示には freeview を使う。旧バージョンで使われていた tkmedit，tksurfer は非推奨であり，FreeSurfer 7 では freeview に置き換えられている。

「1手順」で行った場合

「recon-all -all -s bert1」の出力結果の確認 (1) 頭蓋骨除去後の頭部ボリューム画像データ

freeview -v $SUBJECTS_DIR/bert1/mri/brainmask.mgz

「recon-all -all -s bert1」の出力結果の確認 (2) 軟膜面（皮質表面）のサーフェスデータ

freeview -f $SUBJECTS_DIR/bert1/surf/lh.pial

「recon-all -all -s bert1」の出力結果の確認 (3) 白質面のサーフェスデータ

freeview -f $SUBJECTS_DIR/bert1/surf/lh.white

「recon-all -all -s bert1」の出力結果の確認 (4) 膨張面のサーフェスデータ

freeview -f $SUBJECTS_DIR/bert1/surf/lh.inflated:overlay=lh.curv

「recon-all -all -s bert1」の出力結果の確認 (5) 球にマッピングされたサーフェスデータ

freeview -f $SUBJECTS_DIR/bert1/surf/lh.sphere:overlay=lh.curv

「3手順」で行った場合

手順1: 「recon-all -autorecon1 -s bert3」の出力結果の確認. 頭蓋骨除去後の頭部ボリューム画像データ

freeview -v $SUBJECTS_DIR/bert3/mri/brainmask.mgz

手順2: 「recon-all -autorecon2 -s bert3」の出力結果の確認 (1) 軟膜面（皮質表面）のサーフェスデータ

freeview -f $SUBJECTS_DIR/bert3/surf/lh.pial

手順2: 「recon-all -autorecon2 -s bert3」の出力結果の確認 (2) 白質面のサーフェスデータ

freeview -f $SUBJECTS_DIR/bert3/surf/lh.white

手順2: 「recon-all -autorecon2 -s bert3」の出力結果の確認 (3) 膨張面のサーフェスデータ

freeview -f $SUBJECTS_DIR/bert3/surf/lh.inflated:overlay=lh.curv

手順3: 「recon-all -autorecon3 -s bert3」の出力結果の確認

freeview -f $SUBJECTS_DIR/bert3/surf/lh.sphere:overlay=lh.curv

内部で実行されたコマンドの確認

gedit $SUBJECTS_DIR/サブジェクト名/scripts/recon-all.cmd

「3手順」で実行した場合は，1手順ごとにコマンドファイル recon-all.cmd が上書きされる。全手順のコマンドを確認したい場合は，各手順の終了後にこのファイルを保存しておく。

実行時のログの確認

gedit $SUBJECTS_DIR/サブジェクト名/scripts/recon-all.log

ログファイルは追記される。エラーの原因を調べるときは，このファイルと recon-all.error を確認する。

セグメンテーション結果の表示とラベルの確認

セグメンテーション結果の .mgz 形式ファイルは3種類あり，それぞれ用いているアトラスが異なる。colormap=lut を指定すると，ラベルごとに色分けして表示される。

freeview -v $SUBJECTS_DIR/bert1/mri/T1.mgz \
  $SUBJECTS_DIR/bert1/mri/aseg.mgz:colormap=lut:opacity=0.4
freeview -v $SUBJECTS_DIR/bert1/mri/T1.mgz \
  $SUBJECTS_DIR/bert1/mri/aparc+aseg.mgz:colormap=lut:opacity=0.4
freeview -v $SUBJECTS_DIR/bert1/mri/T1.mgz \
  $SUBJECTS_DIR/bert1/mri/aparc.a2009s+aseg.mgz:colormap=lut:opacity=0.4

aseg.mgz：皮質下構造のセグメンテーション結果
aparc+aseg.mgz：Desikan-Killiany アトラスによる皮質の領域分割結果と aseg を合わせたもの
aparc.a2009s+aseg.mgz：Destrieux アトラス（a2009s）による皮質の領域分割結果と aseg を合わせたもの

* 旧バージョンで出力されていた aparc.a2005s は，FreeSurfer 7 では a2009s に置き換えられている。

ラベル値と名称の対応は，$FREESURFER_HOME/FreeSurferColorLUT.txt に記述されている。

gedit $FREESURFER_HOME/FreeSurferColorLUT.txt

各領域の体積，皮質厚などの統計値は，stats ディレクトリ内のファイル（.stats）に記述されている。

aseg.mgz に対応する統計値

gedit $SUBJECTS_DIR/bert1/stats/aseg.stats

aparc+aseg.mgz に対応する統計値

gedit $SUBJECTS_DIR/bert1/stats/lh.aparc.stats
gedit $SUBJECTS_DIR/bert1/stats/rh.aparc.stats

aparc.a2009s+aseg.mgz に対応する統計値

gedit $SUBJECTS_DIR/bert1/stats/lh.aparc.a2009s.stats
gedit $SUBJECTS_DIR/bert1/stats/rh.aparc.a2009s.stats

これらのファイルが生成されるのは，「recon-all -all -s サブジェクト名」あるいは「recon-all -autorecon3 -s サブジェクト名」が正常終了した後である。

実行結果の例

サーフェスデータのファイル形式の変換

Surface File 形式のサーフェスデータを asc 形式に変換する。

cd $SUBJECTS_DIR/bert1/surf
mris_convert lh.inflated lh.inflated.asc

asc 形式のサーフェスデータを Surface File 形式に変換する。

mris_convert lh.inflated.asc lh.inflated2

* 元のファイルの上書きを避けるため lh.inflated2 に保存している。

mris_convert は，STL，OBJ，VTK，GIfTI（.gii）などの形式への変換にも対応している。拡張子で出力形式が決まる。

mris_convert lh.inflated lh.inflated.stl

talairach 位置合わせのエラー

「recon-all -all -s サブジェクト名」の実行中に，talairach 位置合わせが失敗した場合，次のようなエラーメッセージが表示される。

ERROR: Talairach QA check failed!
transforms/talairach.xfm  ***FAILED***

対策として，手動で talairach 位置合わせを行う。次のコマンドを実行する。

tkregisterfv --s サブジェクト名 --fstal --surf orig

* サーフェスがまだ生成されていない場合は --surf orig を外して実行する。

上記コマンドを実行すると、操作ウインドウと画像ウインドウの2画面が表示される。

調節に必要なボタン

SAVE REG　:　調節した結果を保存
CORONAL　：　Coronal View
SAGITTAL　：　Sagittal View
HORIZONTAL　：　Horizontal View
SCALE BRAIN ：大きさを調節
TRANSLATE BRAIN　:　平行移動量を調節
ROTATE BRAIN　:　回転量を調整
TARGET ：画像ウインドウに入力画像を表示
MOVEABLE : 画像ウインドウにテンプレート画像を表示

左図：テンプレート画像（$FREESURFER_HOME/average/mni305.cor.mgz）右図：入力画像（orig.mgz）

矢状断（SAGITTAL）のスライス 128 で脳梁を目印に位置を合わせ，次に水平断（HORIZONTAL），冠状断（CORONAL）で正中線を合わせる。3 方向を切り替えながら調節を繰り返す。

調節が終わったら「SAVE REG」ボタンを押して保存し，再度 recon-all を実行する。talairach 変換は後続のすべての処理に影響するため，全手順をやり直す。

recon-all -all -s サブジェクト名

位置合わせの結果に問題がないことを目視で確認したうえで，自動チェックを通過しない場合には，-notal-check を付けて自動チェックを行わずに実行する。

recon-all -all -s サブジェクト名 -notal-check

別の方法として，MNI の mritotal を用いた位置合わせを試すこともできる。-clean-tal は既存の talairach.xfm を削除する。

recon-all -s サブジェクト名 -talairach -use-mritotal -tal-check -clean-tal