跳到主要内容

匹配

用于模板、特征、形状和配准匹配,在图像中定位目标。

相关系数匹配​

CCoeffNormed · 可执行

以归一化相关系数在输入图像中定位单个最佳模板位置,并输出带阈值颜色框的 BGR 叠加图。

签名​

var match = CCoeffNormed(templatePath: "templates/part-a.png", acceptScore: 0.8, maximumResponsePixels: 67108864);

输入​

inputImage
  • 输入
  • 必填
  • 约束 必须是非空 CV_8U 图像。允许 1、3 或 4 通道。像素数不超过 16,777,216。
由视觉图上游图像边连接提供;不是节点调用参数。

参数​

templatePathstring
  • 输入
  • 必填
  • 约束 文件必须存在且能解码为图像。解析后的路径必须位于授权根内,且路径链不得经过重解析点。模板宽、高均不得大于输入图像。
模板图像路径;相对路径以视觉资源授权根为基准。
acceptScoredouble
  • 输入
  • 可选
  • 默认 0.8
  • 约束 范围 0–1。score 大于等于阈值时绘制绿色框,否则绘制红色框。
最佳相关系数的接受阈值;只决定叠加框颜色,不会过滤或清空输出。
maximumResponsePixelsint
  • 输入
  • 可选
  • 默认 67108864
  • 约束 范围 1–67,108,864。响应像素数计算为 (input.Width-template.Width+1) × (input.Height-template.Height+1)。默认响应上限为 67,108,864;项目资源策略可能采用更低预算。
MatchTemplate 响应图允许的最大像素数。

输出​

imageImage
与输入同宽高的 CV_8UC3 BGR 叠加图,标出单个最佳模板矩形。
scoredouble
  • 约束 通常位于 -1–1;运行时要求结果为有限数。
最佳 CCoeffNormed 响应值。
xdouble
最佳匹配矩形左上角 X 像素坐标。
ydouble
最佳匹配矩形左上角 Y 像素坐标。
widthdouble
匹配模板宽度(像素)。
heightdouble
匹配模板高度(像素)。

行为​

  • 视觉 SCL 中赋值目标是节点 ID;X、Y 是设计画布坐标,输入图像通过上游连接提供。
  • 输入与模板都会转换为灰度图,再计算 CCoeffNormed 相关响应。
  • 只返回全响应图中的一个最大值位置,不计算次峰、PSR 或峰值裕量。
  • 模板路径缺失、越过授权根、经过重解析点、文件不存在、图像不可解码或模板大于输入时执行失败。

错误与限制​

  • VISION_PIPELINE_PARAMETER_REQUIRED:必需参数缺失。
  • VISION_PIPELINE_PARAMETER_TYPE:参数无法按声明类型解析。
  • VISION_PIPELINE_PARAMETER_RANGE:数值参数超出参数合同范围。
  • VISION_PIPELINE_RESOURCE_LIMIT:输入像素、响应图或临时资源超过上限。

示例​

在上游图像中查找 part-a 模板;match.score、match.x、match.y 等 量测值 由节点 ID 命名。

var match = CCoeffNormed(templatePath: "templates/part-a.png", acceptScore: 0.85, maximumResponsePixels: 16777216);

稀疏光流形变匹配​

DeformableMatch · 可执行

在模板上提取角点,并以金字塔 Lucas-Kanade 光流跟踪到输入图像,输出形变向量叠加图与位移统计。

签名​

var deformation = DeformableMatch(templatePath: "templates/flexible-part.png", maxFeatures: 512, qualityLevel: 0.01, minDistance: 10, windowSize: 15, pyramidLevels: 4);

输入​

inputImage
  • 输入
  • 必填
  • 约束 必须是非空 CV_8U 图像。允许 1、3 或 4 通道。像素数不超过 16,777,216。模板与输入应使用相同宽高;当前版本不会自动统一两者尺寸。
待跟踪场景图像,由视觉图上游图像边连接提供。

参数​

templatePathstring
  • 输入
  • 必填
  • 约束 文件必须存在、可解码,并位于视觉资源授权根内。路径链不得经过重解析点。
用于提取角点的模板图像路径。
maxFeaturesint
  • 输入
  • 可选
  • 默认 512
  • 约束 范围 1–4096。
模板上最多提取的角点数。
qualityLeveldouble
  • 输入
  • 可选
  • 默认 0.01
  • 约束 范围 0.001–1。
角点质量阈值。
minDistanceint
  • 输入
  • 可选
  • 默认 10
  • 单位 px
  • 约束 范围 1–256。
相邻角点的最小距离。
windowSizeint
  • 输入
  • 可选
  • 默认 15
  • 单位 px
  • 约束 范围 3–127。必须为奇数。
光流搜索窗口的宽和高。
pyramidLevelsint
  • 输入
  • 可选
  • 默认 4
  • 约束 范围 1–8。
光流金字塔最大层级。

输出​

imageImage
与输入同宽高的 CV_8UC3 BGR 叠加图,以箭头显示角点位移。
featureCountdouble
模板中提取的角点数。
trackedCountdouble
参与统计的有限位移点数;当前版本不按跟踪状态再次过滤。
medianFlowMagnitudedouble
  • 单位 px
计入点位移模长的中位数。
maxFlowMagnitudedouble
  • 单位 px
计入点位移模长的最大值。
deformationEnergydouble
  • 单位 px
所有计入点位移模长之和。

行为​

  • 模板与输入先转为灰度图,再提取模板角点。
  • 以金字塔 Lucas-Kanade 光流从模板坐标跟踪到输入图像;输出不是稠密光流,也不生成可复用模型。
  • 角点为 0 或没有可计入的有限位移时执行失败。
  • trackedCount 和位移统计只按有限值与幅度上限筛选,不代表经过状态过滤的成功跟踪数。

错误与限制​

  • VISION_PIPELINE_PARAMETER_ODD:windowSize 不是奇数。
  • VISION_PIPELINE_PARAMETER_REQUIRED:必需参数缺失。
  • VISION_PIPELINE_PARAMETER_TYPE:参数无法按声明类型解析。
  • VISION_PIPELINE_PARAMETER_RANGE:数值参数超出参数合同范围。
  • VISION_PIPELINE_RESOURCE_LIMIT:输入像素、响应图或临时资源超过上限。

示例​

以稀疏光流观察柔性零件相对模板的角点位移。

var deformation = DeformableMatch(templatePath: "templates/flexible-part.png", maxFeatures: 800, qualityLevel: 0.02, minDistance: 8, windowSize: 21, pyramidLevels: 4);

BF 特征匹配​

FeatureMatchBrute · 可执行

以 ORB、SIFT 或 AKAZE 提取特征,执行二近邻与 Lowe 比率筛选,再用 RANSAC 单应矩阵定位模板。

签名​

var featureMatch = FeatureMatchBrute(templatePath: "templates/logo.png", detector: "ORB", maxFeatures: 1000, ratioThreshold: 0.75, normType: "Hamming", crossCheck: false, minMatches: 12, ransacThreshold: 3.0);

输入​

inputImage
  • 输入
  • 必填
  • 约束 必须是非空 CV_8U 图像。允许 1、3 或 4 通道。像素数不超过 16,777,216。
待定位场景图像,由视觉图上游图像边连接提供。

参数​

templatePathstring
  • 输入
  • 必填
  • 约束 文件必须存在、可解码,并位于视觉资源授权根内。路径链不得经过重解析点。
特征模板图像路径。
detectorstring
  • 输入
  • 可选
  • 默认 ORB
  • 约束 可选 ORB、SIFT、AKAZE。
特征点与描述子算法。
maxFeaturesint
  • 输入
  • 可选
  • 默认 1000
  • 约束 范围 1–8192。运行时对模板或场景实际描述子数另施加 8192 硬上限。AKAZE 构造路径不消费该值来限制检测器本身。
ORB/SIFT 的最大特征数,并限制最多绘制的匹配线数量。
ratioThresholddouble
  • 输入
  • 可选
  • 默认 0.75
  • 约束 范围 0.1–1。
Lowe 二近邻距离比率阈值。
normTypestring
  • 输入
  • 可选
  • 默认 Hamming
  • 约束 可选 Hamming、L2。ORB 固定使用 Hamming,SIFT/AKAZE 固定使用 L2;normType 不改变算法选择。
公开合同 声明的距离类型。
crossCheckbool
  • 输入
  • 可选
  • 默认 FALSE
  • 约束 当前版本保留该字段,但匹配固定不启用交叉校验。
公开合同 声明的交叉校验开关。
minMatchesint
  • 输入
  • 可选
  • 默认 12
  • 约束 范围 1–8192。FindHomography 实际至少需要 4 对有效点;将值设为 1–3 不能保证执行成功。
Lowe 筛选后继续估计单应矩阵所需的最少匹配数。
ransacThresholddouble
  • 输入
  • 可选
  • 默认 3
  • 单位 px
  • 约束 范围 0.01–32。
RANSAC 单应矩阵重投影阈值。

输出​

imageImage
与输入同宽高的 CV_8UC3 BGR 叠加图,绘制最多 128 条优质匹配线和投影模板四边形。
keypointCountSourcedouble
场景图像检测到的关键点数。
keypointCountTemplatedouble
模板图像检测到的关键点数。
matchCountdouble
通过 Lowe 比率筛选的匹配数。
goodMatchCountdouble
当前与 matchCount 相同,表示 Lowe 筛选后的匹配数。
inlierCountdouble
RANSAC 单应矩阵的内点数。
medianDistancedouble
  • 单位 px
单应投影点到对应场景点距离的中位数。
inlierRatiodouble
inlierCount 与 goodMatchCount 的比值。

行为​

  • 模板和输入先转灰度;检测器分别计算关键点与描述子。
  • 对每个模板描述子取两个近邻并执行 Lowe 比率筛选。
  • ORB 自动使用 Hamming 距离;SIFT 与 AKAZE 自动使用 L2,normType 不改变当前执行路径。
  • 描述子为空、优质匹配少于 minMatches、单应矩阵为空/非有限/退化时执行失败。

错误与限制​

  • VISION_PIPELINE_PARAMETER_REQUIRED:必需参数缺失。
  • VISION_PIPELINE_PARAMETER_ENUM:枚举参数不是参数合同允许值。
  • VISION_PIPELINE_PARAMETER_RANGE:数值参数超出参数合同范围。
  • VISION_PIPELINE_RESOURCE_LIMIT:输入像素、响应图或临时资源超过上限。

示例​

使用 SIFT 描述子定位带透视变化的模板。

var featureMatch = FeatureMatchBrute(templatePath: "templates/logo.png", detector: "SIFT", maxFeatures: 1500, ratioThreshold: 0.7, normType: "L2", crossCheck: false, minMatches: 12, ransacThreshold: 2.5);

FLANN 特征匹配​

FeatureMatchFlann · 可执行

以 SIFT 或 ORB 提取特征,执行近邻搜索与 Lowe 比率筛选,再用 RANSAC 单应矩阵定位模板。

签名​

var featureMatch = FeatureMatchFlann(templatePath: "templates/logo.png", detector: "SIFT", maxFeatures: 1000, ratioThreshold: 0.75, minMatches: 12, ransacThreshold: 3.0, kdTrees: 5);

输入​

inputImage
  • 输入
  • 必填
  • 约束 必须是非空 CV_8U 图像。允许 1、3 或 4 通道。像素数不超过 16,777,216。
待定位场景图像,由视觉图上游图像边连接提供。

参数​

templatePathstring
  • 输入
  • 必填
  • 约束 文件必须存在、可解码,并位于视觉资源授权根内。路径链不得经过重解析点。
特征模板图像路径。
detectorstring
  • 输入
  • 可选
  • 默认 ORB
  • 约束 可选 SIFT、ORB。默认使用 ORB。
特征点与描述子算法。
maxFeaturesint
  • 输入
  • 可选
  • 默认 1000
  • 约束 范围 1–8192。运行时对模板或场景实际描述子数另施加 8192 硬上限。
检测器请求的最大特征数,并限制最多绘制的匹配线数量。
ratioThresholddouble
  • 输入
  • 可选
  • 默认 0.75
  • 约束 范围 0.1–1。
Lowe 二近邻距离比率阈值。
minMatchesint
  • 输入
  • 可选
  • 默认 12
  • 约束 范围 1–8192。FindHomography 实际至少需要 4 对有效点。
Lowe 筛选后继续估计单应矩阵所需的最少匹配数。
ransacThresholddouble
  • 输入
  • 可选
  • 默认 3
  • 单位 px
  • 约束 范围 0.01–32。
RANSAC 单应矩阵重投影阈值。
kdTreesint
  • 输入
  • 可选
  • 默认 5
  • 约束 范围 1–16。当前版本保留 kdTrees 参数,但该值不会改变匹配计算。ORB 模式下 kdTrees 同样不会改变匹配计算。
公开合同 声明的 FLANN KD-tree 数量。

输出​

imageImage
与输入同宽高的 CV_8UC3 BGR 叠加图,绘制最多 128 条优质匹配线和投影模板四边形。
keypointCountSourcedouble
场景图像检测到的关键点数。
keypointCountTemplatedouble
模板图像检测到的关键点数。
matchCountdouble
通过 Lowe 比率筛选的匹配数。
goodMatchCountdouble
当前与 matchCount 相同。
inlierCountdouble
RANSAC 单应矩阵的内点数。
medianDistancedouble
  • 单位 px
单应投影点到对应场景点距离的中位数。
inlierRatiodouble
inlierCount 与 goodMatchCount 的比值。

行为​

  • 模板和输入先转灰度;检测器分别计算关键点与描述子。
  • 匹配器对每个模板描述子取两个近邻,执行 Lowe 比率筛选后用 RANSAC 求单应矩阵。
  • 描述子为空、优质匹配少于 minMatches、单应矩阵为空/非有限/退化时执行失败。

错误与限制​

  • VISION_PIPELINE_PARAMETER_REQUIRED:必需参数缺失。
  • VISION_PIPELINE_PARAMETER_ENUM:枚举参数不是参数合同允许值。
  • VISION_PIPELINE_PARAMETER_RANGE:数值参数超出参数合同范围。
  • VISION_PIPELINE_RESOURCE_LIMIT:输入像素、响应图或临时资源超过上限。

示例​

以 SIFT 浮点描述子和默认 FLANN 匹配器定位模板。

var featureMatch = FeatureMatchFlann(templatePath: "templates/logo.png", detector: "SIFT", maxFeatures: 2000, ratioThreshold: 0.7, minMatches: 16, ransacThreshold: 2.5, kdTrees: 5);

ECC 图像配准​

ImageRegistration · 可执行

以模板图像为参考,用 ECC 求平移、欧氏、仿射或单应变换,并输出配准后的灰度图。

签名​

var registered = ImageRegistration(templatePath: "templates/reference.png", motionType: "Euclidean", maxIterations: 1000, terminationEpsilon: 0.000001, gaussianSigma: 0.0, pyramidLevels: 1);

输入​

inputImage
  • 输入
  • 必填
  • 约束 必须是非空 CV_8U 图像。允许 1、3 或 4 通道。像素数不超过 16,777,216。
待配准图像,由视觉图上游图像边连接提供。

参数​

templatePathstring
  • 输入
  • 必填
  • 约束 文件必须存在、可解码,并位于视觉资源授权根内。路径链不得经过重解析点。若模板尺寸不同,运行时会将其缩放到输入尺寸。
参考模板图像路径。
motionTypestring
  • 输入
  • 可选
  • 默认 Euclidean
  • 约束 可选 Translation、Euclidean、Affine、Homography。
ECC 估计使用的运动模型。
maxIterationsint
  • 输入
  • 可选
  • 默认 1000
  • 约束 范围 1–10000。
ECC 终止条件的最大迭代次数。
terminationEpsilondouble
  • 输入
  • 可选
  • 默认 0.000001
  • 约束 范围 1e-8–1。
ECC 终止条件的相关系数增量阈值。
gaussianSigmadouble
  • 输入
  • 可选
  • 默认 0
  • 约束 范围 0–10。值大于 0 时先四舍五入,再调整为不小于 3 的奇数滤波尺寸;值为 0 时滤波尺寸为 5。
控制 ECC 预滤波尺寸;该值不是高斯标准差。
pyramidLevelsint
  • 输入
  • 可选
  • 默认 1
  • 约束 范围 1–8。当前只执行单层 ECC;pyramidLevels 不改变配准计算。
公开合同 声明的金字塔层数。

输出​

imageImage
  • 约束 返回图像为单通道;请按实际返回通道数处理。
与输入同宽高的 CV_8UC1 灰度配准图。
correlationdouble
ECC 的最终相关系数,必须为有限数。
iterationsdouble
写回配置的 maxIterations,不是 ECC 实际迭代次数。
epsilondouble
写回配置的 terminationEpsilon。
transformTypedouble
当前写回 motionType 文本长度,不是运动模型枚举值。

行为​

  • 输入和模板转灰度并归一化为 CV_32FC1;模板尺寸不同则缩放到输入尺寸。
  • Translation、Euclidean、Affine 使用 2×3 变换矩阵,Homography 使用 3×3 矩阵。
  • ECC 未收敛时返回配准失败并保留原始错误消息。
  • 当前 pyramidLevels 不执行多层求解;返回图像为单通道灰度图。

错误与限制​

  • VISION_PIPELINE_PARAMETER_REQUIRED:必需参数缺失。
  • VISION_PIPELINE_PARAMETER_ENUM:枚举参数不是参数合同允许值。
  • VISION_PIPELINE_PARAMETER_RANGE:数值参数超出参数合同范围。
  • VISION_PIPELINE_RESOURCE_LIMIT:输入像素、响应图或临时资源超过上限。

示例​

以仿射 ECC 将上游图像对齐到 reference.png。

var registered = ImageRegistration(templatePath: "templates/reference.png", motionType: "Affine", maxIterations: 1500, terminationEpsilon: 0.0000001, gaussianSigma: 5.0, pyramidLevels: 1);

互信息模板匹配​

MutualInfo · 可执行

以离散联合直方图计算模板与场景滑窗的互信息,返回互信息最大的单个位置及 BGR 叠加图。

签名​

var miMatch = MutualInfo(templatePath: "templates/reference.png", histogramBins: 32, stride: 4, maximumResponsePixels: 4194304);

输入​

inputImage
  • 输入
  • 必填
  • 约束 必须是非空 CV_8U 图像。允许 1、3 或 4 通道。像素数不超过 16,777,216。
待搜索场景图像,由视觉图上游图像边连接提供。

参数​

templatePathstring
  • 输入
  • 必填
  • 约束 文件必须存在、可解码,并位于视觉资源授权根内。路径链不得经过重解析点。模板宽、高均不得大于输入图像。
用于互信息比较的模板图像路径。
histogramBinsint
  • 输入
  • 可选
  • 默认 32
  • 约束 范围 8–256。较大值会按平方增加每个滑窗的联合直方图工作量和内存。
单图直方图每轴的分箱数;联合直方图包含 bins² 个单元。
strideint
  • 输入
  • 可选
  • 默认 4
  • 单位 px
  • 约束 范围 1–32。
滑窗在 X、Y 方向的采样步长。
maximumResponsePixelsint
  • 输入
  • 可选
  • 默认 4194304
  • 约束 范围 1–4,194,304。上限检查使用未除以 stride 的完整响应宽×高。
完整响应域允许的最大像素数。

输出​

imageImage
与输入同宽高的 CV_8UC3 BGR 叠加图,以绿色矩形标出互信息最大位置。
bestMiScoredouble
最佳滑窗的互信息 H(template)+H(window)-H(joint)。
xdouble
最佳滑窗左上角 X 像素坐标。
ydouble
最佳滑窗左上角 Y 像素坐标。
entropySourcedouble
模板图像熵。
entropyTemplatedouble
最佳场景窗口熵。

行为​

  • 输入和模板转为灰度;像素值量化到 histogramBins 个分箱。
  • 运行时按 stride 遍历场景窗口,自实现边缘概率分布和二维联合直方图,并选择最大互信息位置。
  • maximumResponsePixels 在步长采样前按完整响应域检查,不能通过增大 stride 绕过硬上限。
  • entropySource 当前表示模板熵,entropyTemplate 当前表示最佳场景窗口熵。

错误与限制​

  • VISION_PIPELINE_PARAMETER_REQUIRED:必需参数缺失。
  • VISION_PIPELINE_PARAMETER_RANGE:数值参数超出参数合同范围。
  • VISION_PIPELINE_RESOURCE_LIMIT:输入像素、响应图或临时资源超过上限。

示例​

以互信息在上游灰度场景中搜索参考模板。

var miMatch = MutualInfo(templatePath: "templates/thermal-reference.png", histogramBins: 32, stride: 8, maximumResponsePixels: 1048576);

NCC 模板匹配​

NccMatch · 可执行

以六种相关模式执行单尺度模板匹配,返回单个最佳位置、次峰分数和 BGR 叠加图。

签名​

var ncc = NccMatch(templatePath: "templates/part-a.png", method: "CCoeffNormed", acceptScore: 0.8, peakExclusionRadius: 8, maximumResponsePixels: 67108864);

输入​

inputImage
  • 输入
  • 必填
  • 约束 必须是非空 CV_8U 图像。允许 1、3 或 4 通道。像素数不超过 16,777,216。
待搜索场景图像,由视觉图上游图像边连接提供;不是节点调用参数。

参数​

templatePathstring
  • 输入
  • 必填
  • 约束 文件必须存在且能解码为图像。解析后的路径必须位于授权根内,且路径链不得经过重解析点。模板宽、高均不得大于输入图像。
模板图像路径;相对路径以视觉资源授权根为基准。
methodstring
  • 输入
  • 可选
  • 默认 CCoeffNormed
  • 约束 可选 SqDiff、SqDiffNormed、CCorr、CCorrNormed、CCoeff、CCoeffNormed。
相关匹配模式。
acceptScoredouble
  • 输入
  • 可选
  • 默认 0.8
  • 约束 范围 0–1。score 大于等于阈值时绘制绿色框,否则绘制红色框。
归一化后最佳分数的接受阈值;只决定叠加框颜色,不过滤输出。
peakExclusionRadiusint
  • 输入
  • 可选
  • 默认 8
  • 单位 px
  • 约束 范围 1–1024。该值作用于响应图坐标,不是输入图像中的模板矩形外扩距离。
计算 secondBestScore 时,以最佳位置为圆心排除的响应图半径。
maximumResponsePixelsint
  • 输入
  • 可选
  • 默认 67108864
  • 约束 范围 1–67,108,864。响应像素数计算为 (input.Width-template.Width+1) × (input.Height-template.Height+1)。默认响应上限为 67,108,864;项目资源策略可能采用更低预算。
MatchTemplate 响应图允许的最大像素数。

输出​

imageImage
与输入同宽高的 CV_8UC3 BGR 叠加图,标出单个最佳模板矩形。
scoredouble
最佳响应转换后的有限分数;SqDiff 两种模式为 1-minValue,其余模式为 maxValue。
xdouble
最佳匹配矩形左上角 X 像素坐标。
ydouble
最佳匹配矩形左上角 Y 像素坐标。
widthdouble
匹配模板宽度(像素)。
heightdouble
匹配模板高度(像素)。
secondBestScoredouble
排除最佳位置附近圆形区域后,按同一模式转换得到的次优响应分数。

行为​

  • 视觉 SCL 中赋值目标是节点 ID;X、Y 是设计画布坐标,输入图像通过上游连接提供。
  • 输入与模板都会转换为灰度图,再计算所选匹配模式的响应。
  • SqDiff 和 SqDiffNormed 选择最小响应并写回 1-minValue;其余模式选择最大响应。
  • 只返回一个最佳位置;secondBestScore 仅排除最佳响应点附近圆形区域,不计算 PSR。
  • templatePath 缺失、越过授权根、经过重解析点、文件不存在、图像不可解码或模板大于输入时执行失败。

错误与限制​

  • VISION_PIPELINE_PARAMETER_REQUIRED:必需参数缺失。
  • VISION_PIPELINE_PARAMETER_ENUM:枚举参数不是参数合同允许值。
  • VISION_PIPELINE_PARAMETER_TYPE:参数无法按声明类型解析。
  • VISION_PIPELINE_PARAMETER_RANGE:数值参数超出参数合同范围。
  • VISION_PIPELINE_RESOURCE_LIMIT:输入像素、响应图或临时资源超过上限。

示例​

以归一化互相关在上游图像中查找 part-a 模板,并写回 ncc.score、ncc.secondBestScore 和位置尺寸。

var ncc = NccMatch(templatePath: "templates/part-a.png", method: "CCorrNormed", acceptScore: 0.85, peakExclusionRadius: 12, maximumResponsePixels: 16777216);

形状特征可视化​

ShapeModelCreate · 可执行

从输入图像提取 Shi-Tomasi 角点与 Canny 边缘,生成形状特征的 BGR 可视化及点数、边缘像素数和图像尺寸测量。

签名​

var modelView = ShapeModelCreate(maxFeatures: 512, qualityLevel: 0.01, minDistance: 10, cannyThreshold1: 50.0, cannyThreshold2: 200.0, render: "Both");

输入​

inputImage
  • 输入
  • 必填
  • 约束 必须是非空 CV_8U 图像。允许 1、3 或 4 通道。像素数不超过 16,777,216。
用于提取角点和边缘的图像,由视觉图上游图像边连接提供。

参数​

maxFeaturesint
  • 输入
  • 可选
  • 默认 512
  • 约束 范围 1–4096。
最多返回的角点数。
qualityLeveldouble
  • 输入
  • 可选
  • 默认 0.01
  • 约束 范围 0.001–1。
角点质量阈值。
minDistanceint
  • 输入
  • 可选
  • 默认 10
  • 单位 px
  • 约束 范围 1–256。
相邻角点的最小距离。
cannyThreshold1double
  • 输入
  • 可选
  • 默认 50
  • 约束 范围 0–1000。
Canny 边缘检测的第一个阈值。
cannyThreshold2double
  • 输入
  • 可选
  • 默认 200
  • 约束 范围 0–1000。公开合同 未声明 cannyThreshold1 与 cannyThreshold2 的大小关系。
Canny 边缘检测的第二个阈值。
renderstring
  • 输入
  • 可选
  • 默认 Both
  • 约束 可选 Points、Edges、Both。
选择叠加角点、边缘或两者。

输出​

imageImage
与输入同宽高的 CV_8UC3 BGR 叠加图;边缘为红色,角点为黄色圆点。
featurePointCountdouble
检测到的角点数。
edgePixelCountdouble
Canny 二值边缘图中的非零像素数。
templateWidthdouble
输入灰度图宽度(像素)。
templateHeightdouble
输入灰度图高度(像素)。

行为​

  • 输入先转换为灰度图,再分别提取角点和 Canny 边缘。
  • render=Points 只绘制角点,render=Edges 只绘制边缘,render=Both 同时绘制两者。
  • 该算子只输出角点和边缘可视化,不创建或保存可复用模型。
  • ShapeModelFind 与该输出没有模型句柄依赖;查找算子独立从 templatePath 加载模板。

错误与限制​

  • VISION_PIPELINE_PARAMETER_TYPE:参数无法按声明类型解析。
  • VISION_PIPELINE_PARAMETER_ENUM:枚举参数不是参数合同允许值。
  • VISION_PIPELINE_PARAMETER_RANGE:数值参数超出参数合同范围。
  • VISION_PIPELINE_RESOURCE_LIMIT:输入像素、响应图或临时资源超过上限。

示例​

在上游零件图像上叠加 Canny 边缘与 Shi-Tomasi 角点,并写回特征统计。

var modelView = ShapeModelCreate(maxFeatures: 800, qualityLevel: 0.02, minDistance: 8, cannyThreshold1: 40.0, cannyThreshold2: 160.0, render: "Both");

形状查找​

ShapeModelFind · 可执行

在图像金字塔上按角度和尺度旋转缩放模板,以 CCoeffNormed 搜索单个最佳位置,并输出分数、姿态和 BGR 叠加图。

签名​

var shape = ShapeModelFind(templatePath: "templates/contour.png", angleStart: -180.0, angleExtent: 360.0, angleStep: 1.0, scaleMin: 0.5, scaleMax: 2.0, scaleStep: 0.25, pyramidLevels: 4, acceptScore: 0.7, maxMatches: 10, maximumResponsePixels: 67108864);

输入​

inputImage
  • 输入
  • 必填
  • 约束 必须是非空 CV_8U 图像。允许 1、3 或 4 通道。像素数不超过 16,777,216。
待搜索场景图像,由视觉图上游图像边连接提供。

参数​

templatePathstring
  • 输入
  • 必填
  • 约束 文件必须存在、可解码,并位于视觉资源授权根内。路径链不得经过重解析点。
参与角度和尺度扫描的模板图像路径。
angleStartdouble
  • 输入
  • 可选
  • 默认 -180
  • 单位 deg
  • 约束 范围 -360–360。
角度扫描起点。
angleExtentdouble
  • 输入
  • 可选
  • 默认 360
  • 单位 deg
  • 约束 公开合同 数值范围为 0–720,关系校验要求严格大于 0。
从 angleStart 起的角度扫描范围。
angleStepdouble
  • 输入
  • 可选
  • 默认 1
  • 单位 deg
  • 约束 范围 0.01–90。必须小于等于 angleExtent。
角度扫描步长。
scaleMindouble
  • 输入
  • 可选
  • 默认 0.5
  • 约束 范围 0.1–2。不得大于 scaleMax。
模板尺度扫描下界。
scaleMaxdouble
  • 输入
  • 可选
  • 默认 2
  • 约束 范围 0.1–4。
模板尺度扫描上界。
scaleStepdouble
  • 输入
  • 可选
  • 默认 0.25
  • 约束 范围 0.01–1。必须落在 (0, scaleMax-scaleMin] 区间。
模板尺度扫描步长。
pyramidLevelsint
  • 输入
  • 可选
  • 默认 4
  • 约束 范围 1–8。
从高层到原分辨率尝试的图像金字塔层数。
acceptScoredouble
  • 输入
  • 可选
  • 默认 0.7
  • 约束 范围 0–1。某层 bestScore 大于阈值时不再扫描更低金字塔层。
提前结束金字塔搜索、框颜色和 matchCount 的接受阈值。
maxMatchesint
  • 输入
  • 可选
  • 默认 10
  • 约束 范围 1–1024。当前只返回一个最佳点,maxMatches 不会产生 Top-N 结果。
最大匹配数预算。
maximumResponsePixelsint
  • 输入
  • 可选
  • 默认 67108864
  • 约束 范围 1–67,108,864。
每个金字塔层、尺度和角度组合的 MatchTemplate 响应图最大像素数。

输出​

imageImage
与输入同宽高的 CV_8UC3 BGR 叠加图,以轴对齐矩形标出单个最佳位置。
bestScoredouble
所有已扫描组合中的最佳 CCoeffNormed 分数。
bestXdouble
最佳位置映射回原输入分辨率后的左上角 X 坐标。
bestYdouble
最佳位置映射回原输入分辨率后的左上角 Y 坐标。
bestAngledouble
  • 单位 deg
最佳模板旋转角度。
bestScaledouble
最佳模板缩放因子。
matchCountdouble
当前实现只写 0 或 1:bestScore 达到 acceptScore 时为 1,否则为 0。

行为​

  • 输入与模板转灰度;场景按 pyramidLevels 从高层向原分辨率扫描。
  • 每个尺度模板先缩放并下采样,再在固定画布内旋转,随后以 CCoeffNormed 运行 MatchTemplate。
  • 某层最佳分数大于 acceptScore 后提前结束金字塔循环;当前实现不做子像素或局部姿态精化。
  • 最终叠加框按 bestScale 重建为轴对齐矩形,不绘制旋转四边形。
  • 当前只返回单个最佳点;maxMatches 仅参与资源预算,未形成多结果合同。

错误与限制​

  • VISION_PIPELINE_PARAMETER_REQUIRED:必需参数缺失。
  • VISION_PIPELINE_PARAMETER_TYPE:参数无法按声明类型解析。
  • VISION_PIPELINE_PARAMETER_RANGE:数值参数超出参数合同范围。
  • VISION_PIPELINE_PARAMETER_RELATION:参数之间的关系不满足参数合同。
  • VISION_PIPELINE_RESOURCE_LIMIT:输入像素、响应图或临时资源超过上限。

示例​

在有限角度和尺度范围内搜索 contour 模板,并写回最佳姿态与阈值命中数。

var shape = ShapeModelFind(templatePath: "templates/contour.png", angleStart: -45.0, angleExtent: 90.0, angleStep: 1.0, scaleMin: 0.8, scaleMax: 1.2, scaleStep: 0.1, pyramidLevels: 4, acceptScore: 0.75, maxMatches: 10, maximumResponsePixels: 16777216);

多尺度模板匹配​

TemplateMatchScaled · 可执行

在指定尺度区间逐步缩放模板,以 CCoeffNormed 搜索单个最佳位置,并输出最佳尺度、位置、尺寸和 BGR 叠加图。

签名​

var scaledMatch = TemplateMatchScaled(templatePath: "templates/part-a.png", scaleMin: 0.5, scaleMax: 2.0, scaleStep: 0.1, acceptScore: 0.8, maximumResponsePixels: 67108864);

输入​

inputImage
  • 输入
  • 必填
  • 约束 必须是非空 CV_8U 图像。允许 1、3 或 4 通道。像素数不超过 16,777,216。
待搜索场景图像,由视觉图上游图像边连接提供。

参数​

templatePathstring
  • 输入
  • 必填
  • 约束 文件必须存在、可解码,并位于视觉资源授权根内。路径链不得经过重解析点。
参与多尺度扫描的模板图像路径。
scaleMindouble
  • 输入
  • 可选
  • 默认 0.5
  • 约束 范围 0.1–2。不得大于 scaleMax。
模板尺度扫描下界。
scaleMaxdouble
  • 输入
  • 可选
  • 默认 2
  • 约束 范围 0.1–4。
模板尺度扫描上界。
scaleStepdouble
  • 输入
  • 可选
  • 默认 0.1
  • 约束 范围 0.01–1。必须落在 (0, scaleMax-scaleMin] 区间。
模板尺度扫描步长。
acceptScoredouble
  • 输入
  • 可选
  • 默认 0.8
  • 约束 范围 0–1。bestScore 大于等于阈值时绘制绿色框,否则绘制红色框。
最佳 CCoeffNormed 分数的接受阈值;只决定叠加框颜色,不过滤输出。
maximumResponsePixelsint
  • 输入
  • 可选
  • 默认 67108864
  • 约束 范围 1–67,108,864。默认响应上限为 67,108,864;项目资源策略可能采用更低预算。
每个合法尺度的 MatchTemplate 响应图允许的最大像素数。

输出​

imageImage
与输入同宽高的 CV_8UC3 BGR 叠加图,标出最佳缩放模板矩形。
bestScoredouble
所有合法尺度中的最佳 CCoeffNormed 分数。
bestScaledouble
产生 bestScore 的模板缩放因子。
xdouble
最佳匹配矩形左上角 X 像素坐标。
ydouble
最佳匹配矩形左上角 Y 像素坐标。
widthdouble
最佳缩放模板宽度(像素)。
heightdouble
最佳缩放模板高度(像素)。

行为​

  • 输入与模板转灰度;模板在 scaleMin 到 scaleMax 的闭区间内按 scaleStep 逐步缩放。
  • 缩放宽高经四舍五入并至少取 1 像素;大于输入的尺度样本被跳过。
  • 每个合法尺度用 Area 插值缩放模板,再运行 CCoeffNormed MatchTemplate。
  • 只返回全尺度扫描中的一个最佳位置,不计算旋转、次峰或 PSR。
  • 所有尺度都大于输入、没有合法矩形或最佳分数非有限值时执行失败。

错误与限制​

  • VISION_PIPELINE_PARAMETER_REQUIRED:必需参数缺失。
  • VISION_PIPELINE_PARAMETER_TYPE:参数无法按声明类型解析。
  • VISION_PIPELINE_PARAMETER_RANGE:数值参数超出参数合同范围。
  • VISION_PIPELINE_PARAMETER_RELATION:参数之间的关系不满足参数合同。
  • VISION_PIPELINE_RESOURCE_LIMIT:输入像素、响应图或临时资源超过上限。

示例​

在 0.8–1.2 倍范围内搜索 part-a 模板,并写回最佳尺度、位置和尺寸。

var scaledMatch = TemplateMatchScaled(templatePath: "templates/part-a.png", scaleMin: 0.8, scaleMax: 1.2, scaleStep: 0.05, acceptScore: 0.85, maximumResponsePixels: 16777216);