简介：CAT12.7 安装包面向从事神经影像与脑结构 MRI 分析的科研人员和学生，尤其适合需要在 SPM 环境下完成 T1 图像预处理、皮层厚度估计与脑形态测量的用户，也适合已有 MATLAB 与 SPM 基础、希望减少环境配置阻碍的中高级学习者。压缩包共 822 个文件，约 222.93MB，包含大量 MATLAB 脚本与函数、跨平台 MEX 组件、HTML 说明页面、NIfTI 影像、PNG 示意图，以及 FreeSurfer 格式的脑区 annot 图谱、模板和 mask 等配套数据，基本覆盖工具箱运行、分区分析与结果核验所需内容。已有 1731 人学习下载，说明该版本在相关学习笔记和实操流程中被较多使用。对于沿用旧版教程、希望复现 T1 处理步骤的读者，可从中获得较完整的 CAT12 目录结构、脚本函数、图谱模板与示例数据，便于在 MATLAB/SPM 中配置路径、检查依赖并开展皮层表面与脑区指标分析，也能为旧版流程迁移和新版工具对比提供参考。

1. 一个装着上万行 MATLAB 代码的 CAT12.7 版本安装包，到底解决什么问题

凌晨两点，一份三十个被试的 T1 结构像还在机器上排队跑分割，跑到第二十七个突然抛错退出，前二十六个的结果白跑一遍——这种崩溃只要经历过一次，就会开始重视安装包和批处理脚本本身。CAT12.7 版本安装包解决的就是这件事：它把基于 SPM12 的计算解剖工具箱完整打包下来，让 T1 加权像的组织分割、颅内体积估计、基于体素和基于表面的形态学分析能在本机一次性对齐环境。适合两类人：手上有一批 DICOM 或 NIfTI 结构像、要算出灰质体积或皮层厚度指标的影像数据处理开发者；以及想把分割步骤嵌进自己分析流水线、需要稳定复现结果的研究型工程师。它本质是一份源码软件，不是双击就能用的桌面应用。

2. 目录结构与运行环境：cat12、spm12 和 MATLAB 三方怎么对齐

拿到安装包之后最忌讳的一件事，就是直接解压、双击、启动，然后被一堆 "Undefined function" 挡在门外。CAT12 不是独立程序，它是一层跑在 SPM12 之上、SPM12 又跑在 MATLAB 之上的工具箱，三者版本必须像齿轮一样咬住。这一章先把目录看清楚，再把路径理清楚，最后处理没有 MATLAB 授权的那种情况。

2.1 解压后先看这五个位置

解压安装包之后，正常情况下会看到两类顶层目录：一个是spm12，一个是cat12。后者才是主角，前者是依赖。进入cat12之后，真正需要认识的只有下面这几块，其余大多是函数文件和数据模板：

为什么要先看清tpm和templates_*：这两个目录决定了分割和归一化的默认行为，很多"结果不对"的报障追到最后，是有人为了省空间把模板目录删了，或者拷了个旧版本模板混进来。我第一次整理工具箱时就把tpm单独挪到了别处，结果每次分割都报找不到组织概率图，翻了半小时日志才发现是自己埋的雷。

另外要认一下cat12/external下面有没有随包带的表面处理组件。做基于表面的分析时，这一层缺东西会在后期重建阶段才暴露，前面分割一切正常，等到算厚度才断，排查成本非常高。装完先跑一个被试，把全链路走通，比事后救火划算得多。

2.2 MATLAB 路径顺序与启动自检

CAT12 的路径注册有一个顺序要求：SPM12 必须先于 CAT12 进入搜索路径。原因是 CAT12 启动时会做一次 SPM 版本探测，探测不到就直接终止。反过来把 CAT12 放前面，虽然函数也能找到，但版本检查拿到的可能是空值。

% 先清场，避免旧版本残留干扰 restoredefaultpath; % 1) SPM12 先入路径，注意这里用 addpath 而不是 genpath addpath('/opt/toolboxes/spm12'); % 2) CAT12 需要递归加入，它下面还有子目录依赖 addpath(genpath('/opt/toolboxes/cat12')); % 3) 固化下来，下次启动不用重敲 savepath; % 4) 自检：能打印出版本号才算装通 disp(which('spm')); disp(which('cat12'));

这段里几个细节值得说。restoredefaultpath是我踩坑之后养成的前置动作，很多"函数冲突"类报错其实是用户目录下残留了一份老的spm文件夹，新旧混用导致行为诡异。addpath和genpath的区别在于：SPM12 只加顶层目录就够了，它的子目录由自身的初始化逻辑处理；CAT12 则必须用genpath把子目录全部铺开，否则调用到深层函数时会报未定义。

验证环节不要只看which的返回值，还要真正启动一次图形界面：

% 启动 SPM 主界面，这是 CAT12 能加载的前提 spm('defaults','FMRI'); spm_jobman('initcfg'); % 再启动 CAT12，正常会弹出一个独立窗口 cat12;

spm('defaults', ...)里的参数决定了一组全局默认值，做结构像处理一般用FMRI或PET都可以，差别主要在滤波和缩放策略上。spm_jobman('initcfg')这一步很多人漏掉，它负责初始化批处理系统的配置缓存，漏了之后在某些 MATLAB 版本上调用spm_jobman('run', ...)会报配置结构不完整。窗口能弹出来、下拉菜单里能看到 CAT12 条目，环境就算对齐了。

2.3 没有 MATLAB 授权时走独立版

现实里经常遇到的情况是：分析机器上没有 MATLAB 商业授权，或者授权被别的节点占着。安装包里如果带了独立运行版本，走的是 MATLAB Runtime 路线，原理是编译器把工具箱和运行库打包成不依赖 MATLAB 的可执行文件。

独立版的验证方式和工具箱版完全不同，不需要进 MATLAB，直接在终端跑：

# 先确认运行库能被找到 export LD_LIBRARY_PATH=/opt/toolboxes/MCR/v97/runtime/glnxa64:$LD_LIBRARY_PATH # 用最小输入试跑，输出目录必须提前建好 /opt/toolboxes/cat12_standalone/run_cat12.sh \ /opt/toolboxes/MCR/v97 \ /data/sub-01/anat/sub-01_T1w.nii \ /data/sub-01/out

第一行是运行库路径，v97这类版本号必须和打包时用的 MATLAB 版本严丝合缝对上，差一个版本就会报找不到libmwmclmcrrt.so。第二段的三个参数依次是运行库根目录、输入文件、输出目录，输入输出都建议用绝对路径，相对路径在独立版里经常因为工作目录切换而失效。

独立版的代价是灵活性下降：图形界面能做的事它都能做，但批处理的字段没法在运行时随意改，要改就得重新生成配置文件。所以我的一般做法是——有 MATLAB 授权就用工具箱版跑调试，把参数调稳之后再固化成独立版丢到计算节点上批量跑。两套环境都在手边，比死磕一套要省时间。

3. 核心链路拆解：一张 T1 从进 cat12 到出 mwp1 的全过程

搞清目录只算进了门，真正决定结果质量的是分割这一段。CAT12 的分割不是一步，而是一条由配准、组织分类、归一化、调制串起来的链路，每一环都有一组可以调的参数，参数错了结果看起来"能出图"，但数值完全不能用。这一章把这条链路拆开讲，并给出可以直接抄的批处理结构。

3.1 配准、组织分割与归一化的三步顺序

一张原始 T1 进来，第一步是仿射配准，把个体脑袋摆到标准空间附近，同时估计出六参数的刚体变换。这一步的初值来自头皮剥离后的图像，所以头动严重或者视野不全的数据在这里就会出问题，表现为后续组织概率图错位。

第二步是组织分类，把每个体素判成灰质、白质、脑脊液、颅骨、软组织、空气六类。CAT12 在这一步用的是自适应最大后验估计，配合局部自适应分割强度，比早期版本对不均匀场更耐受。这一步还会顺带估计出总颅内体积，是后面做比例校正的基础。

第三步是空间归一化与调制。归一化把个体空间映射到标准模板空间；调制则是把形变场的雅可比行列式乘回图像强度，保证"体积守恒"——换句话说，调制后的灰质图上每个体素的数值代表的是原始体积，而不是概率密度。

顺序不能颠倒，但可以跳过。做 ROI 分析时很多人只做分割不做归一化，直接拿个体空间的灰质图配图谱；做基于体素的分析就必须做归一化加调制。判断标准很简单：结果要和别人的坐标对齐，就得归一化；只在个体空间里量体积，可以省掉这一步。我见过有人在归一化之后才发现自己其实只需要个体体积，白跑一整轮。

3.2 一个 segmentation 批处理结构长什么样

图形界面点出来的操作最后都会变成一个 matlabbatch 结构。理解这个结构，等于拿到了把 GUI 变成脚本的钥匙。下面是最小可用的一段：

% 初始化批处理系统 spm_jobman('initcfg'); % 清空上一次残留，防止字段串味 clear matlabbatch; % 输入：NIfTI 路径后面必须带 ',1' 表示取第一卷 matlabbatch{1}.spm.tools.cat.estwrite.data = { '/data/sub-01/anat/sub-01_T1w.nii,1' }; % 并行进程数，内存不够就调小，见第 5 章 matlabbatch{1}.spm.tools.cat.estwrite.nproc = 2; % 仿射配准方式，默认即可，异常数据可换 matlabbatch{1}.spm.tools.cat.estwrite.opts.affreg = 'mni'; % 组织概率图模板路径，必须是本机真实存在的绝对路径 matlabbatch{1}.spm.tools.cat.estwrite.opts.tpm = { '/opt/toolboxes/cat12/tpm/TPM.nii' }; % 局部自适应分割强度，默认 0.5，对比度差的数据可上调 matlabbatch{1}.spm.tools.cat.estwrite.extopts.LASstr = 0.5; % 配准正则化强度，越小越严格 matlabbatch{1}.spm.tools.cat.estwrite.extopts.regstr = 0.5; % 输出：打开灰质与白质的调制归一化结果 matlabbatch{1}.spm.tools.cat.estwrite.output.GM.native = 1; matlabbatch{1}.spm.tools.cat.estwrite.output.GM.warped = 1; matlabbatch{1}.spm.tools.cat.estwrite.output.GM.mod = 1; matlabbatch{1}.spm.tools.cat.estwrite.output.WM.native = 1; matlabbatch{1}.spm.tools.cat.estwrite.output.WM.warped = 1; matlabbatch{1}.spm.tools.cat.estwrite.output.WM.mod = 1; % 跳过表面重建，只做体素级分析能省一半时间 matlabbatch{1}.spm.tools.cat.estwrite.output.surface = 0; % 真正执行 spm_jobman('run', matlabbatch);

逐段说。data里的,1是 SPM 的约定，标记取文件的第几帧，4D 数据必须写清楚，3D 数据不写某些版本也能跑但容易在批量时出岔子，养成习惯就好。nproc控制并行，它的取值直接决定内存峰值，后面避坑章节会专门说。

opts.tpm给的是六类组织概率图模板，CAT12 内部会按这个文件的位置推断同级目录下的其他模板，所以路径必须是完整的绝对路径，写成相对路径在某些工作目录下会静默失败，输出看着正常但组织分类明显跑偏。

extopts.LASstr是局部自适应分割强度，这个参数最值得动手调：默认 0.5 对常规 3T 数据够用，遇到 1.5T 或者对比度偏弱的扫描，把它调到 0.6 到 0.7，能明显改善深部灰质的分类效果。代价是过度平滑，边界会糊，所以别一上来就调。

extopts.regstr控制配准正则化，值越小形变越自由。脑室显著扩大或者有占位效应的数据，适当放松到 0.3 左右能减少配准失败，但会带来形变过度的风险，得看成像质量决定。

output.GM.native / warped / mod三个开关分别对应个体空间、标准空间、调制后结果。全打开最保险，代价是磁盘占用翻几倍。做基于体素的形态学分析，实际只需要mod为 1 且warped为 1 的组合，也就是那批mwp1文件；native留作个体空间 ROI 用。output.surface = 0是提速的关键，表面重建很吃时间，不做皮层分析就关掉，一个被试能省十几分钟。

3.3 输出文件命名规则与体素尺寸选择

跑完之后输出目录会多出一堆前缀文件，不认识命名规则很容易拿错数据。规则是按前缀字母叠加：p表示组织分割结果，w表示归一化到标准空间，m表示调制，l表示另外一些标记。组合起来：

• p1：个体空间灰质概率图，数值范围 0 到 1
• mwp1：归一化并调制后的灰质图，做 VBM 统计用的就是它
• mwp2：对应的白质图
• p0：原始图像经过偏差校正后的版本

拿错文件的后果很直接：用p1去做组间比较，比较的是概率不是体积，结论基本没有意义。我见过最典型的一个翻车是有人把wp1（归一化但没调制）当成体积指标，跑出来组间差异方向全是反的，回头查了两周才发现少了一个m前缀。

体素尺寸的选择是另一个容易含糊的点。归一化时默认会重采样到 1.5 mm 各向同性，做 VBM 通常够用；如果样本量小、预期效应也小，可以降到 1 mm 提高空间分辨率，但文件体积和计算量会涨到三四倍，平滑核也要相应调整。反过来，只做粗略的 ROI 体积统计，保持 1.5 mm 甚至 2 mm 更划算。

3.4 质量检测报告与 IQR 评级

CAT12 每个被试跑完会生成一份 XML 报告和一张预览图，里面最值得看的是图像质量评级。它把多个指标综合成一个百分制分数，再映射成 A 到 E 的等级。经验阈值是：A 和 B 放心用，C 需要人工看图确认，D 和 E 建议剔除或者重跑。

这个评级不是玄学，它主要反映配准残差、组织对比度和噪声水平。评级偏低常见于三种情况：扫描时头动明显、T1 对比度不足、视野切掉了小脑或顶部。前两种调参数救不回来，只能剔除；第三种如果只是轻微截断，可以尝试调整配准初值。

批量处理时一定要把这套指标抽出来汇总，否则三十个被试里混进两个 D 级，统计结果就被污染了。下一章会给一个从 XML 里提数的脚本，直接生成可排序的表格。

4. 批处理落地：把 GUI 操作换成可重复执行的脚本

图形界面点一遍能出结果，点三十遍就是灾难，而且不可复现。这一章把上一章的批处理结构封装成能跑在命令行、能断点续跑、能输出失败清单的脚本。目标是：一个被试出错不影响整批，第二天早上看日志就能知道哪个该重跑。

4.1 单被试的命令行调用

先解决"不进 MATLAB 界面也能跑"的问题。现代版本用-batch参数最省事：

#!/bin/bash # 单被试分割，失败时保留日志 matlab -batch "addpath('/opt/toolboxes/spm12'); \ addpath(genpath('/opt/toolboxes/cat12')); \ spm('defaults','FMRI'); \ spm_jobman('initcfg'); \ run('/opt/pipeline/seg_one.m')" \ -logfile /data/logs/sub-01.log

-batch的好处是执行完自动退出，退出码能反映是否异常，方便外层脚本判断。-logfile把标准输出重定向到文件，出问题时不用靠记忆复现。注意命令里的分号不能省，整串是一条 MATLAB 语句。

对应的seg_one.m就是把第 3 章的批处理结构包一层函数，输入输出做成参数：

function seg_one(inFile, outDir) % 单个被试的分割入口，路径全部走绝对路径 if ~exist(outDir, 'dir'); mkdir(outDir); end clear matlabbatch; matlabbatch{1}.spm.tools.cat.estwrite.data = {[inFile ',1']}; matlabbatch{1}.spm.tools.cat.estwrite.nproc = 2; matlabbatch{1}.spm.tools.cat.estwrite.opts.tpm = { '/opt/toolboxes/cat12/tpm/TPM.nii'}; matlabbatch{1}.spm.tools.cat.estwrite.extopts.LASstr = 0.5; matlabbatch{1}.spm.tools.cat.estwrite.output.GM.mod = 1; matlabbatch{1}.spm.tools.cat.estwrite.output.GM.warped = 1; matlabbatch{1}.spm.tools.cat.estwrite.output.surface = 0; % 结果统一落到指定输出目录，避免污染原始数据目录 matlabbatch{1}.spm.tools.cat.estwrite.output.warps = [1 0]; try spm_jobman('run', matlabbatch); catch ME % 把错误原样抛出，由外层脚本捕获写进失败清单 fprintf(2, 'SEG_FAILED: %s\n', ME.message); rethrow(ME); end end

函数化的意义在于隔离。把批处理写死在脚本里，加一个被试就得改一次代码；做成inFile / outDir两参数，外层只负责遍历，职责清楚。try-catch里那句fprintf(2, ...)是写给日志看的，2是标准错误流，方便外层的 grep 抓取。rethrow保证异常不被吞掉，退出码才会非零。

4.2 批量遍历与断点续跑

批量脚本的核心不是循环，是"跳过已完成"。判断依据建议用输出文件是否存在，而不是维护一个状态文件——状态文件和数据目录一旦不同步，就会出现"以为跑过了其实没有"的惨案。

% 批量遍历，跳过已完成的被试 rootDir = '/data/raw'; outRoot = '/data/derivatives'; subs = dir(fullfile(rootDir, 'sub-*')); failed = {}; for i = 1:numel(subs) sid = subs(i).name; inFile = fullfile(rootDir, sid, 'anat', [sid '_T1w.nii']); outDir = fullfile(outRoot, sid); % 关键判据：调制后的灰质图存在就跳过 probe = dir(fullfile(outRoot, sid, 'mwp1*.nii')); if ~isempty(probe) fprintf('SKIP %s\n', sid); continue; end if ~exist(inFile, 'file') fprintf('MISSING %s\n', sid); failed{end+1} = sid; %#ok<SAGROW> continue; end try seg_one(inFile, outDir); fprintf('DONE %s\n', sid); catch failed{end+1} = sid; %#ok<SAGROW> end end % 失败清单落盘，第二天直接照着重跑 writelines(failed, '/data/logs/failed.txt');

跳过判据选mwp1*.nii而不是随便一个输出文件，是因为分割中途崩溃时会留下部分输出，用最靠后的产物做判据最安全。writelines在老版本 MATLAB 上不存在，换成fopen+fprintf循环即可，别因为一个函数把整段脚本卡住。

还有一个容易被忽略的点：输出目录和原始数据目录必须分开。有人图省事让 CAT12 直接输出到原始数据所在目录，结果预处理产物和原始 DICOM、NIfTI 混在一起，后续再遍历时把所有mwp1也当输入扫进去了，重复计算还把磁盘塞满。

4.3 日志与失败清单

日志不是跑完再看的东西，是跑的时候用来定位的。我一般的做法是每被试一个日志文件，文件名带被试编号和日期，外加一份汇总的失败清单。日志里至少要有四类信息：开始时间、输入路径、异常信息、结束时间。少了时间戳，多个任务并发时根本分不清先后。

如果不想自己造轮子，-logfile已经能兜住大部分需求；唯一要补的是把每个被试的失败原因单独摘出来。上面那个catch里打印的SEG_FAILED前缀就是为此设计的，跑完之后一句命令就能汇总：

grep -h "SEG_FAILED" /data/logs/*.log | sort | uniq -c | sort -rn

这条命令的输出直接告诉你哪类错误最常见，比一个个翻日志高效得多。真正常见的就那么几种，下一章逐一拆。

5. 避坑与排查：五条血泪经验对着看

这一章是我自己踩过的、以及在别人机器上复现过的五类问题，按"现象、原因、解决"写。放在这里而不是散在各章，是因为出问题时人是慌的，需要一份能直接对照的清单。

5.1 启动就报未定义函数

现象：输入cat12之后提示Undefined function or variable 'spm'，或者 CAT12 窗口一闪而过。

原因：路径顺序错了，或者根本只加了 CAT12 没加 SPM12。CAT12 的启动函数第一步就是调用 SPM 做版本探测，探测不到直接退出，异常信息还不一定友好。

解决：严格按"先addpath('/opt/toolboxes/spm12')、再addpath(genpath('/opt/toolboxes/cat12'))"的顺序注册，注册完savepath固化。如果仍然报错，用which spm确认拿到的是不是你期望的那一份，用户目录下残留的旧版本优先级可能更高。

5.2 跑到一半内存爆掉

现象：批量处理时前几个被试正常，跑到中途 MATLAB 直接崩溃或者系统开始疯狂换页，日志停在某个被试没有任何输出。

原因：nproc开太大。每个并行进程都会复制一份分割所需的中间数据，峰值内存大约是单进程的两到三倍。默认值在某些版本上是 4，机器只有 16 GB 内存时撑不住。

解决：把nproc降到 1 或 2，先测单被试的峰值内存再定。经验值是一张 1 mm 分辨率的 T1 全流程峰值在 2 GB 上下，并行数乘上去不能超过物理内存的七成。另外别在同一天既跑并行又开大图查看器，两者抢内存非常凶。

5.3 输出目录里找不到 mwp1

现象：分割跑完了，日志显示成功，但输出目录只有p1、p2，没有mwp1。

原因：output.GM.mod或output.GM.warped有一个没打开。这两个开关是独立的，只开native = 1就只出个体空间的结果。

解决：三个开关按需组合，做组间体积比较至少要warped = 1且mod = 1。改完记得清掉旧的 matlabbatch 结构，字段是叠加的，不清场容易留下上一轮的残留值。

5.4 路径里有中文或空格

现象：某些被试报文件读取失败，另一些同样命名规则的却正常，报错信息指向的路径看起来完全正确。

原因：SPM 底层的文件读写对非 ASCII 字符和空格的支持一直不太好，尤其是批量拼接路径时，空格会被当成参数分隔符。

解决：原始数据、输出目录、工具箱路径，三者全部用纯英文、无空格、无特殊符号的路径。这一条看起来最没技术含量，但它是排查成本最高的坑之一，因为报错位置往往和真实原因隔了好几层。我现在的习惯是项目初始化时就建好/data/raw、/data/derivatives两个顶层目录，所有人往里放数据，从源头掐掉这个问题。

5.5 质量评级普遍偏低

现象：整批被试的评级集中在 C 和 D，单看某一张图像又觉得没什么大问题。

原因：多数情况下是配准残差偏大，常见于视野不全、头动明显或者 T1 对比度弱的数据。也可能是一批数据用了同一个不合适的配准初值。

解决：先抽三到五张图人工确认，排除图像本身的问题；确认是参数导致的话，把extopts.regstr从 0.5 适度放松，同时把extopts.LASstr上调一档，重跑一个小样本对比评级变化。如果调整之后评级没有改善，就不要再救了，这批数据的成像质量本身达不到分析要求，硬调参数只会把噪声压进结果里。

6. 二次开发：改参数、写评分脚本、把流程封装成自己的工具

装通、跑通之后，真正的价值在于把这套东西改造成贴合自己项目的流水线。三个方向最值得投入。

第一个是参数固化。所有会随项目变化的参数——平滑核大小、体素尺寸、输出开关——都抽到一个配置文件里，脚本只读配置。我习惯用一张表管起来：

第二个是质量评分自动化。从每个被试的 XML 报告里把评级提出来，汇总成 CSV，按分数排序，前几名重点看。核心逻辑不复杂：

% 从 cat12 输出的 XML 里提取质量评级相关字段 f = dir('/data/derivatives/sub-*/cat_*_seg.xml'); rows = cell(numel(f), 2); for i = 1:numel(f) txt = fileread(fullfile(f(i).folder, f(i).name)); % 用正则抓评级字母，比解析整个 XML 结构轻量 tok = regexp(txt, '<qualityrating>([A-E])</qualityrating>', 'tokens'); rows{i,1} = f(i).folder; rows{i,2} = tok{1}{1}; end T = cell2table(rows, 'VariableNames', {'subject','rating'}); writetable(T, '/data/logs/qc.csv');

fileread把整个文件读成字符串，regexp抓目标字段，避开了完整 XML 解析的层级遍历，对固定格式的报告足够稳。字段名要以实际输出为准，不同小版本的标签可能有差异，跑之前先打开一份 XML 确认。这段脚本真正的用途不是打分，而是把"哪个被试该重跑"这件事变成可排序的列表，省掉人工逐个翻报告的时间。

第三个是封装。把分割、QC、汇总三步串成一条命令，输入一个数据根目录，输出一张结果表。封装时守住一条原则：每一步都留中间产物和日志，不要把异常吞在自己写的函数里。我在早期版本里图省事，把try-catch写成了静默跳过，结果一批数据跑完显示全部成功，实际上三分之一是空输出，等到统计阶段才发现样本量对不上。

从那以后我每次改完流水线，都会先手动挑三个被试——一个正常的、一个视野不全的、一个明显有头动的——强制走一遍全流程，确认正常的那份出结果、异常的那两份被正确标记进失败清单，再放开跑整批。这个习惯帮我挡掉过好几次批量事故。希望帮到你。

本文还有配套的精品资源，点击获取