구역 체류 시간

구역 내 객체 체류 시간을 추적합니다.

v3

하나 이상의 정의된 다각형 구역 내에서 추적된 객체가 보낸 시간을 계산 및 추적하고, 특정 영역에서의 객체 존재 시간을 측정하며(객체가 어떤 구역에든 있으면 '구역 내'로 간주되는 여러 구역 지원), 구역 포함 여부를 기준으로 탐지를 필터링하고, 객체가 구역을 벗어날 때 시간 추적을 재설정하며, 구역 기반 분석, 체류 시간 분석, 존재 모니터링 워크플로를 활성화합니다.

이 블록의 작동 방식

이 블록은 각 고유 track ID에 대한 진입 및 이탈 시간을 추적하여 각 추적 객체가 하나 이상의 정의된 다각형 구역 안에 얼마나 오래 있었는지 측정합니다. 이 블록은 여러 구역을 지원하며, 객체가 정의된 구역 중 어느 하나에라도 있으면 '구역 내'로 간주합니다. 이 블록은:

1. track ID가 포함된 추적 탐지 예측, 임베디드 비디오 메타데이터가 있는 이미지, 그리고 다각형 구역 정의(단일 구역 또는 구역 목록)를 받습니다

2. 이미지에서 비디오 메타데이터를 추출합니다:

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

   • fps, frame_number, frame_timestamp, video_identifier 및 비디오 소스 정보를 추출합니다

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

3. 탐지에 track ID가 있는지 검증합니다(tracker_id가 반드시 있어야 함):

   • 탐지가 추적 블록(예: Byte Tracker)에서 와야 합니다

   • 각 객체는 프레임 간에 유지되는 고유한 tracker_id를 가져야 합니다

   • tracker_id가 없으면 오류를 발생시킵니다

4. 구역 입력을 다각형 목록으로 정규화합니다:

   • 단일 다각형 구역 또는 다각형 구역 목록을 허용합니다

   • 일관된 처리를 위해 단일 다각형을 자동으로 목록으로 감쌉니다

   • 모든 구역에 대해 중첩 깊이와 좌표 형식을 검증합니다

   • 유연한 구역 입력 형식(단일 구역 또는 여러 구역)을 사용할 수 있습니다

5. 비디오의 다각형 구역을 초기화하거나 가져옵니다:

   • 각 고유한 구역 조합에 대해 구역 좌표로부터 PolygonZone 객체 목록을 생성합니다

   • 구역 좌표를 검증합니다(각 구역은 최소 3개 점의 목록이어야 하며, 각 점은 2개 좌표를 가져야 함)

   • OrderedDict에 구역 캐시와 함께 구역 구성을 저장합니다(최대 100개의 구역 조합)

   • 캐시 조회를 위해 video_identifier와 구역 좌표를 결합한 zone key를 사용합니다

   • 캐시가 100개 구역 조합을 초과하면 FIFO 방식으로 제거를 구현합니다

   • 구역 탐지를 위한 트리거 앵커 포인트(예: CENTER, BOTTOM_CENTER)를 구성합니다

6. 비디오의 시간 추적 상태를 초기화하거나 가져옵니다:

   • 각 track_id가 어떤 구역에 들어갔는지 추적하는 딕셔너리를 유지합니다

   • video_identifier를 사용하여 비디오별 진입 타임스탬프를 저장합니다

   • 각 비디오에 대해 별도의 추적 상태를 유지합니다

7. 시간 측정을 위한 현재 타임스탬프를 계산합니다:

   • 비디오 파일의 경우: frame_number / fps로 타임스탬프를 계산합니다

   • 스트리밍 비디오의 경우: 메타데이터의 frame_timestamp를 사용합니다

   • 지속 시간 계산을 위한 정확한 시간 측정을 제공합니다

8. 어떤 탐지가 구역 내에 있는지 확인합니다:

   • 다각형 구역 트리거를 사용하여 각 탐지를 모든 다각형 구역과 비교합니다

   • 구역 포함 여부 행렬(구역 x 탐지)을 생성합니다

   • 논리 OR 연산을 사용합니다: 객체는 어떤 구역이든 하나에 있으면 '구역 내'로 간주됩니다

   • triggering_anchor는 경계 상자의 어느 점을 확인할지 결정합니다(CENTER, BOTTOM_CENTER 등)

   • 각 탐지에 대해 어떤 구역이든 포함 여부를 나타내는 불리언을 반환합니다

9. 각 추적 객체의 시간 추적을 업데이트합니다:

   • 어떤 구역이든 진입한 객체의 경우: 아직 추적되지 않았다면 진입 타임스탬프를 기록합니다

   • 어떤 구역이든 있는 객체의 경우: 경과 시간을 current_timestamp - entry_timestamp로 계산합니다

   • 모든 구역을 벗어난 객체의 경우:

     • : reset_out_of_zone_detections가 True이면 진입 타임스탬프를 제거합니다(0으로 재설정)

     • : reset_out_of_zone_detections가 False이면 진입 타임스탬프를 유지합니다(추적 지속)

10. 구역 밖 탐지를 처리합니다:

    • remove_out_of_zone_detections가 True이면: 모든 구역 바깥의 탐지를 출력에서 필터링합니다

    • remove_out_of_zone_detections가 False이면: 구역 밖 탐지를 time = 0으로 포함합니다

11. 각 탐지에 time_in_zone 정보를 추가합니다:

    • 각 탐지에 time_in_zone 값(초 단위)을 메타데이터로 첨부합니다

    • 어떤 구역이든 있는 객체: 시간은 어떤 구역이든 머문 지속 시간을 나타냅니다

    • 모든 구역 밖의 객체: 시간은 0(재설정하지 않은 경우) 또는 정의되지 않음(제거된 경우)입니다

12. time_in_zone 정보가 포함된 탐지를 반환합니다:

    • time_in_zone 메타데이터로 강화된 추적 탐지를 출력합니다

    • remove_out_of_zone_detections 설정에 따라 필터링되거나 필터링되지 않습니다

    • 모든 원래 탐지 속성과 시간 추적 정보를 유지합니다

이 블록은 프레임 간에 지속적인 추적 상태를 유지하여, 여러 프레임에 걸쳐 어떤 구역이든 계속 머무는 객체의 누적 시간을 정확하게 측정할 수 있게 합니다. 시간은 객체가(track_id를 기준으로) 어떤 구역이든 처음 진입한 시점부터 현재 프레임까지 측정되어 실시간 지속 시간 추적을 제공합니다. 여러 구역이 제공되면 객체의 앵커 포인트가 어떤 구역이든 하나 안에 있으면 '구역 내'로 간주되어, 여러 영역을 하나의 결합된 구역처럼 추적할 수 있습니다. 구역 캐시는 FIFO 제거 방식을 사용해 각 비디오에 대한 여러 구역 구성을 효율적으로 관리하며 메모리 사용량을 제한합니다. 트리거링 앵커는 구역 탐지에 경계 상자의 어느 부분을 사용할지 결정하여, 객체 위치에 따라 서로 다른 구역 진입/이탈 동작을 가능하게 합니다.

일반적인 사용 사례

• 다중 구역 체류 시간 분석: 행동 분석을 위해 객체가 여러 영역 중 어느 곳이든 얼마나 오래 머무는지 측정합니다(예: 매장 구역 전체에서 고객 체류 시간 측정, 여러 주차 구역에서 보낸 시간 추적, 겹치는 구역에서의 시간 분석). 다중 구역 체류 시간 분석 워크플로를 활성화합니다

• 구역 기반 모니터링: 보안 및 안전을 위해 여러 정의된 영역 전반의 객체 존재를 모니터링합니다(예: 제한 구역 내 배회 감지, 여러 위험 구역의 체류 시간 모니터링, 보안 구역 전반의 존재 추적). 다중 구역 모니터링 워크플로를 활성화합니다

• 소매 분석: 소매 인사이트를 위해 여러 매장 구역에서 고객 시간을 추적합니다(예: 상품 통로 중 어느 곳이든 머문 시간 측정, 부서별 쇼핑 패턴 분석, 여러 구역의 참여도 추적). 다중 구역 소매 분석 워크플로를 활성화합니다

• 점유 관리: 공간 활용을 위해 여러 공간 중 어느 곳이든 객체가 보낸 시간을 측정합니다(예: 여러 주차장에 주차한 차량 시간 추적, 구역별 테이블 점유 측정, 여러 영역의 공간 사용 분석). 다중 구역 점유 관리 워크플로를 활성화합니다

• 안전 준수: 여러 제한 구역 또는 시간 제한 구역에서 시간 위반을 모니터링합니다(예: 위험 구역 내 장시간 체류 감지, 구역 전반의 시간 제한 위반 모니터링, 여러 영역의 안전 준수 추적). 다중 구역 안전 모니터링 워크플로를 활성화합니다

• 교통 분석: 차량이 여러 교통 구역이나 교차로 중 어느 곳이든 머문 시간을 측정합니다(예: 여러 교차로에서의 체류 시간 추적, 구역 전반의 대기열 대기 시간 측정, 여러 영역의 교통 흐름 분석). 다중 구역 교통 분석 워크플로를 활성화합니다

다른 블록에 연결하기

이 블록은 임베디드 비디오 메타데이터가 포함된 이미지, 추적 탐지, 그리고 구역 좌표를 받아 time_in_zone 메타데이터가 포함된 timed_detections를 생성합니다:

• Byte Tracker 블록 이후 추적 객체가 여러 구역에서 보낸 시간을 측정하기 위해(예: 추적 객체의 여러 구역 체류 시간 추적, 영역 전반에서 일관된 ID로 체류 시간 측정, 여러 구역의 추적 객체 존재 분석), tracking-to-time 워크플로를 활성화합니다

• 구역 정의 블록 뒤에 정의된 여러 영역에 시간 추적을 적용하기 위해(예: 여러 다각형 구역 전체의 시간 측정, 사용자 지정 다중 구역 구성에서의 지속 시간 추적, 구역 기반 영역 존재 분석), zone-to-time 워크플로를 활성화합니다

• 로직 블록 이전 Continue If와 같이 어떤 구역이든 시간에 따라 결정을 내리기 위해(예: 어떤 구역이든 임계값을 초과하면 계속, 구역 전반의 체류 시간을 기준으로 필터링, 여러 영역의 시간 위반에 대해 작업 트리거), 시간 기반 의사결정 워크플로를 활성화합니다

• 분석 블록 앞에 시간 기반 지표를 분석하기 위해(예: 체류 시간 패턴 분석, time-in-zone 데이터 처리, 지속 시간 지표 작업), 시간 분석 워크플로를 활성화합니다

• 알림 블록 앞에서 시간 위반 또는 임계값에 대해 알리기 위해(예: 장시간 체류 알림, 시간 제한 위반 통지, 시간 기반 경고 트리거), 시간 기반 알림 워크플로를 활성화합니다

• 데이터 저장 블록 앞에서 시간 지표를 기록하기 위해(예: 체류 시간 데이터 저장, time-in-zone 지표 로그 기록, 지속 시간 측정값 기록), 시간 지표 로깅 워크플로를 활성화합니다

버전 차이

v2에서 개선됨:

• 다중 구역 지원: 여러 다각형 구역에 걸친 시간 추적을 동시에 지원하며, 객체가 정의된 구역 중 어느 하나에라도 있으면 '구역 내'로 간주됩니다. 다중 구역 시간 추적 및 분석을 활성화합니다

• 유연한 구역 입력: 단일 다각형 구역 또는 다각형 구역 목록을 허용하며, 두 형식을 원활하게 처리하도록 입력을 자동으로 정규화합니다

• 구역 캐시 관리: 메모리 사용량을 제한하면서 각 비디오에 대한 여러 구역 구성을 효율적으로 관리하기 위해 FIFO 제거(max 100개 구역 조합)를 사용하는 구역 캐시를 구현합니다

• 결합된 구역 논리: 모든 구역에 걸쳐 논리 OR 연산을 사용하여, 포괄적인 존재 모니터링을 위한 단일 구역 시스템처럼 여러 영역을 추적할 수 있게 합니다

• 향상된 구역 키 시스템: 캐시 조회를 위해 결합된 구역 키(video_identifier + 구역 좌표)를 사용하여 구역 구성을 효율적으로 저장하고 검색할 수 있게 합니다

요구 사항

이 블록은 tracker_id 정보가 있는 추적 탐지를 필요로 합니다(탐지는 Byte Tracker와 같은 추적 블록에서 와야 함). 구역은 단일 다각형 또는 다각형 목록으로 정의할 수 있으며, 각 다각형은 최소 3개 점의 목록이어야 하고, 각 점은 정확히 2개 좌표(x, y)를 가진 목록 또는 튜플이어야 합니다. 이미지의 video_metadata에는 정확한 시간 측정을 위해 비디오 파일의 프레임 속도(fps) 또는 스트리밍 비디오의 프레임 타임스탬프가 포함되어야 합니다. 이 블록은 각 비디오에 대해 프레임이 순차적으로 처리되는 비디오 워크플로에서 사용해야 하므로, 프레임 간에 지속적인 추적 상태를 유지합니다. 정확한 시간 측정을 위해서는 유효한 track ID가 있는 탐지를 프레임마다 일관되게 제공해야 합니다. 여러 구역이 제공되면 객체는 어떤 구역이든 하나에 있으면 '구역 내'로 간주됩니다.

유형 식별자

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

속성

이름	유형	설명	참조
name	str	이 단계에 대한 고유 식별자를 입력하세요..	❌
zone	List[Any]	시간 측정을 위한 하나 이상의 영역을 정의하는 다각형 구역 좌표입니다. 단일 다각형 구역 또는 다각형 구역 목록일 수 있습니다. 각 구역은 최소 3개 점의 목록이어야 하며, 각 점은 정확히 2개 좌표 [x, y] 또는 (x, y)를 가진 목록 또는 튜플이어야 합니다. 좌표는 이미지 크기와 일치하는 픽셀 공간이어야 합니다. 단일 구역 예시: [(100, 100), (100, 200), (300, 200), (300, 100)]. 여러 구역 예시: [[(100, 100), (100, 200), (300, 200), (300, 100)], [(400, 400), (400, 500), (600, 500), (600, 400)]]. 객체는 triggering_anchor 포인트가 제공된 어떤 구역이든 하나 안에 있으면 '구역 내'로 간주됩니다. 구역 좌표는 검증되며 각 구역에 대해 PolygonZone 객체가 생성됩니다. 구역 구성은 FIFO 제거를 통해 캐시됩니다(최대 100개 조합)..	✅
triggering_anchor	str	객체를 '구역 내'로 간주하기 위해 탐지 경계 상자의 어느 점이 구역 안에 있어야 하는지 지정하는 점입니다. 옵션에는 'CENTER'(기본값, 경계 상자 중심), 'BOTTOM_CENTER'(하단 중앙), 'TOP_CENTER'(상단 중앙), 'CENTER_LEFT'(중앙 왼쪽), 'CENTER_RIGHT'(중앙 오른쪽), 그리고 다른 Position enum 값들이 포함됩니다. triggering_anchor는 객체 경계 상자의 어느 부분을 구역 다각형과 비교할지 결정합니다. 여러 구역이 제공되면 앵커 포인트가 어떤 구역이든 하나 안에 있으면 객체는 '구역 내'로 간주됩니다. 일반적인 구역 탐지에는 CENTER를, 지면 수준 구역(예: 발/차량 바닥 추적)에는 BOTTOM_CENTER를, 그 외에는 탐지 요구에 따라 다른 앵커를 사용하세요. 기본값은 'CENTER'입니다..	✅
remove_out_of_zone_detections	bool	True인 경우(기본값), 모든 구역 바깥에서 발견된 탐지는 필터링되어 출력에 포함되지 않습니다. 적어도 하나의 구역 안에 있는 탐지만 반환됩니다. False인 경우, 모든 탐지가 출력에 포함되며 모든 구역 바깥의 객체는 time_in_zone = 0이 됩니다. 어떤 구역이든 있는 객체만 분석하려면 True를, 구역 상태와 함께 모든 탐지를 유지하려면 False를 사용하세요. 여러 구역이 제공되면 객체는 어떤 구역이든 하나에 있으면 '구역 내'로 간주됩니다. 구역 활동에 집중한 더 깔끔한 출력을 위해 기본값은 True입니다..	✅
reset_out_of_zone_detections	bool	True인 경우(기본값), 추적 객체가 모든 구역을 벗어나면 시간 추적이 재설정됩니다(진입 타임스탬프가 지워짐). 객체가 어떤 구역이든 다시 진입하면 시간 추적은 0부터 다시 시작합니다. False인 경우, 모든 구역을 벗어난 후에도 시간 추적이 계속되며, 재진입 시 누적 시간이 유지됩니다. 어떤 구역이든 현재 연속 체류 시간을 측정하려면 True를(모든 구역을 벗어날 때 재설정), 여러 진입에 걸친 누적 시간을 측정하려면 False를 사용하세요. 여러 구역이 제공되면 시간은 객체가 모든 구역을 벗어날 때만 재설정됩니다. 연속 존재 지속 시간을 측정하기 위한 기본값은 True입니다..	✅

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

런타임 호환성

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

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

입력 및 출력 바인딩

사용 가능한 연결은 바인딩 유형에 따라 달라집니다. 어떤 바인딩 유형인지 확인하세요 구역 내 시간 버전 v3 을 가지고 있는지.

입력 및 출력 바인딩

• 입력

  • 이미지 (이미지): 시간 계산과 상태 관리에 필요한 임베디드 비디오 메타데이터(fps, frame_number, frame_timestamp, video_identifier, video source)가 포함된 현재 비디오 프레임의 입력 이미지입니다. 이 블록은 WorkflowImageData 객체에서 video_metadata를 추출합니다. fps와 frame_number는 비디오 파일에서 타임스탬프를 계산하는 데 사용됩니다(timestamp = frame_number / fps). 스트리밍 비디오의 경우 frame_timestamp가 직접 사용됩니다. video_identifier는 서로 다른 비디오에 대해 별도의 추적 상태와 구역 구성을 유지하는 데 사용됩니다. 구역 시각화와 참조에 사용됩니다. 이미지 크기는 구역 좌표를 검증하는 데 사용됩니다. 이 버전은 메타데이터를 별도의 메타데이터 필드로 요구하는 대신 이미지 객체에 임베드하여 여러 구역을 효율적인 구역 캐시 관리와 함께 지원합니다..

  • detections (Union[object_detection_prediction, instance_segmentation_prediction]): tracker_id 정보가 있는 추적 탐지 예측(객체 탐지 또는 인스턴스 분할)입니다. 탐지는 프레임 간에 유지되는 고유한 tracker_id 값을 할당하는 추적 블록(예: Byte Tracker)에서 와야 합니다. 각 탐지는 시간 추적을 활성화하기 위해 tracker_id를 가져야 합니다. 이 블록은 각 추적 객체의 time_in_zone을 해당 track_id가 어떤 구역이든 처음 진입한 시점을 기준으로 계산합니다. 객체는 앵커 포인트가 제공된 어떤 구역이든 하나 안에 있으면 '구역 내'로 간주됩니다. 출력에는 time_in_zone 메타데이터(초 단위 지속 시간)가 강화된 동일한 탐지가 포함됩니다. remove_out_of_zone_detections가 True이면 어떤 구역이든 하나 안에 있는 탐지만 출력에 포함됩니다..

  • zone (list_of_values): 시간 측정을 위한 하나 이상의 영역을 정의하는 다각형 구역 좌표입니다. 단일 다각형 구역 또는 다각형 구역 목록일 수 있습니다. 각 구역은 최소 3개 점의 목록이어야 하며, 각 점은 정확히 2개 좌표 [x, y] 또는 (x, y)를 가진 목록 또는 튜플이어야 합니다. 좌표는 이미지 크기와 일치하는 픽셀 공간이어야 합니다. 단일 구역 예시: [(100, 100), (100, 200), (300, 200), (300, 100)]. 여러 구역 예시: [[(100, 100), (100, 200), (300, 200), (300, 100)], [(400, 400), (400, 500), (600, 500), (600, 400)]]. 객체는 triggering_anchor 포인트가 제공된 어떤 구역이든 하나 안에 있으면 '구역 내'로 간주됩니다. 구역 좌표는 검증되며 각 구역에 대해 PolygonZone 객체가 생성됩니다. 구역 구성은 FIFO 제거를 통해 캐시됩니다(최대 100개 조합)..

  • triggering_anchor (string): 객체를 '구역 내'로 간주하기 위해 탐지 경계 상자의 어느 점이 구역 안에 있어야 하는지 지정하는 점입니다. 옵션에는 'CENTER'(기본값, 경계 상자 중심), 'BOTTOM_CENTER'(하단 중앙), 'TOP_CENTER'(상단 중앙), 'CENTER_LEFT'(중앙 왼쪽), 'CENTER_RIGHT'(중앙 오른쪽), 그리고 다른 Position enum 값들이 포함됩니다. triggering_anchor는 객체 경계 상자의 어느 부분을 구역 다각형과 비교할지 결정합니다. 여러 구역이 제공되면 앵커 포인트가 어떤 구역이든 하나 안에 있으면 객체는 '구역 내'로 간주됩니다. 일반적인 구역 탐지에는 CENTER를, 지면 수준 구역(예: 발/차량 바닥 추적)에는 BOTTOM_CENTER를, 그 외에는 탐지 요구에 따라 다른 앵커를 사용하세요. 기본값은 'CENTER'입니다..

  • remove_out_of_zone_detections (boolean): True인 경우(기본값), 모든 구역 바깥에서 발견된 탐지는 필터링되어 출력에 포함되지 않습니다. 적어도 하나의 구역 안에 있는 탐지만 반환됩니다. False인 경우, 모든 탐지가 출력에 포함되며 모든 구역 바깥의 객체는 time_in_zone = 0이 됩니다. 어떤 구역이든 있는 객체만 분석하려면 True를, 구역 상태와 함께 모든 탐지를 유지하려면 False를 사용하세요. 여러 구역이 제공되면 객체는 어떤 구역이든 하나에 있으면 '구역 내'로 간주됩니다. 구역 활동에 집중한 더 깔끔한 출력을 위해 기본값은 True입니다..

  • reset_out_of_zone_detections (boolean): True인 경우(기본값), 추적 객체가 모든 구역을 벗어나면 시간 추적이 재설정됩니다(진입 타임스탬프가 지워짐). 객체가 어떤 구역이든 다시 진입하면 시간 추적은 0부터 다시 시작합니다. False인 경우, 모든 구역을 벗어난 후에도 시간 추적이 계속되며, 재진입 시 누적 시간이 유지됩니다. 어떤 구역이든 현재 연속 체류 시간을 측정하려면 True를(모든 구역을 벗어날 때 재설정), 여러 진입에 걸친 누적 시간을 측정하려면 False를 사용하세요. 여러 구역이 제공되면 시간은 객체가 모든 구역을 벗어날 때만 재설정됩니다. 연속 존재 지속 시간을 측정하기 위한 기본값은 True입니다..

• 출력

  • timed_detections (Union[object_detection_prediction, instance_segmentation_prediction]): sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 예측, 다음 경우 object_detection_prediction 또는 sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 및 세그멘테이션 마스크 예측, 다음 경우 instance_segmentation_prediction.

예시 JSON 정의

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/time_in_zone@v3",
	    "image": "$inputs.image",
	    "detections": "$steps.object_detection_model.predictions",
	    "zone": [
	        [
	            100,
	            100
	        ],
	        [
	            100,
	            200
	        ],
	        [
	            300,
	            200
	        ],
	        [
	            300,
	            100
	        ]
	    ],
	    "triggering_anchor": "CENTER",
	    "remove_out_of_zone_detections": true,
	    "reset_out_of_zone_detections": true
	}

v2

정의된 다각형 구역 내에서 추적 객체가 보낸 시간을 계산 및 추적하고, 특정 영역에서의 객체 존재 시간을 측정하며, 구역 포함 여부를 기준으로 탐지를 필터링하고, 객체가 구역을 벗어날 때 시간 추적을 재설정하며, 구역 기반 분석, 체류 시간 분석, 존재 모니터링 워크플로를 활성화합니다.

이 블록의 작동 방식

이 블록은 각 고유 track ID에 대한 진입 및 이탈 시간을 추적하여 각 추적 객체가 정의된 다각형 구역 안에 얼마나 오래 있었는지 측정합니다. 이 블록은:

1. track ID가 포함된 추적 탐지 예측, 임베디드 비디오 메타데이터가 있는 이미지, 그리고 다각형 구역 정의를 받습니다

2. 이미지에서 비디오 메타데이터를 추출합니다:

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

   • fps, frame_number, frame_timestamp, video_identifier 및 비디오 소스 정보를 추출합니다

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

3. 탐지에 track ID가 있는지 검증합니다(tracker_id가 반드시 있어야 함):

   • 탐지가 추적 블록(예: Byte Tracker)에서 와야 합니다

   • 각 객체는 프레임 간에 유지되는 고유한 tracker_id를 가져야 합니다

   • tracker_id가 없으면 오류를 발생시킵니다

4. 비디오의 다각형 구역을 초기화하거나 가져옵니다:

   • 각 고유 비디오에 대해 구역 좌표로부터 PolygonZone 객체를 생성합니다

   • 구역 좌표를 검증합니다(최소 3개 점의 목록이어야 하며, 각 점은 2개 좌표를 가져야 함)

   • video_identifier를 사용하여 비디오별로 구역 구성을 저장합니다

   • 구역 탐지를 위한 트리거 앵커 포인트(예: CENTER, BOTTOM_CENTER)를 구성합니다

5. 비디오의 시간 추적 상태를 초기화하거나 가져옵니다:

   • 각 track_id가 구역에 들어갔는지 추적하는 딕셔너리를 유지합니다

   • video_identifier를 사용하여 비디오별 진입 타임스탬프를 저장합니다

   • 각 비디오에 대해 별도의 추적 상태를 유지합니다

6. 시간 측정을 위한 현재 타임스탬프를 계산합니다:

   • 비디오 파일의 경우: frame_number / fps로 타임스탬프를 계산합니다

   • 스트리밍 비디오의 경우: 메타데이터의 frame_timestamp를 사용합니다

   • 지속 시간 계산을 위한 정확한 시간 측정을 제공합니다

7. 어떤 탐지가 구역 내에 있는지 확인합니다:

   • 다각형 구역 트리거를 사용하여 각 탐지의 앵커 포인트가 구역 안에 있는지 테스트합니다

   • triggering_anchor는 경계 상자의 어느 점을 확인할지 결정합니다(CENTER, BOTTOM_CENTER 등)

   • 각 탐지에 대해 구역 포함 여부를 나타내는 불리언을 반환합니다

8. 각 추적 객체의 시간 추적을 업데이트합니다:

   • 구역에 진입하는 객체의 경우: 아직 추적되지 않았다면 진입 타임스탬프를 기록합니다

   • 구역에 있는 객체의 경우: 경과 시간을 current_timestamp - entry_timestamp로 계산합니다

   • 구역을 벗어나는 객체의 경우:

     • : reset_out_of_zone_detections가 True이면 진입 타임스탬프를 제거합니다(0으로 재설정)

     • : reset_out_of_zone_detections가 False이면 진입 타임스탬프를 유지합니다(추적 지속)

9. 구역 밖 탐지를 처리합니다:

   • remove_out_of_zone_detections가 True이면: 구역 바깥의 탐지를 출력에서 필터링합니다

   • remove_out_of_zone_detections가 False이면: 구역 밖 탐지를 time = 0으로 포함합니다

10. 각 탐지에 time_in_zone 정보를 추가합니다:

    • 각 탐지에 time_in_zone 값(초 단위)을 메타데이터로 첨부합니다

    • 구역 내 객체: 시간은 구역 내에 머문 지속 시간을 나타냅니다

    • 구역 밖 객체: 시간은 0(재설정하지 않은 경우) 또는 정의되지 않음(제거된 경우)입니다

11. time_in_zone 정보가 포함된 탐지를 반환합니다:

    • time_in_zone 메타데이터로 강화된 추적 탐지를 출력합니다

    • remove_out_of_zone_detections 설정에 따라 필터링되거나 필터링되지 않습니다

    • 모든 원래 탐지 속성과 시간 추적 정보를 유지합니다

이 블록은 프레임 간에 지속적인 추적 상태를 유지하여, 여러 프레임에 걸쳐 구역 안에 남아 있는 객체의 누적 시간을 정확하게 측정할 수 있게 합니다. 시간은 객체가(track_id를 기준으로) 처음 구역에 진입한 시점부터 현재 프레임까지 측정되어 실시간 지속 시간 추적을 제공합니다. 구역은 여러 점으로 이루어진 다각형으로 정의되어 유연한 영역 정의가 가능합니다. triggering_anchor는 구역 탐지에 경계 상자의 어느 부분을 사용할지 결정하여, 객체 위치에 따라 서로 다른 구역 진입/이탈 동작을 가능하게 합니다.

일반적인 사용 사례

• 체류 시간 분석: 행동 분석을 위해 객체가 특정 영역에 얼마나 오래 머무는지 측정합니다(예: 매장 구역에서 고객 체류 시간 측정, 주차 공간에서 보낸 시간 추적, 대기 구역의 시간 분석). 체류 시간 분석 워크플로를 활성화합니다

• 구역 기반 모니터링: 보안 및 안전을 위해 정의된 영역에서의 객체 존재를 모니터링합니다(예: 제한 구역에서의 배회 감지, 위험 구역의 체류 시간 모니터링, 보안 구역의 존재 추적). 구역 모니터링 워크플로를 활성화합니다

• 소매 분석: 소매 인사이트를 위해 서로 다른 매장 구역에서 고객 시간을 추적합니다(예: 상품 통로에서의 시간 측정, 쇼핑 패턴 분석, 부서 참여도 추적). 소매 분석 워크플로를 활성화합니다

• 점유 관리: 공간 활용을 위해 공간에서 객체가 보낸 시간을 측정합니다(예: 차량 주차 시간 추적, 테이블 점유 시간 측정, 공간 사용 패턴 분석). 점유 관리 워크플로를 활성화합니다

• 안전 준수: 제한되거나 시간 제한이 있는 구역에서의 시간 위반을 모니터링합니다(예: 위험 구역의 장시간 체류 감지, 시간 제한 위반 모니터링, 안전 준수 추적). 안전 모니터링 워크플로를 활성화합니다

• 교통 분석: 교통 구역이나 교차로에서 차량이 보낸 시간을 측정합니다(예: 교차로에서의 시간 추적, 대기열 대기 시간 측정, 교통 흐름 패턴 분석). 교통 분석 워크플로를 활성화합니다

다른 블록에 연결하기

이 블록은 임베디드 비디오 메타데이터가 포함된 이미지, 추적 탐지, 그리고 구역 좌표를 받아 time_in_zone 메타데이터가 포함된 timed_detections를 생성합니다:

• Byte Tracker 블록 이후 추적 객체의 시간 측정을 위해(예: 추적 객체의 구역 내 시간 추적, 일관된 ID로 체류 시간 측정, 추적 객체 존재 분석), tracking-to-time 워크플로를 활성화합니다

• 구역 정의 블록 뒤에 정의된 영역에 시간 추적을 적용하기 위해(예: 다각형 구역에서의 시간 측정, 사용자 지정 구역에서의 지속 시간 추적, 구역 기반 존재 분석), zone-to-time 워크플로를 활성화합니다

• 로직 블록 이전 Continue If와 같이 구역 내 시간에 따라 결정을 내리기 위해(예: 시간이 임계값을 초과하면 계속, 체류 시간을 기준으로 필터링, 시간 위반 시 작업 트리거), 시간 기반 의사결정 워크플로를 활성화합니다

• 분석 블록 앞에 시간 기반 지표를 분석하기 위해(예: 체류 시간 패턴 분석, time-in-zone 데이터 처리, 지속 시간 지표 작업), 시간 분석 워크플로를 활성화합니다

• 알림 블록 앞에서 시간 위반 또는 임계값에 대해 알리기 위해(예: 장시간 체류 알림, 시간 제한 위반 통지, 시간 기반 알림 트리거), 시간 기반 알림 워크플로를 활성화합니다

• 데이터 저장 블록 앞에서 시간 지표를 기록하기 위해(예: 체류 시간 데이터 저장, time-in-zone 지표 로그 기록, 지속 시간 측정값 기록), 시간 지표 로깅 워크플로를 활성화합니다

버전 차이

v1에서 개선됨:

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

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

• 간소화된 워크플로: 필요한 입력 수를 줄여 이미지와 메타데이터가 같은 소스에서 오는 워크플로에 더 쉽게 연결할 수 있습니다

요구 사항

이 블록은 tracker_id 정보가 있는 추적 탐지를 필요로 합니다(탐지는 Byte Tracker와 같은 추적 블록에서 와야 함). 구역은 최소 3개 점의 목록으로 정의되어야 하며, 각 점은 정확히 2개 좌표(x, y)를 가진 목록 또는 튜플이어야 합니다. 이미지의 video_metadata에는 정확한 시간 측정을 위해 비디오 파일의 프레임 속도(fps) 또는 스트리밍 비디오의 프레임 타임스탬프가 포함되어야 합니다. 이 블록은 각 비디오에 대해 프레임이 순차적으로 처리되는 비디오 워크플로에서 사용해야 하므로, 프레임 간에 지속적인 추적 상태를 유지합니다. 정확한 시간 측정을 위해서는 유효한 track ID가 있는 탐지를 프레임마다 일관되게 제공해야 합니다.

유형 식별자

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

속성

이름	유형	설명	참조
name	str	이 단계에 대한 고유 식별자를 입력하세요..	❌
zone	List[Any]	시간 측정을 위한 영역을 정의하는 다각형 구역 좌표입니다. 최소 3개 점의 목록이어야 하며, 각 점은 정확히 2개 좌표 [x, y] 또는 (x, y)를 가진 목록 또는 튜플이어야 합니다. 좌표는 이미지 크기와 일치하는 픽셀 공간이어야 합니다. 예: 사각형 구역의 경우 [(100, 100), (100, 200), (300, 200), (300, 100)]. 이 구역은 시간 추적이 수행되는 다각형 영역을 정의합니다. 객체는 triggering_anchor 포인트가 이 다각형 안에 있을 때 '구역 내'로 간주됩니다. 구역 좌표는 검증되며 각 비디오에 대해 PolygonZone 객체가 생성됩니다..	✅
triggering_anchor	str	객체를 '구역 내'로 간주하기 위해 탐지 경계 상자의 어느 점이 구역 안에 있어야 하는지 지정하는 점입니다. 옵션에는 'CENTER'(기본값, 경계 상자 중심), 'BOTTOM_CENTER'(하단 중앙), 'TOP_CENTER'(상단 중앙), 'CENTER_LEFT'(중앙 왼쪽), 'CENTER_RIGHT'(중앙 오른쪽), 그리고 다른 Position enum 값들이 포함됩니다. triggering_anchor는 객체 경계 상자의 어느 부분을 구역 다각형과 비교할지 결정합니다. 일반적인 구역 탐지에는 CENTER를, 지면 수준 구역(예: 발/차량 바닥 추적)에는 BOTTOM_CENTER를, 그 외에는 탐지 요구에 따라 다른 앵커를 사용하세요. 기본값은 'CENTER'입니다..	✅
remove_out_of_zone_detections	bool	True인 경우(기본값), 구역 바깥에서 발견된 탐지는 필터링되어 출력에 포함되지 않습니다. 구역 안에 있는 탐지만 반환됩니다. False인 경우, 모든 탐지가 출력에 포함되며 구역 바깥의 객체는 time_in_zone = 0이 됩니다. 구역 안의 객체만 분석하려면 True를, 구역 상태와 함께 모든 탐지를 유지하려면 False를 사용하세요. 구역 활동에 집중한 더 깔끔한 출력을 위해 기본값은 True입니다..	✅
reset_out_of_zone_detections	bool	True인 경우(기본값), 추적 객체가 구역을 벗어나면 시간 추적이 재설정됩니다(진입 타임스탬프가 지워짐). 객체가 구역에 다시 진입하면 시간 추적은 0부터 다시 시작합니다. False인 경우, 구역을 벗어난 후에도 시간 추적이 계속되며, 재진입 시 누적 시간이 유지됩니다. 구역 내 현재 연속 시간을 측정하려면 True를(이탈 시 재설정), 여러 진입에 걸친 누적 시간을 측정하려면 False를 사용하세요. 기본값은 연속 존재 지속 시간을 측정하기 위한 True입니다..	✅

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

런타임 호환성

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

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

입력 및 출력 바인딩

사용 가능한 연결은 바인딩 유형에 따라 달라집니다. 어떤 바인딩 유형인지 확인하세요 구역 내 시간 버전 v2 을 가지고 있는지.

입력 및 출력 바인딩

• 입력

  • 이미지 (이미지): 시간 계산과 상태 관리에 필요한 임베디드 비디오 메타데이터(fps, frame_number, frame_timestamp, video_identifier, video source)가 포함된 현재 비디오 프레임의 입력 이미지입니다. 이 블록은 WorkflowImageData 객체에서 video_metadata를 추출합니다. fps와 frame_number는 비디오 파일에서 타임스탬프를 계산하는 데 사용됩니다(timestamp = frame_number / fps). 스트리밍 비디오의 경우 frame_timestamp가 직접 사용됩니다. video_identifier는 서로 다른 비디오에 대해 별도의 추적 상태와 구역 구성을 유지하는 데 사용됩니다. 구역 시각화와 참조에 사용됩니다. 이미지 크기는 구역 좌표를 검증하는 데 사용됩니다. 이 버전은 메타데이터를 별도의 메타데이터 필드로 요구하는 대신 이미지 객체에 메타데이터를 임베드하여 입력을 단순화합니다..

  • detections (Union[object_detection_prediction, instance_segmentation_prediction]): tracker_id 정보가 있는 추적 탐지 예측(객체 탐지 또는 인스턴스 분할)입니다. 탐지는 프레임 간에 유지되는 고유한 tracker_id 값을 할당하는 추적 블록(예: Byte Tracker)에서 와야 합니다. 각 탐지는 시간 추적을 활성화하기 위해 tracker_id를 가져야 합니다. 이 블록은 각 추적 객체의 time_in_zone을 해당 track_id가 처음 구역에 진입한 시점을 기준으로 계산합니다. 출력에는 time_in_zone 메타데이터(초 단위 지속 시간)가 강화된 동일한 탐지가 포함됩니다. remove_out_of_zone_detections가 True이면 구역 안에 있는 탐지만 출력에 포함됩니다..

  • zone (list_of_values): 시간 측정을 위한 영역을 정의하는 다각형 구역 좌표입니다. 최소 3개 점의 목록이어야 하며, 각 점은 정확히 2개 좌표 [x, y] 또는 (x, y)를 가진 목록 또는 튜플이어야 합니다. 좌표는 이미지 크기와 일치하는 픽셀 공간이어야 합니다. 예: 사각형 구역의 경우 [(100, 100), (100, 200), (300, 200), (300, 100)]. 이 구역은 시간 추적이 수행되는 다각형 영역을 정의합니다. 객체는 triggering_anchor 포인트가 이 다각형 안에 있을 때 '구역 내'로 간주됩니다. 구역 좌표는 검증되며 각 비디오에 대해 PolygonZone 객체가 생성됩니다..

  • triggering_anchor (string): 객체를 '구역 내'로 간주하기 위해 탐지 경계 상자의 어느 점이 구역 안에 있어야 하는지 지정하는 점입니다. 옵션에는 'CENTER'(기본값, 경계 상자 중심), 'BOTTOM_CENTER'(하단 중앙), 'TOP_CENTER'(상단 중앙), 'CENTER_LEFT'(중앙 왼쪽), 'CENTER_RIGHT'(중앙 오른쪽), 그리고 다른 Position enum 값들이 포함됩니다. triggering_anchor는 객체 경계 상자의 어느 부분을 구역 다각형과 비교할지 결정합니다. 일반적인 구역 탐지에는 CENTER를, 지면 수준 구역(예: 발/차량 바닥 추적)에는 BOTTOM_CENTER를, 그 외에는 탐지 요구에 따라 다른 앵커를 사용하세요. 기본값은 'CENTER'입니다..

  • remove_out_of_zone_detections (boolean): True인 경우(기본값), 구역 바깥에서 발견된 탐지는 필터링되어 출력에 포함되지 않습니다. 구역 안에 있는 탐지만 반환됩니다. False인 경우, 모든 탐지가 출력에 포함되며 구역 바깥의 객체는 time_in_zone = 0이 됩니다. 구역 안의 객체만 분석하려면 True를, 구역 상태와 함께 모든 탐지를 유지하려면 False를 사용하세요. 구역 활동에 집중한 더 깔끔한 출력을 위해 기본값은 True입니다..

  • reset_out_of_zone_detections (boolean): True인 경우(기본값), 추적 객체가 구역을 벗어나면 시간 추적이 재설정됩니다(진입 타임스탬프가 지워짐). 객체가 구역에 다시 진입하면 시간 추적은 0부터 다시 시작합니다. False인 경우, 구역을 벗어난 후에도 시간 추적이 계속되며, 재진입 시 누적 시간이 유지됩니다. 구역 내 현재 연속 시간을 측정하려면 True를(이탈 시 재설정), 여러 진입에 걸친 누적 시간을 측정하려면 False를 사용하세요. 기본값은 연속 존재 지속 시간을 측정하기 위한 True입니다..

• 출력

  • timed_detections (Union[object_detection_prediction, instance_segmentation_prediction]): sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 예측, 다음 경우 object_detection_prediction 또는 sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 및 세그멘테이션 마스크 예측, 다음 경우 instance_segmentation_prediction.

예시 JSON 정의

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/time_in_zone@v2",
	    "image": "$inputs.image",
	    "detections": "$steps.object_detection_model.predictions",
	    "zone": [
	        [
	            100,
	            100
	        ],
	        [
	            100,
	            200
	        ],
	        [
	            300,
	            200
	        ],
	        [
	            300,
	            100
	        ]
	    ],
	    "triggering_anchor": "CENTER",
	    "remove_out_of_zone_detections": true,
	    "reset_out_of_zone_detections": true
	}

v1

정의된 다각형 구역 내에서 추적 객체가 보낸 시간을 계산 및 추적하고, 특정 영역에서의 객체 존재 시간을 측정하며, 구역 포함 여부를 기준으로 탐지를 필터링하고, 객체가 구역을 벗어날 때 시간 추적을 재설정하며, 구역 기반 분석, 체류 시간 분석, 존재 모니터링 워크플로를 활성화합니다.

이 블록의 작동 방식

이 블록은 각 고유 track ID에 대한 진입 및 이탈 시간을 추적하여 각 추적 객체가 정의된 다각형 구역 안에 얼마나 오래 있었는지 측정합니다. 이 블록은:

1. track ID가 포함된 추적 탐지 예측, 이미지, 비디오 메타데이터, 그리고 다각형 구역 정의를 받습니다

2. 탐지에 track ID가 있는지 검증합니다(tracker_id가 반드시 있어야 함):

   • 탐지가 추적 블록(예: Byte Tracker)에서 와야 합니다

   • 각 객체는 프레임 간에 유지되는 고유한 tracker_id를 가져야 합니다

   • tracker_id가 없으면 오류를 발생시킵니다

3. 비디오의 다각형 구역을 초기화하거나 가져옵니다:

   • 각 고유 비디오에 대해 구역 좌표로부터 PolygonZone 객체를 생성합니다

   • 구역 좌표를 검증합니다(최소 3개 점의 목록이어야 하며, 각 점은 2개 좌표를 가져야 함)

   • video_identifier를 사용하여 비디오별로 구역 구성을 저장합니다

   • 구역 탐지를 위한 트리거 앵커 포인트(예: CENTER, BOTTOM_CENTER)를 구성합니다

4. 비디오의 시간 추적 상태를 초기화하거나 가져옵니다:

   • 각 track_id가 구역에 들어갔는지 추적하는 딕셔너리를 유지합니다

   • video_identifier를 사용하여 비디오별 진입 타임스탬프를 저장합니다

   • 각 비디오에 대해 별도의 추적 상태를 유지합니다

5. 시간 측정을 위한 현재 타임스탬프를 계산합니다:

   • 비디오 파일의 경우: frame_number / fps로 타임스탬프를 계산합니다

   • 스트리밍 비디오의 경우: 메타데이터의 frame_timestamp를 사용합니다

   • 지속 시간 계산을 위한 정확한 시간 측정을 제공합니다

6. 어떤 탐지가 구역 내에 있는지 확인합니다:

   • 다각형 구역 트리거를 사용하여 각 탐지의 앵커 포인트가 구역 안에 있는지 테스트합니다

   • triggering_anchor는 경계 상자의 어느 점을 확인할지 결정합니다(CENTER, BOTTOM_CENTER 등)

   • 각 탐지에 대해 구역 포함 여부를 나타내는 불리언을 반환합니다

7. 각 추적 객체의 시간 추적을 업데이트합니다:

   • 구역에 진입하는 객체의 경우: 아직 추적되지 않았다면 진입 타임스탬프를 기록합니다

   • 구역에 있는 객체의 경우: 경과 시간을 current_timestamp - entry_timestamp로 계산합니다

   • 구역을 벗어나는 객체의 경우:

     • : reset_out_of_zone_detections가 True이면 진입 타임스탬프를 제거합니다(0으로 재설정)

     • : reset_out_of_zone_detections가 False이면 진입 타임스탬프를 유지합니다(추적 지속)

8. 구역 밖 탐지를 처리합니다:

   • remove_out_of_zone_detections가 True이면: 구역 바깥의 탐지를 출력에서 필터링합니다

   • remove_out_of_zone_detections가 False이면: 구역 밖 탐지를 time = 0으로 포함합니다

9. 각 탐지에 time_in_zone 정보를 추가합니다:

   • 각 탐지에 time_in_zone 값(초 단위)을 메타데이터로 첨부합니다

   • 구역 내 객체: 시간은 구역 내에 머문 지속 시간을 나타냅니다

   • 구역 밖 객체: 시간은 0(재설정하지 않은 경우) 또는 정의되지 않음(제거된 경우)입니다

10. time_in_zone 정보가 포함된 탐지를 반환합니다:

    • time_in_zone 메타데이터로 강화된 추적 탐지를 출력합니다

    • remove_out_of_zone_detections 설정에 따라 필터링되거나 필터링되지 않습니다

    • 모든 원래 탐지 속성과 시간 추적 정보를 유지합니다

이 블록은 프레임 간에 지속적인 추적 상태를 유지하여, 여러 프레임에 걸쳐 구역 안에 남아 있는 객체의 누적 시간을 정확하게 측정할 수 있게 합니다. 시간은 객체가(track_id를 기준으로) 처음 구역에 진입한 시점부터 현재 프레임까지 측정되어 실시간 지속 시간 추적을 제공합니다. 구역은 여러 점으로 이루어진 다각형으로 정의되어 유연한 영역 정의가 가능합니다. triggering_anchor는 구역 탐지에 경계 상자의 어느 부분을 사용할지 결정하여, 객체 위치에 따라 서로 다른 구역 진입/이탈 동작을 가능하게 합니다.

일반적인 사용 사례

• 체류 시간 분석: 행동 분석을 위해 객체가 특정 영역에 얼마나 오래 머무는지 측정합니다(예: 매장 구역에서 고객 체류 시간 측정, 주차 공간에서 보낸 시간 추적, 대기 구역의 시간 분석). 체류 시간 분석 워크플로를 활성화합니다

• 구역 기반 모니터링: 보안 및 안전을 위해 정의된 영역에서의 객체 존재를 모니터링합니다(예: 제한 구역에서의 배회 감지, 위험 구역의 체류 시간 모니터링, 보안 구역의 존재 추적). 구역 모니터링 워크플로를 활성화합니다

• 소매 분석: 소매 인사이트를 위해 서로 다른 매장 구역에서 고객 시간을 추적합니다(예: 상품 통로에서의 시간 측정, 쇼핑 패턴 분석, 부서 참여도 추적). 소매 분석 워크플로를 활성화합니다

• 점유 관리: 공간 활용을 위해 공간에서 객체가 보낸 시간을 측정합니다(예: 차량 주차 시간 추적, 테이블 점유 시간 측정, 공간 사용 패턴 분석). 점유 관리 워크플로를 활성화합니다

• 안전 준수: 제한되거나 시간 제한이 있는 구역에서의 시간 위반을 모니터링합니다(예: 위험 구역의 장시간 체류 감지, 시간 제한 위반 모니터링, 안전 준수 추적). 안전 모니터링 워크플로를 활성화합니다

• 교통 분석: 교통 구역이나 교차로에서 차량이 보낸 시간을 측정합니다(예: 교차로에서의 시간 추적, 대기열 대기 시간 측정, 교통 흐름 패턴 분석). 교통 분석 워크플로를 활성화합니다

다른 블록에 연결하기

이 블록은 추적 탐지, 이미지, 비디오 메타데이터, 그리고 구역 좌표를 받아 time_in_zone 메타데이터가 포함된 timed_detections를 생성합니다:

• Byte Tracker 블록 이후 추적 객체의 시간 측정을 위해(예: 추적 객체의 구역 내 시간 추적, 일관된 ID로 체류 시간 측정, 추적 객체 존재 분석), tracking-to-time 워크플로를 활성화합니다

• 구역 정의 블록 뒤에 정의된 영역에 시간 추적을 적용하기 위해(예: 다각형 구역에서의 시간 측정, 사용자 지정 구역에서의 지속 시간 추적, 구역 기반 존재 분석), zone-to-time 워크플로를 활성화합니다

• 로직 블록 이전 Continue If와 같이 구역 내 시간에 따라 결정을 내리기 위해(예: 시간이 임계값을 초과하면 계속, 체류 시간을 기준으로 필터링, 시간 위반 시 작업 트리거), 시간 기반 의사결정 워크플로를 활성화합니다

• 분석 블록 앞에 시간 기반 지표를 분석하기 위해(예: 체류 시간 패턴 분석, time-in-zone 데이터 처리, 지속 시간 지표 작업), 시간 분석 워크플로를 활성화합니다

• 알림 블록 앞에서 시간 위반 또는 임계값에 대해 알리기 위해(예: 장시간 체류 알림, 시간 제한 위반 통지, 시간 기반 알림 트리거), 시간 기반 알림 워크플로를 활성화합니다

• 데이터 저장 블록 앞에서 시간 지표를 기록하기 위해(예: 체류 시간 데이터 저장, time-in-zone 지표 로그 기록, 지속 시간 측정값 기록), 시간 지표 로깅 워크플로를 활성화합니다

요구 사항

이 블록은 tracker_id 정보가 있는 추적 탐지를 필요로 합니다(탐지는 Byte Tracker와 같은 추적 블록에서 와야 함). 구역은 최소 3개 점의 목록으로 정의되어야 하며, 각 점은 정확히 2개 좌표(x, y)를 가진 목록 또는 튜플이어야 합니다. 정확한 시간 측정을 위해 블록은 비디오 파일의 경우 프레임 속도(fps) 또는 스트리밍 비디오의 경우 프레임 타임스탬프를 포함한 비디오 메타데이터를 필요로 합니다. 이 블록은 각 비디오에 대해 프레임이 순차적으로 처리되는 비디오 워크플로에서 사용해야 하므로, 프레임 간에 지속적인 추적 상태를 유지합니다. 정확한 시간 측정을 위해서는 유효한 track ID가 있는 탐지를 프레임마다 일관되게 제공해야 합니다.

유형 식별자

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

속성

이름	유형	설명	참조
name	str	이 단계에 대한 고유 식별자를 입력하세요..	❌
zone	List[Any]	시간 측정을 위한 영역을 정의하는 다각형 구역 좌표입니다. 최소 3개 점의 목록이어야 하며, 각 점은 정확히 2개 좌표 [x, y] 또는 (x, y)를 가진 목록 또는 튜플이어야 합니다. 좌표는 이미지 크기와 일치하는 픽셀 공간이어야 합니다. 예: 사각형 구역의 경우 [[x1, y1], [x2, y2], [x3, y3], [x4, y4]]. 이 구역은 시간 추적이 수행되는 다각형 영역을 정의합니다. 객체는 triggering_anchor 포인트가 이 다각형 안에 있을 때 '구역 내'로 간주됩니다. 구역 좌표는 검증되며 각 비디오에 대해 PolygonZone 객체가 생성됩니다..	✅
triggering_anchor	str	객체를 '구역 내'로 간주하기 위해 탐지 경계 상자의 어느 점이 구역 안에 있어야 하는지 지정하는 점입니다. 옵션에는 'CENTER'(기본값, 경계 상자 중심), 'BOTTOM_CENTER'(하단 중앙), 'TOP_CENTER'(상단 중앙), 'CENTER_LEFT'(중앙 왼쪽), 'CENTER_RIGHT'(중앙 오른쪽), 그리고 다른 Position enum 값들이 포함됩니다. triggering_anchor는 객체 경계 상자의 어느 부분을 구역 다각형과 비교할지 결정합니다. 일반적인 구역 탐지에는 CENTER를, 지면 수준 구역(예: 발/차량 바닥 추적)에는 BOTTOM_CENTER를, 그 외에는 탐지 요구에 따라 다른 앵커를 사용하세요. 기본값은 'CENTER'입니다..	✅
remove_out_of_zone_detections	bool	True인 경우(기본값), 구역 바깥에서 발견된 탐지는 필터링되어 출력에 포함되지 않습니다. 구역 안에 있는 탐지만 반환됩니다. False인 경우, 모든 탐지가 출력에 포함되며 구역 바깥의 객체는 time_in_zone = 0이 됩니다. 구역 안의 객체만 분석하려면 True를, 구역 상태와 함께 모든 탐지를 유지하려면 False를 사용하세요. 구역 활동에 집중한 더 깔끔한 출력을 위해 기본값은 True입니다..	✅
reset_out_of_zone_detections	bool	True인 경우(기본값), 추적 객체가 구역을 벗어나면 시간 추적이 재설정됩니다(진입 타임스탬프가 지워짐). 객체가 구역에 다시 진입하면 시간 추적은 0부터 다시 시작합니다. False인 경우, 구역을 벗어난 후에도 시간 추적이 계속되며, 재진입 시 누적 시간이 유지됩니다. 구역 내 현재 연속 시간을 측정하려면 True를(이탈 시 재설정), 여러 진입에 걸친 누적 시간을 측정하려면 False를 사용하세요. 기본값은 연속 존재 지속 시간을 측정하기 위한 True입니다..	✅

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

런타임 호환성

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

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

입력 및 출력 바인딩

사용 가능한 연결은 바인딩 유형에 따라 달라집니다. 어떤 바인딩 유형인지 확인하세요 구역 내 시간 버전 v1 을 가지고 있는지.

입력 및 출력 바인딩

• 입력

  • 이미지 (이미지): 현재 비디오 프레임의 입력 이미지입니다. 구역 시각화와 참조에 사용됩니다. 이 블록은 이미지 크기를 사용하여 구역 좌표를 검증합니다. 프레임 타임스탬프가 필요한 경우 이미지 메타데이터가 시간 계산에 사용될 수 있습니다..

  • 메타데이터 (video_metadata): 시간 계산과 상태 관리에 필요한 프레임 속도(fps), 프레임 번호, 프레임 타임스탬프, 비디오 식별자, 비디오 소스 정보를 포함한 비디오 메타데이터입니다. fps와 frame_number는 비디오 파일에서 타임스탬프를 계산하는 데 사용됩니다(timestamp = frame_number / fps). 스트리밍 비디오의 경우 frame_timestamp가 직접 사용됩니다. video_identifier는 서로 다른 비디오에 대해 별도의 추적 상태와 구역 구성을 유지하는 데 사용됩니다. 정확한 시간 측정을 위해 메타데이터에는 비디오 파일의 유효한 fps 또는 스트림의 frame_timestamp가 포함되어야 합니다..

  • detections (Union[object_detection_prediction, instance_segmentation_prediction]): tracker_id 정보가 있는 추적 탐지 예측(객체 탐지 또는 인스턴스 분할)입니다. 탐지는 프레임 간에 유지되는 고유한 tracker_id 값을 할당하는 추적 블록(예: Byte Tracker)에서 와야 합니다. 각 탐지는 시간 추적을 활성화하기 위해 tracker_id를 가져야 합니다. 이 블록은 각 추적 객체의 time_in_zone을 해당 track_id가 처음 구역에 진입한 시점을 기준으로 계산합니다. 출력에는 time_in_zone 메타데이터(초 단위 지속 시간)가 강화된 동일한 탐지가 포함됩니다. remove_out_of_zone_detections가 True이면 구역 안에 있는 탐지만 출력에 포함됩니다..

  • zone (list_of_values): 시간 측정을 위한 영역을 정의하는 다각형 구역 좌표입니다. 최소 3개 점의 목록이어야 하며, 각 점은 정확히 2개 좌표 [x, y] 또는 (x, y)를 가진 목록 또는 튜플이어야 합니다. 좌표는 이미지 크기와 일치하는 픽셀 공간이어야 합니다. 예: 사각형 구역의 경우 [[x1, y1], [x2, y2], [x3, y3], [x4, y4]]. 이 구역은 시간 추적이 수행되는 다각형 영역을 정의합니다. 객체는 triggering_anchor 포인트가 이 다각형 안에 있을 때 '구역 내'로 간주됩니다. 구역 좌표는 검증되며 각 비디오에 대해 PolygonZone 객체가 생성됩니다..

  • triggering_anchor (string): 객체를 '구역 내'로 간주하기 위해 탐지 경계 상자의 어느 점이 구역 안에 있어야 하는지 지정하는 점입니다. 옵션에는 'CENTER'(기본값, 경계 상자 중심), 'BOTTOM_CENTER'(하단 중앙), 'TOP_CENTER'(상단 중앙), 'CENTER_LEFT'(중앙 왼쪽), 'CENTER_RIGHT'(중앙 오른쪽), 그리고 다른 Position enum 값들이 포함됩니다. triggering_anchor는 객체 경계 상자의 어느 부분을 구역 다각형과 비교할지 결정합니다. 일반적인 구역 탐지에는 CENTER를, 지면 수준 구역(예: 발/차량 바닥 추적)에는 BOTTOM_CENTER를, 그 외에는 탐지 요구에 따라 다른 앵커를 사용하세요. 기본값은 'CENTER'입니다..

  • remove_out_of_zone_detections (boolean): True인 경우(기본값), 구역 바깥에서 발견된 탐지는 필터링되어 출력에 포함되지 않습니다. 구역 안에 있는 탐지만 반환됩니다. False인 경우, 모든 탐지가 출력에 포함되며 구역 바깥의 객체는 time_in_zone = 0이 됩니다. 구역 안의 객체만 분석하려면 True를, 구역 상태와 함께 모든 탐지를 유지하려면 False를 사용하세요. 구역 활동에 집중한 더 깔끔한 출력을 위해 기본값은 True입니다..

  • reset_out_of_zone_detections (boolean): True인 경우(기본값), 추적 객체가 구역을 벗어나면 시간 추적이 재설정됩니다(진입 타임스탬프가 지워짐). 객체가 구역에 다시 진입하면 시간 추적은 0부터 다시 시작합니다. False인 경우, 구역을 벗어난 후에도 시간 추적이 계속되며, 재진입 시 누적 시간이 유지됩니다. 구역 내 현재 연속 시간을 측정하려면 True를(이탈 시 재설정), 여러 진입에 걸친 누적 시간을 측정하려면 False를 사용하세요. 기본값은 연속 존재 지속 시간을 측정하기 위한 True입니다..

• 출력

  • timed_detections (Union[object_detection_prediction, instance_segmentation_prediction]): sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 예측, 다음 경우 object_detection_prediction 또는 sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 및 세그멘테이션 마스크 예측, 다음 경우 instance_segmentation_prediction.

예시 JSON 정의

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/time_in_zone@v1",
	    "image": "$inputs.image",
	    "metadata": "<block_does_not_provide_example>",
	    "detections": "$steps.object_detection_model.predictions",
	    "zone": "$inputs.zones",
	    "triggering_anchor": "CENTER",
	    "remove_out_of_zone_detections": true,
	    "reset_out_of_zone_detections": true
	}