简介：这是面向C# WinForm开发者的图像显示与图形绘制示例工程，解决在图像控件中实时显示、缩放平移、绘制和调整ROI区域以及读取鼠标位置坐标与RGB值等问题。工程基于SnsPictureBox自定义控件，输入接口支持Bitmap、byte[]和IntPtr地址，可直接在线程中刷新画面，无需委托封送，适合机器视觉、图像处理上位机开发场景。压缩包共309个文件，以cs源码、dll依赖、resx界面资源、exe可执行程序为主，另含sln/csproj工程文件和txt/PDF说明文档，整体大小19.15MB，结构完整便于编译复现。目前已有607人学习下载，可帮助开发者快速集成图像预览、ROI交互绘制和像素信息提取功能，减少底层图像控件开发成本。
1. 从“没法交互”到“可拖拽ROI”：坐标、手柄、像素读取三者为什么绑在一起
C#上位机里做视觉调试，最磨人的往往不是算子选哪个，而是ROI写在代码里没法交互。框选位置一变就要改坐标、重新编译、启动，再看一遍效果，循环几次，耐心基本耗尽。想确认鼠标当前到底压在图像哪个像素上，还得临时写断点输出。这种开发方式拖慢的不是某一个功能，而是整个算法迭代速度。标题里的“可绘制Roil / 可调整Roi”，本质是把WinForms图像窗口上的ROI变成可拖拽组件：鼠标画框、手柄缩放、整体平移，同时实时显示原图像坐标和像素RGB。下面按自绘Panel的思路，把坐标换算、手柄绘制、命中检测、像素读取四段代码完整拆开，适合做视觉上位机或图像标定工具的人直接移植。
2. 绘制前的底座：C#图像缩放显示与鼠标坐标换算函数
2.1 为什么不直接用 PictureBox 叠加图形
在C#上位机里做图像显示，最常见的选择是PictureBox加SizeMode.Zoom。它用来显示静态图片没有问题，但要在上面叠加可拖拽ROI时，我不会继续用它。原因有两个：一是PictureBox的Paint事件在SizeMode变化后坐标系不直观，尤其从Zoom切到StretchImage时整个显示区域被拉伸，之前画好的框会错位；二是PictureBox默认状态下的双缓冲表现一般，频繁Invalidate时整块控件会明显闪动。
常见做法是自定义一个Panel子类，自己管理图像绘制、坐标换算和鼠标事件。这样从根本上绕开PictureBox的显示语义，ROI坐标始终按原始图像坐标保存，只在绘制那一刻换算到控件坐标。
public sealed class ImageCanvas : Panel { public ImageCanvas() { DoubleBuffered = true; ResizeRedraw = true; BackColor = Color.FromArgb(30, 30, 30); } }DoubleBuffered = true让ROI拖动时只在后缓冲绘制，不会闪烁；ResizeRedraw = true保证窗口尺寸变化时控件立刻重算显示区域；深灰色背景让图像边缘和画布空白区分得很清楚，调试时不会把背景误认为图像内容。
2.2 显示矩形计算：Zoom 效果的最小实现
在ImageCanvas的Paint事件里，第一步不是画ROI，而是计算出图像“应该画在控件的哪个矩形里”。这个矩形就是后续所有坐标换算的基准。
private RectangleF CalcDisplayRect() { if (_image == null) return RectangleF.Empty; float scaleX = (float)Width / _image.Width; float scaleY = (float)Height / _image.Height; float scale = Math.Min(scaleX, scaleY); float w = _image.Width * scale; float h = _image.Height * scale; float x = (Width - w) / 2f; float y = (Height - h) / 2f; return new RectangleF(x, y, w, h); }Math.Min对应的是PictureBox的Zoom语义：按宽、高两个缩放系数里小的那一个整体缩放，保证图像完整显示。(Width - w) / 2f实现居中，而不是把图像钉在左上角。视觉工具里居中的好处是，图像四周留出的空白区域对称，肉眼更容易判断ROI是否越界。
如果项目需要StretchImage效果，把scale改成scaleX和scaleY分别参与宽高计算即可；如果做居中裁切，则用Math.Max替代Math.Min，超出部分用Graphics.SetClip裁掉。改动点都集中在这个函数上，后续ROI绘制代码不需要跟着改。
2.3 双向坐标换算与边界限制
有了显示矩形，控件坐标和图像坐标之间的换算就是两个线性公式。我把它们定义成PointF版本，避免取整过程损失精度。
private PointF UiToImageF(PointF ui) { var r = CalcDisplayRect(); if (r.IsEmpty || _image == null) return PointF.Empty; float ix = (ui.X - r.X) / r.Width * _image.Width; float iy = (ui.Y - r.Y) / r.Height * _image.Height; return new PointF(ix, iy); } private PointF ImageToUiF(PointF img) { var r = CalcDisplayRect(); if (r.IsEmpty || _image == null) return PointF.Empty; float ux = img.X / _image.Width * r.Width + r.X; float uy = img.Y / _image.Height * r.Height + r.Y; return new PointF(ux, uy); }| 方向 | 公式要点 | 典型用途 |
|---|---|---|
| UI → 图像 | 先减显示矩形原点，再除以显示宽高，最后乘图像宽高 | 鼠标取像素、创建ROI |
| 图像 → UI | 先除以图像宽高，再乘显示宽高，最后加显示矩形原点 | 绘制ROI边框、手柄位置 |
两套换算都返回PointF。鼠标事件拿到的控件坐标虽然是整数Point，但换算后用浮点保存，ROI的边界就不会因为连续拖拽而不断累积舍入误差。唯一需要小心的是鼠标落在画布空白区时，UiToImageF会给出负数或超出图像宽高的坐标，因此取像素前必须过滤。
private PointF ClampToImage(PointF p) { if (_image == null) return PointF.Empty; return new PointF( Math.Clamp(p.X, 0, _image.Width - 1), Math.Clamp(p.Y, 0, _image.Height - 1)); }Math.Clamp把坐标限制在[0, Width-1]和[0, Height-1]区间，这是后面用LockBits或GetPixel读像素时不会越界的底线。坐标换算做完，画布底座就稳了。
3. 可调整ROI的绘制：矩形边框、8个手柄与半透明遮罩
3.1 RoiInfo 数据结构与手柄布局
ROI不能只存一个Rectangle就完事。拖拽过程中需要区分“当前拖的是哪个手柄”，还要限制最小尺寸。我定义了一个轻量的可调整ROI类：
public sealed class AdjustableRoi { public RectangleF Bounds; public const int MinSize = 6; }Bounds使用图像坐标系，拖拽时每次更新它，绘制时再用ImageToUiF换算到屏幕。这样当窗口被拉伸、缩放比例变化时，ROI在图像里的实际位置保持不变，不会出现“窗口拉大后框和图像错位”的问题。
8个手柄的UI位置基于ROI在屏幕上的矩形计算，一共是四角加四边中点。绘制手柄需要返回一组Rectangle，方便命中检测直接调用Contains。
private Rectangle[] GetHandles() { var r = RoiBoundsInUi(); var pts = new[] { new PointF(r.Left, r.Top), new PointF(r.Left + r.Width / 2f, r.Top), new PointF(r.Right, r.Top), new PointF(r.Left, r.Top + r.Height / 2f), new PointF(r.Right, r.Top + r.Height / 2f), new PointF(r.Left, r.Bottom), new PointF(r.Left + r.Width / 2f, r.Bottom), new PointF(r.Right, r.Bottom) }; const int s = 6; return pts.Select(p => Rectangle.Round( new RectangleF(p.X - s / 2f, p.Y - s / 2f, s, s))).ToArray(); }RoiBoundsInUi()是ImageToUiF作用在ROIBounds四个边界上得到的RectangleF。手柄边长6是相对控件坐标的固定像素值，不会随图像缩放变化。这样设计是有意为之：手柄是操作控件，不是图像内容，图像缩得很小时手柄依然容易被点中。
| 下标 | 位置语义 | 拖拽效果 |
|---|---|---|
| 0 | 左上角 | 同时改X、Y、Width、Height |
| 1 | 上边中点 | 只改Y和Height |
| 2 | 右上角 | 改X、Width、Height |
| 3 | 左边中点 | 只改X和Width |
| 4 | 右边中点 | 只改Width |
| 5 | 左下角 | 改X、Width、Height |
| 6 | 下边中点 | 只改Height |
| 7 | 右下角 | 改Width、Height |
3.2 GDI+ 绘制：遮罩、边框、手柄
绘制顺序有讲究：先画图像，再画ROI遮罩，最后画边框和手柄。遮罩的作用是把ROI之外的区域压暗，让视觉焦点自动落在框内。
private void DrawRoiMask(Graphics g) { var ui = RoiBoundsInUi(); using var brush = new SolidBrush(Color.FromArgb(70, 0, 0, 0)); var old = g.Clip; g.SetClip(new RectangleF(0, 0, Width, Height)); g.ExcludeClip(Rectangle.Round(ui)); g.FillRectangle(brush, 0, 0, Width, Height); g.Clip = old; }Color.FromArgb(70, 0, 0, 0)是70/255透明度的黑色。用SetClip限定填充范围，再用ExcludeClip挖掉ROI矩形，这样只压暗框外区域。old保存原裁剪区，绘制后必须恢复，否则后续手柄绘制会被上个区域的裁剪限制。
边框和手柄的绘制保持风格一致：
private void DrawRoiFrame(Graphics g) { var ui = RoiBoundsInUi(); using var pen = new Pen(Color.LimeGreen, 2f); g.DrawRectangle(pen, ui.X, ui.Y, ui.Width, ui.Height); var handles = GetHandles(); using var white = new SolidBrush(Color.White); foreach (var h in handles) { g.FillRectangle(white, h); g.DrawRectangle(pen, h); } }边框用亮绿色在大多数工业图像上对比度都够；手柄白色打底、绿色描边，让暗色区域里也能看清。DrawRectangle的pen宽度用2像素，缩放比例放大时线宽不会跟着变，整个框在视觉上始终保持清晰的边界感。
3.3 手柄固定像素而不是跟随图像缩放
手柄要不要跟随图像比例缩放，是很多人会纠结的地方。若手柄尺寸按图像缩放，图像缩小时手柄也会变小，最后变成几个难点的点，命中检测的难度直线上升。因此我把手柄尺寸固定为控件像素，计算上完全绕开缩放比例。
需要记住的是：GetHandles返回的Rectangle是基于控件坐标的，而ROI的Bounds是基于图像坐标的，这两者之间靠RoiBoundsInUi换算。拖拽时从MouseDown拿到的坐标也是控件坐标，所以命中检测可以直接对手柄矩形做Contains，不需要再额外转换。
4. ROI 交互逻辑：命中检测、拖拽缩放与最小尺寸约束
4.1 命中检测：先手柄、后内部
可调整ROI的交互本质是一个小的状态机：鼠标按下时决定操作类型，MouseMove里执行移动或缩放，MouseUp时结束操作。命中检测的核心是优先级顺序，手柄优先于ROI内部。因为ROI一般不会太小，若先判断内部，很可能鼠标落在手柄上却误触发了移动。
private enum HitPart { None, Body, Handle } private HitPart HitTest(Point p, out int handleIndex) { handleIndex = -1; if (_roi == null) return HitPart.None; var handles = GetHandles(); for (int i = 0; i < handles.Length; i++) { if (handles[i].Contains(p)) { handleIndex = i; return HitPart.Handle; } } return RoiBoundsInUi().Contains(p) ? HitPart.Body : HitPart.None; }handleIndex用手柄数组下标，即前面表格里的0到7。HitPart.Handle表示当前进入缩放模式，HitPart.Body进入移动模式，HitPart.None就是点在空白区域，什么都不做。
| 命中结果 | 后续拖拽行为 |
|---|---|
| None | 不处理MouseMove中的ROI更新 |
| Body | 整块ROI平移 |
| Handle | 根据手柄下标调整对应边 |
4.2 MouseDown 与 MouseMove 里的位移换算
鼠标按下时记录命中类型和上一次坐标，这个坐标用控件的Point即可，位移计算用浮点差值完成。
private HitPart _hitPart; private int _hitHandle = -1; private Point _lastCursor; private void Canvas_MouseDown(object sender, MouseEventArgs e) { if (e.Button != MouseButtons.Left) return; _hitPart = HitTest(e.Location, out _hitHandle); _lastCursor = e.Location; }MouseMove里先计算基于图像坐标的位移。因为ROI的Bounds存在图像坐标里，屏幕上的1像素在图像里可能是0.5或0.2个单位，不能用控件坐标直接加减。
private void Canvas_MouseMove(object sender, MouseEventArgs e) { if (e.Button == MouseButtons.Left && _hitPart != HitPart.None) { var uiDelta = new PointF( e.Location.X - _lastCursor.X, e.Location.Y - _lastCursor.Y); var display = CalcDisplayRect(); var imgDelta = new PointF( uiDelta.X / display.Width * _image.Width, uiDelta.Y / display.Height * _image.Height); if (_hitPart == HitPart.Body) MoveRoi(imgDelta); else if (_hitPart == HitPart.Handle) ResizeRoi(_hitHandle, imgDelta); _lastCursor = e.Location; Invalidate(); } }这里没有把鼠标坐标换算成图像坐标再求差，而是直接把位移量做按比例缩放。好处是计算路径短，且不受显示矩形原点影响。display.Width * _image.Width的换算和前面UiToImageF是同一个比例关系，结果一致。
移动的实现很直接：
private void MoveRoi(PointF delta) { var b = _roi.Bounds; b.X += delta.X; b.Y += delta.Y; ClampRoiToImage(ref b); _roi.Bounds = b; }移动时唯一要防的是拖出图像范围，交给ClampRoiToImage统一处理。
4.3 ResizeRoi：按手柄下标更新边界
缩放逻辑用四个布尔变量分别表示“左、右、上、下”是否有动作。这个写法比switch逐个分支清晰，后续加手柄或改热区也不容易漏。
private void ResizeRoi(int handle, PointF delta) { var b = _roi.Bounds; bool left = handle is 0 or 3 or 5; bool right = handle is 2 or 4 or 7; bool top = handle is 0 or 1 or 2; bool bottom = handle is 5 or 6 or 7; if (left) { b.X += delta.X; b.Width -= delta.X; } if (right) b.Width += delta.X; if (top) { b.Y += delta.Y; b.Height -= delta.Y; } if (bottom) b.Height += delta.Y; if ((int)b.Width < AdjustableRoi.MinSize || (int)b.Height < AdjustableRoi.MinSize) return; ClampRoiToImage(ref b); _roi.Bounds = b; }以拖左手柄为例：鼠标往右拖时delta.X为正，b.X加大且Width减小，视觉上是左边框右移，右边框不动。这种方式天然覆盖角上的手柄，例如0号手柄同时命中left和top，两个方向同步调整。MinSize = 6是在图像坐标系里的最小像素尺寸，防止ROI被拖成负宽高。
边界约束统一处理：
private void ClampRoiToImage(ref RectangleF b) { if (_image == null) return; float maxX = _image.Width - b.Width; float maxY = _image.Height - b.Height; b.X = Math.Clamp(b.X, 0, Math.Max(0, maxX)); b.Y = Math.Clamp(b.Y, 0, Math.Max(0, maxY)); }Math.Max(0, maxX)处理ROI宽于图像时的极端情况，避免Math.Clamp的max参数小于min参数而抛异常。实际使用中MinSize远小于图像尺寸，不太会触发这个分支，但防御性写法能让组件在异常图像上也不崩。
5. 实时取鼠标位置的图像坐标和像素RGB：GetPixel 与 LockBits 的取舍
5.1 MouseMove 里实时刷新状态栏
ROI绘制好之后，鼠标在图像上移动时，状态栏需要同步显示坐标和RGB。这一步在MouseMove里做，但要注意不能每次都整块重绘图像，那会白白消耗画面刷新率。
private void Canvas_MouseMove(object sender, MouseEventArgs e) { if (_image == null) return; PointF img = UiToImageF(e.Location); int xi = (int)img.X; int yi = (int)img.Y; if (xi < 0 || yi < 0 || xi >= _image.Width || yi >= _image.Height) { toolStripStatusLabel.Text = "图像坐标：图像外"; return; } Color c = GetPixelCached(xi, yi); toolStripStatusLabel.Text = string.Format( "图像坐标：({0}, {1}) RGB：({2},{3},{4})", xi, yi, c.R, c.G, c.B); }UiToImageF把鼠标控件坐标换算成图像坐标。这里取整用的是直接截断，也就是坐标朝向原点方向靠拢，和图像离散像素的索引语义一致。显示层看到的鼠标位置和算法层取到的像素点之间，不会出现1像素偏移。
5.2 GetPixel 与 LockBits 对照
很多人想到取RGB，第一反应是Bitmap.GetPixel。它在小图和低频取色时没有问题，但鼠标扫过图像时MouseMove触发频率远超预期，每帧可能触发几十次甚至上百次GetPixel。此时GetPixel的封装开销会被成倍放大，状态栏刷新开始变得卡顿。
更合适的做法是把整张图的像素数据一次性锁到内存，之后按索引直接读数组。换来的代价是首次构建缓存时需要几毫秒，这对加载图像来说完全可以接受。
| 方式 | 单次耗时量级 | 适合场景 |
|---|---|---|
| Bitmap.GetPixel | 微秒到几十微秒 | 只取少数几个点，不连续跟踪 |
| LockBits + Marshal.Copy | 首次数毫秒，后续接近零 | 鼠标实时扫图取色 |
| unsafe 指针直接读 | 无复制，但有unsafe约束 | 对性能极端敏感的老项目 |
实现里最稳妥的是LockBits + Marshal.Copy，不需要开unsafe，还能顺便兼容不同位深。只要保证进入缓存之前把图像统一成24bpp RGB即可。
5.3 像素缓存构建与 RGB 输出顺序
构建像素缓存之前，先统一格式。工业相机可能返回8位灰度图或32位彩色图，如果不转换就按固定偏移读像素，结果一定是错的。
private void EnsureRgb24() { if (_image == null || _image.PixelFormat == PixelFormat.Format24bppRgb) return; var clone = new Bitmap(_image.Width, _image.Height, PixelFormat.Format24bppRgb); using (var g = Graphics.FromImage(clone)) { g.DrawImage(_image, 0, 0, _image.Width, _image.Height); } _image.Dispose(); _image = clone; }DrawImage把任意格式绘制到新的24bpp位图上，完成格式转换。这一步只在图像加载时执行一次，量级上不会拖慢交互。
缓存构建：
private byte[] _pixelCache; private int _stride; private void BuildPixelCache() { if (_image == null) return; var data = _image.LockBits( new Rectangle(0, 0, _image.Width, _image.Height), ImageLockMode.ReadOnly, PixelFormat.Format24bppRgb); try { _stride = data.Stride; _pixelCache = new byte[_stride * data.Height]; Marshal.Copy(data.Scan0, _pixelCache, 0, _pixelCache.Length); } finally { _image.UnlockBits(data); } }Stride可能不等于Width * 3，因为GDI+为保证内存对齐，会在每行末尾填充字节。所以缓存数组大小是Stride * Height，而不是Width * Height * 3。
读取像素索引：
private Color GetPixelCached(int x, int y) { if (_pixelCache == null) return Color.Empty; int offset = y * _stride + x * 3; byte b = _pixelCache[offset]; byte g = _pixelCache[offset + 1]; byte r = _pixelCache[offset + 2]; return Color.FromArgb(r, g, b); }24bpp内存顺序是B、G、R，所以偏移0是蓝色分量，偏移2是红色分量。这里必须按BGR顺序读，然后组装成Color.FromArgb(r, g, b)。如果直接返回Color.FromArgb(_pixelCache[offset], ...)，整张图的红蓝会互换，导致调试结果完全不可信。
6. 两个收尾技巧：33ms 限流刷新和与 OpenCVSharp 的框选联动
6.1 状态栏刷新限流
鼠标在控件上快速扫过时，MouseMove的信息量太大。ROI拖拽需要及时重绘，但状态栏文字没必要每帧都更新。常见做法是按33毫秒限流，也就是大约每秒30次状态刷新，视觉上依然流畅，CPU占用却低很多。
private DateTime _lastInfoTime = DateTime.MinValue; private void UpdateCursorInfo(Point uiPos) { if ((DateTime.Now - _lastInfoTime).TotalMilliseconds < 33) return; _lastInfoTime = DateTime.Now; // 这里再走 UiToImageF 和 GetPixelCached }把状态刷新和ROI拖拽分离：Canvas_MouseMove里先执行拖拽逻辑，再调用限流后的UpdateCursorInfo。拖动ROI本身走Invalidate重绘，不受33ms限制，手感不粘滞；状态栏文字最多每秒刷新30次，不会成为性能瓶颈。
6.2 和 OpenCVSharp 联动时的矩形换算
很多C#上位机项目最终要把这个ROI交给OpenCVSharp处理。OpenCVSharp的Rect要求整型参数，但AdjustableRoi.Bounds是浮点，直接强转前要明白精度去向。
var roiRect = new OpenCvSharp.Rect( (int)_roi.Bounds.X, (int)_roi.Bounds.Y, (int)_roi.Bounds.Width, (int)_roi.Bounds.Height);强转是截断而不是四舍五入，对ROI起点像素影响不大，但如果ROI坐标可能为负，必须先做Clamp，否则OpenCvSharp.Rect内部会抛异常。验证时拿一张带颜色渐变的标准测试图，鼠标停在某个明显色块边缘，把状态栏读到的RGB和Photoshop里同一个坐标的颜色值对照，差1以内说明取色逻辑正常；如果红蓝互换或整体偏色，就去检查Format24bppRgb的BGR偏移，而不是怀疑鼠标坐标算错了。
本文还有配套的精品资源，点击获取
