MaaEnd IconRecognition：基于C++与ONNX的物品图标识别实现原理

MaaEnd IconRecognition基于C与ONNX的物品图标识别实现原理【免费下载链接】MaaEndMaaEnd 终末地小助手基于视觉 AI 的「明日方舟终末地」自动化工具项目地址: https://gitcode.com/gh_mirrors/maa/MaaEndMaaEnd 是一款基于视觉 AI 的《明日方舟终末地》自动化工具其中IconRecognition 物品图标识别组件负责在游戏中看懂背包、仓库、交易台等界面上的每一个物品给定一块屏幕区域它就能返回物品 ID、格子和置信度分数。本文带你拆解这个 C 核心模块的四步识别流水线、它如何与 ONNX 模型分工协作以及从哪些文件开始阅读源码最合适。IconRecognition 是什么只做认物品一件事IconRecognition是 MaaEnd 的 C Custom Recognition 组件对外只暴露一个recognizeAPI。调用方做两件事告诉它当前是什么界面grid_type如transfer背包/仓库、trade交易台、rewards奖励卡片等给它一块 Maa ROI1280x720 基准下的[x, y, w, h]区域。它则返回每个命中格子的物品 ID、坐标和匹配分数。需要强调的是它只负责定位与分类不负责进入界面、点击物品或流程跳转——那些由 Pipeline 或业务 Service 控制。这种识别与操作解耦是整个 MaaEnd 自动化的架构前提也让识别组件可以独立测试、独立迭代。组件入口在 agent/cpp-algo/source/IconRecognition/模块说明见 README.md。运行时它只读取三份公开资源物品目录recognition_items.json近 9000 行记录每个item_id的名称、分类、稀有度和图标资源图标资源assets/resource/image/IconRecognition/rarity/*.png按稀有度分组的物品图标多语言文案assets/locales/interface/*.json。识别流水线四步找格子 → 校颜色 → 配图标 → 滤结果抛开实现细节IconRecognition只做四件事详见 识别算法文档步骤做什么核心类1. 格子定位在 ROI 内找出全部物品格子GridDetector、GridProfiles、RegularLattice2. 颜色条校正用稀有度颜色条修正格子相位RarityClassifier、TrustedRarity3. 图标匹配逐格与候选模板做结构颜色匹配CandidateSelector、IconMatcher、SubpixelMatcher4. 结果过滤按阈值、纹理、排序去重后返回ForegroundTexture、ItemMatchLess第一步如何在屏幕上找到物品网格游戏界面里的物品是一格格排好的但分辨率、缩放、界面元素都会变化所以不能硬编码坐标。GridDetector的做法是结构候选从格框边缘和明暗差中找出可能的网格区域GridFeatures、GridGeometry、GridAnchors协作颜色条证据背包类界面格子底部有一条代表稀有度的窄色条只有同时满足宽度、厚度、连续性、背景对比和双边缘约束的窄条才被视为可靠的位置证据RarityClassifier.cpp规则网格拟合把离散的横纵观测拟合成一套统一的起点间距规则网格RegularLattice.cpp再由同一套浮点网格一次性投影出所有格子坐标避免逐格累加把取整误差传播下去双路对比颜色条候选与结构候选互相验证证据不足时保留保守的结构候选回退路径。此外组件内置 Win32 与 ADB 两套 1280x720 控制器的网格 profile见 grid-profiles.mdADB 放大画面会先临时归一化到标准 720p 逻辑密度再运行同一套算法最后把坐标映射回原图——调用方无需关心设备差异。第二步稀有度颜色条的先验价值识别背包物品时稀有度颜色条不只是装饰。在逐格匹配前RarityCandidates会先用颜色条把候选模板缩小到同稀有度集合首轮只比对同稀有度模板没达标再扩大到全候选。候选集小了匹配就更快、更稳——这是典型的用廉价先验换昂贵计算的工程取舍。第三步模板匹配 Lab 颜色空间 亚像素细化每个格子的图标匹配发生在输入原图上IconMatcher.cpp模板直接从 128px 原始图标资源缩放到当前格子尺寸同时考虑两路信号结构相似OpenCV 模板匹配得分颜色相似在 Lab 色彩空间中比较亮度与颜色分量——Lab 把明暗和颜色拆开比直接比 RGB 更能抵抗光照和背景差异。两路分数合并后若分数值得再看但还没达标SubpixelMatcher会在像素级再搜索更细的位置偏移SubpixelMatcher.h。还有两个很有工程味的细节低纹理拒绝ForegroundTexture会拒绝几乎空白、纹理方差不足的格子防止把空格或纯色块硬认成某物品遮挡恢复当最高候选的残差集中在格子上下边缘时EdgeOcclusion判定图标被工具栏等元素遮挡把实测遮挡带从匹配遮罩中清零后重新排名且只有恢复结果保持原最高候选不变、达到阈值时才采纳。第四步阈值、排序与去重只有最终分数达到请求阈值默认 0.85、且未被低纹理检查拒绝的结果才进入公开matches。结果先按分数降序同分再按格子 y、x 和物品 ID 比较ItemMatchLess开启去重后每个item_id只保留得分最高的格子。值得注意的是识别完成但没有命中对外返回no_match是正常结果而非异常只有网格定位完全失败才返回exception。请求与结果的完整类型定义见 IconRecognitionTypes.h。ONNX 与模板匹配MaaEnd 的双引擎分工一个常见的疑问MaaEnd 是视觉 AI工具为什么 IconRecognition 不用神经网络答案在于分工。MaaEnd 的 ONNX 推理集中在 MapLocator 模块YoloPredictor.h 和 CameraOrientationPredictor.h 引入onnxruntime_cxx_api.h运行时加载cls.onnx、preprocess.onnx、polar_with_ref.onnx等模型见 MapLocateAction.cpp由 CMakeLists.txt 统一链接ONNXRuntime用神经网络解决开放场景的地图定位这类没有固定答案的问题。而 IconRecognition 面对的是闭集识别物品图标是已知、可枚举的目录里有多少物品就有多少模板所以它选择了确定性视觉算法——模板匹配 颜色空间比较 几何拟合。这套方案的优势很直接无需训练数据新物品只要把图标和资源目录同步进来就能识别分数可复现同一张截图每次匹配结果一致便于回归测试界面适配可控每个grid_type都有明确的 profile 和遮罩策略行为边界清晰。一句话总结神经网络负责开放世界的看懂确定性算法负责已知物品集的认准两者通过同一个 C 算法核心协作构成 MaaEnd 的视觉 AI 底座。配套工具链与推荐阅读路径图标识别能稳定工作离不开一条数据先行的资源流水线tools/icon_recognition/ 下的download.py、catalog.py、publish.py负责图标素材的下载、目录生成与发布校验item_transfer/则处理同图标组物品的映射生成确保recognition_items.json与游戏素材保持同步。如果你想继续深入建议按这条路径阅读外部契约参数、参考 ROI、返回值IconRecognition 开发者使用指南模块职责与数据流内部架构文档算法细节网格定位、匹配、遮挡恢复识别算法文档网格 profile 维护网格配置维护测试与人工审核图测试文档测试代码位于 test/编排入口IconRecognizer.cppMaaFramework 适配层见 IconRecognitionRecognition.cpp从一个格子如何被认出来到整个目录如何被维护IconRecognition 展示了视觉自动化工具最务实的一面不追求炫技的模型而是把几何先验、颜色空间和确定性匹配用到极致。理解了这个模块你就掌握了 MaaEnd 大部分业务任务自动囤货、背包收纳、交易识别背后共同的识别基础。【免费下载链接】MaaEndMaaEnd 终末地小助手基于视觉 AI 的「明日方舟终末地」自动化工具项目地址: https://gitcode.com/gh_mirrors/maa/MaaEnd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考