FreeSurferおよびFastSurfer導入ガイド

機械学習



はじめに

脳画像解析における代表的なツールであるFreeSurferは、精神・神経科学研究において広く活用されています。さらにそれを高速化したFastSurferが登場しています。FreeSurferおよびFastSurferは、皮質厚や表面積、体積などの構造的指標の抽出において信頼性が高く、多くの論文で使用されています。

この記事では、実際に私が遭遇した課題や引っかかったポイントも含め、FreeSurferおよびFastSurferの導入方法を解説します。

1. FreeSurferの導入手順

1.1 FreeSurferライセンスの取得について

FreeSurferを使用するには、ライセンスファイル（無料）を取得し、インストールディレクトリに配置する必要があります。

公式サイトにアクセスし、名前・所属・メールアドレスを登録します。

メールで送られてくる “license.txt”を受け取ります。

ライセンスファイルを $FREESURFER_HOME に保存します。

mv ~/Downloads/license.txt $FREESURFER_HOME/license.txt

ライセンスがないと recon-all 実行時にエラーが発生し、解析が進まないため、必ず事前に登録しておきましょう。

1.2 インストール手順（macOS上）

FreeSurferのダウンロード（公式サイトからdmgファイルを取得）

DownloadAndInstall - Free Surfer Wiki
surfer.nmr.mgh.harvard.edu

インストーラを実行し、アプリケーションフォルダに配置する（例：/Applications/freesurfer）

.zshrcまたは.bash_profile に環境変数を設定

export FREESURFER_HOME=/Applications/freesurfer
source $FREESURFER_HOME/SetUpFreeSurfer.sh

反映させるには、ターミナルで以下を実行

source ~/.zshrc #または source ~/.bash_profile

補足： bashrcに追記すると毎回設定する必要がなくなります。

echo "export FREESURFER_HOME=/usr/local/freesurfer" >> ~/.bashrc
echo "source \$FREESURFER_HOME/SetUpFreeSurfer.sh" >> ~/.bashrc
source ~/.bashrc

インストールできたか試しに見てみます。

freeview -v $SUBJECTS_DIR/bert/mri/brain.mgz \
        -v $SUBJECTS_DIR/bert/mri/aparc+aseg.mgz:colormap=lut:opacity=0.3
freeview -f $SUBJECTS_DIR/bert/surf/lh.inflated:curvature=curv \
             $SUBJECTS_DIR/bert/surf/rh.inflated:curvature=curv

2. FastSurferの導入手順

FastSurferはFreeSurferと同等の精度を持ちつつ、ディープラーニングを用いて高速に処理が可能な代替ツールです。

2.1 前提条件

  • NVIDIA GPU（CUDA対応）推奨
  • 公式ではDockerが動作する環境推奨

2.2 導入方法

ここでは、手動ダウンロードによる導入方法（Dockerを使わない場合）を紹介します。

FastSurferはDockerを使用せずに手動でもセットアップ可能ですが、CUDA、PyTorch、依存パッケージの整合性に注意が必要です。

# リポジトリのクローン
git clone https://github.com/Deep-MI/FastSurfer.git
cd FastSurfer

# Python仮想環境の作成と有効化
python3 -m venv venv
source venv/bin/activate

# 必要パッケージのインストール
pip install -r requirements.txt

# チェックポイントのダウンロード
mkdir -p checkpoints
wget https://dl.deep-mi.org/fastsurfer/fastsurferCNN/ckpts/fastsurfer_deepnet.pt -P checkpoints/

注意：

  • fastsurfer_deepnet.pt はセグメンテーションCNNの学習済みモデルです。
  • CUDAとPyTorchのバージョンは公式のREADMEを参照して一致させる必要があります。
# macOSでのDockerのインストールは、公式サイト（https://www.docker.com/products/docker-desktop/）からDocker Desktopをダウンロード・インストールしてください。

# FastSurferのクローン
git clone https://github.com/Deep-MI/FastSurfer.git
cd FastSurfer

# Dockerイメージのビルド（macOS上でも可能。ただしGPUはLinux専用のため、処理自体はCPU）
docker build -t fastsurfer ..

引っかかりポイント例：

  • Dockerイメージのビルド中にメモリエラー（特にWSL2環境）
  • GPUがDockerから認識されない（–gpus all のために nvidia-container-toolkit が必要）

2.3 実行例（WSL2ではマウントやパスに注意）

FastSurferの主要オプション解説

–t1：処理対象のT1強調画像のパス（必須）

–sid：被験者ID（Subject ID）

–sd：出力先のsubjectsディレクトリ

–parallel：並列処理を有効化（CPU並列処理を一部サポート）

–batch：並列実行のスレッド数（GPUメモリに応じて調整）

–fs_license：FreeSurferのライセンスファイルのパス（必要な場合）

–no_cuda：CUDAを使用しない（CPU動作）

公式ドキュメント：https://github.com/Deep-MI/FastSurfer

sudo docker run --rm --gpus all \
-v $PWD:/data -v $PWD/output:/output \
fastsurfer \
--t1 /data/sub01_T1.nii.gz \
--sid sub01 \
--sd /output \
--parallel --batch 8

3. FreeSurferとFastSurferの比較と使い分け

特徴FreeSurferFastSurfer
精度高い（これまでの研究で多用）FreeSurferとほぼ同等
処理時間非常に長い（5〜8時間以上）非常に高速（30〜45分程度）
必要環境CPUでOKGPUで高速
トラブル頻度高い（依存関係やパス設定）Dockerに慣れれば比較的少ない

4. よくある質問（FAQ）

Q1: recon-allはどれくらい時間がかかる？
A: 通常のFreeSurferでは5〜8時間、FastSurferではGPU使用で30分〜45分程度です。FastSurferをCPUで実行する場合でも、FreeSurferよりも高速に処理されることが多く、実行環境によっては1〜2時間程度で完了するケースも報告されています。近年のFastSurferはCPUモードでも最適化が進んでおり、GPUがなくても実用的な処理時間で使用できます。

Q2: FastSurferで出力されるファイル形式は？
A: FreeSurferと同様に surf/ や stats/ ディレクトリが生成され、同じパイプラインで扱えます。

Q3: WSL2でも動作する？
A: 一部のユーザーは動作報告あり。ただしDockerのGPU認識やI/Oの速度低下に注意。

Q4: recon-allの進行状況がわかりづらい…
A: recon-all.log をtailすることで確認できます。tail -f $SUBJECTS_DIR/sub01/scripts/recon-all.log

まとめ

FreeSurferおよびFastSurferは、精神医学研究における脳画像処理に不可欠なツールです。特にFastSurferは近年のGPU環境を活かした高速処理が魅力ですが、環境構築や実行時のポイントには注意が必要です。本記事を参考に効率的な導入と活用を目指してください。



タイトルとURLをコピーしました