简介CAT12.7 是面向脑结构 MRI 与 T1 加权图像处理学习者的 SPM 工具箱安装包适合正在复现教程笔记、需要固定旧版本环境的研究生与神经影像初学者使用尤其适合依赖旧版界面与函数接口的课程实验。压缩包内含 822 个文件约 222.93MB以 m 源码脚本、exe 与多平台 mex 二进制、nii/gii 影像与表面数据、annot 脑图谱标注、png/html 说明文档及 txt/csv 配置清单为主并保留模板、mask 与部分 C/C 扩展源码便于了解工具箱的目录组织和运行依赖。已有 1731 人学习下载。对于官方已覆盖旧版、难以再获取 CAT12.7 的读者这份包可用于搭建稳定的 T1 处理环境对照笔记完成分割、配准与表面指标计算等流程也方便检查版本兼容、补全图谱与模板文件减少因环境不一致导致的复现偏差并对照官方更新差异判断后续迁移风险。1. CAT12.7 安装包到底装的是什么一份压缩包和它背后的三层依赖把 CAT12.7 版本安装包解压开第一层很容易让人误判没有 setup.exe没有安装向导只有一堆 .m 文件、一个 cat12 目录和若干描述文件。它是典型的源码软件分发形态——放进搜索路径就能用路径不对则一行错误都不给。本质是 SPM12 的一个工具箱插件负责结构像的分割、配准、调制、皮层表面重建和质量控制跑 VBM、ROI 体积、皮层厚度的流程都绕不开它。它适合已经能启动 MATLAB、手里有 T1 结构像的从业者完全没碰过 MATLAB 的人先补命令行和路径概念否则每一步都是未知错误。2. 前置环境对表MATLAB、SPM12 与 CAT12.7 的版本咬合怎么对装 CAT12.7 翻车的案例里真正因为压缩包损坏的极少绝大多数是三件套没咬合上。这一章把版本边界、目录规划和路径写入讲清楚后面所有操作才有稳定的地基。2.1 三个组件各自的职责与版本边界MATLAB 是运行时和图形宿主负责解释 .m 文件、渲染 SPM 的 batch 界面、提供并行池SPM12 是宿主框架提供 batch 系统、NIfTI/XML/GIfTI 读写、统计模块CAT12.7 只负责它自己那部分算法和模板。分清楚这层关系报错就能第一时间定位到应该检查哪一层而不是对着 CAT12 的目录反复重装。版本边界不必记死记住“新的带旧的”这条经验规则就够用MATLAB 定在 64 位 R2020a 及以上SPM12 用近两年的修订版CAT12.7 用压缩包原样。确实以压缩包内 README 为准但按这个区间配十台机器里九台不会出问题。组件职责建议版本区间不匹配时的典型症状MATLAB解释器、图形、并行池R2020a 64 位界面控件不渲染、并行启动失败SPM12batch、图像 IO、统计近两年修订版Undefined function spm_jsonread一类缺失函数CAT12.7分割、配准、表面、QC与压缩包同名版本SPM 界面无 CAT12 面板、spm_cat12找不到最容易踩的坑是 SPM12 用了几年前的旧包。CAT12.7 在启动时会调用 SPM 里相对新的函数和默认字段老版本 SPM 上直接抛“未定义函数”而这个报错的位置往往在 CAT12 的初始化代码里看起来像是 CAT12 坏了实际是宿主太旧。反过来MATLAB 版本过高也有代价新版 MATLAB 对图形句柄和字符串类型的处理更严格极老的 SPM 修订版会出兼容问题所以两头都别走极端。提示先确认spm(Ver)返回的 SPM12 修订号再动 CAT12 的目录。宿主版本不确定时后面所有排查都是盲猜。2.2 目录结构与路径规划的具体做法路径规划的原则只有一条全英文、无空格、层级浅。Windows 上用户名是中文、把工具包放在“桌面\新建文件夹”里是 CAT12 报错的高发来源——MATLAB 的addpath能处理中文路径但 CAT12 内部调用外部程序、写临时文件、解析 NIfTI 头时不一定能出问题的位置离真正原因很远。我一般把工具和数据分开放在两个根目录下工具只读、数据可写备份和迁移都省事D:/neuro/apps/spm12/ # SPM12 解压后的根目录 D:/neuro/apps/spm12/toolbox/cat12/ # CAT12.7 放这里 D:/neuro/data/sub-001/anat/ # 原始 T1按被试分目录 D:/neuro/work/ # 中间结果和临时文件 D:/neuro/scripts/ # 自己的批处理脚本落位前先看一眼解压结果。压缩包解开后如果多套了一层比如cat12.7_xxxx/cat12/...直接整个丢进 toolbox 就会变成toolbox/cat12.7_xxxx/cat12/cat12.mSPM 扫不到界面上的 CAT12 面板就是不出现。正确形态是toolbox/cat12/cat12.m和toolbox/cat12/spm_cat12.m直接可见。数据目录里不要混放 DICOM 和 NIfTI。CAT12 的 DICOM 导入会按目录扫描混放时容易把已经转好的 NIfTI 再当输入喂一遍或者把不同序列的 DICOM 归到同一个输出名上结果就是文件名撞车、后写的覆盖先写的而且不报错。2.3 MATLAB 路径写入与启动配置路径有两种加的方式一次性的addpath和固化进pathdef.m的savepath。工具包目录固定不变就直接固化省得每次开机重来。用addpath而不是genpath是血泪经验——genpath会把工具箱里所有子目录包括 external、demo、旧版本兼容代码全塞进搜索路径函数名冲突立刻出现典型表现是某个 SPM 函数被 CAT12 自带的同名旧版覆盖行为变得莫名其妙。% 一次性配置把宿主和插件都加进搜索路径然后固化 addpath(D:/neuro/apps/spm12); addpath(D:/neuro/apps/spm12/toolbox/cat12); savepath; % 写入 pathdef.m下次启动自动生效 % 验证两个 which 都应该返回具体路径而不是 not found which spm which cat12savepath在 MATLAB 装在系统盘 Program Files 下时会因为写权限失败提示无法保存。这时别去改系统目录权限改用userpath指向一个有写权限的目录或者干脆在startup.m里保留那两行addpath每次启动自动执行效果一样且不动系统文件。启动 SPM 之前先设默认参数这一步决定后面 batch 的默认值spm(defaults, fmri); % 设默认模态影响默认 TR 和滤波参数 spm_jobman(initcfg); % 初始化 batch 系统脚本化调用前必须执行spm(defaults,fmri)影响的是统计模块的默认值分割流程用不到 TR但设了没坏处能避免 batch 里出现空字段。spm_jobman(initcfg)则是脚本化运行的必需品漏掉它spm_jobman(run, ...)会报配置未初始化。2.4 多版本共存时用路径顺序说话同一台机器上放两个 CAT12 版本做对比是很常见的需求。这时不要靠“记住哪个是真的”而是靠addpath的顺序——MATLAB 搜索路径是从前到后的第一个命中的就是生效的。把要用的版本addpath在最前面或者用addpath(..., -begin)另一个版本放在后面切换时重新执行一次即可。有个隐蔽的坑CAT12 启动后会在基础工作区或全局变量里缓存版本信息和部分配置。切换版本后不重启 MATLAB界面上显示的版本号可能还是旧的看上去像是“装错了”。切换版本的正确姿势是清空工作区、重新addpath、再启动 SPM别在同一个会话里来回切。3. 落位与冒烟测试解压、加路径、跑通一个被试装完不等于能用。这一章给出一个最小闭环从一个 T1 图像进去从灰质图出来全程不超过十分钟但能暴露九成的环境问题。3.1 三种落位方式各自的代价放在spm12/toolbox/cat12是最省事的做法SPM 启动时会自动扫描 toolbox 目录下的子目录并注册面板直接出现不需要额外addpath。代价是 SPM 升级时容易连带覆盖升级前要单独备份一份 CAT12。独立目录加addpath适合多版本并存和权限受限的机器比如 SPM 装在只读的网络盘上。代价是每次启动都要保证addpath执行过否则面板消失用startup.m固化可以解决。丢进 MATLAB 自己的 toolbox 目录是不推荐的做法。MATLAB 会在启动时对这个目录做缓存新增工具箱后需要rehash toolboxcache才认而且和 MATLAB 自带工具箱混在一起卸载时极容易误删。3.2 启动验证的三种方式界面验证最直观命令行敲spm打开 SPM 主界面底部或侧边应该出现 CAT12 的面板区块里面有 Segmentation、Surface、Tools 之类的入口。看不到就说明路径没生效别急着怀疑压缩包。命令行验证更可靠which cat12 % 应返回 .../toolbox/cat12/cat12.m which spm_cat12 % 应返回 .../toolbox/cat12/spm_cat12.m cat12; % 直接调起 CAT12 的独立界面三个都通再去看 SPM 界面。顺序反过来会浪费很多时间——界面是最后渲染的它不出来可能只是图形问题而不是路径问题。3.3 最小闭环一张 T1 进一张灰质图出不要一上来就跑整批数据。先拿一个被试跑通确认输出目录有文件、文件头正确、灰度分布合理再谈批处理。下面是最小的脚本化调用字段名来自 CAT12 的 batch 结构spm(defaults, fmri); spm_jobman(initcfg); t1 D:/neuro/data/sub-001/anat/sub-001_T1w.nii; matlabbatch {}; matlabbatch{1}.spm.tools.cat.estwrite.data {t1}; matlabbatch{1}.spm.tools.cat.estwrite.nproc 1; % 单被试调试别开并行 matlabbatch{1}.spm.tools.cat.estwrite.opts.tpm {D:/neuro/apps/spm12/tpm/TPM.nii}; matlabbatch{1}.spm.tools.cat.estwrite.extopts.regstr 1; % 默认配准强度 matlabbatch{1}.spm.tools.cat.estwrite.extopts.vox 1.5; % 输出体素1.5mm 省时省盘 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.GM.dartel 1; matlabbatch{1}.spm.tools.cat.estwrite.output.WM.native 1; matlabbatch{1}.spm.tools.cat.estwrite.output.CSF.native 1; matlabbatch{1}.spm.tools.cat.estwrite.output.bias.native 1; matlabbatch{1}.spm.tools.cat.estwrite.output.surface 0; % 冒烟测试跳过表面重建 spm_jobman(run, matlabbatch);字段名不必背。正确做法是在 SPM 界面里把 Segmentation 的选项点一遍然后 File → Save Batch 导出成 .mat用load打开看结构照着抄字段。CAT12 每个小版本都可能挪动个别字段抄界面导出的结构永远不会错。参数说明按影响从大到小排nproc是并行进程数调试期一定设 1否则报错信息会被多个进程的输出冲散extopts.regstr是配准强度默认档在成人结构像上够用儿童或明显萎缩的脑可以往上调一档extopts.vox是输出体素大小1.5mm 相比 1.0mm 能把耗时和磁盘占用压到一半左右做群体统计时差异通常可以接受output.surface关掉可以跳过皮层表面重建冒烟测试阶段没必要跑。3.4 冒烟测试的验收标准跑完先看目录。应该出现以mwp1、wp1、p1开头的 NIfTI以及一个记录分割质量的文本文件。文件数量对不上说明输出选项没生效回去检查 batch 里output那几行。再看图像。用 SPM 的 Display 打开p1灰质概率图灰质应该集中在皮层和深部核团脑室和颅骨区域接近零。如果整张图灰蒙蒙、灰白质边界糊成一团多半是配准没收敛或者输入的 T1 本身有严重的运动伪影和强度不均。最后看质量记录文件的几个指标。CAT12 会输出每个被试的配准误差和图像质量评分这两项异常的被试后面统计阶段会变成离群点与其到那时再回头删不如在冒烟阶段就记下来。4. VBM 预处理参数模板、配准强度与调制输出怎么选分割参数不是玄学每个选项背后都对应一个“你要回答什么科学问题”的判断。这一章按输出用途倒推参数而不是罗列选项。4.1 配准强度与模板选择CAT12 把空间配准拆成两步仿射配准把个体脑大致对齐到模板空间非线性配准再细化局部形变。仿射那一步的强度是可调的常见做法是用默认档遇到脑形态偏离模板较远的样本儿童、老年人、明显萎缩往上调一档让仿射阶段多花点时间换取非线性阶段更少的局部扭曲。模板选择在 CAT12 里主要是组织概率图TPM的路径。用默认 TPM 就够它由大量成人数据平均而来。如果研究对象是婴幼儿成人 TPM 明显不合适需要换专门的模板这类模板不是 CAT12 自带的得自己准备并显式指定路径指定错了会表现为分割出的灰质体积系统性偏小或偏大。注意模板换了后续所有体积数值都不能和用默认模板跑出来的结果直接比较。混着用是群体分析里最难查的错误之一。4.2 输出前缀与统计端的对应关系CAT12 输出文件名前面的小写字母有严格含义搞混了统计结果就是错的。这是新手最容易翻车的地方因为文件都在、都能打开看起来一切正常。前缀含义典型用途p1/p2/p3组织概率图未归一化检查分割质量wp1/wp2归一化到模板空间未调制看形状不做体积统计mwp1/mwp2归一化 调制保留局部体积信息标准 VBM 灰质体积分析wj开头雅可比行列式形变场分析、局部萎缩程度DARTEL 导出供 DARTEL 做组间配准的刚性组织图大样本精细配准标准 VBM 用mwp1调制把非线性形变造成的体积变化乘回图像强度里所以每个体素的值反映的是局部灰质体积而不是灰质密度。只用wp1做统计等于把体积信息抹掉结论会偏向“密度”而非“体积”写文章时容易被审稿人抓住。DARTEL 导出是为大样本准备的。CAT12 可以把组织图按 DARTEL 的格式导出交给 SPM 的 DARTEL 工具做组内平均模板再归一化。样本量在几十以上、脑形态差异大时值得走这条路代价是多一整套流程和更长的耗时。4.3 平滑核的选择VBM 统计前要做高斯平滑核宽FWHM常见取 6~10mm。核宽和经验规则有关越接近预期效应团的尺寸统计灵敏度越高核宽太小配准残差会带来大量假阳性核宽太大小范围效应被抹平。我一般先用 8mm 跑一版看整体格局如果预期效应是弥散的皮层改变8mm 合适如果是深部小核团改用 6mm 并配合更严格的团块阈值。平滑在 SPM 的 Smooth 模块做输入选mwp1图像输出会加s前缀统计时读smwp1。平滑前要先确认所有被试的mwp1是同一个包围盒和体素大小。CAT12 默认会用模板的包围盒但改了extopts.vox之后不同批次跑出来的图像体素大小会不一致SPM 的 Smooth 遇到尺寸不一致的输入会报错或者按第一张图的规格裁剪后者更危险因为不报错。4.4 质量检查与样本同质性CAT12 自带 Check Sample Homogeneity本质是算所有被试两两之间的图像相似度画成相关性矩阵和箱线图把明显偏离群体的被试标出来。这个工具的价值在于配准失败往往不会报错只会让某张图看起来“有点不对”肉眼在一百个被试里根本看不出来。阈值怎么定用协方差或相关性都行箱线图的 IQR 倍数常见设 2 或 3。设 2 会标出更多候选适合样本量小、宁可多查的时候设 3 更保守标出来的基本是真问题。被标出来不等于必须剔除先打开图像看确认是配准失败还是解剖本身特殊比如明显脑室扩大再决定。这一步的建议是固定下来每次跑完批量分割都执行一遍不要因为“上次没问题”就跳过。环境换了、SPM 版本升了、批量脚本改了一行都可能让某个被试静默失败。4.5 长流程的资源控制一个被试的完整分割含表面重建在普通工作站上要十几分钟到半小时几十个被试就是一夜。资源控制没做好半夜跑到一半内存耗尽退出第二天还得从头来。nproc设成物理核心数的六到七成比较稳每个进程峰值内存按 2~3GB 估16GB 内存的机器设 4 个进程就接近上限了。临时目录指向剩余空间大的盘分割过程会产生大量中间文件系统盘被写满导致失败的案例不少见。批量跑之前先用一个被试测出单例耗时和内存峰值再乘上被试数这个估算比任何经验值都准。5. 避坑与排查五类装得上却跑不对的现场问题下面五条都是“装完了、也能启动、但结果不对”的场景。按现象、原因、解决的顺序写照着对号入座即可。5.1 启动 SPM 后看不到 CAT12 面板现象which cat12能返回路径但 SPM 主界面底部没有 CAT12 的区块菜单里也没有 CAT 相关项。原因SPM 扫描 toolbox 目录发生在启动时如果 CAT12 是在 SPM 启动之后才addpath进来的面板不会补渲染另一种情况是目录层级多套了一层spm_cat12.m不在toolbox/cat12/的直接子级。解决先restoredefaultpath清干净重新addpath宿主和插件然后重启 MATLAB 再启动 SPM。目录层级问题直接看文件系统确认cat12.m就在toolbox/cat12/下多套的那层删掉或者把内层提上来。5.2 分割跑到一半报内存不足退出现象日志显示处理到某个被试时中断MATLAB 命令窗口出现内存相关的报错前面几个被试的结果正常。原因并行进程数设太高或者某个被试的图像矩阵特别大高分辨率、未降采样单个进程的峰值内存远超估算值。解决把nproc降一半重跑先确认是并发问题还是单例问题。如果单个被试也跑不动把extopts.vox从 1.0 放到 1.5输出体素变大内存和耗时同步下降。批量脚本里加上失败重试和断点续跑别让一个被试失败拖垮整批。5.3 报未定义函数且函数名看起来属于 SPM现象启动 CAT12 或者执行分割时报Undefined function spm_xxx而这个函数在 SPM 目录里明明存在。原因搜索路径里存在另一份同名的旧版 SPM 函数被优先命中了或者genpath把 CAT12 自带的兼容代码加进了路径覆盖了宿主版本。解决which -all spm_xxx看有几个命中把多余的那份从路径里移掉。根治办法是改用逐个addpath而不是genpath并且定期restoredefaultpath清理累积的路径污染。5.4 分割跑完但统计时被试对不齐现象所有mwp1都在SPM 统计也能跑但结果里出现大片位于脑外的“激活”或者某个被试的整体信号明显偏移。原因某个被试的仿射配准失败图像被摆到了模板空间的错误位置但因为流程没报错一直到统计阶段才暴露也可能是不同批次跑的图像体素大小不一致平滑时被静默裁剪。解决跑 Check Sample Homogeneity看相关性矩阵里的离群点再抽几个被试打开wp1叠到模板上看位置。确认是配准问题的被试调高配准强度重跑或者直接剔除。批处理脚本里固定加一步“检查所有输入的维度和体素大小是否一致”这一步几行代码能省掉一整轮返工。5.5 版本号显示和压缩包对不上现象装的是新版本但 CAT12 界面或版本查询返回的是旧版本号。原因机器上有多份 CAT12搜索路径顺序决定了生效的那份或者切换版本后没有重启 MATLAB缓存里的版本信息还是旧的。解决which -all cat12列出所有命中按顺序确认哪个在最前。切换版本时用完整的清空流程clear all、restoredefaultpath、重新addpath、重启 MATLAB四步都做别图省事。6. 批处理与结果校验把重复劳动压进一个脚本单个被试跑通之后真正的成本在批量。手点界面跑五十个被试中间任何一次误点都要重来而且没法复现。我的习惯是把整个流程写成一个函数输入是数据根目录输出是每个被试的状态表跑完一眼就能看出谁成功谁失败。function run_cat12_batch(rootDir, outDir, nproc) % rootDir 下按 sub-*/anat/*T1w.nii 组织输出统一写到 outDir spm(defaults, fmri); spm_jobman(initcfg); files dir(fullfile(rootDir, sub-*, anat, *T1w.nii)); status cell(numel(files), 3); for i 1:numel(files) t1 fullfile(files(i).folder, files(i).name); try matlabbatch {}; matlabbatch{1}.spm.tools.cat.estwrite.data {t1}; matlabbatch{1}.spm.tools.cat.estwrite.nproc nproc; matlabbatch{1}.spm.tools.cat.estwrite.extopts.vox 1.5; matlabbatch{1}.spm.tools.cat.estwrite.output.GM.mod 1; matlabbatch{1}.spm.tools.cat.estwrite.output.surface 0; spm_jobman(run, matlabbatch); % 逐被试串行失败不污染其他人 status{i, 1} t1; status{i, 2} ok; catch ME status{i, 1} t1; status{i, 2} failed; status{i, 3} ME.message; % 记下错误原文便于回溯 end end save(fullfile(outDir, batch_status.mat), status); end外层串行、内层并行的结构是刻意的nproc让单个被试内部并行被试之间串行这样一个被试崩了不会连带其他被试状态表也能准确记录到具体是谁失败。如果反过来让被试之间并行失败信息会和别人的输出混在一起排查成本翻倍。跑完之后的校验我固定做三件事写成一张核对表校验项做法不合格的处理输出文件齐全统计每个被试目录下mwp1是否存在缺失的单独重跑维度一致读所有mwp1的spm_vol比对 dim 和 mat不一致的检查extopts.vox设置样本同质性跑一次 Check Sample Homogeneity离群被试逐个打开确认这三步加起来不到十分钟但能挡掉后面统计阶段最难受的一类返工——数据都跑完了才发现有两个被试从第一步就错了。从那以后我每换一台机器、每升一次版本都先拿一个公开的示例 T1 跑一遍这个最小闭环确认输出文件和图像质量都对再动真实数据。装工具这件事验证一次的成本远低于事后追溯。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/27 7:32:21 · 阅读 1.2k CAT12.7安装配置与VBM预处理全流程避坑指南
简介CAT12.7 是面向脑结构 MRI 与 T1 加权图像处理学习者的 SPM 工具箱安装包适合正在复现教程笔记、需要固定旧版本环境的研究生与神经影像初学者使用尤其适合依赖旧版界面与函数接口的课程实验。压缩包内含 822 个文件约 222.93MB以 m 源码脚本、exe 与多平台 mex 二进制、nii/gii 影像与表面数据、annot 脑图谱标注、png/html 说明文档及 txt/csv 配置清单为主并保留模板、mask 与部分 C/C 扩展源码便于了解工具箱的目录组织和运行依赖。已有 1731 人学习下载。对于官方已覆盖旧版、难以再获取 CAT12.7 的读者这份包可用于搭建稳定的 T1 处理环境对照笔记完成分割、配准与表面指标计算等流程也方便检查版本兼容、补全图谱与模板文件减少因环境不一致导致的复现偏差并对照官方更新差异判断后续迁移风险。1. CAT12.7 安装包到底装的是什么一份压缩包和它背后的三层依赖把 CAT12.7 版本安装包解压开第一层很容易让人误判没有 setup.exe没有安装向导只有一堆 .m 文件、一个 cat12 目录和若干描述文件。它是典型的源码软件分发形态——放进搜索路径就能用路径不对则一行错误都不给。本质是 SPM12 的一个工具箱插件负责结构像的分割、配准、调制、皮层表面重建和质量控制跑 VBM、ROI 体积、皮层厚度的流程都绕不开它。它适合已经能启动 MATLAB、手里有 T1 结构像的从业者完全没碰过 MATLAB 的人先补命令行和路径概念否则每一步都是未知错误。2. 前置环境对表MATLAB、SPM12 与 CAT12.7 的版本咬合怎么对装 CAT12.7 翻车的案例里真正因为压缩包损坏的极少绝大多数是三件套没咬合上。这一章把版本边界、目录规划和路径写入讲清楚后面所有操作才有稳定的地基。2.1 三个组件各自的职责与版本边界MATLAB 是运行时和图形宿主负责解释 .m 文件、渲染 SPM 的 batch 界面、提供并行池SPM12 是宿主框架提供 batch 系统、NIfTI/XML/GIfTI 读写、统计模块CAT12.7 只负责它自己那部分算法和模板。分清楚这层关系报错就能第一时间定位到应该检查哪一层而不是对着 CAT12 的目录反复重装。版本边界不必记死记住“新的带旧的”这条经验规则就够用MATLAB 定在 64 位 R2020a 及以上SPM12 用近两年的修订版CAT12.7 用压缩包原样。确实以压缩包内 README 为准但按这个区间配十台机器里九台不会出问题。组件职责建议版本区间不匹配时的典型症状MATLAB解释器、图形、并行池R2020a 64 位界面控件不渲染、并行启动失败SPM12batch、图像 IO、统计近两年修订版Undefined function spm_jsonread一类缺失函数CAT12.7分割、配准、表面、QC与压缩包同名版本SPM 界面无 CAT12 面板、spm_cat12找不到最容易踩的坑是 SPM12 用了几年前的旧包。CAT12.7 在启动时会调用 SPM 里相对新的函数和默认字段老版本 SPM 上直接抛“未定义函数”而这个报错的位置往往在 CAT12 的初始化代码里看起来像是 CAT12 坏了实际是宿主太旧。反过来MATLAB 版本过高也有代价新版 MATLAB 对图形句柄和字符串类型的处理更严格极老的 SPM 修订版会出兼容问题所以两头都别走极端。提示先确认spm(Ver)返回的 SPM12 修订号再动 CAT12 的目录。宿主版本不确定时后面所有排查都是盲猜。2.2 目录结构与路径规划的具体做法路径规划的原则只有一条全英文、无空格、层级浅。Windows 上用户名是中文、把工具包放在“桌面\新建文件夹”里是 CAT12 报错的高发来源——MATLAB 的addpath能处理中文路径但 CAT12 内部调用外部程序、写临时文件、解析 NIfTI 头时不一定能出问题的位置离真正原因很远。我一般把工具和数据分开放在两个根目录下工具只读、数据可写备份和迁移都省事D:/neuro/apps/spm12/ # SPM12 解压后的根目录 D:/neuro/apps/spm12/toolbox/cat12/ # CAT12.7 放这里 D:/neuro/data/sub-001/anat/ # 原始 T1按被试分目录 D:/neuro/work/ # 中间结果和临时文件 D:/neuro/scripts/ # 自己的批处理脚本落位前先看一眼解压结果。压缩包解开后如果多套了一层比如cat12.7_xxxx/cat12/...直接整个丢进 toolbox 就会变成toolbox/cat12.7_xxxx/cat12/cat12.mSPM 扫不到界面上的 CAT12 面板就是不出现。正确形态是toolbox/cat12/cat12.m和toolbox/cat12/spm_cat12.m直接可见。数据目录里不要混放 DICOM 和 NIfTI。CAT12 的 DICOM 导入会按目录扫描混放时容易把已经转好的 NIfTI 再当输入喂一遍或者把不同序列的 DICOM 归到同一个输出名上结果就是文件名撞车、后写的覆盖先写的而且不报错。2.3 MATLAB 路径写入与启动配置路径有两种加的方式一次性的addpath和固化进pathdef.m的savepath。工具包目录固定不变就直接固化省得每次开机重来。用addpath而不是genpath是血泪经验——genpath会把工具箱里所有子目录包括 external、demo、旧版本兼容代码全塞进搜索路径函数名冲突立刻出现典型表现是某个 SPM 函数被 CAT12 自带的同名旧版覆盖行为变得莫名其妙。% 一次性配置把宿主和插件都加进搜索路径然后固化 addpath(D:/neuro/apps/spm12); addpath(D:/neuro/apps/spm12/toolbox/cat12); savepath; % 写入 pathdef.m下次启动自动生效 % 验证两个 which 都应该返回具体路径而不是 not found which spm which cat12savepath在 MATLAB 装在系统盘 Program Files 下时会因为写权限失败提示无法保存。这时别去改系统目录权限改用userpath指向一个有写权限的目录或者干脆在startup.m里保留那两行addpath每次启动自动执行效果一样且不动系统文件。启动 SPM 之前先设默认参数这一步决定后面 batch 的默认值spm(defaults, fmri); % 设默认模态影响默认 TR 和滤波参数 spm_jobman(initcfg); % 初始化 batch 系统脚本化调用前必须执行spm(defaults,fmri)影响的是统计模块的默认值分割流程用不到 TR但设了没坏处能避免 batch 里出现空字段。spm_jobman(initcfg)则是脚本化运行的必需品漏掉它spm_jobman(run, ...)会报配置未初始化。2.4 多版本共存时用路径顺序说话同一台机器上放两个 CAT12 版本做对比是很常见的需求。这时不要靠“记住哪个是真的”而是靠addpath的顺序——MATLAB 搜索路径是从前到后的第一个命中的就是生效的。把要用的版本addpath在最前面或者用addpath(..., -begin)另一个版本放在后面切换时重新执行一次即可。有个隐蔽的坑CAT12 启动后会在基础工作区或全局变量里缓存版本信息和部分配置。切换版本后不重启 MATLAB界面上显示的版本号可能还是旧的看上去像是“装错了”。切换版本的正确姿势是清空工作区、重新addpath、再启动 SPM别在同一个会话里来回切。3. 落位与冒烟测试解压、加路径、跑通一个被试装完不等于能用。这一章给出一个最小闭环从一个 T1 图像进去从灰质图出来全程不超过十分钟但能暴露九成的环境问题。3.1 三种落位方式各自的代价放在spm12/toolbox/cat12是最省事的做法SPM 启动时会自动扫描 toolbox 目录下的子目录并注册面板直接出现不需要额外addpath。代价是 SPM 升级时容易连带覆盖升级前要单独备份一份 CAT12。独立目录加addpath适合多版本并存和权限受限的机器比如 SPM 装在只读的网络盘上。代价是每次启动都要保证addpath执行过否则面板消失用startup.m固化可以解决。丢进 MATLAB 自己的 toolbox 目录是不推荐的做法。MATLAB 会在启动时对这个目录做缓存新增工具箱后需要rehash toolboxcache才认而且和 MATLAB 自带工具箱混在一起卸载时极容易误删。3.2 启动验证的三种方式界面验证最直观命令行敲spm打开 SPM 主界面底部或侧边应该出现 CAT12 的面板区块里面有 Segmentation、Surface、Tools 之类的入口。看不到就说明路径没生效别急着怀疑压缩包。命令行验证更可靠which cat12 % 应返回 .../toolbox/cat12/cat12.m which spm_cat12 % 应返回 .../toolbox/cat12/spm_cat12.m cat12; % 直接调起 CAT12 的独立界面三个都通再去看 SPM 界面。顺序反过来会浪费很多时间——界面是最后渲染的它不出来可能只是图形问题而不是路径问题。3.3 最小闭环一张 T1 进一张灰质图出不要一上来就跑整批数据。先拿一个被试跑通确认输出目录有文件、文件头正确、灰度分布合理再谈批处理。下面是最小的脚本化调用字段名来自 CAT12 的 batch 结构spm(defaults, fmri); spm_jobman(initcfg); t1 D:/neuro/data/sub-001/anat/sub-001_T1w.nii; matlabbatch {}; matlabbatch{1}.spm.tools.cat.estwrite.data {t1}; matlabbatch{1}.spm.tools.cat.estwrite.nproc 1; % 单被试调试别开并行 matlabbatch{1}.spm.tools.cat.estwrite.opts.tpm {D:/neuro/apps/spm12/tpm/TPM.nii}; matlabbatch{1}.spm.tools.cat.estwrite.extopts.regstr 1; % 默认配准强度 matlabbatch{1}.spm.tools.cat.estwrite.extopts.vox 1.5; % 输出体素1.5mm 省时省盘 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.GM.dartel 1; matlabbatch{1}.spm.tools.cat.estwrite.output.WM.native 1; matlabbatch{1}.spm.tools.cat.estwrite.output.CSF.native 1; matlabbatch{1}.spm.tools.cat.estwrite.output.bias.native 1; matlabbatch{1}.spm.tools.cat.estwrite.output.surface 0; % 冒烟测试跳过表面重建 spm_jobman(run, matlabbatch);字段名不必背。正确做法是在 SPM 界面里把 Segmentation 的选项点一遍然后 File → Save Batch 导出成 .mat用load打开看结构照着抄字段。CAT12 每个小版本都可能挪动个别字段抄界面导出的结构永远不会错。参数说明按影响从大到小排nproc是并行进程数调试期一定设 1否则报错信息会被多个进程的输出冲散extopts.regstr是配准强度默认档在成人结构像上够用儿童或明显萎缩的脑可以往上调一档extopts.vox是输出体素大小1.5mm 相比 1.0mm 能把耗时和磁盘占用压到一半左右做群体统计时差异通常可以接受output.surface关掉可以跳过皮层表面重建冒烟测试阶段没必要跑。3.4 冒烟测试的验收标准跑完先看目录。应该出现以mwp1、wp1、p1开头的 NIfTI以及一个记录分割质量的文本文件。文件数量对不上说明输出选项没生效回去检查 batch 里output那几行。再看图像。用 SPM 的 Display 打开p1灰质概率图灰质应该集中在皮层和深部核团脑室和颅骨区域接近零。如果整张图灰蒙蒙、灰白质边界糊成一团多半是配准没收敛或者输入的 T1 本身有严重的运动伪影和强度不均。最后看质量记录文件的几个指标。CAT12 会输出每个被试的配准误差和图像质量评分这两项异常的被试后面统计阶段会变成离群点与其到那时再回头删不如在冒烟阶段就记下来。4. VBM 预处理参数模板、配准强度与调制输出怎么选分割参数不是玄学每个选项背后都对应一个“你要回答什么科学问题”的判断。这一章按输出用途倒推参数而不是罗列选项。4.1 配准强度与模板选择CAT12 把空间配准拆成两步仿射配准把个体脑大致对齐到模板空间非线性配准再细化局部形变。仿射那一步的强度是可调的常见做法是用默认档遇到脑形态偏离模板较远的样本儿童、老年人、明显萎缩往上调一档让仿射阶段多花点时间换取非线性阶段更少的局部扭曲。模板选择在 CAT12 里主要是组织概率图TPM的路径。用默认 TPM 就够它由大量成人数据平均而来。如果研究对象是婴幼儿成人 TPM 明显不合适需要换专门的模板这类模板不是 CAT12 自带的得自己准备并显式指定路径指定错了会表现为分割出的灰质体积系统性偏小或偏大。注意模板换了后续所有体积数值都不能和用默认模板跑出来的结果直接比较。混着用是群体分析里最难查的错误之一。4.2 输出前缀与统计端的对应关系CAT12 输出文件名前面的小写字母有严格含义搞混了统计结果就是错的。这是新手最容易翻车的地方因为文件都在、都能打开看起来一切正常。前缀含义典型用途p1/p2/p3组织概率图未归一化检查分割质量wp1/wp2归一化到模板空间未调制看形状不做体积统计mwp1/mwp2归一化 调制保留局部体积信息标准 VBM 灰质体积分析wj开头雅可比行列式形变场分析、局部萎缩程度DARTEL 导出供 DARTEL 做组间配准的刚性组织图大样本精细配准标准 VBM 用mwp1调制把非线性形变造成的体积变化乘回图像强度里所以每个体素的值反映的是局部灰质体积而不是灰质密度。只用wp1做统计等于把体积信息抹掉结论会偏向“密度”而非“体积”写文章时容易被审稿人抓住。DARTEL 导出是为大样本准备的。CAT12 可以把组织图按 DARTEL 的格式导出交给 SPM 的 DARTEL 工具做组内平均模板再归一化。样本量在几十以上、脑形态差异大时值得走这条路代价是多一整套流程和更长的耗时。4.3 平滑核的选择VBM 统计前要做高斯平滑核宽FWHM常见取 6~10mm。核宽和经验规则有关越接近预期效应团的尺寸统计灵敏度越高核宽太小配准残差会带来大量假阳性核宽太大小范围效应被抹平。我一般先用 8mm 跑一版看整体格局如果预期效应是弥散的皮层改变8mm 合适如果是深部小核团改用 6mm 并配合更严格的团块阈值。平滑在 SPM 的 Smooth 模块做输入选mwp1图像输出会加s前缀统计时读smwp1。平滑前要先确认所有被试的mwp1是同一个包围盒和体素大小。CAT12 默认会用模板的包围盒但改了extopts.vox之后不同批次跑出来的图像体素大小会不一致SPM 的 Smooth 遇到尺寸不一致的输入会报错或者按第一张图的规格裁剪后者更危险因为不报错。4.4 质量检查与样本同质性CAT12 自带 Check Sample Homogeneity本质是算所有被试两两之间的图像相似度画成相关性矩阵和箱线图把明显偏离群体的被试标出来。这个工具的价值在于配准失败往往不会报错只会让某张图看起来“有点不对”肉眼在一百个被试里根本看不出来。阈值怎么定用协方差或相关性都行箱线图的 IQR 倍数常见设 2 或 3。设 2 会标出更多候选适合样本量小、宁可多查的时候设 3 更保守标出来的基本是真问题。被标出来不等于必须剔除先打开图像看确认是配准失败还是解剖本身特殊比如明显脑室扩大再决定。这一步的建议是固定下来每次跑完批量分割都执行一遍不要因为“上次没问题”就跳过。环境换了、SPM 版本升了、批量脚本改了一行都可能让某个被试静默失败。4.5 长流程的资源控制一个被试的完整分割含表面重建在普通工作站上要十几分钟到半小时几十个被试就是一夜。资源控制没做好半夜跑到一半内存耗尽退出第二天还得从头来。nproc设成物理核心数的六到七成比较稳每个进程峰值内存按 2~3GB 估16GB 内存的机器设 4 个进程就接近上限了。临时目录指向剩余空间大的盘分割过程会产生大量中间文件系统盘被写满导致失败的案例不少见。批量跑之前先用一个被试测出单例耗时和内存峰值再乘上被试数这个估算比任何经验值都准。5. 避坑与排查五类装得上却跑不对的现场问题下面五条都是“装完了、也能启动、但结果不对”的场景。按现象、原因、解决的顺序写照着对号入座即可。5.1 启动 SPM 后看不到 CAT12 面板现象which cat12能返回路径但 SPM 主界面底部没有 CAT12 的区块菜单里也没有 CAT 相关项。原因SPM 扫描 toolbox 目录发生在启动时如果 CAT12 是在 SPM 启动之后才addpath进来的面板不会补渲染另一种情况是目录层级多套了一层spm_cat12.m不在toolbox/cat12/的直接子级。解决先restoredefaultpath清干净重新addpath宿主和插件然后重启 MATLAB 再启动 SPM。目录层级问题直接看文件系统确认cat12.m就在toolbox/cat12/下多套的那层删掉或者把内层提上来。5.2 分割跑到一半报内存不足退出现象日志显示处理到某个被试时中断MATLAB 命令窗口出现内存相关的报错前面几个被试的结果正常。原因并行进程数设太高或者某个被试的图像矩阵特别大高分辨率、未降采样单个进程的峰值内存远超估算值。解决把nproc降一半重跑先确认是并发问题还是单例问题。如果单个被试也跑不动把extopts.vox从 1.0 放到 1.5输出体素变大内存和耗时同步下降。批量脚本里加上失败重试和断点续跑别让一个被试失败拖垮整批。5.3 报未定义函数且函数名看起来属于 SPM现象启动 CAT12 或者执行分割时报Undefined function spm_xxx而这个函数在 SPM 目录里明明存在。原因搜索路径里存在另一份同名的旧版 SPM 函数被优先命中了或者genpath把 CAT12 自带的兼容代码加进了路径覆盖了宿主版本。解决which -all spm_xxx看有几个命中把多余的那份从路径里移掉。根治办法是改用逐个addpath而不是genpath并且定期restoredefaultpath清理累积的路径污染。5.4 分割跑完但统计时被试对不齐现象所有mwp1都在SPM 统计也能跑但结果里出现大片位于脑外的“激活”或者某个被试的整体信号明显偏移。原因某个被试的仿射配准失败图像被摆到了模板空间的错误位置但因为流程没报错一直到统计阶段才暴露也可能是不同批次跑的图像体素大小不一致平滑时被静默裁剪。解决跑 Check Sample Homogeneity看相关性矩阵里的离群点再抽几个被试打开wp1叠到模板上看位置。确认是配准问题的被试调高配准强度重跑或者直接剔除。批处理脚本里固定加一步“检查所有输入的维度和体素大小是否一致”这一步几行代码能省掉一整轮返工。5.5 版本号显示和压缩包对不上现象装的是新版本但 CAT12 界面或版本查询返回的是旧版本号。原因机器上有多份 CAT12搜索路径顺序决定了生效的那份或者切换版本后没有重启 MATLAB缓存里的版本信息还是旧的。解决which -all cat12列出所有命中按顺序确认哪个在最前。切换版本时用完整的清空流程clear all、restoredefaultpath、重新addpath、重启 MATLAB四步都做别图省事。6. 批处理与结果校验把重复劳动压进一个脚本单个被试跑通之后真正的成本在批量。手点界面跑五十个被试中间任何一次误点都要重来而且没法复现。我的习惯是把整个流程写成一个函数输入是数据根目录输出是每个被试的状态表跑完一眼就能看出谁成功谁失败。function run_cat12_batch(rootDir, outDir, nproc) % rootDir 下按 sub-*/anat/*T1w.nii 组织输出统一写到 outDir spm(defaults, fmri); spm_jobman(initcfg); files dir(fullfile(rootDir, sub-*, anat, *T1w.nii)); status cell(numel(files), 3); for i 1:numel(files) t1 fullfile(files(i).folder, files(i).name); try matlabbatch {}; matlabbatch{1}.spm.tools.cat.estwrite.data {t1}; matlabbatch{1}.spm.tools.cat.estwrite.nproc nproc; matlabbatch{1}.spm.tools.cat.estwrite.extopts.vox 1.5; matlabbatch{1}.spm.tools.cat.estwrite.output.GM.mod 1; matlabbatch{1}.spm.tools.cat.estwrite.output.surface 0; spm_jobman(run, matlabbatch); % 逐被试串行失败不污染其他人 status{i, 1} t1; status{i, 2} ok; catch ME status{i, 1} t1; status{i, 2} failed; status{i, 3} ME.message; % 记下错误原文便于回溯 end end save(fullfile(outDir, batch_status.mat), status); end外层串行、内层并行的结构是刻意的nproc让单个被试内部并行被试之间串行这样一个被试崩了不会连带其他被试状态表也能准确记录到具体是谁失败。如果反过来让被试之间并行失败信息会和别人的输出混在一起排查成本翻倍。跑完之后的校验我固定做三件事写成一张核对表校验项做法不合格的处理输出文件齐全统计每个被试目录下mwp1是否存在缺失的单独重跑维度一致读所有mwp1的spm_vol比对 dim 和 mat不一致的检查extopts.vox设置样本同质性跑一次 Check Sample Homogeneity离群被试逐个打开确认这三步加起来不到十分钟但能挡掉后面统计阶段最难受的一类返工——数据都跑完了才发现有两个被试从第一步就错了。从那以后我每换一台机器、每升一次版本都先拿一个公开的示例 T1 跑一遍这个最小闭环确认输出文件和图像质量都对再动真实数据。装工具这件事验证一次的成本远低于事后追溯。希望帮到你。本文还有配套的精品资源点击获取