# 开发手册 - MapLocator 小地图定位系统

## 简介

此文档介绍了如何使用 **MapLocator** 相关的节点。

**MapLocator** 是一个基于原生 C++ 开发的、深度融合了 AI 与传统计算机视觉算法的下一代小地图定位系统。它能够在剧烈的特效干扰中稳健地输出玩家所处的地图区域（主要表现为地图名称/区域名，如 ZoneID）、全局像素坐标 $(x, y)$ 以及当前朝向角度。本系统专为极端的画面遮挡与光影滥炸等复杂场景设计，以极低的系统开销实现毫秒级别的精准定位。

### 边界说明

MapLocator 仅负责“充当系统明亮的眼睛”——即高频、高精度的**坐标与方位识别**，属于 Recognition 层。要实现“让人物跑到指定坐标去”，还需要依托开发者在外层接入寻路算法并下发针对物理操作（鼠标转向、键盘移动）的控制代码（Action），本模块并不会自动接管游戏控制。

### MapLocator 核心技术架构

1. **原生计算优势与 OpenCV 赋能**
   该系统作为 `cpp-algo` 独立进程组件接入 Pipeline ，得益于使用原生 C++ 和 OpenCV 构建底层图像管线，并在内存处理上高度优化，能使其在引入 YOLO 模型推理的前提下保持极低的运行延迟。
2. **强大的动态环境感知与 YOLO 前置鉴别**
   系统部署了独立训练的 YOLOv26-small 模型作为场景识别的前置校验流。模型可根据置信度直接确认当前画面是否确实存在合法小地图区域（Minimap ROI），快速过滤诸如：正处于各种常规全屏菜单、遭遇特效糊脸遮挡画面等异常场景带来的干扰，极大幅度降低误判几率。
3. **基于梯度域 ZNCC 匹配与抗干扰能力**
   系统内置了专为多重 Alpha 渲染（半透明UI堆叠）优化的梯度特征提取以及 ZNCC（零均值归一化互相关）模板匹配机制。在遇到技能光效频闪或是 UI 重大变化时，依靠边缘特征以及轮廓权重，依然能够维持高度的匹配鲁棒性。
4. **内置动捕引擎 (MotionTracker) 的追踪优化**
   系统内部记录并分析了角色历史运动速度。当进入下一帧识别时，算法并不会盲目全局搜索，而是会根据上一帧预估的瞬时速度推断角色这一刻的合理移动半径（Search Bounds）。这既缩减了模板匹配的范围并借此极大提升了运算速度，也能避免匹配到远处极为相似但实际上站不到的错误色块。

---

## 节点说明

下面详细介绍 MapLocator 提供的节点的具体用法。本节点基于 MAA 的 `Custom` 类型设计，可直接被嵌装在 Pipeline 内，非常推荐后续的控制/Action 层直接从其输出 (`out_detail`) 中捕获极高精度的数值以决定后续走位。

### custom_recognition: MapLocateRecognition

获取玩家当前所处的大地图分区名（也称 ZoneID 或 mapName），以及精确的坐标和朝向。

#### 节点参数

**运行机制**：调用一次 `MapLocateRecognition` 节点，底层即进行**且仅进行一帧（当前有效截图）**的小地图计算并返回坐标。如果您需要像“外挂雷达”那样实现随动的连续追踪，你需要基于 Pipeline 的循环机制将其包裹（例如利用 `next` 将节点连通或套入循环节点中），高频复用以实现持续供流。

**必填参数**：**无**

**可选参数 (`custom_recognition_param`)**：
支持传递 JSON 对象格式的高级参数设置，用于在极端或特定场景中覆写默认参数，针对性地微调本定位器。

- `loc_threshold`: 介于 $[0, 1]$ 的实数，默认 `0.55`。控制基于图像匹配特征的最宽容的命中基础分数线。如果环境极尽复杂光怪陆离而频繁意外断连，可酌情下浮（比如 `0.45`）；常规情形推荐保持默认或按需上调，确保精确度。
- `yolo_threshold`: 介于 $[0, 1]$ 的实数，默认 `0.70`。YOLO判断地图UI类别的最低置信度阈值。过低可能会把部分具备类似圆盘UI的界面错认为小地图。
- `force_global_search`: 真假值，默认 `false`。出于极致优化的考量，日常跟踪中只需沿着玩家上次的范围局域（Local Search）即可。但当处于大区域跨越转移、复活传送、长时间切屏恢复时，应当开启 `true` 以强制采用全图全局扫描策略锁定位置。
- `max_lost_frames`: 整数，默认 `3`。允许连续多少帧系统检测不到合法结果后，才实质宣告“彻底丢失（Tracking Lost）”。提高该值能增加短暂UI遮挡的过渡能力，但错误锁定时间也会相应延长。

#### 返回值结构 (Out Detail)

定位成功或中断检测结束后，节点将向 `out_detail` 管道以及控制台输出 JSON 结构的完整状态反馈。可用于复杂的业务流转或报错处理：

- `status`: [底层状态码枚举]
    - `0 (Success)`: 定位完全成功。
    - `1 (TrackingLost)`: 追踪丢弃（全局爆破寻觅同样毫无所获）。
    - `2 (ScreenBlocked)`: 画像遭遇未知且庞大干扰物的压倒性覆写/遮挡。
    - `3 (Teleported)`: 两帧之间坐标位移严重超出人类/载具移速极限，进而判定为遭受了强制传送。
    - `4 (YoloFailed)`: 初始 YOLO 模型已确认当前游戏截图不具备小地图识别区域。
- `mapName`: （成功态）本次定位吻合度最高的大地图区域名称 (如 "map01_lv001")。
- `x`: （成功态）X 轴向全局像素坐标（水平值）。
- `y`: （成功态）Y 轴向全局像素坐标（垂直值）。
- `rot`: （成功态）当前计算输出的真实朝向偏航角（高精度，通常 $0^\circ \sim 360^\circ$ 以北为零向）。
- `locConf`: 最终命中置信度得分，常用于微调参数时的参考。
- `latencyMs`: 节点算法执行消耗的总自然毫秒数，供性能监控使用。

#### 示例用法

**最简调用（推荐基础使用）：**
得益于内部强大的初始化自适应流程，绝大多数情况下只需像下边这样直接调用 `MapLocateRecognition`，完全不用传任何额外参数。系统会自动使用 YOLO 推理寻找所属地图并进行全自动的长期跟踪：

```json
{
    "MyLocateTask": {
        "recognition": "Custom",
        "custom_recognition": "MapLocateRecognition",
        "action": "DoNothing"
    }
}
```

**进阶调用（传递额外参数）：**
当在执行长途复活传送，或是你需要跳过前期计算强行指定它在某张地图搜寻坐标时，可以使用 `custom_recognition_param` 覆写参数：

```json
{
    "MyLocateTask": {
        "recognition": "Custom",
        "custom_recognition": "MapLocateRecognition",
        "custom_recognition_param": {
            "loc_threshold": 0.55,
            "yolo_threshold": 0.7,
            "force_global_search": true
        },
        "action": "DoNothing"
    }
}
```

### custom_recognition: MapLocateAssertLocation

判断玩家当前是否位于指定 `zone_id` 的某个矩形区域内。

这个节点本质上是对 `MapLocateRecognition` 的一次薄封装：底层仍然先做一次定位，然后检查返回的 `zone_id` 与 `(x, y)` 是否满足给定条件。它是一个纯判定节点，不负责移动，也不会修改任何导航状态。

#### 节点参数

**必填参数 (`custom_recognition_param`)**：

- `zone_id`: 目标区域名，必须与定位结果中的区域名完全一致。
- `target`: 由 4 个数字组成的数组 `[x, y, w, h]`，表示左上角坐标与矩形宽高。

**可选参数 (`custom_recognition_param`)**：

- `loc_threshold`: 含义同 [MapLocateRecognition](#custom_recognition-maplocaterecognition)。
- `yolo_threshold`: 含义同 [MapLocateRecognition](#custom_recognition-maplocaterecognition)。
- `force_global_search`: 含义同 [MapLocateRecognition](#custom_recognition-maplocaterecognition)。

#### 返回值结构 (Out Detail)

该节点同样会向 `out_detail` 输出 JSON，常用字段如下：

- `status`: 底层定位状态码，语义同 `MapLocateRecognition`。
- `matched`: 真假值。只有当区域和矩形都命中时才为 `true`。
- `inTarget`: 与 `matched` 等价，便于直接读取“是否在目标框中”。
- `message`: 底层定位日志或失败原因。
- `zoneId`: 本次判定要求的目标区域名。
- `x` / `y` / `rot` / `locConf` / `latencyMs`: 本次定位结果；只有定位成功时才有意义。
- `target`: 回显本次判定使用的 `[x, y, w, h]`。

#### 示例用法

```json
{
    "WulingBaseAssert": {
        "recognition": "Custom",
        "custom_recognition": "MapLocateAssertLocation",
        "custom_recognition_param": {
            "zone_id": "Wuling_Base",
            "target": [
                605,
                878,
                60,
                20
            ]
        },
        "action": "DoNothing"
    }
}
```

> [!TIP]
>
> 这个节点适合在进入 `MapNavigateAction` 之前做入口判定。例如：先判断人物是否已经站在传送落点附近，再决定后续是否继续跑对应路线。
