简介CAT12.7 版本安装包面向从事脑结构磁共振与T1加权影像处理的科研人员、学生以及需要复现旧版分析流程的用户重点解决官方更新后老版本不易获取、运行环境难以对齐的问题。压缩包共八百二十二个文件约二百二十三兆字节主体包括MATLAB脚本、影像数据、脑区标注、图示文档、多平台二进制程序、模板与掩膜等覆盖代码、数据及说明材料。包内可见Schaefer2018、HCP MMP1、a2009s等分区标注并配有CAT12工具函数与表面处理脚本可用于T1影像分割、配准、表面指标计算及结果核查目录组织贴近工具箱原始结构便于按功能查找脚本、模板和示例数据。已有1731人学习下载适合希望按固定版本对照笔记复现实验、减少旧包缺失困扰的读者并降低旧环境搭建难度。1. CAT12.7 安装包装完之后不报错才算真正开始CAT12.7 安装包下载下来后是一个压缩包解压后得到一堆.m文件和若干子目录里面没有 exe也没有安装向导。很多人第一次拿到它双击无反应就以为下载错了。其实它是一个跑在 MATLAB 之上的 SPM12 工具箱全称是计算解剖工具箱做的是脑结构像的 VBM 分析、表面形态测量和 ROI 统计靠的是 MATLAB 解释执行源码所以所谓“安装”本质是把目录放对、路径挂上、SPM 认得它。它适合两类人手里已有 T1 结构像、想做灰质体积或皮层厚度的影像从业者以及要把分段流程批量化跑几百例的工程侧同学。不适合完全没碰过 MATLAB 的人硬上因为九成的报错都不是 CAT12 本身的问题而是路径、版本、内存这三件事。2. 版本咬合MATLAB、SPM12 与 CAT12.7 的三层依赖CAT12 不是一个独立程序它从下往上叠了三层MATLAB 提供解释器和图形环境SPM12 提供图像读写、配准、统计的底座CAT12 在这一层之上实现组织分割、颅骨剥离、表面重建。任何一层没对齐表现出来都是 CAT12 报错但根因往往在下面两层。所以装之前先把这三层的关系理清比装完再一处处排查省事得多。2.1 谁调用谁从一次cat12命令看调用链在 MATLAB 命令行敲cat12实际发生的事是MATLAB 在当前搜索路径里找到cat12.m这个文件做几件事——检查 SPM12 是否在路径上、检查 SPM12 的修订号是否满足要求、把 CAT12 自己的子目录cat_*、spm_cat12、CAT、atlases等挂进路径、最后调spm起图形界面并把 CAT12 的按钮注册进去。这一串动作只要有一环失败你看到的就是一句很短的报错比如Undefined function spm或者界面上根本没有 CAT12 面板。理解这条调用链的价值在于定位。报错说找不到spm问题在第二层报错说cat12未定义问题在第一层的路径能进界面但点 Segment 之后崩问题通常在第三层的参数或数据。我一般建议按这个顺序验证别一上来就重装。至于版本对应关系CAT12 每个大版本都对应一个 SPM12 的最低修订号安装包里通常带一份说明文档第一件事就是翻它的依赖段落。与其死记数字不如记住验证方法CAT12 启动后会在命令行打印自己检测到的 SPM12 修订号两者不匹配时会有一行醒目提示。看到这行提示就别往下跑了先去把 SPM12 更新到匹配版本否则后面分割出来的结果可能悄悄错掉。MATLAB 这边太老的版本会因为语法不兼容直接报解析错误太新的版本偶尔会遇到图形组件行为变化。稳妥区间是近几年的常规版本装在默认路径下最省心。另一个常被忽略的点是工具箱依赖分段流程里会用到图像形态学运算和统计函数缺了对应工具箱报错信息会指向一个你看不懂的内部函数名比如某个连通域标记函数未定义。2.2 目录怎么摆路径里不能出现的四类字符CAT12 的推荐位置是 SPM12 的toolboxes子目录下也就是spm12/toolboxes/cat12/。这么做的好处是 SPM12 启动时会自动扫描toolboxes你少写一行addpath坏处是如果你以后想换 SPM12 版本CAT12 得跟着搬。我自己的习惯是放在一个独立的工具目录里用addpath显式挂载路径写死在启动脚本里换机器只改一行。路径本身有四类字符绝对不能出现中文、空格、括号、波浪线之外的各类符号。原因不玄学SPM12 内部大量用字符串拼接生成文件名遇到空格会被当成参数分隔遇到非 ASCII 字符在某些系统上会被转码成乱码最后报的是“文件不存在”可你明明看得见文件在那儿。血泪经验是哪怕你其他项目都在中文目录下跑得好好的CAT12 也别赌。还有一层目录陷阱来自解压本身。很多压缩包解开后是CAT12.7_Rxxxx/CAT12.7_Rxxxx/这样的双层结构外层只有内层一个文件夹。如果你把外层路径挂上去cat12.m根本不在搜索路径里命令行敲cat12自然未定义。解压完先ls一眼确认cat12.m就在你准备挂的那个目录的第一层。2.3 依赖自检三条命令把缺的东西一次列清装完之后不要急着点界面先在 MATLAB 里跑一段自检。这段代码的作用是把“当前路径上到底有没有、是哪个版本、依赖工具箱齐不齐”一次性打印出来省得后面出问题时来回猜。% CAT12 依赖自检在 MATLAB 命令行直接粘贴执行 targets {spm, cat12, spm_jobman, spm_preproc}; for k 1:numel(targets) p which(targets{k}); if isempty(p) fprintf([缺失] %-12s 不在搜索路径上\n, targets{k}); else fprintf([OK] %-12s - %s\n, targets{k}, p); end end % 打印 SPM12 修订号CAT12 启动时也会打这里提前看 try v spm(Ver); fprintf(SPM 版本: %s\n, v); catch fprintf(SPM 未能初始化先解决上一层问题\n); end % 检查两个常用工具箱是否存在 tb {Image Processing Toolbox, Statistics and Machine Learning Toolbox}; for k 1:numel(tb) if isempty(ver(tb{k})) fprintf([警告] 未检测到 %s\n, tb{k}); end end代码逻辑很直白which只看搜索路径不看文件是否存在所以它能精准回答“MATLAB 到底认不认这个函数”。如果spm那行是缺失先别管 CAT12去把 SPM12 的顶层目录加进路径。spm(Ver)会触发 SPM 的初始化顺便把版本号打出来这一步在无图形界面的服务器上也能跑。参数上唯一需要改的是targets列表如果你的 CAT12 版本里没有spm_cat12把不存在的名字删掉即可缺一个次要函数不影响主流程。工具箱那两行是警告不是硬性拦截缺了也能跑一部分功能但跑到具体步骤会断早点补上更省事。自检过了再进下一章。没过的话下面这节就是给你准备的。3. 从压缩包到界面四步把 CAT12.7 挂进 SPM12这一步的目标很具体命令行敲cat12弹出 CAT12 的主界面界面上能看到版本信息和 SPM12 的修订号并且 SPM 主窗口底部的工具箱区域出现 CAT12 按钮。达到这个状态安装就算完成后面所有问题都是数据问题和参数问题。3.1 解压与目录扁平化先在 shell 里把包解开顺手确认层级。下面的命令做了三件事解压到指定目录、列出第一层内容、如果发现是双层同名目录就自动把内层提上来。# 假设压缩包在 ~/Downloads目标工具目录为 ~/tools mkdir -p ~/tools unzip -q ~/Downloads/CAT12.7_*.zip -d ~/tools/ # 看一眼第一层是什么 ls -1 ~/tools # 如果出现 CAT12.7_xxxx/CAT12.7_xxxx 这种双层结构把内层提上来 cd ~/tools if [ -d CAT12.7_xxxx/CAT12.7_xxxx ]; then mv CAT12.7_xxxx/CAT12.7_xxxx ./cat12_tmp rm -rf CAT12.7_xxxx mv cat12_tmp cat12 fi # 最终验收cat12.m 必须在这一层 ls ~/tools/cat12/cat12.munzip -q的-q是静默模式包大的时候不刷屏。中间那段判断是我每次都会做的动作因为压缩包作者打包习惯不一样有的带一层壳有的不带手工判断容易看花眼。最后一行ls是关键验收能不能看到cat12.m看到就说明目录层级对了。目录名我统一改成小写cat12好处是启动脚本里路径稳定不用每次跟着版本号改。版本号信息在文件内部不影响使用。3.2 Set Path 与 savepath让路径活过这次会话只跑一次addpath是临时的关掉 MATLAB 就没了。要么每次启动都执行一遍要么用savepath写进用户的pathdef.m。两种做法各有适用场景我一般两样都做启动脚本里显式addpath保证换机器能用同时savepath让日常手工调试省一步。% 一次性挂载把下面两行路径改成你自己的实际位置 spm_dir /home/user/tools/spm12; cat_dir /home/user/tools/cat12; addpath(spm_dir); % genpath 会把 cat12 下所有子目录都加进来包括 atlases 和 external addpath(genpath(cat_dir)); % 验证 assert(~isempty(which(spm)), SPM12 路径不对); assert(~isempty(which(cat12)), CAT12 路径不对); % 保存路径可选写入用户级 pathdef status savepath; if status ~ 0 fprintf(savepath 失败通常是安装目录无写权限改用启动脚本方式即可\n); endgenpath这一行的取舍值得说一下。它把所有子目录一次性加入包括几十兆的图谱目录和第三方 external 目录启动时会慢几秒但省心不会出现“某个函数在子目录里没挂上”的怪问题。追求启动速度的做法是只加顶层让 CAT12 自己管子路径代价是某些边缘功能可能找不到依赖出错时你得手工补。savepath返回非零是常见现象尤其是 MATLAB 装在系统级目录、当前用户没有写权限的时候。这时候不用纠结把上面几行存成一个startup_cat12.m在 MATLAB 的启动脚本里run一下就行效果一样。3.3 首启验证界面、版本行、按钮三处对齐进 MATLAB切到 SPM12 目录再启动这一步不能省。SPM 有些内部资源是按当前工作目录的相对路径找的在任意目录启动偶尔会报资源缺失。cd(/home/user/tools/spm12); spm fmri; % 或 spm pet / spm default起 SPM 主界面 cat12; % 打开 CAT12 主界面spm fmri只是选了一套界面布局和默认参数对结构像分段没有实质影响用spm default也一样。CAT12 界面起来之后看三个地方标题栏或左下角的 CAT12 版本号、命令行窗口打印的 SPM12 修订号、SPM 主窗口底部工具箱区是否出现 CAT12 按钮。三处都对上安装环节结束。如果cat12命令能起界面但 SPM 主窗口没有按钮通常是启动顺序反了——先起 CAT12 后起 SPM注册动作被覆盖。反过来先spm再cat12就好。3.4 无界面服务器把图形依赖摘掉再跑大部分实际生产环境是没有桌面的 Linux 服务器这时候直接跑带界面的启动方式会卡在图形初始化。MATLAB 提供-nodisplay和-nosplash两个开关配合-r执行完退出是最通用的批处理入口。#!/usr/bin/env bash # run_cat12_batch.sh —— 服务器端无界面调用模板 MATLAB_BIN/usr/local/MATLAB/bin/matlab SCRIPT/home/user/work/batch_segment.m $MATLAB_BIN -nodisplay -nosplash -nodesktop \ -r try, run($SCRIPT); catch ME, disp(getReport(ME)); end; exit-nodisplay摘掉图形后端-nosplash跳过启动画面-nodesktop不加载编辑器。-r后面那串用try/catch包住是必须的批处理里任何一步抛异常如果不捕获MATLAB 会停在交互提示上不退出任务调度器那边看到的就是“进程挂死”而不是“失败”。getReport(ME)会把完整堆栈打到标准输出日志里能直接看到出错行。再补一句关于独立版的说明。CAT12 还有不需要 MATLAB 的独立运行版本靠预编译运行时跑。它的优点是部署轻缺点也明确不支持全部功能尤其是表面相关的处理和部分交互式检查参数字段也可能和源码版对不上。如果只是批量跑标准分段独立版够用要做皮层表面或者调试参数还是得回到源码版。4. 第一次分段把一例 T1 跑成可统计的灰质图安装通了之后第一个真正的考验是跑通一例。分段segmentation是 CAT12 的核心动作输入一张 T1 加权结构像输出灰质、白质、脑脊液的概率图以及配准到标准空间的变形场和调制后的组织图。这些输出后面要进统计所以第一步跑出来的东西质量直接决定整批数据的可用性。4.1 输入侧准备头信息、方向与命名CAT12 对输入的要求比想象中宽松它内部会做仿射预校正头信息有点偏也能救回来。但有两件事它会明确抱怨图像不是三维的比如四维时间序列误传以及图像朝向信息缺失。前者报错很直接后者可能不报错但配准结果歪掉。我一般在上传之前先扫一遍头信息把体素尺寸、维度、朝向打出来。体素各向异性太强比如层厚 5mm、层间距 1mm 那种的数据分割出来的灰质边界会明显毛糙这种数据能重扫就重扫不能重扫就在报告里标注别当成正常样本混进去。命名上建议用 BIDS 风格的sub-XXX_T1w.nii不是为了好看是为了后续批处理脚本能用通配符一次抓全。文件名里带空格、带中文、带多个点都会在批处理拼接路径时出问题。4.2 分段参数APP、LAS、GCUT 各管什么什么时候动CAT12 的分段界面参数不少但真正需要你判断的只有三个其余留默认。第一个是偏场校正的强度界面上叫 APP 相关的那一项。核磁图像受场强不均影响同一块组织在不同位置的灰度会缓慢漂移偏场校正就是把这个漂移抹平。强度调高抹得狠适合表面线圈、大视野、信号衰减明显的数据调低抹得保守适合本身对比度就弱的数据。判断依据不是猜是看输出报告里的偏场校正前后对比图如果脑内出现明显的明暗台阶说明强度不够如果白质内部被抹得过于均匀、灰白质边界反而糊了说明过头了。第二个是局部自适应分割的强度。常规数据留在中间值即可遇到灰白质对比度特别低比如某些序列参数下的图像再往上加。加太多会让分割结果偏向“平滑”细小结构比如海马旁的回会被吃掉。第三个是颅骨剥离强度。CAT12 默认会做颅骨剥离强度不够的表现是脑外组织硬脑膜、静脉窦、眼球后脂肪被误判成灰质报告里表现为脑外出现成片的灰质概率强度过高则会把脑皮层表面削掉一层表现为灰质体积系统性偏低。这两类错误都很难在单例上肉眼发现必须看报告里的表面渲染图。还有一个隐藏选项值得提是否输出表面。第一次跑建议关掉表面重建耗时是分段的好几倍而且失败率高依赖的拓扑修复步骤对数据质量敏感。等分段流程稳定了再单独开表面。4.3 把界面设置导成 matlabbatch一次配置批量复用界面点一遍只能跑一例批量必须落到脚本。CAT12 基于 SPM 的批处理系统界面上所有设置都能导出成一个matlabbatch结构体。做法是在界面上配好参数后点菜单里的“Save Batch”存成.mat然后在脚本里load进来改数据字段。% batch_segment.m —— 单例分段的批处理骨架 addpath(/home/user/tools/spm12); addpath(genpath(/home/user/tools/cat12)); % 1) 载入界面上导出的批处理模板 load(/home/user/work/tpl_segment.mat); % 变量名必须是 matlabbatch % 2) 只改数据入口其余参数沿用模板 input_nii /data/sub-001/anat/sub-001_T1w.nii; matlabbatch{1}.spm.tools.cat.estwrite.data {[input_nii ,1]}; % 3) 并行进程数不超过物理核数也不超过可用内存能撑住的份数 matlabbatch{1}.spm.tools.cat.estwrite.nproc 4; % 4) 关掉表面输出先保证分段稳定 matlabbatch{1}.spm.tools.cat.estwrite.output.surface 0; % 5) 执行 spm_jobman(run, matlabbatch);字段路径spm.tools.cat.estwrite是 CAT12 分段写出的分支名data里那个,1是 SPM 的帧选择语法表示取第一卷不加会报格式错误。nproc控制并行这里有个坑后面单独讲。最后一行spm_jobman(run, ...)是执行入口出错时它会抛出带步骤名的异常日志里能定位到具体是哪个子步骤崩的。需要提醒的是字段名在不同小版本之间会挪位置。比如某些版本把配准选项放在extopts.registration下某些版本又拆了一层。所以最稳的做法不是抄别人的脚本而是在你自己机器的界面上配一遍、导出、看清楚结构再往里填数据。抄来的脚本报“字段不存在”九成是版本差异不是你的错。4.4 输出核对从概率图到质量报告一例跑完输出目录里会多出一堆文件。第一次看到容易懵其实按前缀能分清楚。前缀/文件含义用途p1p2p3灰质/白质/脑脊液概率图原生空间检查分割质量不直接进统计wp1wp2配准到标准空间的概率图空间对齐检查mwp1mwp2调制后的组织图体积信息保留VBM 统计的主要输入wj_开头雅可比行列式调制结果另一种体积校正方式cat_*_report.pdf单例质量报告逐例质检的核心依据cat_*_catlog.txt运行日志与参数快照复现和排错统计用的主力是mwp1它把配准时的形变缩放补偿回去了所以反映的是真实体积而不是形状。用wp1做统计是常见误用那样得到的结论会被头颅大小带偏。质量报告比输出文件更重要。报告里有几处必看分割结果的表面渲染图有没有脑外组织残留、图像质量评级一个字母等级从优到差、以及几个量化指标。评级差的样本不要硬塞进统计宁愿剔除并在方法里写清楚剔除标准。我见过太多人跑完几百例直接进组分析最后组间差异其实是几个坏样本撑起来的这种错误没法靠统计方法补救。5. 避坑与排查跑不起来时的六类现场这一章按现象组织不按理论组织。每一条都是我在不同机器、不同数据上真实撞过的按“看到什么 → 为什么 → 怎么办”写遇到对得上的直接照做。5.1 安装期的三个坑层级、字符、版本打架现象一命令行敲cat12报未定义但目录里明明有cat12.m。原因基本是路径挂错了层。解压出来的双层目录结构你addpath的是外层cat12.m在内层MATLAB 搜索路径里没有它。另一个可能是你addpath用了相对路径而当前工作目录已经换了。解决办法which(cat12)返回空就用绝对路径重新挂挂完再which一次确认顺手把双层目录拍平一劳永逸。现象二SPM 起来了但一点分段就报找不到某个文件文件名里还带着奇怪的问号。路径里有中文、空格或特殊符号。SPM 内部拼路径时不转义空格被当成分隔符非 ASCII 字符在部分系统上被转码。这个坑最坑的地方是它时好时坏——某些步骤不涉及路径拼接就能过跑到一半才炸。解决办法只有一个把数据、工具、输出全部挪到纯英文无空格路径下包括你的用户名目录有些系统的家目录带中文。挪完重新跑别在原路径上试图绕。现象三界面能起分段也能跑但结果明显不对灰质图一片糊。八成是 SPM12 版本和 CAT12 版本不匹配或者机器上同时装了两份 SPM12路径里挂的是旧的那份。旧版 SPM 的配准和分割接口跟新版有差异CAT12 调到的函数签名对不上时不一定报错而是静默走了一条退化的路径结果看起来“跑完了”但质量很差。解决办法先which(spm)确认只有一份、且是你期望的那份再核对 CAT12 启动时打印的修订号提示有警告就先更新 SPM12。这个坑的隐蔽性最强因为它不报错。5.2 运行期的三个坑内存、并行、假成功现象四跑到一半进程被杀日志最后一行是内存相关或直接没有日志。分段是内存大户一例三维 T1 在配准阶段能吃下好几个 G。批量时如果nproc设成物理核数N 个进程同时抢内存系统 OOM 杀进程表现就是“莫名消失”。而且被杀的时候往往不写日志你在日志里什么都看不到像个黑匣子。解决办法nproc按内存算不按核数算——可用内存除以单例峰值取小值不确定单例峰值就先串行跑一例用系统监视看峰值再倒推并行度。宁少勿多串行跑一晚上也比半夜全崩强。现象五批处理里某几例失败了但整个任务返回码是 0调度器认为成功。这是“假成功”根源是脚本用了try/catch但没把异常往上抛。CAT12 的批处理在内部某些步骤失败时可能只往日志里写一行不抛异常spm_jobman照常返回。解决办法跑完主动核对输出文件数量每个输入必须对应一组完整的输出至少mwp1和报告文件数量对不上就判定失败。这一步一定要写进脚本别靠人眼看。现象六报告显示分割完成但某几例的报告里质量评级很差表面渲染图能看到脑外残留。不一定是参数问题先怀疑数据。层厚过大、扫描时头动明显、对比度异常的数据默认参数救不回来。处理顺序是先看原始图有没有明显伪影再试着单独把颅骨剥离强度调高一档重跑该例还不行就剔除并在记录里写明原因。硬调参数把坏数据“修好”往往是把真实信号也一起抹掉了得不偿失。顺带提一个环境层面的坑在容器或集群里跑临时目录可能挂的是很小的分区分段过程中的中间文件写满临时空间报错信息却是跟磁盘无关的 IO 错误。跑之前df -h看一眼临时目录把 MATLAB 的临时目录指到大分区上能省掉一整晚的排查。6. 批量复核把“跑完了”变成“跑对了”单例跑通只是起点真正决定这批数据能不能用的是复核环节。我现在的习惯是批量跑完之后不直接进统计先过一遍自动化的初筛把明显不合格的挑出来再人工看剩下的报告。这个流程写成一个脚本跑完批量顺手执行五分钟出结果。初筛做三件事数文件、扫日志、抓质量评级。#!/usr/bin/env bash # qc_sweep.sh —— 批量结果的机械化初筛 OUT_ROOT/data/derivatives/cat12 IN_LISTsubjects.txt # 每行一个 sub-XXX fail0 while read -r sid; do d$OUT_ROOT/$sid # 1) 关键输出是否齐全调制灰质图 质量报告 n_mwp$(find $d -name mwp1*.nii 2/dev/null | wc -l) n_rpt$(find $d -name cat_*_report.pdf 2/dev/null | wc -l) if [ $n_mwp -lt 1 ] || [ $n_rpt -lt 1 ]; then echo [缺失] $sid mwp1$n_mwp report$n_rpt fail$((fail1)); continue fi # 2) 日志里抓典型错误关键词 if grep -qiE error|failed|out of memory $d/cat_*_catlog.txt 2/dev/null; then echo [日志异常] $sid fail$((fail1)); continue fi echo [通过] $sid done $IN_LIST echo ---- 异常合计: $fail ----subjects.txt是受试者清单一行一个脚本按行读。find加wc -l是数文件的老办法比ls稳文件名里有特殊字符也不会出错。日志关键词那一步只做粗筛error出现在正常日志里也不是没有可能比如参数说明里带这个词所以它标出来的是“需要人工看一眼”不是“一定失败”。第二层是质量评级的分布。CAT12 报告里的评级是分级的把每个样本的评级抽出来做成一张频数表一眼能看出这批数据的整体质量。如果某一档集中了大量样本先别急着往下走抽三五例打开报告看渲染图确认是数据本身的问题还是参数设偏了。参数设偏的典型特征是所有样本的评级都不高但也不至于失败整体平移了一档——这种批量重跑一次就能救回来比逐例调参划算得多。第三层才是人工。我只人工看两类评级落在差档的以及自动化初筛标记异常的。每例看三样东西表面渲染图有没有脑外残留、灰白质边界是否干净、配准后的图像与模板重叠是否合理。三样都过就放行有一样存疑就重跑该例并记录。从那以后我每次批量跑完都强制先走一遍这个初筛再碰统计数据哪怕只有十几例也一样。因为“跑完了”和“跑对了”之间隔着的往往就是那几个不报错但结果已经歪掉的样本而它们对组间比较的影响远比你想的大。希望帮到你。本文还有配套的精品资源点击获取