画像検索 ("search") (JA)

4.2.2 画像検索 ("search")

説明

画像検索（コード「search」）は、1 つ以上のテンプレート画像および/またはイメージコレクションによって表されるコンポーネントまたはオブジェクトをデスクトップ画面で検索します。これは通常、デスクトップ画面の内容（「オブジェクトが確実に表示されていることを確認する」）の検証、または後続のマウスまたはキーボード操作のためのコンポーネントの位置特定（ （「見つけてクリックまたはドラッグ」、「見つけて押す/入力する」など）。

この方法は、3つの独立した許容メカニズムを持つプレーンピクセル比較を使用します：

1. ピクセルベースの許容誤差 は、テンプレート画像と一定量のピクセルが異なる出現箇所をアルゴリズムが検索することを可能にします。これは、一致に必要なピクセルの割合を定義する「passrate」パラメータによって実現されます。例えば、テンプレート画像サイズが10x10（100ピクセル）でパスレートを99%に設定した場合、アルゴリズムは最大1ピクセル異なる位置まで全ての一致箇所を検出します。パスレートを低く設定するほど、パフォーマンスは低下し、検索に要する時間は長くなることに注意してください。

2. RGB許容値はv2.2で導入されました。これは0から256までの整数であるtoleranceパラメータによって有効化されます。この値は、デスクトップピクセルの赤、緑、青の各成分が、対応するテンプレートピクセルと同等と見なされるために許容される最大差異を示します。この値により、画像のぼかしや背景との融合などによりピクセルがわずかに変化する画像の処理が可能になります。この挙動は、アプリケーション更新時に装飾テキストや一部の画像が一定の方法でレンダリングされないFlashアプリケーションで報告されています。許容値が高いほど誤検出の可能性が高まる点に注意してください。ほとんどのシナリオでは、ぼかしレベルに応じて値を[0, 100]の範囲に設定すべきです。パラメータが指定されない場合、デフォルトはゼロとなり、アルゴリズムは完全な色一致を用いてピクセルを比較します。

3. 透明度／半透明度に基づく許容値により、テンプレート画像の特定のピクセルを無視できます。画像検索アルゴリズムはデフォルトで、透過度成分アルファが最小アルファパラメータ（minalpha）で指定された閾値未満の、すべての透明または半透明（部分的に透明）ピクセルを「合格」と見なします。たとえば、100ピクセルのテンプレート画像に90個の透明ピクセルが含まれ、最小アルファ値が0xFF（完全に不透明なピクセルのみを検索するよう強制）に設定されている場合、デスクトップ画像との比較対象となるのは残りの10個の非透明ピクセルのみとなります。 
   
   透明度を基にした許容値は、背景色やコンポーネント色の変化に対して頑健な画像比較を構築する強力な手法です。たとえば、リモートデスクトップ上にレンダリングされたアイコンを検索する場合、アイコンテンプレート内の背景色ピクセルを透明にマークすることで、リモートデスクトップの色が変化しても画像比較が確実に通過するようになります。テンプレート画像は、一般的な画像エディタでさらに加工して、重要でないピクセルを削除し、検索対象のオブジェクトの骨格だけを残すこともできます。これは、地理情報システム（GIS）など、オブジェクトのレンダリングが不安定な特定の種類のアプリケーションをテストする唯一の方法であることが多いのです。

-Plan Robot Enterprise バージョン 2.1 以降では、自動背景透明化 が removebg および bgcolor パラメータを通じてサポートされています。これにより、サードパーティ製エディタで画像を編集することなく、テンプレート画像の背景を無視することが可能になります。このアルゴリズムは、入力として不透明なテンプレート画像（透明度のない画像）を受け取り、内部の透明度フィルターを適用して背景と同一または合理的に類似した全てのピクセルを除去します。背景色はデフォルトでテンプレート画像の最初のピクセルが使用されますが、bgcolor パラメータで明示的に指定することも可能です。自動透明化は GUI、特にテンプレート画像エディターおよびCompareウィンドウで説明されている比較 GUI コンポーネントを使用して、簡単に設定できます。

また、サードパーティの画像エディタを使用して、テンプレート画像に透明度を導入することもできます。

例えば、WindowsやLinux/Unixのユーザーは、Gimpなどを利用して、以下のように透明度を設定することができる：

1. テンプレート画像を、例えば Gimpで開きます。

2. レイヤー＞透明度＞カラーをアルファに変換します

3. 透明色を選択してください。通常、Gimpが提供するデフォルト設定（白い背景色）のままにしておいても問題なく動作します。

4. テンプレート画像をファイルに保存してください。

5. テンプレート画像エディタで再テストしてください。 これは、画像に背景色と非常に近い色しか含まれていない場合、Gimp がすべてのピクセルを透明または半透明にしてしまい、デフォルトの minalpha 値での画像検索にテンプレートが使用できなくなる可能性があるため、必要な作業です。テンプレート画像エディタは、このようなケースを検出し、画像検索パラメータの変更を提案することができます。

結果として得られた一致位置の座標は、呼び出し元スクリプトに対して、_SEARCH_で始まる変数のセットとして公開されます：

マッチ位置の幅と高さを取得するには、 _COMPARETO_TEMPLATE_WIDTH および _COMPARETO_TEMPLATE_HEIGHT 変数を使用します。これらは ホスティングコマンドまたはJavaメソッド呼び出しによって設定されます。

注意：一致する位置の数はComparetoコマンドの設定パラメータによって制限され、最大値に達すると検索は停止します。

オプション

このメソッドは、ホスティングコマンドまたは Java メソッド呼び出しによって指定される 1 つ以上の テンプレート画像 および/またはイメージコレクションを必要とします。「passrate」パラメータは、「search」メソッドのコンテキストにおいて、テンプレート画像と画面上のマッチ位置の間で完全に一致しなければならないピクセルの最小比率を指定します。 デフォルト値は 100% (ピクセル差は許容されない) です。「cmparea」パラメータはオプションであり、省略した場合はデフォルトで全画面になります。

サポートされている特定のパラメータ：

トレランス=<0-255>

- The toleranceパラメータは制御しますRGB許容差 わずかな色の変化まで許容します。0から255までの整数で指定し、0は許容値なし（完全一致）を、255は最大許容値を示します。これは、デスクトップピクセルの赤・緑・青成分が、対応するテンプレートピクセルと同等と見なされる最大許容差を示します。許容値が高いほど、誤った一致検出の可能性が高まります。

このパラメータは、ぼかし処理や背景との合成などによりピクセルがわずかに変化する画像の処理を可能にします。この挙動は、装飾テキストや一部の画像が時間経過とともに一定の方法でレンダリングされないFlashアプリケーションで報告されています。ほとんどの場合、ぼかしレベルに応じて値は[0, 100]の範囲に設定すべきです。パラメータが指定されない場合、デフォルト値はゼロとなり、アルゴリズムは正確な色一致を用いてピクセルを比較します。

removebg=<true|false>。

removebg パラメータは、自動背景透過をオン（「true」）またはオフ（「false」）に切り替えます。値「true」は、テンプレート画像の背景色を無視する自動透過を適用します。テンプレート画像（または複数のテンプレート画像）に既に透明または半透明のピクセルが含まれている場合、背景フィルターは適用されず、このパラメータおよびbgcolorパラメータは無視されます。デフォルト値は「false」（背景フィルターはオフ）です。

bgcolor=<HTMLColor>。

bgcolor パラメータはオプションであり、removebg パラメータによって有効化された 自動背景透過 モード用のカスタム背景色を定義できます。HTML 風の表記法による RGB 値を受け付けます。例えば、白は "ffffff"、黒は "000000" などです。値は6文字で構成され、R、G、Bの各成分は2桁の16進数（00～ff）で指定します。bgcolorが指定されていない場合、メソッドはテンプレート画像の最初のピクセル（画像左上隅）から背景色を選択します。

minalpha

minalpha パラメータは半透明の許容範囲を設定します。このパラメータは removebg フィルタでフィルタリングされた画像や、 すでに透明や半透明の画素があるテンプレートに適用できます。デフォルト値の 255 は検索アルゴリズムに指示して完全に不透明な画素だけを比較させ、 透明や半透明 (半透明) の画素はすべて無視させます。255より小さい値は、アルファ成分が指定された限界と等しいかそれ以上の半透明のピクセルも比較するアルゴリズムになります。

最小アルファパラメータは、背景カラーフィルタがあまりにも多くのピクセル、あるいはすべてのピクセルを透明または半透明にする状況を解決するためのものです。この場合、検索アルゴリズムは少数の不透明な画素とだけ比較することになり、通常予期せぬ一致結果を招きます。アルファリミットを下げると、比較可能なピクセルの数が増えるので、画像検索アルゴリズムの精度を上げるために使うことができます。しかし、半透明のピクセルの比較は色の類似性に基づいているため、古典的な画像検索よりもパフォーマンスが著しく低下し、最小アルファ値が極端に低いと予期しない一致結果が生じる可能性があることに注意してください。

戻り値

このメソッドは、入力テンプレート画像の少なくとも1つに対して、少なくとも1つのマッチする場所が見つかった場合、呼び出しコマンド（メソッド呼び出し）に0（成功）を返させます。そうでない場合は、値1を返します。

トラブルシューティング

失敗した「検索」比較に対処するために：

• スクリプトが検索失敗後に終了するよう設計されている場合、ロスレス形式（PNGまたはBMP）でスクリーンショットを作成することが推奨されます。そのコードの例を以下に示します。これにより、比較後に失敗した比較を再現しデバッグすることが可能になります。スクリーンショットは、 ログインダイアログ内の「静的画像クライアント」経由で読み込むか、比較コマンド／メソッド呼び出しプロパティウィンドウ内の は「RD画像を読み込む」ボタンを使用して読み込むことができます。

• 合格率を下げるか、RGB許容値パラメータ（「tolerance」）を上げて、一致するまで「比較」ボタンでテストしてください。パラメータで検索の不具合が修正できない場合は、代替テンプレート画像を作成し、テンプレートリストまたはイメージコレクションに追加してください。

• 比較に失敗する最も一般的な要因については(ja) 画像比較のススメ章を参照されたい。

• 明らかな理由なく検索が失敗した場合は、スクリーンショットと画像テンプレートをT-Plaまでメールでお送りください。サポート.

使用例

Compareto buttonOk.png  method="search" tolerance="50"

if ({_EXIT_CODE} > 0) {
  Screenshot failure.png desc="Failed to find the OK button."
  Exit 1 desc="Failed to find the OK button."
} else {
  Mouse click to=x:{_SEARCH_X},y:{_SEARCH_Y}
}

- OKボタンを探してクリックしてください。ボタンが見つからない場合は終了スクリーンショットを撮影し、終了コード1でスクリプトを終了させてください。

詳細なコンポーネント検索例については、「search2」メソッド仕様を参照してください。 または以下の抜粋を参照してください：

 例

Compareto buttonOk.png  method="search2" passrate="90" sort="bottom"
if ({_EXIT_CODE} > 0) {
  Screenshot failure.png desc="Failed to find the OK button."
  Exit 1 desc="Failed to find the OK button."
} else {
  Mouse click to=x:{_SEARCH_X},y:{_SEARCH_Y}
}

• 最下部のOKボタンを探してクリックしてください。ボタンが見つからない場合は終了画面のスクリーンショットを撮影し、終了コード1でスクリプトを終了させてください。

// すべてのボタンを探してクリックする
Compareto "button.png" passrate="100" method="search2" 
if ({_EXIT_CODE} == 0) { 
    for (i=1; {i}<{_SEARCH_MATCH_COUNT}+1; i={i}+1) { 
        Mouse click to=x:{_SEARCH_X_{i}},y:{_SEARCH_Y_{i}} wait=1s 
    } 
} 

// ボタンが消えるか状態が変わるまで15秒待ちます
Waitfor "mismatch" method="search2" passrate="100" template="button.png" timeout="15s" 
if ({_EXIT_CODE} > 0) { 
    Exit 1 desc="Some buildings failed to turn the state!" 
}

• 画面上で複数のボタンを探し、一つ一つクリックする。その後、すべてのボタンが消えるか状態が変わるか画面を確認する。

// スクロールボタンを見つける
Compareto "scrollbutton.png" method="search2" 
if ({_EXIT_CODE} > 0) { 
    Exit 1 desc="Failed to locate the scroll button!" 
}

// その座標をX、Y変数に保存する
Var X={_COMPARETO_CLICK_X} Y={_COMPARETO_CLICK_Y}

// 100回ループを反復処理する
for (i=0; {i}<100; i={i}+1) { 
    // スクロールボタンをクリック
    Mouse "click" to="x:{_COMPARETO_CLICK_X},y:{_COMPARETO_CLICK_Y}" 

    // コンポーネントが画面上に表示されているか確認します。ページがスクロールして画面に
    // 更新されるまでに時間がかかる可能性があるため、Waitforを使用します 
    Waitfor match template="component.png" method="search2" timeout=3s 
    if ({_EXIT_CODE} == 0) { 
        // Found -> break the for loop 
        break 
    } 

    // 最後のループ #99 -> コンポーネントが見つかりません、スクリプトを終了します
    if ({i} == 99) { 
        Exit 2 desc="Failed to scroll to the component!" 
    } 
} 

• スクロールされたページ（ウィンドウ）内に表示されているコンポーネントを検索する方法の例。この例では、スクロールダウンボタンを繰り返しクリックし、ループ内でコンポーネントの存在を確認します。スクロールボタンをクリックする操作は、最終的にはPgDownキーの押下で置き換えられる可能性があります。