> 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/nearest-neighbor-detection-match.md).

# 最近傍検出マッチ

設定可能なアンカーポイント間の単純な 2D ユークリッド画素距離を使い、クエリセット内の各検出についてターゲットセット内で最も近い検出（同距離なら複数）を見つけて、2つの検出セットの最近傍空間結合を実行します。

## このブロックの仕組み

このブロックは、クエリセット内の各検出をターゲットセット内の最近傍に対応付けます。このブロックは:

1. クエリ予測とターゲット予測（物体検出、インスタンスセグメンテーション、またはキーポイント検出）を受け取ります。- 同じセットをクエリとターゲットの両方に渡すことができます
2. 選択された `query_point` と `target_point` オプション: 中心、バウンディングボックスの4つの角のいずれか、4つの辺の中点のいずれか、または名前付きキーポイント（キーポイント検出予測と `query_keypoint_name`/`target_keypoint_name`)
3. 各クエリアンカーポイントと各ターゲットアンカーポイントの全組み合わせの画素距離行列を計算します（総当たりで、空間木ではありません。このブロックが想定する、1フレームあたり数十検出規模に適しています）
4. 各クエリ検出について、その検出と同じ `detection_id` （自己一致の除外）。そのため、同じ検出セットをクエリとターゲットの両方として渡しても、検出が自分自身に一致することはありません
5. If `max_distance` が設定されている場合、残っている候補ターゲットのうち、それより遠いものを破棄します `max_distance` ランキング前にクエリアンカーポイントからの距離がその画素数を超えるものを除外します。上限を超えるターゲットは、除外された自己一致と同じように扱われます
6. 各クエリ検出について最小距離を見つけ、その最小値から固定 1 ピクセルの epsilon 以内にある残りのターゲット検出をすべて含めます。そのため、完全一致またはほぼ完全一致の同距離は、任意の単一の勝者ではなく複数の一致として扱われます
7. 最も近い距離（ピクセル単位）を各クエリ検出のメタデータに付与します。対象となるターゲットがない検出（ターゲットセットが空、すべてのターゲットが自己一致として除外された、または残りのターゲットがすべて `max_distance`）を取得します `None`
8. 3つのフラットで整列された出力を返します。つまり、拡張されたクエリ予測と、すべてのクエリ-ターゲット対応を表す同じ長さ・同じ順序の2つの検出セットです。 `matched_query_detections` と `matched_target_detections` - 1行につき1つのクエリ-ターゲットの組み合わせです。同点のクエリ検出は、同点の各一致ごとに1回ずつ現れます（行が複製されます）。有効な一致がないクエリ検出は両方から省かれ、次にのみ表示されます `query_predictions` （ `nearest_target_distance` に設定されます `None`)

距離は常に、単純で未較正の 2D ユークリッド画素距離です。Distance Measurement ブロックとは異なり、実世界単位への変換はありません。これにより、このブロックは相対的な／ピクセル空間での近さだけが必要なユースケースに対してシンプルに保たれます。

## 一般的な使用例

* **ゾーン／アンカー割り当て**: 各検出オブジェクトを最も近い参照点またはアンカー検出に割り当てます（例: 人を最寄りの出口標識に対応付ける、車両を最寄りの駐車マーカに対応付ける）。これにより、近接ベースの割り当てワークフローが可能になります
* **クラス間関連付け**: あるクラスの検出を別のクラスの最も近い検出に関連付けます（例: 検出された手を最寄りの検出された道具に対応付ける、プレイヤーを最寄りのボール検出に対応付ける）。これにより、異なる物体タイプ間の関係分析が可能になります
* **重複／オーバーラップ分析**: 検出セットをそれ自体と比較して、各検出の最も近い隣接検出を見つけます（例: 群衆内で最も近い別の人を見つける、密集した検出を特定する）。これにより、密度分析とクラスタリング分析が可能になります
* **トラッキング引き継ぎ**: 同一フレーム上の2つのモデル出力間で検出を対応付けます（例: 高速な汎用検出器の出力を、遅い専門モデルの出力に対応付ける）ことで結果を統合します。これにより、複数モデル融合ワークフローが可能になります

## 他のブロックへの接続

このブロックは2つの検出セットを受け取り、拡張されたクエリ予測と、すべてのクエリ-ターゲット対応を表す2つのフラットで整列した検出セットを生成します。中間のマージ手順や次元操作は不要です。なぜなら `matched_query_detections` と `matched_target_detections` は、各検出生成ブロックが返すのと同じ形を持つ通常の検出セットです:

* **物体検出、インスタンスセグメンテーション、またはキーポイント検出のモデルブロックの後に** 一致させるためのクエリセットとターゲットセットを構築し、検出からマッチングへのワークフローを可能にします
* **ロジックブロックの前** Continue If や Detections Filter のようなブロックで、 `nearest_target_distance` （例: 最も近い一致がしきい値距離以内なら継続する）またはフィルタする `matched_query_detections`/`matched_target_detections` 直接、近接ベースの判定ワークフローを可能にします
* **可視化ブロックの前** Label Visualization や Bounding Box Visualization のようなブロックで、拡張された `query_predictions`、または `matched_query_detections`/`matched_target_detections` ものを並べて表示し、対応付けられたペアを描画します。これにより、距離注釈付きの可視化が可能になります
* **データ保存ブロックの前** CSV Formatter のようなブロックで、すべてのクエリ-ターゲットの組み合わせを1行としてエクスポートし、対応ペアのログ記録ワークフローを可能にします

## 要件

このブロックには2つの検出予測セット（物体検出、インスタンスセグメンテーション、またはキーポイント検出）が必要です。同じセットを両方に使用できます `query_predictions` と `target_predictions`. を使用するには `KEYPOINT` アンカーオプションをいずれかのセットで使用する場合、そのセットはキーポイント検出予測である必要があり、対応する `query_keypoint_name`/`target_keypoint_name` を指定する必要があります。自己一致の除外は `detection_id` が両方のセットに存在することに依存します。これは、Roboflow のすべての物体検出、インスタンスセグメンテーション、キーポイント検出モデルブロックで自動的に設定されます。 `max_distance` は任意です。未設定のままにすると、距離に関係なく各クエリ検出を最も近いターゲットに対応付けます。

なお、 `query_predictions` はその場で拡張されます。つまり、同じ `sv.Detections` 渡されたオブジェクトは変更されます（新しい `nearest_target_distance` フィールドがその `.data`に追加されて返されます。これは Velocity や Time in Zone などのブロックで使われるのと同じ慣例です。各分岐でそれぞれ独自の、未変更の `nearest_target_distance`.

### 型識別子

ステップで次の識別子を使用してください `"type"` フィールド： `roboflow_core/detections_nearest_neighbor@v1` ワークフローにこのブロックをステップとして追加するには。

### プロパティ

| **名前**                 | **型** | **説明**                                                                                                                                                                                                                                                | 参照 |
| ---------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`                 | `str` | このステップの一意の識別子を入力してください。                                                                                                                                                                                                                               | ❌  |
| `query_point`          | `str` | 各クエリ検出の位置を表すために使うアンカーポイント: CENTER、角（TOP\_LEFT、TOP\_RIGHT、BOTTOM\_LEFT、BOTTOM\_RIGHT）、辺の中点（TOP\_CENTER、BOTTOM\_CENTER、CENTER\_LEFT、CENTER\_RIGHT）、または KEYPOINT（ `query_predictions` がキーポイント検出予測であること、および `query_keypoint_name` が設定されていること）             | ✅  |
| `target_point`         | `str` | 各ターゲット検出の位置を表すために使うアンカーポイント。次と同じオプション: `query_point`、を個別に設定します。KEYPOINT を使うと、 `target_predictions` 上の名前付きキーポイントに対して一致させられます（ `target_predictions` がキーポイント検出予測であること、および `target_keypoint_name` が設定されていること）                                             | ✅  |
| `query_keypoint_name`  | `str` | クエリアンカーポイントとして使うキーポイントクラス名。必要なのは次の場合のみ `query_point` が KEYPOINT に設定されているときのみ; `query_predictions` その場合、キーポイント検出予測でなければなりません。                                                                                                                          | ✅  |
| `target_keypoint_name` | `str` | ターゲットアンカーポイントとして使うキーポイントクラス名。必要なのは次の場合のみ `target_point` が KEYPOINT に設定されているときのみ; `target_predictions` その場合、キーポイント検出予測でなければなりません。                                                                                                                      | ✅  |
| `max_distance`         | `整数`  | クエリ検出と候補ターゲットの間に許容される最大画素距離。これより遠いターゲットは、自己一致が除外されるのと同じように、ランキング前に除外されます。残った最も近いターゲットがまだこれより遠い（または残りのターゲットがまったくない）クエリ検出には `nearest_target_distance = None` となり、 `matched_query_detections`/`matched_target_detections`から省かれます。制限なしにするには未設定のままにしてください。 | ✅  |

この **参照** 列は、で利用可能な動的値を使ってプロパティをパラメータ化できる可能性を示します `ワークフロー` 実行時。参照 *バインディング* 詳細は。

### 入力と出力のバインディング

利用可能な接続は、そのバインディング種別によって異なります。どのバインディング種別が `最近傍検出一致` のバージョン `v1` あるか確認してください。

<details>

<summary>入力と出力のバインディング</summary>

* 入力
  * `query_predictions` (*Union\[*[*`object_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`keypoint_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/keypoint-detection-prediction.md)*]*) : 最近傍一致を見つける対象の検出です。このセット内の各検出は `target_predictions`。同じセレクタを両方に使用できます `query_predictions` と `target_predictions` （例: 1つのセット内で各検出の最も近い隣接検出を見つける）- 検出が自分自身に一致することはありません。
  * `target_predictions` (*Union\[*[*`object_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`keypoint_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/keypoint-detection-prediction.md)*]*) : ...内で最も近い一致を検索する対象の検出です。...内の各検出ごとに `query_predictions`。...と同じセレクタにできます `query_predictions`..
  * `query_point` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)) : 各クエリ検出の位置を表すために使うアンカーポイント: CENTER、角（TOP\_LEFT、TOP\_RIGHT、BOTTOM\_LEFT、BOTTOM\_RIGHT）、辺の中点（TOP\_CENTER、BOTTOM\_CENTER、CENTER\_LEFT、CENTER\_RIGHT）、または KEYPOINT（ `query_predictions` がキーポイント検出予測であること、および `query_keypoint_name` が設定されていること）
  * `target_point` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)) : 各ターゲット検出の位置を表すために使うアンカーポイント。次と同じオプション: `query_point`、を個別に設定します。KEYPOINT を使うと、 `target_predictions` 上の名前付きキーポイントに対して一致させられます（ `target_predictions` がキーポイント検出予測であること、および `target_keypoint_name` が設定されていること）
  * `query_keypoint_name` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)) : クエリアンカーポイントとして使うキーポイントクラス名。必要なのは次の場合のみ `query_point` が KEYPOINT に設定されているときのみ; `query_predictions` その場合、キーポイント検出予測でなければなりません。
  * `target_keypoint_name` ([*`string`*](/workflows/ja/gaido/developer-guide/kinds/string.md)) : ターゲットアンカーポイントとして使うキーポイントクラス名。必要なのは次の場合のみ `target_point` が KEYPOINT に設定されているときのみ; `target_predictions` その場合、キーポイント検出予測でなければなりません。
  * `max_distance` ([*`整数`*](/workflows/ja/gaido/developer-guide/kinds/integer.md)) : クエリ検出と候補ターゲットの間に許容される最大画素距離。これより遠いターゲットは、自己一致が除外されるのと同じように、ランキング前に除外されます。残った最も近いターゲットがまだこれより遠い（または残りのターゲットがまったくない）クエリ検出には `nearest_target_distance = None` となり、 `matched_query_detections`/`matched_target_detections`から省かれます。制限なしにするには未設定のままにしてください。
* 出力
  * `query_predictions` (*Union\[*[*`object_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`keypoint_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/keypoint-detection-prediction.md)*]*）：sv.Detections(...) 形式の検出バウンディングボックスを含む予測。 `object_detection_prediction` または、sv.Detections(...) 形式の検出バウンディングボックスとセグメンテーションマスクを含む予測。 `instance_segmentation_prediction` または、検出されたバウンディングボックスと検出されたキーポイントを sv.Detections(...) オブジェクトの形式で持つ Prediction の場合 `keypoint_detection_prediction`.
  * `matched_query_detections` (*Union\[*[*`object_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`keypoint_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/keypoint-detection-prediction.md)*]*）：sv.Detections(...) 形式の検出バウンディングボックスを含む予測。 `object_detection_prediction` または、sv.Detections(...) 形式の検出バウンディングボックスとセグメンテーションマスクを含む予測。 `instance_segmentation_prediction` または、検出されたバウンディングボックスと検出されたキーポイントを sv.Detections(...) オブジェクトの形式で持つ Prediction の場合 `keypoint_detection_prediction`.
  * `matched_target_detections` (*Union\[*[*`object_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/object-detection-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/ja/gaido/developer-guide/kinds/instance-segmentation-prediction.md)*,* [*`keypoint_detection_prediction`*](/workflows/ja/gaido/developer-guide/kinds/keypoint-detection-prediction.md)*]*）：sv.Detections(...) 形式の検出バウンディングボックスを含む予測。 `object_detection_prediction` または、sv.Detections(...) 形式の検出バウンディングボックスとセグメンテーションマスクを含む予測。 `instance_segmentation_prediction` または、検出されたバウンディングボックスと検出されたキーポイントを sv.Detections(...) オブジェクトの形式で持つ Prediction の場合 `keypoint_detection_prediction`.

</details>

<details>

<summary>JSON 定義の例</summary>

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/detections_nearest_neighbor@v1",
	    "query_predictions": "$steps.model.predictions",
	    "target_predictions": "$steps.model.predictions",
	    "query_point": "CENTER",
	    "target_point": "CENTER",
	    "query_keypoint_name": "left_shoulder",
	    "target_keypoint_name": "left_shoulder",
	    "max_distance": 50
	}
```

</details>