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

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

Cv2.Rectangle

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

摘要：本页演示 Rectangle(InputOutputArray, Point, Point, Scalar, int, LineTypes, int) 如何用两个对角点绘制矩形，并说明 thickness<0 时会变成填充矩形。

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

public static void Rectangle(InputOutputArray img, Point pt1, Point pt2, Scalar color, int thickness = 1, LineTypes lineType = LineTypes.Link8, int shift = 0)

2. 函数用途

Cv2.Rectangle(...) 用来在图像上绘制一个轴对齐矩形。

这个重载直接接收两个 Point，非常适合下面这些场景：

1. 已经有两个对角点。
2. 角点来自检测结果或鼠标交互。
3. 想直接把两点当成矩形范围来画出来。

它常用于：

1. 画检测框。
2. 画兴趣区域（ROI）。
3. 标出待处理目标的范围。
4. 教学中讲解“两个角点决定一个矩形”。

3. 函数公式

两个对角点定义的矩形可以表示为：

$$R=[x_{min},x_{max}]\times [y_{min},y_{max}]$$

其中：

$$x_{min}=\min (x_1,x_2),x_{max}=\max (x_1,x_2)$$

$$y_{min}=\min (y_1,y_2),y_{max}=\max (y_1,y_2)$$

当 thickness<0 时，OpenCV 会把矩形内部直接填满。

4. 函数原理说明

这个函数会先把两个点规范化成矩形范围，再根据 thickness 决定画边框还是填充：

1. 先找出两个点的最小/最大 x 和 y。
2. 再按 lineType 把边框转成像素。
3. 如果 thickness<0，就绘制填充区域。

对初学者来说，最重要的是记住：

1. 两个 Point 不一定要严格按左上角、右下角顺序传入。
2. OpenCV 会自动按角点范围理解它们。
3. thickness 小于 0 时不是“更粗”，而是“填充”。

官方文档也明确说明：这个函数既可以画普通矩形，也可以画填充矩形。

5. 参数含义解析

参数名	类型	必填	含义
img	InputOutputArray	是	要被绘制的图像
pt1	Point	是	矩形一个角点
pt2	Point	是	与 pt1 对角的角点
color	Scalar	是	矩形颜色
thickness	int	否	线宽，默认 1；小于 0 时填充
lineType	LineTypes	否	线型，默认 Link8
shift	int	否	固定点小数位，默认 0

补充说明：

1. Point 版本最适合“两个角点”的原始数据。
2. color 在彩色图像里仍然按 BGR 顺序解释。
3. shift 与 Line 的含义相同，都是固定点坐标。

6. 应用场景列表

场景名	场景说明	典型用途
场景A：目标框	用两个角点框住目标	检测框
场景B：ROI 范围	指定一个处理区域	截图裁剪
场景C：标注框	人工标注的框	训练数据
场景D：UI 区域	做界面区域高亮	交互提示

7. 函数使用示例

说明：下面示例对应 WPF 场景 A。它直接使用两个角点绘制矩形，然后保存成 PNG。

using OpenCvSharp;

internal static class Program
{
    private static void Main()
    {
        // 创建白色背景，方便观察矩形边框。
        using var canvas = new Mat(240, 400, MatType.CV_8UC3, Scalar.White);

        // 两个对角点决定了矩形范围。
        var pt1 = new Point(62, 56);
        var pt2 = new Point(300, 188);

        // 这里使用普通描边矩形，方便先看懂角点关系。
        Cv2.Rectangle(
            canvas,
            pt1,
            pt2,
            new Scalar(68, 124, 230),
            3,
            LineTypes.Link8,
            0);

        // 把结果保存到文件里，便于直接观察。
        Cv2.ImWrite("rectangle-point.png", canvas);
    }
}

8. 注意事项

1. thickness<0 时是填充，不是更粗的边框。
2. 两个点顺序不严格固定，但示例里最好统一成左上角和右下角。
3. 矩形是轴对齐的，不会自动旋转。
4. 如果颜色和背景太接近，矩形边框会不明显。

9. 调优建议

1. 教学展示时，先用描边矩形，再讲填充矩形。
2. 需要强调区域时，填充矩形通常比单纯描边更醒目。
3. 如果想更平滑，可以把 lineType 换成 AntiAlias。
4. 如果坐标来源很多，建议先统一封装成 Point 或 Rect。

10. 进阶扩展

1. 可以把 Rectangle 和 Line 结合起来画检测框加对角线。
2. 可以把矩形和文字标签一起做成目标标注图。
3. 可以与 FindContours、BoundingRect 一起讲 ROI 和包围框。
4. 可以做一个可拖拽的矩形选择器。

11. 常见错误排查

1. 忘记 thickness<0 会触发填充语义。
2. 误以为两个点必须先排序，实际上 OpenCV 会自动理解它们。
3. 把矩形当成旋转矩形，结果预期和输出不一致。
4. 忽略了 InputOutputArray 需要可写目标图像。

相关链接：

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