検出戦略

マクロがシンプルなタップを超えると、信頼性を左右する最大の要素はクリック自体ではなく、ターゲットをどのように検出するかです。高度なマクロは、自動化対象の UI に応じて適切な検出戦略を選択したときに最もよく機能します。

最もシンプルで信頼できるシグナルから始める

設定をチューニングする前に、まず最も安定したシグナルを選びます。

1. ターゲットの位置が決して変わらない場合のみ固定座標を使用する
2. 視覚的な形状が安定して特徴的な場合は画像検出を使用する
3. アイコンよりもラベルのほうが認識しやすい場合はテキスト検出を使用する
4. ターゲットがおおよそどこに現れるか分かっている場合は、より小さな Region() を使用する

複数の戦略が機能する場合は、検索範囲が最も小さく、曖昧さが最も少ないものを選んでください。

Screen と Region

最もよくあるパフォーマンス上の間違いは、すべてをフル画面で検索することです。

Screen を使うべきケース:

• ターゲットがほぼどこにでも現れる可能性がある
• マクロの最初のバージョンを作っている
• 新しいアプリフローを探索している

Region を使うべきケース:

• ターゲットが常に UI の既知のセクションに現れる
• 画面に繰り返し現れるアイコンやテキストが含まれている
• より高速で安定したマッチングを行いたい

local actionArea = Region(900, 1600, 1080, 2200)
actionArea:click("continue-button.jpg")

Fit Region テクニック

最も便利な高度なテクニックのひとつが、フィットリージョン（fit region）です。

考え方は次のとおりです。

1. Screen:find() を使ってオブジェクトを一度見つける
2. result:getRegion() を使ってそのマッチをフィットした Region に変換する
3. オブジェクトのサイズが安定しているなら、そのフィットリージョンを以降の検索に再利用する

この手法は次の場合にうまく機能します。

• オブジェクトが常に同じ幅と高さを持つ
• オブジェクトの内容は変わっても、コンテナの領域は一貫している
• フル画面検索が高コストで、頻繁に繰り返される

local result = Screen:find("inventory-panel.jpg")
if result then
    local fitRegion = result:getRegion()
    local collectButton = fitRegion:find("collect-button.jpg")
    if collectButton then
        fitRegion:click("collect-button.jpg")
    end
end

これが強力な理由:

• 最初のフル画面検索だけが高コストなステップ
• オブジェクトが一度見つかれば、以降の検索はすべてフィットした範囲内に限定される
• 繰り返しのフローで OCR と画像マッチングのコストを大幅に削減できる

フィットリージョンを使うべきケース:

• 安定したパネル、カード、ポップアップ、スロット、コンテナがある
• マクロが同じマッチしたオブジェクト内で繰り返し操作する
• 同じオブジェクトが異なる位置に現れるが、寸法は同じ

フィットリージョンを避けるべきケース:

• 画面やデバイス間でオブジェクトが大幅にリサイズされる
• ターゲット領域が動的に展開/折りたたまれる
• 最初のマッチが汎用的すぎて誤ったコンテナに束縛される可能性がある

実践上、フィットリージョンは、座標をハードコードせずに遅い Screen マクロを速い Region マクロに変換する最も良い方法のひとつです。

画像検出とテキスト検出

画像検出が適しているケース:

• ターゲットがほぼグラフィカルである
• UI の言語が変わる可能性がある
• テキストが装飾的、またはボタン内にレンダリングされている
• テキストが小さすぎたりコントラストが低すぎたりして OCR が苦戦する

テキスト検出が適しているケース:

• ラベルが位置を変えるが同じ文言を保つ
• 同じ視覚コンポーネントが多くのテーマや状態で現れる
• ボタンの形状は変わるがラベルは読み取れる
• アプリが動的に生成したテキストをマッチさせたい

Word-by-Word と Line-by-Line の OCR

テキスト検出を使う場合、検出方法が重要です。

• 単語や非常に短いラベルには setDetectionMethod(1) を使用
• フレーズや行全体がターゲットの場合は setDetectionMethod(2) を使用

Screen:click("Login", ClickParams():setDetectionType("TEXT"):setDetectionMethod(1))

Screen:wait("Your session has expired", 5000, FinderParams():setDetectionType("TEXT"):setDetectionMethod(2))

一致スコアを段階的にチューニングする

一致スコアが高すぎると検出漏れを招きます。低すぎると誤検知を招きます。

実践的なチューニング手順:

1. デフォルトのスコアで始める
2. ターゲットが見逃される場合はスコアを少し下げる
3. 別のものがマッチする場合はスコアを少し上げる
4. 両方が起きる場合は、スコアをさらに変える前に検索範囲を絞る

ほとんどの場合、Region() で曖昧さを減らすほうが、一致スコアを強く押し込むよりも安全です。

効果があるときだけグレースケールを使う

グレースケールは速度を向上させ、一貫性を高めることもありますが、常に優れているわけではありません。

グレースケールを使うべきケース:

• ターゲットが色よりも形状で定義される
• 照明や色の変動でマッチングが不安定になる
• ローエンドデバイスでより高速なマッチングを行いたい

グレースケールに頼るのを避けるべきケース:

• 色が類似ターゲット間の主な違いである
• アクティブ状態と非アクティブ状態を色で区別しようとしている

動的スケーリング

同じマクロが異なる解像度のデバイスで実行される場合、動的スケーリングにより画像検出が引き続き利用可能になります。

動的スケーリングを使うべきケース:

• テンプレートをあるデバイスでキャプチャしたが、別のデバイスで実行する
• 同じアプリのレイアウトがスマートフォンやタブレットでリサイズされる

ただし、単一デバイス上で UI の一貫性がすでに高い場合は、うまく切り抜かれたテンプレートと適切なリージョンのほうが、スケーリングを過剰にチューニングするよりも通常は安定します。

テンプレートを積極的に切り抜く

良いテンプレートは、ターゲットを一意にする要素だけを含むべきです。

良いテンプレート:

• アイコンそのもの
• 一意のラベル領域
• 最小限の安定した視覚パターン

悪いテンプレート:

• 広範な周囲の余白
• アニメーションする背景
• 実行のたびに変わるコンテンツ
• ターゲットの一部ではない近接要素

難しい画面には 2 段階検出を使う

画面がノイズだらけの場合は、段階的なアプローチを使います。

1. 安定したアンカー要素を待機する
2. 検索範囲を絞る
3. その範囲内で最終的なターゲットを検出する

Screen:wait("settings-title.jpg", 5000)

local footerArea = Region(0, 1700, 1080, 2400)
footerArea:click("save-button.jpg")

推奨パターン

高度なマクロでは、通常は次の順序が最も安全です。

1. 安定した状態を待つ
2. 検索範囲を絞る
3. 意図的に画像検出かテキスト検出を選ぶ
4. 曖昧さを減らしてからスコアをチューニングする
5. 続行する前に結果を検証する

関連ページ

• ベストプラクティス
• 画像/テキストの検出
• 画像またはテキストが表示/消失するまで待機する