AI-on-the-edge-device 对齐参数详解SearchFieldY 参考搜索区域Y 方向的原理与调优【免费下载链接】AI-on-the-edge-deviceEasy to use device for connecting old measuring units (water, power, gas, ...) to the digital world项目地址: https://gitcode.com/GitHub_Trending/ai/AI-on-the-edge-device导读本文围绕 AI-on-the-edge-device 固件中[Alignment]段的SearchFieldY参数展开它定义了在校准对齐阶段程序以参考点为中心、在Y 方向高度上搜索参考图像reference的范围。文章将结合ClassFlowAlignment.cpp、CFindTemplate.cpp等源码解释该参数如何决定搜索窗口的尺寸、为何其计算耗时随搜索区域大小呈二次方增长并给出贴近实际部署的配置与调优建议。读完本文你将理解该专家参数背后的模板匹配原理能够在保证对齐精度的前提下把计算开销压到最低。1. 参数速览SearchFieldY是 AI-on-the-edge-device 固件中负责图像校准Alignment环节的一个配置项基本信息如下项目内容参数名SearchFieldY所属配置段[Alignment]文档默认值20单位像素Pixels参数类型Expert Parameter专家参数普通 UI 中默认隐藏作用以参考点target为中心在 Y 方向垂直方向、即搜索区域的高度上搜索参考图像的半宽范围它和兄弟参数SearchFieldX见 param-docs/parameter-pages/Alignment/SearchFieldX.md共同构成一个以参考点为中心的矩形搜索窗口SearchFieldX决定窗口在 X 方向的左右延伸SearchFieldY决定窗口在 Y 方向的上下延伸。⚠️专家参数警告该参数在文档中明确标注为 Expert Parameter见 param-docs/expert-params.txt 中的列表只在完全理解其行为时才建议修改。改动不当可能导致参考模板匹配失败或对齐偏差。2. SearchFieldY 解决什么问题参考搜索区域的 Y 向范围AI-on-the-edge-device 需要把每次拍摄的水表/电表照片与预先保存的参考图像对齐才能保证后续 ROI 裁剪与数字识别CNN的准确性。对齐过程的核心是模板匹配在实拍图像中寻找参考模板例如 sd-card/config/config.ini 中配置的ref0.jpg、ref1.jpg当前出现的位置。由于相机每次安装后位置相对固定参考模板只会出现在参考点附近很小的区域内因此固件不需要在整张图中搜索而是以每个参考点的期望坐标target_x/target_y为中心划出一个有限的搜索窗口SearchFieldX决定窗口在 X 方向向左右各延伸多少像素SearchFieldY决定窗口在 Y 方向向上下各延伸多少像素即搜索区域的高度Y-size。文档原文对该参数的描述为Y-size (height) in which the reference is searched即参考图像被搜索的 Y 方向尺寸高度。在实际出厂配置中两个方向均为 20 像素。以下是 sd-card/config/config.ini 中完整的[Alignment]段落L37-L43[Alignment] InitialRotate 0.0 SearchFieldX 20 SearchFieldY 20 AlignmentAlgo default /config/ref0.jpg 103 271 /config/ref1.jpg 442 142最后两行的格式为模板文件路径 X坐标 Y坐标即每个参考模板的target_x/target_y。以ref0.jpg 103 271为例搜索窗口的 Y 范围约为271 - 20到271 20像素再经过图像边界裁剪。SD 卡演示配置 sd-card/demo/config.ini 使用相同的取值。3. 源码级原理从配置解析到搜索窗口计算3.1 参数解析ClassFlowAlignment::ReadParameterSearchFieldY在固件中的解析入口位于 ClassFlowAlignment.cpp 的ReadParameter方法int suchex 40; int suchey 40; // L59-L60代码级后备默认值 ... else if ((toUpper(splitted[0]) SEARCHFIELDY) (splitted.size() 1)) { if (isStringNumeric(splitted[1])) { suchey std::stod(splitted[1]); // L95-L98读取 SearchFieldY } } ... for (int i 0; i anz_ref; i) { References[i].search_x suchex; // L142 References[i].search_y suchey; // L143 References[i].fastalg_SAD_criteria SAD_criteria; // 默认 0.05 References[i].alignment_algo alg_algo; }两点值得注意文档默认值 20 与代码后备默认值 40 的差异文档标注的默认值20对应仓库出厂配置文件config.ini中的实际取值而如果配置文件中缺失该参数代码内部的后备默认值是40L59-L60。这意味着该参数不是不写即 20而是出厂配置为 20缺失时退化为 40后者会让搜索窗口和计算量显著变大。解析结果被写入每个参考模板对应的RefInfo结构体search_x/search_y作为后续模板匹配的输入。3.2 搜索窗口计算CFindTemplate::FindTemplate真正使用SearchFieldY的地方在 CFindTemplate.cpp 的FindTemplate(RefInfo *_ref)方法。它根据target坐标与search_x/search_y计算出搜索窗口的起止范围ow_start _ref-target_x - _ref-search_x; ow_start std::max(ow_start, 0); ow_stop _ref-target_x _ref-search_x; if ((ow_stop tpl_width) width) ow_stop width - tpl_width; // 防止越界 oh_start _ref-target_y - _ref-search_y; oh_start std::max(oh_start, 0); oh_stop _ref-target_y _ref-search_y; if ((oh_stop tpl_height) height) oh_stop height - tpl_height; // 防止越界可见Y 方向搜索范围以target_y为中心、向上下各延伸SearchFieldY像素并在图像边界处被自动裁剪std::max(..., 0)和宽度/高度上限因此把SearchFieldY设得再大也不会越界访问只会增加无效计算。另外RefInfo结构中search_x 0或search_y 0时有特殊语义CFindTemplate.cpp搜索范围退化为整幅图像width/heightfound坐标归零——这是跳过局部搜索的特殊路径日常配置中不应主动将SearchFieldY设为 0 来触发。3.3 搜索窗口内的模板匹配SAD 双重循环窗口范围确定后FindTemplate在ow_start..ow_stop×oh_start..oh_stop内逐位置滑动模板用 SAD平方差和评估相似度取最小 SAD 的位置作为匹配结果for (xouter ow_start; xouter ow_stop; xouter) for (youter oh_start; youter oh_stop; youter) { aktSAD 0; for (tpl_x 0; tpl_x tpl_width; tpl_x) for (tpl_y 0; tpl_y tpl_height; tpl_y) { // 逐像素计算 (模板 - 原图)^2 累加 } if (aktSAD minSAD) { minSAD aktSAD; _ref-found_x xouter; _ref-found_y youter; } }这就是文档中计算时间随搜索区域大小呈二次方增长quadratic的由来搜索窗口内待评估的位置总数约为(2×SearchFieldX1) × (2×SearchFieldY1)窗口面积随SearchField尺寸呈二次方增长而每个位置又都要与整个模板做全像素 SAD 累加因此整体耗时与搜索窗口面积成正比。SearchFieldY每增大一倍Y 方向候选位置翻倍总计算量随之成倍上升。3.4 完整的对齐调用链SearchFieldY影响的是对齐流水线中的找参考点环节整条链路如下ClassFlowAlignment.cpp 创建CAlignAndCutImage对象CAlignAndCutImage::Align()CAlignAndCutImage.cpp对两个参考模板依次调用CFindTemplate::FindTemplate得到found_x/found_y由两个参考点的期望位置与实际找到位置的偏差计算平移量dx/dy与旋转角d_winkelatan2差分求角最后通过CRotateImage对整幅图像执行TranslateRotate完成对齐。因此SearchFieldY取值过小 → 参考模板可能落在搜索窗口之外 → 匹配失败或匹配到错误位置 → 平移/旋转角度计算错误 → 后续 ROI 与数字识别全部错位。这也是它被列为专家参数的原因。4. 性能权衡为什么搜索区域越小越好文档原文给出两条明确约束对齐是整套流程中计算量最大的步骤之一计算时间随搜索区域尺寸呈二次方增长。结合源码可以量化这一影响搜索窗口的候选位置数约等于(2×SX1)×(2×SY1)其中每个候选位置都要完成一次模板面积大小的 SAD 累加。假设模板为 40×40 像素SearchFieldX SearchFieldY 10时窗口约 21×21 441 个候选位置SearchFieldX SearchFieldY 20时窗口约 41×41 1681 个候选位置计算量约为前者的 3.8 倍SearchFieldX SearchFieldY 40时窗口约 81×81 6561 个候选位置计算量约为 20 取值时的 4 倍。由于目标设备是资源受限的 ESP32 系列图像处理在 PSRAM 中进行CAlignAndCutImage.cpp 使用malloc_psram_heap分配中间缓冲区每次对齐都要在每次读数周期中执行搜索窗口过大将显著拖慢整轮读数流程。调优实践建议以出厂值20为起点在参考模板能被稳定找到的前提下逐步缩小SearchFieldY以及SearchFieldX相机固定后参考点的实际漂移通常只有几个像素10~15 往往足够调小后务必观察多轮读数确认对齐结果稳定参考 edit_alignment.html 可视化页面中的对齐预览图/img_tmp/alg.jpg、/img_tmp/rot.jpg避免出现偶发匹配失败若不得不使用较大搜索范围可考虑同时评估AlignmentAlgo如fast模式对耗时的影响——RefInfo中的fastalg_x/fastalg_y机制CFindTemplate.h可在满足 SAD 判据时跳过全窗口扫描。5. 在 Web UI 中修改 SearchFieldYSearchFieldY属于专家参数在配置页中默认折叠。相关前端逻辑位于 edit_config_template.htmltr classexpert unused_idAlignment_SearchFieldY_ex8 ... input required typenumber namename idAlignment_SearchFieldY_value1 size13 min1 step1 ... td$TOOLTIP_Alignment_SearchFieldY/td由该模板可见输入框声明为typenumber且min1、step1即只接受不小于 1 的整数像素值行元素带有classexpert与readconfigparam.js中ParamAddValue(param, catname, SearchFieldY)的注册逻辑配合在非专家模式下被隐藏需在配置界面展开专家参数后才能编辑保存与读取分别通过 edit_config_template.html 的WriteParameter(param, category, Alignment, SearchFieldY, false)与 edit_config_template.html 的ReadParameter(...)完成。修改后固件会将新值写回 SD 卡上的config.ini重启或重新加载配置后生效。6. 与其他对齐参数的协同关系SearchFieldY不是孤立参数它与[Alignment]段的其他配置共同决定对齐质量参数作用与 SearchFieldY 的关系SearchFieldXX 方向搜索范围与SearchFieldY共同构成搜索窗口见 SearchFieldX.mdAlignmentAlgo匹配算法default/highaccuracy/fast/offfast模式alignment_algo 2可在上一轮结果附近快速确认缓解大搜索窗口的耗时InitialRotate初始旋转角决定对齐前的预处理旋转旋转不准时搜索窗口内的模板形态也会变化参考模板行如/config/ref0.jpg 103 271模板路径与期望位置其target_x/target_y是搜索窗口的中心两个参考点间距影响旋转角计算精度对齐环节在整个流程中的位置可参考流程相关文档与可视化页面overview.html对齐结果的排查可结合日志与/img_tmp/rot.jpg、/img_tmp/alg.jpg等中间图像进行。7. 小结SearchFieldY是 AI-on-the-edge-device 对齐模块中控制Y 方向参考搜索范围的关键专家参数本质以参考点target_y为中心、上下各延伸SearchFieldY像素的搜索高度默认值出厂配置为20sd-card/config/config.ini代码后备默认值为40ClassFlowAlignment.cpp复杂度搜索窗口面积随该值二次增长直接影响每轮读数的计算耗时因此在保证匹配成功的前提下尽可能小是核心调优原则边界保护搜索范围超出图像边界时会被自动裁剪不会越界访问只会浪费算力修改方式Web UI 专家参数区域整数、最小 1或直接编辑 SD 卡config.ini的[Alignment]段。掌握该参数的原理与权衡是在 ESP32 这类资源受限设备上兼顾对齐精度与响应速度的重要一环。【免费下载链接】AI-on-the-edge-deviceEasy to use device for connecting old measuring units (water, power, gas, ...) to the digital world项目地址: https://gitcode.com/GitHub_Trending/ai/AI-on-the-edge-device创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考