OpencvSharp 算子学习教案之 - Cv2.Circle 重载2

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

Cv2.Circle

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

摘要：本页演示 Circle(InputOutputArray, Point, int, Scalar, int, LineTypes, int) 如何直接使用 Point 对象绘制圆，并通过 thickness<0 演示实心圆。

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

publicstaticvoidCircle(InputOutputArrayimg,Pointcenter,intradius,Scalarcolor,intthickness=1,LineTypeslineType=LineTypes.Link8,intshift=0)

2. 函数用途

Cv2.Circle(...)用来在图像上绘制一个圆。

这个重载直接接收Point center，最适合下面这些场景：

1. 你的上游函数已经返回了一个点对象。
2. 你想把几何结果和绘图结果继续连起来讲。
3. 你希望代码更清晰地表达“圆心就是一个点”。

它常用于：

1. 特征点可视化。
2. 关键点高亮。
3. 圆形标注和实心圆提示。
4. 教学中演示对象化坐标写法。

3. 函数公式

圆的几何定义仍然是：

( x − x 0 ) 2 + ( y − y 0 ) 2 = r 2 (x-x_0)^2+(y-y_0)^2=r^2(x−x0​)2+(y−y0​)2=r2

这里只是把圆心从两个整数改成了一个Point对象，几何意义完全没有变化。

当shift启用时，整数点仍然可以按固定点方式解释：

p r e a l = p i n t 2 s h i f t p_{real}=\frac{p_{int}}{2^{shift}}preal​=2shiftpint​​

4. 函数原理说明

这个函数和 int 坐标版本的绘制原理相同：

1. 先读取圆心对象和半径。
2. 再根据lineType生成边界像素。
3. 最后按thickness决定画边还是填充。

OpenCV 官方文档还说明了这些边界条件：

1. 绘图函数会自动裁剪超出图像边界的部分。
2. 抗锯齿主要适用于 8 位图像。
3. 颜色通道按 BGR 顺序解释。

对初学者来说，Point版本的价值在于：它更像“几何对象”，而不是“两个分散的数字”。

5. 参数含义解析

补充说明：

1. Point很适合和其它几何函数配套使用。
2. radius仍然是半径，不是直径。
3. thickness < 0时会得到一个实心圆。

6. 应用场景列表

7. 函数使用示例

说明：下面示例对应 WPF 场景 B。它直接传入Point center，并把thickness设成-1来演示实心圆。

usingOpenCvSharp;internalstaticclassProgram{privatestaticvoidMain(){// 创建一张白底画布，便于观察填充区域。usingvarcanvas=newMat(240,400,MatType.CV_8UC3,Scalar.White);// 这里直接使用 Point 表示圆心。varcenter=newPoint(230,120);intradius=54;// 把 Mat 包装成 InputOutputArray，明确命中 Point 重载。usingvardrawTarget=InputOutputArray.Create(canvas);// thickness = -1 表示绘制实心圆。Cv2.Circle(drawTarget,center,radius,newScalar(230,126,68),-1,LineTypes.AntiAlias,0);// 保存结果，方便直接检查实心圆的效果。Cv2.ImWrite("circle-point.png",canvas);}}

8. 注意事项

1. Point只是坐标容器，不会自动帮你做几何校正。
2. thickness < 0时不会再画边框，而是直接填充。
3. 如果圆心颜色和背景接近，初学者可能会误以为没画出来。
4. shift仍然是固定点语义，不是普通缩放参数。

9. 调优建议

1. 调试时可以先用浅色背景，再用深色圆。
2. 如果需要突出圆心，可以叠加DrawMarker或文本标签。
3. 如果要展示边界平滑效果，优先使用LineTypes.AntiAlias。
4. 如果要表达“选中区域”，实心圆通常比空心圆更醒目。

10. 进阶扩展

1. 可以把圆心和DrawMarker组合起来做调试工具。
2. 可以和Ellipse对比，帮助初学者理解“圆是椭圆的特例”。
3. 可以把点坐标从PointPolygonTest、FitLine等函数结果中取出来。
4. 可以和鼠标事件配合做实时交互圆。

11. 常见错误排查

1. 把Point当成普通数组使用，而不是几何点对象。
2. 把半径写成直径。
3. 误以为thickness < 0只是“更粗一些”。
4. 忽略了 BGR 和 RGB 的顺序差异。

相关链接：

• WPF 教学控件：Cv2CircleControl.xaml.cs
• 样例实现：CirclePointSample.cs
• 官方文档源码位置：OpenCvSharp/Cv2/Cv2_imgproc.cs