xhouse/XplorePlane
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

快捷工具处添加比例尺开关

Browse Source
This commit is contained in:
李伟
2026-05-13 09:04:14 +08:00
parent f5f449b6fc
commit b9106acdf0
8 changed files with 392 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
XP.ImageProcessing.Processors/定位识别/TemplateMatchingProcessor.cs
+162 -9
View File
@@ -22,18 +22,44 @@ namespace XP.ImageProcessing.Processors;
/// <summary>
/// 模板匹配算子（定位识别）
/// </summary>
/// <remarks>
/// 算法原理：
/// 模板匹配是一种基于图像块的匹配方法，通过在待搜索图像上滑动模板，
/// 计算每个位置与模板的相似度，找到最佳匹配位置。
///
/// 匹配方法说明：
/// 1. CcoeffNormed (归一化相关系数) - 推荐使用，对光照变化有一定的鲁棒性
/// 公式: corr = Σ(I(x,y) * T(x,y)) / sqrt(ΣI² * ΣT²)
/// 分数范围: -1 ~ 1，值越大越相似
///
/// 2. SqdiffNormed (归一化平方差) - 值越小越相似
/// 公式: diff = Σ(I(x,y) - T(x,y))² / (ΣI² + ΣT²)
/// 分数范围: 0 ~ 1，值越小越相似
///
/// 3. CcorrNormed (归一化相关) - 对模板和图像的亮度变化敏感
/// 4. Ccoeff (相关系数) - 未归一化版本
/// 5. Ccorr (相关) - 未归一化版本
/// 6. Sqdiff (平方差) - 未归一化版本
///
/// 性能说明：
/// - 时间复杂度: O(W * H * w * h)，其中W/H为图像尺寸，w/h为模板尺寸
/// - 可通过设置SearchRegion限制搜索范围来提升性能
/// </remarks>
public class TemplateMatchingProcessor : ImageProcessorBase
{
private static readonly ILogger _logger = Log.ForContext<TemplateMatchingProcessor>();
/// <summary>
/// 匹配方法选项列表，供UI下拉选择
/// </summary>
private static readonly string[] MatchMethodOptions =
{
"CcoeffNormed",
"SqdiffNormed",
"CcorrNormed",
"Ccoeff",
"Ccorr",
"Sqdiff"
"CcoeffNormed", // 归一化相关系数（推荐）
"SqdiffNormed", // 归一化平方差
"CcorrNormed", // 归一化相关
"Ccoeff", // 相关系数
"Ccorr", // 相关
"Sqdiff" // 平方差
};
public TemplateMatchingProcessor()
@@ -42,8 +68,16 @@ public class TemplateMatchingProcessor : ImageProcessorBase
Description = LocalizationHelper.GetString("TemplateMatchingProcessor_Description");
}
/// <summary>
/// 初始化参数定义
/// </summary>
protected override void InitializeParameters()
{
// ===== 模板相关参数 =====
/// <summary>
/// 模板图片路径，支持灰度或彩色图片（自动转灰度）
/// </summary>
Parameters.Add("TemplatePath", new ProcessorParameter(
"TemplatePath",
LocalizationHelper.GetString("TemplateMatchingProcessor_TemplatePath"),
@@ -53,25 +87,36 @@ public class TemplateMatchingProcessor : ImageProcessorBase
null,
LocalizationHelper.GetString("TemplateMatchingProcessor_TemplatePath_Desc")));
/// <summary>
/// 匹配算法选择，不同算法对光照和旋转的敏感度不同
/// </summary>
Parameters.Add("MatchMethod", new ProcessorParameter(
"MatchMethod",
LocalizationHelper.GetString("TemplateMatchingProcessor_MatchMethod"),
typeof(string),
"CcoeffNormed",
"CcoeffNormed", // 默认使用归一化相关系数
null,
null,
LocalizationHelper.GetString("TemplateMatchingProcessor_MatchMethod_Desc"),
MatchMethodOptions));
/// <summary>
/// 匹配阈值，判断匹配是否成功的分数门限
/// - CcoeffNormed/CcorrNormed: 建议 0.75-0.95
/// - SqdiffNormed: 建议 0.1-0.3
/// </summary>
Parameters.Add("MatchThreshold", new ProcessorParameter(
"MatchThreshold",
LocalizationHelper.GetString("TemplateMatchingProcessor_MatchThreshold"),
typeof(double),
0.75,
0.75, // 默认阈值
0.0,
1.0,
LocalizationHelper.GetString("TemplateMatchingProcessor_MatchThreshold_Desc")));
/// <summary>
/// 是否在输出图像上绘制匹配矩形框
/// </summary>
Parameters.Add("DrawRectangle", new ProcessorParameter(
"DrawRectangle",
LocalizationHelper.GetString("TemplateMatchingProcessor_DrawMatch"),
@@ -81,6 +126,9 @@ public class TemplateMatchingProcessor : ImageProcessorBase
null,
LocalizationHelper.GetString("TemplateMatchingProcessor_DrawMatch_Desc")));
/// <summary>
/// 匹配矩形框的线条粗细
/// </summary>
Parameters.Add("RectangleThickness", new ProcessorParameter(
"RectangleThickness",
LocalizationHelper.GetString("TemplateMatchingProcessor_RectThickness"),
@@ -90,6 +138,11 @@ public class TemplateMatchingProcessor : ImageProcessorBase
8,
LocalizationHelper.GetString("TemplateMatchingProcessor_RectThickness_Desc")));
// ===== 搜索区域参数（可选，用于限制搜索范围提升性能）=====
/// <summary>
/// 搜索区域左上角X坐标
/// </summary>
Parameters.Add("SearchRegionX", new ProcessorParameter(
"SearchRegionX",
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegionX"),
@@ -99,6 +152,9 @@ public class TemplateMatchingProcessor : ImageProcessorBase
null,
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegion_Desc")));
/// <summary>
/// 搜索区域左上角Y坐标
/// </summary>
Parameters.Add("SearchRegionY", new ProcessorParameter(
"SearchRegionY",
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegionY"),
@@ -108,6 +164,9 @@ public class TemplateMatchingProcessor : ImageProcessorBase
null,
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegion_Desc")));
/// <summary>
/// 搜索区域宽度，0表示使用整幅图像
/// </summary>
Parameters.Add("SearchRegionWidth", new ProcessorParameter(
"SearchRegionWidth",
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegionWidth"),
@@ -117,6 +176,9 @@ public class TemplateMatchingProcessor : ImageProcessorBase
null,
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegion_Desc")));
/// <summary>
/// 搜索区域高度，0表示使用整幅图像
/// </summary>
Parameters.Add("SearchRegionHeight", new ProcessorParameter(
"SearchRegionHeight",
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegionHeight"),
@@ -129,8 +191,14 @@ public class TemplateMatchingProcessor : ImageProcessorBase
_logger.Debug("InitializeParameters");
}
/// <summary>
/// 执行模板匹配处理
/// </summary>
/// <param name="inputImage">输入的灰度图像</param>
/// <returns>处理后的图像（可选带匹配矩形框）</returns>
public override Image<Gray, byte> Process(Image<Gray, byte> inputImage)
{
// ===== 1. 获取参数 =====
var path = (GetParameter<string>("TemplatePath") ?? string.Empty).Trim();
var methodName = GetParameter<string>("MatchMethod") ?? "CcoeffNormed";
var threshold = GetParameter<double>("MatchThreshold");
@@ -141,10 +209,13 @@ public class TemplateMatchingProcessor : ImageProcessorBase
var searchRw = GetParameter<int>("SearchRegionWidth");
var searchRh = GetParameter<int>("SearchRegionHeight");
// 清除上一次的输出数据
OutputData.Clear();
// 克隆输入图像用于输出（避免修改原图）
var output = inputImage.Clone();
// ===== 2. 参数校验：模板文件 =====
if (string.IsNullOrEmpty(path) || !File.Exists(path))
{
_logger.Warning("TemplateMatching: invalid or missing template file: {Path}", path);
@@ -153,6 +224,7 @@ public class TemplateMatchingProcessor : ImageProcessorBase
return output;
}
// ===== 3. 加载模板图像 =====
using var template = LoadTemplate(path);
if (template == null)
{
@@ -161,17 +233,24 @@ public class TemplateMatchingProcessor : ImageProcessorBase
return output;
}
// ===== 4. 确定搜索区域（ROI）=====
// 如果未指定搜索区域，则使用整幅图像
var searchRoi = ResolveSearchRoi(inputImage.Width, inputImage.Height, searchRx, searchRy, searchRw, searchRh);
var offsetX = searchRoi.X;
var offsetX = searchRoi.X; // 记录ROI偏移，用于还原到全局坐标
var offsetY = searchRoi.Y;
// ===== 5. 在ROI区域内执行模板匹配 =====
Image<Gray, byte>? roiImage = null;
try
{
// 设置输入图像的ROI（感兴趣区域）
inputImage.ROI = searchRoi;
// 复制ROI区域到新图像
roiImage = inputImage.Copy();
// 清除ROI设置
inputImage.ROI = Rectangle.Empty;
// ===== 5.1 校验模板尺寸 =====
if (template.Width > roiImage.Width || template.Height > roiImage.Height)
{
_logger.Warning("TemplateMatching: template larger than search region ({Tw}x{Th} vs {Iw}x{Ih})",
@@ -181,20 +260,34 @@ public class TemplateMatchingProcessor : ImageProcessorBase
return output;
}
// ===== 5.2 执行模板匹配 =====
// OpenCV MatchTemplate 在ROI上滑动模板，计算每个位置的相似度
// 结果是一个 (W-w+1) x (H-h+1) 的分数矩阵
var method = ParseMethod(methodName);
using var resultMat = new Mat();
CvInvoke.MatchTemplate(roiImage, template, resultMat, method);
// ===== 5.3 找到最佳匹配位置 =====
// MinMaxLoc 在分数矩阵中找到最小值和最大值的位置
double minVal = 0, maxVal = 0;
Point minLoc = default, maxLoc = default;
CvInvoke.MinMaxLoc(resultMat, ref minVal, ref maxVal, ref minLoc, ref maxLoc);
// 根据匹配方法选择使用最小值还是最大值
// 平方差类方法：值越小越好（使用minLoc）
// 相关类方法：值越大越好（使用maxLoc）
var useMin = method == TemplateMatchingType.Sqdiff || method == TemplateMatchingType.SqdiffNormed;
var loc = useMin ? minLoc : maxLoc;
var score = useMin ? minVal : maxVal;
// ===== 5.4 判定匹配是否成功 =====
var matched = IsMatchAcceptable(method, minVal, maxVal, threshold);
// ===== 5.5 转换到全局坐标 =====
// 由于是在ROI内匹配的，需要加上ROI的偏移量
var globalLoc = new Point(loc.X + offsetX, loc.Y + offsetY);
// ===== 5.6 输出结果数据 =====
OutputData["Matched"] = matched;
OutputData["MatchScore"] = score;
OutputData["MatchX"] = globalLoc.X;
@@ -203,6 +296,7 @@ public class TemplateMatchingProcessor : ImageProcessorBase
OutputData["TemplateHeight"] = template.Height;
OutputData["MatchMethod"] = methodName;
// ===== 5.7 可选：绘制匹配矩形 =====
if (matched && draw)
{
var rect = new Rectangle(globalLoc.X, globalLoc.Y, template.Width, template.Height);
@@ -216,34 +310,71 @@ public class TemplateMatchingProcessor : ImageProcessorBase
}
finally
{
// 释放ROI图像资源
roiImage?.Dispose();
}
}
/// <summary>
/// 计算实际的搜索ROI区域
/// </summary>
/// <param name="imgW">图像宽度</param>
/// <param name="imgH">图像高度</param>
/// <param name="rx">用户指定的ROI X坐标</param>
/// <param name="ry">用户指定的ROI Y坐标</param>
/// <param name="rw">用户指定的ROI宽度，0表示整幅图像</param>
/// <param name="rh">用户指定的ROI高度，0表示整幅图像</param>
/// <returns>计算后的有效ROI区域</returns>
private static Rectangle ResolveSearchRoi(int imgW, int imgH, int rx, int ry, int rw, int rh)
{
// 宽度或高度为0时，使用整幅图像作为搜索区域
if (rw <= 0 || rh <= 0)
return new Rectangle(0, 0, imgW, imgH);
// 限制坐标在图像范围内
rx = Math.Clamp(rx, 0, Math.Max(0, imgW - 1));
ry = Math.Clamp(ry, 0, Math.Max(0, imgH - 1));
// 限制宽度和高度不超出图像边界
rw = Math.Clamp(rw, 1, Math.Max(1, imgW - rx));
rh = Math.Clamp(rh, 1, Math.Max(1, imgH - ry));
return new Rectangle(rx, ry, rw, rh);
}
/// <summary>
/// 判断匹配结果是否满足阈值条件
/// </summary>
/// <param name="method">匹配方法类型</param>
/// <param name="minVal">最小相似度分数</param>
/// <param name="maxVal">最大相似度分数</param>
/// <param name="threshold">用户设定的阈值</param>
/// <returns>是否满足匹配条件</returns>
/// <remarks>
/// 不同匹配方法的分数含义不同：
/// - 平方差类(Sqdiff/SqdiffNormed): 分数越小越相似，需要 minVal <= threshold
/// - 相关类(Ccoeff/Ccorr/CcoeffNormed/CcorrNormed): 分数越大越相似，需要 maxVal >= threshold
/// </remarks>
private static bool IsMatchAcceptable(TemplateMatchingType method, double minVal, double maxVal, double threshold)
{
return method switch
{
// 平方差类：值越小越好
TemplateMatchingType.SqdiffNormed => minVal <= threshold,
TemplateMatchingType.Sqdiff => minVal <= threshold,
// 相关类：值越大越好
TemplateMatchingType.CcorrNormed or TemplateMatchingType.CcoeffNormed => maxVal >= threshold,
TemplateMatchingType.Ccorr or TemplateMatchingType.Ccoeff => maxVal >= threshold,
// 默认按相关类处理
_ => maxVal >= threshold
};
}
/// <summary>
/// 将字符串方法名转换为OpenCV枚举类型
/// </summary>
/// <param name="name">方法名称字符串</param>
/// <returns>对应的TemplateMatchingType枚举值</returns>
private static TemplateMatchingType ParseMethod(string? name)
{
return name?.Trim() switch
@@ -253,23 +384,45 @@ public class TemplateMatchingProcessor : ImageProcessorBase
"Ccorr" => TemplateMatchingType.Ccorr,
"CcorrNormed" => TemplateMatchingType.CcorrNormed,
"Ccoeff" => TemplateMatchingType.Ccoeff,
// 默认返回归一化相关系数（推荐）
_ => TemplateMatchingType.CcoeffNormed
};
}
/// <summary>
/// 从磁盘加载模板图像并转换为灰度图
/// </summary>
/// <param name="path">模板图片文件路径</param>
/// <returns>灰度模板图像，加载失败返回null</returns>
/// <remarks>
/// 支持的输入格式：
/// - 灰度图像：直接使用
/// - 彩色图像：自动转换为灰度
/// - 支持任意位深度的图像
/// </remarks>
private static Image<Gray, byte>? LoadTemplate(string path)
{
try
{
// 使用任意格式读取（支持灰度、彩色、16位等）
using var raw = CvInvoke.Imread(path, ImreadModes.AnyDepth | ImreadModes.AnyColor);
if (raw.IsEmpty)
return null;
// 创建灰度图像
var templ = new Image<Gray, byte>(raw.Width, raw.Height);
// 根据通道数决定是否需要灰度转换
if (raw.NumberOfChannels == 1)
{
// 已经是灰度图，直接复制
raw.CopyTo(templ.Mat);
}
else
{
// 彩色图转灰度 (BGR -> Gray)
CvInvoke.CvtColor(raw, templ, ColorConversion.Bgr2Gray);
}
return templ;
}