Freesurfer Tool

FreeSurfer Tool

Overview

FreeSurfer is the gold-standard open-source suite for automated reconstruction of the brain’s cortical surface from structural MRI, including skull-stripping, intensity normalization, Talairach registration, cortical parcellation (Desikan-Killiany / Destrieux atlases), subcortical segmentation (aseg), surface mesh generation, cortical thickness estimation, and statistics.

This skill serves as the NeuroClaw interface-layer wrapper for FreeSurfer and strictly follows the hierarchical design:

1. Check whether FreeSurfer is installed (recon-all --version, $FREESURFER_HOME environment variable).
2. If not found → immediately invoke dependency-planner to plan and (after user confirmation) install the latest stable FreeSurfer release + license setup.
3. Collect and confirm: input NIfTI file(s), subject ID, output SUBJECTS_DIR, desired stages/flags (e.g. -all, -autorecon1..3, -T2, -FLAIR, -parallel).
4. Generate a clear, numbered execution plan including exact shell commands.
5. Present plan, estimated runtime, disk/RAM requirements, and risks → wait for explicit user confirmation (“YES” / “execute” / “proceed”).
6. On confirmation → delegate all shell command execution to the claw-shell skill (environment setup, recon-all invocation, logging, progress monitoring).
7. Report completion status, log location, output directory, and next steps.

Key design principle (2026 update): No direct subprocess.run() calls for long-running FreeSurfer commands. All shell execution is routed through claw-shell for centralized logging, timeout handling, real-time output streaming, and interruption safety.

Research use only.

Quick Reference (Common Use Cases)

Installation Check & Setup

Installation is fully delegated to dependency-planner.

When FreeSurfer is not detected:

• Call dependency-planner with request:
  "Install latest stable FreeSurfer (8.1.0 or newer) on current OS, including license.txt setup"
• After user confirms the installation plan → dependency-planner handles download, package install, license placement
• This skill then verifies $FREESURFER_HOME and recon-all availability

Prerequisites:

• dependency-planner (mandatory for installation)
• claw-shell (mandatory for command execution)
• Valid FreeSurfer academic license (free registration required)
• ≥16 GB RAM recommended (32 GB+ strongly preferred for -all)

Agent Reference Rule

When the agent needs FreeSurfer processing implementation code, it should first consult the curated snippet in skills/freesurfer-tool/scripts/ instead of copying from the embedded wrapper below.

Reference snippet available:

• scripts/freesurfer_processor.py -> recon-all pipeline orchestration: environment setup, stage selection, parallel flags, claw-shell delegation

Example:

python skills/freesurfer-tool/scripts/freesurfer_processor.py \
    --input-mri sub-001_T1w.nii.gz \
    --subjid sub-001 \
    --subjects-dir /data/freesurfer_output \
    --stages all \
    --extra-flags "-T2 T2.nii.gz -parallel -openmp 12"

NeuroClaw recommended wrapper script

# freesurfer_processor.py
import argparse
import os
import sys
from pathlib import Path
from datetime import datetime

# In real NeuroClaw: these would be agent tool calls
def check_freesurfer_installed():
    # Simulate check via claw-shell
    # Real impl: call claw-shell with "recon-all --version"
    return False, "FreeSurfer not found (simulation mode)"

def delegate_to_claw_shell(commands, purpose, log_tag):
    print(f"[Delegating to claw-shell] Purpose: {purpose}")
    print(f"Log tag: {log_tag}")
    print("Commands to execute:")
    for cmd in commands:
        print("  " + cmd)
    # Real implementation: agent/tool call to claw-shell
    # e.g. tool_call("claw-shell", commands=commands, log_tag=log_tag, capture_output=True, timeout="24h")

def main():
    parser = argparse.ArgumentParser(description="NeuroClaw FreeSurfer Processor")
    parser.add_argument("--input-mri", required=True, help="Path to T1w (or other) NIfTI file")
    parser.add_argument("--subjid", required=True, help="Subject ID (e.g. sub-001)")
    parser.add_argument("--subjects-dir", required=True, help="Output SUBJECTS_DIR path")
    parser.add_argument("--stages", default="all", help="all / autorecon1 / autorecon2 / autorecon3 / stats / comma-separated stages")
    parser.add_argument("--extra-flags", default="", help="Additional flags, e.g. '-T2 T2.nii.gz -FLAIR FLAIR.nii.gz -parallel -openmp 12'")
    parser.add_argument("--plan-only", action="store_true", help="Show plan without execution")
    args = parser.parse_args()

    installed, version_info = check_freesurfer_installed()
    if not installed:
        print("FreeSurfer not detected on system.")
        print("→ Invoking dependency-planner to install FreeSurfer and set up license.")
        print("Please complete the dependency-planner confirmation flow first.")
        sys.exit(1)

    print("FreeSurfer detected:", version_info)

    subjects_dir = Path(args.subjects_dir).resolve()
    print(f"\nProcessing plan for subject: {args.subjid}")
    print(f"Input MRI     : {args.input_mri}")
    print(f"Output dir    : {subjects_dir}")
    print(f"Stages        : {args.stages}")
    if args.extra_flags:
        print(f"Extra flags   : {args.extra_flags}")

    # Build shell commands
    commands = []
    # 1. Set environment
    fs_home = "/usr/local/freesurfer"  # typical default; adjust if needed
    commands.append(f"export FREESURFER_HOME={fs_home}")
    commands.append(f"source $FREESURFER_HOME/SetUpFreeSurfer.sh")

    # 2. recon-all command
    recon_cmd = [
        "recon-all",
        "-subjid", args.subjid,
        "-i", args.input_mri
    ]

    if args.stages == "all":
        recon_cmd.append("-all")
    elif "," in args.stages:
        for stage in args.stages.split(","):
            stage = stage.strip()
            if stage:
                recon_cmd.append(f"-{stage}")
    else:
        recon_cmd.append(f"-{args.stages}")

    if args.extra_flags:
        recon_cmd.extend(args.extra_flags.split())

    # Recommend parallel execution if not disabled
    if "-parallel" not in args.extra_flags and "-openmp" not in args.extra_flags:
        recon_cmd.extend(["-parallel", "-openmp", "8"])

    commands.append(" ".join(recon_cmd))

    log_tag = f"freesurfer_{args.subjid}_{datetime.now().strftime('%Y%m%d_%H%M%S')}"

    print("\nExecution plan (to be run via claw-shell):")
    for i, cmd in enumerate(commands, 1):
        print(f"Step {i}: {cmd}")

    print(f"\nEstimated runtime: 4–24 hours (full -all), 1–4 hours (segmentation stages only)")
    print(f"Disk usage: ~2–5 GB per subject")
    print(f"Logs will be captured by claw-shell under tag: {log_tag}")

    if args.plan_only:
        print("\nPlan-only mode — no execution performed.")
        return

    confirm = input("\nExecute now? Type YES to proceed: ").strip().upper()
    if confirm != "YES":
        print("Aborted by user.")
        return

    print("\nDelegating pipeline execution to claw-shell skill...")
    delegate_to_claw_shell(
        commands=commands,
        purpose=f"FreeSurfer processing for subject {args.subjid} ({args.stages})",
        log_tag=log_tag
    )

    print(f"→ Execution handed over to claw-shell.")
    print(f"→ Check logs using tag: {log_tag}")
    print(f"→ Final outputs will be in: {subjects_dir / args.subjid}")

if __name__ == "__main__":
    main()

Important Notes & Limitations

• All actual shell command execution is delegated to claw-shell (no direct subprocess calls for recon-all).
• Full -all pipeline is very long-running → claw-shell should support background/detached mode or long timeouts.
• Input must be NIfTI (.nii or .nii.gz); convert DICOM first using dcm2nii skill.
• Output follows standard FreeSurfer structure: $SUBJECTS_DIR/<subjid>.
• Windows users: strongly recommended to use WSL2 (installation handled by dependency-planner).
• License check: skill assumes license.txt is already in place after dependency-planner run.

When to Call This Skill

• User provides structural MRI (NIfTI) and wants automated FreeSurfer processing.
• Any mention of recon-all, aseg, aparc, cortical thickness, surface reconstruction, or FreeSurfer statistics.

Complementary / Related Skills

• dependency-planner → install FreeSurfer + license
• claw-shell → safe execution of long-running shell commands
• conda-env-manager → manage Python environment for post-processing FreeSurfer outputs

Reference

Official site: https://surfer.nmr.mgh.harvard.edu
Latest stable release (as of 2026): FreeSurfer 8.1.0 or newer
License registration: https://surfer.nmr.mgh.harvard.edu/registration.html
Documentation: https://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferWiki

Custom NeuroClaw skill created to integrate FreeSurfer safely into the hierarchical skill structure.

Curated reference snippet in this skill:

• skills/freesurfer-tool/scripts/freesurfer_processor.py

Post-Execution Verification (Harness Integration)

After FreeSurfer processing completes, this skill automatically invokes harness-core's VerificationRunner to validate output integrity:

Integrated verification checks:

from skills.harness_core import VerificationRunner, AuditLogger

verifier = VerificationRunner(task_type="freesurfer_processing")

# 1. Brain-extracted anatomy files
verifier.add_check("brain_extraction",
    checker=lambda: verify_brain_extraction(subjects_dir, subjid),
    severity="error"
)

# 2. Cortical surface files (white, pial)
verifier.add_check("surface_reconstruction",
    checker=lambda: verify_surface_files(subjects_dir, subjid),
    severity="error"
)

# 3. Cortical thickness bounds (1–4 mm range)
verifier.add_check("thickness_bounds",
    checker=lambda: verify_cortical_thickness_range(subjects_dir, subjid),
    severity="warning"
)

# 4. parcellation labels (aparc/aseg)
verifier.add_check("parcellation",
    checker=lambda: verify_aparc_aseg(subjects_dir, subjid),
    severity="error"
)

# 5. Statistics file completeness
verifier.add_check("statistics",
    checker=lambda: verify_stats_files(subjects_dir, subjid),
    severity="warning"
)

report = verifier.run(subjects_dir)

# Log verification results
logger = AuditLogger(log_file=f"{subjects_dir}/{subjid}/freesurfer_verification.jsonl")
logger.log_validation(
    task_name="freesurfer_processing",
    subject_id=subjid,
    checks_passed=len([r for r in report.results if r.passed]),
    total_checks=len(report.results)
)

Output: {SUBJECTS_DIR}/{subjid}/freesurfer_verification.jsonl (structured audit log with JSONL format)

Created At: 2026-03-19 20:00 HKT
Last Updated At: 2026-04-05 02:03 HKT
Author: chengwang96