Class TemplateMatchOp

java.lang.Object
cloud.opencode.base.image.analysis.TemplateMatchOp
public final class TemplateMatchOp extends Object
Template Matching using Normalized Cross-Correlation (NCC) 基于归一化互相关（NCC）的模板匹配

Finds occurrences of a template image within a larger source image by computing the Normalized Cross-Correlation at every valid position. NCC produces a score in [-1, 1] where 1.0 indicates a perfect match.

通过在每个有效位置计算归一化互相关来查找模板图像在较大源图像中的出现。 NCC 产生 [-1, 1] 范围内的分数，1.0 表示完美匹配。

Features | 主要功能:

  • Best-match search: find the single best matching position - 最佳匹配搜索: 查找单个最佳匹配位置
  • Multi-match search: find all positions above a threshold with NMS - 多匹配搜索: 查找所有高于阈值的位置并进行非极大值抑制
  • Grayscale-based comparison for illumination robustness - 基于灰度的比较，对光照具有鲁棒性
  • Non-maximum suppression to eliminate overlapping detections - 非极大值抑制消除重叠检测

Usage Examples | 使用示例:

BufferedImage source = ...; // large image
BufferedImage template = ...; // small template to find

// Find best match
TemplateMatchOp.MatchResult best = TemplateMatchOp.match(source, template);
System.out.printf("Best match at (%d, %d) with score %.4f%n",
    best.x(), best.y(), best.score());

// Find all matches above threshold 0.8
List<TemplateMatchOp.MatchResult> all = TemplateMatchOp.matchAll(source, template, 0.8);
for (TemplateMatchOp.MatchResult m : all) {
    System.out.printf("Match at (%d, %d), score=%.4f%n", m.x(), m.y(), m.score());
}

Performance | 性能特性:

  • Time complexity: O(W * H * tw * th) where (W, H) is source size and (tw, th) is template size - 时间复杂度: O(W * H * tw * th)，(W, H) 为源图像尺寸，(tw, th) 为模板尺寸
  • Space complexity: O(W * H) for the grayscale source and score map - 空间复杂度: O(W * H) 用于灰度源图像和分数图

Security | 安全性:

  • Thread-safe: Yes (stateless, all methods are pure functions) - 线程安全: 是（无状态，所有方法为纯函数）
  • Null-safe: No (null image throws NullPointerException) - 空值安全: 否（null 图像抛出 NullPointerException）
Since:
JDK 25, opencode-base-image V2.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • match

      public static TemplateMatchOp.MatchResult match(BufferedImage source, BufferedImage template)
      Find the best match of a template in the source image using NCC. 使用 NCC 在源图像中查找模板的最佳匹配。

      Both images are converted to grayscale before matching. The method slides the template over every valid position in the source and computes the Normalized Cross-Correlation score.

      匹配前两幅图像均转换为灰度。方法将模板滑过源图像中每个有效位置， 并计算归一化互相关分数。

      Parameters:
      source - the source image to search in | 要搜索的源图像
      template - the template image to find | 要查找的模板图像
      Returns:
      the best match result | 最佳匹配结果
      Throws:
      NullPointerException - if source or template is null | 当源图像或模板为 null 时抛出
      ImageOperationException - if template is larger than source | 当模板大于源图像时抛出

    • matchAll

      public static List<TemplateMatchOp.MatchResult> matchAll(BufferedImage source, BufferedImage template, double threshold)
      Find all matches of a template in the source image above a threshold. 查找源图像中高于阈值的所有模板匹配。

      After computing NCC at every valid position, local maxima above the given threshold are selected. Non-maximum suppression is applied to eliminate overlapping detections within a template-sized neighborhood.

      在每个有效位置计算 NCC 后，选择高于给定阈值的局部极大值。 应用非极大值抑制来消除模板大小邻域内的重叠检测。

      Parameters:
      source - the source image to search in | 要搜索的源图像
      template - the template image to find | 要查找的模板图像
      threshold - the minimum NCC score threshold in [-1, 1] | 最小 NCC 分数阈值，范围 [-1, 1]
      Returns:
      the list of match results above the threshold, sorted by score descending | 高于阈值的匹配结果列表，按分数降序排序
      Throws:
      NullPointerException - if source or template is null | 当源图像或模板为 null 时抛出
      ImageOperationException - if template is larger than source or threshold is invalid | 当模板大于源图像或阈值无效时抛出