识别
用于模板定位、特征匹配、标记识别和图像配准。
ArUco 标记检测
ArucoMarkerDetect · 可执行
按指定字典检测 ArUco/AprilTag 标记,绘制四边形并输出首个标记及几何测量。
签名
var markers = ArucoMarkerDetect(dictionary: "Dict4X4_50", cornerRefinementMethod: "None", maximumMarkers: 256);
输入
inputImage- 待检测的非空 8-bit 灰度或 BGR 图像。
参数
dictionarystring- 预定义标记字典。
cornerRefinementMethodstring- 角点细化方法。
maximumMarkersint- 本节点允许返回的最大标记数。
输出
outputImage- 绘制标记边框和 ID 的 BGR 图像。
measurements量测值集合- 节点前缀键:markerCount、firstMarkerId、firstCenterX、firstCenterY、totalPerimeter;无标记时 ID 与中心为 -1。
行为
- 按中心 Y、中心 X、ID 和原始序号对检测结果稳定排序。
- 校验每个 ID 位于所选字典容量内,且四角构成图像内的非退化凸四边形。
- 未检测到标记时返回未绘制标记的 BGR 图像和零计数;不修改输入图像。
错误与限制
VISION_PIPELINE_PARAMETER_ENUM:dictionary 或 cornerRefinementMethod 不是 参数合同 允许值。VISION_WAVEB_INPUT_TYPE_UNSUPPORTED:输入不是非空 8-bit 灰度/BGR 图像。VISION_WAVEB_RESULT_LIMIT_EXCEEDED:检测数超过 maximumMarkers。VISION_WAVEB_DEGENERATE_GEOMETRY:ID 越出字典容量,或角点/ID 数量和四边形几何无效。VISION_WAVEB_INPUT_LIMIT_EXCEEDED:输入像素数超过 16777216。
示例
使用 4x4_50 字典和亚像素角点细化检测标记。
var markers = ArucoMarkerDetect(dictionary: "Dict4X4_50", cornerRefinementMethod: "Subpix", maximumMarkers: 256);
ArUco 标记位姿估计
ArucoMarkerPoseEstimate · 可执行
检测指定字典的 ArUco/AprilTag 标记,并根据相机内参和标记边长估计旋转、平移向量。
签名
var pose = ArucoMarkerPoseEstimate(dictionary: "Dict4X4_50", markerLength: 0.05, fx: 700, fy: 700, cx: 319.5, cy: 239.5, maximumMarkers: 256);
输入
inputImage- 非空 8-bit 灰度或 BGR 图像。
参数
dictionarystring- 预定义标记字典。
markerLengthdouble- 标记实际边长。
fxdouble- 相机水平方向焦距。
fydouble- 相机垂直方向焦距。
cxdouble- 主点 X 坐标。
cydouble- 主点 Y 坐标。
maximumMarkersint- 允许检测的最大标记数。
输出
outputImage- 绘制全部检测边框,并在第一个成功解算标记中心绘制圆圈的 BGR 图像。
measurements量测值集合- 节点前缀键:markerCount、solvedCount、firstMarkerId、firstRvecX/Y/Z、firstTvecX/Y/Z;无标记时仅保证 markerCount=0。
行为
- 假定畸变系数为零,使用四个平面角点和 SolvePnP Iterative 解算位姿。
- 单个标记解算失败时继续处理其他标记;solvedCount 只统计成功项。
- 未检测到标记时返回输入的 BGR 投影和 markerCount=0;不修改输入图像。
错误与限制
VISION_PIPELINE_PARAMETER_REQUIRED:markerLength、fx 或 fy 缺失。VISION_PIPELINE_PARAMETER_RANGE:内参、标记边长、主点或 maximumMarkers 超出 参数合同 范围。ARGUMENT_EXCEPTION:输入不是非空 8-bit 灰度/BGR 图像。VISION_PIPELINE_RESOURCE_LIMIT:检测数超过 maximumMarkers。
示例
以 50 mm 标记和 640×480 相机主点估计位姿。
var pose = ArucoMarkerPoseEstimate(dictionary: "Dict4X4_50", markerLength: 0.05, fx: 700, fy: 700, cx: 319.5, cy: 239.5, maximumMarkers: 256);
AverageHash 图像指纹
AverageHashFingerprint · 可执行
计算固定 64-bit AverageHash 亮度均值指纹,并以两个 32-bit 测量值输出。
签名
var fingerprint = AverageHashFingerprint();
输入
inputImage- 非空 8-bit 灰度、BGR 或 BGRA 图像。
参数
无参数。
输出
outputImage- 输入图像的独立克隆;像素内容不变。
measurements量测值集合- 节点前缀键:hashHigh32、hashLow32、hashBitCount(恒为 64)、oneBits。高低 32 位按大端字节顺序组装。
行为
- 先转灰度,再调用 视觉运行时 AverageHash 生成恰好 8 字节的指纹。
- AverageHash 可能使不同常量图像碰撞,只适合相似性粗筛,不是加密散列或唯一身份。
- 四个 量测值 键必须在调用前均不存在;提交失败会回滚本次写入。
错误与限制
ARGUMENT_EXCEPTION:输入为空,或不是 8-bit 1/3/4 通道图像。INVALID_DATA_EXCEPTION:轴长越界、视觉运行时 指纹不是连续 8 字节,或目标 量测值 键已存在。VISION_PIPELINE_RESOURCE_LIMIT:输入像素数超过 16777216 或静态输出预算不足。
示例
计算图像 64-bit AverageHash,并从 量测值s 读取高低 32 位。
var fingerprint = AverageHashFingerprint();
CamShift 颜色跟踪定位
CamShiftLocate · 可执行
从种子区域建立 HSV 色相直方图,以 CamShift 估计目标旋转矩形并输出质量测量。
签名
var location = CamShiftLocate(seedX: 0, seedY: 0, seedWidth: 640, seedHeight: 480, hueBins: 32, minimumSaturation: 32, minimumValue: 32, maximumIterations: 20, epsilon: 1);
输入
inputImage- 非空 8-bit BGR 三通道图像。
参数
seedXint- 种子 ROI 左上角 X。
seedYint- 种子 ROI 左上角 Y。
seedWidthint- 种子 ROI 宽度。
seedHeightint- 种子 ROI 高度。
hueBinsint- 色相直方图分箱数。
minimumSaturationint- 参与建模和反投影的最小饱和度。
minimumValueint- 参与建模和反投影的最小亮度。
maximumIterationsint- CamShift/MeanShift 最大迭代次数。
epsilondouble- 终止位移阈值。
输出
outputImage- 在输入 BGR 图像克隆上绘制定位椭圆。
measurements量测值集合- 节点前缀键:centerX、centerY、width、height、angleDegrees、backProjectionMass、finalWindowBackProjectionMass、finalWindowMassRatio、rotatedRectMassRatio、rotatedRectSupportCoverageRatio、meanShiftIterations、meanShiftIterationRatio、meanShiftCenterDisplacementPixels。
行为
- 仅使用满足 saturation/value 门限的种子像素建立归一化色相直方图。
- CamShift 结果和最终窗口必须有限、非空且位于输入边界内,否则 fail-closed。
- 额外执行 MeanShift 计算迭代比和中心偏移质量指标;不修改输入图像。
错误与限制
VISION_PIPELINE_PARAMETER_RANGE:ROI、直方图、门限或终止参数超出 参数合同 范围。VISION_PIPELINE_PARAMETER_RELATION:seed ROI 没有完整落在输入图像内。ARGUMENT_EXCEPTION:输入不是 8-bit BGR 三通道图像。INVALID_DATA_EXCEPTION:种子有效像素/直方图/反投影为空,或定位结果、质量测量无效。
示例
从 120×90 像素种子区域跟踪颜色目标。
var location = CamShiftLocate(seedX: 100, seedY: 80, seedWidth: 120, seedHeight: 90, hueBins: 32, minimumSaturation: 32, minimumValue: 32, maximumIterations: 20, epsilon: 1);
HSV 彩色模板匹配
ColorTemplateMatch · 可执行
在 HSV 三个通道分别执行归一化模板匹配,返回最佳通道、位置和各通道得分。
签名
var match = ColorTemplateMatch(templatePath: "template.png", method: "CCoeffNormed", acceptScore: 0.7, maximumResponsePixels: 16777216);
输入
inputImage- 非空 8-bit BGR 或 BGRA 图像。
参数
templatePathstring- 授权资源根内的 8-bit BGR/BGRA 模板路径。
methodstring- 视觉运行时 归一化模板匹配模式。
acceptScoredouble- 结果框颜色使用的得分阈值;不是失败门。
maximumResponsePixelsint- 单通道匹配响应图允许的最大像素数。
输出
outputImage- 在最佳位置绘制绿色或红色模板矩形的 BGR 图像。
measurements量测值集合- 节点前缀键:score、x、y、bestChannel(H=0/S=1/V=2)、channelScoreH、channelScoreS、channelScoreV。
行为
- 输入和模板转换到 HSV 后,H/S/V 三通道独立匹配;CCorr/CCoeff 取最大值,SqDiff 取最小值。
- score 仅用于选择位置和结果框颜色,不会因低于 acceptScore 抛错。
- 响应图像素数超过预算时 fail-closed;不修改输入图像。
错误与限制
VISION_PIPELINE_PARAMETER_REQUIRED:templatePath 缺失或为空。VISION_PIPELINE_PARAMETER_ENUM:method 不是允许的归一化模式。ARGUMENT_EXCEPTION:输入不是非空 8-bit BGR/BGRA 图像。INVALID_DATA_EXCEPTION:模板类型无效、模板大于输入或未产生有限得分。VISION_PIPELINE_RESOURCE_LIMIT:响应图像素数超过 maximumResponsePixels。
示例
在授权模板上执行 HSV 分通道相关匹配。
var match = ColorTemplateMatch(templatePath: "template.png", method: "CCoeffNormed", acceptScore: 0.7, maximumResponsePixels: 16777216);
轮廓形状匹配
ContourShapeMatch · 可执行
将二值输入中的外轮廓与参考图最大轮廓按 Hu moments 或 ShapeContext 距离匹配。
签名
var match = ContourShapeMatch(referencePath: "shape.png", method: "I1", minimumContourArea: 16, minimumContourPerimeter: 0.000001, maximumScore: 0.25, maximumComponents: 256, maximumPoints: 65536);
输入
inputImage- 非空 8-bit 单通道二值图像。
参数
referencePathstring- 授权资源根内的参考图像路径;转灰度后必须是 0/255 二值图。
methodstring- 轮廓距离方法。
minimumContourAreadouble- 参与匹配的最小轮廓面积。
minimumContourPerimeterdouble- 参与匹配的最小闭合周长。
maximumScoredouble- 接受结果的最大距离;仅影响 accepted 和绘制颜色。
maximumComponentsint- 输入或参考图允许的最大连通域/候选轮廓数。
maximumPointsint- 每张图所有候选轮廓允许的总点数。
输出
outputImage- 在输入二值图的 BGR 投影上绘制最佳轮廓;接受为绿色,拒绝为红色。
measurements量测值集合- 节点前缀键:score、accepted、matchedArea、matchedCenterX、matchedCenterY、matchedPointCount。
行为
- 参考图选择面积最大的合格外轮廓,输入图对全部合格外轮廓计算距离并选择最低分。
- I1/I2/I3 使用 视觉运行时 MatchShapes;ShapeContext 固定重采样 64 点,并要求显式 maximumScore。
- 没有合格轮廓、Hu 公共有效分量或有限 ShapeContext 距离时 fail-closed;不隐式二值化。
错误与限制
VISION_PIPELINE_PARAMETER_REQUIRED:referencePath 缺失,或 ShapeContext 未显式提供 maximumScore。VISION_PIPELINE_PARAMETER_RELATION:maximumPoints 小于 maximumComponents×3,或 ShapeContext 组件上限超过 32。ARGUMENT_EXCEPTION:输入不是 8-bit 单通道图像。INVALID_DATA_EXCEPTION:图像非严格二值、轮廓退化或没有有限匹配分数。VISION_PIPELINE_RESOURCE_LIMIT:连通域或轮廓点数超过 maximumComponents/maximumPoints。
示例
以 I1 Hu 距离匹配参考二值轮廓。
var match = ContourShapeMatch(referencePath: "shape.png", method: "I1", minimumContourArea: 16, minimumContourPerimeter: 0.000001, maximumScore: 0.25, maximumComponents: 256, maximumPoints: 65536);
ECC 图像配准
EccImageRegister · 可执行
以增强相关系数最大化估计平移、欧氏、仿射或单应变换,并将输入配准到参考图。
签名
var registered = EccImageRegister(referencePath: "reference.png", motionModel: "Affine", maximumIterations: 100, epsilon: 0.000001, gaussianFilterSize: 5, minimumCorrelation: 0.8, pyramidLevels: 1, pyramidScale: 0.5);
输入
inputImage- 非空且有灰度纹理的 8-bit 灰度、BGR 或 BGRA 图像。
参数
referencePathstring- 授权资源根内、与输入同尺寸且有纹理的参考图像路径。
motionModelstring- 待估计的运动模型。
maximumIterationsint- 每层 ECC 最大迭代次数。
epsilondouble- ECC 收敛精度。
gaussianFilterSizeint- ECC 内部高斯滤波核。
minimumCorrelationdouble- 接受配准结果的最小相关系数。
pyramidLevelsint- 由粗到细的图像金字塔层数。
pyramidScaledouble- 相邻金字塔层缩放比。
输出
outputImage- 按估计逆映射变换到输入尺寸的配准图像,边界以 0 填充。
measurements量测值集合- 节点前缀键:correlation、m00、m01、m02、m10、m11、m12、m20、m21、m22。非单应模型最后一行固定为 0,0,1。
行为
- 输入和参考图转为 [0,1] 浮点灰度;多层模式从最粗层向原分辨率传播变换。
- 相关系数低于 minimumCorrelation、纹理过平、ECC 不收敛或矩阵退化时 fail-closed。
- Homography 还验证四角分母同号,拒绝地平线穿过图像域或角点映射异常。
错误与限制
VISION_PIPELINE_PARAMETER_REQUIRED:referencePath 或 motionModel 缺失。VISION_PIPELINE_PARAMETER_ODD:gaussianFilterSize 不是 1–31 的奇数。VISION_PIPELINE_PARAMETER_RELATION:金字塔层数、缩放比、输入尺寸和迭代工作量组合无效。VISION_ECC_IMAGE_REGISTER_DID_NOT_CONVERGE:任一 ECC native 调用未收敛。VISION_ECC_HOMOGRAPHY_HORIZON_CROSSES_IMAGE_DOMAIN:单应地平线穿过闭合图像域。INVALID_DATA_EXCEPTION:参考图不同尺寸、纹理不足、相关性不足或变换矩阵无效。
示例
以三层金字塔执行仿射 ECC 配准。
var registered = EccImageRegister(referencePath: "reference.png", motionModel: "Affine", maximumIterations: 100, epsilon: 0.000001, gaussianFilterSize: 5, minimumCorrelation: 0.8, pyramidLevels: 3, pyramidScale: 0.5);
Haar 人眼检测
EyeDetectHaar · 可执行
加载授权 Haar 级联 XML,以多尺度分类器检测人眼矩形。
签名
var eyes = EyeDetectHaar(cascadePath: "haarcascade_eye.xml", scaleFactor: 1.1, minNeighbors: 3, minimumObjectWidth: 16, minimumObjectHeight: 16, maximumDetections: 512);
输入
inputImage- 非空 8-bit 灰度、BGR 或 BGRA 图像。
参数
cascadePathstring- 授权资源根内的 Haar 级联 XML 路径。
scaleFactordouble- 相邻检测尺度的缩放因子。
minNeighborsint- 保留候选所需的最小邻居数。
minimumObjectWidthint- 最小检测宽度。
minimumObjectHeightint- 最小检测高度。
maximumDetectionsint- 允许的最大检测数。
输出
outputImage- 以青色矩形绘制检测结果的 BGR 图像。
measurements量测值集合- 节点前缀键:eyeCount、firstX、firstY、firstWidth、firstHeight、totalArea;无检测时 firstX/firstY=-1,尺寸和面积为 0。
行为
- 输入先转灰度,再以 ScaleImage 模式调用 Haar 多尺度分类器。
- 未检测到目标时正常返回零计数,不伪造矩形。
- 级联文件无法加载或检测数超过上限时 fail-closed;不修改输入图像。
错误与限制
VISION_PIPELINE_PARAMETER_REQUIRED:cascadePath 缺失或为空。VISION_PIPELINE_PARAMETER_RANGE:尺度、邻居数、最小尺寸或结果上限越界。ARGUMENT_EXCEPTION:输入不是非空 8-bit 1/3/4 通道图像。INVALID_DATA_EXCEPTION:Haar 级联 XML 无法加载。VISION_PIPELINE_RESOURCE_LIMIT:检测数超过 maximumDetections。
示例
用授权眼部级联模型检测人眼。
var eyes = EyeDetectHaar(cascadePath: "haarcascade_eye.xml", scaleFactor: 1.1, minNeighbors: 3, minimumObjectWidth: 16, minimumObjectHeight: 16, maximumDetections: 512);
Haar 人脸检测
FaceDetectHaar · 可执行
加载授权 Haar 级联 XML,以多尺度分类器检测人脸矩形。
签名
var faces = FaceDetectHaar(cascadePath: "haarcascade_frontalface_default.xml", scaleFactor: 1.1, minNeighbors: 3, minimumObjectWidth: 24, minimumObjectHeight: 24, maximumDetections: 256);
输入
inputImage- 非空 8-bit 灰度、BGR 或 BGRA 图像。
参数
cascadePathstring- 授权资源根内的 Haar 级联 XML 路径。
scaleFactordouble- 相邻检测尺度的缩放因子。
minNeighborsint- 保留候选所需的最小邻居数。
minimumObjectWidthint- 最小检测宽度。
minimumObjectHeightint- 最小检测高度。
maximumDetectionsint- 允许的最大检测数。
输出
outputImage- 以绿色矩形绘制检测结果的 BGR 图像。
measurements量测值集合- 节点前缀键:faceCount、firstX、firstY、firstWidth、firstHeight、totalArea;无检测时 firstX/firstY=-1,尺寸和面积为 0。
行为
- 输入先转灰度,再以 ScaleImage 模式调用 Haar 多尺度分类器。
- 未检测到目标时正常返回零计数,不伪造矩形。
- 级联文件无法加载或检测数超过上限时 fail-closed;不修改输入图像。
错误与限制
VISION_PIPELINE_PARAMETER_REQUIRED:cascadePath 缺失或为空。VISION_PIPELINE_PARAMETER_RANGE:尺度、邻居数、最小尺寸或结果上限越界。ARGUMENT_EXCEPTION:输入不是非空 8-bit 1/3/4 通道图像。INVALID_DATA_EXCEPTION:Haar 级联 XML 无法加载。VISION_PIPELINE_RESOURCE_LIMIT:检测数超过 maximumDetections。
示例
用授权正面人脸级联模型检测人脸。
var faces = FaceDetectHaar(cascadePath: "haarcascade_frontalface_default.xml", scaleFactor: 1.1, minNeighbors: 3, minimumObjectWidth: 24, minimumObjectHeight: 24, maximumDetections: 256);
ORB 特征模板匹配
FeatureTemplateMatch · 可执行
使用 ORB、比率筛选与 RANSAC 单应性定位模板区域。
签名
var region = FeatureTemplateMatch(fastThreshold: 20, levels: 8, maxFeatures: 1000, minInlierRatio: 0.5, minInliers: 8, minMatches: 12, ransacThreshold: 3, ratioThreshold: 0.75, scaleFactor: 1.2, templatePath: "template.png");
输入
inputImage- 待定位模板的非空 8-bit 灰度、BGR 或 BGRA 输入图像。
参数
templatePathstring- 授权资源根内的模板图像路径。
maxFeaturesint- ORB 最大特征数。
scaleFactordouble- ORB 金字塔缩放因子。
levelsint- ORB 金字塔层数。
fastThresholdint- ORB FAST 阈值。
ratioThresholddouble- KNN Lowe 比率阈值。
minMatchesint- 进入单应性估计的最小匹配数。
ransacThresholddouble- RANSAC 重投影阈值。
minInliersint- 接受定位的最小内点数。
minInlierRatiodouble- 接受定位的最小内点比例。
输出
outputImage- 绘制投影模板四边形的 BGR 图像。
measurements量测值集合- 节点前缀键:matchCount、inlierCount、inlierRatio、regionArea。
行为
- 模板和场景都必须产生非空 ORB 描述子。
- KNN 比率筛选后使用 RANSAC 单应性,并按内点数和比例 fail-closed。
- 不修改输入图像。
错误与限制
VISION_PIPELINE_PARAMETER_REQUIRED:templatePath 缺失或为空。VISION_PIPELINE_PARAMETER_RANGE:ORB、比率筛选、RANSAC 或内点门参数超出 参数合同 范围。INVALID_OPERATION_EXCEPTION:描述子为空、有效匹配数不足、单应矩阵退化、内点不足或投影区域无效。UNAUTHORIZED_ACCESS_EXCEPTION:templatePath 不能解析到授权资源根内。
示例
使用默认 ORB 与 RANSAC 质量门定位授权模板。
var region = FeatureTemplateMatch(fastThreshold: 20, levels: 8, maxFeatures: 1000, minInlierRatio: 0.5, minInliers: 8, minMatches: 12, ransacThreshold: 3, ratioThreshold: 0.75, scaleFactor: 1.2, templatePath: "template.png");
Ballard 广义霍夫平移定位
GeneralizedHoughBallardLocate · 可执行
以 Ballard 广义霍夫变换在单通道图像中执行受限平移定位和确定性候选抑制。
签名
var location = GeneralizedHoughBallardLocate(templatePath: "template.png", cannyLowThreshold: 50, cannyHighThreshold: 100, dp: 1, minDist: 1, levels: 360, votesThreshold: 100, maximumCandidates: 64, maximumTemplateEdgePoints: 262144, maximumInputEdgePoints: 1048576, maximumVoteOperations: 268435456, maximumRawCandidates: 16384);
输入
inputImage- 非空 8-bit 单通道输入图像。
参数
templatePathstring- 授权资源根内的非空 8-bit 单通道模板。
cannyLowThresholdint- Canny 低阈值。
cannyHighThresholdint- Canny 高阈值。
dpdouble- 位置累加器分辨率反比。
minDistdouble- Darra 确定性 NMS 的最小中心距离。
levelsint- Ballard 方向量化级数。
votesThresholdint- 中心候选最小票数。
maximumCandidatesint- NMS 后允许的最大候选数。
maximumTemplateEdgePointsint- 模板边缘点预算。
maximumInputEdgePointsint- 输入边缘点预算。
maximumVoteOperationsint- 模板边缘点×输入边缘点的工作量预算。
maximumRawCandidatesint- native 原始候选预算。
输出
outputImage- 绘制最佳模板矩形和中心十字的 BGR 图像。
measurements量测值集合- 节点前缀键:found、centerX、centerY、scale(恒 1)、angleDegrees(恒 0)、centerVotes、candidateCount、rawCandidateCount、secondCenterVotes、centerVoteMargin、bestCenterVoteShare、meanRetainedCenterVotes。
行为
- 该实现只做平移定位,不搜索旋转或尺度;scale 恒为 1,angleDegrees 恒为 0。
- 候选按票数降序、Y/X/原序号稳定排序,再按 minDist 执行确定性 NMS。
- 无输入边缘或无候选时正常返回 found=0;工作量或结果超过显式预算时 fail-closed。
错误与限制
VISION_PIPELINE_PARAMETER_RELATION:Canny 阈值顺序、候选上限或票数/边缘预算关系无效。ARGUMENT_EXCEPTION:输入或模板不是非空 8-bit 单通道图像。INVALID_DATA_EXCEPTION:模板无边缘,模板大于输入,或 native 候选形态/值无效。VISION_PIPELINE_RESOURCE_LIMIT:图像、边缘点、投票操作数或候选数超过对应上限。
示例
以 8 像素 NMS 距离执行受限平移定位。
var location = GeneralizedHoughBallardLocate(templatePath: "template.png", cannyLowThreshold: 50, cannyHighThreshold: 100, dp: 1, minDist: 8, levels: 360, votesThreshold: 100, maximumCandidates: 64, maximumTemplateEdgePoints: 262144, maximumInputEdgePoints: 1048576, maximumVoteOperations: 268435456, maximumRawCandidates: 16384);
Guil 广义霍夫旋转尺度定位
GeneralizedHoughGuilLocate · 可执行
以 Guil 广义霍夫变换在受控旋转、尺度范围内定位模板,并对计算量和候选数实施硬预算。
签名
var location = GeneralizedHoughGuilLocate(templatePath: "template.png", cannyLowThreshold: 30, cannyHighThreshold: 110, dp: 3, minDist: 10, maxBufferSize: 256, xi: 90, levels: 360, angleEpsilon: 1, minAngle: 0, maxAngle: 360, angleStep: 1, angleThreshold: 1500, minScale: 0.5, maxScale: 2, scaleStep: 0.05, scaleThreshold: 50, positionThreshold: 10, maximumTemplateEdgePoints: 262144, maximumInputEdgePoints: 1048576, maximumFeaturePairOperations: 268435456, maximumFeatureComparisons: 268435456, maximumRawCandidates: 16384, maximumCandidates: 64);
输入
inputImage- 非空 8-bit 单通道输入图像。
参数
templatePathstring- 授权资源根内的非空 8-bit 单通道模板。
cannyLowThresholdint- Canny 低阈值。
cannyHighThresholdint- Canny 高阈值。
dpdouble- 位置累加器分辨率反比。
minDistdouble- Darra 确定性 NMS 的最小中心距离。
maxBufferSizeint- 每个方向层的特征缓冲上限。
xidouble- 特征对方向差。
levelsint- 方向量化级数。
angleEpsilondouble- 方向差容差。
minAngledouble- 最小搜索角度。
maxAngledouble- 最大搜索角度。
angleStepdouble- 角度分箱步长。
angleThresholdint- 角度候选票数阈值。
minScaledouble- 最小搜索尺度。
maxScaledouble- 最大搜索尺度。
scaleStepdouble- 尺度分箱步长。
scaleThresholdint- 尺度候选票数阈值。
positionThresholdint- 位置候选票数阈值。
maximumTemplateEdgePointsint- 模板边缘点预算。
maximumInputEdgePointsint- 输入边缘点预算。
maximumFeaturePairOperationsint- 特征对构建预算。
maximumFeatureComparisonsint- 旋转/尺度特征比较预算。
maximumRawCandidatesint- native 原始候选预算。
maximumCandidatesint- NMS 后允许的最大候选数。
输出
outputImage- 绘制最佳旋转缩放矩形和中心十字的 BGR 图像。
measurements量测值集合- 节点前缀键:found、centerX、centerY、scale、angleDegrees、positionVotes、scaleVotes、angleVotes、candidateCount。
行为
- 在 minAngle..maxAngle 和 minScale..maxScale 内搜索,并在 native 调用前估算特征对、比较次数和原始候选上界。
- 候选按位置票、尺度票、角度票降序后按位置/尺度/角度稳定排序,再按 minDist 执行 NMS。
- 该结果是受限旋转/尺度定位,不承诺无界遮挡、透视形变或亚像素 shape model。
错误与限制
VISION_PIPELINE_PARAMETER_RELATION:Canny 顺序、角度/尺度区间、分箱数、xi 容差或候选上限关系无效。ARGUMENT_EXCEPTION:输入或模板类型无效,或浮点参数非有限。INVALID_DATA_EXCEPTION:模板无边缘、模板大于输入,或 native 候选形态/值无效。VISION_PIPELINE_RESOURCE_LIMIT:图像、边缘点、特征对、比较次数或候选数超过对应上限。
示例
在 0–30°、0.8–1.2 倍尺度内执行受限旋转尺度定位。
var location = GeneralizedHoughGuilLocate(templatePath: "template.png", cannyLowThreshold: 30, cannyHighThreshold: 110, dp: 3, minDist: 10, maxBufferSize: 256, xi: 90, levels: 360, angleEpsilon: 1, minAngle: 0, maxAngle: 30, angleStep: 1, angleThreshold: 1500, minScale: 0.8, maxScale: 1.2, scaleStep: 0.05, scaleThreshold: 50, positionThreshold: 10, maximumTemplateEdgePoints: 262144, maximumInputEdgePoints: 1048576, maximumFeaturePairOperations: 268435456, maximumFeatureComparisons: 268435456, maximumRawCandidates: 16384, maximumCandidates: 64);
HOG 行人检测
PedestrianDetectHog · 可执行
使用 视觉运行时 默认行人 SVM 检测器和 HOG 多尺度滑窗输出行人矩形。
签名
var pedestrians = PedestrianDetectHog(hitThreshold: 0, winStride: 8, padding: 8, scale: 1.05, finalThreshold: 2, maximumDetections: 512);
输入
inputImage- 非空 8-bit 灰度、BGR 或 BGRA 图像。
参数
hitThresholddouble- SVM 检测窗口命中阈值。
winStridedouble- 水平和垂直滑窗步长。
paddingdouble- 水平和垂直检测 padding。
scaledouble- 图像金字塔相邻尺度因子。
finalThresholddouble- 传给 视觉运行时 groupThreshold 的值;执行时转换为 Int32。
maximumDetectionsint- 允许的最大检测数。
输出
outputImage- 以黄色矩形绘制行人候选的 BGR 图像。
measurements量测值集合- 节点前缀键:pedestrianCount、firstX、firstY、firstWidth、firstHeight、totalArea;无检测时 firstX/firstY=-1。
行为
- 输入先转灰度,再使用 视觉运行时 默认 64×128 行人检测器执行多尺度检测。
- 未检测到行人时正常返回零计数;不输出置信权重。
- 检测数超过 maximumDetections 时 fail-closed;不修改输入图像。
错误与限制
VISION_PIPELINE_PARAMETER_RANGE:HOG 阈值、步长、padding、尺度或结果上限越界。ARGUMENT_EXCEPTION:输入不是非空 8-bit 1/3/4 通道图像,或 winStride/scale 关系无效。VISION_PIPELINE_RESOURCE_LIMIT:检测数超过 maximumDetections。
示例
用 视觉运行时 默认 HOG/SVM 配置检测行人候选。
var pedestrians = PedestrianDetectHog(hitThreshold: 0, winStride: 8, padding: 8, scale: 1.05, finalThreshold: 2, maximumDetections: 512);
相位相关配准
PhaseCorrelationRegister · 可执行
将输入与授权参考图转为浮点灰度,通过相位相关估计纯平移,并把输入反向平移到参考图坐标系。
签名
var registered = PhaseCorrelationRegister(referencePath: "reference.png", window: "Hann", minimumResponse: 0.1);
输入
inputImage- 待配准的非空 8-bit 灰度、BGR 或 BGRA 图像。
参数
referencePathstring- 授权资源根内的参考图像路径。
windowstring- 相位相关前应用的窗口类型。
minimumResponsedouble- 接受平移估计的最小相位相关响应。
输出
outputImage- 按估计位移反向 WarpAffine 到输入尺寸的配准图像,边界以 0 填充。
measurements量测值集合- 节点前缀键:shiftX、shiftY、response。shiftX/shiftY 是从参考图到输入图的估计位移。
行为
- 输入和参考图转为 [0,1] 的 CV_32FC1 灰度;Hann 模式使用同尺寸 Hanning 窗。
- 视觉运行时.PhaseCorrelate 估计参考图到输入图的位移,输出以 -shiftX/-shiftY 对输入执行线性仿射变换。
- 响应低于 minimumResponse、位移或响应非有限、参考图无效或尺寸不一致时 fail-closed;不修改输入和参考图。
错误与限制
VISION_PIPELINE_PARAMETER_REQUIRED:referencePath 缺失或为空。VISION_PIPELINE_PARAMETER_ENUM:window 不是 Hann 或 None。VISION_PIPELINE_PARAMETER_RANGE:minimumResponse 超出 0.000001–1。ARGUMENT_EXCEPTION:输入不是非空 8-bit 灰度/BGR/BGRA 图像,或 Hann 模式的输入宽高不都大于 1。INVALID_DATA_EXCEPTION:参考图类型或尺寸无效,位移/响应非有限,或响应低于 minimumResponse。UNAUTHORIZED_ACCESS_EXCEPTION:referencePath 不能解析到授权资源根内。VISION_PIPELINE_RESOURCE_LIMIT:参考资源、输出或 native/managed 工作区超过资源计划上限。OPERATION_CANCELED_EXCEPTION:取消令牌在资源读取、相位相关或输出提交前触发。
示例
SCL 教程示例:用 Hann 窗配准同尺寸参考图,并拒绝响应低于 0.05 的结果。
var registered = PhaseCorrelationRegister(referencePath: "reference.png", window: "Hann", minimumResponse: 0.05);
参考图像差分
ReferenceDiff · 可执行
将输入与授权参考图逐通道比较并生成阈值差异掩膜。
签名
var mask = ReferenceDiff(alignmentRule: "RequireSameSize", iterations: 1, kernelSize: 3, morphology: "None", referencePath: "golden.png", threshold: 25);
输入
inputImage- 非空 8-bit 灰度、BGR 或 BGRA 输入图像。
参数
referencePathstring- 授权资源根内的参考图像路径。
alignmentRulestring- 输入与参考图尺寸不一致时的处理规则。
thresholddouble- 绝对差异二值化阈值。
morphologystring- 差异掩膜的可选后处理。
kernelSizeint- Open/Close 的矩形核边长。
iterationsint- 形态学迭代次数。
输出
outputImage- 单通道二值差异掩膜。
measurements量测值集合- 节点前缀键:changedPixels、changedRatio、blueMaximumDifference、blueMeanDifference、blueThresholdExceededRatio、greenMaximumDifference、greenMeanDifference、greenThresholdExceededRatio、redMaximumDifference、redMeanDifference、redThresholdExceededRatio。灰度输入复用同一平面,BGRA 的 alpha 不参与统计。
行为
- RequireSameSize 在尺寸不一致时拒绝;ResizeReferenceToInput 以 Linear 插值对齐参考图。
- 单通道掩膜按灰度绝对差生成;逐通道统计输出 B/G/R 最大差、平均差和超阈值比例,BGRA 的 alpha 被忽略。
- 输入和参考图各自受 16777216 像素硬上限与资源计划约束;不修改输入和参考图像。
错误与限制
VISION_PIPELINE_PARAMETER_REQUIRED:referencePath 或 alignmentRule 缺失。VISION_PIPELINE_PARAMETER_ENUM:alignmentRule 或 morphology 不是 参数合同 允许值。VISION_PIPELINE_PARAMETER_RANGE:threshold、kernelSize 或 iterations 超出 参数合同 范围。VISION_PIPELINE_PARAMETER_ODD:kernelSize 不是 1–255 的奇数。ARGUMENT_EXCEPTION:输入不是非空 8-bit 灰度/BGR/BGRA 图像,或 RequireSameSize 下参考图尺寸不同。INVALID_DATA_EXCEPTION:参考图不是支持的图像类型,或规划后参考资源内容发生变化。UNAUTHORIZED_ACCESS_EXCEPTION:referencePath 不能解析到授权资源根内。VISION_PIPELINE_RESOURCE_LIMIT:输入或参考图超过 16777216 像素,或资源、工作区、输出、测量预算不足。OPERATION_CANCELED_EXCEPTION:取消令牌在资源读取、逐通道统计、形态学或提交前触发。
示例
SCL 教程示例:按同尺寸规则和默认阈值生成参考图像差异掩膜。
var mask = ReferenceDiff(alignmentRule: "RequireSameSize", iterations: 1, kernelSize: 3, morphology: "None", referencePath: "golden.png", threshold: 25);
归一化模板匹配
TemplateMatch · 可执行
用指定模板执行归一化模板匹配,输出最佳位置、得分和峰值质量测量。
签名
var match = TemplateMatch(acceptScore: 0.8, maximumResponsePixels: 16777216, method: "CCoeffNormed", peakExclusionRadius: 8, templatePath: "template.png");
输入
inputImage- 非空 8-bit 灰度、BGR 或 BGRA 输入图像。
参数
templatePathstring- 授权资源根内的模板图像路径。
methodstring- 归一化匹配模式。
acceptScoredouble- 决定结果框颜色的接受得分。
peakExclusionRadiusint- 计算次优峰和 PSR 时排除最佳峰的半径。
maximumResponsePixelsint- 匹配响应图允许的最大像素数。
输出
outputImage- 在最佳匹配矩形上绘制接受或拒绝颜色的 BGR 图像。
measurements量测值集合- 节点前缀键:score、x、y、secondBestScore、peakMargin、psr。
行为
- SqDiffNormed 以 1-minValue 转换为越大越好的得分;CCorrNormed 和 CCoeffNormed 使用 maxValue。
- 以 peakExclusionRadius 屏蔽最佳峰邻域后计算 secondBestScore、peakMargin 和 psr;无旁瓣时返回有限零质量值。
- 模板经授权资源根解析,响应图在 native 分配前受 maximumResponsePixels 限制;acceptScore 只控制框色,不构成失败门;不修改输入图像。
错误与限制
VISION_PIPELINE_PARAMETER_REQUIRED:templatePath 缺失或为空。VISION_PIPELINE_PARAMETER_ENUM:method 不是 SqDiffNormed、CCorrNormed 或 CCoeffNormed。VISION_PIPELINE_PARAMETER_RANGE:acceptScore、peakExclusionRadius 或 maximumResponsePixels 超出 参数合同 范围。ARGUMENT_EXCEPTION:输入不是非空 8-bit 灰度/BGR/BGRA 图像,或模板尺寸大于输入。INVALID_OPERATION_EXCEPTION:最佳得分、次优得分、峰值差或旁瓣统计不是有限值。UNAUTHORIZED_ACCESS_EXCEPTION:templatePath 不能解析到授权资源根内。VISION_PIPELINE_RESOURCE_LIMIT:响应图超过 maximumResponsePixels,或模板资源、输出、工作区、测量预算不足。
示例
SCL 教程示例:使用授权资源根中的模板,以默认归一化方法和质量参数执行匹配。
var match = TemplateMatch(acceptScore: 0.8, maximumResponsePixels: 16777216, method: "CCoeffNormed", peakExclusionRadius: 8, templatePath: "template.png");