Image Search V2 ("search2") (JA)

4.2.1 Image Search V2V2 ("search2")

説明

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

search2 "アルゴリズムは、従来の画像検索メソッド（"search"）を改良した新世代の手法であり、以下の改善点があります：：

1. 使いやすい - デスクトップ画像の微小な変化に対する許容度を制御する唯一のパラメータは、標準の「passrate」です。そのデフォルト値は50%に設定されており、Flashアプリケーションなどデスクトップ画像レベルでの自動化が困難とされる環境を含む、ほとんどの環境において、箱から出してすぐに信頼性の高い検索を実行します。

2. 高速パフォーマンス - パスレートパラメータが低い値であっても、検索は大幅に高速化されます。また、このアルゴリズムは画像ピクセルのコピーを回避し、デスクトップバッファで直接動作するため、他の類似の方法よりもメモリ消費量が最大90%少なくなります。

3. 結果ソート - ベストマッチによる結果（マッチする場所）のデフォルトソートは、パスレート値が低すぎてメソッドが複数のファジーマッチを生成しても、ベストマッチの場所が常に最初に報告されることを保証します。これにより、最初のマッチ（最も正しい可能性が高いマッチ）を使って作業し、他の遠隔的に類似したマッチを無視することができます。

4. 拡大縮小画像の検索 - リリース4.0で導入されたscaleパラメータは、入力コンポーネント画像のスケーリングされたインスタンスを検索します。これにより、さまざまな解像度のデバイス（Android、iOS ...）で単一の検索を再利用できるようになりました。

5. 長方形以外のテンプレート画像はリリース8.1からサポートされています。テンプレート画像には透明または半透明のピクセルを指定すると、画像検索時に自動的に無視されます（一致とみなされます）。これにより、背景のない、あるいはオブジェクトの特徴が削除された、あらゆる形状のテンプレート画像を作成することができます。新しいテンプレート・イメージ・エディター v2または他のサードパーティの画像エディタを使用してください。円形のChromeアイコンのテンプレート画像の例です：

一致した位置の座標は、SEARCHで始まる変数のセットとして呼び出し元スクリプトに公開されます。このシステムは従来の「search」メソッドと互換性があります：

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

バージョン4.4以降、このメソッドでは一致する位置の数を制限できるようになりました。これは、完全なデスクトップ検索では一致する項目が多すぎたり時間がかかりすぎる場合に、「最初のN件を見つけて停止する」といったシナリオをサポートすることを目的としています。スクリプトから制限を設定するには、Varコマンドを使用して_SEARCH2_MATCH_LIMIT変数を設定します。リセットするには変数を空の値に設定します。例えば値を1に設定すると、最初の一致位置で検索が停止します：：

//Setthematchlimitto1
Var_search2_match_limit=1
Comparetocomp.pngmethod=search2

// マッチ制限をリセットする
Var_search2_match_limit=1

v6.1より、パフォーマンスの問題を防ぐため、マッチするロケーションの最大数が内部的に1,000に制限されました。この制限は、メソッドの環境設定で変更することができます。

互換性に関する注記: リリース8.2以降、「search2」アルゴリズムは「拡張」アルゴリズムにフォールバックします

オプション

このメソッドは、ホスティングコマンドまたはJavaメソッド呼び出しを通じて指定された1つ以上の テンプレート画像 および/またはイメージコレクションを必要とします。 

「search2」メソッドにおいて、「passrate」パラメータは、テンプレート画像と画面上の対応位置との間に必要な最小類似度を指定します。デフォルト値は50%であり、これはほとんどのケースで良好な性能と精度のバランスを保証します。低コントラスト環境などで一致が過剰に発生する場合は、合格率を高く設定してください。最高の性能を得るには合格率を100%に設定します。。

「cmparea」パラメータはオプションであり、省略された場合はデフォルトで全画面表示となります。

このメソッドは、以下の2つの特定のパラメータをサポートします：

sort=<best|none|top|bottom|left|right>。

-結果のソートモード（オプション）：

• "best" - 最適な一致順（差分が最小の最適な位置を最初に）でソートします。差分値が同じ位置は、自然な読み順（左から右、上から下）で並べ替えられます。このモードは、パラメータが指定されていない場合のデフォルトです。

• "none" - 並べ替えを行わず、結果を自然な「読み取り」順序（左から右、上から下）のまま表示します。このモードでは、従来の「検索」メソッドと同じ順序で結果が表示されます。

• "top" - 上から下へ（最上位から順に）並べ替え。

• "bottom" - 位置を底から上へ（一番下から順に）並べ替える。

• "left" - 位置を左から右へ並べ替え（左端が最初）。

• "right" - 位置を右から左へ並べ替え（右端が最初）。。

scale=<float_number(s)>とする。

-scaleは4.0からサポートされたオプションのパラメータです。入力画像のスケールされたインスタンスを検索することができます。この値には、1 つの浮動小数点数 (スケールファクタ) を指定することもできますし、 セミコロン ';' で区切られた数値のリストを指定することもできます。それ以上の数値がある場合は、マッチするかリストがなくなるまで、指定した順番で処理されます。

この値が0より大きい場合、拡大率として扱われます。例えば、2.0という値は、幅と高さが2倍に拡大されたコンポーネントを検索します。

ダイナミック・スケーリングを採用するために指定できる2つの負の定数があります。これらの定数は、現在のデスクトップの解像度と、テンプレート(コンポーネント)画像が作成されたデスクトップのサイズとの差に応じて、入力画像を拡大縮小します。Robot3.x以前のバージョンでは、デスクトップの解像度がテンプレートのメタデータに保存されていないため、この操作を有効にするには、Robot4.0で画像を作成または更新する必要があります。古いイメージを更新するには、元のデスクトップに接続し、プロジェクトビュー内のテンプレートを右クリックし、 画像プロパティの更新項目を選択します。

対応する音階モードは以下の通

• -1("ストレッチモード") は、デスクトップの幅と高さの変更に従って入力画像を拡大縮小します。結果として得られる画像は、同じ幅と高さの比率（幅と高さの比率）を持つこともあれば、持たないこともあります。

• -2("プロポーショナル・スケール・モード") は、デスクトップの幅と高さの相対的な変化を小さくして、幅と高さの両方のスケーリングに使用します。結果として得られる画像は、同じ比率（幅と高さの比率）になります。

戻り値

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

トラブルシューティング

失敗した「search2」比較に対処するには：

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

• 画像変化に対する許容度を高めるには、単純に通過率を下げてください。ファジーレベルを非常に低く設定することを恐れないでください。ただし、GUI の「比較」ボタンを使用して、正しいコンポーネントの位置が最初に報告されることを必ずテストしてください。パス率によって検索の不具合を修正できない場合は、代替のテンプレート画像を作成し、テンプレートリストまたはイメージコレクションに追加してください。

• 比較の失敗を引き起こす最も一般的な要因については(ja) 画像比較のススメ章を参照してください。。

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

使用例

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) { 
        // 見つかった場合 -> forループを終了する
        break 
    } 

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

- スクロールされたページ（ウィンドウ）に表示されているコンポーネントを検索する方法の例です。この例では、スクロールダウンボタンをクリックし続け、ループの中でコンポーネントの存在をチェックします。スクロールボタンをクリックする作業は、最終的にはPgDownキーを押すことで置き換えることができます。