TianWeiToolsPro.Controls.Drawing 3.1.4

TianWeiToolsPro.Controls.Drawing

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

当前库的核心思路是：

• ImageView 负责底层图像显示、视口变换、鼠标交互、图形渲染、标尺与鼠标叠加层
• ImageEditor 负责对外包装、模板集成、能力转发与默认样式配置

目标框架

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

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

主要功能

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

核心控件：

• ImageView：底层图像显示与交互控件
• ImageEditor：更适合业务侧直接使用的包装控件

支持的典型能力：

• 图像显示
• 鼠标滚轮缩放
• 拖拽平移
• 图像坐标与控件坐标转换
• 视口矩阵变化通知
• 鼠标像素信息显示

2. 图形绘制与编辑

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

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

• 线段 Line
• 卡尺线 LineCalipers
• 圆 ShapeCircle
• 圆卡尺 CircleCalipers
• 矩形 ShapeRect1 / ShapeRect2
• 椭圆 ShapeEllipse1
• 多边形 ShapePolygon
• 角度测量 AngleMeasure

支持的典型能力：

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

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

近期版本已将原先分散在页面层的坐标标尺、鼠标十字线与坐标显示能力统一收敛到控件库内部，由 ImageView 直接负责渲染，ImageEditor 负责对外暴露配置。

当前支持的能力包括：

• 显示横向/纵向标尺
• 鼠标移动时同时显示十字线与坐标文本
• 鼠标离开控件后自动清除十字线与坐标显示
• 支持图像坐标到业务坐标的变换矩阵显示
• 标尺单位文本自定义
• 标尺位置自定义
• 标尺尺寸、主次刻度密度、画笔样式自定义

可配置项包括：

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

位置枚举：

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

4. 图像数据适配

为了适配不同图像来源，项目中提供了统一的 ImageData 抽象及多种实现，包括：

• BitmapImageData
• WriteableBitmapImageData
• MatImageData
• HObjectImageData
• ActionImageData

便于与 WPF、OpenCvSharp、Halcon 等图像来源进行对接。

5. 图形持久化描述

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

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

常见使用方式

1. 在 XAML 中使用 ImageEditor

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

2. 自定义标尺外观

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

3. 在代码中显示图形

imageEditor.DisplayShape(shape);
imageEditor.DisplayShapes(shapes);
imageEditor.RefreshDisplay();

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

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

5. 订阅视图状态事件

ImageEditor 当前已对外转发内部 ImageView 的视图状态事件，业务层可直接订阅：

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

示例：

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

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

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

默认样式说明

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

这样做的目的：

• 保持 ImageView 更偏底层、通用
• 避免模板绑定时由包装控件空值覆盖内部默认资源
• 让业务侧可以通过样式统一替换默认外观

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

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

如需统一调整项目视觉风格，优先在 ImageEditor.xaml 的样式中修改。

最近更新摘要

结合近期对 TianWeiToolsPro.Controls.Drawing 的调整，目前已完成以下收敛：

• 将视口状态、鼠标位置、十字线与标尺能力集中到 ImageView
• ImageEditor 仅负责包装、转发与模板集成
• ShowMousePosition 为真时，同时显示鼠标十字线与坐标文本
• 鼠标离开控件时，自动清除十字线与坐标显示
• 新增标尺位置枚举与可配置停靠能力
• 新增标尺尺寸、主次刻度密度、画笔等完整外部配置面
• 默认值迁移到 ImageEditor.xaml，避免包装层模板绑定覆盖底层默认资源

依赖说明

当前项目可见依赖包括：

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

说明

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