pHash感知哈希DCT图像哈希源码逐行解读从算法原理到编译验证的完整指南【免费下载链接】pHashpHash - the open source perceptual hash library项目地址: https://gitcode.com/gh_mirrors/pha/pHashpHash 是一款开源的 C 感知哈希库perceptual hash library专为图像、视频、音频和文本计算感知指纹。本文带你逐行解读其 DCT 图像哈希核心函数ph_dct_imagehash的源码——从灰度化、32×32 缩放、二维 DCT 变换到 8×8 中位数比特编码彻底搞懂相似的图片为什么会算出接近的 64 位哈希值并附编译验证步骤帮助新手一次性掌握相似图片检测的实现原理。一、什么是感知哈希它和 MD5 有 3 个关键区别如果你做过文件去重一定熟悉 MD5改一个字节摘要就面目全非。但图片去重不能这么干——同一张照片换个尺寸、重新压一次 JPEG像素值就变了MD5 自然全变。感知哈希解决的就是这个问题它提取的是图像的视觉骨架而不是像素的精确值。对比维度加密哈希MD5 / SHA感知哈希pHash微小改动结果完全剧变结果基本不变仅个别比特不同典型用途完整性校验、数字签名重复图片检测、以图搜图、版权比对结果比较严格相等算汉明距离距离小即相似pHash 库内置了 6 种哈希算法覆盖图像、视频、音频和文本其中 DCT 图像哈希是应用最广的一个。二、pHash 项目速览6 种哈希算法一张表API 函数处理对象输出抗扰动能力ph_dct_imagehash图像DCT64 位整数缩放、压缩、轻微明暗变化ph_image_digest图像Radon DCTRadish40 字节摘要旋转、缩放ph_mh_imagehash图像Marr-Hildreth 小波576 位缩放、轻微裁剪、JPEG 噪声ph_dct_videohash视频关键帧 DCT64 位哈希数组重新编码、帧率变化ph_audiohash音频Bark 频谱32 位帧哈希数组重新编码、轻微均衡ph_texthash文本k-gram 赢窗指纹点数组插入、删除、改写完整 API 声明见 src/pHash.h.cmake其中 DCT 图像哈希的入口声明在 src/pHash.h.cmakeint ph_dct_imagehash(const char* file, ulong64 hash);一个字符串路径进一个 64 位整数出接口简单得让人怀疑——接下来就拆开看它内部做了什么。三、DCT 图像哈希5 步流水线总览整个算法可以概括为一条流水线读图 转灰度只保留亮度通道丢弃颜色7×7 均值滤波抹平 JPEG 噪声缩放至 32×32统一观察尺度二维 DCT 变换从空间域进入频率域取左上角 8×8 低频块 → 生成 64 位哈希下面对照源码 src/pHash.cpp 逐步拆解。四、源码逐行解读ph_dct_imagehash4.1 读图与通道处理为什么先转成灰度CImguint8_t src; if (load_image(file, src) 0) return -1; CImgfloat meanfilter(7, 7, 1, 1, 1); // 全 1 的 7×7 均值矩阵 CImgfloat img; if (src.spectrum() 3) { img src.RGBtoYCbCr().channel(0).get_convolve(meanfilter); } else if (src.spectrum() 4) { // RGBA先裁掉 alpha 通道再走同样流程L437-L443 ... } else { img src.channel(0).get_convolve(meanfilter); }几个细节值得注意统一入口load_imagesrc/pHash.cpp负责读 PNG / JPEG / TIFF由内置的 third-party/CImg/CImg.h 完成开启HAVE_HEIF编译开关后HEIF / HEIC / AVIF 会改走 libheif 解码RGB 先转 YCbCr 再取Y亮度通道——人眼对亮度敏感、对颜色不敏感这正是感知二字的来源RGBA 图像必须先裁掉 alpha 通道否则RGBtoYCbCr会抛异常这是代码注释里提到的 issue #39 的修复4.2 7×7 均值滤波先把噪声磨掉CImgfloat meanfilter(7, 7, 1, 1, 1); img ...get_convolve(meanfilter); // 每个像素与 48 个邻居求平均JPEG 压缩、轻微锐化会在像素层面引入高频噪声。卷积一次 7×7 均值核后这些细碎扰动被平滑掉留下的都是大块结构——为后面的频率分析扫清障碍。4.3 缩放到 32×32统一观察尺度img.resize(32, 32);不管原图是 100×100 还是 4000×4000都统一压成 32×32。这一步让哈希对缩放扰动天然免疫两张图只要内容相同缩到 32×32 后几乎一样。选 32 而非 64 也有讲究——它是 2 的幂、对 DCT 友好且左上角 1/4 区域正好是 8×8够描述形状细节又少到不会干扰判断。4.4 二维 DCT 变换用两次矩阵乘法完成DCT 基矩阵在ph_dct_matrix中构造src/pHash.cppCImgfloat matrix(N, N, 1, 1, 1 / sqrt((float)N)); // 第 0 行 1/√N const float c1 sqrt(2.0 / N); matrix(x, y) c1 * cos((cimg::PI / 2 / N) * y * (2 * x 1));get_dct_matrixsrc/pHash.cpp用函数内 static只构建一次 32×32 的矩阵C11 保证线程安全避免每次哈希都重建。真正的变换只有一行三明治矩阵乘法const CImgfloat C get_dct_matrix(); CImgfloat Ctransp C.get_transpose(); CImgfloat dctImage C * img * Ctransp; // C · img · Cᵀ一次二维 DCT 被拆成乘基矩阵 × 乘其转置代码直观且高效。变换后图像的能量集中到左上角低频区左上角是整体轮廓低频右下角是纹理细节高频。4.5 核心 5 行8×8 低频块 → 64 位哈希CImgfloat subsec dctImage.crop(0, 0, 7, 7).unroll(x); // 左上 8×8 拍平成 64 个系数 CImgfloat ac subsec.get_crop(1, 0, 0, 0, 63, 0, 0, 0); // 排除 DC取 63 个 AC 系数 float median ac.median(); // 算中位数 hash 0; for (int i 0; i 64; i) { if (subsec(i) median) hash | 0x01; // 大于中位数 → 记 1否则记 0 if (i 63) hash 1; }源码注释src/pHash.cpp里藏着两个踩坑修复非常值得学习必须取 (0,0)–(7,7) 的规范 8×8 块。早期版本取的是 (1,1)–(8,8)跳过了最低频的一行一列导致与所有其他自称 pHash 的库互不兼容已修正为规范实现中位数要排除 DC 系数 (0,0)。DC 表示图像整体亮度幅值通常是 AC 系数的 10–100 倍若计入中位数它对应的哈希位几乎恒为 1白白浪费 64 位中的 1 位。至此一张图片就凝结成了 64 个比特每一位只回答一个问题——这个低频系数比中位数高吗五、为什么左上角 8×8 能以貌识图把 DCT 结果想象成一张频率地图左上角低频天空是蓝的、山在中间、地平线在下——图像的骨架右下角高频树叶的锯齿、皮肤毛孔——细节纹理缩放、轻微压缩、亮度微调主要摧毁高频细节低频骨架几乎无损。而 64 位哈希只编码低频的相对大小关系比中位数高/低不编码绝对数值所以抗扰动能力极强。这就是感知哈希区别于 MD5 的本质丢掉的恰恰是不重要的东西。六、两张图相似吗汉明距离速查算完哈希比较只需一个函数src/pHash.cppint ph_hamming_distance(const ulong64 h1, const ulong64 h2) { ulong64 x h1 ^ h2; return __builtin_popcountll(x); // 异或后统计 1 的个数 不同位数 }按项目 README 给出的经验值汉明距离判断0几乎完全相同≤ 10非常相似同一张图的缩放 / 压缩版本10 ~ 20边界区域建议用自己的数据集标定阈值≥ 20基本不相关⚡ 实际项目中建议拿自己业务的图片各测一遍再确定阈值——不同场景证件照 vs 风景照的合理分界线并不相同。七、动手验证3 步编译并跑通 DCT 感知哈希示例git clone https://gitcode.com/gh_mirrors/pha/pHash cd pHash mkdir build cd build cmake -DPHASH_EXAMPLESON .. make -j准备两个目录dir_original原图和dir_blurred同文件名的模糊/压缩版运行./Release/TestDCT dir_original dir_blurred示例程序 examples/test_imagephash.cpp 会分两组输出intra distance同名的两个版本互比——距离应该很小≤10 为佳inter distance不同图片互比——距离应该很大≥20 为佳两组结果一比较你就直观看到了感知哈希抗扰动、分得开的全部价值。图像哈希依赖 libpng / libjpeg / libtiff视频、音频哈希可分别用-DWITH_VIDEO_HASHON、-DWITH_AUDIO_HASHON单独开启。八、新手常见问题 FAQQ1为什么输出恰好是 64 位因为取的是 8×8 64 个低频 DCT 系数每个系数变 1 比特。Q2为什么缩放成 32×32 而不是 64×6432 是 2 的幂对 DCT 友好左上 1/4 区域8×8足以刻画形状图越小无关细节越少。Q3JPEG 重压缩、调亮度后哈希会变吗只会有少数比特变化这就是设计目标。若还要求抗旋转请换用 Radon 变换的ph_image_digest循环互相关天然对旋转不敏感。Q4支持哪些图片格式默认 PNG / JPEG / TIFFHEIF / HEIC / AVIF 需编译时开启-DWITH_HEIFON见 src/pHash.cpp 的分流逻辑。Q5能用于版权检测吗能。重复图片检测、内容 ID、以图搜图正是感知哈希的典型应用场景配合索引库可支撑大规模比对。九、核心文件导航模块路径DCT 图像哈希主实现src/pHash.cppDCT 基矩阵构造src/pHash.cpp汉明距离src/pHash.cpp视频哈希复用同一套 DCT 比特逻辑src/pHash.cpp公共 API 声明src/pHash.h.cmake内置图像处理引擎 CImgthird-party/CImg/CImg.hDCT 示例程序TestDCTexamples/test_imagephash.cpp多语言绑定Java / C# / PHPbindings/项目总览与算法说明README.md写在最后从 400 多行库里最关键的 50 行源码中我们看到了一个精巧的设计闭环灰度化保住人眼视角均值滤波去噪32×32 统一尺度DCT 抽低频骨架中位数比较抹掉绝对值。五步走完一张图片就浓缩成一个 64 位指纹配合汉明距离即可在毫秒级完成相似判断。理解了ph_dct_imagehash这一条主线再去读 Radish、Marr-Hildreth 甚至视频、音频哈希都是水到渠成的事。【免费下载链接】pHashpHash - the open source perceptual hash library项目地址: https://gitcode.com/gh_mirrors/pha/pHash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
pHash感知哈希DCT图像哈希源码逐行解读从算法原理到编译验证的完整指南【免费下载链接】pHashpHash - the open source perceptual hash library项目地址: https://gitcode.com/gh_mirrors/pha/pHashpHash 是一款开源的 C 感知哈希库perceptual hash library专为图像、视频、音频和文本计算感知指纹。本文带你逐行解读其 DCT 图像哈希核心函数ph_dct_imagehash的源码——从灰度化、32×32 缩放、二维 DCT 变换到 8×8 中位数比特编码彻底搞懂相似的图片为什么会算出接近的 64 位哈希值并附编译验证步骤帮助新手一次性掌握相似图片检测的实现原理。一、什么是感知哈希它和 MD5 有 3 个关键区别如果你做过文件去重一定熟悉 MD5改一个字节摘要就面目全非。但图片去重不能这么干——同一张照片换个尺寸、重新压一次 JPEG像素值就变了MD5 自然全变。感知哈希解决的就是这个问题它提取的是图像的视觉骨架而不是像素的精确值。对比维度加密哈希MD5 / SHA感知哈希pHash微小改动结果完全剧变结果基本不变仅个别比特不同典型用途完整性校验、数字签名重复图片检测、以图搜图、版权比对结果比较严格相等算汉明距离距离小即相似pHash 库内置了 6 种哈希算法覆盖图像、视频、音频和文本其中 DCT 图像哈希是应用最广的一个。二、pHash 项目速览6 种哈希算法一张表API 函数处理对象输出抗扰动能力ph_dct_imagehash图像DCT64 位整数缩放、压缩、轻微明暗变化ph_image_digest图像Radon DCTRadish40 字节摘要旋转、缩放ph_mh_imagehash图像Marr-Hildreth 小波576 位缩放、轻微裁剪、JPEG 噪声ph_dct_videohash视频关键帧 DCT64 位哈希数组重新编码、帧率变化ph_audiohash音频Bark 频谱32 位帧哈希数组重新编码、轻微均衡ph_texthash文本k-gram 赢窗指纹点数组插入、删除、改写完整 API 声明见 src/pHash.h.cmake其中 DCT 图像哈希的入口声明在 src/pHash.h.cmakeint ph_dct_imagehash(const char* file, ulong64 hash);一个字符串路径进一个 64 位整数出接口简单得让人怀疑——接下来就拆开看它内部做了什么。三、DCT 图像哈希5 步流水线总览整个算法可以概括为一条流水线读图 转灰度只保留亮度通道丢弃颜色7×7 均值滤波抹平 JPEG 噪声缩放至 32×32统一观察尺度二维 DCT 变换从空间域进入频率域取左上角 8×8 低频块 → 生成 64 位哈希下面对照源码 src/pHash.cpp 逐步拆解。四、源码逐行解读ph_dct_imagehash4.1 读图与通道处理为什么先转成灰度CImguint8_t src; if (load_image(file, src) 0) return -1; CImgfloat meanfilter(7, 7, 1, 1, 1); // 全 1 的 7×7 均值矩阵 CImgfloat img; if (src.spectrum() 3) { img src.RGBtoYCbCr().channel(0).get_convolve(meanfilter); } else if (src.spectrum() 4) { // RGBA先裁掉 alpha 通道再走同样流程L437-L443 ... } else { img src.channel(0).get_convolve(meanfilter); }几个细节值得注意统一入口load_imagesrc/pHash.cpp负责读 PNG / JPEG / TIFF由内置的 third-party/CImg/CImg.h 完成开启HAVE_HEIF编译开关后HEIF / HEIC / AVIF 会改走 libheif 解码RGB 先转 YCbCr 再取Y亮度通道——人眼对亮度敏感、对颜色不敏感这正是感知二字的来源RGBA 图像必须先裁掉 alpha 通道否则RGBtoYCbCr会抛异常这是代码注释里提到的 issue #39 的修复4.2 7×7 均值滤波先把噪声磨掉CImgfloat meanfilter(7, 7, 1, 1, 1); img ...get_convolve(meanfilter); // 每个像素与 48 个邻居求平均JPEG 压缩、轻微锐化会在像素层面引入高频噪声。卷积一次 7×7 均值核后这些细碎扰动被平滑掉留下的都是大块结构——为后面的频率分析扫清障碍。4.3 缩放到 32×32统一观察尺度img.resize(32, 32);不管原图是 100×100 还是 4000×4000都统一压成 32×32。这一步让哈希对缩放扰动天然免疫两张图只要内容相同缩到 32×32 后几乎一样。选 32 而非 64 也有讲究——它是 2 的幂、对 DCT 友好且左上角 1/4 区域正好是 8×8够描述形状细节又少到不会干扰判断。4.4 二维 DCT 变换用两次矩阵乘法完成DCT 基矩阵在ph_dct_matrix中构造src/pHash.cppCImgfloat matrix(N, N, 1, 1, 1 / sqrt((float)N)); // 第 0 行 1/√N const float c1 sqrt(2.0 / N); matrix(x, y) c1 * cos((cimg::PI / 2 / N) * y * (2 * x 1));get_dct_matrixsrc/pHash.cpp用函数内 static只构建一次 32×32 的矩阵C11 保证线程安全避免每次哈希都重建。真正的变换只有一行三明治矩阵乘法const CImgfloat C get_dct_matrix(); CImgfloat Ctransp C.get_transpose(); CImgfloat dctImage C * img * Ctransp; // C · img · Cᵀ一次二维 DCT 被拆成乘基矩阵 × 乘其转置代码直观且高效。变换后图像的能量集中到左上角低频区左上角是整体轮廓低频右下角是纹理细节高频。4.5 核心 5 行8×8 低频块 → 64 位哈希CImgfloat subsec dctImage.crop(0, 0, 7, 7).unroll(x); // 左上 8×8 拍平成 64 个系数 CImgfloat ac subsec.get_crop(1, 0, 0, 0, 63, 0, 0, 0); // 排除 DC取 63 个 AC 系数 float median ac.median(); // 算中位数 hash 0; for (int i 0; i 64; i) { if (subsec(i) median) hash | 0x01; // 大于中位数 → 记 1否则记 0 if (i 63) hash 1; }源码注释src/pHash.cpp里藏着两个踩坑修复非常值得学习必须取 (0,0)–(7,7) 的规范 8×8 块。早期版本取的是 (1,1)–(8,8)跳过了最低频的一行一列导致与所有其他自称 pHash 的库互不兼容已修正为规范实现中位数要排除 DC 系数 (0,0)。DC 表示图像整体亮度幅值通常是 AC 系数的 10–100 倍若计入中位数它对应的哈希位几乎恒为 1白白浪费 64 位中的 1 位。至此一张图片就凝结成了 64 个比特每一位只回答一个问题——这个低频系数比中位数高吗五、为什么左上角 8×8 能以貌识图把 DCT 结果想象成一张频率地图左上角低频天空是蓝的、山在中间、地平线在下——图像的骨架右下角高频树叶的锯齿、皮肤毛孔——细节纹理缩放、轻微压缩、亮度微调主要摧毁高频细节低频骨架几乎无损。而 64 位哈希只编码低频的相对大小关系比中位数高/低不编码绝对数值所以抗扰动能力极强。这就是感知哈希区别于 MD5 的本质丢掉的恰恰是不重要的东西。六、两张图相似吗汉明距离速查算完哈希比较只需一个函数src/pHash.cppint ph_hamming_distance(const ulong64 h1, const ulong64 h2) { ulong64 x h1 ^ h2; return __builtin_popcountll(x); // 异或后统计 1 的个数 不同位数 }按项目 README 给出的经验值汉明距离判断0几乎完全相同≤ 10非常相似同一张图的缩放 / 压缩版本10 ~ 20边界区域建议用自己的数据集标定阈值≥ 20基本不相关⚡ 实际项目中建议拿自己业务的图片各测一遍再确定阈值——不同场景证件照 vs 风景照的合理分界线并不相同。七、动手验证3 步编译并跑通 DCT 感知哈希示例git clone https://gitcode.com/gh_mirrors/pha/pHash cd pHash mkdir build cd build cmake -DPHASH_EXAMPLESON .. make -j准备两个目录dir_original原图和dir_blurred同文件名的模糊/压缩版运行./Release/TestDCT dir_original dir_blurred示例程序 examples/test_imagephash.cpp 会分两组输出intra distance同名的两个版本互比——距离应该很小≤10 为佳inter distance不同图片互比——距离应该很大≥20 为佳两组结果一比较你就直观看到了感知哈希抗扰动、分得开的全部价值。图像哈希依赖 libpng / libjpeg / libtiff视频、音频哈希可分别用-DWITH_VIDEO_HASHON、-DWITH_AUDIO_HASHON单独开启。八、新手常见问题 FAQQ1为什么输出恰好是 64 位因为取的是 8×8 64 个低频 DCT 系数每个系数变 1 比特。Q2为什么缩放成 32×32 而不是 64×6432 是 2 的幂对 DCT 友好左上 1/4 区域8×8足以刻画形状图越小无关细节越少。Q3JPEG 重压缩、调亮度后哈希会变吗只会有少数比特变化这就是设计目标。若还要求抗旋转请换用 Radon 变换的ph_image_digest循环互相关天然对旋转不敏感。Q4支持哪些图片格式默认 PNG / JPEG / TIFFHEIF / HEIC / AVIF 需编译时开启-DWITH_HEIFON见 src/pHash.cpp 的分流逻辑。Q5能用于版权检测吗能。重复图片检测、内容 ID、以图搜图正是感知哈希的典型应用场景配合索引库可支撑大规模比对。九、核心文件导航模块路径DCT 图像哈希主实现src/pHash.cppDCT 基矩阵构造src/pHash.cpp汉明距离src/pHash.cpp视频哈希复用同一套 DCT 比特逻辑src/pHash.cpp公共 API 声明src/pHash.h.cmake内置图像处理引擎 CImgthird-party/CImg/CImg.hDCT 示例程序TestDCTexamples/test_imagephash.cpp多语言绑定Java / C# / PHPbindings/项目总览与算法说明README.md写在最后从 400 多行库里最关键的 50 行源码中我们看到了一个精巧的设计闭环灰度化保住人眼视角均值滤波去噪32×32 统一尺度DCT 抽低频骨架中位数比较抹掉绝对值。五步走完一张图片就浓缩成一个 64 位指纹配合汉明距离即可在毫秒级完成相似判断。理解了ph_dct_imagehash这一条主线再去读 Radish、Marr-Hildreth 甚至视频、音频哈希都是水到渠成的事。【免费下载链接】pHashpHash - the open source perceptual hash library项目地址: https://gitcode.com/gh_mirrors/pha/pHash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
