OpencvSharp 算子学习教案之 – Cv2.Ellipse 重载1
大家好，Opencv在很多工程项目中都会用到，而OpencvSharp则是以C#开发与实现的Opencv操作库，对.NET开发人员友好，但很多API的中文资料、应用场景及常见坑点等缺乏系统性归纳，因此这系列博客将给大家带来Cv2及Mat对象全系列算子学习教案，供大家参考学习。
Cv2.Ellipse
- 教案版本：V1.0
- 面向对象：OpenCvSharp 初学者
- 所属模块：imgproc
- 源码位置：OpenCvSharp/Cv2/Cv2_imgproc.cs:4592
摘要：本页演示 Ellipse(InputOutputArray, Point, Size, double, double, double, Scalar, int, LineTypes, int) 如何使用圆心、半轴、旋转角和起止角绘制椭圆弧，并说明 startAngle 和 endAngle 的范围语义。
1. 函数名称（带参数签名）
public static void Ellipse(InputOutputArray img, Point center, Size axes, double angle, double startAngle, double endAngle, Scalar color, int thickness = 1, LineTypes lineType = LineTypes.Link8, int shift = 0)
2. 函数用途
Cv2.Ellipse(…) 用来在图像上绘制椭圆、椭圆弧或椭圆扇形。
这个重载直接接收圆心、半轴、旋转角和起止角，最适合下面这些场景：
它常用于：
3. 函数公式
旋转椭圆可以写成下面的形式：
x
′
2
a
2
+
y
′
2
b
2
=
1
\\frac{x'^2}{a^2}+\\frac{y'^2}{b^2}=1
a2x′2+b2y′2=1
其中
a
a
a 和
b
b
b 是半轴长度，旋转后的坐标可以写成：
$$ \\begin{bmatrix} x’\\ y’ \\end{bmatrix}
\\begin{bmatrix} \\cos\\theta & \\sin\\theta\\ -\\sin\\theta & \\cos\\theta \\end{bmatrix} \\begin{bmatrix} x-x_0\\ y-y_0 \\end{bmatrix} $$
如果 startAngle 和 endAngle 不是完整的 0 到 360，绘制结果就会变成椭圆弧或扇形。
4. 函数原理说明
这个函数内部会先按参数生成椭圆轮廓，再把轮廓近似成分段线段进行绘制。
OpenCV 官方文档强调了几个边界条件：
对初学者来说，最容易混淆的是 axes。它表示的是半轴长度对应的尺寸信息，不是一个普通的宽高矩形。
5. 参数含义解析
| img | InputOutputArray | 是 | 要被绘制的图像 |
| center | Point | 是 | 椭圆中心 |
| axes | Size | 是 | 椭圆半轴长度 |
| angle | double | 是 | 椭圆旋转角度，单位为度 |
| startAngle | double | 是 | 起始角，单位为度 |
| endAngle | double | 是 | 结束角，单位为度 |
| color | Scalar | 是 | 椭圆颜色 |
| thickness | int | 否 | 线宽，默认 1；小于 0 时表示填充 |
| lineType | LineTypes | 否 | 线型，默认 Link8 |
| shift | int | 否 | 固定点小数位，默认 0 |
补充说明：
6. 应用场景列表
| 场景A：姿态可视化 | 用旋转椭圆表示物体方向 | 目标跟踪 |
| 场景B：椭圆弧提示 | 只画出椭圆的一段 | 范围说明 |
| 场景C：拟合结果展示 | 显示椭圆拟合后的轮廓 | 计算机视觉教学 |
| 场景D：方向指示 | 用角度说明对象朝向 | 交互标注 |
7. 函数使用示例
说明：下面示例对应 WPF 场景 A。它用圆心、半轴、旋转角和起止角绘制一段椭圆弧。
using OpenCvSharp;
internal static class Program
{
private static void Main()
{
// 创建白底画布，便于观察椭圆弧的边界。
using var canvas = new Mat(260, 420, MatType.CV_8UC3, Scalar.White);
// 圆心、半轴和旋转角是椭圆的核心参数。
var center = new Point(200, 128);
var axes = new Size(110, 66);
double angle = 28;
double startAngle = 20;
double endAngle = 320;
// 用 InputOutputArray 包装 Mat，明确命中该重载。
using var drawTarget = InputOutputArray.Create(canvas);
// 这里画的是椭圆弧，而不是完整椭圆。
Cv2.Ellipse(drawTarget, center, axes, angle, startAngle, endAngle, new Scalar(64, 124, 230), 3, LineTypes.AntiAlias, 0);
// 保存结果，方便观察旋转角和起止角的影响。
Cv2.ImWrite("ellipse-center-axes.png", canvas);
}
}
8. 注意事项
9. 调优建议
10. 进阶扩展
11. 常见错误排查
相关链接：
- WPF 教学控件：Cv2EllipseControl.xaml.cs
- 样例实现：EllipseCenterAxesSample.cs
- 官方文档源码位置：OpenCvSharp/Cv2/Cv2_imgproc.cs
