简介：CAT12.7作为SPM12生态中常用的脑结构影像分析工具箱，该安装包面向需要稳定复现形态学分析流程的神经影像研究者、医学研究生等入门与进阶用户。由于官方版本更新导致旧版下载入口被覆盖，这份压缩包完整保留了作者笔记对应的CAT12.7版本环境，可配合教程直接运行T1结构像预处理、灰质体积测量等操作。资源共822个文件，以312个m脚本、109个png示意图、43个gii表面数据、31个nii影像模板为主，同时包含Schaefer2018多个分辨率及HCP-MMP1脑图谱annot注释文件、适配Win/macOS/Linux平台的mex编译组件等，压缩后222.93MB，整体构成较完整的功能性子模块结构。目前已有1727人学习下载这一版本，适合希望使用与既有笔记匹配环境、快速获取皮层分区图谱与工具函数，减少自行配置老版本成本的读者。
1. 神经影像不是玄学：CAT12.7 安装包把 VBM 全流程做成了可复现管线
拿到一百个被试的 T1 结构像要做灰质体积比较，手写 VBM 流程至少两星期；用 CAT12.7 这个源码软件，环境配置好之后一个晚上能跑完全组数据。第一次拆包的人通常会被它几百个 .m 文件吓住，读透之后你会发现它就是一条从原始 T1 到灰质体积、皮层厚度的自动化管线，分割、配准、质量检查、统计接口全给你备好了。下文按我实际拆包、在服务器上跑通、再改脚本的顺序，讲清楚这个安装包怎么装、怎么跑、怎么改成自己的分析流程，给正准备在脑结构数据上做一次完整分析的开发者一个能直接落地的方案。
2. 安装包结构拆解：从源码目录看一个神经影像工具箱的设计
CAT12.7 和普通源码软件最大的区别在于，它的「安装」不是一个黑匣子安装程序，而是把整套源码摊开在你面前。这对做影像分析的组来说特别友好：任何参数你都可以顺着脚本追到它被使用的位置，出了问题不用瞎猜。
2.1 目录分工：几百个 .m 文件不是乱摊子
CAT12.7 解压后是一个 cat12 文件夹，我一般直接放进 SPM12 的 toolbox 目录，这样 SPM 启动时能顺着工具箱扫描逻辑自动发现它。顶层堆着大量 .m 文件，命名规律很强：cat_ 前缀是 CAT 主逻辑，spm_ 前缀是 SPM 的扩展，剩下的是内部工具。按前缀分组基本能定位任何功能。
| 文件/目录 | 职责说明 |
|---|---|
| cat_defaults.m | 全局默认参数，GUI 与脚本共用一份配置 |
| cat_main.m | 分割与归一化主流程入口 |
| cat_conf_estwrite.m | 预处理 job 配置定义，对应 GUI 的 Segment Data |
| cat_conf_long.m | 纵向分析 job 配置 |
| cat_vol_*.m | 体数据工具集：裁剪、重采样、偏置场校正 |
| cat_surf_*.m | 表面网格生成、皮层厚度计算 |
| cat_long_*.m | 个体内纵向配准与分割 |
| cat_roi / cat_atlas | 图谱与 ROI 统计 |
| tpl/ | TPM、DARTEL 模板、脑图谱 |
| xml/ | 质量协议与报告样式 |
| internal/ | 内部实现，不建议直接调用 |
这个表值得对着自己解压出来的包过一遍。写批处理脚本时打交道最多的是 cat_conf_estwrite.m 和 cat_conf_long.m，想知道 GUI 上某个下拉框对应脚本里的哪个字段，直接在这两个文件里搜界面文案最快，比翻文档都准。
2.2 依赖链：为什么 CAT12.7 不能脱离 SPM12 单独跑
CAT12.7 本质上不是一个独立软件，而是一个寄生在 SPM12 里的工具箱。数据读写走 spm_vol、spm_read_vols，批处理依赖 spm_jobman，归一化复用 SPM 的形变场框架，平滑调 spm_smooth。换句话说，SPM12 提供基础设施，CAT12 提供脑形态学分析的专业逻辑，两者合起来才是一条完整链路。
版本搭配上，MATLAB 建议 R2018b 及以上，版本太老会出现函数找不到之类的诡异报错；SPM12 也要用较新的修订版。机器上如果有并行计算工具箱，nproc 参数才能享受到多核加速，否则只能单核跑，全组数据的时间会拉得非常长。
2.3 tpl 模板目录：结果落在哪个空间由它决定
tpl 目录很容易被忽略，但它的地位很关键。TPM.nii 是组织概率图，分割时判定体素属于灰质、白质还是脑脊液的先验就来自这里；DARTEL 模板用于把个体数据归一化到公共空间，保证不同被试的脑区能对上；atlas 子目录里放着若干脑图谱，做 ROI 统计时按图谱编号提取值。
我见过有人把脚本里的模板路径指错位置，一批数据全跑出空间错位的结果。血泪经验是：模板路径永远用 fullfile(spm('dir'), 'toolbox', 'cat12', 'tpl', ...) 拼出来，不要手写绝对路径，否则换机器、换环境就要改一遍。
2.4 质量检查机制：xml 报告不是事后补丁
CAT12.7 在预处理阶段就内置了质量检查，每次处理完会生成一份 xml 质量报告，核心指标包括整体质量等级、表面质量分数这些。服务器上没图形界面也能生成网页版报告，评审或存档时直接甩链接给组里其他人，比一张截图清楚得多。这个设计思路值得学：质量信息在产出阶段就跟着数据走，而不是等统计分析完才发现某几个被试的数据是废的。
3. 环境搭建与首次运行：把安装包变成能出结果的流程
从拆包到跑出第一份结果，最长的一段路通常是环境问题。下面按我自己的顺序走一遍，每一步卡住都有对应的排查点。
3.1 环境准备：三件事先确认
装之前先确认三件事。第一，MATLAB 版本在 R2018b 以上，可以从 about 界面看版本号，版本太老会在启动阶段报错；第二，SPM12 已经能正常打开 GUI，这样 CAT12 的按钮才有地方挂；第三，确认有没有并行计算工具箱，没有的话后面 nproc 只能写 1，速度会差好几倍。
磁盘空间也别省。单被试的完整输出包括 p 系列、mwp1、形变场、表面数据，加起来 5 到 10 GB 很常见。全组一百个被试之前先算好剩余空间，别跑一半磁盘写满，MATLAB 会直接崩给你看。
3.2 安装步骤：路径正确比什么都重要
% 在 MATLAB 中把 SPM12 与 CAT12.7 加入路径 spm12_path = '/opt/spm12'; cat12_path = '/opt/spm12/toolbox/cat12'; addpath(spm12_path); addpath(cat12_path); % 只加根目录，不要用 genpath savepath;这里特意强调：只 addpath(cat12_path)，不要图省事写成 genpath(cat12_path)。internal 等子目录里有些通用函数名会和 SPM 自带函数重名，一旦路径顺序不对，启动时会报一堆 Undefined function。我在这上面翻过一次车，后来规规矩矩只加根目录，再没出过问题。
保存路径后重启 MATLAB，命令行输入 spm 打开主界面，右侧会出现 CAT12 按钮，点进去能看到 Segment Data、Longitudinal、Surface 等入口，说明安装成功。按钮没出现，先检查路径是不是真的保存进 startup.m 或 matlabrc 了。
3.3 首次运行：单被试先跑通再谈批量
装完之后最忌讳的就是直接丢全组数据进 GUI。先用一个 T1 数据，在 Segment Data 界面手工跑通，观察命令行输出和产物文件，这样比出错了再大海捞针地排错高效得多。
首次运行结束后，输出目录应该出现 p 系列、mwp1 前缀的文件，以及 surf 子目录。用下面命令快速验证：
ls *p0* *p1* *p2* *mwp1* 2>/dev/null ls surf/命令行里出现 CAT12 版本信息且没有报错，单被试验证就算通过。这一步是后悔药：单被试只要几分钟，出问题能立刻定位；直接跑批量的话，几十个被试的错误混在一起，翻日志都能翻到头大。
3.4 输出产物解读：p0、p1、p2、mwp1 分别是什么
跑完后目录里多了一堆缩写文件，第一次看容易懵。快速对照表：
| 产物 | 含义 |
|---|---|
| p0_* | 原始空间的组织分割图 |
| p1_* | 归一化到模板空间的组织图 |
| p2_* | 归一化并调制后的组织图 |
| mwp1_* | 调制灰质图，VBM 统计直接用它做平滑后比较 |
| surf/lh.thickness | 左半球皮层厚度 |
| cat_*.mat | 该被试的体积标量与质量指标 |
调制（modulation）这一步很关键：乘上形变场的雅可比行列式，保留脑区体积信息。如果只做密度分析不关心体积，可以不勾调制，但经典 VBM 默认是调制的。
4. 核心模块拆解：从 T1 到灰质体积的关键处理链路
跑通一次之后，就该把黑匣子打开看看里面到底发生了什么。CAT12.7 的处理链路可以拆成三块：分割、表面重建、批处理封装。
4.1 分割主流程：一次 estwrite 到底做了什么
estwrite 是 estimate + write 的缩写，一次任务里同时完成参数估计和结果写出。大致顺序是：
- 读入 T1，做偏置场校正和强度归一化，消除扫描仪场不均匀性；
- 仿射配准到参考空间，让数据大致摆到一个公共位置；
- 基于 TPM 先验和图像强度做混合模型分类，估计每个体素属于灰质、白质、脑脊液的概率；
- 用 DARTEL 做非线性配准，把个体形变场估计出来；
- 按设定输出调制或未调制的组织图。
脚本里几个常用参数的含义要理解到位。nproc 是并行核数，设成机器核数的一半比较稳；affreg 控制仿射配准参考，东亚人群数据用 eastern 比默认 mni 更不容易在深部结构上漂；ngaus 是每个组织类别的高斯分量数，默认值对大多数数据够用，但数据噪声大的时候试着降一档，分割会更平滑；denoise 打开后会对图像做自适应降噪，对老式扫描仪数据特别管用。
4.2 表面重建与皮层厚度：从体积分割到网格
分割完成后，如果想做皮层厚度分析，需要走表面重建这一步。CAT12.7 会把灰质概率图转换成左右半球的网格表面，再沿着表面法线方向计算皮层厚度。这个投影算法在 cat_surf_*.m 里实现，不需要你手动设置复杂的平滑参数。
表面输出是一组 gifti 格式文件，常见的是 lh.thickness、rh.thickness 以及 central、area 这些网格数据。皮层厚度不是标量图，而是每个网格顶点一个值，所以后续做统计时不能直接套用体积分析的 SPM 流程，一般要先做表面平滑，再做顶点水平的组间比较。这一步很多人会忽略，结果就是用错了模态。
4.3 批量处理脚本实战：一个循环跑完整组被试
GUI 能用的功能，批处理脚本里都有对应字段。我一般先在 GUI 里配好一次，点 Save Batch 生成脚本，再把被试循环套进去。下面是一个完整的全组 VBM 批处理脚本：
% CAT12.7 全组 VBM 批量脚本 clear; clc; spm('defaults', 'fmri'); spm_jobman('initcfg'); % 被试列表，按你的目录结构改 subjects = {'sub-01', 'sub-02', 'sub-03'}; base = '/data'; for i = 1:numel(subjects) t1 = fullfile(base, subjects{i}, 'anat', [subjects{i} '_T1w.nii']); if ~exist(t1, 'file') warning('缺失 %s，跳过', t1); continue; end matlabbatch{1}.spm.tools.cat.estwrite.data = {t1}; matlabbatch{1}.spm.tools.cat.estwrite.nproc = 4; matlabbatch{1}.spm.tools.cat.estwrite.opts.tpm = {... fullfile(spm('dir'), 'toolbox', 'cat12', 'tpl', 'TPM.nii')}; matlabbatch{1}.spm.tools.cat.estwrite.opts.affreg = 'eastern'; matlabbatch{1}.spm.tools.cat.estwrite.opts.ngaus = 2; matlabbatch{1}.spm.tools.cat.estwrite.opts.denoise = 1; matlabbatch{1}.spm.tools.cat.estwrite.output.GM.native = 1; matlabbatch{1}.spm.tools.cat.estwrite.output.GM.mod = 1; matlabbatch{1}.spm.tools.cat.estwrite.output.surface = 1; try spm_jobman('run', matlabbatch); catch err fprintf('【失败】%s: %s\n', subjects{i}, err.message); end enddata 字段必须用 cell 包装，漏掉花括号的话 spm_jobman 会直接报错；nproc 按机器核数的一半设，16 核机器写 8 没问题，8 核机器写 2 到 4 比较稳；opts.tpm 指向 tpl 目录里的 TPM.nii，不要写死绝对路径。try/catch 包裹循环的好处是，单个被试失败不会中断整组任务，日志里能留下失败原因。
提示：CAT12 不同小版本的 batch 字段名偶有调整。最可靠的做法是先在 GUI 里配好参数点 Save Batch，生成的脚本字段一定和你手头的版本匹配，再往自己的循环里套。
跑完之后，每个被试目录会生成 cat_*.mat 文件，里面存着 TIV、灰质总体积、白质总体积这些标量。抽全组指标的小循环：
% 汇总全组体积指标 subjects = {'sub-01', 'sub-02', 'sub-03'}; for i = 1:numel(subjects) m = dir(fullfile(base, subjects{i}, 'cat_*.mat')); if isempty(m), continue; end S = load(fullfile(m.folder, m.name)); % 字段名可能随版本变化，先 fieldnames(S) 确认一下 fprintf('%s TIV=%.2f\n', subjects{i}, S.TIV); end字段名我吃过一次亏，当时直接按别人博客里写的字段取，结果全是空值。后来统一先 fieldnames 看一遍再取，一分钟的事能省半天排查。
5. 避坑指南：从装不上到算不对的五个典型问题
这部分是我和几个做过同一批数据的同学踩坑总结，每条都按现象、原因、解决三段写，遇到同症状直接照着处理。
5.1 路径与版本类问题
坑一：启动 CAT12 报 Undefined function 或按钮不出现
现象：MATLAB 命令行输入 spm 能打开主界面，但右侧没有 CAT12 按钮，直接调 cat_main 报 Undefined function。
原因：SPM12 和 CAT12 的路径加载顺序反了，或者 genpath 把 internal 子目录加进了路径，导致同名函数互相覆盖。
解决：先 addpath SPM12 根目录，再 addpath cat12 根目录，只加根目录，重启 MATLAB。如果还不行，用 pathtool 检查重复路径，把旧的 cat12 路径删干净。
坑二：输出目录里没有 surf 文件夹
现象：分割和归一化结果都正常，但 surf 目录不存在，厚度数据无从谈起。
原因：estwrite 界面的 surface 输出选项没勾选，默认配置不生成表面。
解决：在 batch 里确认 output.surface = 1，或者在 GUI 里把 Surface and thickness 勾上后再保存脚本。检查字段时对着自己的 GUI 版本看，不同小版本字段名略有不同。
坑三：脚本写好了但 spm_jobman 不认
现象：自己手写的 matlabbatch 结构，spm_jobman('run', matlabbatch) 直接报 config 错误。
原因：手写字段名和当前版本的配置定义不一致，最常见的是把 nproc 和 opts 写到了错误的结构层级。
解决：先进 GUI 点一遍 Segment Data，设置完参数后 Save Batch，拿生成的脚本对照自己的结构，只改 data 和被试循环，其他原样保留。
5.2 数据与计算资源问题
坑四：内存不足，MATLAB 直接崩
现象：跑第一个被试时系统内存耗尽，MATLAB 进程被杀，命令行窗口直接消失。
原因：nproc 设成了机器核数，每个核同时加载模板和图像数组，16G 内存的机器根本扛不住 8 个核的体数据运算。
解决：nproc 设成核数的一半；服务器上跑之前用 free -g 看实际可用内存；单被试验证时先用 nproc=1，确认数据没问题再并行。
坑五：一部分被试结果里厚度图是花斑，质量报告显示 D 级
现象：分割表面出来了，但厚度图视觉上噪声很大，xml 报告里质量等级落在 D，形态学明显不可信。
原因：头动伪影或脑组织外残留严重，分割阶段把非脑组织当成了灰质，表面重建把噪声投影成了厚度峰值。
解决：回到原始 T1 检查是不是有伪影；试着把 denoise 打开再跑一次；还不行就手工调整偏置场强度参数重跑。如果三种办法都救不回来，直接标记该被试为质量不合格，别硬塞进组间统计，否则分析结果会被几个离群点带偏。
6. 二次开发思路：把 CAT12.7 嵌进你自己的分析流水线
跑通全组数据只是起点，真正能让效率翻倍的，是把这套处理嵌进你自己的项目里，让数据从进目录到出报表中间不需要人守在旁边。
6.1 从 GUI 参数到可复用脚本
我现在的组织方式是：每个项目一个总脚本，被试列表、T1 路径、输出目录全部由总脚本生成，CAT12 的 batch 只负责最核心的处理逻辑。路径不再手写，而是从项目配置里读。这样换电脑、换服务器，只改一处配置文件，整个流水线照跑。
6.2 把质量指标和体积数据汇总成一张表
前面提到的 cat_*.mat 和 xml 报告，可以统一抽出来合成 CSV。我一般会在批量跑完后自动跑一个收集循环，把每个被试的 TIV、组织体积、质量等级写进一张表，然后在统计阶段直接按这张表排除不合格被试。这一步以前都是人工翻报告，后来做成脚本，半天的工作变成三分钟。
6.3 与统计模块衔接
VBM 的 mwp1 图在平滑之后，可以直接进 SPM 的 second-level 做组间比较；皮层厚度则是走 gifti 表面统计。要做的就是把预处理输出和统计模块的输入目录对齐，别让两个阶段的数据组织方式打架。
那次全组跑完发现一半数据没有 surf 输出以后，我每次拿到新安装包都会先单被试验证、再全组批量，这个流程帮我挡住了不少翻车。希望帮到你。
本文还有配套的精品资源，点击获取
