简介这份C#自定义图像控件ROI绘制管理资源面向WinForm开发者与机器视觉入门者解决在图像窗体上交互式绘制矩形、旋转矩形、圆形等兴趣区域并统一管理的需求。代码以UImageWindow控件为载体结合ROI基类与List集合组织不同形状对象新增类型时只需继承基类即可便于扩展与维护。压缩包共34个文件以14个.cs源码文件为核心同时包含窗体资源、配置文件、可执行程序等整体大小仅159KB结构清晰适合直接参考改造。已有185人学习下载。通过源码可掌握自定义控件继承、图形绘制与命中测试、集合管理及设计时支持等关键写法尤其适合希望快速在项目中嵌入ROI标注与管理功能的C#中级开发者。 做了几年C#上位机开发最绕不开的一个需求就是在图像上画ROIRegion of Interest感兴趣区域。无论是做视觉定位、缺陷检测还是简单的尺寸测量第一步基本都是让用户框出要处理的区域。这个功能乍一看不起眼真要做得好用、稳定、可维护里面藏着不少门道。今天就把我这几年在WinForm下实现ROI绘制管理组件的经验完整写出来从数据结构设计到交互细节从绘制优化到坐标系统转换一次性讲透。适合正在做上位机、视觉项目或者想自己封装控件库的朋友参考。1. 组件整体设计与数据结构1.1 为什么选择GDI自绘方案做ROI绘制技术路线无非三条使用现成的第三方控件、基于OpenCV的UI窗口、自己用GDI实现。我用过前两种最后都换成了自绘方案原因很实际第三方控件比如Halcon的HWindow虽然功能完整但商业授权贵而且和C#项目的融合度始终差一口气OpenCV自带的高GUI窗口则完全不支持复杂的自定义交互做演示可以做产品不行。自绘的好处是彻底可控。你可以定义任意形态的ROI控制它的画笔、填充、选中状态、手柄样式还可以把ROI的数据结构独立出来方便序列化保存和跨模块传递。GDI本身性能足够绘制几十个ROI完全不会卡顿对于上位机这种对实时性要求不极端苛刻的界面场景自绘是性价比最高的选择。1.2 ROI基类与继承体系ROI的类型会越来越多矩形、旋转矩形、圆形、多边形、椭圆甚至点区域。为了让上层逻辑统一处理我设计了一个抽象基类RoiBase所有具体类型继承它。public abstract class RoiBase { public string Id { get; set; } Guid.NewGuid().ToString(); public string Name { get; set; } public RoiType Type { get; protected set; } public bool IsSelected { get; set; } public bool IsVisible { get; set; } true; public Color PenColor { get; set; } Color.Lime; public float PenWidth { get; set; } 2f; /// summary绘制ROI本体/summary public abstract void Draw(Graphics g, CoordTransform transform); /// summary命中测试判断点是否落在ROI区域内/summary public abstract bool HitTest(PointF point, CoordTransform transform, float tolerance); /// summary平移ROI/summary public abstract void Translate(PointF offset); /// summary获取所有拖拽手柄的位置/summary public abstract ListDragHandle GetHandles(CoordTransform transform); /// summary根据手柄操作更新ROI/summary public abstract void UpdateFromHandle(DragHandle handle, PointF newPos); /// summary序列化为可保存的结构/summary public abstract RoiData Serialize(); /// summary从保存的结构恢复/summary public abstract void Deserialize(RoiData data); }这套设计的核心思路是面向接口编程。上层不管是列表管理、右键菜单还是保存加载都只依赖RoiBase新增一种ROI类型时不需要改动任何上层代码只增加一个继承类就行。1.3 手柄与拖动状态的建模ROI交互的核心是手柄Handle。选中一个ROI后要能通过拖动手柄来缩放、旋转通过拖动本体来平移。我把手柄抽象成一个结构public enum HandleType { Move, Corner, Edge, Rotate } public class DragHandle { public HandleType Type { get; set; } public int Index { get; set; } // 标识哪个顶点/边 public PointF Position { get; set; } // 屏幕坐标 public float Size { get; set; } 8f; }交互时需要一个状态机来记录鼠标的状态Idle空闲、Creating创建中、Moving平移、Resizing缩放、Rotating旋转。每次鼠标按下时先做命中测试确定进入哪个状态鼠标移动时根据状态调用对应的方法更新ROI鼠标抬起时恢复到Idle。这个状态机是整个交互逻辑的地基状态转移清晰了代码就不会乱。2. 核心绘制细节与实时渲染优化2.1 矩形、旋转矩形、圆形的GDI绘制实现矩形和圆形属于基础形态直接调用GDI原生方法即可。旋转矩形稍微麻烦因为GDI没有直接画旋转矩形的接口。我的做法是先把坐标系统平移到旋转矩形的中心然后按角度旋转坐标系再画一个没有旋转角度的矩形public override void Draw(Graphics g, CoordTransform transform) { var rect transform.ImageToScreen(_center, _width, _height); var state g.Save(); g.TranslateTransform(rect.Center.X, rect.Center.Y); g.RotateTransform(-_angle); // 注意GDI的角度方向 g.DrawRectangle(_pen, -rect.Width / 2, -rect.Height / 2, rect.Width, rect.Height); g.Restore(state); }这里有个坑GDI的RotateTransform是顺时针方向而数学上我们习惯的极坐标角度是逆时针为正。如果后续要和OpenCV的RotatedRect做数据交换OpenCV的angle定义也是顺时针但是从水平轴开始量。这个方向问题经常导致角度显示对不上后面专门写一节来讲。绘制时Pen的宽度建议跟随缩放比例调整。图像放大时如果画笔宽度固定ROI的线条会显得很细看不清图像缩小时又会显得很粗遮挡内容。我一般会把PenWidth乘上当前缩放系数的倒数保证ROI在屏幕上看起来粗细一致。2.2 双缓冲与局部刷新策略用过GDI自绘的人都知道最大的痛点是闪烁。闪烁的根源是绘制过程太长窗体先擦除背景再重绘中间有一段时间屏幕是空白或旧画面。解决方法是双缓冲在内存里先把整帧画好再一次性地拷贝到屏幕。WinForms下最简单的做法是设置控件的DoubleBuffered true但它对自定义控件有效对直接在窗体上绘制的情况支持有限。我更推荐用BufferedGraphics可以精确控制缓冲区域public class RoiCanvas : Control { private BufferedGraphics _bufferedGraphics; private BufferedGraphicsContext _context; protected override void OnResize(EventArgs e) { base.OnResize(e); if (_context null) _context BufferedGraphicsManager.Current; if (_bufferedGraphics ! null) _bufferedGraphics.Dispose(); _bufferedGraphics _context.Allocate(CreateGraphics(), ClientRectangle); Invalidate(); } protected override void OnPaint(PaintEventArgs e) { if (_bufferedGraphics null) return; _bufferedGraphics.Graphics.Clear(Color.FromArgb(30, 30, 30)); // 1. 绘制背景图图像 DrawImage(_bufferedGraphics.Graphics); // 2. 绘制所有ROI DrawAllRois(_bufferedGraphics.Graphics); // 3. 绘制选中ROI的手柄与信息 DrawSelectedHandles(_bufferedGraphics.Graphics); _bufferedGraphics.Render(e.Graphics); } }局部刷新方面鼠标拖动ROI时实际上每一帧变化的区域很小。如果不做任何优化整个控件不停地重绘CPU占用会偏高。我采取的方案是在鼠标拖动时只刷新ROI变化前后的两个边界矩形合并区域Region拖动结束后再全量刷新。实测下来CPU占用能降低40%以上。具体实现是记录拖动前和拖动后的ROI边界然后Invalidate(mergedRect)。2.3 选中态、悬停态、禁用态的视觉反馈一个成熟的ROI组件视觉反馈细节很重要。我在项目里实现了三种交互状态悬停鼠标在ROI上但未按下、选中点击后、禁用不允许操作。普通状态下使用纯色线条选中状态下使用白色虚线叠加悬停时把鼠标光标改成移动图标并将ROI的描边加粗。手柄在选中态才显示每个手柄是一个小实心方块外加一个半透明的外圈这样在复杂图像背景下也能看清楚。视觉反馈其实是在传达这个区域可被操作的语义。用户看到光标变化和手柄就自然明白怎么操作不需要教程。这就是好的交互设计应该做的。3. 交互操作实战创建、拖拽、旋转、缩放3.1 鼠标事件驱动的完整交互流程ROI的创建和编辑本质上就是一组鼠标事件的组合。我在RoiCanvas控件里定义了一个交互控制器RoiInteractionController把事件逻辑从绘制逻辑中分离出来避免OnPaint和OnMouseMove纠缠不清。创建矩形ROI的流程是鼠标按下时如果当前处于添加矩形模式就记录起点创建一个临时ROI进入Creating状态鼠标移动时动态更新ROI的长宽鼠标抬起时如果长宽小于某个阈值比如5像素判定为误操作取消创建否则把临时ROI正式加入ROI列表。protected override void OnMouseDown(MouseEventArgs e) { base.OnMouseDown(e); if (_interactionMode InteractionMode.AddRectangle) { _currentRoi new RoiRect { StartPoint e.Location }; _controller.EnterState(InteractionState.Creating); Invalidate(); } } protected override void OnMouseMove(MouseEventArgs e) { base.OnMouseMove(e); if (_controller.CurrentState InteractionState.Creating) { var rect _currentRoi as RoiRect; rect.EndPoint e.Location; Invalidate(); } else { // 命中测试切换光标样式 UpdateCursor(e.Location); } } protected override void OnMouseUp(MouseEventArgs e) { base.OnMouseUp(e); if (_controller.CurrentState InteractionState.Creating) { var rect _currentRoi as RoiRect; if (rect.Width 5 rect.Height 5) _roiManager.Add(rect); else _currentRoi null; // 视为误触 _controller.EnterState(InteractionState.Idle); Invalidate(); } }旋转矩形的创建和矩形类似但有一点不同用户拖出矩形后还可以在松开前旋转角度。我的实现是按住鼠标拖出初始矩形此时如果按住Shift键移动鼠标旋转跟随鼠标相对中心的方位角变化松开Shift则保持当前角度。这样一次操作就能完成旋转矩形的全部参数设定。3.2 命中测试点与旋转矩形的距离计算命中测试是交互的基石做不好就会出现明明点在ROI上却没反应的糟糕体验。矩形和圆形很好判断旋转矩形需要多一步坐标变换。我的方案是把鼠标点先变换到旋转矩形的本地坐标系再判断是否落在未旋转的矩形范围内public override bool HitTest(PointF point, CoordTransform transform, float tolerance) { var center transform.ImageToScreen(_center); var dx point.X - center.X; var dy point.Y - center.Y; var rad -_angle * Math.PI / 180.0; // 逆变换转到本地坐标系 var localX (float)(dx * Math.Cos(rad) - dy * Math.Sin(rad)); var localY (float)(dx * Math.Sin(rad) dy * Math.Cos(rad)); var halfW _width * transform.Scale / 2 tolerance; var halfH _height * transform.Scale / 2 tolerance; return Math.Abs(localX) halfW Math.Abs(localY) halfH; }这里的关键是tolerance参数。用户的操作习惯和屏幕分辨率不同鼠标点击的精确位置和视觉上想点的位置往往有3到5像素的偏差所以命中测试加一点冗余是必要的。我一般用8像素用户基本感觉不到延迟。3.3 旋转手柄与缩放约束旋转手柄的位置通常放在ROI顶部边缘的中间这样离ROI本身有一段距离用户不容易误操作。我把旋转手柄的位置定义为矩形本地坐标系的(0, -halfH - offset)然后经过旋转和平移变换映射到屏幕坐标。旋转操作时计算鼠标位置与ROI中心点的夹角更新ROI的_angle。为了让旋转更跟手会有平滑处理的细节记录上一帧的角度计算差值如果差值大于180度或小于-180度做角度归约防止角度跳变。public void RotateTo(PointF mousePos) { var center RoiToScreenCentroid(); var angle (float)(Math.Atan2(mousePos.Y - center.Y, mousePos.X - center.X) * 180.0 / Math.PI); // 矩形绘制时顶部朝上而GDI角度从水平轴算起所以要加90度 _angle angle 90f; // 角度归一化到 [0, 360) _angle (_angle 360f) % 360f; }缩放约束也是实际使用中容易忽略的点。直接拖动角手柄时如果鼠标从矩形右下角拖到了左上角矩形会翻面宽高变成负值。为了避免这种情况我在UpdateFromHandle里对宽高做了下限约束最小5像素同时保持中心点不变。对于Shift键同时按下的情况则保持宽高比约束实现等比缩放。4. 管理功能与坐标系联动4.1 ROI列表的数据绑定与批量操作ROI画出来只是第一步能管起来才是工程化的关键。我实现了一个RoiManager类内部维护ObservableCollectionRoiBase这样可以和WinForms的DataGridView或ListBox直接绑定ROI的新增、删除、选中状态变化都能实时同步到界面列表上。管理功能覆盖了添加、删除、复制CtrlD、清空、全选、上移下移调整绘制层级、显示/隐藏、锁定禁止编辑、重命名。这些操作看起来琐碎但在实际项目中每个都派得上用场。比如锁定功能在图像密集区域微调时防止误拖其他ROI是非常关键的。public class RoiManager { public ObservableCollectionRoiBase Items { get; } new(); public RoiBase SelectedItem { get; set; } public void Duplicate() { if (SelectedItem null) return; var copy SelectedItem.Clone(); copy.Translate(new PointF(15, 15)); // 偏移一些避免完全重叠 Items.Add(copy); SelectedItem copy; } }4.2 图像坐标与屏幕坐标的变换映射ROI组件嵌入显示图像的控件中必然涉及坐标变换。图像有自己的分辨率控件有屏幕尺寸用户可能还做了缩放和平移。我的处理方式是封装一个CoordTransform类持有三个参数Scale缩放系数、OffsetX、OffsetY。screenX imageX * Scale OffsetX screenY imageY * Scale OffsetY反向变换则反过来。所有ROI内部存储的坐标一律是图像逻辑坐标仅在与鼠标交互时才转换为屏幕坐标。这样做的好处是无论用户怎么缩放和平移图像ROI的数据始终稳定保存加载不会错乱。有个常见坑一定要提DPI缩放。WinForms在高DPI显示器上默认不缩放导致图像显示模糊、坐标偏移。我给RoiCanvas的构造函数里加了SetStyle并在程序入口设置了Application.SetHighDpiMode(HighDpiMode.PerMonitorV2)这样坐标变换才能在高分屏上保持准确。4.3 与OpenCV及脚本数据的格式对接视觉项目绕不开OpenCV的RotatedRect。C#这边基本通过OpenCvSharp来交互。原始数据交换时两边矩形中心在图像坐标系中是相同的主要差异在角度定义上。OpenCV的RotatedRect.angle表示矩形宽边与水平轴顺时针的夹角范围是[0, 90)而GDI旋转变换从0度水平轴顺时针为正向。我在对接时写过转换工具函数public static RotatedRect ToOpenCvRotatedRect(RoiRotatedRect roi) { float angle roi.Angle; // 统一到OpenCV的 [0, 90) 区间并保证宽高匹配 if (angle 90) angle - 90; return new RotatedRect(roi.Center, new Size2f(roi.Width, roi.Height), angle); }另外很多视觉脚本需要ROI参数比如Halcon的gen_rectangle2我通常在导出时生成一段配置文本包含类型、中心坐标、宽高、角度等信息。这样调试的时候可以把C#里画好的ROI直接复制到Halcon脚本里验证处理效果效率非常高。5. 常见问题与排查技巧实录5.1 绘制闪烁与性能瓶颈现象1拖动ROI时整个画面闪烁抖动。排查八成是没开双缓冲或Invalidate的区域过大。解决办法是设置DoubleBuffered true并且拖动过程中只刷新变化区域。如果你的绘制代码里每次OnPaint都重新加载图像那性能会更差图像对象应当作为缓存在外部传入不在绘制回调里做磁盘IO。现象2ROI数量一多超过50个拖动时明显卡顿。排查逐个绘制时如果每次都创建Pen和Brush资源开销巨大。把常用画笔预先创建并缓存绘制时直接用能显著提升性能。还可以利用GDI的Region.Exclude或裁剪只画可见区域中的ROI避免绘制屏幕外的ROI。5.2 旋转矩形角度混乱现象旋转矩形在C#里显示正常但传给OpenCV之后角度和宽高方向似乎对不上。根源角度参考系不一致。GDI的RotateTransform以屏幕Y轴向下为正向视觉上看起来顺时针增加OpenCV的angle是宽边与水平轴的夹角且范围有限。出现这类问题时不要只盯着转换函数先把两边在相同输入下的输出打出来对比确认各自的角度定义后再写映射。排查技巧写一个自检工具程序启动时创建已知角度的旋转矩形0度、30度、45度、90度、135度导出为OpenCV格式再让OpenCV画回来对比一目了然。5.3 图像缩放后ROI错位现象放大图像后ROI不再贴合图像上的目标区域。原因ROI坐标被错误地存成了屏幕坐标。屏幕坐标会随缩放和平移变化而图像坐标是固定的。正确做法是所有ROI内部只存图像坐标只有绘图和命中测试时才做变换。再补充一个我踩过的坑在做平移变换时如果OffsetX和OffsetY是累计加法算出来的时间长了会有浮点误差累积导致图像微漂移。解决方法是保存一个视图中心点和缩放系数每次渲染时用中心点计算出偏移量而不是累加增量。5.4 用户习惯和细节体验做完核心功能后我第一次拿给同事直接试用反馈了不少体验问题一并整理在这里鼠标拖拽创建矩形时如果从右下角往左上角拖矩形会出现负宽高视觉上翻转了。我的处理是在所有ROI类型里都做了归一化创建过程中实时计算左上角和右下角始终保证宽高为正。删除快捷键建议同时支持Delete和CtrlBackspace很多工业现场用的键盘轨迹球不一定方便按Delete。右键菜单应该包含复制到图像坐标系、显示顶点坐标等调试信息对排查视觉问题时非常有帮助。多个ROI重叠时点击应该选择最顶层的那个而不是第一个命中测试通过的那个。所以命中测试时要倒序遍历ROI列表从最后一个最上层开始。个人经验与扩展想法最后说一点我个人的体会。ROI组件不只是一个绘图功能它其实是视觉项目的交互地基。一次做对了后面所有需要圈选、标记、测量的功能都可以复用它做粗糙了后续每个项目都得打补丁。我目前这套C#版本的ROI组件已经在两个量产设备上跑了两年多性能稳定。最近我正在为它补充两个扩展方向一是把ROI配置做成模板支持批量加载和多套方案切换适合换产场景二是增加ROI组的逻辑门比如两个圆的交集区域方便做复合测量。如果你正在做类似功能我建议从矩形和圆形两个类型起步把交互状态机、坐标变换、序列化这三个核心模块打磨好然后再加旋转矩形和多边形。工欲善其事必先利其器这套底子花两个月打扎实后面能省两年改需求的时间。本文还有配套的精品资源点击获取
