OpenCV 4.5.5+ 原生支持 cv::quality::QualitySSIM 类，需链接 opencv_quality 库；输入须为同尺寸单通道图，返回 cv::Scalar 中 [0] 为 SSIM 值（0~1），默认 11×11 窗口可按需调整。
OpenCV 4.5.5+ 自带 cv::quality::QualitySSIM 类，无需手写公式
OpenCV 从 4.5.5 版本起原生支持 SSIM 计算，封装在 cv::quality 模块中。低于该版本（如 4.5.4 或 3.x）调用会链接失败或报 undefined reference to `cv::quality::QualitySSIM::compute'。确认版本最直接的方式是运行：
pkg-config --modversion opencv4或在代码中加
CV_VERSION_MAJOR 和 CV_VERSION_MINOR 判断。
启用该功能需额外链接 opencv_quality 库（CMake 中要显式添加）：
find_package(OpenCV REQUIRED COMPONENTS core imgproc quality)
target_link_libraries(your_target ${OpenCV_LIBS})
漏掉 quality 组件是编译期最常踩的坑——函数声明可见，但链接时失败。
cv::quality::QualitySSIM::compute() 的输入要求很严格
该函数只接受单通道（CV_8UC1 或 CV_32FC1）图像，且两张图必须尺寸完全一致。传入彩色图（CV_8UC3）会触发断言失败，错误信息类似：
OpenCV(4.5.5): error: (-215:Assertion failed) src1.size == src2.size && src1.type() == src2.type() in function 'compute'
立即学习“C++免费学习笔记（深入）”；
正确做法是先转灰度再计算：
- 用
cv::cvtColor(img, gray, cv::COLOR_BGR2GRAY)转换（注意 OpenCV 默认读取为 BGR） - 确保两图分辨率相同——如果原始图尺寸不同，必须先
cv::resize()对齐，不能依赖函数内部自动适配 - 若图像含 alpha 通道，需先剥离（
cv::cvtColor(img, rgb, cv::COLOR_BGRA2BGR)再转灰度）
SSIM 返回值是 cv::Scalar，不是单个 float
cv::quality::QualitySSIM::compute() 返回一个 cv::Scalar，其 [0] 分量才是最终 SSIM 值（范围 0~1），其余分量为各通道 SSIM（单通道图则只有 [0] 有效）。常见误用是直接打印 result 而不取索引，导致输出类似 [0.921345] 这种带括号的字符串，无法参与后续数值比较。
安全写法：
cv::Ptr<cv::quality::QualitySSIM> ssim = cv::quality::QualitySSIM::create(); cv::Scalar score = ssim->compute(gray1, gray2); float ssim_value = score[0]; // 必须取 [0]
若需多通道分别评估（如 RGB 图逐通道算），应先分离通道再调用，而非依赖 score[1]、score[2]——单通道输入下它们无意义。
性能敏感场景慎用默认窗口大小
默认使用 11×11 高斯窗口计算局部均值与方差，对小图（如 64×64）可能过重，导致 SSIM 值偏高且对噪声不鲁棒；对大图（如 2000×1500）则计算变慢。可通过 setQualityMap() 启用质量图输出，或传入自定义 cv::Size 改变窗口：
ssim->setGaussianKernelSize(cv::Size(7, 7)); // 改为 7×7 窗口
但注意：窗口尺寸必须为奇数，且不能小于 3；大于 15 后边际收益极低，反而增加浮点误差累积。实测在多数自然图像上，7×7 和 11×11 结果差异通常
真正容易被忽略的是：SSIM 对亮度/对比度线性变换不敏感，但对 gamma 校正、直方图均衡等非线性操作高度敏感——如果两张图预处理方式不一致（比如一张做了 CLAHE，另一张没有），算出来的 SSIM 值已失去参考价值。
