简介：这是一套基于WPF的C#图像显示与ROI管理控件实现，面向工业检测、医学影像及教学演示等需要轻量级图像标注的桌面应用开发者。它无需依赖Halcon运行时，即可复现HSmartWindowControl的核心交互体验，支持图像加载、缩放、平移，以及矩形、圆形、多边形、椭圆等ROI的鼠标实时绘制、顶点拖拽调整、选中高亮、键盘删除与坐标批量导出，内部采用Canvas+Shape组合渲染，ROI数据结构独立封装，便于对接OpenCV或EmguCV流程。资源包共52个文件，约106KB，以26个cs源码、3个xaml界面、3个csproj工程及resx、axaml、json等配置为主，含完整可运行示例TestWindowWpf与RoiImplementation、Helper、Themes等模块，无第三方UI库依赖。目前已有36人学习下载，适合希望快速掌握WPF图像标注交互逻辑的中高级开发者参考。
1. 从 Halcon 的 Draw 系列算子说起：为什么 WPF 里要自己造一个 ROI 控件
如果你是从 Halcon 转过来做 WPF 上位机的，大概率经历过这个瞬间：在 HDevelop 里draw_rectangle1、draw_circle、draw_region随手一画，ROI 就出来了，拖拽、缩放、删除都是现成的；可一旦搬到 WPF 的Image控件上，鼠标事件全得自己接，Canvas坐标和图像像素坐标还得手动换算，画出来的框一缩放就飘。这个 WPF 自定义图像显示控件要解决的正是这件事——把 Halcon 那套「鼠标直接操作 ROI」的交互逻辑，用 WPF 原生控件复刻出来，支持矩形、圆形、多边形等 ROI 的绘制、拖拽、删除，并且坐标体系和图像像素对齐。它适合做机器视觉上位机、缺陷检测界面、标定工具的开发同学，尤其是团队里没人愿意碰交互层、又不想为了一个 ROI 去引整套商业控件的场景。下面我按「控件怎么搭 → 交互怎么接 → 坑在哪」的顺序拆一遍。
2. 控件骨架与坐标映射：把 Canvas 叠在 Image 上
2.1 为什么是 Image + Canvas 双层结构
WPF 里显示图像最直接的是Image控件，设Source为BitmapSource即可。但Image本身不承载任何交互元素，ROI 必须画在它上面。常见做法是用一个Grid把Image和Canvas叠起来，Canvas背景透明、IsHitTestVisible保持true，这样鼠标事件落在Canvas上，图像在底下正常渲染。
<Grid x:Name="RootGrid" ClipToBounds="True"> <!-- 图像层：只负责显示 --> <Image x:Name="DisplayImage" Stretch="Uniform" RenderOptions.BitmapScalingMode="HighQuality"/> <!-- ROI 层：承载所有交互图形 --> <Canvas x:Name="RoiCanvas" Background="Transparent" IsHitTestVisible="True"/> </Grid>这里有个关键选择：Stretch="Uniform"。图像按比例缩放填满控件，但缩放后图像实际显示区域和控件区域不一致，左右或上下会有留白。ROI 坐标如果直接按控件坐标存，一旦窗口 resize 就全错位。所以坐标映射必须做两件事——把鼠标的控件坐标转成图像像素坐标，再把 ROI 的像素坐标转回控件坐标渲染。
2.2 像素坐标与控件坐标的双向换算
先算图像在控件里的实际显示矩形。Uniform模式下，缩放比是控件尺寸和图像尺寸比值的较小者：
// 计算图像在控件内的实际显示区域（含留白偏移） private Rect GetImageDisplayRect() { if (DisplayImage.Source == null) return Rect.Empty; double imgW = DisplayImage.Source.Width; double imgH = DisplayImage.Source.Height; double ctrlW = RootGrid.ActualWidth; double ctrlH = RootGrid.ActualHeight; // Uniform：取较小的缩放比，保证图像完整显示 double scale = Math.Min(ctrlW / imgW, ctrlH / imgH); double showW = imgW * scale; double showH = imgH * scale; // 居中留白偏移 double offsetX = (ctrlW - showW) / 2.0; double offsetY = (ctrlH - showH) / 2.0; return new Rect(offsetX, offsetY, showW, showH); } // 控件坐标 -> 图像像素坐标 private Point ControlToImage(Point p) { var rect = GetImageDisplayRect(); if (rect.IsEmpty) return p; double scale = rect.Width / DisplayImage.Source.Width; return new Point((p.X - rect.X) / scale, (p.Y - rect.Y) / scale); } // 图像像素坐标 -> 控件坐标 private Point ImageToControl(Point p) { var rect = GetImageDisplayRect(); if (rect.IsEmpty) return p; double scale = rect.Width / DisplayImage.Source.Width; return new Point(p.X * scale + rect.X, p.Y * scale + rect.Y); }GetImageDisplayRect返回的Rect同时携带了偏移和缩放信息，后面所有换算都基于它。参数上唯一要盯的是scale的除数——用rect.Width / Source.Width而不是控件宽度，因为留白区域不参与缩放。这套换算我在项目里封装成静态方法，ROI 的存储一律用图像像素坐标，渲染时才转控件坐标，这样无论窗口怎么拉伸，ROI 都钉在图像的正确位置上。
2.3 ROI 数据模型与渲染分离
ROI 不要直接存成 WPF 的Shape对象，否则数据层和 UI 层耦合，序列化、撤销、批量删除都会很难受。我一般定义一个轻量模型：
public enum RoiType { Rectangle, Circle, Polygon } public class RoiItem { public RoiType Type { get; set; } public List<Point> Points { get; set; } = new(); // 像素坐标 public string Id { get; set; } = Guid.NewGuid().ToString("N"); public bool IsSelected { get; set; } }矩形存两个对角点，圆形存圆心加半径点，多边形存顶点列表。渲染时遍历RoiItem集合，用ImageToControl换算后生成对应的Rectangle、Ellipse、Polygon贴到Canvas上。数据归数据、渲染归渲染，后面做删除和拖拽时只改模型再重绘，逻辑干净很多。
3. 鼠标交互三件套：绘制、拖拽、删除的实现
3.1 绘制：MouseDown / Move / Up 的状态机
绘制 ROI 本质是一个三态状态机：空闲、绘制中、完成。用MouseDown记录起点并进入绘制中，MouseMove实时更新预览图形，MouseUp落定并写入模型。
private bool _isDrawing; private Point _startImgPoint; // 起点（像素坐标） private Shape _previewShape; // 绘制中的预览图形 private void RoiCanvas_MouseLeftButtonDown(object sender, MouseButtonEventArgs e) { if (_currentTool == RoiTool.None) return; _startImgPoint = ControlToImage(e.GetPosition(RoiCanvas)); _isDrawing = true; _previewShape = CreatePreviewShape(_currentTool, _startImgPoint); RoiCanvas.Children.Add(_previewShape); RoiCanvas.CaptureMouse(); // 关键：捕获鼠标，防止移出控件丢事件 } private void RoiCanvas_MouseMove(object sender, MouseEventArgs e) { if (!_isDrawing || _previewShape == null) return; var curImg = ControlToImage(e.GetPosition(RoiCanvas)); UpdatePreviewShape(_previewShape, _startImgPoint, curImg); } private void RoiCanvas_MouseLeftButtonUp(object sender, MouseButtonEventArgs e) { if (!_isDrawing) return; _isDrawing = false; RoiCanvas.ReleaseMouseCapture(); var endImg = ControlToImage(e.GetPosition(RoiCanvas)); // 过滤误触：太小或没动就不生成 if (IsTooSmall(_startImgPoint, endImg)) { RoiCanvas.Children.Remove(_previewShape); return; } _roiList.Add(BuildRoiItem(_currentTool, _startImgPoint, endImg)); RedrawAllRois(); }CaptureMouse()是血泪经验——不捕获的话，鼠标拖到控件外面MouseUp就收不到，状态机卡在绘制中，下次点击直接乱套。IsTooSmall用来过滤单击误触，阈值一般设 3 到 5 像素，太小说明用户只是点了一下没想画。
3.2 拖拽：命中检测与整体平移
拖拽分两种：拖 ROI 整体平移，拖控制点改大小。先做整体平移，命中检测用VisualTreeHelper.HitTest或者直接遍历 ROI 做几何判断。我倾向后者，因为 ROI 数量通常不多，几何判断更可控。
private RoiItem HitTestRoi(Point imgPoint) { // 倒序遍历，后画的在上层，优先命中 for (int i = _roiList.Count - 1; i >= 0; i--) { var roi = _roiList[i]; if (IsPointInRoi(roi, imgPoint, tolerance: 5)) return roi; } return null; } private void OnRoiMouseDown(object sender, MouseButtonEventArgs e) { var imgPoint = ControlToImage(e.GetPosition(RoiCanvas)); var hit = HitTestRoi(imgPoint); if (hit == null) return; _draggingRoi = hit; _dragStartImg = imgPoint; _dragOriginPoints = hit.Points.Select(p => new Point(p.X, p.Y)).ToList(); e.Handled = true; // 阻止冒泡到 Canvas 触发新建 } private void OnRoiMouseMove(object sender, MouseEventArgs e) { if (_draggingRoi == null) return; var curImg = ControlToImage(e.GetPosition(RoiCanvas)); double dx = curImg.X - _dragStartImg.X; double dy = curImg.Y - _dragStartImg.Y; for (int i = 0; i < _draggingRoi.Points.Count; i++) { _draggingRoi.Points[i] = new Point( _dragOriginPoints[i].X + dx, _dragOriginPoints[i].Y + dy); } RedrawAllRois(); }tolerance是命中容差，像素坐标下给 5 左右手感比较舒服，太小点不中，太大容易误选相邻 ROI。e.Handled = true必须加，否则事件冒泡到Canvas的MouseDown，一边拖一边又新建一个 ROI，画面直接失控。拖拽时记录_dragOriginPoints快照，每次移动基于原始点加偏移，而不是累加增量，避免浮点误差累积导致 ROI 越拖越偏。
3.3 删除：选中态与键盘响应
删除要先有选中态。单击 ROI 设为选中，按Delete键移除。选中态用IsSelected标记，渲染时给选中的 ROI 换描边颜色或加虚线。
private void RoiCanvas_MouseRightButtonDown(object sender, MouseButtonEventArgs e) { var imgPoint = ControlToImage(e.GetPosition(RoiCanvas)); var hit = HitTestRoi(imgPoint); if (hit != null) { _roiList.Remove(hit); RedrawAllRois(); e.Handled = true; } } // 键盘删除：控件需 Focusable=true 并先获取焦点 private void OnKeyDown(object sender, KeyEventArgs e) { if (e.Key == Key.Delete) { var selected = _roiList.Where(r => r.IsSelected).ToList(); foreach (var r in selected) _roiList.Remove(r); RedrawAllRois(); } }右键删除是最顺手的，但要注意Canvas默认不接收键盘事件，得设Focusable="True"并在MouseDown里Focus()。删除后一定要RedrawAllRois()全量重绘，别去Children.Remove单个图形——模型和视图一旦不同步，后面拖拽就会命中到已经删掉的幽灵 ROI。
4. 避坑与常见问题排查
4.1 现象：ROI 画出来位置对，一缩放窗口就飘
原因：ROI 存的是控件坐标，窗口 resize 后GetImageDisplayRect变了，但模型没跟着换算。解决：模型一律存图像像素坐标，渲染时才转控件坐标，SizeChanged事件里触发RedrawAllRois()。这是最常见的一个坑，本质是坐标存错了层。
4.2 现象：鼠标拖到控件外松开，回来还在画
原因：没调CaptureMouse()，MouseUp丢事件，状态机卡死。解决：MouseDown里CaptureMouse()，MouseUp里ReleaseMouseCapture()，并且加一个兜底——LostMouseCapture事件里强制复位_isDrawing = false。
4.3 现象：拖拽 ROI 时又新建了一个
原因：ROI 图形的MouseDown没设e.Handled = true，事件冒泡到Canvas触发了新建逻辑。解决：所有 ROI 图形的事件处理末尾都加e.Handled = true，把冒泡掐断。
4.4 现象：多边形 ROI 顶点顺序乱了，填充区域自交
原因：用户画多边形时点序可能交叉，或者拖拽单个顶点后顺序没维护。解决：绘制时按点击顺序存点，不做自动排序；渲染用Polygon的Fill规则设FillRule="Nonzero"，自交时表现更符合直觉。如果业务要求凸多边形，拖拽后做一次凸包检测。
4.5 现象：图像很大时拖拽卡顿
原因：每次MouseMove都全量重绘所有 ROI，图形多了就掉帧。解决：拖拽时只更新被拖的那个Shape的坐标，不调RedrawAllRois()；MouseUp时再全量重绘一次保证一致。另外Image开RenderOptions.BitmapScalingMode="LowQuality"在拖拽期间能明显提帧，松手再切回HighQuality。
5. 进阶：ROI 序列化与 Halcon 算子对接
控件做完只是第一步，真正落地时 ROI 得能存能读、能喂给 Halcon 做后续处理。我一般给RoiItem加一套 JSON 序列化，存成像素坐标，换台机器、换个分辨率都能还原。
// 序列化：ROI 列表 -> JSON var options = new JsonSerializerOptions { WriteIndented = true }; string json = JsonSerializer.Serialize(_roiList, options); File.WriteAllText("roi_config.json", json); // 反序列化后必须重绘 _roiList = JsonSerializer.Deserialize<List<RoiItem>>(json); RedrawAllRois();对接 Halcon 时，矩形 ROI 转gen_rectangle1，圆形转gen_circle，多边形转gen_region_polygon。注意 Halcon 的Row对应图像 Y、Column对应 X，而 WPF 的Point是(X, Y)，转换时别把行列搞反——这个错我见过太多次，画面上 ROI 明明对，一进 Halcon 就跑到对角线去了。
// WPF Point(X,Y) -> Halcon (Row, Column) // 矩形：左上、右下 HOperatorSet.GenRectangle1(out HObject rect, topLeft.Y, topLeft.X, bottomRight.Y, bottomRight.X); // 圆形：圆心 Row/Column + 半径 HOperatorSet.GenCircle(out HObject circle, center.Y, center.X, radius);验证方法很简单：画一个矩形 ROI，导出 JSON，用 Halcon 读图后按坐标gen_rectangle1再reduce_domain，看裁出来的区域和 WPF 里框的是不是同一块。对得上，说明坐标映射和序列化都没问题。我现在的习惯是，任何 ROI 控件做完，先拿一张带明显角点的标定板图跑一遍——画框、拖拽、删除、存读、喂 Halcon，五步全过才敢往项目里合。从那以后我每次接图像交互的活，都强制先把这个闭环走一遍，省得后面在产线上被坐标问题反复折磨。希望帮到你。
本文还有配套的精品资源，点击获取
