OpencvSharp 算子学习教案之 - Cv2.DrawContours 重载1-尧图网络科技

OpencvSharp 算子学习教案之 - Cv2.DrawContours 重载1

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

Cv2.DrawContours

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

摘要：本页演示 DrawContours(InputOutputArray, IEnumerable<IEnumerable>, int, Scalar, int, LineTypes, IEnumerable?, int, Point?) 如何按轮廓层级绘制指定子树，并说明 contourIdx 和 maxLevel 的配合方式。

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

publicstaticvoidDrawContours(InputOutputArrayimage,IEnumerable<IEnumerable<Point>>contours,intcontourIdx,Scalarcolor,intthickness=1,LineTypeslineType=LineTypes.Link8,IEnumerable<HierarchyIndex>?hierarchy=null,intmaxLevel=int.MaxValue,Point?offset=null)

2. 函数用途

Cv2.DrawContours(...)用来在图像上绘制一个或多个轮廓的边界，或者在thickness < 0时直接填充轮廓区域。这个重载直接接收点集和层级信息，最适合从“轮廓树”角度理解绘制范围。

它常用于：

轮廓可视化。
目标分组和子轮廓高亮。
带孔区域的边界说明。
从 FindContours 的结果里筛选某个轮廓子树。

3. 函数公式

如果把轮廓看成有父子关系的树，那么绘制范围可以理解成：

S ( contourIdx , maxLevel ) = { c ∣ c ∈ subtree ( contourIdx ) , depth ( c ) ≤ maxLevel } S(\text{contourIdx},\text{maxLevel})=\{c\mid c\in \text{subtree}(\text{contourIdx}),\;\text{depth}(c)\le \text{maxLevel}\}S(contourIdx,maxLevel)={c∣c∈subtree(contourIdx),depth(c)≤maxLevel}

这个公式不是 OpenCV 的源码公式，而是帮助初学者理解contourIdx和maxLevel的抽象方式。contourIdx负责选根，maxLevel负责决定向下展开多少层。

4. 函数原理说明

这个函数会先读取轮廓集合，再根据contourIdx选择从哪一个轮廓开始绘制。如果传入了层级信息，maxLevel就会决定要不要继续画子轮廓、孙轮廓。

OpenCV 官方文档明确说明：

thickness >= 0时绘制轮廓边界。
thickness < 0时填充轮廓内部。
maxLevel只在存在层级信息时才有意义。
offset会把所有绘制出来的轮廓一起平移。

对初学者来说，最重要的是理解：DrawContours不是简单地“把数组画出来”，它会根据层级关系决定究竟画哪一部分。

5. 参数含义解析

参数名	类型	必填	含义
image	InputOutputArray	是	要被绘制的图像
contours	IEnumerable<IEnumerable>	是	每条轮廓的点集
contourIdx	int	是	要从哪条轮廓开始绘制，负数表示全部绘制
color	Scalar	是	轮廓颜色
thickness	int	否	线宽，负数表示填充
lineType	LineTypes	否	线型，默认`Link8`
hierarchy	IEnumerable?	否	轮廓层级信息
maxLevel	int	否	最大绘制层级，默认`int.MaxValue`
offset	Point?	否	所有轮廓的整体平移量

补充说明：

hierarchy的每一项都对应一条轮廓。
contourIdx=0并不代表“全部轮廓”，它只代表从第 1 条轮廓开始。
maxLevel越大，递归展开得越深。

6. 应用场景列表

场景名	场景说明	典型用途
场景A：轮廓树可视化	只画一个轮廓及其子树	层级教学
场景B：孔洞轮廓	看外轮廓和内轮廓的关系	掩膜处理
场景C：局部高亮	只强调某个目标轮廓	调试展示
场景D：结果标注	给提取结果加颜色	视觉分析

7. 函数使用示例

说明：下面示例对应 WPF 场景 A。它用点集和层级信息绘制轮廓子树，并展示contourIdx=0和maxLevel=2的效果。

usingOpenCvSharp;internalstaticclassProgram{privatestaticvoidMain(){// 准备一组有父子关系的轮廓：外轮廓、洞、洞中的小岛，以及右侧独立轮廓。varcontours=new[]{new[]{newPoint(52,50),newPoint(158,40),newPoint(196,98),newPoint(170,174),newPoint(88,186),newPoint(42,122),},new[]{newPoint(88,82),newPoint(138,78),newPoint(154,118),newPoint(126,144),newPoint(82,124),},new[]{newPoint(108,98),newPoint(126,94),newPoint(132,114),newPoint(112,122),},new[]{newPoint(244,62),newPoint(312,46),newPoint(346,94),newPoint(328,156),newPoint(260,146),newPoint(232,100),},};// 手工构造层级信息，和上面的四条轮廓一一对应。varhierarchy=new[]{newHierarchyIndex(3,-1,1,-1),newHierarchyIndex(-1,-1,2,0),newHierarchyIndex(-1,-1,-1,1),newHierarchyIndex(-1,0,-1,-1),};usingvarcanvas=newMat(260,400,MatType.CV_8UC3,Scalar.White);usingvartarget=InputOutputArray.Create(canvas);// contourIdx=0 表示从第 1 条轮廓开始，maxLevel=2 表示展开两层子轮廓。Cv2.DrawContours(target,contours,0,newScalar(53,114,223),3,LineTypes.AntiAlias,hierarchy,2,null);// 保存图片，检查轮廓子树是否按预期绘制。Cv2.ImWrite("drawcontours-point-enumerable.png",canvas);}}