简介面向 C# 与 WPF 开发者、机器视觉方向学习者的图像控件与 ROI 管理示例工程目标是在 WPF 中复刻 Halcon HSmartWindowControl 的交互体验加载并显示图像在图像上绘制矩形、圆形等 ROI并通过鼠标点击与拖动完成 ROI 的添加、删除和修改。工程以 RoiDisplay 解决方案组织包含 RoiDisplayWpf 主程序、TestWindowWpf 测试窗口以及 RoiImplementation、Helper、Themes 等模块接口划分清晰便于后续接入 OpenCV 实现自动检测与模板匹配等扩展功能。压缩包共 86 个文件以 31 个 C# 源码、3 个 XAML 界面文件、2 个 csproj 项目文件与 sln 解决方案为主辅以 dll、config、resx 等依赖与配置项整体约 319KB。目前已有 412 人学习下载适合需要参考控件封装思路、ROI 数据结构设计与交互事件处理的开发者对照阅读。1. 从「控件不像控件」说起为什么要自己写一个图像显示与 ROI 交互控件用 WPF 做机器视觉上位机第一版几乎都会这么写一个Image显示位图上面盖一个CanvasCanvas里放几个Rectangle当 ROI。跑通 demo 只用半天等到要加滚轮缩放、按住空格拖拽平移、拖动 ROI 手柄改尺寸问题就全冒出来了——ROI 框跟着鼠标飘、手柄在 150% 缩放的屏幕上点不中、几千万像素的大图一刷新就卡成幻灯片。根子不在画得对不对而在于屏幕坐标、图像坐标、ROI 逻辑坐标这三套坐标系没有单一可信的换算入口谁都随手乘一个 scale最后就变成了玄学。这套方案要干的事就是把这三层拆开用 C# 写一个能承载 Halcon 与 OpenCV 两种图像源的自定义 WPF 图像控件把 ROI 的绘制、编辑、管理与序列化做成一套可复用的基础设施。它适合正在做视觉检测毕设、课设或者要给设备写一个能交付的取图界面的开发者。2. 需求拆解与选型三层渲染管线与自定义控件的边界动手之前先把「控件到底该管到哪一步」划清楚否则写着写着就会变成一个什么都想干的巨型UserControl。我的划分方式是三层底图层只管把一块内存按正确的缩放和平移画出来ROI 覆盖层只管矢量图元的绘制与命中测试交互层只管把鼠标、键盘、触控事件翻译成对前两层的指令。三层之间不互相new全部通过接口和变换对象通信。这样做的直接好处是底图从WriteableBitmap换成 D3D 共享表面时ROI 那一层一行都不用改。2.1 交互需求清单从「能看」到「能改」的五个层次很多人写控件是先写代码再想需求结果做到一半发现少了个功能架构撑不住只能推倒。我一般会先把需求按能力分层列出来再决定每一层放在哪个类里。图像控件的需求大致能分成五层越往上耦合越重层级能力典型操作归属L1 显示把图正确画出来适应窗口、1:1 显示、灰度/RGB 切换底图层L2 导航在图像里移动视野滚轮以光标为中心缩放、空格左键平移、双击复位交互层L3 创建产生 ROI 图元拖框、拉圆、逐点打多边形、十字取点交互层 ROI 层L4 编辑修改已有 ROI选中、八手柄缩放、旋转、顶点增删、边中点插入ROI 层L5 管理组织与持久化图层顺序、可见性、锁定、命名、序列化、撤销重做领域层这张表的价值在于L1、L2 属于「视图变换」可以用一个 3×2 矩阵全部表达L3 到 L5 属于「图元模型」跟缩放比例无关。把这两件事混在一个类里是后面所有坐标 bug 的源头。提示如果你的项目只需要框选区域送去算法处理L4 里的旋转和顶点编辑可以砍掉能省掉至少三分之一的工作量。先砍需求再谈架构。2.2 渲染选型WriteableBitmap、D3DImage 与 SkiaSharp 的取舍底图怎么画是这个控件第一个必须拍板的决定。常见的四条路各有各的脾气方案刷新开销跨线程实现复杂度适用场景ImageBitmapSource每次换图都要新建对象差低静态图浏览WriteableBitmap中WritePixels走 UI 线程一般低中小图、低频刷新D3DImage低GPU 直通好高高帧率取流、大图SkiaSharpSKElement低好中需要复杂矢量叠加我的默认选择是WriteableBitmap理由是它跟 WPF 的布局、命中测试、RenderTransform天然兼容代码量最小绝大多数课程设计和中小型检测设备够用。只有当图像宽度超过 4000 像素、刷新率要求 30fps 以上时才值得上D3DImage——它需要自己管理 D3D9 共享表面、前后台缓冲和Lock/Unlock调试成本不低属于典型的「性能换复杂度」。至于 SkiaSharp好处是底图和 ROI 能在同一个绘制上下文里画完省掉一层视觉树坏处是失去 WPF 原生的HitTestCore、装饰器和无障碍支持鼠标交互得全部手写。选型一旦定了就要把它藏到接口后面。我在项目里通常定义这么一个图像源抽象让两种内存布局Halcon 的交错指针和 OpenCV 的连续Mat.Data都收敛到同一个UpdatePixels调用上public interface IImageSource { int Width { get; } int Height { get; } // 每像素字节数灰度1、Bgr24为3、Bgra32为4 int Stride { get; } PixelFormat Format { get; } // 把外部内存整块写入目标位图区域rect 为脏区图像坐标 // 返回 false 表示源尺寸已变化调用方需要重建后端缓冲 bool TryWrite(IntPtr src, int srcStride, Int32Rect rect); }TryWrite的rect参数是为脏区刷新留的口子取流时往往只有一小块区域在变整图重写既浪费带宽也拉高 GC。srcStride单独传入而不是用Stride是因为 Halcon 的HImage每行字节数可能做过对齐跟宽度乘通道数对不上这个坑后面第 5 章还会提。返回bool而不是抛异常是为了让上层在分辨率切换时能走「重建缓冲」的分支而不是靠捕获异常做流程控制。2.3 控件基类FrameworkElement、Control 还是 UserControlWPF 里写自定义控件有三条路选错了后面很难受。UserControl本质是一个带 XAML 的组合写起来最快但它是封闭的——别人没法用Template换皮肤你也很难在它内部再插一层VisualCollection。Control有Template、支持主题样式代价是要写Generic.xaml、处理TemplatePart对一个内部使用的图像控件来说太重。我最后选的是FrameworkElement直接派生重写OnRender画底图再用一个受保护的VisualCollection挂 ROI 层的DrawingVisual。理由很实际图像控件不需要内容模型不需要控件模板它需要的是对视觉树和命中测试的完全控制权。FrameworkElement默认的HitTestCore返回整个矩形正好适合做「点击空白处取消选中」这种逻辑而 ROI 的命中测试我在OnMouseLeftButtonDown里自己做不走 WPF 的命中体系因为 ROI 是逻辑对象不是UIElement这样它才能被序列化、被算法层直接引用。VisualCollection这一层的用法要留意顺序底图DrawingVisual放第 0 个ROI 放第 1 个橡皮筋预览放第 2 个。AddVisualChild和AddLogicalChild都要调用否则视觉能画出来但逻辑树断链DataContext继承会失效。这个细节在官方文档里写得不显眼我第一次写的时候只加了视觉没加逻辑绑定的ViewModel一直是null查了两个小时。2.4 图像源适配Halcon 与 OpenCV 两种内存布局的统一真正的项目里图像大概率不是从文件读的而是从相机 SDK、Halcon 的HObject或者 OpenCV 的Mat转过来的。这三者的内存布局差异比想象中大Halcon 的HImage通过GetImagePointer1拿到的是行首指针加行宽通道是分开的三个平面OpenCV 的Mat默认是 BGR 交错Step可能大于Width * 3SIMD 对齐。适配层的职责就是把这些差异吸收掉向上只暴露IImageSource。// OpenCV Mat - WPF 位图注意 Step 可能大于 Width*Channels public bool TryWrite(IntPtr src, int srcStride, Int32Rect rect) { // 只支持整图或行对齐的连续区域越界直接拒绝避免 AccessViolation if (rect.X ! 0 || rect.Width ! Width) return false; if (rect.Y 0 || rect.Y rect.Height Height) return false; _bitmap.Lock(); try { // 目标基址按行偏移目标 stride 用 WriteableBitmap 自己的 BackBufferStride IntPtr dst _bitmap.BackBuffer rect.Y * _bitmap.BackBufferStride; // 逐行拷贝源行宽与目标行宽通常不相等不能一次 memcpy 到底 for (int y 0; y rect.Height; y) { Buffer.MemoryCopy( (byte*)src (rect.Y y) * srcStride, (byte*)dst y * _bitmap.BackBufferStride, _bitmap.BackBufferStride, Width * BytesPerPixel); } _bitmap.AddDirtyRect(rect); } finally { _bitmap.Unlock(); } return true; }这段代码里有两个容易被忽略的参数。Buffer.MemoryCopy的第三个参数是目标缓冲区可用字节数传BackBufferStride而不是Width * BytesPerPixel是为了让运行时能做边界检查虽然理论上行内拷贝不会越界但边界检查能在调试期抓住 stride 算错的问题。AddDirtyRect必须在Unlock之前调用传的是图像坐标系的矩形WPF 会自己换算成 DIP这一点很多人搞反写成屏幕坐标结果只在左上角刷新一小块。Halcon 那一路的适配要多一步HImage的三个通道是分离的平面转成 BGR 交错需要一次三路交织拷贝。如果算法层只做灰度处理最省事的做法是让 Halcon 输出HImage后直接取单通道避免交织开销。这个取舍要看你的检测流程我在做表面缺陷检测时全程灰度就没做 RGB 交织省下来的是实打实的毫秒数。3. 总体架构设计视图层、交互层、领域层的职责划分与数据流架构这件事说白了就是回答「一个鼠标点击事件从进来到画面重绘中间经过了谁」。我这套控件的数据流是单向的输入设备事件 → 交互控制器InteractionController→ 变换对象ViewTransform或图元模型RoiShape→ 标记脏区 → 下一帧统一重绘。整个过程里没有任何一个类会直接去调InvalidateVisual全部走一个RequestRender的入口这样帧率可控也方便加渲染统计。3.1 三个核心接口把「画什么」「怎么变」「怎么响应」分开三个接口分别是IRoiShape图元、IViewTransform变换、IInteractionTool工具。工具是这里最值得说的一层因为它把「当前是画矩形还是画多边形」这件事从控件里抽了出来。控件只认IInteractionTool鼠标按下就转给工具工具自己决定是创建图元、拖拽手柄还是拉橡皮筋。这样加一种新图元比如圆环扇形只需要新增一个工具类控件的switch不会膨胀。public interface IInteractionTool { // 工具被激活时调用可重置内部状态 void Activate(ImageControl host); void Deactivate(); // 返回 true 表示事件已被消费控件不再做默认处理 bool OnMouseDown(Point imagePoint, MouseButtonEventArgs e); bool OnMouseMove(Point imagePoint, MouseEventArgs e); bool OnMouseUp(Point imagePoint, MouseButtonEventArgs e); // 工具自己的预览层橡皮筋、辅助线由控件负责挂到视觉树 DrawingVisual? PreviewVisual { get; } }注意OnMouseDown收到的是imagePoint而不是屏幕点。这个设计是刻意的工具层永远不该知道缩放比例是多少它拿到的就是「图像上第几行第几列」所有和缩放相关的判断都在控件里完成。这一条约束如果守住后面加缩放、旋转、镜像都不会波及工具代码守不住就会出现「工具里也存了一份 scale」的翻车现场。PreviewVisual单独暴露而不是让工具自己往视觉树里塞是为了让控件统一管理 Z 序和清理时机。工具在Deactivate时不需要自己去移除视觉控件会在切换工具时统一清空预览层少一个释放资源的漏点。3.2 视图变换矩阵屏幕坐标与图像坐标的双向映射整个控件只有一个地方存缩放和平移就是一个 3×2 的仿射矩阵。WPF 的System.Windows.Media.Matrix正好是这个规格Invert()直接给出逆矩阵不用自己推公式。public sealed class ViewTransform { // 图像坐标 - 屏幕坐标DIP public Matrix ImageToScreen { get; private set; } Matrix.Identity; public double Scale ImageToScreen.M11; // 假设无旋转M11 M22 public Point Offset new(ImageToScreen.OffsetX, ImageToScreen.OffsetY); // 以屏幕上的某点为锚点缩放锚点下的图像内容保持不动 public void ZoomAt(Point screenAnchor, double factor) { double newScale Math.Clamp(Scale * factor, MinScale, MaxScale); if (Math.Abs(newScale - Scale) 1e-9) return; // 先求锚点对应的图像坐标缩放后再反推需要的平移量 Point imageAnchor ScreenToImage(screenAnchor); ImageToScreen new Matrix(newScale, 0, 0, newScale, 0, 0); Point newScreen ImageToScreen.Transform(imageAnchor); ImageToScreen new Matrix( newScale, 0, 0, newScale, screenAnchor.X - newScreen.X, screenAnchor.Y - newScreen.Y); } public Point ScreenToImage(Point p) { Matrix inv ImageToScreen; inv.Invert(); // 矩阵不可逆会抛 InvalidOperationException return inv.Transform(p); } }ZoomAt是整个交互体验的核心。很多人写滚轮缩放是直接改Scale再乘一个固定平移结果是图越缩越往右下角跑用起来很别扭。正确做法就是上面这三步锚点先反算到图像坐标重建矩阵再把锚点重新贴回原来的屏幕位置。这样光标下面永远是同一块像素缩放才有「手抓住图」的感觉。Math.Clamp的上下限建议按图像尺寸动态算下限取「整图刚好铺满视口」的 0.1 倍上限取 32 倍。上限不设会有浮点精度问题缩放到几百倍之后float精度不够ROI 手柄会开始抖动下限不设则会出现图像缩成一个点、用户找不回来的情况这个体验坑在学生答辩时特别容易被问到。ScreenToImage每次调用都Invert()一次看着浪费但这个矩阵的逆运算量极小两次乘法一次除法实测一秒钟几万次调用也感觉不到。如果确实要抠这点性能可以缓存逆矩阵在矩阵变更时置脏但没必要为它引入一套缓存失效逻辑得不偿失。3.3 命中测试与手柄布局为什么手柄必须画在屏幕空间ROI 的八个缩放手柄画在哪是个容易做错的决定。如果手柄画在图像空间也就是跟着缩放一起放大那么图缩到 10% 的时候手柄会小到 2 个像素根本点不中图放到 800% 的时候手柄又会变成一个大方块难看且挡视线。所以手柄的尺寸必须固定在屏幕空间通常是 7×7 个 DIP。但命中测试又必须在图像空间做因为 ROI 的顶点坐标是图像坐标。这就产生一个混用点手柄中心点从图像坐标变换到屏幕坐标命中半径用屏幕像素算。// 手柄命中把手柄中心投到屏幕再和鼠标屏幕点比距离 public int HitTestHandle(Point screenPoint, ViewTransform vt, double radiusDip 6) { double r2 radiusDip * radiusDip; for (int i 0; i Handles.Count; i) { Point sp vt.ImageToScreen.Transform(Handles[i]); double dx sp.X - screenPoint.X; double dy sp.Y - screenPoint.Y; if (dx * dx dy * dy r2) return i; } return -1; }用平方距离而不是Math.Sqrt是这类命中测试的常规写法能省掉开方。radiusDip默认给 6 而不是 3.5手柄半宽是因为鼠标不可能精确点在中心命中区比视觉区大一圈手感会明显好很多。这就是典型的「实现上多写三行、用起来舒服一倍」的地方。还有个顺序问题手柄的命中优先级必须高于图元本体。如果你先判断「点是否落在矩形内部」那么拖动右下角手柄时程序会认为你在拖整个矩形改成移动而不是缩放。我在InteractionController里的固定顺序是手柄 → 边中点 → 图元本体 → 空白。这个顺序一旦定下来就不要改所有工具共用同一套。3.4 渲染调度与脏区别让每一次鼠标移动都触发整图重绘鼠标拖动 ROI 的时候MouseMove一秒钟能来 100 多次。如果每次都InvalidateVisual并且重画底图底图那几十兆的位图重绘会把 CPU 吃满帧率掉到个位数。这里的做法是分离两层刷新底图只在图像源更新时刷ROI 层在交互时刷而且 ROI 层的刷新要合并到渲染帧里。private bool _renderPending; // 所有需要重绘的地方都走这里不直接调 InvalidateVisual public void RequestRender() { if (_renderPending) return; _renderPending true; // 挂到渲染帧回调一帧内的多次请求只会真正执行一次 CompositionTarget.Rendering OnRendering; } private void OnRendering(object? sender, EventArgs e) { CompositionTarget.Rendering - OnRendering; // 先解绑避免重复触发 _renderPending false; // 只重画 ROI 层底图位图没有变化就不动它 using var dc _roiVisual.RenderOpen(); foreach (var roi in _roiLayer.VisibleShapes) roi.Draw(dc, ViewTransform); }CompositionTarget.Rendering是 WPF 里做自绘控件的标准手段它在每次合成前触发天然和显示器刷新同步比DispatcherTimer的 16ms 定时更稳。注意必须「先解绑再执行」否则同一帧里RequestRender被调多次会重复挂载回调越滚越多最后内存泄漏——这个 bug 隐蔽性很强表现是程序跑十几分钟后越来越卡用性能分析器才看得出来。脏区这块WriteableBitmap的AddDirtyRect是有效手段但只对底图有用。ROI 层是矢量DrawingVisualWPF 自己会做无效区域合并不需要你操心。真正需要操心的是 ROI 数量几百个多边形 ROI 同时可见时每帧RenderOpen遍历一次绘制也不是免费的。我的处理是给每个RoiShape加一个IsVisible和IsSelected标志未选中且不在编辑状态的图元走一套简化的绘制路径不画手柄、不画顶点、用更低的描边精度。4. ROI 绘制与编辑实现六类图元的构造、拖拽与吸附图元层是整个控件里代码量最大的一部分也是最容易写成意大利面的地方。控制复杂度的关键是把「几何计算」和「绘制」「交互」彻底分开几何计算写在一组纯函数里输入输出都是Point不碰DrawingContext这样单元测试好写坐标算错了也容易定位。4.1 图元基类与统一生命周期所有 ROI 图元都从一个抽象基类派生基类负责三件事命名与图层属性、顶点集合的读写、序列化。派生类只实现几何相关的三个方法。public abstract class RoiShape { public string Name { get; set; } ROI; public Color Stroke { get; set; } Colors.Lime; public bool IsVisible { get; set; } true; public bool IsLocked { get; set; } // 锁定后不参与命中测试 // 图元在图像坐标系下的顶点顺序即绘制顺序 public abstract IReadOnlyListPoint Vertices { get; } // 手柄位置图像坐标矩形给8个多边形给顶点本身 public abstract IReadOnlyListPoint GetHandles(); // 判断图像坐标点是否落在图元内部含边线容差单位是图像像素 public abstract bool Contains(Point imagePoint, double tolerance); // 绘制dc 已由外层做好屏幕坐标变换 public abstract void Draw(DrawingContext dc, ViewTransform vt); // 拖动某个手柄handleIndex 来自 GetHandles 的下标 public abstract void MoveHandle(int handleIndex, Point imagePoint); // 平移整个图元 public virtual void Translate(Vector delta) { for (int i 0; i Vertices.Count; i) _mutable[i] delta; } }Contains的tolerance参数容易被忽略。图像缩放得很小时ROI 的边线在屏幕上只有一两个像素宽用户点边线基本点不中必须给一个容差把边线「加粗」成可点击区域。这个容差应该是「屏幕 5 像素换算成图像像素」也就是5 / scale由调用方算好传进来而不是图元自己去读缩放比例——保持图元对视图不可见是前面定下的规矩。Translate做成虚方法而不是抽象方法是因为多边形和图元容器一个框里套多个 ROI 的组的平移逻辑不一样后者要递归。默认实现直接改顶点数组就够了派生类需要特殊处理时再重写。4.2 矩形与旋转矩形手柄布局与拖拽的符号问题普通矩形只有四个角加四条边中点共 8 个手柄拖拽逻辑很直观拖左上角改X和Y的同时改Width和Height要处理「拖过头」导致宽高变负的情况通常的做法是做一次归一化把负宽高翻转成正值并交换起止点。这段代码几乎所有教程都有不展开。真正费神的是旋转矩形。它的手柄位置不再是轴对齐的而是要先算出局部坐标系下的八个点再用旋转矩阵变换到图像坐标。// 旋转矩形中心 半宽半高 角度弧度算八个手柄 public override IReadOnlyListPoint GetHandles() { double cos Math.Cos(Angle), sin Math.Sin(Angle); // 局部坐标下的手柄偏移顺序四角 四边中点 var local new[] { new Vector(-HalfW, -HalfH), new Vector( HalfW, -HalfH), new Vector( HalfW, HalfH), new Vector(-HalfW, HalfH), new Vector(0, -HalfH), new Vector(HalfW, 0), new Vector(0, HalfH), new Vector(-HalfW, 0) }; var result new Point[local.Length]; for (int i 0; i local.Length; i) { // 先旋转再平移到中心 result[i] new Point( Center.X local[i].X * cos - local[i].Y * sin, Center.Y local[i].X * sin local[i].Y * cos); } return result; }Angle用弧度而不是角度是跟 WPF 的RotateTransform保持一致减少换算错误。手柄顺序「四角在前、边中点在后」在HitTestHandle里会带来一个优先级红利角手柄的命中半径可以比边中点大 2 个 DIP因为角上同时改两个维度用户更常拖它。MoveHandle的实现要注意旋转矩形的「反旋转」步骤鼠标给的是图像坐标必须先减去中心、乘上-Angle的旋转矩阵转回局部坐标再在局部坐标里改宽高最后把中心按新的宽高补偿平移。如果忘了补偿拖右下角的时候整个矩形会往左上跑这是旋转矩形最经典的翻车点我第一次写的时候调了整整一个下午。4.3 多边形与自由绘制采样、抽稀与闭合判定多边形 ROI 有两种产生方式逐点点击和按住拖拽自由画。逐点点击好办麻烦的是自由画——鼠标一秒来 100 个点直接全部存下来会有几百个顶点后续编辑时手柄密得根本点不中算法层拿去做多边形填充也慢。我的处理是三步采样降频、道格拉斯-普克抽稀、闭合判定。采样降频就是加一个最小间距判断新点离上一个点不到 3 个屏幕像素就丢掉注意这里的阈值要除以scale才能变成图像像素。抽稀用 Douglas-Peucker容差取2 / scale能把一条手画的弧线压到十几个顶点。// Douglas-Peucker 抽稀points 为图像坐标epsilon 单位也是图像像素 private static ListPoint Simplify(ListPoint points, double epsilon) { if (points.Count 3) return points; double maxDist 0; int index 0; Point a points[0], b points[^1]; // 找离首尾连线最远的点 for (int i 1; i points.Count - 1; i) { double d PerpendicularDistance(points[i], a, b); if (d maxDist) { maxDist d; index i; } } // 超过容差就分段递归否则整段用直线代替 if (maxDist epsilon) { var left Simplify(points.Take(index 1).ToList(), epsilon); var right Simplify(points.Skip(index).ToList(), epsilon); left.RemoveAt(left.Count - 1); left.AddRange(right); return left; } return new ListPoint { a, b }; }递归实现代码短但深递归在顶点极多时可能爆栈实际项目里我会改成显式栈的迭代版本。PerpendicularDistance要处理首尾点重合的退化情况否则除以零会返回NaNNaN参与比较永远是false抽稀会静默失效——你只会发现顶点没被简化却找不到原因。闭合判定分两种策略距离首点小于 8 个屏幕像素就自动闭合或者用户双击强制闭合。我倾向于两个都留因为手绘时既有「画回起点」的习惯也有「随手一停双击」的习惯。闭合之后立刻做一次自相交检测发现自相交就提示用户重画比把错误的多边形送进算法层再报错要友好得多。4.4 编辑操作栈撤销重做与序列化ROI 编辑一定要有撤销不然用户拖歪一个角就得删了重画体验极差。简单的做法是每次操作前把整个 ROI 列表深拷贝一份压栈实现五分钟搞定但内存吃得厉害——几十个多边形 ROI 拷一次就是几百 KB撤销栈存 50 步就二三十兆。我的做法是命令模式每个操作只记录「改了谁、改前是什么、改后是什么」public sealed class MoveHandleCommand : IUndoableCommand { private readonly RoiShape _shape; private readonly int _handleIndex; private readonly Point _before; private Point _after; public void Execute(Point newPosition) { _after newPosition; _shape.MoveHandle(_handleIndex, newPosition); } public void Undo() _shape.MoveHandle(_handleIndex, _before); public void Redo() _shape.MoveHandle(_handleIndex, _after); }关键点是Execute里只存最终位置不存中间的每一次MouseMove。拖拽过程中每帧都会改图元但只有MouseUp那一刻才把一条命令压栈。这样一次拖拽只占一条撤销记录也符合用户的直觉撤销一次应该回到拖拽前而不是回到上一帧。合并策略是在MouseDown时创建命令对象MouseMove只更新_after并直接改图元MouseUp时压栈。这个「延迟压栈」的写法值得单独记一下很多实现是在MouseMove里就压栈结果用户撤销十次才退回原位。序列化用System.Text.Json图元用一个带Type判别字段的多态结构反序列化时按Type分发到具体类。坐标存成[x1, y1, x2, y2, ...]的扁平数组而不是对象数组文件能小一半读写也快。浮点要保留 4 位小数太多位会让文件膨胀且没有意义——图像坐标精度到 0.1 像素早就超过相机分辨率了。5. 避坑与排查坐标系、DPI、内存与交互冲突的五个高频翻车点这一章列的都是我和同事在真实项目里踩过的坑共同特点是「现象看起来像渲染 bug其实是坐标或生命周期问题」。如果你正在调这类控件先对照这五条排查能省掉大量时间。5.1 ROI 在高 DPI 屏幕上整体偏移现象在 100% 缩放的机器上一切正常换到 125% 或 150% 的笔记本上ROI 框整体往左上偏一点越往右下偏得越多偏移量跟坐标值成正比。原因WPF 的鼠标事件给的是 DIP设备无关单位而WriteableBitmap的像素缓冲是按物理像素算的。当图像以 1:1 显示时你把 DIP 直接当像素用两者差了一个dpiScale因子。缩放比例是 1.25 时屏幕坐标 400 DIP 对应 500 物理像素ROI 就偏了 100 像素。解决在控件加载时读一次 DPI 缩放所有涉及「DIP 与物理像素换算」的地方统一乘这个因子。更彻底的做法是让ViewTransform内部只用 DIP图像坐标到 DIP 的换算里显式带上dpiScale// 在 OnDpiChanged 或 Loaded 里刷新不要每次鼠标事件都去读 private double _dpiScale 1.0; protected override void OnDpiChanged(DpiScale oldDpi, DpiScale newDpi) { base.OnDpiChanged(oldDpi, newDpi); _dpiScale newDpi.DpiScaleX; // DPI 变了必须重算适应窗口的缩放否则图会显示不全 FitToWindow(); RequestRender(); }OnDpiChanged这个重写点需要 .NET Core 3.0 以上或 .NET 5老版本框架上要自己在Loaded或WM_DPICHANGED消息里处理。这也是我建议新项目直接上 .NET 6/8 的原因之一——WPF 的 DPI 支持在新版本里完善了很多。5.2 滚轮缩放后图像「跑掉」现象缩放时图像往右下角飘或者缩放中心不在光标而在控件中心用起来像在拖一张不听话的地图。原因只改了Scale没改平移或者用了RenderTransform的ScaleTransform但CenterX/CenterY设成了 0。前者是数学没做闭环后者是把变换交给 WPF 而没自己做锚点计算。解决按 3.2 节的三步法重写ZoomAt。如果确实想用ScaleTransform必须同时设置CenterX、CenterY为光标相对控件的坐标但这样做的问题是它跟你的ImageToScreen矩阵会打架两套变换叠在一起调试起来非常痛苦。我一般会禁用RenderTransform所有变换只走矩阵。5.3 大图刷新时界面卡顿与内存暴涨现象切换图像或者高频取流时界面卡住几百毫秒任务管理器里内存一路涨跑几分钟就上 GB。原因通常有两个。一是每次都new WriteableBitmap旧对象等 GC大图一秒换十次就是几百兆的分配压力二是WritePixels传的是整图明明只有一小块在变。解决位图对象复用尺寸不变时只WritePixels不重建用脏区矩形限制写入范围如果图像源尺寸会变做一次尺寸判断再决定是否重建。另外WriteableBitmap默认是Bgra32如果你的源是灰度图转成Bgra32会让内存翻四倍改成Gray8加调色板能省很多。灰度图用Gray8时要注意FormatConvertedBitmap的开销能直接喂原始字节就直接喂。5.4 图元命中测试永远点不中现象ROI 画出来了样式也对但鼠标点上去毫无反应或者要点偏十几像素才有反应。原因命中测试里把屏幕坐标直接和图像坐标比较了。图缩放 0.5 倍时屏幕点 (200,200) 对应的图像点是 (400,400)你拿 200 去比 400 当然不中。解决统一在 3.3 节的约定下写——InteractionController收到鼠标事件的第一件事就是ScreenToImage之后所有坐标都是图像坐标只有手柄命中测试反过来用手柄的图像坐标ImageToScreen到屏幕再比。这两种「方向」必须在对的地方用写反了就是点不中。建议在代码里加一行断言检查传入Contains的点是否在图像边界内能快速暴露这个错误。5.5 手柄大小随缩放变化现象图放大时手柄变成大方块缩小时手柄小到看不见、点不中。原因手柄的绘制坐标是从图像坐标直接算的没有做尺寸归一化。解决手柄的「中心点」用图像坐标变换到屏幕但「大小」固定为屏幕 DIP比如 7×7绘制时用屏幕坐标画。具体做法是在Draw里先vt.ImageToScreen.Transform(handle)得到屏幕点再以这个点为中心画一个固定尺寸的矩形。同时注意描边宽度也要固定为 1 DIP否则线宽会跟着缩放变成 10 像素粗非常难看。6. 验收与答辩怎么证明这个控件「真的能用」答辩现场最怕的不是功能少而是「老师随手一操作就出问题」。所以验收要自己先做一遍按操作路径走而不是按代码模块走。我一般会准备一张验收表逐项过过不了的当场改别等到现场。验收项操作方法通过标准坐标一致性在 1:1、200%、20% 三档缩放下各点一次图像上的同一个特征点状态栏显示的图像坐标三次一致误差不超过 1 像素缩放锚点光标停在图像某个角上滚动滚轮该角在屏幕上位置不动DPI 兼容把系统缩放改成 150% 重启程序ROI 与图像特征仍然对齐无整体偏移手柄可用性缩放到 10% 和 800% 各拖一次角手柄两种缩放下手柄都能点中尺寸视觉上一致撤销栈连续拖拽 20 次后连按 20 次撤销回到初始状态无残留、无错位序列化往返存盘再读盘所有 ROI 位置、颜色、名称与存盘前一致大图性能加载 5000×4000 灰度图拖动 ROI帧率不低于 30fps无卡顿感答辩讲解的顺序也有讲究。不要一上来就讲架构先演示三个动作滚轮缩放、拖一个矩形 ROI、撤销。这三个动作覆盖了变换、图元、命令栈三条主线评委一看就知道东西是活的。然后再翻到代码讲ViewTransform那一个类重点讲ZoomAt的三步推导——这是整个项目里唯一有数学含量的地方讲清楚了就能撑住「设计」两个字。演示脚本我一般会写成这样三分钟一遍练熟# 演示前自检避免现场翻车 1. 确认程序默认加载一张 4K 测试图不是空白 2. 确认「适应窗口」在启动时自动执行一次 3. 确认状态栏显示 图像坐标 / 缩放倍数 / DPI 三个值 4. 确认撤销栈初始为空按钮置灰 5. 确认关掉调试输出窗口避免异常信息弹出这张清单看着琐碎但每一条都对应一次真实事故加载空白图是因为图像源初始化顺序写反了忘记适应窗口是因为Loaded事件里没算视口尺寸状态栏不显示 DPI 是因为答辩时被问到「你怎么保证跨屏一致」答不上来。把这些做成自检项比临时抱佛脚管用。还有个答辩常被问到的点为什么不直接用 Halcon 的HSmartWindowControl。回答的思路是承认它能用但指出三层问题——它绑定特定算法库换成 OpenCV 或自研算法就得换控件它的 ROI 交互是封装好的黑匣子要定制吸附、对齐、多选这类业务逻辑改不动以及部署时要带一整套运行时依赖。自己写这套东西的价值不在「重复造轮子」而在于把交互层和算法层解耦让 ROI 数据能以纯坐标的形式送进任意算法后端。这个回答既解释了动机也展示了架构思考比单纯说「老师要求自己写」强得多。从那以后我每次交付带交互的控件都强制自己先把验收表走一遍再演示哪怕时间再紧也不跳。因为真正让人难堪的从来不是功能没做完而是演示到一半光标点不中手柄。希望帮到你。本文还有配套的精品资源点击获取
简介面向 C# 与 WPF 开发者、机器视觉方向学习者的图像控件与 ROI 管理示例工程目标是在 WPF 中复刻 Halcon HSmartWindowControl 的交互体验加载并显示图像在图像上绘制矩形、圆形等 ROI并通过鼠标点击与拖动完成 ROI 的添加、删除和修改。工程以 RoiDisplay 解决方案组织包含 RoiDisplayWpf 主程序、TestWindowWpf 测试窗口以及 RoiImplementation、Helper、Themes 等模块接口划分清晰便于后续接入 OpenCV 实现自动检测与模板匹配等扩展功能。压缩包共 86 个文件以 31 个 C# 源码、3 个 XAML 界面文件、2 个 csproj 项目文件与 sln 解决方案为主辅以 dll、config、resx 等依赖与配置项整体约 319KB。目前已有 412 人学习下载适合需要参考控件封装思路、ROI 数据结构设计与交互事件处理的开发者对照阅读。1. 从「控件不像控件」说起为什么要自己写一个图像显示与 ROI 交互控件用 WPF 做机器视觉上位机第一版几乎都会这么写一个Image显示位图上面盖一个CanvasCanvas里放几个Rectangle当 ROI。跑通 demo 只用半天等到要加滚轮缩放、按住空格拖拽平移、拖动 ROI 手柄改尺寸问题就全冒出来了——ROI 框跟着鼠标飘、手柄在 150% 缩放的屏幕上点不中、几千万像素的大图一刷新就卡成幻灯片。根子不在画得对不对而在于屏幕坐标、图像坐标、ROI 逻辑坐标这三套坐标系没有单一可信的换算入口谁都随手乘一个 scale最后就变成了玄学。这套方案要干的事就是把这三层拆开用 C# 写一个能承载 Halcon 与 OpenCV 两种图像源的自定义 WPF 图像控件把 ROI 的绘制、编辑、管理与序列化做成一套可复用的基础设施。它适合正在做视觉检测毕设、课设或者要给设备写一个能交付的取图界面的开发者。2. 需求拆解与选型三层渲染管线与自定义控件的边界动手之前先把「控件到底该管到哪一步」划清楚否则写着写着就会变成一个什么都想干的巨型UserControl。我的划分方式是三层底图层只管把一块内存按正确的缩放和平移画出来ROI 覆盖层只管矢量图元的绘制与命中测试交互层只管把鼠标、键盘、触控事件翻译成对前两层的指令。三层之间不互相new全部通过接口和变换对象通信。这样做的直接好处是底图从WriteableBitmap换成 D3D 共享表面时ROI 那一层一行都不用改。2.1 交互需求清单从「能看」到「能改」的五个层次很多人写控件是先写代码再想需求结果做到一半发现少了个功能架构撑不住只能推倒。我一般会先把需求按能力分层列出来再决定每一层放在哪个类里。图像控件的需求大致能分成五层越往上耦合越重层级能力典型操作归属L1 显示把图正确画出来适应窗口、1:1 显示、灰度/RGB 切换底图层L2 导航在图像里移动视野滚轮以光标为中心缩放、空格左键平移、双击复位交互层L3 创建产生 ROI 图元拖框、拉圆、逐点打多边形、十字取点交互层 ROI 层L4 编辑修改已有 ROI选中、八手柄缩放、旋转、顶点增删、边中点插入ROI 层L5 管理组织与持久化图层顺序、可见性、锁定、命名、序列化、撤销重做领域层这张表的价值在于L1、L2 属于「视图变换」可以用一个 3×2 矩阵全部表达L3 到 L5 属于「图元模型」跟缩放比例无关。把这两件事混在一个类里是后面所有坐标 bug 的源头。提示如果你的项目只需要框选区域送去算法处理L4 里的旋转和顶点编辑可以砍掉能省掉至少三分之一的工作量。先砍需求再谈架构。2.2 渲染选型WriteableBitmap、D3DImage 与 SkiaSharp 的取舍底图怎么画是这个控件第一个必须拍板的决定。常见的四条路各有各的脾气方案刷新开销跨线程实现复杂度适用场景ImageBitmapSource每次换图都要新建对象差低静态图浏览WriteableBitmap中WritePixels走 UI 线程一般低中小图、低频刷新D3DImage低GPU 直通好高高帧率取流、大图SkiaSharpSKElement低好中需要复杂矢量叠加我的默认选择是WriteableBitmap理由是它跟 WPF 的布局、命中测试、RenderTransform天然兼容代码量最小绝大多数课程设计和中小型检测设备够用。只有当图像宽度超过 4000 像素、刷新率要求 30fps 以上时才值得上D3DImage——它需要自己管理 D3D9 共享表面、前后台缓冲和Lock/Unlock调试成本不低属于典型的「性能换复杂度」。至于 SkiaSharp好处是底图和 ROI 能在同一个绘制上下文里画完省掉一层视觉树坏处是失去 WPF 原生的HitTestCore、装饰器和无障碍支持鼠标交互得全部手写。选型一旦定了就要把它藏到接口后面。我在项目里通常定义这么一个图像源抽象让两种内存布局Halcon 的交错指针和 OpenCV 的连续Mat.Data都收敛到同一个UpdatePixels调用上public interface IImageSource { int Width { get; } int Height { get; } // 每像素字节数灰度1、Bgr24为3、Bgra32为4 int Stride { get; } PixelFormat Format { get; } // 把外部内存整块写入目标位图区域rect 为脏区图像坐标 // 返回 false 表示源尺寸已变化调用方需要重建后端缓冲 bool TryWrite(IntPtr src, int srcStride, Int32Rect rect); }TryWrite的rect参数是为脏区刷新留的口子取流时往往只有一小块区域在变整图重写既浪费带宽也拉高 GC。srcStride单独传入而不是用Stride是因为 Halcon 的HImage每行字节数可能做过对齐跟宽度乘通道数对不上这个坑后面第 5 章还会提。返回bool而不是抛异常是为了让上层在分辨率切换时能走「重建缓冲」的分支而不是靠捕获异常做流程控制。2.3 控件基类FrameworkElement、Control 还是 UserControlWPF 里写自定义控件有三条路选错了后面很难受。UserControl本质是一个带 XAML 的组合写起来最快但它是封闭的——别人没法用Template换皮肤你也很难在它内部再插一层VisualCollection。Control有Template、支持主题样式代价是要写Generic.xaml、处理TemplatePart对一个内部使用的图像控件来说太重。我最后选的是FrameworkElement直接派生重写OnRender画底图再用一个受保护的VisualCollection挂 ROI 层的DrawingVisual。理由很实际图像控件不需要内容模型不需要控件模板它需要的是对视觉树和命中测试的完全控制权。FrameworkElement默认的HitTestCore返回整个矩形正好适合做「点击空白处取消选中」这种逻辑而 ROI 的命中测试我在OnMouseLeftButtonDown里自己做不走 WPF 的命中体系因为 ROI 是逻辑对象不是UIElement这样它才能被序列化、被算法层直接引用。VisualCollection这一层的用法要留意顺序底图DrawingVisual放第 0 个ROI 放第 1 个橡皮筋预览放第 2 个。AddVisualChild和AddLogicalChild都要调用否则视觉能画出来但逻辑树断链DataContext继承会失效。这个细节在官方文档里写得不显眼我第一次写的时候只加了视觉没加逻辑绑定的ViewModel一直是null查了两个小时。2.4 图像源适配Halcon 与 OpenCV 两种内存布局的统一真正的项目里图像大概率不是从文件读的而是从相机 SDK、Halcon 的HObject或者 OpenCV 的Mat转过来的。这三者的内存布局差异比想象中大Halcon 的HImage通过GetImagePointer1拿到的是行首指针加行宽通道是分开的三个平面OpenCV 的Mat默认是 BGR 交错Step可能大于Width * 3SIMD 对齐。适配层的职责就是把这些差异吸收掉向上只暴露IImageSource。// OpenCV Mat - WPF 位图注意 Step 可能大于 Width*Channels public bool TryWrite(IntPtr src, int srcStride, Int32Rect rect) { // 只支持整图或行对齐的连续区域越界直接拒绝避免 AccessViolation if (rect.X ! 0 || rect.Width ! Width) return false; if (rect.Y 0 || rect.Y rect.Height Height) return false; _bitmap.Lock(); try { // 目标基址按行偏移目标 stride 用 WriteableBitmap 自己的 BackBufferStride IntPtr dst _bitmap.BackBuffer rect.Y * _bitmap.BackBufferStride; // 逐行拷贝源行宽与目标行宽通常不相等不能一次 memcpy 到底 for (int y 0; y rect.Height; y) { Buffer.MemoryCopy( (byte*)src (rect.Y y) * srcStride, (byte*)dst y * _bitmap.BackBufferStride, _bitmap.BackBufferStride, Width * BytesPerPixel); } _bitmap.AddDirtyRect(rect); } finally { _bitmap.Unlock(); } return true; }这段代码里有两个容易被忽略的参数。Buffer.MemoryCopy的第三个参数是目标缓冲区可用字节数传BackBufferStride而不是Width * BytesPerPixel是为了让运行时能做边界检查虽然理论上行内拷贝不会越界但边界检查能在调试期抓住 stride 算错的问题。AddDirtyRect必须在Unlock之前调用传的是图像坐标系的矩形WPF 会自己换算成 DIP这一点很多人搞反写成屏幕坐标结果只在左上角刷新一小块。Halcon 那一路的适配要多一步HImage的三个通道是分离的平面转成 BGR 交错需要一次三路交织拷贝。如果算法层只做灰度处理最省事的做法是让 Halcon 输出HImage后直接取单通道避免交织开销。这个取舍要看你的检测流程我在做表面缺陷检测时全程灰度就没做 RGB 交织省下来的是实打实的毫秒数。3. 总体架构设计视图层、交互层、领域层的职责划分与数据流架构这件事说白了就是回答「一个鼠标点击事件从进来到画面重绘中间经过了谁」。我这套控件的数据流是单向的输入设备事件 → 交互控制器InteractionController→ 变换对象ViewTransform或图元模型RoiShape→ 标记脏区 → 下一帧统一重绘。整个过程里没有任何一个类会直接去调InvalidateVisual全部走一个RequestRender的入口这样帧率可控也方便加渲染统计。3.1 三个核心接口把「画什么」「怎么变」「怎么响应」分开三个接口分别是IRoiShape图元、IViewTransform变换、IInteractionTool工具。工具是这里最值得说的一层因为它把「当前是画矩形还是画多边形」这件事从控件里抽了出来。控件只认IInteractionTool鼠标按下就转给工具工具自己决定是创建图元、拖拽手柄还是拉橡皮筋。这样加一种新图元比如圆环扇形只需要新增一个工具类控件的switch不会膨胀。public interface IInteractionTool { // 工具被激活时调用可重置内部状态 void Activate(ImageControl host); void Deactivate(); // 返回 true 表示事件已被消费控件不再做默认处理 bool OnMouseDown(Point imagePoint, MouseButtonEventArgs e); bool OnMouseMove(Point imagePoint, MouseEventArgs e); bool OnMouseUp(Point imagePoint, MouseButtonEventArgs e); // 工具自己的预览层橡皮筋、辅助线由控件负责挂到视觉树 DrawingVisual? PreviewVisual { get; } }注意OnMouseDown收到的是imagePoint而不是屏幕点。这个设计是刻意的工具层永远不该知道缩放比例是多少它拿到的就是「图像上第几行第几列」所有和缩放相关的判断都在控件里完成。这一条约束如果守住后面加缩放、旋转、镜像都不会波及工具代码守不住就会出现「工具里也存了一份 scale」的翻车现场。PreviewVisual单独暴露而不是让工具自己往视觉树里塞是为了让控件统一管理 Z 序和清理时机。工具在Deactivate时不需要自己去移除视觉控件会在切换工具时统一清空预览层少一个释放资源的漏点。3.2 视图变换矩阵屏幕坐标与图像坐标的双向映射整个控件只有一个地方存缩放和平移就是一个 3×2 的仿射矩阵。WPF 的System.Windows.Media.Matrix正好是这个规格Invert()直接给出逆矩阵不用自己推公式。public sealed class ViewTransform { // 图像坐标 - 屏幕坐标DIP public Matrix ImageToScreen { get; private set; } Matrix.Identity; public double Scale ImageToScreen.M11; // 假设无旋转M11 M22 public Point Offset new(ImageToScreen.OffsetX, ImageToScreen.OffsetY); // 以屏幕上的某点为锚点缩放锚点下的图像内容保持不动 public void ZoomAt(Point screenAnchor, double factor) { double newScale Math.Clamp(Scale * factor, MinScale, MaxScale); if (Math.Abs(newScale - Scale) 1e-9) return; // 先求锚点对应的图像坐标缩放后再反推需要的平移量 Point imageAnchor ScreenToImage(screenAnchor); ImageToScreen new Matrix(newScale, 0, 0, newScale, 0, 0); Point newScreen ImageToScreen.Transform(imageAnchor); ImageToScreen new Matrix( newScale, 0, 0, newScale, screenAnchor.X - newScreen.X, screenAnchor.Y - newScreen.Y); } public Point ScreenToImage(Point p) { Matrix inv ImageToScreen; inv.Invert(); // 矩阵不可逆会抛 InvalidOperationException return inv.Transform(p); } }ZoomAt是整个交互体验的核心。很多人写滚轮缩放是直接改Scale再乘一个固定平移结果是图越缩越往右下角跑用起来很别扭。正确做法就是上面这三步锚点先反算到图像坐标重建矩阵再把锚点重新贴回原来的屏幕位置。这样光标下面永远是同一块像素缩放才有「手抓住图」的感觉。Math.Clamp的上下限建议按图像尺寸动态算下限取「整图刚好铺满视口」的 0.1 倍上限取 32 倍。上限不设会有浮点精度问题缩放到几百倍之后float精度不够ROI 手柄会开始抖动下限不设则会出现图像缩成一个点、用户找不回来的情况这个体验坑在学生答辩时特别容易被问到。ScreenToImage每次调用都Invert()一次看着浪费但这个矩阵的逆运算量极小两次乘法一次除法实测一秒钟几万次调用也感觉不到。如果确实要抠这点性能可以缓存逆矩阵在矩阵变更时置脏但没必要为它引入一套缓存失效逻辑得不偿失。3.3 命中测试与手柄布局为什么手柄必须画在屏幕空间ROI 的八个缩放手柄画在哪是个容易做错的决定。如果手柄画在图像空间也就是跟着缩放一起放大那么图缩到 10% 的时候手柄会小到 2 个像素根本点不中图放到 800% 的时候手柄又会变成一个大方块难看且挡视线。所以手柄的尺寸必须固定在屏幕空间通常是 7×7 个 DIP。但命中测试又必须在图像空间做因为 ROI 的顶点坐标是图像坐标。这就产生一个混用点手柄中心点从图像坐标变换到屏幕坐标命中半径用屏幕像素算。// 手柄命中把手柄中心投到屏幕再和鼠标屏幕点比距离 public int HitTestHandle(Point screenPoint, ViewTransform vt, double radiusDip 6) { double r2 radiusDip * radiusDip; for (int i 0; i Handles.Count; i) { Point sp vt.ImageToScreen.Transform(Handles[i]); double dx sp.X - screenPoint.X; double dy sp.Y - screenPoint.Y; if (dx * dx dy * dy r2) return i; } return -1; }用平方距离而不是Math.Sqrt是这类命中测试的常规写法能省掉开方。radiusDip默认给 6 而不是 3.5手柄半宽是因为鼠标不可能精确点在中心命中区比视觉区大一圈手感会明显好很多。这就是典型的「实现上多写三行、用起来舒服一倍」的地方。还有个顺序问题手柄的命中优先级必须高于图元本体。如果你先判断「点是否落在矩形内部」那么拖动右下角手柄时程序会认为你在拖整个矩形改成移动而不是缩放。我在InteractionController里的固定顺序是手柄 → 边中点 → 图元本体 → 空白。这个顺序一旦定下来就不要改所有工具共用同一套。3.4 渲染调度与脏区别让每一次鼠标移动都触发整图重绘鼠标拖动 ROI 的时候MouseMove一秒钟能来 100 多次。如果每次都InvalidateVisual并且重画底图底图那几十兆的位图重绘会把 CPU 吃满帧率掉到个位数。这里的做法是分离两层刷新底图只在图像源更新时刷ROI 层在交互时刷而且 ROI 层的刷新要合并到渲染帧里。private bool _renderPending; // 所有需要重绘的地方都走这里不直接调 InvalidateVisual public void RequestRender() { if (_renderPending) return; _renderPending true; // 挂到渲染帧回调一帧内的多次请求只会真正执行一次 CompositionTarget.Rendering OnRendering; } private void OnRendering(object? sender, EventArgs e) { CompositionTarget.Rendering - OnRendering; // 先解绑避免重复触发 _renderPending false; // 只重画 ROI 层底图位图没有变化就不动它 using var dc _roiVisual.RenderOpen(); foreach (var roi in _roiLayer.VisibleShapes) roi.Draw(dc, ViewTransform); }CompositionTarget.Rendering是 WPF 里做自绘控件的标准手段它在每次合成前触发天然和显示器刷新同步比DispatcherTimer的 16ms 定时更稳。注意必须「先解绑再执行」否则同一帧里RequestRender被调多次会重复挂载回调越滚越多最后内存泄漏——这个 bug 隐蔽性很强表现是程序跑十几分钟后越来越卡用性能分析器才看得出来。脏区这块WriteableBitmap的AddDirtyRect是有效手段但只对底图有用。ROI 层是矢量DrawingVisualWPF 自己会做无效区域合并不需要你操心。真正需要操心的是 ROI 数量几百个多边形 ROI 同时可见时每帧RenderOpen遍历一次绘制也不是免费的。我的处理是给每个RoiShape加一个IsVisible和IsSelected标志未选中且不在编辑状态的图元走一套简化的绘制路径不画手柄、不画顶点、用更低的描边精度。4. ROI 绘制与编辑实现六类图元的构造、拖拽与吸附图元层是整个控件里代码量最大的一部分也是最容易写成意大利面的地方。控制复杂度的关键是把「几何计算」和「绘制」「交互」彻底分开几何计算写在一组纯函数里输入输出都是Point不碰DrawingContext这样单元测试好写坐标算错了也容易定位。4.1 图元基类与统一生命周期所有 ROI 图元都从一个抽象基类派生基类负责三件事命名与图层属性、顶点集合的读写、序列化。派生类只实现几何相关的三个方法。public abstract class RoiShape { public string Name { get; set; } ROI; public Color Stroke { get; set; } Colors.Lime; public bool IsVisible { get; set; } true; public bool IsLocked { get; set; } // 锁定后不参与命中测试 // 图元在图像坐标系下的顶点顺序即绘制顺序 public abstract IReadOnlyListPoint Vertices { get; } // 手柄位置图像坐标矩形给8个多边形给顶点本身 public abstract IReadOnlyListPoint GetHandles(); // 判断图像坐标点是否落在图元内部含边线容差单位是图像像素 public abstract bool Contains(Point imagePoint, double tolerance); // 绘制dc 已由外层做好屏幕坐标变换 public abstract void Draw(DrawingContext dc, ViewTransform vt); // 拖动某个手柄handleIndex 来自 GetHandles 的下标 public abstract void MoveHandle(int handleIndex, Point imagePoint); // 平移整个图元 public virtual void Translate(Vector delta) { for (int i 0; i Vertices.Count; i) _mutable[i] delta; } }Contains的tolerance参数容易被忽略。图像缩放得很小时ROI 的边线在屏幕上只有一两个像素宽用户点边线基本点不中必须给一个容差把边线「加粗」成可点击区域。这个容差应该是「屏幕 5 像素换算成图像像素」也就是5 / scale由调用方算好传进来而不是图元自己去读缩放比例——保持图元对视图不可见是前面定下的规矩。Translate做成虚方法而不是抽象方法是因为多边形和图元容器一个框里套多个 ROI 的组的平移逻辑不一样后者要递归。默认实现直接改顶点数组就够了派生类需要特殊处理时再重写。4.2 矩形与旋转矩形手柄布局与拖拽的符号问题普通矩形只有四个角加四条边中点共 8 个手柄拖拽逻辑很直观拖左上角改X和Y的同时改Width和Height要处理「拖过头」导致宽高变负的情况通常的做法是做一次归一化把负宽高翻转成正值并交换起止点。这段代码几乎所有教程都有不展开。真正费神的是旋转矩形。它的手柄位置不再是轴对齐的而是要先算出局部坐标系下的八个点再用旋转矩阵变换到图像坐标。// 旋转矩形中心 半宽半高 角度弧度算八个手柄 public override IReadOnlyListPoint GetHandles() { double cos Math.Cos(Angle), sin Math.Sin(Angle); // 局部坐标下的手柄偏移顺序四角 四边中点 var local new[] { new Vector(-HalfW, -HalfH), new Vector( HalfW, -HalfH), new Vector( HalfW, HalfH), new Vector(-HalfW, HalfH), new Vector(0, -HalfH), new Vector(HalfW, 0), new Vector(0, HalfH), new Vector(-HalfW, 0) }; var result new Point[local.Length]; for (int i 0; i local.Length; i) { // 先旋转再平移到中心 result[i] new Point( Center.X local[i].X * cos - local[i].Y * sin, Center.Y local[i].X * sin local[i].Y * cos); } return result; }Angle用弧度而不是角度是跟 WPF 的RotateTransform保持一致减少换算错误。手柄顺序「四角在前、边中点在后」在HitTestHandle里会带来一个优先级红利角手柄的命中半径可以比边中点大 2 个 DIP因为角上同时改两个维度用户更常拖它。MoveHandle的实现要注意旋转矩形的「反旋转」步骤鼠标给的是图像坐标必须先减去中心、乘上-Angle的旋转矩阵转回局部坐标再在局部坐标里改宽高最后把中心按新的宽高补偿平移。如果忘了补偿拖右下角的时候整个矩形会往左上跑这是旋转矩形最经典的翻车点我第一次写的时候调了整整一个下午。4.3 多边形与自由绘制采样、抽稀与闭合判定多边形 ROI 有两种产生方式逐点点击和按住拖拽自由画。逐点点击好办麻烦的是自由画——鼠标一秒来 100 个点直接全部存下来会有几百个顶点后续编辑时手柄密得根本点不中算法层拿去做多边形填充也慢。我的处理是三步采样降频、道格拉斯-普克抽稀、闭合判定。采样降频就是加一个最小间距判断新点离上一个点不到 3 个屏幕像素就丢掉注意这里的阈值要除以scale才能变成图像像素。抽稀用 Douglas-Peucker容差取2 / scale能把一条手画的弧线压到十几个顶点。// Douglas-Peucker 抽稀points 为图像坐标epsilon 单位也是图像像素 private static ListPoint Simplify(ListPoint points, double epsilon) { if (points.Count 3) return points; double maxDist 0; int index 0; Point a points[0], b points[^1]; // 找离首尾连线最远的点 for (int i 1; i points.Count - 1; i) { double d PerpendicularDistance(points[i], a, b); if (d maxDist) { maxDist d; index i; } } // 超过容差就分段递归否则整段用直线代替 if (maxDist epsilon) { var left Simplify(points.Take(index 1).ToList(), epsilon); var right Simplify(points.Skip(index).ToList(), epsilon); left.RemoveAt(left.Count - 1); left.AddRange(right); return left; } return new ListPoint { a, b }; }递归实现代码短但深递归在顶点极多时可能爆栈实际项目里我会改成显式栈的迭代版本。PerpendicularDistance要处理首尾点重合的退化情况否则除以零会返回NaNNaN参与比较永远是false抽稀会静默失效——你只会发现顶点没被简化却找不到原因。闭合判定分两种策略距离首点小于 8 个屏幕像素就自动闭合或者用户双击强制闭合。我倾向于两个都留因为手绘时既有「画回起点」的习惯也有「随手一停双击」的习惯。闭合之后立刻做一次自相交检测发现自相交就提示用户重画比把错误的多边形送进算法层再报错要友好得多。4.4 编辑操作栈撤销重做与序列化ROI 编辑一定要有撤销不然用户拖歪一个角就得删了重画体验极差。简单的做法是每次操作前把整个 ROI 列表深拷贝一份压栈实现五分钟搞定但内存吃得厉害——几十个多边形 ROI 拷一次就是几百 KB撤销栈存 50 步就二三十兆。我的做法是命令模式每个操作只记录「改了谁、改前是什么、改后是什么」public sealed class MoveHandleCommand : IUndoableCommand { private readonly RoiShape _shape; private readonly int _handleIndex; private readonly Point _before; private Point _after; public void Execute(Point newPosition) { _after newPosition; _shape.MoveHandle(_handleIndex, newPosition); } public void Undo() _shape.MoveHandle(_handleIndex, _before); public void Redo() _shape.MoveHandle(_handleIndex, _after); }关键点是Execute里只存最终位置不存中间的每一次MouseMove。拖拽过程中每帧都会改图元但只有MouseUp那一刻才把一条命令压栈。这样一次拖拽只占一条撤销记录也符合用户的直觉撤销一次应该回到拖拽前而不是回到上一帧。合并策略是在MouseDown时创建命令对象MouseMove只更新_after并直接改图元MouseUp时压栈。这个「延迟压栈」的写法值得单独记一下很多实现是在MouseMove里就压栈结果用户撤销十次才退回原位。序列化用System.Text.Json图元用一个带Type判别字段的多态结构反序列化时按Type分发到具体类。坐标存成[x1, y1, x2, y2, ...]的扁平数组而不是对象数组文件能小一半读写也快。浮点要保留 4 位小数太多位会让文件膨胀且没有意义——图像坐标精度到 0.1 像素早就超过相机分辨率了。5. 避坑与排查坐标系、DPI、内存与交互冲突的五个高频翻车点这一章列的都是我和同事在真实项目里踩过的坑共同特点是「现象看起来像渲染 bug其实是坐标或生命周期问题」。如果你正在调这类控件先对照这五条排查能省掉大量时间。5.1 ROI 在高 DPI 屏幕上整体偏移现象在 100% 缩放的机器上一切正常换到 125% 或 150% 的笔记本上ROI 框整体往左上偏一点越往右下偏得越多偏移量跟坐标值成正比。原因WPF 的鼠标事件给的是 DIP设备无关单位而WriteableBitmap的像素缓冲是按物理像素算的。当图像以 1:1 显示时你把 DIP 直接当像素用两者差了一个dpiScale因子。缩放比例是 1.25 时屏幕坐标 400 DIP 对应 500 物理像素ROI 就偏了 100 像素。解决在控件加载时读一次 DPI 缩放所有涉及「DIP 与物理像素换算」的地方统一乘这个因子。更彻底的做法是让ViewTransform内部只用 DIP图像坐标到 DIP 的换算里显式带上dpiScale// 在 OnDpiChanged 或 Loaded 里刷新不要每次鼠标事件都去读 private double _dpiScale 1.0; protected override void OnDpiChanged(DpiScale oldDpi, DpiScale newDpi) { base.OnDpiChanged(oldDpi, newDpi); _dpiScale newDpi.DpiScaleX; // DPI 变了必须重算适应窗口的缩放否则图会显示不全 FitToWindow(); RequestRender(); }OnDpiChanged这个重写点需要 .NET Core 3.0 以上或 .NET 5老版本框架上要自己在Loaded或WM_DPICHANGED消息里处理。这也是我建议新项目直接上 .NET 6/8 的原因之一——WPF 的 DPI 支持在新版本里完善了很多。5.2 滚轮缩放后图像「跑掉」现象缩放时图像往右下角飘或者缩放中心不在光标而在控件中心用起来像在拖一张不听话的地图。原因只改了Scale没改平移或者用了RenderTransform的ScaleTransform但CenterX/CenterY设成了 0。前者是数学没做闭环后者是把变换交给 WPF 而没自己做锚点计算。解决按 3.2 节的三步法重写ZoomAt。如果确实想用ScaleTransform必须同时设置CenterX、CenterY为光标相对控件的坐标但这样做的问题是它跟你的ImageToScreen矩阵会打架两套变换叠在一起调试起来非常痛苦。我一般会禁用RenderTransform所有变换只走矩阵。5.3 大图刷新时界面卡顿与内存暴涨现象切换图像或者高频取流时界面卡住几百毫秒任务管理器里内存一路涨跑几分钟就上 GB。原因通常有两个。一是每次都new WriteableBitmap旧对象等 GC大图一秒换十次就是几百兆的分配压力二是WritePixels传的是整图明明只有一小块在变。解决位图对象复用尺寸不变时只WritePixels不重建用脏区矩形限制写入范围如果图像源尺寸会变做一次尺寸判断再决定是否重建。另外WriteableBitmap默认是Bgra32如果你的源是灰度图转成Bgra32会让内存翻四倍改成Gray8加调色板能省很多。灰度图用Gray8时要注意FormatConvertedBitmap的开销能直接喂原始字节就直接喂。5.4 图元命中测试永远点不中现象ROI 画出来了样式也对但鼠标点上去毫无反应或者要点偏十几像素才有反应。原因命中测试里把屏幕坐标直接和图像坐标比较了。图缩放 0.5 倍时屏幕点 (200,200) 对应的图像点是 (400,400)你拿 200 去比 400 当然不中。解决统一在 3.3 节的约定下写——InteractionController收到鼠标事件的第一件事就是ScreenToImage之后所有坐标都是图像坐标只有手柄命中测试反过来用手柄的图像坐标ImageToScreen到屏幕再比。这两种「方向」必须在对的地方用写反了就是点不中。建议在代码里加一行断言检查传入Contains的点是否在图像边界内能快速暴露这个错误。5.5 手柄大小随缩放变化现象图放大时手柄变成大方块缩小时手柄小到看不见、点不中。原因手柄的绘制坐标是从图像坐标直接算的没有做尺寸归一化。解决手柄的「中心点」用图像坐标变换到屏幕但「大小」固定为屏幕 DIP比如 7×7绘制时用屏幕坐标画。具体做法是在Draw里先vt.ImageToScreen.Transform(handle)得到屏幕点再以这个点为中心画一个固定尺寸的矩形。同时注意描边宽度也要固定为 1 DIP否则线宽会跟着缩放变成 10 像素粗非常难看。6. 验收与答辩怎么证明这个控件「真的能用」答辩现场最怕的不是功能少而是「老师随手一操作就出问题」。所以验收要自己先做一遍按操作路径走而不是按代码模块走。我一般会准备一张验收表逐项过过不了的当场改别等到现场。验收项操作方法通过标准坐标一致性在 1:1、200%、20% 三档缩放下各点一次图像上的同一个特征点状态栏显示的图像坐标三次一致误差不超过 1 像素缩放锚点光标停在图像某个角上滚动滚轮该角在屏幕上位置不动DPI 兼容把系统缩放改成 150% 重启程序ROI 与图像特征仍然对齐无整体偏移手柄可用性缩放到 10% 和 800% 各拖一次角手柄两种缩放下手柄都能点中尺寸视觉上一致撤销栈连续拖拽 20 次后连按 20 次撤销回到初始状态无残留、无错位序列化往返存盘再读盘所有 ROI 位置、颜色、名称与存盘前一致大图性能加载 5000×4000 灰度图拖动 ROI帧率不低于 30fps无卡顿感答辩讲解的顺序也有讲究。不要一上来就讲架构先演示三个动作滚轮缩放、拖一个矩形 ROI、撤销。这三个动作覆盖了变换、图元、命令栈三条主线评委一看就知道东西是活的。然后再翻到代码讲ViewTransform那一个类重点讲ZoomAt的三步推导——这是整个项目里唯一有数学含量的地方讲清楚了就能撑住「设计」两个字。演示脚本我一般会写成这样三分钟一遍练熟# 演示前自检避免现场翻车 1. 确认程序默认加载一张 4K 测试图不是空白 2. 确认「适应窗口」在启动时自动执行一次 3. 确认状态栏显示 图像坐标 / 缩放倍数 / DPI 三个值 4. 确认撤销栈初始为空按钮置灰 5. 确认关掉调试输出窗口避免异常信息弹出这张清单看着琐碎但每一条都对应一次真实事故加载空白图是因为图像源初始化顺序写反了忘记适应窗口是因为Loaded事件里没算视口尺寸状态栏不显示 DPI 是因为答辩时被问到「你怎么保证跨屏一致」答不上来。把这些做成自检项比临时抱佛脚管用。还有个答辩常被问到的点为什么不直接用 Halcon 的HSmartWindowControl。回答的思路是承认它能用但指出三层问题——它绑定特定算法库换成 OpenCV 或自研算法就得换控件它的 ROI 交互是封装好的黑匣子要定制吸附、对齐、多选这类业务逻辑改不动以及部署时要带一整套运行时依赖。自己写这套东西的价值不在「重复造轮子」而在于把交互层和算法层解耦让 ROI 数据能以纯坐标的形式送进任意算法后端。这个回答既解释了动机也展示了架构思考比单纯说「老师要求自己写」强得多。从那以后我每次交付带交互的控件都强制自己先把验收表走一遍再演示哪怕时间再紧也不跳。因为真正让人难堪的从来不是功能没做完而是演示到一半光标点不中手柄。希望帮到你。本文还有配套的精品资源点击获取
