속도

부드럽게 하기와 단위 변환을 통해 추적 객체의 속도와 속력을 계산합니다.

시간에 따른 객체 중심의 변위를 측정하고, 지수 이동 평균 평활화를 적용해 노이즈를 줄이며, 픽셀/초 단위 측정을 초당 미터로 변환함으로써 교통 속도 모니터링, 이동 분석, 행동 추적, 성능 측정 워크플로에서 추적된 객체의 속도와 속력을 계산합니다.

이 블록의 작동 방식

이 블록은 비디오 프레임 전반에서 객체의 위치를 추적하여 객체가 얼마나 빠르게 이동하는지 측정합니다. 이 블록은:

1. 고유한 tracker ID가 있는 추적된 탐지 예측과 비디오 메타데이터가 포함된 이미지를 받습니다

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

   • frame 타임스탬프 또는 프레임 번호와 프레임 속도(fps)를 얻기 위해 video_metadata에 접근합니다

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

   • 비디오 파일에서는 frame_number/fps를, 스트림에서는 frame_timestamp를 사용하여 현재 타임스탬프를 결정합니다

3. 탐지 결과에 tracker ID가 있는지 검증합니다(프레임 간 객체 움직임 추적에 필요함)

4. 객체 중심 위치를 계산합니다:

   • 현재 프레임에서 각 바운딩 박스의 중심점(x, y)을 계산합니다

   • 바운딩 박스 좌표를 사용해 기하학적 중심을 찾습니다

5. 추적 상태를 가져오거나 초기화합니다:

   • 비디오별로 각 tracker_id의 이전 위치와 타임스탬프를 유지합니다

   • 비디오별로 각 tracker_id의 평활화된 속도 이력을 저장합니다

   • 처음 등장한 객체에 대한 새 추적 항목을 생성합니다

6. 각 추적된 객체의 속도와 속력을 계산합니다:

   • 이전 위치가 있는 객체의 경우: 현재 프레임과 이전 프레임 사이의 변위(위치 변화)와 시간 델타(시간 변화)를 계산합니다

   • 속도: 변위를 시간 델타로 나누어 속도 벡터를 계산합니다(픽셀/초)

   • 속력: 속도를 속도 벡터의 크기(길이)로 계산합니다(방향과 무관한 총 픽셀/초)

   • 새 객체의 경우: 속도와 속력을 0으로 설정합니다(아직 이동 데이터가 없음)

7. 지수 이동 평균 평활화를 적용합니다:

   • 구성 가능한 평활화 계수(alpha)를 사용한 지수 이동 평균으로 속도 측정값을 평활화합니다

   • 탐지 변동으로 인한 속도 계산의 노이즈와 지터를 줄입니다

   • alpha 값이 낮을수록 더 많이 평활화됩니다(변화에 더 느리게 반응), alpha 값이 높을수록 평활화가 덜 적용됩니다(변화에 더 빠르게 반응)

   • 각 객체의 평활화된 속도와 평활화된 속력을 계산합니다

8. 단위를 초당 미터로 변환합니다:

   • 픽셀 기반 속도와 속력을 pixels_per_meter 변환 계수로 나눕니다

   • 모든 측정값(velocity, speed, smoothed_velocity, smoothed_speed)을 실제 단위로 변환합니다

   • 실제 속도 측정값(예: km/h, mph)과 비교할 수 있게 합니다

9. 탐지 메타데이터에 속도 데이터를 저장합니다:

   • 각 탐지에 네 가지 속도 지표를 추가합니다: velocity(m/s), speed(m/s), smoothed_velocity(m/s), smoothed_speed(m/s)

   • 속도는 이동의 방향과 크기를 나타내는 2차원 벡터 [vx, vy]입니다

   • 속력은 방향과 무관한 총 속도를 나타내는 스칼라 값입니다

   • 모든 측정값은 후속 사용을 위해 detections.data에 저장됩니다

10. 다음 프레임을 위해 추적 상태를 업데이트합니다:

    • 추적된 모든 객체의 현재 위치와 타임스탬프를 저장합니다

    • 다음 프레임의 평활화 계산을 위해 평활화된 속도를 저장합니다

11. 속도 정보가 추가된 탐지 결과를 반환합니다:

    • 추가된 속도 메타데이터와 함께 동일한 탐지 객체를 출력합니다

    • 이제 각 탐지에는 메타데이터에 속도와 속력 데이터가 포함됩니다

속도는 시간에 따른 객체 중심(바운딩 박스 중심)의 변위를 기반으로 계산됩니다. 이 블록은 각 비디오마다 별도의 추적 상태를 유지하므로 여러 비디오 스트림에 걸쳐 속도를 계산할 수 있습니다. 원근 왜곡과 카메라 배치 때문에 계산된 속도는 프레임 내에서 객체가 나타나는 위치에 따라 달라질 수 있습니다. 카메라에 더 가깝거나 깊이가 다른 객체는 같은 실제 속도에 대해서도 픽셀/초 값이 다를 수 있습니다. 평활화는 탐지 부정확성과 프레임 간 변동으로 인한 노이즈를 줄이는 데 도움이 됩니다.

일반적인 사용 사례

• 교통 속도 모니터링: 도로와 고속도로에서 차량 속도를 측정합니다(예: 교통 속도 모니터링, 과속 위반 감지, 교통 흐름률 분석). 이를 통해 교통 단속 및 분석 워크플로를 지원합니다

• 스포츠 성과 분석: 스포츠 활동 중 선수의 움직임과 속도를 추적합니다(예: 선수 속도 측정, 스프린트 성과 분석, 이동 패턴 추적). 이를 통해 스포츠 분석 워크플로를 지원합니다

• 보안 및 감시: 보안 시나리오에서 사람이나 객체의 이동 속도를 모니터링합니다(예: 달리기 또는 의심스러운 급속 이동 감지, 군중 흐름 속도 모니터링, 객체 이동 속도 추적). 이를 통해 보안 모니터링 워크플로를 지원합니다

• 소매 분석: 소매 공간에서 고객의 이동 패턴과 보행 속도를 분석합니다(예: 고객 흐름률 측정, 쇼핑 행동 패턴 분석, 이동 효율성 추적). 이를 통해 소매 행동 분석 워크플로를 지원합니다

• 야생동물 행동 연구: 자연 서식지에서 동물의 이동 속도와 패턴을 추적합니다(예: 동물 속도 측정, 이동 경로 분석, 이동 행동 연구). 이를 통해 야생동물 연구 워크플로를 지원합니다

• 산업 모니터링: 산업 환경에서 차량, 장비 또는 제품의 속도를 모니터링합니다(예: 컨베이어 속도 추적, 시설 내 차량 속도 측정, 생산 라인 이동 속도 모니터링). 이를 통해 산업 자동화 워크플로를 지원합니다

다른 블록에 연결하기

이 블록은 추적된 탐지 결과와 비디오 메타데이터가 포함된 이미지를 받아, 속도 메타데이터가 추가된 탐지 결과를 생성합니다:

• Byte Tracker 블록 이후 추적된 객체의 속도를 계산하기 위해(예: 추적된 차량의 속도 측정, 추적된 사람의 이동 분석, 추적된 객체 속도 모니터링), 추적에서 속도 변환 워크플로를 지원합니다

• 객체 탐지 또는 인스턴스 분할 블록 이후 이동 속도를 측정하기 위해 추적 기능을 활성화한 상태에서(예: 차량 속도 계산, 사람 이동 속도 추적, 객체 속도 모니터링), 탐지에서 속도 변환 워크플로를 지원합니다

• 시각화 블록 이전 속도 정보를 표시하기 위해(예: 속도 오버레이 시각화, 속도 벡터 표시, 이동 속도 주석 표시), 속도 시각화 워크플로를 지원합니다

• 로직 블록 이전 Continue If와 같은 블록으로 속도 임계값을 기반으로 결정을 내리기 위해(예: 속도가 제한을 초과하면 계속, 속도 범위에 따라 필터링, 속도 위반 시 동작 트리거), 속도 기반 의사결정 워크플로를 지원합니다

• 알림 블록 앞에서 속도 위반이나 임계값 이벤트를 알리기 위해(예: 과속 위반 알림, 급속 이동 알림, 속도 기반 경고 트리거), 속도 기반 알림 워크플로를 지원합니다

• 데이터 저장 블록 앞에서 속도 측정값을 기록하기 위해(예: 속도 데이터 로그, 속도 통계 저장, 이동 메트릭 기록), 속도 데이터 로깅 워크플로를 지원합니다

요구 사항

이 블록은 tracker_id 정보가 있는 추적된 탐지 결과가 필요합니다(탐지 결과는 Byte Tracker와 같은 추적 블록에서 와야 합니다). 이미지의 video_metadata에는 정확한 시간 델타를 계산하기 위해 비디오 파일의 프레임 속도(fps) 또는 스트리밍 비디오의 프레임 타임스탬프가 포함되어야 합니다. 이 블록은 video_identifier를 사용해 각 비디오별로 프레임 간 지속적인 추적 상태를 유지하므로, 프레임이 순차적으로 처리되는 비디오 워크플로에서 사용해야 합니다. 정확한 속도 측정을 위해서는 유효한 tracker ID와 함께 프레임 전반에 걸쳐 일관되게 탐지 결과가 제공되어야 합니다. pixels_per_meter 변환 계수는 실제 속도 측정의 정확도를 위해 카메라 설정과 장면 기하에 맞게 보정되어야 합니다. 원근 왜곡으로 인해 프레임 내 객체 위치에 따라 속도 정확도가 달라질 수 있습니다.

유형 식별자

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

속성

이름	유형	설명	참조
name	str	이 단계에 대한 고유 식별자를 입력하세요..	❌
smoothing_alpha	float	지수 이동 평균의 평활화 계수(alpha)이며, 범위는 0 < alpha <= 1입니다. 속도 측정값에 얼마나 많은 평활화를 적용할지 제어합니다. 값이 낮을수록(0에 가까울수록) 더 많이 평활화되어 변화에 더 느리게 반응하고 노이즈가 적습니다. 값이 높을수록(1에 가까울수록) 평활화가 덜 적용되어 변화에 더 빠르게 반응하고 노이즈가 많습니다. 기본값 0.5는 평활성과 반응성의 균형을 맞춥니다..	✅
pixels_per_meter	float	실제 속도 계산을 위한 픽셀에서 미터로의 변환 계수입니다. 픽셀/초 단위의 속도 측정값을 이 값으로 나누어 초당 미터로 변환합니다. 0보다 커야 합니다. 정확한 실제 속도를 얻으려면 카메라 높이, 각도, 장면 기하에 맞게 보정하세요. 예: 1픽셀 = 0.01미터(1cm)라면 0.01을 사용합니다. 기본값 1.0은 변환이 없음을 의미합니다(결과는 픽셀/초)..	✅

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

런타임 호환성

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

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

입력 및 출력 바인딩

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

입력 및 출력 바인딩

• 입력

  • 이미지 (이미지): 비디오 메타데이터가 포함된 이미지. video_metadata에는 fps, frame_number, frame_timestamp, video_identifier가 포함됩니다. 시간 델타를 계산하고 서로 다른 비디오에 대해 별도의 속도 추적 상태를 유지하는 데 필요합니다..

  • detections (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction]): 추적 블록의 tracker_id 정보를 포함해야 하는 추적된 객체 탐지 또는 인스턴스 분할 예측 결과입니다. 속도는 시간에 따른 바운딩 박스 중심의 변위를 기반으로 계산됩니다. 출력 탐지 결과에는 탐지 메타데이터에 velocity(m/s 벡터), speed(m/s 스칼라), smoothed_velocity(m/s 벡터), smoothed_speed(m/s 스칼라)가 포함됩니다..

  • smoothing_alpha (float): 지수 이동 평균의 평활화 계수(alpha)이며, 범위는 0 < alpha <= 1입니다. 속도 측정값에 얼마나 많은 평활화를 적용할지 제어합니다. 값이 낮을수록(0에 가까울수록) 더 많이 평활화되어 변화에 더 느리게 반응하고 노이즈가 적습니다. 값이 높을수록(1에 가까울수록) 평활화가 덜 적용되어 변화에 더 빠르게 반응하고 노이즈가 많습니다. 기본값 0.5는 평활성과 반응성의 균형을 맞춥니다..

  • pixels_per_meter (float): 실제 속도 계산을 위한 픽셀에서 미터로의 변환 계수입니다. 픽셀/초 단위의 속도 측정값을 이 값으로 나누어 초당 미터로 변환합니다. 0보다 커야 합니다. 정확한 실제 속도를 얻으려면 카메라 높이, 각도, 장면 기하에 맞게 보정하세요. 예: 1픽셀 = 0.01미터(1cm)라면 0.01을 사용합니다. 기본값 1.0은 변환이 없음을 의미합니다(결과는 픽셀/초)..

• 출력

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

예시 JSON 정의

{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/velocity@v1",
	    "image": "<block_does_not_provide_example>",
	    "detections": "$steps.object_detection_model.predictions",
	    "smoothing_alpha": 0.5,
	    "pixels_per_meter": 0.01
	}