李伟
436 lines
17 KiB
C#
436 lines
17 KiB
C#
// ============================================================================
|
||
// Copyright © 2026 Hexagon Technology Center GmbH. All Rights Reserved.
|
||
// 文件名: TemplateMatchingProcessor.cs
|
||
// 描述: 灰度模板匹配算子，在整幅图像中搜索与模板最相似的位置
|
||
// 功能:
|
||
// - 从磁盘加载模板（灰度或彩色图自动转灰度）
|
||
// - OpenCV MatchTemplate + MinMaxLoc 求最佳匹配
|
||
// - 可选在输出图上绘制匹配矩形
|
||
// - 将匹配结果写入 OutputData（坐标、得分、是否通过阈值）
|
||
// 作者: 李伟 wei.lw.li@hexagon.com
|
||
// ============================================================================
|
||
|
||
using System.Drawing;
|
||
using Emgu.CV;
|
||
using Emgu.CV.CvEnum;
|
||
using Emgu.CV.Structure;
|
||
using XP.ImageProcessing.Core;
|
||
using Serilog;
|
||
|
||
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" // 平方差
|
||
};
|
||
|
||
public TemplateMatchingProcessor()
|
||
{
|
||
Name = LocalizationHelper.GetString("TemplateMatchingProcessor_Name");
|
||
Description = LocalizationHelper.GetString("TemplateMatchingProcessor_Description");
|
||
}
|
||
|
||
/// <summary>
|
||
/// 初始化参数定义
|
||
/// </summary>
|
||
protected override void InitializeParameters()
|
||
{
|
||
// ===== 模板相关参数 =====
|
||
|
||
/// <summary>
|
||
/// 模板图片路径，支持灰度或彩色图片（自动转灰度）
|
||
/// </summary>
|
||
Parameters.Add("TemplatePath", new ProcessorParameter(
|
||
"TemplatePath",
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_TemplatePath"),
|
||
typeof(string),
|
||
string.Empty,
|
||
null,
|
||
null,
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_TemplatePath_Desc")));
|
||
|
||
/// <summary>
|
||
/// 匹配算法选择，不同算法对光照和旋转的敏感度不同
|
||
/// </summary>
|
||
Parameters.Add("MatchMethod", new ProcessorParameter(
|
||
"MatchMethod",
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_MatchMethod"),
|
||
typeof(string),
|
||
"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.0,
|
||
1.0,
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_MatchThreshold_Desc")));
|
||
|
||
/// <summary>
|
||
/// 是否在输出图像上绘制匹配矩形框
|
||
/// </summary>
|
||
Parameters.Add("DrawRectangle", new ProcessorParameter(
|
||
"DrawRectangle",
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_DrawMatch"),
|
||
typeof(bool),
|
||
true,
|
||
null,
|
||
null,
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_DrawMatch_Desc")));
|
||
|
||
/// <summary>
|
||
/// 匹配矩形框的线条粗细
|
||
/// </summary>
|
||
Parameters.Add("RectangleThickness", new ProcessorParameter(
|
||
"RectangleThickness",
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_RectThickness"),
|
||
typeof(int),
|
||
2,
|
||
1,
|
||
8,
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_RectThickness_Desc")));
|
||
|
||
// ===== 搜索区域参数（可选，用于限制搜索范围提升性能）=====
|
||
|
||
/// <summary>
|
||
/// 搜索区域左上角X坐标
|
||
/// </summary>
|
||
Parameters.Add("SearchRegionX", new ProcessorParameter(
|
||
"SearchRegionX",
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegionX"),
|
||
typeof(int),
|
||
0,
|
||
0,
|
||
null,
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegion_Desc")));
|
||
|
||
/// <summary>
|
||
/// 搜索区域左上角Y坐标
|
||
/// </summary>
|
||
Parameters.Add("SearchRegionY", new ProcessorParameter(
|
||
"SearchRegionY",
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegionY"),
|
||
typeof(int),
|
||
0,
|
||
0,
|
||
null,
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegion_Desc")));
|
||
|
||
/// <summary>
|
||
/// 搜索区域宽度，0表示使用整幅图像
|
||
/// </summary>
|
||
Parameters.Add("SearchRegionWidth", new ProcessorParameter(
|
||
"SearchRegionWidth",
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegionWidth"),
|
||
typeof(int),
|
||
0,
|
||
0,
|
||
null,
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegion_Desc")));
|
||
|
||
/// <summary>
|
||
/// 搜索区域高度，0表示使用整幅图像
|
||
/// </summary>
|
||
Parameters.Add("SearchRegionHeight", new ProcessorParameter(
|
||
"SearchRegionHeight",
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegionHeight"),
|
||
typeof(int),
|
||
0,
|
||
0,
|
||
null,
|
||
LocalizationHelper.GetString("TemplateMatchingProcessor_SearchRegion_Desc")));
|
||
|
||
_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");
|
||
var draw = GetParameter<bool>("DrawRectangle");
|
||
var thickness = GetParameter<int>("RectangleThickness");
|
||
var searchRx = GetParameter<int>("SearchRegionX");
|
||
var searchRy = GetParameter<int>("SearchRegionY");
|
||
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);
|
||
OutputData["Matched"] = false;
|
||
OutputData["Message"] = "Template file not found";
|
||
return output;
|
||
}
|
||
|
||
// ===== 3. 加载模板图像 =====
|
||
using var template = LoadTemplate(path);
|
||
if (template == null)
|
||
{
|
||
OutputData["Matched"] = false;
|
||
OutputData["Message"] = "Template load failed";
|
||
return output;
|
||
}
|
||
|
||
// ===== 4. 确定搜索区域（ROI）=====
|
||
// 如果未指定搜索区域，则使用整幅图像
|
||
var searchRoi = ResolveSearchRoi(inputImage.Width, inputImage.Height, searchRx, searchRy, searchRw, searchRh);
|
||
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})",
|
||
template.Width, template.Height, roiImage.Width, roiImage.Height);
|
||
OutputData["Matched"] = false;
|
||
OutputData["Message"] = "Template larger than search region";
|
||
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;
|
||
OutputData["MatchY"] = globalLoc.Y;
|
||
OutputData["TemplateWidth"] = template.Width;
|
||
OutputData["TemplateHeight"] = template.Height;
|
||
OutputData["MatchMethod"] = methodName;
|
||
|
||
// ===== 5.7 可选：绘制匹配矩形 =====
|
||
if (matched && draw)
|
||
{
|
||
var rect = new Rectangle(globalLoc.X, globalLoc.Y, template.Width, template.Height);
|
||
CvInvoke.Rectangle(output, rect, new MCvScalar(255), thickness);
|
||
}
|
||
|
||
_logger.Debug("TemplateMatching: Matched={Matched}, Score={Score}, Origin=({X},{Y}), SearchRoi=({Rx},{Ry},{Rw},{Rh})",
|
||
matched, score, globalLoc.X, globalLoc.Y, searchRoi.X, searchRoi.Y, searchRoi.Width, searchRoi.Height);
|
||
|
||
return output;
|
||
}
|
||
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
|
||
{
|
||
"Sqdiff" => TemplateMatchingType.Sqdiff,
|
||
"SqdiffNormed" => TemplateMatchingType.SqdiffNormed,
|
||
"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;
|
||
}
|
||
catch (Exception ex)
|
||
{
|
||
_logger.Error(ex, "TemplateMatching: failed to load template {Path}", path);
|
||
return null;
|
||
}
|
||
}
|
||
}
|