Byte 추적기

ByteTrack를 사용하여 비디오 프레임 전반에서 객체 위치를 추적하고 업데이트합니다.

더 이상 사용되지 않음

이 블록은 더 이상 사용되지 않습니다. 대신 ByteTrack 추적기 블록을 사용하세요.

v3

ByteTrack 알고리즘을 사용하여 비디오 프레임 전반에서 객체를 추적해 일관된 객체 ID를 유지하고, 가림과 일시적인 소실을 처리하며, 탐지 결과를 기존 추적과 연관시키고, 고유한 추적 ID를 할당하고, 인스턴스를 새 항목 또는 이전에 본 항목으로 분류하며, 객체 행동 분석, 이동 추적, 첫 등장 감지, 비디오 분석 워크플로를 가능하게 합니다.

이 블록의 작동 방식

이 블록은 각 프레임의 탐지 결과를 기존 추적과 연관시키고 새 객체에 대해 새 추적을 생성함으로써 연속된 비디오 프레임 전반에서 객체 추적을 유지하며, 인스턴스가 이전에 본 적이 있는지 여부에 따라 분류합니다. 이 블록은:

1. 현재 프레임의 탐지 예측값과 비디오 메타데이터가 포함된 이미지를 수신합니다

2. 이미지에서 비디오 메타데이터(프레임 속도 및 비디오 식별자 포함)를 추출합니다:

   • WorkflowImageData 객체에서 video_metadata에 접근합니다

   • 트래커 설정을 위한 fps(초당 프레임 수)를 추출합니다

   • 서로 다른 비디오에 대해 별도의 추적 상태를 유지하기 위해 video_identifier를 추출합니다

   • 누락된 fps를 정상적으로 처리합니다(실패하지 않고 0으로 기본값을 사용하며 경고를 기록)

3. 비디오용 ByteTrack 트래커를 초기화하거나 가져옵니다:

   • 고유한 비디오마다(video_identifier로 식별됨) 새 트래커 인스턴스를 생성합니다

   • 프레임 전반의 추적 상태를 유지하기 위해 트래커를 메모리에 저장합니다

   • 메타데이터의 프레임 속도와 사용자가 지정한 매개변수로 트래커를 구성합니다

   • 같은 비디오의 이후 프레임에 대해 기존 트래커를 재사용합니다

4. 비디오용 인스턴스 캐시를 초기화하거나 가져옵니다:

   • 이전에 본 적이 있는 추적 ID를 추적하기 위한 캐시를 생성합니다

   • video_identifier를 사용하여 각 비디오마다 별도의 캐시를 유지합니다

   • instances_cache_size 매개변수를 사용하여 캐시 크기를 구성합니다

   • 캐시 용량을 관리하기 위해 FIFO(선입선출) 전략을 사용합니다

5. 여러 탐지 배치가 제공되면 병합합니다:

   • 여러 소스의 탐지를 하나의 탐지 집합으로 결합합니다

   • 일관된 추적을 위해 모든 탐지가 함께 처리되도록 보장합니다

6. ByteTrack 알고리즘을 사용해 추적을 업데이트합니다:

   • 추적 연관: IoU(Intersection over Union, 교집합 대비 합집합) 매칭을 사용해 현재 프레임의 탐지 결과를 기존 추적과 매칭합니다

   • 추적 활성화: 기존 추적과 일치하지 않는, track_activation_threshold보다 신뢰도가 높은 탐지에 대해 새 추적을 생성합니다

   • 추적 매칭: IoU가 minimum_matching_threshold를 초과할 때 탐지를 추적과 연관시킵니다

   • 추적 유지: 일시적인 가림을 처리하기 위해 lost_track_buffer를 사용하여 매칭이 없는 추적을 유지합니다

   • 추적 유효성 검사: 최소 minimum_consecutive_frames의 연속 프레임 동안 존재한 추적만 출력합니다

7. 추적된 인스턴스를 새 항목 또는 이미 본 항목으로 분류합니다:

   • track_id가 있는 각 추적된 탐지에 대해 인스턴스 캐시를 확인합니다

   • 새 인스턴스: 캐시에 없는 추적 ID는 새 항목(첫 등장)으로 표시됩니다

   • 이미 본 인스턴스: 캐시에서 찾은 추적 ID는 이미 본 항목(재등장)으로 표시됩니다

   • 새 추적 ID로 캐시를 업데이트하고 FIFO 제거 방식으로 캐시 크기를 관리합니다

8. 추적 과제를 처리합니다:

   • 가림: 객체가 일시적으로 가려져도 추적을 유지합니다(lost_track_buffer 프레임 사용)

   • 놓친 탐지: 탐지가 누락된 프레임에서도 추적을 유지합니다

   • 오탐: 충분히 오래 지속되지 않는 추적을 필터링합니다(minimum_consecutive_frames)

   • 추적 분할: 손실된 객체에 대한 버퍼를 유지하여 추적 분할을 줄입니다

9. 각 객체에 고유한 추적 ID를 할당합니다:

   • 추적되는 각 객체는 프레임 전반에 걸쳐 유지되는 일관된 track_id를 받습니다

   • 추적 ID는 추적이 활성화될 때 할당되며 비디오 전체 동안 유지됩니다

   • 전체 비디오 시퀀스에 걸쳐 개별 객체를 추적할 수 있게 합니다

10. 추적된 탐지 결과 세 가지 집합을 반환합니다:

    • tracked_detections: track_id가 포함된 모든 추적된 탐지 결과(v2와 동일)

    • new_instances: 처음 등장하는 track_id가 포함된 탐지 결과(각 track_id는 처음 생성될 때 한 번만 나타남)

    • already_seen_instances: 이전에 본 적이 있는 track_id가 포함된 탐지 결과(트래커가 탐지와 연관시킬 때마다 track_id가 나타남)

ByteTrack은 외형 특징 없이 프레임 간 탐지를 연관시키는 tracking-by-detection을 수행하는 효율적인 다중 객체 추적 알고리즘입니다. 이 알고리즘은 2단계 연관 전략을 사용합니다. 먼저 신뢰도 높은 탐지를 추적과 매칭한 다음, 신뢰도 낮은 탐지를 남은 추적과 손실된 추적에 매칭합니다. 알고리즘은 손실된 추적을 위한 버퍼를 유지하여, 객체가 가림이나 탐지 실패로 인해 일시적으로 사라졌을 때 추적을 복구할 수 있게 합니다. 인스턴스 분류 기능은 첫 등장(장면에 새로 들어오는 객체)과 재등장(가림 후 또는 프레임 밖으로 나갔다가 다시 나타나는 객체)을 구분할 수 있게 하며, 이는 카운팅, 행동 분석, 이벤트 감지에 유용합니다. 구성 가능한 매개변수는 추적 동작을 세밀하게 조정할 수 있게 합니다: track_activation_threshold는 새 추적이 생성되는 시점을 제어하고(높을수록 더 보수적), lost_track_buffer는 가림 처리를 제어하며(높을수록 가림 복구가 더 좋음), minimum_matching_threshold는 연관 품질을 제어하고(높을수록 더 엄격한 매칭), minimum_consecutive_frames는 짧게 지속되는 가짜 추적을 필터링하며(높을수록 가짜 추적이 적음), instances_cache_size는 새/이미 본 분류를 위해 기억할 추적 ID의 수를 제어합니다(높을수록 기억이 더 김).

일반적인 사용 사례

• 비디오 분석: 행동 분석과 이동 패턴을 위해 비디오 프레임 전반에서 객체를 추적합니다(예: 영상에서 사람의 이동 추적, 차량 경로 모니터링, 객체 궤적 분석), 비디오 분석 워크플로를 가능하게 함

• 첫 등장 감지: 카운팅 및 이벤트 감지를 위해 장면에 들어오는 새 객체를 식별합니다(예: 구역에 새로 들어오는 사람 감지, 새로 나타나는 차량 식별, 최초 등장 추적), 새 인스턴스 감지 워크플로를 가능하게 함

• 트래픽 모니터링: 교통 장면에서 차량과 객체를 등장 추적과 함께 추적합니다(예: 프레임 전반의 차량 추적, 차량 경로 모니터링, 일관된 ID로 고유 차량 수 계산, 장면에 들어오는 새 차량 감지), 교통 모니터링 워크플로를 가능하게 함

• 감시 시스템: 보안 모니터링을 위해 객체의 ID를 유지하고 새 प्रवेश을 감지합니다(예: 감시 영상에서 개인 추적, 구역에 새로 들어오는 사람 감지, 객체 이동 모니터링, 객체 ID 유지), 감시 추적 워크플로를 가능하게 함

• 소매 분석: 소매 인사이트를 위해 고객과 제품을 प्रवेश 감지와 함께 추적합니다(예: 고객 경로 추적, 매장에 새로 들어오는 고객 감지, 쇼핑 행동 모니터링, 유동 인구 패턴 분석), 소매 분석 워크플로를 가능하게 함

• 객체 개수 세기: 첫 등장만 추적하여 고유 객체 수를 정확하게 계산합니다(예: 새 인스턴스를 추적해 고유 방문자 수 계산, 교차로로 진입하는 차량 수 계산, 고유 객체 등장 추적), 정확한 카운팅 워크플로를 가능하게 함

다른 블록에 연결하기

이 블록은 비디오 메타데이터와 탐지 예측값이 포함된 이미지를 수신하여 tracked_detections, new_instances, already_seen_instances를 생성합니다:

• 객체 탐지, 인스턴스 분할 또는 키포인트 탐지 블록 이후 비디오 프레임 전반에서 감지된 객체를 추적하기 위해(예: 비디오에서 감지된 객체 추적, 탐지 결과에 track ID 추가, 프레임 전반의 객체 ID 유지), 탐지-추적 워크플로를 가능하게 함

• new_instances 출력 사용 첫 등장 탐지 및 처리를 위해(예: 새 객체 수 계산, 첫 등장 시 동작 트리거, 새 입력 감지, 새 객체 추적 초기화), 새 인스턴스 감지 워크플로를 가능하게 함

• already_seen_instances 출력 사용 재등장 및 돌아온 객체를 처리하기 위해(예: 돌아온 객체 처리, 재등장 처리, 기존 객체 필터링), 재등장 처리 워크플로를 가능하게 함

• 비디오 분석 블록 전에 일관된 객체 ID가 필요한 경우(예: 추적된 객체 행동 분석, 객체 궤적 처리, 추적된 객체 데이터 활용), 추적-분석 워크플로를 가능하게 함

• 시각화 블록 이전 일관된 색상이나 레이블로 추적된 객체를 표시하기 위해(예: 추적된 객체 시각화, track ID 표시, 객체 경로 표시, 새 인스턴스 강조), 추적 시각화 워크플로를 가능하게 함

• 로직 블록 이전 Continue If처럼 추적 정보나 인스턴스 상태를 기반으로 결정을 내리기 위해(예: 객체가 새 항목이면 계속, track ID를 기준으로 필터링, 추적 데이터를 사용해 결정, 새 객체와 돌아온 객체 처리), 추적 기반 결정 워크플로를 가능하게 함

버전 차이

v2에서 개선됨:

• 인스턴스 분류: 추적된 객체가 이전에 본 적이 있는지 여부에 따라 분류하는 두 개의 새 출력(new_instances 및 already_seen_instances)을 추가하여 첫 등장 감지와 재등장 추적을 가능하게 함

• 인스턴스 캐시: 프레임 전반에서 이전에 본 track ID를 기억하는 인스턴스 캐시 시스템을 도입하여, 장면에 새로 들어오는 객체와 가림 또는 프레임 밖 이탈 후 다시 나타나는 객체를 구분할 수 있게 함

• 키포인트 탐지 지원: 객체 탐지와 인스턴스 분할 외에도 키포인트 탐지 예측을 지원하여, 키포인트 기반 탐지 모델로 추적 기능을 확장함

• 구성 가능한 캐시 크기: instances_cache_size 매개변수를 추가하여 캐시에 기억할 track ID 수를 제어하고, 메모리 사용량과 추적 기록 길이의 균형을 맞춤

• 향상된 출력: 하나 대신 세 개의 출력값을 반환합니다 - tracked_detections (모든 추적 객체), new_instances (첫 등장), 그리고 already_seen_instances (재등장)

요구 사항

이 블록은 fps(초당 프레임 수)와 비디오 식별자 정보를 포함한 비디오 메타데이터가 들어 있는 이미지와 탐지 예측값(object detection, instance segmentation, 또는 keypoint detection)이 필요합니다. 이미지의 video_metadata에는 최적의 추적 성능을 위해 유효한 fps 값이 포함되어야 하지만, 값이 없으면 블록은 fps=0으로 계속 동작합니다. 이 블록은 각 비디오의 프레임 전반에서 추적 상태와 인스턴스 캐시를 유지하므로, 프레임이 순차적으로 처리되는 비디오 워크플로에서 사용해야 합니다. 최적의 추적 성능을 위해 탐지 결과는 프레임 전반에 걸쳐 일관되게 제공되어야 합니다. 이 알고리즘은 안정적인 탐지 성능에서 가장 잘 동작하며 lost_track_buffer 메커니즘을 통해 일시적인 탐지 공백을 처리합니다. 인스턴스 캐시는 캐시 크기 한도에 도달하면 FIFO 제거를 사용하여 이전에 본 track ID의 기록을 유지합니다.

유형 식별자

단계에서 다음 식별자를 사용하세요 "type" 필드: roboflow_core/byte_tracker@v3 워크플로우에 이 블록을 단계로 추가하려면.

속성

이름	유형	설명	참조
name	str	이 단계에 대한 고유 식별자를 입력하세요..	❌
track_activation_threshold	float	탐지 결과에서 새 추적을 활성화하기 위한 신뢰도 임계값입니다. 0.0과 1.0 사이여야 합니다. 기본값은 0.25입니다. 이 임계값보다 높은 신뢰도의 탐지만 새 추적을 생성할 수 있습니다. 이 값을 높이면(예: 0.3~0.5) 신뢰도 높은 탐지만으로 추적을 생성하므로 추적 정확도와 안정성이 향상되지만, 신뢰도가 낮은 실제 탐지를 놓칠 수 있습니다. 이 값을 낮추면(예: 0.15~0.2) 낮은 신뢰도의 탐지도 받아들여 추적 완전성이 높아지지만, 오탐으로 인한 노이즈와 불안정성이 증가할 수 있습니다. 탐지 모델 성능에 따라 조정하세요: 탐지가 신뢰할 수 있으면 더 낮은 값을, 오탐이 흔하면 더 높은 값을 사용하세요..	✅
lost_track_buffer	정수	추적이 손실되었을 때(일치하는 탐지 없음) 추적을 유지할 프레임 수입니다. 양의 정수여야 합니다. 기본값은 30프레임입니다. 객체가 일시적으로 사라지면(가림, 놓친 탐지, 또는 프레임 밖 이탈로 인해) 추적은 손실로 간주되기 전에 이 프레임 수만큼 유지됩니다. 이 값을 높이면(예: 50~100) 가림 처리가 향상되고 짧은 탐지 공백으로 인한 추적 분할이나 소실이 크게 줄어들지만 메모리 사용량은 증가합니다. 이 값을 낮추면(예: 10~20) 메모리 사용량은 줄어들지만 짧은 가림 동안 추적이 사라질 수 있습니다. 가림 빈도에 따라 조정하세요: 가림이 자주 발생하면 더 높은 값을, 안정적인 추적 시나리오에서는 더 낮은 값을 사용하세요..	✅
minimum_matching_threshold	float	탐지를 기존 추적과 매칭하기 위한 IoU(Intersection over Union, 교집합 대비 합집합) 임계값입니다. 0.0과 1.0 사이여야 합니다. 기본값은 0.8입니다. 탐지의 바운딩 박스 IoU가 이 임계값을 초과하면 추적과 연관됩니다. 이 값을 높이면(예: 0.85~0.95) 더 강한 공간적 겹침을 요구하므로 추적 정확도가 향상되지만, 객체가 빠르게 움직이거나 탐지 상자가 달라질 때 추적 분할이 발생할 수 있습니다. 이 값을 낮추면(예: 0.6~0.75) 더 느슨한 매칭을 허용하여 추적 완전성이 향상되지만, 잘못된 양성 연관과 추적 드리프트 위험이 있습니다. 객체 이동 속도와 탐지 안정성에 따라 조정하세요: 안정적인 객체에는 더 높은 값을, 빠르게 움직이는 객체에는 더 낮은 값을 사용하세요..	✅
minimum_consecutive_frames	정수	추적이 유효하다고 간주되어 출력되기 전에 객체를 연속해서 추적해야 하는 최소 프레임 수입니다. 양의 정수여야 합니다. 기본값은 1입니다(모든 추적이 즉시 유효함). 최소 이 연속 프레임 수 동안 지속된 추적만 출력에 포함됩니다. 이 값을 높이면(예: 3~5) 오탐 또는 중복 탐지로 인한 우발적 추적 생성을 방지하고, 짧게 지속되는 불필요한 추적을 걸러내지만, 더 짧은 정상 추적을 놓칠 수 있습니다. 이 값을 낮추면(예: 1) 모든 추적이 즉시 포함되어 완전성은 극대화되지만 오탐 추적이 포함될 수 있습니다. 오탐 비율에 따라 조정하세요: 오탐이 흔하면 더 높은 값을, 탐지가 신뢰할 수 있으면 더 낮은 값을 사용하세요..	✅
instances_cache_size	정수	인스턴스가 새 항목인지 이미 본 항목인지 판단하기 위해 인스턴스 캐시에서 기억할 수 있는 최대 track ID 수입니다. 양의 정수여야 합니다. 기본값은 16384입니다. 캐시는 FIFO(선입선출) 제거를 사용하며, 캐시가 가득 차면 가장 오래된 track ID가 제거되어 새 ID를 위한 공간이 확보됩니다. 이 값을 높이면(예: 32768~65536) 더 긴 기간의 track ID 기록을 유지하여 더 긴 간격 후의 재등장을 감지할 수 있지만 메모리를 더 많이 사용합니다. 이 값을 낮추면(예: 8192) 메모리 사용량은 줄어들지만 더 이전에 등장한 track ID 기록을 잃을 수 있어, 다시 나타난 객체가 새 항목으로 분류될 수 있습니다. 비디오 길이와 객체 재등장 패턴에 따라 조정하세요: 긴 비디오나 잦은 재등장에는 더 높은 값을, 짧은 비디오나 드문 재등장에는 더 낮은 값을 사용하세요..	❌

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

런타임 호환성

소프트 - 런타임 호스팅 서버리스, 전용 배포; 실행 원격; 입력 비디오 : 이 블록은 프로세스 메모리에서 비디오별 상태를 유지합니다(video_metadata.video_identifier로 키 지정). 상태 비저장 또는 다중 복제 HTTP 런타임에서 원격 단계 실행을 사용하면 연속 요청이 서로 다른 작업자 프로세스에서 처리될 수 있으므로, 상태가 호출 사이에 초기화되어 추적 / 카운팅 / 집계를 위한 출력은 의미가 없어집니다. 안정적인 프레임 간 결과를 위해 지속적인 WebRTC 세션에서 로컬 단계 실행을 사용하세요.

소프트 - 입력 이미지 : 이 블록은 비디오나 반복 프레임 워크플로의 시간적 문맥에 의존합니다. 정지 이미지/사진에는 추적, 비교, 집계 또는 시각화할 의미 있는 히스토리가 없으므로 이 블록은 거의 또는 전혀 이점을 제공하지 않습니다.

입력 및 출력 바인딩

사용 가능한 연결은 바인딩 유형에 따라 달라집니다. 어떤 바인딩 유형인지 확인하세요 Byte 추적기 버전 v3 을 가지고 있는지.

입력 및 출력 바인딩

• 입력

  • 이미지 (이미지): ByteTrack 초기화와 추적 상태 관리를 위해 필요한 비디오 메타데이터(fps 및 video_identifier)가 포함된 입력 이미지입니다. 블록은 WorkflowImageData 객체에서 video_metadata를 추출합니다. fps 값은 트래커 구성에 사용되며, video_identifier는 서로 다른 비디오에 대해 별도의 추적 상태와 인스턴스 캐시를 유지하는 데 사용됩니다. fps가 없거나 유효하지 않으면 블록은 0으로 기본값을 사용하고 경고를 기록하지만 계속 동작합니다. 여러 비디오를 처리하는 경우 각 비디오는 별도의 추적 상태와 캐시를 유지하기 위해 메타데이터에 고유한 video_identifier를 가져야 합니다. 블록은 video_identifier를 사용하여 각 비디오의 프레임 전반에 걸쳐 지속적인 트래커와 인스턴스 캐시를 유지합니다..

  • detections (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction]): 현재 비디오 프레임에서 추적할 탐지 예측값(object detection, instance segmentation, 또는 keypoint detection)입니다. 블록은 이러한 탐지를 기존 추적과 연관시키거나 새 추적을 생성합니다. 객체 탐지, 인스턴스 분할, 키포인트 탐지 예측을 지원합니다. 일관된 추적을 유지하려면 각 프레임에 대해 순서대로 탐지를 제공해야 합니다. 여러 탐지 배치가 제공되면 추적 전에 병합됩니다. 탐지에는 바운딩 박스와 클래스 이름이 포함되어야 하며(키포인트 탐지의 경우 키포인트도 포함). 추적 후 출력에는 track_id 정보가 추가된 동일한 탐지가 포함되어, 프레임 전반에서 같은 객체를 식별할 수 있습니다..

  • track_activation_threshold (0에서 1 사이의 실수): 탐지 결과에서 새 추적을 활성화하기 위한 신뢰도 임계값입니다. 0.0과 1.0 사이여야 합니다. 기본값은 0.25입니다. 이 임계값보다 높은 신뢰도의 탐지만 새 추적을 생성할 수 있습니다. 이 값을 높이면(예: 0.3~0.5) 신뢰도 높은 탐지만으로 추적을 생성하므로 추적 정확도와 안정성이 향상되지만, 신뢰도가 낮은 실제 탐지를 놓칠 수 있습니다. 이 값을 낮추면(예: 0.15~0.2) 낮은 신뢰도의 탐지도 받아들여 추적 완전성이 높아지지만, 오탐으로 인한 노이즈와 불안정성이 증가할 수 있습니다. 탐지 모델 성능에 따라 조정하세요: 탐지가 신뢰할 수 있으면 더 낮은 값을, 오탐이 흔하면 더 높은 값을 사용하세요..

  • lost_track_buffer (정수): 추적이 손실되었을 때(일치하는 탐지 없음) 추적을 유지할 프레임 수입니다. 양의 정수여야 합니다. 기본값은 30프레임입니다. 객체가 일시적으로 사라지면(가림, 놓친 탐지, 또는 프레임 밖 이탈로 인해) 추적은 손실로 간주되기 전에 이 프레임 수만큼 유지됩니다. 이 값을 높이면(예: 50~100) 가림 처리가 향상되고 짧은 탐지 공백으로 인한 추적 분할이나 소실이 크게 줄어들지만 메모리 사용량은 증가합니다. 이 값을 낮추면(예: 10~20) 메모리 사용량은 줄어들지만 짧은 가림 동안 추적이 사라질 수 있습니다. 가림 빈도에 따라 조정하세요: 가림이 자주 발생하면 더 높은 값을, 안정적인 추적 시나리오에서는 더 낮은 값을 사용하세요..

  • minimum_matching_threshold (0에서 1 사이의 실수): 탐지를 기존 추적과 매칭하기 위한 IoU(Intersection over Union, 교집합 대비 합집합) 임계값입니다. 0.0과 1.0 사이여야 합니다. 기본값은 0.8입니다. 탐지의 바운딩 박스 IoU가 이 임계값을 초과하면 추적과 연관됩니다. 이 값을 높이면(예: 0.85~0.95) 더 강한 공간적 겹침을 요구하므로 추적 정확도가 향상되지만, 객체가 빠르게 움직이거나 탐지 상자가 달라질 때 추적 분할이 발생할 수 있습니다. 이 값을 낮추면(예: 0.6~0.75) 더 느슨한 매칭을 허용하여 추적 완전성이 향상되지만, 잘못된 양성 연관과 추적 드리프트 위험이 있습니다. 객체 이동 속도와 탐지 안정성에 따라 조정하세요: 안정적인 객체에는 더 높은 값을, 빠르게 움직이는 객체에는 더 낮은 값을 사용하세요..

  • minimum_consecutive_frames (정수): 추적이 유효하다고 간주되어 출력되기 전에 객체를 연속해서 추적해야 하는 최소 프레임 수입니다. 양의 정수여야 합니다. 기본값은 1입니다(모든 추적이 즉시 유효함). 최소 이 연속 프레임 수 동안 지속된 추적만 출력에 포함됩니다. 이 값을 높이면(예: 3~5) 오탐 또는 중복 탐지로 인한 우발적 추적 생성을 방지하고, 짧게 지속되는 불필요한 추적을 걸러내지만, 더 짧은 정상 추적을 놓칠 수 있습니다. 이 값을 낮추면(예: 1) 모든 추적이 즉시 포함되어 완전성은 극대화되지만 오탐 추적이 포함될 수 있습니다. 오탐 비율에 따라 조정하세요: 오탐이 흔하면 더 높은 값을, 탐지가 신뢰할 수 있으면 더 낮은 값을 사용하세요..

• 출력

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

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

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

예시 JSON 정의

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/byte_tracker@v3",
	    "image": "<block_does_not_provide_example>",
	    "detections": "$steps.object_detection_model.predictions",
	    "track_activation_threshold": 0.25,
	    "lost_track_buffer": 30,
	    "minimum_matching_threshold": 0.8,
	    "minimum_consecutive_frames": 1,
	    "instances_cache_size": "<block_does_not_provide_example>"
	}

v2

ByteTrack 알고리즘을 사용하여 비디오 프레임 전반에서 객체를 추적해 일관된 객체 ID를 유지하고, 가림과 일시적인 소실을 처리하며, 탐지 결과를 기존 추적과 연관시키고, 고유한 추적 ID를 할당하며, 객체 행동 분석, 이동 추적, 비디오 분석 워크플로를 가능하게 합니다.

이 블록의 작동 방식

이 블록은 각 프레임의 탐지 결과를 기존 추적과 연관시키고 새 객체에 대해 새 추적을 생성함으로써 연속된 비디오 프레임 전반에서 객체 추적을 유지합니다. 이 블록은:

1. 현재 프레임의 탐지 예측값과 비디오 메타데이터가 포함된 이미지를 수신합니다

2. 이미지에서 비디오 메타데이터(프레임 속도 및 비디오 식별자 포함)를 추출합니다:

   • WorkflowImageData 객체에서 video_metadata에 접근합니다

   • 트래커 설정을 위한 fps(초당 프레임 수)를 추출합니다

   • 서로 다른 비디오에 대해 별도의 추적 상태를 유지하기 위해 video_identifier를 추출합니다

   • 누락된 fps를 정상적으로 처리합니다(실패하지 않고 0으로 기본값을 사용하며 경고를 기록)

3. 비디오용 ByteTrack 트래커를 초기화하거나 가져옵니다:

   • 고유한 비디오마다(video_identifier로 식별됨) 새 트래커 인스턴스를 생성합니다

   • 프레임 전반의 추적 상태를 유지하기 위해 트래커를 메모리에 저장합니다

   • 메타데이터의 프레임 속도와 사용자가 지정한 매개변수로 트래커를 구성합니다

   • 같은 비디오의 이후 프레임에 대해 기존 트래커를 재사용합니다

4. 여러 탐지 배치가 제공되면 병합합니다:

   • 여러 소스의 탐지를 하나의 탐지 집합으로 결합합니다

   • 일관된 추적을 위해 모든 탐지가 함께 처리되도록 보장합니다

5. ByteTrack 알고리즘을 사용해 추적을 업데이트합니다:

   • 추적 연관: IoU(Intersection over Union, 교집합 대비 합집합) 매칭을 사용해 현재 프레임의 탐지 결과를 기존 추적과 매칭합니다

   • 추적 활성화: 기존 추적과 일치하지 않는, track_activation_threshold보다 신뢰도가 높은 탐지에 대해 새 추적을 생성합니다

   • 추적 매칭: IoU가 minimum_matching_threshold를 초과할 때 탐지를 추적과 연관시킵니다

   • 추적 유지: 일시적인 가림을 처리하기 위해 lost_track_buffer를 사용하여 매칭이 없는 추적을 유지합니다

   • 추적 유효성 검사: 최소 minimum_consecutive_frames의 연속 프레임 동안 존재한 추적만 출력합니다

6. 추적 과제를 처리합니다:

   • 가림: 객체가 일시적으로 가려져도 추적을 유지합니다(lost_track_buffer 프레임 사용)

   • 놓친 탐지: 탐지가 누락된 프레임에서도 추적을 유지합니다

   • 오탐: 충분히 오래 지속되지 않는 추적을 필터링합니다(minimum_consecutive_frames)

   • 추적 분할: 손실된 객체에 대한 버퍼를 유지하여 추적 분할을 줄입니다

7. 각 객체에 고유한 추적 ID를 할당합니다:

   • 추적되는 각 객체는 프레임 전반에 걸쳐 유지되는 일관된 track_id를 받습니다

   • 추적 ID는 추적이 활성화될 때 할당되며 비디오 전체 동안 유지됩니다

   • 전체 비디오 시퀀스에 걸쳐 개별 객체를 추적할 수 있게 합니다

8. track ID가 포함된 추적된 탐지 결과를 반환합니다:

   • track_id 정보가 추가된 탐지 예측값을 출력합니다

   • 각 탐지에는 프레임 전반에서 같은 객체를 식별하기 위한 할당된 track_id가 포함됩니다

   • 모든 원래 탐지 속성(바운딩 박스, 신뢰도, 클래스 이름)에 추적 정보를 더해 유지합니다

ByteTrack은 외형 특징 없이 프레임 간 탐지를 연관시키는 tracking-by-detection을 수행하는 효율적인 다중 객체 추적 알고리즘입니다. 이 알고리즘은 2단계 연관 전략을 사용합니다. 먼저 신뢰도 높은 탐지를 추적과 매칭한 다음, 신뢰도 낮은 탐지를 남은 추적과 손실된 추적에 매칭합니다. 알고리즘은 손실된 추적을 위한 버퍼를 유지하여, 객체가 가림이나 탐지 실패로 인해 일시적으로 사라졌을 때 추적을 복구할 수 있게 합니다. 구성 가능한 매개변수는 추적 동작을 세밀하게 조정할 수 있게 합니다: track_activation_threshold는 새 추적이 생성되는 시점을 제어하고(높을수록 더 보수적), lost_track_buffer는 가림 처리를 제어하며(높을수록 가림 복구가 더 좋음), minimum_matching_threshold는 연관 품질을 제어하고(높을수록 더 엄격한 매칭), minimum_consecutive_frames는 짧게 지속되는 가짜 추적을 필터링하며(높을수록 가짜 추적이 적음).

일반적인 사용 사례

• 비디오 분석: 행동 분석과 이동 패턴을 위해 비디오 프레임 전반에서 객체를 추적합니다(예: 영상에서 사람의 이동 추적, 차량 경로 모니터링, 객체 궤적 분석), 비디오 분석 워크플로를 가능하게 함

• 트래픽 모니터링: 교통 분석을 위해 교통 장면에서 차량과 객체를 추적합니다(예: 프레임 전반의 차량 추적, 차량 경로 모니터링, 일관된 ID로 차량 수 계산), 교통 모니터링 워크플로를 가능하게 함

• 감시 시스템: 보안 모니터링을 위해 비디오 프레임 전반에서 객체 ID를 유지합니다(예: 감시 영상에서 개인 추적, 객체 이동 모니터링, 객체 ID 유지), 감시 추적 워크플로를 가능하게 함

• 스포츠 분석: 성능 분석을 위해 스포츠 비디오에서 선수와 객체를 추적합니다(예: 선수 이동 추적, 선수 궤적 분석, 공 위치 모니터링), 스포츠 분석 워크플로를 가능하게 함

• 소매 분석: 소매 인사이트를 위해 비디오 프레임 전반에서 고객과 제품을 추적합니다(예: 고객 경로 추적, 쇼핑 행동 모니터링, 유동 인구 패턴 분석), 소매 분석 워크플로를 가능하게 함

• 객체 행동 분석: 시간 경과에 따른 행동과 상호작용을 분석하기 위해 객체를 추적합니다(예: 객체 상호작용 분석, 이동 패턴 연구, 객체 관계 추적), 행동 분석 워크플로를 가능하게 함

다른 블록에 연결하기

이 블록은 비디오 메타데이터와 탐지 예측값이 포함된 이미지를 수신하여 track ID가 포함된 tracked_detections를 생성합니다:

• 객체 탐지 또는 인스턴스 분할 블록 이후 비디오 프레임 전반에서 감지된 객체를 추적하기 위해(예: 비디오에서 감지된 객체 추적, 탐지 결과에 track ID 추가, 프레임 전반의 객체 ID 유지), 탐지-추적 워크플로를 가능하게 함

• 비디오 분석 블록 전에 일관된 객체 ID가 필요한 경우(예: 추적된 객체 행동 분석, 객체 궤적 처리, 추적된 객체 데이터 활용), 추적-분석 워크플로를 가능하게 함

• 시각화 블록 이전 일관된 색상이나 레이블로 추적된 객체를 표시하기 위해(예: 추적된 객체 시각화, track ID 표시, 객체 경로 표시), 추적 시각화 워크플로를 가능하게 함

• 로직 블록 이전 Continue If처럼 추적 정보에 기반해 결정을 내리기 위해(예: 객체가 추적 중이면 계속, track ID를 기준으로 필터링, 추적 데이터를 사용해 결정), 추적 기반 결정 워크플로를 가능하게 함

• 집계 또는 카운팅 블록 전에 추적된 객체를 정확하게 계산하기 위해(예: 고유한 추적 객체 수 계산, 추적 통계 집계, 추적 데이터 처리), 추적-카운팅 워크플로를 가능하게 함

• 비디오 처리 파이프라인에서 객체 추적이 더 큰 비디오 분석 워크플로의 일부인 경우(예: 비디오 파이프라인에서 객체 추적, 처리 체인에서 ID 유지, 비디오 분석 활성화), 비디오 추적 파이프라인 워크플로를 가능하게 함

버전 차이

v1에서 개선됨:

• 간소화된 입력: 이미지 별도의 메타데이터 필드를 요구하는 대신 임베디드 비디오 메타데이터가 포함된 input을 사용하여 워크플로 연결을 단순화하고 입력 복잡성을 줄입니다

• 유연한 FPS 처리: 오류를 발생시키지 않고 0으로 기본값을 사용하고 경고를 기록함으로써 누락되었거나 유효하지 않은 fps 값을 정상적으로 처리하여, 불완전한 메타데이터에 대해 이 블록의 복원력을 높입니다

• 향상된 통합: 이미지 객체에서 직접 비디오 메타데이터에 접근하므로, 별도의 메타데이터 입력을 요구하지 않아 이미지 기반 워크플로와 더 잘 통합됩니다

요구 사항

이 블록은 fps(초당 프레임 수)와 비디오 식별자 정보를 포함한 비디오 메타데이터가 들어 있는 이미지와 탐지 예측값(object detection 또는 instance segmentation)이 필요합니다. 이미지의 video_metadata에는 최적의 추적 성능을 위해 유효한 fps 값이 포함되어야 하지만, 값이 없으면 블록은 fps=0으로 계속 동작합니다. 이 블록은 각 비디오의 프레임 전반에서 추적 상태를 유지하므로, 프레임이 순차적으로 처리되는 비디오 워크플로에서 사용해야 합니다. 최적의 추적 성능을 위해 탐지 결과는 프레임 전반에 걸쳐 일관되게 제공되어야 합니다. 이 알고리즘은 안정적인 탐지 성능에서 가장 잘 동작하며 lost_track_buffer 메커니즘을 통해 일시적인 탐지 공백을 처리합니다.

유형 식별자

단계에서 다음 식별자를 사용하세요 "type" 필드: roboflow_core/byte_tracker@v2 워크플로우에 이 블록을 단계로 추가하려면.

속성

이름	유형	설명	참조
name	str	이 단계에 대한 고유 식별자를 입력하세요..	❌
track_activation_threshold	float	탐지 결과에서 새 추적을 활성화하기 위한 신뢰도 임계값입니다. 0.0과 1.0 사이여야 합니다. 기본값은 0.25입니다. 이 임계값보다 높은 신뢰도의 탐지만 새 추적을 생성할 수 있습니다. 이 값을 높이면(예: 0.3~0.5) 신뢰도 높은 탐지만으로 추적을 생성하므로 추적 정확도와 안정성이 향상되지만, 신뢰도가 낮은 실제 탐지를 놓칠 수 있습니다. 이 값을 낮추면(예: 0.15~0.2) 낮은 신뢰도의 탐지도 받아들여 추적 완전성이 높아지지만, 오탐으로 인한 노이즈와 불안정성이 증가할 수 있습니다. 탐지 모델 성능에 따라 조정하세요: 탐지가 신뢰할 수 있으면 더 낮은 값을, 오탐이 흔하면 더 높은 값을 사용하세요..	✅
lost_track_buffer	정수	추적이 손실되었을 때(일치하는 탐지 없음) 추적을 유지할 프레임 수입니다. 양의 정수여야 합니다. 기본값은 30프레임입니다. 객체가 일시적으로 사라지면(가림, 놓친 탐지, 또는 프레임 밖 이탈로 인해) 추적은 손실로 간주되기 전에 이 프레임 수만큼 유지됩니다. 이 값을 높이면(예: 50~100) 가림 처리가 향상되고 짧은 탐지 공백으로 인한 추적 분할이나 소실이 크게 줄어들지만 메모리 사용량은 증가합니다. 이 값을 낮추면(예: 10~20) 메모리 사용량은 줄어들지만 짧은 가림 동안 추적이 사라질 수 있습니다. 가림 빈도에 따라 조정하세요: 가림이 자주 발생하면 더 높은 값을, 안정적인 추적 시나리오에서는 더 낮은 값을 사용하세요..	✅
minimum_matching_threshold	float	탐지를 기존 추적과 매칭하기 위한 IoU(Intersection over Union, 교집합 대비 합집합) 임계값입니다. 0.0과 1.0 사이여야 합니다. 기본값은 0.8입니다. 탐지의 바운딩 박스 IoU가 이 임계값을 초과하면 추적과 연관됩니다. 이 값을 높이면(예: 0.85~0.95) 더 강한 공간적 겹침을 요구하므로 추적 정확도가 향상되지만, 객체가 빠르게 움직이거나 탐지 상자가 달라질 때 추적 분할이 발생할 수 있습니다. 이 값을 낮추면(예: 0.6~0.75) 더 느슨한 매칭을 허용하여 추적 완전성이 향상되지만, 잘못된 양성 연관과 추적 드리프트 위험이 있습니다. 객체 이동 속도와 탐지 안정성에 따라 조정하세요: 안정적인 객체에는 더 높은 값을, 빠르게 움직이는 객체에는 더 낮은 값을 사용하세요..	✅
minimum_consecutive_frames	정수	추적이 유효하다고 간주되어 출력되기 전에 객체를 연속해서 추적해야 하는 최소 프레임 수입니다. 양의 정수여야 합니다. 기본값은 1입니다(모든 추적이 즉시 유효함). 최소 이 연속 프레임 수 동안 지속된 추적만 출력에 포함됩니다. 이 값을 높이면(예: 3~5) 오탐 또는 중복 탐지로 인한 우발적 추적 생성을 방지하고, 짧게 지속되는 불필요한 추적을 걸러내지만, 더 짧은 정상 추적을 놓칠 수 있습니다. 이 값을 낮추면(예: 1) 모든 추적이 즉시 포함되어 완전성은 극대화되지만 오탐 추적이 포함될 수 있습니다. 오탐 비율에 따라 조정하세요: 오탐이 흔하면 더 높은 값을, 탐지가 신뢰할 수 있으면 더 낮은 값을 사용하세요..	✅

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

런타임 호환성

소프트 - 런타임 호스팅 서버리스, 전용 배포; 실행 원격; 입력 비디오 : 이 블록은 프로세스 메모리에서 비디오별 상태를 유지합니다(video_metadata.video_identifier로 키 지정). 상태 비저장 또는 다중 복제 HTTP 런타임에서 원격 단계 실행을 사용하면 연속 요청이 서로 다른 작업자 프로세스에서 처리될 수 있으므로, 상태가 호출 사이에 초기화되어 추적 / 카운팅 / 집계를 위한 출력은 의미가 없어집니다. 안정적인 프레임 간 결과를 위해 지속적인 WebRTC 세션에서 로컬 단계 실행을 사용하세요.

소프트 - 입력 이미지 : 이 블록은 비디오나 반복 프레임 워크플로의 시간적 문맥에 의존합니다. 정지 이미지/사진에는 추적, 비교, 집계 또는 시각화할 의미 있는 히스토리가 없으므로 이 블록은 거의 또는 전혀 이점을 제공하지 않습니다.

입력 및 출력 바인딩

사용 가능한 연결은 바인딩 유형에 따라 달라집니다. 어떤 바인딩 유형인지 확인하세요 Byte 추적기 버전 v2 을 가지고 있는지.

입력 및 출력 바인딩

• 입력

  • 이미지 (이미지): ByteTrack 초기화와 추적 상태 관리를 위해 필요한 비디오 메타데이터(fps 및 video_identifier)가 포함된 입력 이미지입니다. 블록은 WorkflowImageData 객체에서 video_metadata를 추출합니다. fps 값은 트래커 구성에 사용되며, video_identifier는 서로 다른 비디오에 대해 별도의 추적 상태를 유지하는 데 사용됩니다. fps가 없거나 유효하지 않으면 블록은 0으로 기본값을 사용하고 경고를 기록하지만 계속 동작합니다. 여러 비디오를 처리하는 경우 각 비디오는 별도의 추적 상태를 유지하기 위해 메타데이터에 고유한 video_identifier를 가져야 합니다. 블록은 video_identifier를 사용하여 각 비디오의 프레임 전반에 걸쳐 지속적인 트래커를 유지합니다. 이 버전은 별도의 메타데이터 필드 대신 이미지 객체에 메타데이터를 포함시켜 입력을 단순화합니다..

  • detections (Union[object_detection_prediction, instance_segmentation_prediction]): 현재 비디오 프레임에서 추적할 탐지 예측값(object detection 또는 instance segmentation)입니다. 블록은 이러한 탐지를 기존 추적과 연관시키거나 새 추적을 생성합니다. 일관된 추적을 유지하려면 각 프레임에 대해 순서대로 탐지를 제공해야 합니다. 여러 탐지 배치가 제공되면 추적 전에 병합됩니다. 탐지에는 바운딩 박스와 클래스 이름이 포함되어야 합니다. 추적 후 출력에는 track_id 정보가 추가된 동일한 탐지가 포함되어, 프레임 전반에서 같은 객체를 식별할 수 있습니다..

  • track_activation_threshold (0에서 1 사이의 실수): 탐지 결과에서 새 추적을 활성화하기 위한 신뢰도 임계값입니다. 0.0과 1.0 사이여야 합니다. 기본값은 0.25입니다. 이 임계값보다 높은 신뢰도의 탐지만 새 추적을 생성할 수 있습니다. 이 값을 높이면(예: 0.3~0.5) 신뢰도 높은 탐지만으로 추적을 생성하므로 추적 정확도와 안정성이 향상되지만, 신뢰도가 낮은 실제 탐지를 놓칠 수 있습니다. 이 값을 낮추면(예: 0.15~0.2) 낮은 신뢰도의 탐지도 받아들여 추적 완전성이 높아지지만, 오탐으로 인한 노이즈와 불안정성이 증가할 수 있습니다. 탐지 모델 성능에 따라 조정하세요: 탐지가 신뢰할 수 있으면 더 낮은 값을, 오탐이 흔하면 더 높은 값을 사용하세요..

  • lost_track_buffer (정수): 추적이 손실되었을 때(일치하는 탐지 없음) 추적을 유지할 프레임 수입니다. 양의 정수여야 합니다. 기본값은 30프레임입니다. 객체가 일시적으로 사라지면(가림, 놓친 탐지, 또는 프레임 밖 이탈로 인해) 추적은 손실로 간주되기 전에 이 프레임 수만큼 유지됩니다. 이 값을 높이면(예: 50~100) 가림 처리가 향상되고 짧은 탐지 공백으로 인한 추적 분할이나 소실이 크게 줄어들지만 메모리 사용량은 증가합니다. 이 값을 낮추면(예: 10~20) 메모리 사용량은 줄어들지만 짧은 가림 동안 추적이 사라질 수 있습니다. 가림 빈도에 따라 조정하세요: 가림이 자주 발생하면 더 높은 값을, 안정적인 추적 시나리오에서는 더 낮은 값을 사용하세요..

  • minimum_matching_threshold (0에서 1 사이의 실수): 탐지를 기존 추적과 매칭하기 위한 IoU(Intersection over Union, 교집합 대비 합집합) 임계값입니다. 0.0과 1.0 사이여야 합니다. 기본값은 0.8입니다. 탐지의 바운딩 박스 IoU가 이 임계값을 초과하면 추적과 연관됩니다. 이 값을 높이면(예: 0.85~0.95) 더 강한 공간적 겹침을 요구하므로 추적 정확도가 향상되지만, 객체가 빠르게 움직이거나 탐지 상자가 달라질 때 추적 분할이 발생할 수 있습니다. 이 값을 낮추면(예: 0.6~0.75) 더 느슨한 매칭을 허용하여 추적 완전성이 향상되지만, 잘못된 양성 연관과 추적 드리프트 위험이 있습니다. 객체 이동 속도와 탐지 안정성에 따라 조정하세요: 안정적인 객체에는 더 높은 값을, 빠르게 움직이는 객체에는 더 낮은 값을 사용하세요..

  • minimum_consecutive_frames (정수): 추적이 유효하다고 간주되어 출력되기 전에 객체를 연속해서 추적해야 하는 최소 프레임 수입니다. 양의 정수여야 합니다. 기본값은 1입니다(모든 추적이 즉시 유효함). 최소 이 연속 프레임 수 동안 지속된 추적만 출력에 포함됩니다. 이 값을 높이면(예: 3~5) 오탐 또는 중복 탐지로 인한 우발적 추적 생성을 방지하고, 짧게 지속되는 불필요한 추적을 걸러내지만, 더 짧은 정상 추적을 놓칠 수 있습니다. 이 값을 낮추면(예: 1) 모든 추적이 즉시 포함되어 완전성은 극대화되지만 오탐 추적이 포함될 수 있습니다. 오탐 비율에 따라 조정하세요: 오탐이 흔하면 더 높은 값을, 탐지가 신뢰할 수 있으면 더 낮은 값을 사용하세요..

• 출력

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

예시 JSON 정의

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/byte_tracker@v2",
	    "image": "<block_does_not_provide_example>",
	    "detections": "$steps.object_detection_model.predictions",
	    "track_activation_threshold": 0.25,
	    "lost_track_buffer": 30,
	    "minimum_matching_threshold": 0.8,
	    "minimum_consecutive_frames": 1
	}

v1

ByteTrack 알고리즘을 사용하여 비디오 프레임 전반에서 객체를 추적해 일관된 객체 ID를 유지하고, 가림과 일시적인 소실을 처리하며, 탐지 결과를 기존 추적과 연관시키고, 고유한 추적 ID를 할당하며, 객체 행동 분석, 이동 추적, 비디오 분석 워크플로를 가능하게 합니다.

이 블록의 작동 방식

이 블록은 각 프레임의 탐지 결과를 기존 추적과 연관시키고 새 객체에 대해 새 추적을 생성함으로써 연속된 비디오 프레임 전반에서 객체 추적을 유지합니다. 이 블록은:

1. 현재 프레임의 탐지 예측값과 비디오 메타데이터(프레임 속도 및 비디오 식별자 포함)를 수신합니다

2. 비디오용 ByteTrack 트래커를 초기화하거나 가져옵니다:

   • 고유한 비디오마다(video_identifier로 식별됨) 새 트래커 인스턴스를 생성합니다

   • 프레임 전반의 추적 상태를 유지하기 위해 트래커를 메모리에 저장합니다

   • 메타데이터의 프레임 속도와 사용자가 지정한 매개변수로 트래커를 구성합니다

   • 같은 비디오의 이후 프레임에 대해 기존 트래커를 재사용합니다

3. 여러 탐지 배치가 제공되면 병합합니다:

   • 여러 소스의 탐지를 하나의 탐지 집합으로 결합합니다

   • 일관된 추적을 위해 모든 탐지가 함께 처리되도록 보장합니다

4. ByteTrack 알고리즘을 사용해 추적을 업데이트합니다:

   • 추적 연관: IoU(Intersection over Union, 교집합 대비 합집합) 매칭을 사용해 현재 프레임의 탐지 결과를 기존 추적과 매칭합니다

   • 추적 활성화: 기존 추적과 일치하지 않는, track_activation_threshold보다 신뢰도가 높은 탐지에 대해 새 추적을 생성합니다

   • 추적 매칭: IoU가 minimum_matching_threshold를 초과할 때 탐지를 추적과 연관시킵니다

   • 추적 유지: 일시적인 가림을 처리하기 위해 lost_track_buffer를 사용하여 매칭이 없는 추적을 유지합니다

   • 추적 유효성 검사: 최소 minimum_consecutive_frames의 연속 프레임 동안 존재한 추적만 출력합니다

5. 추적 과제를 처리합니다:

   • 가림: 객체가 일시적으로 가려져도 추적을 유지합니다(lost_track_buffer 프레임 사용)

   • 놓친 탐지: 탐지가 누락된 프레임에서도 추적을 유지합니다

   • 오탐: 충분히 오래 지속되지 않는 추적을 필터링합니다(minimum_consecutive_frames)

   • 추적 분할: 손실된 객체에 대한 버퍼를 유지하여 추적 분할을 줄입니다

6. 각 객체에 고유한 추적 ID를 할당합니다:

   • 추적되는 각 객체는 프레임 전반에 걸쳐 유지되는 일관된 track_id를 받습니다

   • 추적 ID는 추적이 활성화될 때 할당되며 비디오 전체 동안 유지됩니다

   • 전체 비디오 시퀀스에 걸쳐 개별 객체를 추적할 수 있게 합니다

7. track ID가 포함된 추적된 탐지 결과를 반환합니다:

   • track_id 정보가 추가된 탐지 예측값을 출력합니다

   • 각 탐지에는 프레임 전반에서 같은 객체를 식별하기 위한 할당된 track_id가 포함됩니다

   • 모든 원래 탐지 속성(바운딩 박스, 신뢰도, 클래스 이름)에 추적 정보를 더해 유지합니다

ByteTrack은 외형 특징 없이 프레임 간 탐지를 연관시키는 tracking-by-detection을 수행하는 효율적인 다중 객체 추적 알고리즘입니다. 이 알고리즘은 2단계 연관 전략을 사용합니다. 먼저 신뢰도 높은 탐지를 추적과 매칭한 다음, 신뢰도 낮은 탐지를 남은 추적과 손실된 추적에 매칭합니다. 알고리즘은 손실된 추적을 위한 버퍼를 유지하여, 객체가 가림이나 탐지 실패로 인해 일시적으로 사라졌을 때 추적을 복구할 수 있게 합니다. 구성 가능한 매개변수는 추적 동작을 세밀하게 조정할 수 있게 합니다: track_activation_threshold는 새 추적이 생성되는 시점을 제어하고(높을수록 더 보수적), lost_track_buffer는 가림 처리를 제어하며(높을수록 가림 복구가 더 좋음), minimum_matching_threshold는 연관 품질을 제어하고(높을수록 더 엄격한 매칭), minimum_consecutive_frames는 짧게 지속되는 가짜 추적을 필터링하며(높을수록 가짜 추적이 적음).

일반적인 사용 사례

• 비디오 분석: 행동 분석과 이동 패턴을 위해 비디오 프레임 전반에서 객체를 추적합니다(예: 영상에서 사람의 이동 추적, 차량 경로 모니터링, 객체 궤적 분석), 비디오 분석 워크플로를 가능하게 함

• 트래픽 모니터링: 교통 분석을 위해 교통 장면에서 차량과 객체를 추적합니다(예: 프레임 전반의 차량 추적, 차량 경로 모니터링, 일관된 ID로 차량 수 계산), 교통 모니터링 워크플로를 가능하게 함

• 감시 시스템: 보안 모니터링을 위해 비디오 프레임 전반에서 객체 ID를 유지합니다(예: 감시 영상에서 개인 추적, 객체 이동 모니터링, 객체 ID 유지), 감시 추적 워크플로를 가능하게 함

• 스포츠 분석: 성능 분석을 위해 스포츠 비디오에서 선수와 객체를 추적합니다(예: 선수 이동 추적, 선수 궤적 분석, 공 위치 모니터링), 스포츠 분석 워크플로를 가능하게 함

• 소매 분석: 소매 인사이트를 위해 비디오 프레임 전반에서 고객과 제품을 추적합니다(예: 고객 경로 추적, 쇼핑 행동 모니터링, 유동 인구 패턴 분석), 소매 분석 워크플로를 가능하게 함

• 객체 행동 분석: 시간 경과에 따른 행동과 상호작용을 분석하기 위해 객체를 추적합니다(예: 객체 상호작용 분석, 이동 패턴 연구, 객체 관계 추적), 행동 분석 워크플로를 가능하게 함

다른 블록에 연결하기

이 블록은 탐지 예측값과 비디오 메타데이터를 수신하여 track ID가 포함된 tracked_detections를 생성합니다:

• 객체 탐지 또는 인스턴스 분할 블록 이후 비디오 프레임 전반에서 감지된 객체를 추적하기 위해(예: 비디오에서 감지된 객체 추적, 탐지 결과에 track ID 추가, 프레임 전반의 객체 ID 유지), 탐지-추적 워크플로를 가능하게 함

• 비디오 분석 블록 전에 일관된 객체 ID가 필요한 경우(예: 추적된 객체 행동 분석, 객체 궤적 처리, 추적된 객체 데이터 활용), 추적-분석 워크플로를 가능하게 함

• 시각화 블록 이전 일관된 색상이나 레이블로 추적된 객체를 표시하기 위해(예: 추적된 객체 시각화, track ID 표시, 객체 경로 표시), 추적 시각화 워크플로를 가능하게 함

• 로직 블록 이전 Continue If처럼 추적 정보에 기반해 결정을 내리기 위해(예: 객체가 추적 중이면 계속, track ID를 기준으로 필터링, 추적 데이터를 사용해 결정), 추적 기반 결정 워크플로를 가능하게 함

• 집계 또는 카운팅 블록 전에 추적된 객체를 정확하게 계산하기 위해(예: 고유한 추적 객체 수 계산, 추적 통계 집계, 추적 데이터 처리), 추적-카운팅 워크플로를 가능하게 함

• 비디오 처리 파이프라인에서 객체 추적이 더 큰 비디오 분석 워크플로의 일부인 경우(예: 비디오 파이프라인에서 객체 추적, 처리 체인에서 ID 유지, 비디오 분석 활성화), 비디오 추적 파이프라인 워크플로를 가능하게 함

요구 사항

이 블록은 fps(초당 프레임 수) 정보를 포함한 비디오 메타데이터와 탐지 예측값(object detection 또는 instance segmentation)이 필요합니다. 비디오 메타데이터에는 ByteTrack 초기화를 위한 유효한 fps 값이 포함되어야 합니다. 이 블록은 각 비디오의 프레임 전반에서 추적 상태를 유지하므로, 프레임이 순차적으로 처리되는 비디오 워크플로에서 사용해야 합니다. 최적의 추적 성능을 위해 탐지 결과는 프레임 전반에 걸쳐 일관되게 제공되어야 합니다. 이 알고리즘은 안정적인 탐지 성능에서 가장 잘 동작하며 lost_track_buffer 메커니즘을 통해 일시적인 탐지 공백을 처리합니다.

유형 식별자

단계에서 다음 식별자를 사용하세요 "type" 필드: roboflow_core/byte_tracker@v1 워크플로우에 이 블록을 단계로 추가하려면.

속성

이름	유형	설명	참조
name	str	이 단계에 대한 고유 식별자를 입력하세요..	❌
track_activation_threshold	float	탐지 결과에서 새 추적을 활성화하기 위한 신뢰도 임계값입니다. 0.0과 1.0 사이여야 합니다. 기본값은 0.25입니다. 이 임계값보다 높은 신뢰도의 탐지만 새 추적을 생성할 수 있습니다. 이 값을 높이면(예: 0.3~0.5) 신뢰도 높은 탐지만으로 추적을 생성하므로 추적 정확도와 안정성이 향상되지만, 신뢰도가 낮은 실제 탐지를 놓칠 수 있습니다. 이 값을 낮추면(예: 0.15~0.2) 낮은 신뢰도의 탐지도 받아들여 추적 완전성이 높아지지만, 오탐으로 인한 노이즈와 불안정성이 증가할 수 있습니다. 탐지 모델 성능에 따라 조정하세요: 탐지가 신뢰할 수 있으면 더 낮은 값을, 오탐이 흔하면 더 높은 값을 사용하세요..	✅
lost_track_buffer	정수	추적이 손실되었을 때(일치하는 탐지 없음) 추적을 유지할 프레임 수입니다. 양의 정수여야 합니다. 기본값은 30프레임입니다. 객체가 일시적으로 사라지면(가림, 놓친 탐지, 또는 프레임 밖 이탈로 인해) 추적은 손실로 간주되기 전에 이 프레임 수만큼 유지됩니다. 이 값을 높이면(예: 50~100) 가림 처리가 향상되고 짧은 탐지 공백으로 인한 추적 분할이나 소실이 크게 줄어들지만 메모리 사용량은 증가합니다. 이 값을 낮추면(예: 10~20) 메모리 사용량은 줄어들지만 짧은 가림 동안 추적이 사라질 수 있습니다. 가림 빈도에 따라 조정하세요: 가림이 자주 발생하면 더 높은 값을, 안정적인 추적 시나리오에서는 더 낮은 값을 사용하세요..	✅
minimum_matching_threshold	float	탐지를 기존 추적과 매칭하기 위한 IoU(Intersection over Union, 교집합 대비 합집합) 임계값입니다. 0.0과 1.0 사이여야 합니다. 기본값은 0.8입니다. 탐지의 바운딩 박스 IoU가 이 임계값을 초과하면 추적과 연관됩니다. 이 값을 높이면(예: 0.85~0.95) 더 강한 공간적 겹침을 요구하므로 추적 정확도가 향상되지만, 객체가 빠르게 움직이거나 탐지 상자가 달라질 때 추적 분할이 발생할 수 있습니다. 이 값을 낮추면(예: 0.6~0.75) 더 느슨한 매칭을 허용하여 추적 완전성이 향상되지만, 잘못된 양성 연관과 추적 드리프트 위험이 있습니다. 객체 이동 속도와 탐지 안정성에 따라 조정하세요: 안정적인 객체에는 더 높은 값을, 빠르게 움직이는 객체에는 더 낮은 값을 사용하세요..	✅
minimum_consecutive_frames	정수	추적이 유효하다고 간주되어 출력되기 전에 객체를 연속해서 추적해야 하는 최소 프레임 수입니다. 양의 정수여야 합니다. 기본값은 1입니다(모든 추적이 즉시 유효함). 최소 이 연속 프레임 수 동안 지속된 추적만 출력에 포함됩니다. 이 값을 높이면(예: 3~5) 오탐 또는 중복 탐지로 인한 우발적 추적 생성을 방지하고, 짧게 지속되는 불필요한 추적을 걸러내지만, 더 짧은 정상 추적을 놓칠 수 있습니다. 이 값을 낮추면(예: 1) 모든 추적이 즉시 포함되어 완전성은 극대화되지만 오탐 추적이 포함될 수 있습니다. 오탐 비율에 따라 조정하세요: 오탐이 흔하면 더 높은 값을, 탐지가 신뢰할 수 있으면 더 낮은 값을 사용하세요..	✅

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

런타임 호환성

소프트 - 런타임 호스팅 서버리스, 전용 배포; 실행 원격; 입력 비디오 : 이 블록은 프로세스 메모리에서 비디오별 상태를 유지합니다(video_metadata.video_identifier로 키 지정). 상태 비저장 또는 다중 복제 HTTP 런타임에서 원격 단계 실행을 사용하면 연속 요청이 서로 다른 작업자 프로세스에서 처리될 수 있으므로, 상태가 호출 사이에 초기화되어 추적 / 카운팅 / 집계를 위한 출력은 의미가 없어집니다. 안정적인 프레임 간 결과를 위해 지속적인 WebRTC 세션에서 로컬 단계 실행을 사용하세요.

소프트 - 입력 이미지 : 이 블록은 비디오나 반복 프레임 워크플로의 시간적 문맥에 의존합니다. 정지 이미지/사진에는 추적, 비교, 집계 또는 시각화할 의미 있는 히스토리가 없으므로 이 블록은 거의 또는 전혀 이점을 제공하지 않습니다.

입력 및 출력 바인딩

사용 가능한 연결은 바인딩 유형에 따라 달라집니다. 어떤 바인딩 유형인지 확인하세요 Byte 추적기 버전 v1 을 가지고 있는지.

입력 및 출력 바인딩

• 입력

  • 메타데이터 (video_metadata): ByteTrack 초기화와 추적 상태 관리를 위해 필요한 프레임 속도(fps)와 비디오 식별자 정보가 포함된 비디오 메타데이터입니다. fps 값은 트래커 구성에 사용되며, video_identifier는 서로 다른 비디오에 대해 별도의 추적 상태를 유지하는 데 사용됩니다. 메타데이터에는 유효한 fps 정보가 포함되어야 합니다. ByteTrack은 초기화를 위해 프레임 속도가 필요합니다. 여러 비디오를 처리하는 경우 각 비디오의 메타데이터에는 별도의 추적 상태를 유지하기 위한 고유한 video_identifier가 있어야 합니다. 블록은 video_identifier를 사용하여 각 비디오의 프레임 전반에 걸쳐 지속적인 트래커를 유지합니다..

  • detections (Union[object_detection_prediction, instance_segmentation_prediction]): 현재 비디오 프레임에서 추적할 탐지 예측값(object detection 또는 instance segmentation)입니다. 블록은 이러한 탐지를 기존 추적과 연관시키거나 새 추적을 생성합니다. 일관된 추적을 유지하려면 각 프레임에 대해 순서대로 탐지를 제공해야 합니다. 여러 탐지 배치가 제공되면 추적 전에 병합됩니다. 탐지에는 바운딩 박스와 클래스 이름이 포함되어야 합니다. 추적 후 출력에는 track_id 정보가 추가된 동일한 탐지가 포함되어, 프레임 전반에서 같은 객체를 식별할 수 있습니다..

  • track_activation_threshold (0에서 1 사이의 실수): 탐지 결과에서 새 추적을 활성화하기 위한 신뢰도 임계값입니다. 0.0과 1.0 사이여야 합니다. 기본값은 0.25입니다. 이 임계값보다 높은 신뢰도의 탐지만 새 추적을 생성할 수 있습니다. 이 값을 높이면(예: 0.3~0.5) 신뢰도 높은 탐지만으로 추적을 생성하므로 추적 정확도와 안정성이 향상되지만, 신뢰도가 낮은 실제 탐지를 놓칠 수 있습니다. 이 값을 낮추면(예: 0.15~0.2) 낮은 신뢰도의 탐지도 받아들여 추적 완전성이 높아지지만, 오탐으로 인한 노이즈와 불안정성이 증가할 수 있습니다. 탐지 모델 성능에 따라 조정하세요: 탐지가 신뢰할 수 있으면 더 낮은 값을, 오탐이 흔하면 더 높은 값을 사용하세요..

  • lost_track_buffer (정수): 추적이 손실되었을 때(일치하는 탐지 없음) 추적을 유지할 프레임 수입니다. 양의 정수여야 합니다. 기본값은 30프레임입니다. 객체가 일시적으로 사라지면(가림, 놓친 탐지, 또는 프레임 밖 이탈로 인해) 추적은 손실로 간주되기 전에 이 프레임 수만큼 유지됩니다. 이 값을 높이면(예: 50~100) 가림 처리가 향상되고 짧은 탐지 공백으로 인한 추적 분할이나 소실이 크게 줄어들지만 메모리 사용량은 증가합니다. 이 값을 낮추면(예: 10~20) 메모리 사용량은 줄어들지만 짧은 가림 동안 추적이 사라질 수 있습니다. 가림 빈도에 따라 조정하세요: 가림이 자주 발생하면 더 높은 값을, 안정적인 추적 시나리오에서는 더 낮은 값을 사용하세요..

  • minimum_matching_threshold (0에서 1 사이의 실수): 탐지를 기존 추적과 매칭하기 위한 IoU(Intersection over Union, 교집합 대비 합집합) 임계값입니다. 0.0과 1.0 사이여야 합니다. 기본값은 0.8입니다. 탐지의 바운딩 박스 IoU가 이 임계값을 초과하면 추적과 연관됩니다. 이 값을 높이면(예: 0.85~0.95) 더 강한 공간적 겹침을 요구하므로 추적 정확도가 향상되지만, 객체가 빠르게 움직이거나 탐지 상자가 달라질 때 추적 분할이 발생할 수 있습니다. 이 값을 낮추면(예: 0.6~0.75) 더 느슨한 매칭을 허용하여 추적 완전성이 향상되지만, 잘못된 양성 연관과 추적 드리프트 위험이 있습니다. 객체 이동 속도와 탐지 안정성에 따라 조정하세요: 안정적인 객체에는 더 높은 값을, 빠르게 움직이는 객체에는 더 낮은 값을 사용하세요..

  • minimum_consecutive_frames (정수): 추적이 유효하다고 간주되어 출력되기 전에 객체를 연속해서 추적해야 하는 최소 프레임 수입니다. 양의 정수여야 합니다. 기본값은 1입니다(모든 추적이 즉시 유효함). 최소 이 연속 프레임 수 동안 지속된 추적만 출력에 포함됩니다. 이 값을 높이면(예: 3~5) 오탐 또는 중복 탐지로 인한 우발적 추적 생성을 방지하고, 짧게 지속되는 불필요한 추적을 걸러내지만, 더 짧은 정상 추적을 놓칠 수 있습니다. 이 값을 낮추면(예: 1) 모든 추적이 즉시 포함되어 완전성은 극대화되지만 오탐 추적이 포함될 수 있습니다. 오탐 비율에 따라 조정하세요: 오탐이 흔하면 더 높은 값을, 탐지가 신뢰할 수 있으면 더 낮은 값을 사용하세요..

• 출력

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

예시 JSON 정의

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/byte_tracker@v1",
	    "metadata": "<block_does_not_provide_example>",
	    "detections": "$steps.object_detection_model.predictions",
	    "track_activation_threshold": 0.25,
	    "lost_track_buffer": 30,
	    "minimum_matching_threshold": 0.8,
	    "minimum_consecutive_frames": 1
	}