MaaEnd 网格识别引擎RecoGrid/GridTracker/EssenceGrid 三层架构完整剖析【免费下载链接】MaaEndMaaEnd 终末地小助手基于视觉 AI 的「明日方舟终末地」自动化工具项目地址: https://gitcode.com/gh_mirrors/maa/MaaEndMaaEnd 网格识别引擎是 MaaEnd——这款基于视觉 AI 的《明日方舟终末地》自动化助手——最核心的底层能力之一。当你要自动扫荡「核心」仓库时程序面对的不是接口数据而是一张张不断滚动的库存截图几十上百个格子、重复出现的图标、看不见的滚动进度。网格识别引擎要解决的正是这个问题从单张截图里认出网格再把多张滚动截图拼成一份带全局坐标、不重复的清单。整个引擎采用 RecoGrid → GridTracker → EssenceGrid 的三层架构职责层层递进是理解 MaaEnd 视觉自动化的绝佳入口。一、为什么需要网格识别一张滚动截图的难题在终末地的主城里「核心」Essence以网格货架的形式陈列一排排格子有的空着有的装着品质各异的物品。自动化流程需要逐格判断它是什么品质锁定了没有要不要丢弃纯模板匹配做不好这件事原因很直接库存页面可以上下滚动同一物品会跨多张截图出现必须去重格子数量、行列边界因 UI 缩放而异必须几何检测而非硬编码坐标「翻到底了」没有明确标志需要靠连续重复帧来推断终点。MaaEnd 的解法就是把上述三个问题拆给三个模块各自只做一件事。二、30 秒看懂RecoGrid / GridTracker / EssenceGrid 分层架构层级模块一句话职责状态第一层RecoGrid单帧识别检测行列几何、生成单元格矩形与比较特征无状态第二层GridTracker滚动拼接对齐重叠行、分配全局坐标、发布去重后的新格子有状态第三层EssenceGrid业务适配接入 Maa Pipeline驱动点击、OCR 与后续动作有状态会话级这种「识别 → 追踪 → 适配」的分层非常干净下层永远不知道上层在干什么。RecoGrid 不关心你在扫仓库还是扫商店GridTracker 不关心格子里装的是什么EssenceGrid 则负责把两者翻译成 Maa 流水线能消费的节点决策。三、第一层 RecoGrid单张截图如何变出一张网格RecoGrid 的对外入口只有一个函数RecognizeGrid(image, options)输入一张截图输出一个GridFrame行列数、每个格子的屏幕矩形、感知哈希、紧凑颜色特征、是否占用。它的内部流程可以概括为四步 归一化与裁剪把截图缩放到 720p 坐标系再裁出网格所在 ROI让后续算法不受分辨率影响投影分割对 ROI 做行列方向投影按阈值切出行段和列段见 GridDetector.h 中的rowThresholdRatio、minKeptSegmentRatio等参数并支持「锁定行高/列宽」来稳定首帧之后的几何占用判定与遮罩用亮度阈值判断格子是否为空同时用 CellMask.h 遮掉格子内部固定的装饰区域避免误判特征生成为每个格子计算感知哈希PHash和紧凑全格特征供上层做跨帧比较实现在 PHashFilter.h。这里有一个值得注意的设计——失败契约识别失败不抛异常而是返回一个空的GridFrame并附带诊断信息见 RecoGrid README。「正常识别失败是数据不是控制流」这让上层可以像处理普通结果一样做重试逻辑非常务实。四、第二层 GridTracker把滚动帧缝成一张大网格单帧识别只解决了「这张图」的问题而库存可能有几百格。GridTracker 接收连续的GridFrame通过observe()逐帧处理核心机制有三个① 重叠对齐。当前帧与上一帧在非负行偏移上逐一比对候选排序规则是匹配格比例更高 → 平均特征距离更小 → 比较格数更多。只有满足最少重叠行数且匹配率达标默认 0.5的候选才被采纳视口起点随之前进。② 全局坐标与去重。每个占用格被放置到(视口起点行 局部行, 列)的全局坐标上Tracker 内部维护一份坐标 → 格子的映射只发布「从未在更早全局坐标出现过」的新格子Result::new_cells。业务代码不需要再自建去重表。③ 终点双重确认。滚到底的标志不是「停住了」而是两次连续的完整重复帧行列形状相同、完整rows × cols向量参与比较、匹配率达到repeat_match_ratio默认 0.95。第一次完整重复返回ConfirmingEnd提示再多滚一次第二次才返回Repeated列表完成。任何前进或形状不兼容都会清空挂起状态。状态机的五种状态一目了然定义见 GridTracker.h状态含义Initial首个有效帧全部占用格发布为新格Advanced视口前进或有重叠刷新ConfirmingEnd首次完整重复需再滚一帧确认Repeated第二次连续完整重复列表可判定结束Rejected空帧/不兼容/低置信网格状态不推进另一个贴心细节screen_rect始终保留为当前截图上的矩形所以业务层拿到新格子后可以立刻点击无需再换算坐标。五、第三层 EssenceGrid接入 MaaEnd 流水线的「翻译官」前两层是纯算法库CMake 静态目标recogrid和grid-tracker而 EssenceGrid编译进生产版cpp-algo可执行文件入口见 EssenceGridScan.h才是它们与游戏世界打通的「翻译官」。它注册为两个 Maa 自定义识别节点EssenceGridAdvanceRecognition扫描当前队列并决定下一个流水节点EssenceGridPendingRecognition返回选中格子的精确矩形供流水线点击。整个实例在main.cpp中创建通过trans_arg在两个节点间共享——没有进程级全局库存状态一次滚动会话对应一个实例新任务开始时reset()即可。单帧的完整处理链路是RecoGrid 识别 → GridTracker 对齐并产出new_cells→ EssenceGrid 采样格子底边条判断金/紫品质、左下角判断锁定/丢弃图标 → 通过过滤的格子进入调度队列 → 流水线点击 OCR → Go 端决策「锁定/丢弃/跳过」→ 流水线执行并验证 UI 动作。节点路由规则同样清晰条件下一节点队列中有格子EssenceGridClickPending点击帧被接受且需继续滚动EssenceGridSwipeNext首次完整重复再滚一帧确认第二次连续完整重复EssenceFilterFinish结束帧被拒绝识别返回失败Maa 原地重试错误边界也被明确划好配置、模板加载与常规识别失败都以MaaBool失败返回并携带诊断细节OpenCV 异常在 Maa 回调边界被捕获任何异常不会跨越 C ABI——这对一个以 C 接口对接流水线的模块至关重要。六、快速上手建议的阅读路径想深入源码推荐按依赖顺序阅读 三层总览RecoGrid README → GridTracker README → EssenceGrid README几何检测细节GridDetector.cpp、GridRecognizer.h对齐与状态机GridTracker.cpp业务接线EssenceGridScan.cpp 及主入口 main.cpp七、常见问题FAQQ1为什么不用固定坐标直接点击格子UI 缩放、分辨率、窗口位置都会让硬编码坐标失效。RecoGrid 的投影分割能在首帧自适应检测行列几何后续帧还能用锁定尺寸稳定几何鲁棒得多。Q2滚到底的判断会不会误判单次停顿不够可靠可能只是加载卡顿所以 GridTracker 要求两次连续完整重复且匹配率 ≥ 0.95 才判定结束中途任何前进都会重置确认状态误判空间极小。Q3这套网格识别能复用到其他网格 UI 吗可以。RecoGrid 与 GridTracker 都是与业务无关的库只要目标页面是规则网格仓库、商店货架等配置不同的 ROI、遮罩和模板即可这正是分层架构的价值所在。Q4识别失败会影响任务吗不会导致崩溃。空帧被Rejected后网格状态不推进Maa 会原地重试当前节点OpenCV 异常在 C ABI 边界内消化整个任务循环保持安全。小结MaaEnd 的网格识别引擎用「无状态识别 → 有状态追踪 → 流水线适配」三层架构把「滚动截图 → 全局清单 → 自动化动作」这条链路拆解得干净利落。理解它你就拿到了 MaaEnd 视觉 AI 自动化的一块拼图——下一块拼图就是同样架构下的地图定位与路径规划模块了。【免费下载链接】MaaEndMaaEnd 终末地小助手基于视觉 AI 的「明日方舟终末地」自动化工具项目地址: https://gitcode.com/gh_mirrors/maa/MaaEnd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
