MaaPipelineEditor

主题

kqcoxn
3174
11.3m

字段快捷工具 ​

LocalBridge 提供了强大的字段快捷工具功能，通过连接到您的模拟器或窗口，可以实时截图并辅助填写各种字段。这些工具极大地简化了 Pipeline 编写过程。

前置条件 ​

配置 MaaFramework ​

使用字段快捷工具前，需要先配置 MaaFramework：

  1. 下载 MaaFramework Release 包
    从 MaaFramework Releases 下载对应平台的 Release 包并解压。

  2. 配置库路径
    运行以下命令配置 MaaFramework 库目录（指向解压后的 bin 文件夹）：

    bash
    mpelb config set-lib

    按照提示选择或输入路径，例如：

    • Windows: D:\MaaFramework\bin
    • Linux: /opt/maaframework/bin
    • macOS: /Applications/MaaFramework/bin

  3. 配置 OCR 资源路径（可选）
    如果需要使用原生 OCR 识别功能，需配置 OCR 模型路径：

    bash
    mpelb config set-resource

    选择或输入包含 OCR 模型的资源目录路径。

提示

如果启动时未配置这些路径，LocalBridge 会提示您进行配置。

连接设备 ​

配置完成后，启动 LocalBridge 并在编辑器中连接本地服务，然后：

  1. 点击顶部工具栏的 连接设备 按钮
  2. 在连接面板中选择连接方式：
    • ADB 设备：支持全输出模式的模拟器（如 MuMu、BlueStacks 等）
    • Win32 窗口：支持 Windows 桌面窗口截图
    • PlayCover：mac 原生支持
    • Gamepad：手柄协议
  3. 选择目标设备或窗口，点击 连接

连接成功后，顶部会显示设备信息，此时可以使用所有字段快捷工具。

自动重连

切换到已连接设备时，会自动重新连接到该设备。

工具面板入口 ​

MPE 提供了两种方式访问字段快捷工具:

字段面板快捷入口 ​

在字段右侧，对于特定类型的字段,您会看到对应的工具按钮:

  • 区域选择 📷:适用于 roi、target、begin、end 等区域字段
  • 偏移测量 📏:适用于 roi_offset 字段
  • OCR 识别 🔤:适用于 expected 字段
  • 模板截图 📷:适用于 template 字段
  • 颜色取点 🎨:适用于 lower、upper 等颜色字段
  • 位移差值 📏:适用于 dx、dy 字段

这些按钮会根据当前选中字段的类型智能显示,点击后会自动填充结果到当前字段。

工具箱独立入口 ​

点击编辑区左上角的「工具箱」图标,可以打开工具箱面板。工具箱包含 6 个工具,支持:

  • 独立使用:无需选中节点或字段,直接点击工具即可使用
  • 结果预览:操作完成后显示结果,支持复制值或键值对
  • 灵活应用:可用于查看截图、测试参数等不一定需要填充到字段的场景

OCR 识别工具 ​

功能说明 ​

用于识别指定区域的文字内容，支持前端和原生两种识别模式。

使用步骤 ​

  1. 选中需要填写的字段
    例如 OCR 任务的 expected 字段。
  2. 点击 OCR 按钮
    打开 OCR 识别面板。
  3. 截取当前画面
    • 首次打开会自动截图
    • 也可以点击「刷新截图」重新获取画面
  4. 框选识别区域
    • 在截图上拖动鼠标框选包含文字的区域
    • 也可以手动输入坐标（X, Y, W, H）
  5. 选择识别模式
    • 前端 OCR（Tesseract.js）（推荐）：
      • 基于当前截图识别，不会因窗口更新导致内容不一致
      • 支持 100+ 多语言混合识别
      • 速度较快（首次需加载模型）
    • 原生 OCR（MaaFramework）：
      • 使用本地 OCR 模型识别
      • 会重新截取当前窗口画面，可能因窗口更新导致内容不一致
      • 速度较慢，无后处理
  6. 确认结果
    • 框选后系统会自动识别
    • 识别完成后可以编辑结果文本
    • 点击「确认」将文本和 ROI 填入字段

操作技巧 ​

  • 缩放查看：使用鼠标滚轮缩放截图，精确框选文字区域
  • 拖动视图：按住鼠标中键或 Shift+左键拖动查看大图
  • 手动编辑：识别结果可以手动修改，适应各种特殊情况
  • 清空重来：点击「清空」按钮清除识别结果，重新框选

模板截图工具 ​

功能说明 ​

用于截取指定区域的图像作为模板，保存到本地并自动填入 template 字段。

使用步骤 ​

  1. 选中 template 字段
    在字段面板中点击 template 字段。
  2. 点击截图按钮
    打开模板截图面板。
  3. 截取画面
    • 自动截取当前设备画面
    • 可以点击「刷新截图」更新画面
  4. 框选模板区域
    • 拖动鼠标框选需要作为模板的区域
    • 也可以手动输入坐标（X, Y, W, H）
  5. 遮罩涂绿
    • 使用涂色与擦除工具进行遮罩绘制
    • 导出时会自动取消不透明度
  6. 保存模板
    • 输入文件名（不需要输入后缀，自动添加 .png）
    • 系统会智能识别保存路径：
      • 优先使用项目中的 image 或 template 目录
      • 如果不存在，默认保存到根目录
    • 点击「确认」保存图片并填入字段

智能路径识别 ​

系统会自动查找项目中适合保存图片的目录，优先级如下：

  1. {root}/image/
  2. {root}/template/
  3. {root}/images/
  4. {root}/templates/
  5. {root}/ （根目录）

保存成功后，字段中会自动填入相对路径，例如 image/my-template.png。

ROI 区域选择工具 ​

功能说明 ​

用于框选识别区域(Region of Interest),快速填写 roi、target、begin、end 等区域字段。

使用步骤 ​

  1. 选中 roi 字段
    在字段面板中点击 roi 字段。
  2. 点击截图按钮
    打开 ROI 选择面板。
  3. 截取画面并框选
    • 自动截取当前设备画面
    • 拖动鼠标框选目标区域
    • 或手动输入坐标(X, Y, W, H)
  4. 确认区域
    点击「确认」将区域坐标填入 roi 字段,格式为 [x, y, w, h]。

ROI 偏移测量工具 ​

功能说明 ​

用于测量两个区域之间的偏移量,快速配置 ROI 偏移相关字段。通过在截图上先后框选两个区域,系统会自动计算出它们之间的偏移差值。

使用步骤 ​

  1. 选中相关字段
    在字段面板中选择需要配置 ROI 偏移的字段。
  2. 点击偏移测量按钮
    打开 ROI 偏移测量面板。
  3. 截取画面
    • 自动截取当前设备画面
    • 可以点击「刷新截图」更新画面
  4. 框选第一个区域(基准区域)
    • 拖动鼠标框选第一个目标区域
    • 或手动输入坐标(X, Y, W, H)
  5. 框选第二个区域(目标区域)
    • 继续拖动鼠标框选第二个目标区域
    • 系统会自动计算两个区域的偏移量
  6. 查看偏移结果
    • 面板会显示两个区域的坐标
    • 自动计算并显示偏移差值 [dx, dy, dw, dh]
  7. 确认填入
    点击「确认」将偏移量填入对应字段。

应用场景 ​

  • 相对定位:测量 UI 元素之间的相对位置关系
  • 区域比对:比较同一界面中不同区域的位置差异
  • 动态适配:为不同分辨率计算区域偏移参数

颜色拾取工具 ​

功能说明 ​

用于从截图中提取颜色值,支持多种颜色格式。

使用步骤 ​

  1. 选中颜色相关字段
    例如 lower、upper 等颜色字段。
  2. 点击取色按钮
    打开颜色拾取面板。
  3. 截取画面
    • 自动截取当前设备画面
    • 可以点击「刷新截图」更新画面
  4. 选择颜色模式
    • RGB 模式:输出格式为 [R, G, B],适用于大多数颜色识别场景
    • HSV 模式:输出格式为 [H, S, V],适用于需要在不同亮度下识别颜色的场景
    • GRAY 模式:输出格式为 [Gray],适用于灰度图像处理
  5. 选择颜色 直接点击截图上的任意像素,获取该点颜色并按选定模式转换。
  6. 确认填入
    点击「确认」将颜色值填入对应字段。

颜色模式说明 ​

模式格式取值范围适用场景
RGB[R, G, B]0-255常规颜色识别,精确匹配颜色
HSV[H, S, V]H: 0-360, S/V: 0-100光照变化场景,容忍亮度差异
GRAY[Gray]0-255灰度图像,黑白界面识别

颜色范围预览 ​

取色工具支持颜色范围预览功能，可以在设置 lower/upper 边界后实时查看匹配效果。

使用方式：

  1. 在取色面板底部的「颜色范围预览」区域，分别输入颜色的下界（lower）和上界（upper）值
  2. 点击「预览」按钮，截图上会自动高亮显示落在指定颜色范围内的所有像素
  3. 面板会显示匹配的像素总数和占总像素的百分比

预览效果：

  • 命中像素：使用半透明绿色高亮显示
  • 非命中像素：使用半透明黑色遮罩，便于区分
  • 统计信息：显示匹配像素数量和百分比，帮助您判断颜色范围是否合理

提示

颜色范围预览可以帮助您快速验证 lower/upper 参数的合理性，避免设置过宽或过窄的颜色范围。取色后会自动填入对应边界，您可以手动微调后再预览。

测距工具 ​

适用字段：dx、dy（Scroll 滚动动作）

功能说明：通过在截图上拖动鼠标，直观地计算水平（dx）或垂直（dy）方向的滚动距离，用于配置滚动操作。

提示

  • dx（水平滚动）：正值向右滚动，负值向左滚动
  • dy（垂直滚动）：正值向下滚动，负值向上滚动
  • 仅 Win32 控制器支持滚动操作，ADB 控制器不支持

使用步骤 ​

  1. 找到 dx 或 dy 字段
    在 Scroll 动作节点中找到滚动距离字段。
  2. 点击位移差值按钮
    打开位移差值配置面板。
  3. 截取画面
    • 自动截取当前设备画面
    • 可以点击「刷新截图」更新画面
  4. 拖动测量距离
    • dx 模式：在截图上从起点水平拖动到终点，计算水平距离
    • dy 模式：在截图上从起点垂直拖动到终点，计算垂直距离
    • 面板会实时显示起点、终点坐标和计算出的差值
  5. 调整数值（可选）
    可以手动修改计算出的差值，支持负值表示反向滚动
  6. 确认填入
    点击「确认」将滚动距离填入对应字段。

常见问题 ​

无法连接设备 ​

可能原因：

  • MaaFramework 路径未配置或配置错误
  • ADB 设备未启动或连接异常
  • Win32 窗口已关闭

解决方法：

  • 运行 mpelb config set-lib 重新配置路径
  • 重启模拟器或检查 ADB 连接
  • 确保目标窗口正常运行

截图失败或显示黑屏 ​

可能原因：

  • 设备未正确连接
  • 模拟器不支持当前截图方式

解决方法：

  • 尝试断开并重新连接设备
  • 对于 ADB 设备，确保模拟器支持全输出模式
  • 对于 Win32 窗口，确保窗口未最小化

OCR 识别结果不准确 ​

解决方法：

  • 尝试切换识别模式（前端/原生）
  • 确保框选区域足够清晰，避免包含多余背景
  • 前端 OCR 首次使用需要下载模型，请耐心等待
  • 识别完成后可以手动编辑结果文本

模板保存路径不对 ​

解决方法：

  • 确保项目根目录配置正确（即 LocalBridge 启动时的 --root 参数）
  • 手动在项目中创建 image 或 template 目录
  • 系统会自动识别并优先使用这些目录

最佳实践 ​

  1. 保持设备连接：在编辑过程中保持设备连接状态，避免频繁重连。
  2. 合理使用 OCR 模式：
    • 编辑固定内容时使用「前端 OCR」，避免窗口更新干扰
    • 需要实时识别变化内容时使用「原生 OCR」
  3. 规范图片管理：
    • 在项目中创建专门的 image 或 template 目录
    • 使用有意义的文件名，方便后期维护
  4. 善用缩放和拖动：
    • 对于小字或复杂场景，放大查看可以提高框选精度
    • 使用快捷键（滚轮缩放、Shift+拖动）提高操作效率
  5. 验证结果：
    • 使用工具填入字段后，建议通过实际运行验证效果
    • 必要时手动调整坐标或颜色值以达到最佳效果