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

fengxing666

156人浏览 · 2026-06-22 08:36:00

fengxing666 · 2026-06-22 08:36:00 发布

大家好，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. 函数公式

旋转椭圆可以写成下面的形式：

$\frac{x'^2}{a^2}+\frac{y'^2}{b^2}=1$

其中 $a$ 和 $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 官方文档强调了几个边界条件：

如果 startAngle > endAngle，OpenCV 会自动交换它们。
如果想画完整椭圆，可以把起止角设成 0 和 360。
抗锯齿边界主要适用于 8 位图像。
绘图函数会自动裁剪超出图像边界的部分。

对初学者来说，最容易混淆的是 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

补充说明：

axes 表示的是半轴，不是整条直径。
angle 和 startAngle/endAngle 的单位都是“度”。
如果要画完整椭圆，可以把 startAngle 设为 0，把 endAngle 设为 360。

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);
    }
}