> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/workflows/ja/burokku/blocks/classical-computer-vision/template-matching.md).
# テンプレートマッチング
正規化相互相関を用いたテンプレートマッチングにより、より大きな画像内でテンプレート画像のインスタンスを特定します。画像内の任意の位置でテンプレートパターンの完全一致またはほぼ完全一致を見つけ、オブジェクト検出、ロゴ検出、パターン認識、テンプレートベースのオブジェクト位置特定のワークフロー向けに、必要に応じてNMSフィルタリング付きのバウンディングボックス検出を出力します。
## このブロックの仕組み
このブロックは、正規化相互相関テンプレートマッチングを使用して、より大きな入力画像内でテンプレート画像が出現する箇所を検索します。このブロックは次の処理を行います:
1. 入力画像とテンプレート画像（検索対象の小さなパターン）を受け取ります
2. テンプレートマッチングのために両方の画像をグレースケールに変換します（テンプレートマッチングは通常、効率性と堅牢性のためにグレースケール画像で動作します）
3. OpenCV の matchTemplate を TM\_CCOEFF\_NORMED 手法で用いてテンプレートマッチングを実行します:
* テンプレートを入力画像全体の取り得るすべての位置にわたってスライドさせます
* 各位置で正規化相互相関係数を計算します（テンプレートと画像領域の類似度を測定します）
* 各位置でテンプレートがどの程度一致しているかを示す類似度マップを生成します
4. 類似度が matching\_threshold を超える一致位置を特定します:
* 相関係数がしきい値以上であるすべての位置を見つけます
* しきい値の範囲は 0.0 から 1.0 で、値が高いほどより近い一致が必要になります
* しきい値を低くするとより多くの候補一致（部分一致を含む）を見つけ、高くすると非常に類似した一致のみを見つけます
5. 各一致に対してバウンディングボックスを作成します:
* 各一致位置は、テンプレートの寸法に一致するバウンディングボックスを持つ検出として扱われます
* すべての検出の信頼度は 1.0 です（しきい値要件を満たしているため）
* すべての検出にはクラス「template\_match」と class\_id 0 が割り当てられます
* 追跡用に各検出に一意の detection ID を付与します
6. 必要に応じて非最大抑制（NMS）を適用し、重複する検出をフィルタリングします:
* テンプレートマッチングでは、同じ位置に対して重複する検出が多数生成されることがよくあります（重複一致）
* NMS は重複する検出を除去し、各領域で最良の一致のみを保持します
* NMS のしきい値は、検出を削除する前にどの程度の重なりを許容するかを制御します
* 一致数が非常に多い場合に NMS が計算量的に扱いきれなくなるときは、無効化できます（apply\_nms=False）
7. 検出にメタデータを付与します:
* parent\_id を入力画像への参照として設定します
* prediction\_type を「object-detection」に設定します
* 座標参照用に画像の寸法を保存します
* ワークフロー追跡のために親の座標情報を付与します
8. 検出予測を sv.Detections 形式で返し、見つかった一致の総数も返します
このブロックは、完全一致またはほぼ完全一致のテンプレートを見つけるのに有効な正規化相互相関を使用します。テンプレートが画像内に同じスケール、回転、照明条件で現れる場合に最も効果的です。この手法は同じ一致位置に対して重複する検出を多数生成しやすいため、NMS フィルタリングが重要です。ただし、非常に多くの一致がある場合（たとえば繰り返しパターン）には、NMS は計算コストが高くなる可能性があり、必要に応じて無効化できます。
## 一般的な使用例
* **ロゴおよびブランド検出**: 画像内で特定のロゴやブランド要素を見つけます（例: 写真内の企業ロゴを検出する、画像内のブランドマーカーを見つける、シーン内の特定のロゴパターンを特定する）。ロゴ検出ワークフローを可能にします
* **厳密なパターンマッチング**: 画像内で同一に現れる特定のパターンやオブジェクトを特定します（例: スクリーンショット内の特定の UI 要素を見つける、画像内の厳密なパターンを検出する、特定の視覚要素を特定する）。厳密なパターン検出ワークフローを可能にします
* **品質管理と検査**: 品質検査のための参照パターンや特徴を見つけます（例: 製造画像内の特定の特徴を検出する、整列用の参照マーカーを見つける、検査対象を特定する）。品質管理ワークフローを可能にします
* **オブジェクト位置特定**: 正確な外観が分かっている場合に、特定のオブジェクトや領域を特定します（例: 外観が既知の特定オブジェクトを見つける、画像内の参照オブジェクトを特定する、特定の視覚要素を検出する）。テンプレートベースのオブジェクト位置特定を可能にします
* **文書処理**: 文書内の特定の要素や領域を見つけます（例: 文書内のフォームフィールドを特定する、特定の文書要素を検出する、スキャンされた文書内の参照マーカーを見つける）。文書処理ワークフローを可能にします
* **UI 要素検出**: インターフェース画像内の特定の UI コンポーネントや要素を検出します（例: UI スクリーンショット内のボタンを見つける、特定の UI 要素を特定する、インターフェースコンポーネントを検出する）。UI 分析ワークフローを可能にします
## 他のブロックへの接続
このブロックは画像とテンプレートを受け取り、検出予測を生成します:
* **画像入力ブロックの後に** 入力画像内のテンプレートパターンを見つけるために（例: 入力画像内でテンプレートを検索する、カメラフィード内でパターンを特定する、画像ストリーム内でテンプレートを見つける）、テンプレートマッチングワークフローを可能にします
* **前処理ブロックの後に** 前処理済み画像内でテンプレートを見つけるために（例: 画像強調後にテンプレートを照合する、フィルタリングされた画像内のパターンを見つける、正規化された画像内でテンプレートを特定する）、前処理済みテンプレートマッチングを可能にします
* **可視化ブロックの前** テンプレートの一致位置を可視化するために（例: 検出されたテンプレート一致を可視化する、一致のバウンディングボックスを表示する、テンプレート一致結果を示す）、テンプレート一致の可視化ワークフローを可能にします
* **フィルタリングブロックの前** 条件に基づいてテンプレート一致をフィルタリングするために（例: 位置で一致をフィルタリングする、特定の一致領域を選択する、テンプレート一致結果を絞り込む）、フィルタリングされたテンプレートマッチングワークフローを可能にします
* **クロップブロックの前** テンプレート一致の周囲の領域を抽出するために（例: 一致周辺を切り出す、分析用に一致領域を抽出する、テンプレート一致位置を切り出す）、テンプレートベースの領域抽出を可能にします
* **品質管理ワークフローにおいて** テンプレートマッチングが検査や整列に使われる場合（例: 整列用の参照マーカーを見つける、検査対象を検出する、品質管理の特徴を特定する）、品質管理向けテンプレートマッチングワークフローを可能にします
### 型識別子
ステップで次の識別子を使用してください `"type"` フィールド： `roboflow_core/template_matching@v1` ワークフローにこのブロックをステップとして追加するには。
### プロパティ
| **名前** | **型** | **説明** | 参照 |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name` | `str` | このステップの一意の識別子を入力してください。 | ❌ |
| `matching_threshold` | `float` | テンプレート一致に必要な最小類似度しきい値（0.0～1.0）。値が高いほど（1.0 に近いほど）非常に近い一致が必要になり、見つかる一致は少なくなりますがより正確になります。値が低いほど（0.0 に近いほど）より緩やかな一致が許容され、部分一致を含むより多くの候補一致を見つけます。デフォルトは 0.8 で、かなり近い一致を要求します。より多くの一致を見つけたい場合やわずかな変化を扱う場合は、より低いしきい値（0.6～0.7）を使用してください。完全一致のみにしたい場合は、より高いしきい値（0.85～0.95）を使用してください。しきい値はテンプレートマッチングで得られる正規化相互相関係数を比較します.. | ✅ |
| `apply_nms` | `bool` | 重複する検出をフィルタリングするために非最大抑制（NMS）を適用するかどうか。テンプレートマッチングでは、同じ位置に重複する検出が多数生成されることがよくあります。NMS は重複する検出を除去し、各領域で最良の一致のみを保持します。デフォルトは True です（ほとんどの場合に推奨）。次の場合は False に設定してください: (1) 一致数が非常に多い（NMS が計算コスト高になる可能性がある）、(2) フィルタリングなしですべての生の一致を見たい、(3) 一致同士が意図的に近接しており、すべて保持したい。無効化すると、同じ一致位置に対して多くの重複検出が表示されることがあります.. | ✅ |
| `nms_threshold` | `float` | 非最大抑制のための Intersection over Union（IoU）しきい値。apply\_nms が True の場合にのみ関連します。IoU の重なりがこのしきい値を超える検出は重複とみなされ、信頼度が最も高い検出のみが保持されます。値が低いほど（0.3～0.4）重なりの除去が強くなり、わずかに重なっている検出も削除します。値が高いほど（0.6～0.7）寛容になり、強く重なっている検出のみを削除します。デフォルトは 0.5 で、バランスの取れた重なりフィルタリングを提供します。テンプレート一致同士の重なり具合と、有効な一致がどれだけ近接し得るかに応じて調整してください.. | ✅ |
この **参照** 列は、で利用可能な動的値を使ってプロパティをパラメータ化できる可能性を示します `ワークフロー` 実行時。参照 *バインディング* 詳細は。
### 入力と出力のバインディング
利用可能な接続は、そのバインディング種別によって異なります。どのバインディング種別が `テンプレートマッチング` のバージョン `v1` あるか確認してください。
入力と出力のバインディング
* 入力
* `image` ([*`image`*](/workflows/ja/gaido/developer-guide/kinds/image.md)): テンプレートパターンを検索する大きな画像。テンプレートはこの画像全体のすべての可能な位置で検索されます。画像はテンプレートマッチングのために内部でグレースケールに変換されます。テンプレートマッチングは、画像とテンプレートの照明条件が類似しており、テンプレートが画像内で同じスケールと向きで現れる場合に最も効果的です..
* `template` ([*`image`*](/workflows/ja/gaido/developer-guide/kinds/image.md)): 入力画像内で検索する小さなテンプレート画像パターン。テンプレートは入力画像より小さい必要があります。テンプレートは照合のために内部でグレースケールに変換されます。テンプレートマッチングは、このテンプレートの完全一致またはほぼ完全一致を入力画像内の任意の位置で見つけます。テンプレートが画像内で同じスケール、回転、照明条件で現れる場合に最も効果的です。テンプレートの寸法が検出バウンディングボックスのサイズを決定します..
* `matching_threshold` ([*`float`*](/workflows/ja/gaido/developer-guide/kinds/float.md)): テンプレート一致に必要な最小類似度しきい値（0.0～1.0）。値が高いほど（1.0 に近いほど）非常に近い一致が必要になり、見つかる一致は少なくなりますがより正確になります。値が低いほど（0.0 に近いほど）より緩やかな一致が許容され、部分一致を含むより多くの候補一致を見つけます。デフォルトは 0.8 で、かなり近い一致を要求します。より多くの一致を見つけたい場合やわずかな変化を扱う場合は、より低いしきい値（0.6～0.7）を使用してください。完全一致のみにしたい場合は、より高いしきい値（0.85～0.95）を使用してください。しきい値はテンプレートマッチングで得られる正規化相互相関係数を比較します..
* `apply_nms` ([*`boolean`*](/workflows/ja/gaido/developer-guide/kinds/boolean.md)): 重複する検出をフィルタリングするために非最大抑制（NMS）を適用するかどうか。テンプレートマッチングでは、同じ位置に重複する検出が多数生成されることがよくあります。NMS は重複する検出を除去し、各領域で最良の一致のみを保持します。デフォルトは True です（ほとんどの場合に推奨）。次の場合は False に設定してください: (1) 一致数が非常に多い（NMS が計算コスト高になる可能性がある）、(2) フィルタリングなしですべての生の一致を見たい、(3) 一致同士が意図的に近接しており、すべて保持したい。無効化すると、同じ一致位置に対して多くの重複検出が表示されることがあります..
* `nms_threshold` ([*`float_zero_to_one`*](/workflows/ja/gaido/developer-guide/kinds/float-zero-to-one.md)): 非最大抑制のための Intersection over Union（IoU）しきい値。apply\_nms が True の場合にのみ関連します。IoU の重なりがこのしきい値を超える検出は重複とみなされ、信頼度が最も高い検出のみが保持されます。値が低いほど（0.3～0.4）重なりの除去が強くなり、わずかに重なっている検出も削除します。値が高いほど（0.6～0.7）寛容になり、強く重なっている検出のみを削除します。デフォルトは 0.5 で、バランスの取れた重なりフィルタリングを提供します。テンプレート一致同士の重なり具合と、有効な一致がどれだけ近接し得るかに応じて調整してください..
* 出力
* `predictions` ([`object_detection_prediction`](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)): 検出されたバウンディングボックスを sv.Detections(...) オブジェクト形式で含む予測。
* `一致数` ([`整数`](/workflows/ja/gaido/developer-guide/kinds/integer.md)）：整数値。
JSON 定義の例
```json
{
"name": "",
"type": "roboflow_core/template_matching@v1",
"image": "$inputs.image",
"template": "$inputs.template",
"matching_threshold": 0.8,
"apply_nms": "$inputs.apply_nms",
"nms_threshold": "$inputs.nms_threshold"
}
```