템플릿 매칭

지정된 이미지 내에서 주어진 템플릿의 인스턴스를 찾습니다.

정규화 상관관계를 사용하는 템플릿 매칭으로 더 큰 이미지 안에서 템플릿 이미지의 인스턴스를 찾아 이미지의 어떤 위치에서든 템플릿 패턴과 정확하거나 거의 정확하게 일치하는 항목을 검출하고, 객체 탐지, 로고 탐지, 패턴 인식, 템플릿 기반 객체 위치 지정 워크플로를 위해 선택적 NMS 필터링과 함께 바운딩 박스 검출을 출력합니다.

이 블록의 작동 방식

이 블록은 정규화 상관관계 템플릿 매칭을 사용하여 더 큰 입력 이미지 안에서 템플릿 이미지의 발생을 찾습니다. 이 블록은:

1. 입력 이미지와 템플릿 이미지(검색할 더 작은 패턴)를 받습니다

2. 템플릿 매칭을 위해 두 이미지를 모두 그레이스케일로 변환합니다(템플릿 매칭은 일반적으로 효율성과 견고성을 위해 그레이스케일 이미지에서 작동합니다)

3. OpenCV의 matchTemplate을 TM_CCOEFF_NORMED 방식으로 사용하여 템플릿 매칭을 수행합니다:

   • 가능한 모든 위치에서 템플릿을 입력 이미지 위로 슬라이드합니다

   • 각 위치에서 정규화 상관계수를 계산합니다(템플릿과 이미지 영역 간의 유사도를 측정합니다)

   • 각 위치에서 템플릿이 얼마나 잘 일치하는지 보여주는 유사도 맵을 생성합니다

4. 유사도가 matching_threshold를 초과하는 일치 위치를 식별합니다:

   • 상관 계수가 임계값보다 크거나 같은 모든 위치를 찾습니다

   • 임계값 범위는 0.0에서 1.0까지이며, 값이 높을수록 더 가까운 일치를 요구합니다

   • 낮은 임계값은 더 많은 잠재적 일치(부분 일치 포함)를 찾고, 높은 임계값은 매우 유사한 일치만 찾습니다

5. 각 일치에 대한 바운딩 박스를 생성합니다:

   • 각 일치 위치는 템플릿의 크기에 맞는 바운딩 박스를 가진 검출 결과가 됩니다

   • 모든 검출의 신뢰도는 1.0입니다(임계값 요구사항을 충족했기 때문입니다)

   • 모든 검출에는 클래스 "template_match"와 class_id 0이 할당됩니다

   • 각 검출에는 추적을 위한 고유한 검출 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	비최대 억제를 위한 교집합 대비 합집합(IoU) 임계값입니다. apply_nms가 True일 때만 관련이 있습니다. IoU 겹침이 이 임계값보다 큰 검출은 중복으로 간주되며, 가장 높은 신뢰도의 검출만 유지됩니다. 낮은 값(0.3~0.4)은 겹침 제거에 더 공격적이며, 약간만 겹치는 검출도 제거합니다. 높은 값(0.6~0.7)은 더 관대하며, 많이 겹치는 검출만 제거합니다. 기본값은 0.5로, 균형 잡힌 겹침 필터링을 제공합니다. 템플릿 일치 간에 어느 정도의 겹침이 예상되는지와 유효한 일치가 얼마나 가까이 있을 수 있는지에 따라 조정하세요..	✅

이 참조 열은 워크플로우 런타임에서 사용 가능한 동적 값으로 속성을 매개변수화할 수 있는 가능성을 나타냅니다 워크플로우 런타임입니다. 자세한 내용은 바인딩 을 참조하세요.

입력 및 출력 바인딩

사용 가능한 연결은 바인딩 유형에 따라 달라집니다. 어떤 바인딩 유형인지 확인하세요 템플릿 매칭 버전 v1 을 가지고 있는지.

입력 및 출력 바인딩

• 입력

  • 이미지 (이미지): 템플릿 패턴을 검색할 대형 이미지입니다. 템플릿은 이 전체 이미지의 가능한 모든 위치에서 검색됩니다. 템플릿 매칭을 위해 내부적으로 이미지는 그레이스케일로 변환됩니다. 이미지와 템플릿의 조명 조건이 비슷하고 템플릿이 이미지에서 비슷한 스케일과 방향으로 나타날 때 템플릿 매칭이 가장 잘 작동합니다..

  • template (이미지): 입력 이미지 안에서 검색할 작은 템플릿 이미지 패턴입니다. 템플릿은 입력 이미지보다 작아야 합니다. 템플릿은 매칭을 위해 내부적으로 그레이스케일로 변환됩니다. 템플릿 매칭은 입력 이미지의 어떤 위치에서든 이 템플릿의 정확하거나 거의 정확한 일치를 찾습니다. 템플릿이 이미지에 동일한 스케일, 회전, 조명 조건으로 나타날 때 가장 잘 작동합니다. 템플릿의 크기는 검출 바운딩 박스의 크기를 결정합니다..

  • matching_threshold (float): 템플릿 일치에 필요한 최소 유사도 임계값(0.0~1.0)입니다. 값이 높을수록(1.0에 가까울수록) 매우 가까운 일치를 요구하며, 더 적지만 더 정확한 일치를 찾습니다. 값이 낮을수록(0.0에 가까울수록) 더 관대한 일치를 허용하며, 부분 일치를 포함한 더 많은 잠재적 일치를 찾습니다. 기본값은 0.8이며, 이는 꽤 가까운 일치를 요구합니다. 더 많은 일치를 찾거나 약간의 변형을 처리하려면 더 낮은 임계값(0.6~0.7)을 사용하세요. 정확히 일치하는 경우에만 더 높은 임계값(0.85~0.95)을 사용하세요. 이 임계값은 템플릿 매칭에서 나온 정규화 상관계수와 비교됩니다..

  • apply_nms (boolean): 겹치는 검출을 필터링하기 위해 비최대 억제(NMS)를 적용할지 여부입니다. 템플릿 매칭은 종종 같은 위치에서 많은 겹치는 검출을 생성합니다. NMS는 겹치는 검출을 제거하고 각 영역에서 가장 좋은 일치만 유지합니다. 기본값은 True이며(대부분의 경우 권장), 다음 경우 False로 설정하세요: (1) 일치 수가 매우 많은 경우(NMS가 계산 비용이 커질 수 있음), (2) 필터링 없이 모든 원시 일치를 보고 싶은 경우, (3) 일치가 의도적으로 가까이 있으며 모두 유지해야 하는 경우. 비활성화하면 같은 일치 위치에 대해 많은 중복 검출이 보일 수 있습니다..

  • nms_threshold (0에서 1 사이의 실수): 비최대 억제를 위한 교집합 대비 합집합(IoU) 임계값입니다. apply_nms가 True일 때만 관련이 있습니다. IoU 겹침이 이 임계값보다 큰 검출은 중복으로 간주되며, 가장 높은 신뢰도의 검출만 유지됩니다. 낮은 값(0.3~0.4)은 겹침 제거에 더 공격적이며, 약간만 겹치는 검출도 제거합니다. 높은 값(0.6~0.7)은 더 관대하며, 많이 겹치는 검출만 제거합니다. 기본값은 0.5로, 균형 잡힌 겹침 필터링을 제공합니다. 템플릿 일치 간에 어느 정도의 겹침이 예상되는지와 유효한 일치가 얼마나 가까이 있을 수 있는지에 따라 조정하세요..

• 출력

  • 예측 (object_detection_prediction): sv.Detections(...) 객체 형식의 감지된 바운딩 박스가 포함된 예측.

  • number_of_matches (정수): 정수 값.

예시 JSON 정의

{
	    "name": "<your_step_name_here>",
	    "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"
	}