TianWeiToolsPro.UI.Drawing 3.2.0

TianWeiToolsPro.UI.Drawing

TianWeiToolsPro.UI.Drawing 是一个面向 WPF 的图像显示与交互绘制控件库，适用于工业视觉、图像标注、ROI 编辑、测量图形绘制与图像浏览等场景。

业务侧直接使用 ImageView。它同时负责图像显示、视口变换、图元编辑、圆角裁剪、边框绘制，以及标尺和鼠标叠加层。默认外观写在 Themes/Generic.xaml。

目标框架

当前项目采用多目标框架构建（以 TianWeiToolsPro.UI.Drawing.csproj 为准）：

• .NET 6 (Windows)
• .NET 8 (Windows)
• .NET 10 (Windows)

主要功能

1. 图像显示、缩放与平移

核心控件：ImageView

支持的典型能力：

• 图像显示
• 鼠标滚轮缩放
• 拖拽平移
• 图像坐标与控件坐标转换
• 视口矩阵变化通知
• 鼠标像素信息显示
• 按 CornerRadius 圆角裁剪背景、图像、图元与叠加层

2. 图形绘制与编辑

内置多种几何图形与交互工具，适用于视觉 ROI 标注与测量场景。

当前源码中可见的图形/工具包括：

• 线段 Line
• 卡尺线 LineCalipers
• 圆 ShapeCircle
• 圆弧 ShapeArc（依次点击起点、经过点、终点；三个点不能共线）
• 圆卡尺 CircleCalipers
• 矩形 ShapeRect1 / ShapeRect2
• 椭圆 ShapeEllipse1
• 多边形 ShapePolygon
• 折线 ShapePolygon（PolygonDesc.IsClosed = false，渲染不闭合，点击顶点围成的区域仍可选中）
• 角度测量 AngleMeasure

支持的典型能力：

• 绘制单个图形
• 显示多个图形
• 图形选中、拖拽、调整控制点
• 批量清空图形
• 图形渲染刷新

3. 内建标尺、坐标与鼠标叠加层

坐标标尺、鼠标十字线与坐标显示由 ImageView 直接渲染。

当前支持的能力包括：

• 显示横向/纵向标尺
• 鼠标移动时同时显示十字线与坐标文本
• 鼠标离开控件后自动清除十字线与坐标显示
• 支持图像坐标到业务坐标的变换矩阵显示
• 标尺单位文本自定义
• 标尺位置自定义
• 标尺尺寸、主次刻度密度、画笔样式自定义
• 翻转矩阵场景下标尺方向自适配（支持 X/Y 反向映射）
• 标尺单位文本优先绘制在横纵标尺交界角，避免压住刻度线

可配置项包括：

• ShowRuler
• ShowMousePosition
• RulerUnitText
• LeftRulerWidth
• TopRulerHeight
• MajorTickPixelSpacing
• MinorTickCount
• RulerBorderPen
• MajorTickPen
• MinorTickPenBrush
• MouseCrosshairPen
• HorizontalRulerPosition
• VerticalRulerPosition
• CoordinateTransformMatrix

位置枚举：

• HorizontalRulerPosition.Top
• HorizontalRulerPosition.Bottom
• VerticalRulerPosition.Left
• VerticalRulerPosition.Right

4. 图像输入与像素更新

BackgroundImage 是 WriteableBitmap? 依赖属性。直接赋值或绑定时，控件绘制同一个实例，不额外创建像素副本。同一实例的像素变化由 WPF 提交显示，不重复执行换图逻辑。

绑定一张可写位图后，可以在 UI 线程反复更新它的像素；无需每帧重新给绑定源属性赋值：

// DisplayBitmap 已绑定到 ImageView.BackgroundImage，frame 为可复用像素缓冲区。
DisplayBitmap.WritePixels(new Int32Rect(0, 0, width, height), frame, stride, 0);

位图需由显示它的 UI 线程创建。后台线程可以准备像素，但对这张位图调用 WritePixels 仍需在其所属的 UI 线程执行。

UpdateImage 提供以下同步重载，调用时必须位于控件所属的 UI 线程：

imageView.UpdateImage(bitmap);          // System.Drawing.Bitmap
imageView.UpdateImage(mat);             // OpenCvSharp.Mat
imageView.UpdateImage(hObject);         // HalconDotNet.HObject
imageView.UpdateImage(writeableBitmap); // 复制像素；直接共享实例请设置 BackgroundImage
imageView.UpdateImage(pixels, width, height, stride, PixelFormats.Bgr24);
imageView.ClearBackgroundImage();

更新方法复用当前未冻结且尺寸、格式相同的位图。目标为空、已冻结或尺寸格式变化时，创建 96 DPI 位图并通过 SetCurrentValue 替换，保留绑定表达式。单向绑定的源属性不会自动变为新实例，外部若继续写旧实例不会更新新画面；应明确同一控件的更新来源。

源图像和裸指针只在同步调用期间借用，控件不会保存或释放它们。返回时复制已经完成，调用方可释放或复用源资源。后台采集方需安排 UI 调用，并保证实际复制完成前源缓冲区一直有效且不被改写，不能仅排队后立即释放。方法不隐式排队，也不新增帧丢弃或限速策略。

裸像素入口的 pixels 指向逻辑首行，stride 是有符号行步长，支持行尾填充和负步长；调用方负责保证每行有效像素字节均可读。支持 Gray8、Bgr24、Bgr32、Bgra32、Pbgra32。Mat 支持二维 8 位的 1/3/4 通道和子图；HALCON 支持单张 byte 类型的单通道或 RGB 三平面。Bitmap 的 8 位索引输入沿用灰度强度语义，要求索引值代表灰度；ARGB 与预乘 alpha 分别使用对应格式。方法接受的 WriteableBitmap 须属于当前线程或已冻结。

当前保留方法更新及位图替换时清空图元、根据 IsDisplayMode 和首图状态适应窗口的行为；共享位图外部像素更新不执行这些操作。高频调用减少包装和缓冲区重复分配，不保证 WPF 或第三方库全链路零分配。

迁移旧接口：删除 ToImageData()/各类 ImageData 包装；原来的 BackgroundImageData 绑定改为绑定 WriteableBitmap 的 BackgroundImage，或调用上述更新方法。控件清空背景只解除显示引用，不再释放调用方图像。

5. 图形持久化描述

Persistence 目录下提供了多种图形描述类型，用于图形参数保存、恢复与序列化场景，例如：

• LineDesc
• CircleDesc
• Rect1Desc
• Rect2Desc
• Ellipse1Desc
• PolygonDesc
• ImageViewerDesc

常见使用方式

1. 在 XAML 中使用 ImageView

<Drawing:ImageView BackgroundImage="{Binding DisplayBitmap}"
                   Shapes="{Binding Shapes}"
                   IsDisplayMode="True"
                   ShowRuler="True"
                   ShowMousePosition="True"
                   RulerUnitText="mm"
                   HorizontalRulerPosition="Top"
                   VerticalRulerPosition="Left" />

2. 自定义标尺外观

<Drawing:ImageView BackgroundImage="{Binding DisplayBitmap}"
                   ShowRuler="True"
                   ShowMousePosition="True"
                   LeftRulerWidth="48"
                   TopRulerHeight="32"
                   MajorTickPixelSpacing="36"
                   MinorTickCount="5"
                   RulerUnitText="mm">
	<Drawing:ImageView.RulerBorderPen>
		<Pen Brush="White" Thickness="1" />
	</Drawing:ImageView.RulerBorderPen>
	<Drawing:ImageView.MajorTickPen>
		<Pen Brush="White" Thickness="1" />
	</Drawing:ImageView.MajorTickPen>
	<Drawing:ImageView.MinorTickPenBrush>
		<Pen Brush="Gray" Thickness="1" />
	</Drawing:ImageView.MinorTickPenBrush>
	<Drawing:ImageView.MouseCrosshairPen>
		<Pen Brush="DodgerBlue" Thickness="1" />
	</Drawing:ImageView.MouseCrosshairPen>
</Drawing:ImageView>

3. 在代码中显示图形

imageView.DisplayShape(shape);
imageView.DisplayShapes(shapes);
imageView.Rerender();

4. 在代码中发起交互绘制

var rect = await imageView.DrawShapeAsync<ShapeRect1>();

5. 订阅视图状态事件

业务层可直接订阅 ImageView 的视图状态事件：

• TransformMatrixChanged
• VisibleImageRectChanged
• VisibleCoordinateRectChanged
• MouseImagePointChanged
• MouseCoordinatePointChanged
• ViewStateChanged

示例：

using System.Windows;
using System.Windows.Media;

imageView.TransformMatrixChanged += (s, matrix) =>
{
	double scaleX = matrix.M11;
	double scaleY = matrix.M22;
	double offsetX = matrix.OffsetX;
	double offsetY = matrix.OffsetY;
};

imageView.VisibleCoordinateRectChanged += (s, rect) =>
{
	Rect visibleRect = rect;
};

默认样式说明

标尺与鼠标叠加层默认外观统一定义在 Themes/Generic.xaml，而不是写死在 ImageView 的属性元数据中。

当前默认样式中已提供以下默认值：

• CornerRadius = 3
• LeftRulerWidth = 48
• TopRulerHeight = 32
• MajorTickPixelSpacing = 36
• MinorTickCount = 5
• ShowRuler = True
• RulerBorderPen = White
• MajorTickPen = White
• MinorTickPenBrush = Gray
• MouseCrosshairPen = DodgerBlue

如需统一调整项目视觉风格，优先改 Themes/Generic.xaml 中的 ImageView 样式。

最近更新摘要

• 去掉 ImageEditor 包装层，业务侧直接使用 ImageView
• 圆角裁剪与边框由 ImageView 自身完成，不再经过模板中的 ClipBorder
• DrawShapeAsync、CurrentDrawingType、视图状态事件都在 ImageView 上
• ShowMousePosition 为真时，同时显示鼠标十字线与坐标文本
• 鼠标离开控件时，自动清除十字线与坐标显示
• 新增标尺位置枚举与可配置停靠能力
• 修复坐标翻转场景下标尺方向映射问题（基于 CoordinateTransformMatrix 判断轴向反转）
• 优化单位文本位置：在横纵标尺交界角优先显示，减少与刻度文本重叠

标尺坐标与翻转行为说明

• VisibleCoordinateRect 用于给出当前可见业务坐标范围。
• 标尺绘制会结合 CoordinateTransformMatrix 判断 X/Y 轴是否发生反转。
• 当存在反转时，横纵标尺采用反向比例映射，保证刻度方向与图像显示一致。
• 单位文本会优先绘制在标尺交界角；若交界角不可用，再回退到原有边缘位置。

依赖说明

当前项目可见依赖包括：

• TianWeiToolsPro.Common
• HalconXL.Dependency.DoNet
• OpenCvSharp4
• OpenCvSharp4.Extensions
• OpenCvSharp4.runtime.win
• System.Drawing.Common

说明

• 该项目为 WPF 控件库，主要面向 Windows 桌面应用。
• 业务侧直接使用 ImageView。
• 若需要感知当前视图缩放、平移或可视区域变化，订阅 ImageView 对外提供的相关事件。
• 图形类型、工具类型与序列化结构以当前源码实现为准。