升级 VTK 或 Qt 后，程序能打开，截图看起来也相近，就可以认为没有问题吗？如果某个坐标轴被镜像，模型可能仍然像原来的形状；如果驱动改变抗锯齿，截图可能出现像素差异，却没有任何几何错误。回归验证需要把不同性质分开检查。本文以几个很小的反例说明怎样设计能够发现真正问题的证据。
阅读范围：面向三维可视化、医学影像与桌面软件开发者。本文使用合成数据与工程示例，资料核对日期为 2026 年 10 月 16 日。所述软件功能不等于实际设备精度；本文不涉及患者数据、诊疗建议或临床合格阈值。
图 1：VTK 与 Qt 项目怎样做回归验证？几何、图像与性能分层检查的核心关系（原创工程示意）
一、先列出必须保持的性质
回归不是要求所有输出字节永远不变，而是检查项目承诺的行为仍成立。影像读取要保持数值与空间，几何处理要满足相应误差，显示交互要正确响应，性能则要在规定环境中达标。每项条件都应有明确输入、预期与判定方式。
若目标没有定义，测试很容易退化为“没有崩溃”。这样的烟雾测试有价值，却不能覆盖方向、单位、标签含义或交互状态。建议从最容易造成严重误解的边界开始，建立少量高价值用例，再逐步补充真实失败样本。
二、合成数据可以提供独立真值
真实影像丰富，但未必知道每个像素或几何点的精确预期。合成数组、非对称标记与解析几何可以让正确答案清楚可计算。本文使用四个已知三维点，构造小偏移、单位放大和镜像三类结果。
非对称很重要。对称球体镜像后视觉上几乎不变，测试可能完全漏掉方向错误。不同轴使用不同长度、原点设为非零，并加入已知标记，能够让轴交换、符号与尺度问题更容易暴露。
三、几何比较先确认对应关系
本文函数比较成对点，要求两组数组具有相同非空 N×3 形状，并默认第 i 个点代表相同对象。这个前提非常具体：如果点序被打乱，即使几何集合完全相同，成对距离也可能很大。测试应说明点对应从哪里来。
对于没有对应关系的网格，需要选择点到表面、集合距离或其他适当指标。不能把所有问题都塞进同一个 RMS 公式。相同名称的误差在不同采样和对应策略下可能有完全不同含义，报告必须保留这些条件。
四、RMS 与最大误差互相补充
RMS 能概括总体偏差，最大误差更容易发现局部异常。本文同时输出二者，并以最大值作为示例门限。把少量严重偏移混在大量正确点里，RMS 可能仍然较小，因此不能只看平均指标。
阈值 0.1 仅用于本篇合成测试，不是临床或所有项目的合格标准。真正门限应根据任务、单位和独立验证确定。测试应将阈值写成有来源的配置，而不是开发者为了让当前结果通过随意修改。
五、单位错误可以比截图更隐蔽
将几何乘以 1000 后，若渲染器自动 ResetCamera，模型仍可能铺满窗口，看起来与原图很像。视觉缩放掩盖了物理尺度变化。本文直接比较物理坐标，使单位错误被明确拒绝。
因此回归应检查包围范围、已知长度与索引到物理坐标映射，不能让相机自动适配替代尺度验证。导入导出链路尤其需要带单位记录，避免毫米、米或无单位模型在接口处被混用。
六、镜像错误需要方向敏感样本
镜像后的模型可能保持相同点数、边长和整体外观，但左右语义已经改变。本文将 X 轴取负，通过成对点检查发现问题。若只比较无方向的距离集合，某些镜像关系可能依然通过。
实际数据可以加入明确左右标记或命名参考点，并贯穿读取、重采样、显示与导出。检查世界位置与标签语义，比只看三维模型轮廓更强。方向回归应覆盖完整链路，尤其是 LPS/RAS 与数组轴重排边界。
七、图像完全相等与聚合误差不同
代码让 32×32 图像只有一个像素变化一级，逐值相等检查失败，但归一化 MAE 仍然很小。这不意味着哪种检查必然正确，而是它们回答的问题不同：一项检测任何变化，另一项概括平均差异。
若关键标记只有少数像素，平均指标可能忽略它消失；若抗锯齿略有变化，严格相等又可能产生无意义失败。应根据需求选择区域、通道与指标，并保留差异图供复核，避免只返回一个通过标志。
八、图像基准需要受控渲染状态
相机、窗口尺寸、背景、光照、透明度、字体与抗锯齿都会影响截图。比较前固定这些条件，记录库与驱动环境。否则一张差异图可能主要反映布局或环境变化，无法定位算法是否真的改变。
跨平台若采用容差，应证明它能区分可接受变化与目标缺陷。可以主动注入模型消失、相机偏移和标记错位等反例，检查指标确实失败。只拿正常图反复调阈值，很容易得到一个什么都检测不到的测试。
九、数据层验证能减少视觉歧义
对于影像，直接检查已知像素、方向、间距和数组类型；对于标签，检查类别集合与数量；对于网格，检查单元、边界与关键点。很多性质不需要创建 GUI 就能验证，执行更快，失败也更容易解释。
GUI 测试则负责控件事件、状态联动、DPI 和窗口生命周期。它不应重复所有数值算法，却需要覆盖接口上的真实问题。例如数据正确但显示坐标换算错误，只靠纯数值管线测试就无法发现。
十、性能回归要固定条件并区分阶段
首帧包括初始化、上传与缓存准备，稳态交互则可能复用资源。把两者混在一个平均值里，会掩盖体验问题。性能用例应记录输入规模、硬件、线程配置和测量范围，必要时分别检查峰值内存与耗时。
一次测量容易受到系统负载影响，应采用适当重复和稳定统计，但重复次数不能代替环境控制。性能门限应留有合理依据，不能因为某次波动就无条件放宽。本文没有提供真实项目性能基准，只说明应怎样组织证据。
十一、失败样本是回归集的来源
修复过的方向、缓存或生命周期问题，应保留尽可能小的复现样本。测试要检查原来会失败的性质，而不是复制实现步骤。这样未来重构即使改变内部结构，也能继续验证对用户重要的行为。
同时维护样本来源、预期与适用版本。若数据参与了调参，就不应继续被称为完全独立最终验证。真实数据使用还需遵守相应授权与隐私要求；本篇使用合成数据，避免将敏感内容放进示例。
十二、升级报告要说明变化与未覆盖项
一次回归通过只能支持实际检查过的范围。报告应列出版本、环境、通过项、失败项和未覆盖项，并对预期变化给出理由。不能把“所有测试通过”写成“所有场景已经验证”。
本文示例让小偏移通过、单位和镜像失败，并展示图像平均差异的局限。它可以作为项目分层验证的起点，但不是完整测试框架。真正有价值的是每个结论都能回到具体输入、断言与运行记录，而不是测试数量很多。
完整示例与执行方式
本系列使用独立 Python 3.11 环境，实际安装 VTK 9.5.2、PySide6 6.10.1，以及示例需要的 NumPy、SciPy、NiBabel、pydicom。各篇只需安装实际导入的依赖。将下方代码保存为 demo.py 执行；代码涉及的尺寸按正文约定解释，不应直接作为真实系统的参数。
import numpy as np def geometric_gate(expected,actual,threshold_mm): a,b=np.asarray(expected,float),np.asarray(actual,float) if a.shape!=b.shape or a.ndim!=2 or a.shape[1]!=3 or not len(a): raise ValueError('Paired nonempty Nx3 points required') if not np.isfinite(a).all() or not np.isfinite(b).all() or threshold_mm<=0: raise ValueError('Invalid geometry or threshold') lengths=np.linalg.norm(a-b,axis=1) return dict(rms=float(np.sqrt(np.mean(lengths**2))), maximum=float(lengths.max()),passed=bool(lengths.max()<=threshold_mm)) truth=np.array([[0,0,0],[10,0,0],[0,20,0],[0,0,30.]],float) good=truth+.01;wrong_units=truth*1000;mirrored=truth*np.array([-1,1,1]) assert geometric_gate(truth,good,.1)['passed'] assert not geometric_gate(truth,wrong_units,.1)['passed'] assert not geometric_gate(truth,mirrored,.1)['passed'] image=np.full((32,32),100,dtype=np.uint8) changed=image.copy();changed[15,15]=101 assert not np.array_equal(image,changed) normalized_mae=np.mean(abs(image.astype(float)-changed))/255 assert normalized_mae<1e-4 print('good_geometry',geometric_gate(truth,good,.1)) print('wrong_units',geometric_gate(truth,wrong_units,.1)) print('image_normalized_MAE',normalized_mae) print('PASS: geometry failures despite small aggregate image differences')补充实验：独立数值检查
下面的补充脚本已独立运行通过。它把正文中的关键关系转成小型断言，便于区分数据处理和显示表现；保存为 extra.py 后运行。断言覆盖范围以代码为准，不代表完整项目已经验证。
import numpy as np def paired_error(a,b): a,b = np.asarray(a,float),np.asarray(b,float) if a.shape != b.shape or a.ndim != 2 or a.shape[1] != 3: raise ValueError('Paired Nx3 arrays required') distances = np.linalg.norm(a-b,axis=1) return np.sqrt(np.mean(distances**2)),distances.max() reference = np.array([[0.,0,0],[10,0,0],[0,20,0],[0,0,30]]) permuted = reference[[1,0,2,3]] assert paired_error(reference,permuted)[1] == 10 assert set(map(tuple,reference)) == set(map(tuple,permuted)) # Aggregate image error can hide a small critical region. baseline = np.zeros((128,128),dtype=np.float32) baseline[60:64,60:64] = 1 missing_marker = np.zeros_like(baseline) global_mae = np.abs(baseline-missing_marker).mean() region_mae = np.abs(baseline[60:64,60:64]-missing_marker[60:64,60:64]).mean() assert global_mae < .001 assert region_mae == 1 # A maximum-distance check retains the outlier evidence lost in a mean. many = np.zeros((10000,3)) with_outlier = many.copy() with_outlier[0,0] = 1 rms,maximum = paired_error(many,with_outlier) assert rms == .01 and maximum == 1 print('global_MAE',global_mae,'critical_region_MAE',region_mae) print('PASS: correspondence and critical regions require explicit validation')本机执行结果与验证口径
good_geometry {'rms': 0.017320508075689193, 'maximum': 0.017320508075689675, 'passed': True} wrong_units {'rms': 18689.578646935835, 'maximum': 29970.0, 'passed': False} image_normalized_MAE 3.829656862745098e-06 PASS: geometry failures despite small aggregate image differences以上为本任务中的真实执行输出。断言检查的是代码明确表达的性质；不能由一次通过推断其他平台、其他输入或完整业务流程已经验证。示例若说明未渲染、未编译或采用合成文件，应按该限制解释结果。
图 2：常见现象、可能原因与检查行动（原创工程示意）
将示例接入项目：三条执行路径
先把关键数据契约变成断言
选择已知值、非等方间距、非零原点与方向标记，覆盖读取、转换和导出。定义成对点或表面距离的含义，先验证单位与空间，再进入显示。每个门限保留来源，避免测试随着当前实现漂移。
再加入受控截图与真实交互
固定场景状态，保存基准和差异图，按需求选择比较指标。对 GUI 检查快速操作、取消、联动、DPI 与关闭，重点覆盖数值层无法发现的接口问题。主动注入典型缺陷，确认测试真正有检测能力。
最后形成版本化验证记录
记录库、系统、驱动、数据版本与结果。性能与正确性分别判定，预期变化经复核后更新基准，保留原因。失败时优先缩小样本与定位层级，不要只通过修改阈值让流水线恢复绿色。
排错记录应如何写？
截图相近但测量值错误
可能相机自动适配掩盖单位或方向变化。
检查物理坐标、已知长度与方向敏感标记。
像素差异很多但几何正常
可能环境、抗锯齿或字体变化。
固定渲染状态，结合数据与区域图像指标复核。
平均误差小却漏掉关键异常
可能少量局部缺陷被整体统计稀释。
增加最大值、关键区域与主动注入缺陷用例。
升级后测试通过用户仍遇到问题
可能未覆盖真实接口、生命周期或输入范围。
保留最小失败样本，补充相应契约而非盲目加测试。
适用边界与独立验证
本篇验证合成成对点与简单二维数组，没有运行完整 Qt UI 回归、所有 VTK 过滤器、跨平台图像基准或性能压力测试。数值门限只属于示例，实际验收必须结合任务与独立数据制定。
建议保留原始输入、数据单位、参数、软件版本和失败日志。检查数据如果被反复用于选择实现或调参，就不应继续作为完全独立的最终验证集。对外报告应区分功能通过、几何正确、性能测量与环境兼容性，避免用一个成功截图代替全部证据。
参考资料
NumPy testing assertions
VTK testing documentation
Qt 6.10：Qt Test overview
写在最后
“知不足，然后能自反也；知困，然后能自强也。”
—— 《礼记·学记》
把每一步的输入、状态和证据写清楚，比凭经验反复尝试更容易积累可靠的工程判断。
