# 画像認識マクロの仕組み: MAS の基本概念

> MAS の画像認識マクロの仕組み: テンプレート画像と OCR で Android の画面を読み取り、人間らしい入力を adb で送り、マクロがどこで動くかを説明します。

Source: https://automationmacro.com/ja/docs/concepts (はじめに, updated 2026-09-05)

Macro Automation Studio (MAS) は、人がやるのと同じ方法で Android アプリを自動化します。画面を見て、判断し、タップします。このページでは、画像認識マクロの仕組み、アプリで出会う用語、そして各部分がどこで動くかを説明します。一度読めば、残りのドキュメントが理解しやすくなります。

## 画像認識マクロが画面を見る仕組み

MAS は APK を改変せず、アプリのメモリも読みません。adb を通して外側から、3 つの部品で動きます。

### テンプレート画像

テンプレートとは画面の小さな切り抜きです: ボタン、アイコン、バッジなど。Asset Lab でライブのデバイス画面から切り出すと、数値の ID 付きで画像ライブラリに入り、スクリプトはその ID で参照します。実行時に `find_object` が新しいスクリーンショットを撮り、OpenCV のテンプレートマッチングでその中からテンプレートを探します。一致には既定で 0.8 の類似度 (`threshold=0.8`) が必要で、中心点を返すので、次の行でタップできます。

画像ファイルは jpg、png、gif、webp で、1 枚 10 MB までです。テンプレートは小さく特徴的にしてください。画面全体はその画面だけにしか一致しませんが、ボタンならボタンが出る場所ならどこでも一致します。

### Android での OCR 自動化

文字は `read_text` を通して Tesseract OCR で読みます。`Region(x1, y1, x2, y2)` を渡すと、画面全体ではなく 1 つのカウンターや 1 つのラベルだけを見るようになり、ページセグメンテーションモード (1 行なら `psm=7`、1 語なら `psm=8`) も指定できます。`ColorConversion.BLACK_WHITE` は、ノイズの多い背景上の色付き文字に役立ちます。Asset Lab にはライブの OCR テストがあるので、コードに入れる前に領域を調整できます。

### 人間らしい入力

入力は本物のタッチイベントとキーイベントとして送られます: `click`、`swipe`、`input_text`、`key_press`、`zoom_in`、`zoom_out`。タイミングは自由に設定できます。`click` はタップ後に `delay_ms=1000` 待ち、`swipe` は `duration_ms=1000` かけて動き、500 ms 以上押したキーは長押しになります。ゆっくり、間隔を空けたマクロほど機械的に見えません。

### 座標と画面サイズ

すべての座標は画面左上からのピクセルオフセットです。`get_screen_size()` は幅と高さを、`get_device_info()` はそれに加えてデバイス名を返します。テンプレートと領域は、取り込んだときの解像度と DPI に結び付いています。マクロを動かすすべてのデバイスを、作ったときと同じ解像度にしてください。各エミュレータのガイドで推奨サイズを示しており、クラウドデバイスは固定のディスプレイプリセットで作成されます。

## 用語

| 用語 | MAS での意味 |
|---|---|
| マクロ | デバイス上で 1 つの作業を自動化する Python プログラム。実行、スケジュール、共有、販売の単位です。 |
| プロジェクト | マクロの背後にあるフォルダー: `src/app.py`、任意の引数フォーム、アセット、git の履歴。 |
| デバイス | MAS が操作できる 1 台の Android 対象。adb ポート、クラウドデバイスなら ID で識別します。 |
| デバイスグループ | **デバイスグループ** ページ上の、名前の付いたデバイスの集まり。グループ内の各デバイスは固有のマクロ、引数、プロキシ、Webhook を持ち、**すべて開始** で順番に実行します。 |
| 設定プロファイル | 1 つのマクロ向けの、名前の付いた引数値のセット。デバイスはプロファイルに従うので、変更するとそれを使うすべてのデバイスが更新されます。「Default」は常に存在します。 |
| クラウドデバイス | MAS が自社サーバー上で代わりに動かす Android デバイス。その上のマクロはサーバー側で動き、画面は WebRTC で配信されます。 |
| MAS Agent | **エージェント** ページの AI 作成者。作業を説明すると、デバイスを探索し、判断が必要なときは質問し、3 回の検証実行に合格するマクロを組み上げます。 |
| Marketplace | アプリ内の既製 bot のカタログ。ダウンロードすると **マクロ** 内のマクロになります。 |
| Asset Lab | ライブ画面でテンプレートの切り出し、座標の取得、OCR 領域のテストを行う補助アプリ。 |
| UI Builder | 引数フォーム (`.uibproj`) とランタイムダッシュボード (`.uibrt`) のデザイナー。 |
| Code Editor | MAS 内蔵の Python IDE。**マクロ** からプロジェクトごとに開き、デバッガーと実行コンソールがあります。 |

## 動く場所

作業は 3 つの場所で行われます。今どれを見ているかを知っておくと役立ちます。

### あなたのコンピューターがエミュレータを操作する

PC や Mac 上の MAS は、プロセス名と待ち受けポートでエミュレータを見つけ、それぞれと `adb connect 127.0.0.1:<port>` で通信します。ローカルデバイスのスクリーンショット、タップ、OCR はすべてあなたのマシン上で行われるため、マクロの実行中はアプリを開いたままにする必要があります。スケジューラーも同じです。

### クラウドデバイスは MAS のクラウドで動く

クラウドデバイスは MAS のサーバー上にあります。そこでマクロを実行すると、MAS がプロジェクトのスナップショットをアップロードし、デバイスの隣で実行します。アプリで画面をライブで見ることも、アプリを完全に閉じることもできます。どちらでも実行は続きます。アイドル状態のデバイスは約 1 時間の無操作で停止し、データは保持されます。

### スクリプトは JSON-RPC でアプリと通信する

マクロは普通の Python プロセスです。MAS は独自の Python 3.13 環境内で `python -u -m src.app` として起動し、接続情報を環境変数 (`MAS_RPC_PORT`、`MAS_RPC_HOST`、`MAS_DEVICE_ID`、`MAS_SESSION_TOKEN`) で渡します。すべての `mas.*` 呼び出しは、ローカルソケット経由の JSON-RPC 2.0 リクエストです。アプリが adb、OpenCV、Tesseract を持ち、結果を返します。クラウドデバイスでは同じ呼び出しがサンドボックス内の unix ソケットを通ります。これが、`import mas` にインストールが不要な理由であり、MAS の外で起動したスクリプトが「Could not discover RPC port」と報告する理由です。

### AI は作成時だけ、実行時には使わない

MAS Agent は探索とコンパイルの間に AI クレジットを使います。生成されるマクロは素の Python で、他のマクロと同じように、エミュレータでもクラウドデバイスでも、エージェントを介さずに動きます。

## サブスクリプション

アプリ内のページは、サインインと **サブスクリプション** を除いてすべて、有効な利用資格 (無料トライアルか有料プラン) を必要とします。プランの大きさはデバイス数で決まります。つまり、自分のエミュレータやスマホを同時に何台動かせるかです。クラウドデバイスは月ごとのクレジット付きのアドオンで、エージェントのセッション用にクレジットを追加購入できます。解約しても支払い済み期間の終わりまで利用できます。仕組みは [お支払い](/docs/billing) ページに、金額は [料金ページ](/pricing) にあります。

## 次に読むもの

[デバイス](/docs/devices) ページでデバイスを設定するか、[Asset Lab](/docs/asset-lab) で最初のテンプレートを切り出すか、コードから始めたければ [SDK 概要](/docs/sdk) をお読みください。