PTZ 추적(ONVIF)
ONVIF 호환 PTZ 카메라를 제어해 객체를 따라가게 합니다.
감지된 객체를 자동으로 따라가고, 프리셋 위치로 이동하며, 감시, 보안 모니터링, 자동화된 카메라 제어 워크플로에서 PID 제어를 사용해 부드러운 추적을 유지하도록 ONVIF 호환 PTZ(Pan-Tilt-Zoom) 카메라를 제어합니다.
이 블록의 작동 방식
이 블록은 ONVIF 프로토콜을 통해 PTZ 카메라를 제어하여 객체를 실시간으로 자동 추적하고 따라갑니다. 이 블록은:
상위 블록에서 객체 감지 또는 인스턴스 분할 예측을 수신합니다
IP 주소, 포트, 사용자 이름, 비밀번호 자격 증명을 사용하여 ONVIF 호환 PTZ 카메라에 연결합니다
이동 모드(Follow 또는 Go To Preset)를 결정합니다:
Follow 모드의 경우:
추적할 대상 객체를 선택합니다: 가장 높은 신뢰도의 감지 또는 특정 추적 객체(트래커 ID가 있는 경우)
객체의 바운딩 박스 중심과 프레임 중심을 비교하여 위치 오차를 계산합니다
PID(비례-적분-미분) 제어를 사용하여 부드러운 이동 명령을 계산합니다:
비례(Kp): 현재 위치 오차에 반응합니다
적분(Ki): 시간에 따른 정상 상태 오차를 보정합니다
미분(Kd): 미래 오차를 예측하고 진동을 완화합니다
이동 명령을 카메라의 속도 한계에 맞게 정규화하고, 명령 폭주를 방지하기 위해 전송 속도 제한을 적용합니다
ONVIF ContinuousMove 서비스를 통해 카메라에 연속 이동 명령을 보냅니다
헌팅 동작을 방지하기 위해 데드 존(카메라가 움직임을 멈추는 중앙 주변 영역)을 모니터링합니다
객체가 중앙에 오면 선택적으로 줌을 사용해, 프레임을 채우도록 줌 속도를 조정합니다
객체가 사라지거나 추적이 재설정될 때까지 트래커 ID를 사용하여 특정 객체의 추적을 유지합니다
감지된 객체가 없을 때 설정 가능한 유휴 기간 후 자동으로 프리셋 위치로 이동합니다
Go To Preset 모드의 경우:
ONVIF GotoPreset 서비스를 사용하여 카메라를 미리 정의된 프리셋 위치로 이동합니다
카메라가 프리셋 기능을 지원하고 프리셋이 구성되어 있어야 합니다
설정에 지정된 프리셋 이름을 사용합니다
별도의 이벤트 루프를 사용하여 카메라 통신을 비동기적으로 처리해 워크플로 실행이 차단되지 않도록 합니다
탐색 상태, 추적 중인 객체 ID, 줌 상태, 이동 기록을 포함한 카메라 상태를 관리합니다
두 개의 출력을 반환합니다:
predictions: 추적 중인 감지 결과(따라가는 객체가 없으면 비어 있음)
탐색 중: 카메라가 현재 움직이거나 객체를 탐색 중인지 나타내는 불리언
이 블록은 PID 제어를 사용하여 객체 중심과 프레임 중심 사이의 거리를 기반으로 부드럽고 비례적인 이동 명령을 계산합니다. 이동은 카메라 최대 속도의 백분율로 정규화되며, 카메라에 업데이트가 과도하게 몰리지 않도록 명령 속도 제한이 적용됩니다. 데드 존은 객체가 중심 근처에 있을 때 작은 움직임을 방지하여 헌팅 동작을 줄입니다. 줌이 활성화되면 카메라는 먼저 팬/틸트로 객체를 중앙에 맞춘 다음, 객체를 화면에 유지하면서 프레임을 채우기 위해 줌 인합니다.
일반적인 사용 사례
감시 및 보안: 감시 시나리오에서 개인이나 차량을 자동으로 추적합니다(예: 의심스러운 활동 추적, 침입자 추적, 보안 경계 모니터링). 자동화된 감시 워크플로를 지원합니다
스포츠 및 행사 중계: 스포츠 경기나 공연 중 선수나 객체를 추적합니다(예: 경기장에서 선수 따라가기, 공의 움직임 추적, 행사 장면 중계). 자동화된 스포츠 중계 워크플로를 지원합니다
야생동물 모니터링: 자연 서식지에서 동물이나 야생동물을 따라갑니다(예: 새의 움직임 추적, 보호구역의 동물 따라가기, 야생동물 행동 모니터링). 야생동물 관찰 워크플로를 지원합니다
산업 모니터링: 산업 환경에서 객체나 인원을 자동으로 따라갑니다(예: 장비 이동 추적, 작업자 활동 모니터링, 시설 내 차량 따라가기). 산업 자동화 워크플로를 지원합니다
교통 모니터링: 교통 상황에서 차량이나 객체를 추적합니다(예: 교차로를 지나는 차량 따라가기, 교통 위반 추적, 도로 활동 모니터링). 자동화된 교통 모니터링 워크플로를 지원합니다
리테일 분석: 소매 환경에서 고객이나 제품을 추적합니다(예: 고객 동선 따라가기, 제품 상호작용 추적, 쇼핑 행동 모니터링). 소매 분석 워크플로를 지원합니다
다른 블록과 연결하기
이 블록은 예측을 수신하고 카메라 제어 명령 및 추적 상태를 생성합니다:
객체 감지 또는 인스턴스 세분화 블록 이후 감지된 객체를 카메라로 추적합니다(예: 감지된 사람 따라가기, 감지된 차량 추적, 감지된 객체 모니터링). 감지-카메라 추적 워크플로를 지원합니다
Byte Tracker 블록 뒤에서 일관된 ID를 가진 특정 추적 객체를 따라갑니다(예: 프레임 간 추적된 사람 따라가기, 특정 차량 추적 유지, 추적 객체 지속 모니터링). 추적-카메라 워크플로를 지원합니다
객체 감지 필터 블록 뒤에서 특정 객체 클래스를 추적하거나 필터링된 감지를 추적합니다(예: 특정 클래스만 추적, 필터링된 감지 따라가기, 선택된 객체 모니터링). 필터링된 추적 워크플로를 지원합니다
시각화 블록 앞에 카메라 이동 상태와 추적 중인 객체를 표시합니다(예: 추적 상태 시각화, 탐색 표시기 표시, 카메라 제어 피드백 표시). 카메라 제어 시각화 워크플로를 지원합니다
알림 블록 앞에 카메라가 추적을 시작하거나 중지할 때 알립니다(예: 추적 시작 알림, 추적 손실 경고, 카메라 상태 보고). 카메라 상태 알림 워크플로를 지원합니다
감시 및 모니터링 पाइ프라인에서 자동화된 카메라 제어가 더 큰 보안 또는 모니터링 시스템의 일부인 경우(예: 자동 보안 시스템, 모니터링 पाइ프라인, 카메라 제어 체인). 종합적인 감시 워크플로를 지원합니다
요구 사항
이 블록은 네트워크 액세스가 가능한 ONVIF 호환 PTZ 카메라가 필요합니다. 카메라는 Follow 모드에서는 ONVIF ContinuousMove 서비스를, 프리셋 이동에서는 GotoPreset 서비스를 지원해야 합니다. 최적의 성능을 위해 가변 속도 이동을 지원하는 카메라를 사용하세요. 기본 가변 속도를 지원하지 않는 카메라는 simulate_variable_speed 옵션을 사용할 수 있지만, 움직임이 다소 끊길 수 있습니다. 이 블록은 로컬 실행 모드에서만 실행되어야 합니다(원격/클라우드 실행에는 적합하지 않음). 부드러운 추적을 위해 overshoot나 hunting 없이 PID 튜닝을 권장합니다. 카메라 응답성과 비디오 지연에 따라 pid_kp, pid_ki, pid_kd 파라미터를 조정하세요. 정확한 추적을 위해 카메라 이동과 비디오 피드백 사이의 지연을 최소화하는 적극적인 버퍼 소비 전략을 사용하세요. 프리셋 이동이나 자동 재설정 기능을 사용할 경우 카메라에 프리셋이 구성되어 있어야 합니다.
유형 식별자
step에서 다음 식별자를 사용하세요 "type" 필드: roboflow_core/onvif_sink@v1 를 워크플로에 단계로 추가합니다.
속성
이름
유형
설명
참조
name
str
이 단계에 고유 식별자를 입력하세요..
❌
camera_ip
str
ONVIF 연결을 위한 카메라 IP 주소 또는 호스트명. 워크플로 실행 환경에서 접근 가능해야 합니다..
✅
camera_port
int
카메라 ONVIF 서비스 포트(일반적으로 80, 8080 또는 카메라별 포트). 카메라의 ONVIF 구성과 일치해야 합니다..
✅
camera_username
str
ONVIF 인증을 위한 카메라 사용자 이름. 카메라에서 PTZ 제어 권한이 있어야 합니다..
✅
camera_password
str
ONVIF 인증을 위한 카메라 비밀번호. 보안을 위해 비밀로 저장해야 합니다..
✅
movement_type
str
카메라의 이동 모드입니다. 'Follow' 모드는 PID 제어를 사용해 감지된 객체를 추적합니다. 'Go To Preset' 모드는 카메라를 미리 정의된 프리셋 위치로 이동합니다(default_position_preset가 구성되어 있어야 함)..
❌
simulate_variable_speed
bool
기본 가변 속도 지원이 없는 카메라에 대해 가변 속도 시뮬레이션을 활성화합니다. 활성화되면 100% 속도 명령을 보내고 이어서 정지 명령을 보내 백분율 속도를 근사합니다. 움직임이 끊길 수 있으므로 카메라에 가변 속도 기능이 없을 때만 사용하세요..
✅
zoom_if_able
bool
추적 중인 객체로 화면을 채우기 위해 자동 줌을 활성화합니다. 활성화되면 카메라는 먼저 팬/틸트로 객체를 중앙에 맞춘 다음, 객체가 프레임을 채울 때까지 줌 인합니다. 카메라가 줌 기능을 지원해야 합니다..
✅
follow_tracker
bool
트래커 ID를 사용한 지속 추적을 활성화합니다. 활성화되면 카메라는 가장 높은 신뢰도의 감지 결과의 트래커 ID를 고정하고, 해당 객체가 사라지거나 추적이 재설정될 때까지 계속 따라갑니다. 트래커 ID를 할당하려면 워크플로에 Byte Tracker 블록이 필요합니다..
✅
dead_zone
int
카메라 움직임이 멈추는 프레임 중심 주변의 데드 존 크기(픽셀)입니다. 객체가 중앙 근처에 있을 때 헌팅 동작을 방지합니다. 값이 클수록 팬/틸트 헌팅은 줄지만 줌 헌팅이 발생할 수 있습니다. 값이 작을수록 줌 안정성은 향상되지만 팬/틸트 진동이 발생할 수 있습니다. 일반적인 범위: 30-100픽셀..
✅
default_position_preset
str
기본/홈 위치의 프리셋 이름입니다. 카메라는 유휴 기간이 지난 후(move_to_position_after_idle_seconds가 설정된 경우) 또는 Go To Preset 모드를 사용할 때 이 프리셋으로 돌아갑니다. 카메라에 구성된 프리셋 이름과 정확히 일치해야 합니다. 프리셋 이동 기능에 필요합니다..
✅
move_to_position_after_idle_seconds
int
자동 재설정 시간(초)입니다. 카메라가 이 시간 동안 탐색/이동을 멈춘 후 default_position_preset으로 자동 이동합니다. 자동 재설정을 비활성화하려면 0으로 설정하세요. default_position_preset가 구성되어 있어야 합니다..
✅
camera_update_rate_limit
int
카메라 이동 명령 사이의 최소 시간(밀리초)입니다. 카메라에 업데이트가 과도하게 몰리지 않도록 ONVIF 업데이트에 속도 제한을 적용합니다. 값이 낮을수록 추적 반응성은 높아지지만 느린 카메라에는 부담이 될 수 있습니다. 값이 높을수록 카메라 부하는 줄지만 움직임이 덜 부드러울 수 있습니다. 일반적인 범위: 100-500ms..
✅
flip_x_movement
bool
가로(팬) 이동 방향을 반전합니다. 카메라 이미지가 가로로 미러링되어 있고 움직임이 반대로 보일 때 활성화하세요. 이미지가 뒤집힌 경우 카메라 움직임을 보정하는 데 사용합니다..
✅
flip_y_movement
bool
세로(틸트) 이동 방향을 반전합니다. 많은 카메라에서 Y축이 반전되어 있으므로 기본적으로 활성화되어 있습니다. 세로 이동이 반대로 보이면 비활성화하세요..
✅
minimum_camera_speed
실수
최소 이동 속도 백분율(0.0-1.0)입니다. 이 임계값보다 낮은 이동 명령은 이 최소값으로 보정됩니다. 일부 카메라는 매우 낮은 속도를 무시합니다. 작은 움직임에 카메라가 반응하지 않으면 값을 높이세요. 일반적인 범위: 0.02-0.1 (2%-10%)..
✅
pid_kp
실수
PID 비례 이득(Kp)입니다. 위치 오차에 대한 반응을 제어합니다. 값이 높을수록 카메라가 더 빨리 반응하지만 오버슈트와 헌팅이 발생할 수 있습니다. 값이 낮을수록 헌팅은 줄지만 추적이 느려집니다. 기본값에서 시작해 카메라 응답성에 따라 조정하세요. 일반적인 범위: 0.1-0.5..
✅
pid_ki
실수
PID 적분 이득(Ki)입니다. 오차를 시간에 따라 누적해 정상 상태 오차를 제거합니다. 일반적으로 진동을 유발할 수 있으므로 0으로 유지합니다. 작은 오차에도 카메라가 항상 약간 중심에서 벗어난 위치에서 멈추면 약간(0.01-0.1) 높이세요..
✅
pid_kd
실수
PID 미분 이득(Kd)입니다. 미래 오차를 예측하고 진동을 완화합니다. 값이 높을수록 비디오 지연이 있을 때 안정성이 향상되지만, 지나치면 헌팅이 생길 수 있습니다. 카메라 움직임과 비디오 피드백 사이에 지연이 크면 1-5 정도 높이세요. 추적이 끊기는 것처럼 보이면 낮추세요..
✅
해당 참조 열은 워크플로 런타임에서 사용할 수 있는 동적 값으로 속성을 매개변수화할 수 있음을 나타냅니다. 자세한 내용은 워크플로 런타임. 자세한 내용은 바인딩 를 참조하세요.
런타임 호환성
하드 - 실행 원격 : 블록은 step_execution_mode=local이 필요하며, 그렇지 않으면 ValueError를 발생시킵니다. ONVIF 명령은 워크플로를 구동하는 동일한 프로세스에서 발행되어야 합니다.
하드 - 런타임 hosted_serverless, dedicated_deployment : 블록은 PTZ 카메라에 대한 LAN 액세스가 필요합니다. Hosted Serverless 및 Roboflow Dedicated Deployments는 고객 LAN에 접근할 수 없습니다.
입력 및 출력 바인딩
사용 가능한 연결은 바인딩 종류에 따라 달라집니다. 어떤 바인딩 종류가 있는지 확인하세요 PTZ 추적(ONVIF) 버전 v1 가 있습니다.
입력 및 출력 바인딩
입력
predictions(Union[instance_segmentation_prediction,object_detection_prediction]): 추적할 객체 감지 또는 인스턴스 분할 예측. Follow 모드에서는, 트래커 ID가 있는 경우 블록이 가장 높은 신뢰도 예측 또는 추적된 객체를 따라갑니다. 예측에는 바운딩 박스 좌표와, 지속 추적을 위한 선택적 트래커 ID가 포함되어야 합니다..camera_ip(문자열): ONVIF 연결을 위한 카메라 IP 주소 또는 호스트명. 워크플로 실행 환경에서 접근 가능해야 합니다..camera_port(정수): 카메라 ONVIF 서비스 포트(일반적으로 80, 8080 또는 카메라별 포트). 카메라의 ONVIF 구성과 일치해야 합니다..camera_username(문자열): ONVIF 인증을 위한 카메라 사용자 이름. 카메라에서 PTZ 제어 권한이 있어야 합니다..camera_password(secret): ONVIF 인증을 위한 카메라 비밀번호. 보안을 위해 비밀로 저장해야 합니다..simulate_variable_speed(boolean): 기본 가변 속도 지원이 없는 카메라에 대해 가변 속도 시뮬레이션을 활성화합니다. 활성화되면 100% 속도 명령을 보내고 이어서 정지 명령을 보내 백분율 속도를 근사합니다. 움직임이 끊길 수 있으므로 카메라에 가변 속도 기능이 없을 때만 사용하세요..zoom_if_able(boolean): 추적 중인 객체로 화면을 채우기 위해 자동 줌을 활성화합니다. 활성화되면 카메라는 먼저 팬/틸트로 객체를 중앙에 맞춘 다음, 객체가 프레임을 채울 때까지 줌 인합니다. 카메라가 줌 기능을 지원해야 합니다..follow_tracker(boolean): 트래커 ID를 사용한 지속 추적을 활성화합니다. 활성화되면 카메라는 가장 높은 신뢰도의 감지 결과의 트래커 ID를 고정하고, 해당 객체가 사라지거나 추적이 재설정될 때까지 계속 따라갑니다. 트래커 ID를 할당하려면 워크플로에 Byte Tracker 블록이 필요합니다..dead_zone(정수): 카메라 움직임이 멈추는 프레임 중심 주변의 데드 존 크기(픽셀)입니다. 객체가 중앙 근처에 있을 때 헌팅 동작을 방지합니다. 값이 클수록 팬/틸트 헌팅은 줄지만 줌 헌팅이 발생할 수 있습니다. 값이 작을수록 줌 안정성은 향상되지만 팬/틸트 진동이 발생할 수 있습니다. 일반적인 범위: 30-100픽셀..default_position_preset(문자열): 기본/홈 위치의 프리셋 이름입니다. 카메라는 유휴 기간이 지난 후(move_to_position_after_idle_seconds가 설정된 경우) 또는 Go To Preset 모드를 사용할 때 이 프리셋으로 돌아갑니다. 카메라에 구성된 프리셋 이름과 정확히 일치해야 합니다. 프리셋 이동 기능에 필요합니다..move_to_position_after_idle_seconds(정수): 자동 재설정 시간(초)입니다. 카메라가 이 시간 동안 탐색/이동을 멈춘 후 default_position_preset으로 자동 이동합니다. 자동 재설정을 비활성화하려면 0으로 설정하세요. default_position_preset가 구성되어 있어야 합니다..camera_update_rate_limit(정수): 카메라 이동 명령 사이의 최소 시간(밀리초)입니다. 카메라에 업데이트가 과도하게 몰리지 않도록 ONVIF 업데이트에 속도 제한을 적용합니다. 값이 낮을수록 추적 반응성은 높아지지만 느린 카메라에는 부담이 될 수 있습니다. 값이 높을수록 카메라 부하는 줄지만 움직임이 덜 부드러울 수 있습니다. 일반적인 범위: 100-500ms..flip_x_movement(boolean): 가로(팬) 이동 방향을 반전합니다. 카메라 이미지가 가로로 미러링되어 있고 움직임이 반대로 보일 때 활성화하세요. 이미지가 뒤집힌 경우 카메라 움직임을 보정하는 데 사용합니다..flip_y_movement(boolean): 세로(틸트) 이동 방향을 반전합니다. 많은 카메라에서 Y축이 반전되어 있으므로 기본적으로 활성화되어 있습니다. 세로 이동이 반대로 보이면 비활성화하세요..minimum_camera_speed(float_zero_to_one): 최소 이동 속도 백분율(0.0-1.0)입니다. 이 임계값보다 낮은 이동 명령은 이 최소값으로 보정됩니다. 일부 카메라는 매우 낮은 속도를 무시합니다. 작은 움직임에 카메라가 반응하지 않으면 값을 높이세요. 일반적인 범위: 0.02-0.1 (2%-10%)..pid_kp(실수): PID 비례 이득(Kp)입니다. 위치 오차에 대한 반응을 제어합니다. 값이 높을수록 카메라가 더 빨리 반응하지만 오버슈트와 헌팅이 발생할 수 있습니다. 값이 낮을수록 헌팅은 줄지만 추적이 느려집니다. 기본값에서 시작해 카메라 응답성에 따라 조정하세요. 일반적인 범위: 0.1-0.5..pid_ki(실수): PID 적분 이득(Ki)입니다. 오차를 시간에 따라 누적해 정상 상태 오차를 제거합니다. 일반적으로 진동을 유발할 수 있으므로 0으로 유지합니다. 작은 오차에도 카메라가 항상 약간 중심에서 벗어난 위치에서 멈추면 약간(0.01-0.1) 높이세요..pid_kd(실수): PID 미분 이득(Kd)입니다. 미래 오차를 예측하고 진동을 완화합니다. 값이 높을수록 비디오 지연이 있을 때 안정성이 향상되지만, 지나치면 헌팅이 생길 수 있습니다. 카메라 움직임과 비디오 피드백 사이에 지연이 크면 1-5 정도 높이세요. 추적이 끊기는 것처럼 보이면 낮추세요..
출력
predictions(object_detection_prediction): 감지된 경계 상자를 포함하는 sv.Detections(...) 객체 형식의 예측입니다.탐색 중(boolean): 불리언 플래그.
마지막 업데이트
도움이 되었나요?