최근접 탐지 매칭

픽셀 거리를 사용해 각 질의 탐지에 대해 가장 가까운 대상 탐지를 찾습니다.

구성 가능한 앵커 포인트 사이의 단순 2D 유클리드 픽셀 거리를 사용해, 질의 세트의 각 검출에 대해 대상 세트에서 가장 가까운 검출(동점이면 검출들)을 찾아 두 검출 세트 사이에 최근접 이웃 공간 조인을 수행합니다.

이 블록의 작동 방식

이 블록은 질의 세트의 각 검출을 대상 세트의 최근접 이웃과 매칭합니다. 이 블록은:

1. 질의 예측과 대상 예측(객체 탐지, 인스턴스 분할, 또는 키포인트 탐지)을 받습니다. 같은 세트를 질의와 대상으로 모두 전달할 수 있습니다

2. 선택한 항목에 따라 각 세트의 모든 검출에 대한 앵커 포인트를 결정합니다 query_point 및 target_point 옵션: 중심, 바운딩 박스의 네 모서리 중 하나, 네 변의 중간점 중 하나, 또는 이름이 지정된 키포인트(키포인트 탐지 예측과 query_keypoint_name/target_keypoint_name)

3. 각 질의 앵커 포인트와 각 대상 앵커 포인트 사이의 전체 쌍별 픽셀 거리 행렬을 계산합니다(브루트포스 방식이며, 공간 트리는 사용하지 않음 - 이 블록이 목표로 하는 프레임당 수십 개 검출 규모에 적합함)

4. 각 질의 검출에 대해, 그와 동일한 detection_id (자기 일치 제외), 따라서 같은 검출을 질의와 대상으로 모두 전달해도 검출이 자기 자신과 매칭되지는 않습니다

5. 만약 max_distance 가 설정되면, 남아 있는 후보 대상 중 그것보다 더 먼 것은 max_distance 질의 앵커 포인트로부터의 픽셀은 순위를 매기기 전에 제외됩니다. 제한을 초과하는 대상은 제외된 자기 일치와 동일하게 취급됩니다

6. 각 질의 검출에 대한 최소 거리를 찾은 다음, 그 최소값으로부터 고정된 1픽셀 오차 범위 안에 있는 나머지 대상 검출을 모두 포함하므로, 정확히 같거나 거의 같은 동점은 임의의 하나의 승자가 아니라 여러 매치를 생성합니다

7. 각 질의 검출의 메타데이터에 가장 가까운 거리(픽셀 단위)를 추가합니다. 적격한 대상이 없는 검출(빈 대상 세트, 모든 대상이 자기 일치로 제외됨, 또는 남아 있는 모든 대상이 max_distance)는 None

8. 주석이 추가된 질의 예측과, 동일한 길이/순서를 가진 두 검출 세트의 세 개의 평탄하게 정렬된 출력을 반환합니다 - matched_query_detections 및 matched_target_detections - 각 질의-대상 페어링당 한 행씩입니다. 동점 매치가 있는 질의 검출은 동점인 각 매치마다 한 번씩 나타나며(행이 복제됨); 유효한 매치가 없는 질의 검출은 둘 다에서 생략되며, 오직 query_predictions (여기서 nearest_target_distance 로 설정됩니다 None)

거리 측정 블록과 달리, 거리는 항상 단순하고 보정되지 않은 2D 유클리드 픽셀 거리입니다. 실제 세계 단위 변환은 없습니다. 이로 인해 이 블록은 상대적/픽셀 공간 근접성만 필요한 사용 사례에 간단하게 사용할 수 있습니다.

일반적인 사용 사례

• 구역/앵커 할당: 각 검출된 객체를 가장 가까운 기준점이나 앵커 검출에 할당합니다(예: 사람을 가장 가까운 출구 표지판에 매칭하고, 차량을 가장 가까운 주차칸 표식에 매칭), 근접성 기반 할당 워크플로를 가능하게 합니다

• 교차 클래스 연관: 한 클래스의 검출을 다른 클래스의 가장 가까운 검출과 연관시킵니다(예: 검출된 손을 가장 가까운 검출된 도구에 매칭하고, 플레이어를 가장 가까운 공 검출에 매칭), 서로 다른 객체 유형 간의 관계 분석을 가능하게 합니다

• 중복/겹침 분석: 검출 세트를 자기 자신과 비교하여 각 검출의 가장 가까운 이웃을 찾습니다(예: 군중에서 가장 가까운 다른 사람을 찾고, 밀집된 검출을 식별), 밀도 및 군집 분석을 가능하게 합니다

• 추적 인계: 같은 프레임에서 두 모델 출력 사이의 검출을 매칭합니다(예: 빠른 범용 검출기의 출력을 더 느린 전문 모델의 출력에 매칭하여 결과를 결합), 다중 모델 융합 워크플로를 가능하게 합니다

다른 블록에 연결하기

이 블록은 두 검출 세트를 받아서, 주석이 추가된 질의 예측과 모든 질의-대상 페어링을 나타내는 두 개의 평탄하게 정렬된 검출 세트를 출력합니다 - 중간 병합 단계나 차원 조작은 필요 없습니다. 왜냐하면 matched_query_detections 및 matched_target_detections 은 검출 생성 블록이 반환하는 것과 같은 형태의 일반적인 검출 세트이기 때문입니다:

• 객체 탐지, 인스턴스 분할, 또는 키포인트 탐지 모델 블록 뒤에 질의와 대상 세트를 구성하여 매칭하고, 검출-매칭 워크플로를 가능하게 합니다

• 로직 블록 이전 Continue If 또는 Detections Filter 같은 블록을 사용하여 nearest_target_distance (예: 가장 가까운 매치가 임계 거리 이내일 때만 계속) 또는 matched_query_detections/matched_target_detections 직접 필터링하여 근접성 기반 의사결정 워크플로를 가능하게 합니다

• 시각화 블록 이전 Label Visualization 또는 바운딩 박스 시각화 같은 블록을 사용하여 주석이 추가된 query_predictions, 또는 matched_query_detections/matched_target_detections 를 나란히 표시하여 매칭된 쌍을 그리며, 거리 주석이 포함된 시각화를 가능하게 합니다

• 데이터 저장 블록 앞에서 CSV 포맷터 같은 블록을 사용하여 모든 질의-대상 페어링을 한 행으로 내보내며, 매칭된 쌍 로깅 워크플로를 가능하게 합니다

요구 사항

이 블록은 두 개의 검출 예측 세트(객체 탐지, 인스턴스 분할, 또는 키포인트 탐지)를 필요로 합니다. 같은 세트를 둘 다에 사용할 수 있습니다 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 을 가지고 있는지.

입력 및 출력 바인딩

• 입력

  • query_predictions (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction]): 최근접 이웃 매치를 찾을 검출들. 이 세트의 각 검출은 target_predictions와 매칭됩니다. 같은 선택기를 둘 다에 사용할 수 있습니다 query_predictions 및 target_predictions (예: 하나의 세트 내에서 각 검출의 가장 가까운 이웃을 찾으려면) - 검출은 결코 자기 자신과 매칭되지 않습니다..

  • target_predictions (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction]): 각 항목에 대해 가장 가까운 매치를 검색할 검출들 query_predictions. 는 query_predictions..

  • query_point (string): 각 질의 검출의 위치를 나타내는 데 사용되는 앵커 포인트: 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): 각 대상 검출의 위치를 나타내는 데 사용되는 앵커 포인트. 선택지는 query_point와 동일하며, 독립적으로 설정됩니다. KEYPOINT를 사용하여 target_predictions (요구됨 target_predictions 이 키포인트 탐지 예측이어야 하고 target_keypoint_name 로 설정되어야 합니다)..

  • query_keypoint_name (string): 질의 앵커 포인트로 사용할 키포인트 클래스의 이름. 이 경우에만 필요합니다 query_point 가 KEYPOINT로 설정될 때; query_predictions 그런 다음 키포인트 탐지 예측이어야 합니다..

  • target_keypoint_name (string): 대상 앵커 포인트로 사용할 키포인트 클래스의 이름. 이 경우에만 필요합니다 target_point 가 KEYPOINT로 설정될 때; target_predictions 그런 다음 키포인트 탐지 예측이어야 합니다..

  • max_distance (정수): 질의 검출과 후보 대상 사이의 허용 가능한 최대 픽셀 거리. 이것보다 더 먼 대상은 자기 일치가 제외되는 것과 같은 방식으로 순위 매기기 전에 제외됩니다. 남아 있는 가장 가까운 대상이 여전히 이것보다 더 멀거나(또는 남아 있는 대상이 전혀 없으면) 질의 검출에는 nearest_target_distance = None 이 설정되고 matched_query_detections/matched_target_detections에서 생략됩니다. 제한이 없도록 비워 두세요..

• 출력

  • query_predictions (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction]): sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 예측, 다음 경우 object_detection_prediction 또는 sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 및 세그멘테이션 마스크 예측, 다음 경우 instance_segmentation_prediction 또는 탐지된 바운딩 박스와 탐지된 키포인트가 포함된 sv.Detections(...) 객체 형태의 예측이며, keypoint_detection_prediction.

  • matched_query_detections (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction]): sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 예측, 다음 경우 object_detection_prediction 또는 sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 및 세그멘테이션 마스크 예측, 다음 경우 instance_segmentation_prediction 또는 탐지된 바운딩 박스와 탐지된 키포인트가 포함된 sv.Detections(...) 객체 형태의 예측이며, keypoint_detection_prediction.

  • matched_target_detections (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction]): sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 예측, 다음 경우 object_detection_prediction 또는 sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 및 세그멘테이션 마스크 예측, 다음 경우 instance_segmentation_prediction 또는 탐지된 바운딩 박스와 탐지된 키포인트가 포함된 sv.Detections(...) 객체 형태의 예측이며, keypoint_detection_prediction.

예시 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
	}