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 | 使用示例:

Raster source = ...; // large image
Raster 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(Raster source, Raster template)
      Find the best match of a template Raster in the source raster using NCC. 使用 NCC 在源 Raster 中查找模板的最佳匹配。

      Both rasters are converted to BT.601 grayscale before matching.

      匹配前两个 raster 均转换为 BT.601 灰度。

      Parameters:
      source - the source raster | 源 raster
      template - the template raster | 模板 raster
      Returns:
      the best match result | 最佳匹配结果
      Throws:
      NullPointerException - if any argument is null | 任一参数为 null 时抛出
      ImageOperationException - if template is larger than source | 当模板大于源时抛出
      Since:
      opencode-base-image V1.0.4

    • matchAll

      public static List<TemplateMatchOp.MatchResult> matchAll(Raster source, Raster template, double threshold)
      Find all matches of a template Raster in the source raster above a threshold. 在源 Raster 中查找高于阈值的所有模板匹配。
      Parameters:
      source - the source raster | 源 raster
      template - the template raster | 模板 raster
      threshold - the minimum NCC score threshold in [-1, 1] | 最小 NCC 分数阈值
      Returns:
      the list of match results above the threshold | 高于阈值的匹配结果列表
      Throws:
      NullPointerException - if any argument is null | 任一参数为 null 时抛出
      ImageOperationException - if template is larger than source or threshold is invalid | 模板大于源或阈值无效时抛出
      Since:
      opencode-base-image V1.0.4