MaaEnd 网格识别引擎：RecoGrid/GridTracker/EssenceGrid 三层架构完整剖析

MaaEnd 网格识别引擎：RecoGrid/GridTracker/EssenceGrid 三层架构完整剖析

【免费下载链接】MaaEndMaaEnd 终末地小助手：基于视觉 AI 的「明日方舟：终末地」自动化工具项目地址: https://gitcode.com/gh_mirrors/maa/MaaEnd

MaaEnd 网格识别引擎是 MaaEnd——这款基于视觉 AI 的《明日方舟：终末地》自动化助手——最核心的底层能力之一。当你要自动扫荡「核心」仓库时，程序面对的不是接口数据，而是一张张不断滚动的库存截图：几十上百个格子、重复出现的图标、看不见的滚动进度。网格识别引擎要解决的正是这个问题：从单张截图里认出网格，再把多张滚动截图拼成一份带全局坐标、不重复的清单。整个引擎采用 RecoGrid → GridTracker → EssenceGrid 的三层架构，职责层层递进，是理解 MaaEnd 视觉自动化的绝佳入口。

一、为什么需要网格识别：一张滚动截图的难题

在终末地的主城里，「核心」（Essence）以网格货架的形式陈列：一排排格子，有的空着，有的装着品质各异的物品。自动化流程需要逐格判断：它是什么品质？锁定了没有？要不要丢弃？

纯模板匹配做不好这件事，原因很直接：

• 库存页面可以上下滚动，同一物品会跨多张截图出现，必须去重；
• 格子数量、行列边界因 UI 缩放而异，必须几何检测而非硬编码坐标；
• 「翻到底了」没有明确标志，需要靠连续重复帧来推断终点。

MaaEnd 的解法就是把上述三个问题拆给三个模块，各自只做一件事。

二、30 秒看懂：RecoGrid / GridTracker / EssenceGrid 分层架构

这种「识别 → 追踪 → 适配」的分层非常干净：下层永远不知道上层在干什么。RecoGrid 不关心你在扫仓库还是扫商店，GridTracker 不关心格子里装的是什么，EssenceGrid 则负责把两者翻译成 Maa 流水线能消费的节点决策。

三、第一层 RecoGrid：单张截图如何变出一张网格

RecoGrid 的对外入口只有一个函数：RecognizeGrid(image, options)，输入一张截图，输出一个GridFrame（行列数、每个格子的屏幕矩形、感知哈希、紧凑颜色特征、是否占用）。

它的内部流程可以概括为四步 🧭：

1. 归一化与裁剪：把截图缩放到 720p 坐标系，再裁出网格所在 ROI，让后续算法不受分辨率影响；
2. 投影分割：对 ROI 做行列方向投影，按阈值切出行段和列段（见 GridDetector.h 中的rowThresholdRatio、minKeptSegmentRatio等参数），并支持「锁定行高/列宽」来稳定首帧之后的几何；
3. 占用判定与遮罩：用亮度阈值判断格子是否为空，同时用 CellMask.h 遮掉格子内部固定的装饰区域，避免误判；
4. 特征生成：为每个格子计算感知哈希（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）：

另一个贴心细节：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 动作。

节点路由规则同样清晰：

错误边界也被明确划好：配置、模板加载与常规识别失败都以MaaBool失败返回并携带诊断细节，OpenCV 异常在 Maa 回调边界被捕获，任何异常不会跨越 C ABI——这对一个以 C 接口对接流水线的模块至关重要。

六、快速上手：建议的阅读路径

想深入源码，推荐按依赖顺序阅读 📖：

1. 三层总览：RecoGrid README → GridTracker README → EssenceGrid README
2. 几何检测细节：GridDetector.cpp、GridRecognizer.h
3. 对齐与状态机：GridTracker.cpp
4. 业务接线：EssenceGridScan.cpp 及主入口 main.cpp

七、常见问题（FAQ）

Q1：为什么不用固定坐标直接点击格子？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