billy-lyc/neuropilot/brainmask-fix

Claude Code and agent skill by billy-lyc/neuropilot

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

Install

npx vskill@latest install billy-lyc/neuropilot/brainmask-fix

SKILL.md

Brainmask Fix Skill (FreeSurfer autorecon3)

修复 FreeSurfer brainmask.mgz，改善 pial 表面放置效果。

何时触发此 skill

  • pial 表面明显超出脑组织，或切割了脑皮层
  • brainmask.mgz 视觉检查发现 overflow（颅骨包入）或 missing（脑组织排除）
  • autorecon3 结束后 Euler number 异常（< −500）

必须遵守的规则

  1. 绝对不修改源数据目录下的任何文件（只读）——所有输出写入 $QC_OUT
  2. 修改前先备份原始文件
  3. 所有 Python 操作在原生空间（加载 MGZ 时不用 as_closest_canonical()）
  4. Freeview 坐标是 RAS，操作前必须用 r2n() 转成原生索引
  5. 保存时用 orig.mgz 真实 T1 信号（不用 0/1 二值）

目录结构约定

TEST_BASE=/path/to/work
$TEST_BASE/$SUBJECT/orig/   — orig.mgz, brainmask.mgz, (brainmask.synthstrip.mgz)
$TEST_BASE/$SUBJECT/fixed/  — brainmask_fixed.mgz（pipeline 输出）

FreeSurfer SUBJECTS_DIR（最终应用）：

$SUBJECTS_DIR/$SUBJECT/mri/brainmask.mgz
$SUBJECTS_DIR/$SUBJECT/mri/brain.finalsurfs.mgz  ← autorecon3 真正用这个

主脚本

$BRAINMASK_FIX/run_fix.py
bash
SCRIPT=$BRAINMASK_FIX/run_fix.py
PY=${QC_PYTHON:-$QC_SKILL/.venv/bin/python3}   # bash setup_env.sh creates .venv
BASE=/path/to/work
SUBJ=sub-xxx

完整交互流程

Step 0: 用户给出 subject
bash
# 设置变量
SUBJ=sub-xxx
Step 1: init（SynthStrip + 交集）
bash
$PY $SCRIPT --base $BASE --subj $SUBJ init

输出：

  • $BASE/$SUBJ/orig/brainmask.synthstrip.mgz（如果不存在会自动运行 SynthStrip）
  • $BASE/$SUBJ/fixed/brainmask_fixed.mgz（初始交集 base mask）
  • $BASE/$SUBJ/fixed/init_comparison.png（4列对比图：orig / syn / 交集 / orig-only 溢出区域）

→ 用 SendUserFile 发送 init_comparison.png 给用户 → 让用户在 Freeview 打开 fixed/brainmask_fixed.mgz，逐个报告可疑坐标

Freeview 命令给用户：

bash
freeview \
  $BASE/$SUBJ/orig/orig.mgz \
  $BASE/$SUBJ/fixed/brainmask_fixed.mgz:colormap=heat:opacity=0.5
Step 2: 用户报告问题坐标

用户报告格式：

RAS_x x RAS_y x RAS_z: orig_val, mask_val

判断类型：

条件类型操作
orig > 80, mask_val = 0MISSING — 脑组织被排除add_missing
orig < 75, mask_val > 0OVERFLOW — 颅骨/非脑包入rm_overflow
orig 75-100, mask_val > 0，不确定可疑先 viz 查看，再决定

先用 viz 确认坐标：

bash
$PY $SCRIPT --base $BASE --subj $SUBJ viz --ras X Y Z
Step 3a: 修复 MISSING

方法选择：

信号场景方法典型参数
orig > 100高信号灰白质dilation--iterations 8 --thresh 85
orig 50-100低信号/CSF/薄皮层sphere--radius 9 --thresh 50
边界截断mask 边缘刚好切掉一条脑回sphere（偏移）--radius 12 --thresh 88
bash
# 高信号区域（dilation）
$PY $SCRIPT --base $BASE --subj $SUBJ add_missing \
  --ras X Y Z --method dilation --iterations 8 --thresh 85
 
# 低信号/CSF（sphere）
$PY $SCRIPT --base $BASE --subj $SUBJ add_missing \
  --ras X Y Z --method sphere --radius 9 --thresh 50

sphere radius 怎么选：

  1. 询问用户附近是否有已知 OVERFLOW 点
  2. 计算 r2n(ras_miss) 到 r2n(ras_ovf) 的距离
  3. 设 radius < 该距离（留 1-2 voxel 余量）

输出：生成 after_add_*.png → 发给用户确认

Step 3b: 修复 OVERFLOW
bash
$PY $SCRIPT --base $BASE --subj $SUBJ rm_overflow \
  --ras X Y Z --radius 25 --thresh 75

radius 怎么选：

  • 颅骨大片区域（inferior slice）：radius=25-35
  • 小片孤立区域：radius=15-20

thresh 怎么选：

  • 颅骨/头皮：thresh=65（orig < 65）
  • 颈部软组织：thresh=80
  • 不要 设 > 80，否则可能误删薄皮层

输出：生成 after_rm_*.png → 发给用户确认

Step 4: 逐点验证

每次用户说"好了"之后运行：

bash
$PY $SCRIPT --base $BASE --subj $SUBJ verify \
  --points "MISS X1 Y1 Z1" "OVF X2 Y2 Z2" "OVF X3 Y3 Z3"

打印每个点的状态（✓/✗）。

Step 5: 应用到 FreeSurfer（只在用户确认后执行）
bash
FS_SUBJ_DIR=/path/to/freesurfer/$SUBJ
 
# 备份
cp $FS_SUBJ_DIR/mri/brainmask.mgz        $FS_SUBJ_DIR/mri/brainmask.mgz.preEdit
cp $FS_SUBJ_DIR/mri/brain.finalsurfs.mgz $FS_SUBJ_DIR/mri/brain.finalsurfs.mgz.preEdit
 
# 覆盖
cp $BASE/$SUBJ/fixed/brainmask_fixed.mgz $FS_SUBJ_DIR/mri/brainmask.mgz
cp $BASE/$SUBJ/fixed/brainmask_fixed.mgz $FS_SUBJ_DIR/mri/brain.finalsurfs.mgz
Step 6: 运行 autorecon3
bash
module load freesurfer/7.4.1
export SUBJECTS_DIR=/path/to/freesurfer
recon-all -autorecon3 -subjid $SUBJ -notalairach

坐标系快速参考

python
def r2n(ri, rj, rk):
    """Freeview RAS → native array index"""
    return (255 - ri, 255 - rk, rj)
# FreeSurfer conformed space: 256³ 1mm, native axes ('L','I','A')
# Freeview 显示 RAS，操作数组必须在 native 空间

诊断：体素来自哪个 mask？

python
ni, nj, nk = r2n(X, Y, Z)
print(f"brk={brk_d[ni,nj,nk]}  syn={syn_d[ni,nj,nk]}  fixed={fixed_d[ni,nj,nk]}")
brksynfixed来源
001纯新增（我们加的）
101仅 brk 有（交集已排除，我们又加回来）— 检查是否正确
011仅 syn 有（交集已排除，我们又加回来）— 检查是否正确
110两者都有，我们删除了 → 是 OVF
111交集正常保留

脚本路径

脚本用途
run_fix.py主 pipeline（init/add_missing/rm_overflow/verify/viz）
templates/fix_script_template.py手动操作模板（复杂情况）
templates/param_sweep.py三参数对比可视化（给用户选 radius）
01_prepare.md ～ 06_rerun.md各步骤详细说明

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
54
Repository forks
5
7-day trend score
20

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/billy-lyc/neuropilot/brainmask-fix/badge)](https://verified-skill.com/skills/billy-lyc/neuropilot/brainmask-fix)

Something wrong with this skill or its page? Tell us.