OpenCV.js 直方图反投影（Histogram Backprojection）实战：用 cv.calcBackProject 按颜色定位目标

本文讲解 OpenCV.js 中直方图反投影（Histogram Backprojection）的原理与 API 用法：先理解它如何用一张"概率图"表示目标在画面中每个像素的归属置信度，再掌握 cv.calcHist、cv.normalize、cv.calcBackProject 三个函数的完整调用链，最后结合仓库中可交互的 JS 示例（默认以 handSrc.jpg / handDst.jpg 两张手部图片演示）逐步实现按颜色搜索目标图像，并延伸到 CamShift 跟踪中的实际应用。读完本文，你可以直接在自己的 Web 项目里实现"按颜色概率定位目标"的图像处理流程。

1. 什么是直方图反投影

直方图反投影由 Michael J. Swain 和 Dana H. Ballard 在其论文 Indexing via color histograms 中提出。用通俗的话说，它用于图像分割，或在图像中查找感兴趣的目标。具体来说，它会生成一张与输入图像同尺寸、但只有单通道的输出图，图中每个像素的灰度值对应该像素属于目标物体的概率。直观的结果就是：目标物体在输出图中更"白"，其余背景区域更"暗"。直方图反投影也是 CamShift 等颜色目标跟踪算法的核心组成部分。

2. 工作流程：先建"颜色指纹"，再对新图反投影

完整的操作分三步：

1. 建立参考直方图：选取一张"目标占满画面"的图像（原始教程以草地为例：只含草地、排除球员等干扰物，目标尽量填满图像以获得更好效果）。优先使用颜色直方图（如 HSV 色相通道）而非灰度直方图，因为颜色比灰度强度更能刻画物体特征。
2. 反投影：用这张直方图对"待搜索的测试图像"做反投影，即计算测试图中每个像素属于目标（草地）的概率并显示出来。
3. 阈值化：对反投影结果做适当的阈值处理，就能单独分离出目标（草地）本身。

3. 核心 API 一：cv.calcBackProject

OpenCV.js 通过 cv.calcBackProject 实现反投影，其 C++ 原型定义见 imgproc.hpp。函数签名与参数如下：

cv.calcBackProject( images, channels, hist, dst, ranges, scale );

参数	说明
images	源图像数组（MatVector）。所有图像必须具有相同深度（CV_8U、CV_16U 或 CV_32F）和相同尺寸，通道数可任意
channels	用于计算反投影的通道列表，其长度必须与直方图的维数一致（例如一维直方图对应 [0]）
hist	输入直方图，可以是稠密或稀疏直方图
dst	输出反投影结果，单通道数组，尺寸与 images[0] 相同
ranges	各维度直方图 bin 边界组成的数组（与 cv.calcHist 中的 ranges 相同）
scale	可选输出缩放系数

从 C++ 文档注释可以看到其算法本质（见 imgproc.hpp）：与 calcHist 类似，函数在每个位置 (x, y) 从选定通道收集数值并找到对应的直方图 bin——但不同的是它不再累加计数，而是读出 bin 的值、乘以 scale，再存入 backProject(x,y)。从统计角度看，它在计算每个像素取值相对于该直方图所表示的经验概率分布的概率。头文件注释还给出了一个典型用法：跟踪前让物体几乎占满画面并计算色相直方图；跟踪时对每一帧的色相平面做反投影，再阈值化抑制弱颜色、过滤低饱和度与过暗/过亮像素，最后取最大连通域——这正是一个近似版 CamShift 颜色目标跟踪算法的流程。

注意 ranges 必须与建立直方图时完全一致：反投影时像素值会按 ranges 映射回 bin，两边边界不匹配会导致概率图整体错位。

4. 核心 API 二：cv.normalize

反投影前通常需要把直方图归一化到 0–255，便于可视化或作为后续阈值化的输入：

cv.normalize( src, dst, alpha = 1, beta = 0, norm_type = cv.NORM_L2, dtype = -1, mask = new cv.Mat() );

参数	说明
src	输入数组
dst	输出数组，与 src 同尺寸
alpha	归一化到的范数值；范围归一化时为下限
beta	范围归一化时的上限；范数归一化时不使用
norm_type	归一化类型（见 cv.NormTypes，如 cv.NORM_MINMAX、cv.NORM_L2）
dtype	为负时输出与 src 同类型；否则输出通道数与 src 相同、深度为 CV_MAT_DEPTH(dtype)
mask	可选操作掩膜

5. 完整 JS 示例：给两张图做颜色反投影

仓库中的可交互示例 js_histogram_backprojection_calcBackProject.html 提供了可直接修改运行的完整代码，默认加载 handSrc.jpg 作为"目标参考图"、handDst.jpg 作为"待搜索图"（两张图均为 640×480 的手部图像，见 handSrc.jpg 与 handDst.jpg）。示例代码完整流程如下：

let src = cv.imread('srcCanvasInput');   // 参考图（目标占满画面）
let dst = cv.imread('dstCanvasInput');  // 待搜索的测试图
cv.cvtColor(src, src, cv.COLOR_RGB2HSV, 0);   // 转到 HSV 色彩空间
cv.cvtColor(dst, dst, cv.COLOR_RGB2HSV, 0);

let srcVec = new cv.MatVector();
let dstVec = new cv.MatVector();
srcVec.push_back(src); dstVec.push_back(dst);

let backproj = new cv.Mat();
let none = new cv.Mat();
let mask = new cv.Mat();
let hist = new cv.Mat();

let channels = [0];        // 只统计第 0 通道（HSV 的 H，色相）
let histSize = [50];       // 一维直方图，50 个 bin
let ranges = [0, 180];     // 色相范围 0–180（OpenCV 8 位 H 通道取值范围）
let accumulate = false;

// 1) 在参考图上计算色相直方图
cv.calcHist(srcVec, channels, mask, hist, histSize, ranges, accumulate);
// 2) 归一化到 0–255，便于直观显示概率强弱
cv.normalize(hist, hist, 0, 255, cv.NORM_MINMAX, -1, none);
// 3) 对测试图反投影：逐像素查 bin，写出"属于该颜色的概率"
cv.calcBackProject(dstVec, channels, hist, backproj, ranges, 1);
cv.imshow('canvasOutput', backproj);

src.delete(); dst.delete(); srcVec.delete(); dstVec.delete();
backproj.delete(); mask.delete(); hist.delete(); none.delete();

要点解读：

• 色彩空间选择：先 COLOR_RGB2HSV 再取通道 0（H），正是教程中"优先颜色直方图、用色相刻画物体"建议的落地——肤色/草地等目标的色相集中，抗亮度变化能力强于灰度统计。
• histSize 与 ranges：[50] 表示把 0–180 的色相空间切成 50 个 bin。bin 越多分辨率越高但噪声越大，且必须与 calcBackProject 传入的 ranges 保持一致。
• scale 参数：示例传 1 即原样输出 bin 值；如需放大概率对比度可增大该值。
• 内存管理：OpenCV.js 的 Mat/MatVector 需手动 delete()，示例末尾的清理调用是 Web 端避免内存泄漏的规范做法。
• 该示例页面还提供文件上传控件，可以换成任意两张图片重新运行，方便自行验证"目标越占满参考图、效果越好"的结论。

6. 源码层面的印证

• C++ 实现位于 histogram.cpp，calcBackProject 对每个像素执行"按 ranges 定位 bin → 读取 bin 值 → 乘以 scale 写出"的过程，与上文 API 语义完全一致。
• cv.calcBackProject 被列入 OpenCV.js 的函数白名单（见 gen_dict.json），确认当前仓库的 Web 构建可用。
• 更完整的跟踪侧应用可见 CamShift 示例 samples/python/snippets/camshift.py：它正是先对选区计算色相直方图，再逐帧 calcBackProject 得到概率图，然后做 mean-shift 更新搜索窗口——印证了教程"反投影 + 阈值 + 连通域 ≈ 近似 CamShift"的表述。
• 参数调节的交互版本可参考 calcBackProject_Demo1.py，其中用滑动条实时改变 histSize（bin 数），并展示"色相直方图绘制 + 反投影结果显示"的完整流程，核心参数同样为 ranges = [0, 180]、按 NORM_MINMAX 归一化到 0–255。

7. 实践建议与关联学习

• 参考图质量：目标物体尽量占满参考画面，且尽量排除背景颜色与目标相近的成分，这是概率图信噪比的最大影响因素。
• 通道与维数匹配：channels 的长度必须等于直方图维数——一维 H 直方图配 [0]，若要联合 H+S 做二维直方图则配 [0, 1] 且 histSize 变为二维。
• 后续处理：对 backproj 做 cv.threshold 抑制弱响应，再 cv.connectedComponents 取最大连通域，即可获得稳健的目标区域。
• 想进一步把反投影接进跟踪流程，可继续学习本教程库的 Mean Shift 章节，其配套的 js_meanshift.html 演示了基于 mean-shift 的实时视频跟踪。

小结：直方图反投影把"目标长什么样"浓缩成一张直方图，再逐像素查表输出概率图，是颜色目标分割与 CamShift 跟踪的基础算子。在 OpenCV.js 中，calcHist → normalize → calcBackProject 三个函数即可在浏览器内完整实现该流程，且仓库自带可交互示例与参考图像，便于快速上手与调参验证。