OpencvSharp 算子学习教案之 - Cv2.Accumulate

OpencvSharp 算子学习教案之 - Cv2.Accumulate

大家好，Opencv在很多工程项目中都会用到，而OpencvSharp则是以C#开发与实现的Opencv操作库，对.NET开发人员友好，但很多API的中文资料、应用场景及常见坑点等缺乏系统性归纳，因此这系列博客将给大家带来Cv2及Mat对象全系列算子学习教案，供大家参考学习。

Cv2.Accumulate

• 教案版本：V1.0
• 面向对象：OpenCvSharp 初学者
• 所属模块：imgproc
• 源码位置：OpenCvSharp/Cv2/Cv2_imgproc.cs:1542

摘要：Cv2.Accumulate 会把源图像逐像素加到累加器里，常用于背景统计、多帧求和和连续帧分析。本文先解释 mask 和浮点累加器的作用，再用一个 5x5 小矩阵演示多帧累加的具体过程。

1. 函数名称（带参数签名）

publicstaticvoidAccumulate(InputArraysrc,InputOutputArraydst,InputArraymask)

2. 函数用途

Cv2.Accumulate的作用，是把输入图像的像素值加到已有累加器上。

它最常见的用途有：

1. 累积背景统计量。
2. 把多帧图像加成一张总和图。
3. 作为后续平均、方差或前景分析的基础步骤。

这类操作最重要的一点是：dst不能用 8 位图像保存，因为累加多次后数值会越来越大，因此通常要使用 32F 或 64F。

3. 函数公式

设源图像为s r c srcsrc，累加器为d s t dstdst，掩码为m a s k maskmask，则更新规则为：

d s t ( x , y ) ← d s t ( x , y ) + s r c ( x , y ) if m a s k ( x , y ) ≠ 0 dst(x,y) \leftarrow dst(x,y) + src(x,y) \quad \text{if } mask(x,y) \neq 0dst(x,y)←dst(x,y)+src(x,y)ifmask(x,y)=0

如果mask(x,y)=0，那么该位置不会参与累加。

4. 函数原理说明

1. 先准备一个浮点累加器dst。
2. 每来一帧，就把该帧的像素加进去。
3. 如果提供了 mask，就只在 mask 非零的区域更新。
4. 累加完成后，可以继续做平均、统计或背景建模。

初学者最容易混淆的是：

1. 以为dst可以直接是 8 位图像。
2. 以为mask是可有可无的装饰参数。
3. 不清楚Accumulate是逐像素加法，而不是平均值。
4. 忘记多次累加后数值会迅速变大。

5. 参数含义解析

补充说明：

1. src支持 8 位或浮点图像。
2. dst通常要用 32F 或 64F。
3. mask为 0 的位置不会更新。

6. 应用场景列表

7. 函数使用示例

下面的 Console 程序会构造两帧小型灰度矩阵，并把它们累加到同一个 32F 累加器里。为了方便观察，只让中心 3x3 区域参与累加。

usingSystem;usingSystem.Text;usingOpenCvSharp;internalstaticclassProgram{/// <summary>/// 程序入口。/// </summary>privatestaticvoidMain(){// 让控制台支持中文输出，便于阅读教学说明。Console.OutputEncoding=Encoding.UTF8;// 构造两帧 5x5 灰度图，第二帧在第一帧基础上整体增加 10，方便观察累加结果。usingvarsrc1=CreateDemoImage(0);usingvarsrc2=CreateDemoImage(10);// 准备一个中心掩码，只让中间 3x3 区域参与累加。usingvarmask=CreateCenterMask(newSize(5,5));// 累加器必须使用浮点类型，因为它需要保存多帧相加后的结果。usingvardst=newMat(5,5,MatType.CV_32FC1,Scalar.All(0));// 依次把两帧图像加到累加器里。Cv2.Accumulate(src1,dst,mask);Cv2.Accumulate(src2,dst,mask);// 打印每一步的矩阵，方便初学者手算核对。Console.WriteLine("src1 =");PrintMatrix(src1);Console.WriteLine("src2 =");PrintMatrix(src2);Console.WriteLine("mask =");PrintMatrix(mask);Console.WriteLine("dst =");PrintMatrix(dst);}/// <summary>/// 创建 5x5 的教学矩阵，数值从 1 开始递增。/// </summary>/// <param name="offset">所有像素统一增加的偏移量。</param>/// <returns>单通道灰度图。</returns>privatestaticMatCreateDemoImage(intoffset){// 使用单通道 8 位矩阵，便于看到每个像素值的变化。varimage=newMat(5,5,MatType.CV_8UC1);for(varrow=0;row<image.Rows;row++){for(varcol=0;col<image.Cols;col++){// 这里用简单的递增序列，让读者可以快速手算每个位置的值。image.Set(row,col,(byte)(row*image.Cols+col+1+offset));}}returnimage;}/// <summary>/// 创建一个中心 3x3 的掩码。/// </summary>/// <param name="size">掩码尺寸。</param>/// <returns>单通道 8 位掩码。</returns>privatestaticMatCreateCenterMask(Sizesize){// 先创建全 0 掩码，再把中心区域填成 255。varmask=newMat(size.Height,size.Width,MatType.CV_8UC1,Scalar.All(0));Cv2.Rectangle(mask,newRect(1,1,3,3),Scalar.All(255),-1);returnmask;}/// <summary>/// 打印单通道矩阵。/// </summary>/// <param name="matrix">待打印矩阵。</param>privatestaticvoidPrintMatrix(Matmatrix){// 先统一转成 64F，方便按 double 读取和输出。usingvarmatrix64=newMat();matrix.ConvertTo(matrix64,MatType.CV_64FC1);for(varrow=0;row<matrix64.Rows;row++){Console.Write("[");for(varcol=0;col<matrix64.Cols;col++){Console.Write(matrix64.At<double>(row,col).ToString("F0"));if(col<matrix64.Cols-1){Console.Write(", ");}}Console.WriteLine("]");}Console.WriteLine();}}

8. 注意事项

1. dst必须是浮点类型。
2. mask为 0 的位置不会被累加。
3. 连续多帧累加时，数值会越来越大。
4. 如果你想直接求平均，可以在累加后再除以帧数。

9. 调优建议

1. 初学者先用小矩阵理解累加规则，再迁移到真实视频。
2. 如果你只关心局部区域，可以先设计好 mask。
3. 当你要做背景建模时，Accumulate常常是第一步。

10. 运行说明

1. 如果你在控制台工程里运行本文示例，直接把代码放进Program.cs即可。
2. 如果你在本仓库里学习，请打开 WPF 控件 Cv2AccumulateControl.xaml.cs 对应的页面。
3. 点击“运行场景A”，可以在右侧查看多帧累加后的结果。

11. 常见错误排查

1. 把dst误设成 8 位图像，导致累加结果溢出或截断。
2. 忘记mask为 0 的区域不会更新。
3. 误把累加当成平均值。
4. 不了解多帧累加后需要再做归一化或除以帧数。