Skip to content

Latest commit

 

History

History
199 lines (143 loc) · 8.07 KB

1.1-快速开始.md

File metadata and controls

199 lines (143 loc) · 8.07 KB
Raw

快速开始

开发思路

MaaFramework 支持完全通过 Json 低代码编程（Pipeline Json），同时也提供了 接口 以供开发者自行集成。
亦可将两者结合，将低代码作为一种 “封装” 进行调用。
下面介绍几种常用的集成方式：

完全依赖 Json 低代码编程（使用 MaaPiCli.exe）

简单快捷，但不够灵活，推荐 MaaFramework 初学者及编程小白使用。
我们为此方式提供了 🎞️视频教程 和 ⭐项目模板。以下是一个例子：

// Json 不支持注释，此处为伪代码，仅供参考思路，无法直接运行
{
    "识别并点击开始按钮": {
        "recognition": "OCR",           // 文字识别
        "expected": "开始",             // 要识别的字
        "action": "Click",              // 动作：点击
        "next": [
            "识别并点击确定图标",
        ]
    },
    "识别并点击确认图标": {
        "recognition": "TemplateMatch", // 图片模板匹配
        "template": "确认.png",         // 图片文件名
        "action": "Click"
    }
}

使用 Json 低代码编程，但对复杂任务使用自定义逻辑

通过接口启动 CLI，同时注册部分自定义任务。该方法可从 1 中无缝切换。以下是一个例子：

{
    "识别并点击确认图标": {
        "next": [
            "我的自定义任务"
        ]
    },
    "我的自定义任务": {
        "recognition": "Custom",
        "custom_recognition": "MyReco",
        "action": "Custom",
        "custom_action": "MyAct"
    }
}
# 此处为伪代码，仅供参考思路，无法直接运行
def main():
    # 注册自定义识别器
    maafw.Toolkit.register_custom_recognition("MyReco", MyRecognition())

    # 注册自定义动作
    maafw.Toolkit.register_custom_action("MyAct", MyAction())

    # 启动 MaaPiCli
    maafw.Toolkit.run_pi_cli("C:/MaaXXX/resource", "C:/MaaXXX/cache")

class MyRecognition(CustomRecognition):
    def analyze(context, ...):
        # 获取图片，然后进行自己的图像操作
        image = context.tasker.controller.cached_image
        # 返回图像分析结果
        return AnalyzeResult(box=(10, 10, 100, 100))

class MyAction(CustomAction):
    def run(context, ...):
        # 进行点击
        context.controller.post_click(100, 10).wait()
        # 重写接下来要执行的任务
        context.override_next(task_name, ["TaskA", "TaskB"])

自行编写代码

可以将低代码作为一种“封装”进行调用，亦可注册自定义回调使用

# 此处为伪代码，仅供参考思路，无法直接运行
# "识别并点击开始按钮", "识别并点击确认图标" 等均为 Json 中的逻辑
def main():
    detail = tasker.post_pipeline("识别并点击开始按钮").wait().get()

    if detail.completed:
        tasker.controller.post_click(100, 100).wait()

    else:
        image = tasker.controller.cached_image
        save_to_file(image)

        tasker.resource.register_custom_action("MyAction", MyAction())
        tasker.post_pipeline("识别并点击确认图标").wait()

    image: np.ndarray = tasker.controller.post_screencap().wait().get()

准备资源文件

⭐若您使用项目模板，直接在 文件夹 中修改即可。

您需要准备一些资源文件，典型的文件结构 如下：

my_resource
├── image
│   ├── my_image_1.png
│   └── my_image_2.png
├── model
│   └── ocr
│       ├── det.onnx
│       ├── keys.txt
│       └── rec.onnx
└── pipeline
    ├── my_pipeline_1.json
    └── my_pipeline_2.json

其中以 my_ 开头的文件/文件夹均可自行修改名称，其他的则为固定文件名，不可修改，下面依次介绍：

Pipeline JSON 文件

my_resource/pipeline 中的文件，包含主要的脚本执行逻辑，会递归读取目录中所有的 json 格式文件。

可参考 任务流水线协议 进行编写，一个简单的 demo

小工具：

  • JSON Schema
  • VSCode 插件
    • 基于 interface.json 配置资源
    • 支持跳转到任务定义、查找任务引用、重命名任务、补全任务、点击执行任务
    • 支持按照 MaaPiCli 模式执行
    • 支持连接后截图并裁剪图片

图片文件

my_resource/image 中的文件，主要为 pipeline 所用到的模板匹配图片、特征检测图片等，会按照 pipeline 中设定的 template 等字段读取对应的文件。

所使用的图片需要是无损原图缩放到 720p 后的裁剪。若使用安卓模拟器，请使用模拟器自带的截图功能！（不可以直接对模拟器窗口进行截图）

除非你完全清楚 MaaFramework 在做什么，否则请使用下面的截图工具来获取图片。

文字识别模型文件

⭐若您使用项目模板，直接按照其文档，运行 configure.py 即可自动部署模型文件。

my_resource/model/ocr 中的文件，为 PaddleOCR 转 ONNX 后的模型文件。

可使用我们的预转换文件：MaaCommonAssets，选择需要的语种，按照 上述 目录结构存放即可。

若有需要也可以自行对 PaddleOCR 的官方预训练模型进行 fine-tuning （请自行参考 PaddleOCR 官方文档），并转换成 ONNX 文件使用，转换命令可参考 这里

调试

  • 推荐使用 MaaDebugger 。

  • 若使用 MaaPiCli ，会在同目录下生成 config/maa_option.json 文件，其中：

    • logging: 保存日志，会生成 debug/maa.log。默认 true 。
    • recording: 保存录像功能，会保存运行期间所有的截图及操作数据，可使用 DbgController 进行复现调试。默认 false 。
    • save_draw: 保存图像识别可视化结果，会保存运行期间所有图像识别可视化结果绘制图。默认 false 。
    • show_hit_draw: 显示任务命中弹窗，每次识别成功会弹窗显示识别结果。默认 false 。
    • stdout_level: 控制台显示日志等级。默认 2（Error），可设为 0 关闭全部控制台日志，或设为 7 打开全部控制台日志。

  • 若自行集成，可通过 Toolkit.init_option / MaaToolkitConfigInitOption 接口开启调试选项。生成的 json 文件同上。

运行

使用 MaaPiCli（通用 CLI）或者 自行编写集成代码

使用 MaaPiCli

⭐若您使用项目模板，直接按照其文档，运行 install.py 后即可自动打包相关文件

使用 Release 包 bin 文件夹中的 MaaPiCli ，并编写 interface.json 置于同目录下，即可使用

该 Cli 已完成基本功能开发，更多功能不断完善中！详细文档待进一步完善，当前可参考 Sample 编写

实践:

自行编写集成代码

请参考 集成文档

实践:

  • MAABH3 基于 C++ & cmake 的集成实践
  • MBA 基于 C# .NET 的集成实践