🔍 PyAutoGUI 画像認識

📖 はじめに

PyAutoGUIの画像認識機能を使用すると、あらかじめ用意した画像と同じものを画面上から探し、その位置を取得できます。

例えば、「保存」ボタンの画像を用意しておけば、

画面上から保存ボタンを探す
ボタンの中心座標を取得する
その位置をクリックする

という処理を自動化できます。

座標を直接指定する方法と比べて、ウィンドウの位置が多少変わっても対象を見つけられることが利点です。

PyAutoGUIの画像認識は、画面に表示されている画像と、用意した見本画像を比較して位置を探す仕組みです。

🧩 画像認識の仕組み

画像認識では、探したいボタンやアイコンを小さな画像ファイルとして保存します。

例えば、画面上にある「保存」ボタンを探す場合は、そのボタン部分だけを切り抜いて、次のようなファイル名で保存します。

save_button.png

この見本画像をPyAutoGUIへ渡すと、現在の画面から同じ画像を検索します。

見本画像は一般に、次のように呼ばれます。

検索画像
テンプレート画像
参照画像
ニードル画像

この記事では「検索画像」と呼びます。

📦 必要なライブラリ

画像認識にはPyAutoGUIを使用します。

import pyautogui

一致率を指定するconfidenceを利用する場合は、OpenCVも必要です。

pip install opencv-python

実際の画面では色や描画にわずかな差が生じることがあるため、画像認識を利用する場合はOpenCVもインストールしておくことを推奨します。

✂️ 検索画像を準備する

最初に、探したいボタンやアイコンの画像を用意します。

検索対象の周囲を含めすぎず、対象を識別できる範囲で切り抜きます。

例えば保存ボタンを探す場合は、保存ボタンだけが入るように切り抜きます。

検索画像は、Pythonファイルと同じフォルダに保存しておくと扱いやすくなります。

automation/
├─ main.py
└─ save_button.png

検索画像に広い背景を含めると、ウィンドウサイズや周囲の表示が変化しただけで認識できなくなることがあります。

📍 画像の位置を探す

画面上から画像を探すにはlocateOnScreen()を使用します。

import pyautogui

location = pyautogui.locateOnScreen(
    "save_button.png"
)

print(location)

画像が見つかると、次のような情報が取得できます。

Box(left=800, top=500, width=100, height=40)

それぞれの値は次の意味を持ちます。

項目	意味
`left`	画像の左端のX座標
`top`	画像の上端のY座標
`width`	画像の幅
`height`	画像の高さ

locateOnScreen()は画像の中心座標ではなく、画像が存在する長方形の範囲を返します。

🎯 画像の中心座標を取得する

取得した範囲の中心座標はcenter()で求められます。

import pyautogui

location = pyautogui.locateOnScreen(
    "save_button.png"
)

center = pyautogui.center(location)

print(center)

実行結果は次のようになります。

Point(x=850, y=520)

この座標をクリックすれば、画像の中央をクリックできます。

pyautogui.click(center)

🖱️ 画像を探してクリックする

画像を探してクリックする一連の処理は次のように記述できます。

import pyautogui

location = pyautogui.locateOnScreen(
    "save_button.png"
)

center = pyautogui.center(location)

pyautogui.click(center)

🎯 中心座標を直接取得する

locateCenterOnScreen()を使用すると、画像の検索と中心座標の取得をまとめて実行できます。

import pyautogui

center = pyautogui.locateCenterOnScreen(
    "save_button.png"
)

pyautogui.click(center)

単純に画像を探してクリックする場合は、この書き方が便利です。

さらに短くすると、次のように記述できます。

import pyautogui

pyautogui.click(
    pyautogui.locateCenterOnScreen(
        "save_button.png"
    )
)

ただし、画像が見つからなかった場合の処理を追加しにくいため、変数へ代入してからクリックする方が安全です。

画像をクリックする処理では、locateCenterOnScreen()で座標を取得してからclick()を実行する書き方が分かりやすく、後から例外処理も追加できます。

🎚️ 一致率を指定する

画面上の画像は、表示環境によってわずかに異なることがあります。

例えば、次のような違いが発生します。

アンチエイリアスによる輪郭の違い
色のわずかな違い
マウスを重ねたときの表示変化
OSやアプリケーションによる描画の違い

完全一致では見つからない場合は、confidenceで一致率を指定します。

import pyautogui

center = pyautogui.locateCenterOnScreen(
    "save_button.png",
    confidence=0.9
)

pyautogui.click(center)

confidence=0.9は、おおむね90％以上一致する画像を検索する指定です。

confidenceを使用するにはOpenCVが必要です。

confidence=0.9前後から試し、見つからない場合に少しずつ下げて調整すると原因を確認しやすくなります。

⚠️ 一致率を下げすぎない

一致率を下げると画像を見つけやすくなりますが、別の画像を誤って認識する可能性も高くなります。

例えば、似た形のボタンが複数ある画面で一致率を低くすると、違うボタンをクリックすることがあります。

center = pyautogui.locateCenterOnScreen(
    "save_button.png",
    confidence=0.6
)

このように低い値を指定する場合は、誤認識が発生しないか十分な確認が必要です。

confidenceを安易に下げすぎると、別のボタンを誤認識してクリックする危険があります。 削除・送信・確定など、取り消しにくい操作では特に注意してください。

❌ 画像が見つからなかった場合

現在のPyAutoGUIでは、画像が見つからなかった場合にImageNotFoundExceptionが発生します。

次のコードは、対象画像が画面にない場合にエラーで停止します。

center = pyautogui.locateCenterOnScreen(
    "save_button.png",
    confidence=0.9
)

安全に処理するには、tryとexceptを使用します。

import pyautogui

try:
    center = pyautogui.locateCenterOnScreen(
        "save_button.png",
        confidence=0.9
    )

    pyautogui.click(center)

except pyautogui.ImageNotFoundException:
    print("画像が見つかりませんでした。")

これで、画像が見つからなかった場合もプログラムが異常終了しません。

画像認識を業務で利用する場合は、画像が見つからないことを想定し、ImageNotFoundExceptionを処理することを推奨します。

⏳ 画像が表示されるまで待つ

アプリケーションやWebページの読み込みには時間がかかることがあります。

固定時間だけ待機する方法もあります。

import time

time.sleep(3)

しかし、表示にかかる時間が毎回違う場合は、画像が表示されるまで繰り返し検索する方が安定します。

import time
import pyautogui

while True:
    try:
        center = pyautogui.locateCenterOnScreen(
            "save_button.png",
            confidence=0.9
        )

        pyautogui.click(center)
        break

    except pyautogui.ImageNotFoundException:
        time.sleep(0.5)

このコードは、0.5秒ごとに画像を検索し、見つかったらクリックして繰り返しを終了します。

⏱️ タイムアウトを設定する

画像が表示されないまま無限に待ち続けると、プログラムが終了しなくなります。

そこで、一定時間が経過したら検索を終了するようにします。

import time
import pyautogui

timeout = 10
start_time = time.time()

while True:
    try:
        center = pyautogui.locateCenterOnScreen(
            "save_button.png",
            confidence=0.9
        )

        pyautogui.click(center)
        print("保存ボタンをクリックしました。")
        break

    except pyautogui.ImageNotFoundException:
        if time.time() - start_time >= timeout:
            print("保存ボタンが見つかりませんでした。")
            break

        time.sleep(0.5)

この例では、最大10秒間検索します。

待機処理にはタイムアウトを設けてください。画像が表示されない場合に、プログラムが永久に待ち続けることを防げます。

🧰 待機処理を関数にする

画像が表示されるまで待つ処理は何度も使用するため、関数にすると便利です。

import time
import pyautogui


def wait_for_image(
    image_path,
    timeout=10,
    confidence=0.9,
    interval=0.5
):
    start_time = time.time()

    while time.time() - start_time < timeout:
        try:
            return pyautogui.locateCenterOnScreen(
                image_path,
                confidence=confidence
            )

        except pyautogui.ImageNotFoundException:
            time.sleep(interval)

    return None

次のように使用します。

center = wait_for_image(
    "save_button.png",
    timeout=10
)

if center is not None:
    pyautogui.click(center)
else:
    print("保存ボタンが見つかりませんでした。")

この関数は、

画像が見つかった場合は中心座標を返す
タイムアウトした場合はNoneを返す

という動作をします。

🔲 検索範囲を指定する

画面全体ではなく、一部分だけを検索できます。

検索範囲はregionで指定します。

center = pyautogui.locateCenterOnScreen(
    "save_button.png",
    confidence=0.9,
    region=(500, 300, 800, 500)
)

regionには次の順番で値を指定します。

(left, top, width, height)

この例では、

左端：500
上端：300
幅：800
高さ：500

の範囲だけを検索します。

検索対象が表示される位置をある程度限定できる場合は、検索範囲を指定することで処理を効率化できます。

ボタンが必ず画面右下に表示されるなど、位置を限定できる場合はregionを指定すると、検索速度と誤認識の両方を改善できます。

⚫ グレースケールで検索する

grayscale=Trueを指定すると、画像を白黒に変換して比較できます。

center = pyautogui.locateCenterOnScreen(
    "save_button.png",
    confidence=0.9,
    grayscale=True
)

色の比較を省略できるため、検索が速くなる場合があります。

ただし、色の違いでボタンを区別している場合は、誤認識しやすくなります。

色が重要な画面ではgrayscale=Trueを使用しないでください。形が同じで色だけが異なるボタンを区別できなくなる可能性があります。

🔢 同じ画像をすべて探す

画面上に同じ画像が複数ある場合は、locateAllOnScreen()を使用します。

import pyautogui

locations = pyautogui.locateAllOnScreen(
    "checkbox.png",
    confidence=0.9
)

for location in locations:
    print(location)

それぞれの中心をクリックすることもできます。

import pyautogui

locations = pyautogui.locateAllOnScreen(
    "checkbox.png",
    confidence=0.9
)

for location in locations:
    center = pyautogui.center(location)
    pyautogui.click(center)

locateAllOnScreen()は、見つかったすべての位置を順番に取得できるオブジェクトを返します。

📸 検索画像を作るためにスクリーンショットを保存する

PyAutoGUIでは、スクリーンショットをファイルへ保存できます。

import pyautogui

pyautogui.screenshot(
    "screen.png"
)

画面の一部分だけを保存することもできます。

import pyautogui

pyautogui.screenshot(
    "button_area.png",
    region=(700, 400, 300, 200)
)

保存した画像を画像編集ソフトで開き、必要なボタン部分だけを切り抜いて検索画像にします。

🗂️ 画像ファイルを整理する

検索画像が増えてきたら、画像専用のフォルダを作成すると管理しやすくなります。

automation/
├─ main.py
└─ images/
   ├─ save_button.png
   ├─ close_button.png
   ├─ login_button.png
   └─ error_dialog.png

Pythonからは次のように指定します。

center = pyautogui.locateCenterOnScreen(
    "images/save_button.png",
    confidence=0.9
)

pathlibを使用すると、パスをより安全に管理できます。

from pathlib import Path
import pyautogui

image_path = Path("images") / "save_button.png"

center = pyautogui.locateCenterOnScreen(
    str(image_path),
    confidence=0.9
)

🧪 画像が見つからない主な原因

🖼️ 検索画像と画面の大きさが違う

PyAutoGUIの画像検索は、基本的に同じ大きさで表示されている画像を探します。

次のような変更があると、認識できない場合があります。

Windowsの表示倍率を変更した
ブラウザのズーム倍率を変更した
アプリケーションの拡大率を変更した
別の解像度で検索画像を作成した

検索画像を作成したときと実行時で、画面の表示倍率やブラウザのズーム倍率をそろえてください。

🎨 ボタンの表示状態が違う

ボタンは状態によって見た目が変わることがあります。

例えば、次のような状態があります。

通常状態
マウスオーバー状態
押下状態
無効状態
選択状態

通常状態の画像では、マウスオーバー状態のボタンを認識できないことがあります。

必要に応じて状態ごとの画像を用意します。

save_button_normal.png
save_button_hover.png
save_button_disabled.png

🪟 対象がほかのウィンドウに隠れている

PyAutoGUIが検索できるのは、現在画面上に表示されている画像です。

対象が次の状態では検索できません。

別のウィンドウに隠れている
最小化されている
画面外にある
別の仮想デスクトップにある

PyAutoGUIはアプリケーション内部の部品を直接調べるのではなく、現在表示されている画面を検索します。

🖥️ 複数ディスプレイやDPI設定の影響

複数ディスプレイを使用している場合や、ディスプレイごとに表示倍率が異なる場合は、座標や画像サイズに差が生じることがあります。

画像認識が安定しない場合は、次の条件を確認します。

対象アプリを表示するディスプレイ
各ディスプレイの表示倍率
解像度
アプリケーションのウィンドウサイズ

🛡️ 安全なクリック処理

画像を見つけた直後にクリックするのではなく、クリック前に少し待機すると、画面状態が安定する場合があります。

import time
import pyautogui

try:
    center = pyautogui.locateCenterOnScreen(
        "save_button.png",
        confidence=0.9
    )

    pyautogui.moveTo(
        center.x,
        center.y,
        duration=0.5
    )

    time.sleep(0.3)

    pyautogui.click()

except pyautogui.ImageNotFoundException:
    print("保存ボタンが見つかりませんでした。")

カーソルをゆっくり移動させることで、クリック位置を目視確認しやすくなります。

💡 実践例：ボタンを待ってクリックする

次のコードは、画像認識を利用した基本的な実践例です。

import time
from pathlib import Path

import pyautogui


pyautogui.FAILSAFE = True
pyautogui.PAUSE = 0.3

image_path = Path("images") / "save_button.png"
timeout = 10
start_time = time.time()

while time.time() - start_time < timeout:
    try:
        center = pyautogui.locateCenterOnScreen(
            str(image_path),
            confidence=0.9,
            region=(500, 300, 1000, 700)
        )

        pyautogui.moveTo(
            center.x,
            center.y,
            duration=0.5
        )

        pyautogui.click()

        print("保存ボタンをクリックしました。")
        break

    except pyautogui.ImageNotFoundException:
        time.sleep(0.5)

else:
    print("制限時間内に保存ボタンが見つかりませんでした。")

このコードには、実用上重要な要素が含まれています。

フェイルセーフを有効にする
検索範囲を限定する
一致率を指定する
画像が現れるまで待つ
タイムアウトを設定する
クリック前にカーソルを移動する
見つからなかった場合を処理する

⚠️ 画像認識を安定させるポイント

画像認識を安定させるには、次の条件をできるだけ固定します。

画面解像度
Windowsの表示倍率
ブラウザのズーム倍率
アプリケーションのウィンドウサイズ
テーマ設定
ダークモード・ライトモード
検索対象の表示状態

また、検索画像は対象を識別できる範囲で、できるだけ小さく切り抜きます。

画像認識だけに頼らず、ショートカットキー、Tabキー、固定位置、検索範囲の限定などを組み合わせると、より安定した自動化になります。

🚨 画像認識の限界

画像認識は便利ですが、画面の見た目に依存します。

次のような変更には弱い性質があります。

アプリケーションのデザイン変更
ボタンの色や形の変更
フォントの変更
OSの表示倍率変更
ブラウザのズーム変更
ダークモードへの切り替え
アニメーション中の表示変化

また、画像が似ているだけでは、そのボタンが本当に目的の機能を持つかまでは判断できません。

画像を見つけたことだけを根拠に、削除・送信・購入・確定などの重大な操作を直ちに実行しないでください。 直前の画面や確認ダイアログも検証する設計が必要です。

📝 まとめ

PyAutoGUIでは、検索画像を使って画面上のボタンやアイコンを探せます。

代表的な機能は次のとおりです。

locateOnScreen()：画像が存在する範囲を取得する
locateCenterOnScreen()：画像の中心座標を取得する
locateAllOnScreen()：一致する画像をすべて取得する
center()：画像範囲の中心座標を取得する
confidence：画像の一致率を指定する
region：検索範囲を限定する
grayscale：白黒画像として検索する
screenshot()：画面を画像として保存する

実際の自動化では、画像を探してすぐクリックするだけでなく、

画像が表示されるまで待つ
タイムアウトを設定する
見つからなかった場合を処理する
検索範囲を限定する
誤認識しない一致率を設定する

といった設計が重要です。

画像認識とマウス操作を組み合わせることで、ウィンドウの位置が変化するアプリケーションでも、目的のボタンを探して操作できるようになります。

FastAPIとGradioの使い分け

FastAPIとGradioの連携サンプル

Gradio Blocks入門：Blocksだからできる複雑UIを体験しよう

Gradio.interface と Gradio.Blocks

Gradio（グラディオ）について

Gradioで作る！英作文の自動添削アプリ

Gradioで単語カウンターアプリを作る

gradioの部品まとめ

Tkとの比較～なぜスタンドアローンでもよいのにhttp使うのか？

matplotlibで山手線上の駅を移動する点をアニメーションで描写する

matplotlibの概要

VOICEVOX Dockerイメージを使用して音声合成APIサーバーを構築して遊ぶ手順書

pytestをVS Codeで快適に運用する方法

pytestのデコレータ実践ガイド（parametrize / fixture / mark / skip / xfail）

🖱️ PyAutoGUI 概要

💿 PyAutoGUI インストール方法

🖱️ PyAutoGUI マウス操作

⌨️ PyAutoGUI キーボード操作

🔍 PyAutoGUI 画像認識

📸 PyAutoGUI スクリーンショット

🪟 PyGetWindowによるウィンドウ操作

🔍 PyAutoGUI 画像認識

📖 はじめに

🧩 画像認識の仕組み

📦 必要なライブラリ

✂️ 検索画像を準備する

📍 画像の位置を探す

🎯 画像の中心座標を取得する

🖱️ 画像を探してクリックする

🎯 中心座標を直接取得する

🎚️ 一致率を指定する

⚠️ 一致率を下げすぎない

❌ 画像が見つからなかった場合

⏳ 画像が表示されるまで待つ

⏱️ タイムアウトを設定する

🧰 待機処理を関数にする

🔲 検索範囲を指定する

⚫ グレースケールで検索する

🔢 同じ画像をすべて探す

📸 検索画像を作るためにスクリーンショットを保存する

🗂️ 画像ファイルを整理する

🧪 画像が見つからない主な原因

🖼️ 検索画像と画面の大きさが違う

🎨 ボタンの表示状態が違う

🪟 対象がほかのウィンドウに隠れている

🖥️ 複数ディスプレイやDPI設定の影響

🛡️ 安全なクリック処理

💡 実践例：ボタンを待ってクリックする

⚠️ 画像認識を安定させるポイント

🚨 画像認識の限界

📝 まとめ