OpenCV 4.5+ 的 cv::quality::QualitySSIM 需启用 opencv_contrib 并链接 opencv_quality 库；输入须为同尺寸、单通道、CV_32F/CV_64F、[0,1]归一化图像；手动实现更可控，核心用 boxFilter 计算局部均值与方差。
OpenCV 4.5+ 自带 cv::quality::QualitySSIM 类，但默认不启用
OpenCV 从 4.5.0 开始在 opencv_contrib 的 quality 模块中提供了 SSIM 实现，但它不是 core 或 imgproc 的一部分，编译时需显式开启 OPENCV_ENABLE_NONFREE（旧版）或更关键的是：必须启用 OPENCV_DNN_BACKEND_OPENCV 并确保 opencv_contrib 正确编译链接。很多用户直接 #include <opencv2></opencv2> 却报错“undefined reference”，根本原因是链接时没包含 opencv_quality 库。
实操建议：
- 确认 CMake 配置中传入了
-D OPENCV_EXTRA_MODULES_PATH=/path/to/opencv_contrib/modules - 检查构建输出是否出现
Module opencv_quality: YES - 链接时添加
-lopencv_quality（Linux/macOS）或对应 .lib（Windows） - 若仅需单次计算且不想折腾 contrib，用纯 OpenCV + NumPy（Python）或手动实现更省事——C++ 手动算也不复杂
cv::quality::QualitySSIM::compute() 的输入要求很严格
该函数要求两幅图像：CV_32F 或 CV_64F 类型、单通道（灰度）、尺寸完全相同、值域在 [0, 1] 区间。任何偏差都会导致静默返回空结果或 NaN，且无明确错误提示。
常见错误现象：
立即学习“C++免费学习笔记（深入）”；
- 传入
CV_8U图像 → 返回空cv::Scalar，.val[0]为 0 - 彩色图直接传入 → 只处理第一个通道，其余丢弃，结果不可信
- 图像尺寸不一致 → 断言失败或崩溃（取决于 OpenCV 版本）
- 像素值未归一化（如 0–255）→ SSIM 值远低于合理范围（正常应在 0–1），甚至负数
正确预处理步骤：
- 用
cv::cvtColor(img, gray, cv::COLOR_BGR2GRAY)转灰度 - 用
gray.convertScaleAbs(gray, gray, 1.0/255.0)归一化到 [0,1]，再转CV_32F：gray.convertScaleAbs(gray_f32, 1.0, 0.0)不行，要用gray.convertScaleAbs(gray_f32, 1.0/255.0)或更稳妥的gray.convertScaleAbs(gray_f32, 1.0); gray_f32 /= 255.0; - 务必用
CV_32F，CV_64F虽支持但无必要且慢
手动实现 SSIM 更可控，三四十行就能跑通
标准 SSIM 公式含均值、方差、协方差三部分，OpenCV 完全能胜任——不需要第三方库，也不依赖 contrib 编译状态。核心是用 cv::boxFilter 做局部均值（代替高斯，更快），再按公式组合。
关键参数与陷阱：
- 窗口大小建议用 11×11（论文默认），但必须是奇数；
cv::boxFilter的ksize设为cv::Size(11,11)，anchor设为cv::Point(-1,-1) -
C1和C2是稳定常数（避免除零），通常取C1 = (0.01 * L)^2，C2 = (0.03 * L)^2，其中L=1.0（归一化后）→ 即C1 = 1e-4,C2 = 9e-4 - 不要对整图直接算均值——SSIM 是局部窗口滑动计算，最后对所有窗口结果取平均（
cv::mean()） - 注意数据类型：中间
mu1_sq、mu2_sq、mu1_mu2等需用CV_32F，否则溢出
简短示意（核心片段）：
cv::Mat mu1, mu2, mu1_sq, mu2_sq, mu1_mu2; cv::boxFilter(img1, mu1, CV_32F, cv::Size(11,11), cv::Point(-1,-1), false, cv::BORDER_DEFAULT); cv::boxFilter(img2, mu2, CV_32F, cv::Size(11,11), cv::Point(-1,-1), false, cv::BORDER_DEFAULT); mu1_sq = mu1.mul(mu1); mu2_sq = mu2.mul(mu2); mu1_mu2 = mu1.mul(mu2); <p>cv::Mat sigma1_sq, sigma2_sq, sigma12; cv::boxFilter(img1.mul(img1), sigma1_sq, CV_32F, cv::Size(11,11), cv::Point(-1,-1), false, cv::BORDER_DEFAULT); sigma1_sq -= mu1_sq; cv::boxFilter(img2.mul(img2), sigma2_sq, CV_32F, cv::Size(11,11), cv::Point(-1,-1), false, cv::BORDER_DEFAULT); sigma2_sq -= mu2_sq; cv::boxFilter(img1.mul(img2), sigma12, CV_32F, cv::Size(11,11), cv::Point(-1,-1), false, cv::BORDER_DEFAULT); sigma12 -= mu1_mu2;</p><p>const float C1 = 1e-4f, C2 = 9e-4f; cv::Mat ssim_map = ((2<em>mu1_mu2 + C1).mul(2</em>sigma12 + C2)) / ((mu1_sq + mu2_sq + C1).mul(sigma1_sq + sigma2_sq + C2)); double ssim_val = cv::mean(ssim_map)[0];</p>
SSIM 值异常低？先检查图像对齐和内容差异
SSIM 对几何形变极度敏感——哪怕平移 1 像素、轻微旋转或缩放，值就会骤降到 0.3 以下。它不是为配准设计的，而是衡量“已对齐图像”的结构保真度。
使用场景判断：
- 做超分/去噪效果评估？确保 GT 和输出图严格同尺寸、同坐标系（用
cv::resize或cv::warpAffine对齐后再算） - 比较不同压缩质量？用同一张原图生成 JPEG/QP，再比 SSIM —— 这是合理场景
- 想对比两张不同拍摄角度的图？SSIM 完全不适用，换用特征匹配或 LPIPS
- 图像有大面积纯黑/纯白区域？局部均值会失真，考虑加
cv::BORDER_REFLECT或裁掉边缘 5 像素再算
最容易被忽略的一点：SSIM 是逐通道计算的。彩色图必须转灰度再算，或者分别算三个通道再平均——但 RGB 通道权重不同，简单平均会偏色。工业检测中更倾向用 YUV 的 Y 通道，即先 cv::cvtColor(img, yuv, cv::COLOR_BGR2YUV); cv::extractChannel(yuv, y_channel, 0);。
