PTZ Tracking (ONVIF)

Class: ONVIFSinkBlockV1

Source: inference.core.workflows.core_steps.sinks.onvif_movement.v1.ONVIFSinkBlockV1

This ONVIF block allows a workflow to control an ONVIF capable PTZ camera to follow a detected object.

The block returns three values: * predictions: a predictions object containing the single prediction the camera is currently following (can be empty) * seeking: indicates whether or not the camera is currently seeking an object (set asynchronously)

There are two modes:

*Follow: The object it follows is the maximum confidence prediction out of all predictions passed into it. To follow a specific object, use the appropriate filters on the predictiion object to specify the object you want to follow. Additionally if a tracker is used, the camera will follow the tracked object until it disappears. Additionally, zoom can be toggled to get the camera to zoom into a position.

*Move to Preset: The camera can also move to a defined preset position. The camera must support the GotoPreset service.

Note that the tracking block uses the ONVIF continuous movement service. Tracking is adjusted on each successive workflow execution. If workflow execution stops, and the camera is currently moving, the camera will continue moving until it reaches the limits and will no longer be following an object.

Use of a camera with variable speed movement is highly recommended for this block. "Simulate variable speed" can sometimes be used in place of this, but might result in jerky movements and hunting. This setting sends the camera a 100% movement command followed by a stop for a period in order to simulate a percentage speed movement. This can work in some cases, but the success varies depending on the camera's responsiveness.

PID tuning is generally necessary for this block to avoid having the camera overshoot and hunt. Having a significant lag between the camera movement and video (using a lazy buffer consumption strategy) can make tuning extremely difficult. Using an eager buffer consumption strategy is recommended. Increasing the dead zone can also help, but can affect zooming.

Type identifier

Use the following identifier in step "type" field: roboflow_core/onvif_sink@v1to add the block as as step in your workflow.

Properties

Name	Type	Description	Refs
name	str	Enter a unique identifier for this step..	❌
camera_ip	str	Camera IP address or hostname.	✅
camera_port	int	Camera ONVIF port.	✅
camera_username	str	Camera username.	✅
camera_password	str	Camera password.	✅
movement_type	str	Follow object or go to default position preset on execution.	❌
simulate_variable_speed	bool	Simulate variable speed on a lower end camera by using frequent stop commands.	✅
zoom_if_able	bool	Attempt to zoom into an object so it fills the image.	✅
follow_tracker	bool	Lock to the tracking id of the highest confidence prediction until idle or reset. A tracker must be added to the workflow..	✅
dead_zone	int	Camera will stop once bounding box is within this many pixels of FoV center (or border for zoom). Increasing dead zone helps avoid pan/tilt hunting, but decreasing dead zone helps avoid hunting after zoom..	✅
default_position_preset	str	Preset name for default position. This must be a valid camera preset name..	✅
move_to_position_after_idle_seconds	int	Move to the default position after this many seconds of not seeking (0 to disable).	✅
camera_update_rate_limit	int	Minimum number of milliseconds between ONVIF movement updates.	✅
flip_x_movement	bool	Flip X movement if image is mirrored horizontally.	✅
flip_y_movement	bool	Flip Y movement if image is mirrored vertically.	✅
minimum_camera_speed	float	Minimum camera speed as percent (0-1). Some cameras won't honor speeds below a certain amount..	✅
pid_kp	float	PID Kp (proportional) constant. Decrease Kp to reduce hunting at the expense of speed..	✅
pid_ki	float	PID Ki (integral) constant. Use to reduce steady state error, but it can usually be zero..	✅
pid_kd	float	PID Kd (derivative) constant. Increase Kd with lag between video and movement, but excessive Kd can also cause hunting..	✅

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Available Connections

Compatible Blocks

Check what blocks you can connect to PTZ Tracking (ONVIF) in version v1.

• inputs: Detections Stitch, Detections Combine, Seg Preview, Byte Tracker, YOLO-World Model, Google Gemini, Velocity, Dynamic Crop, SIFT Comparison, Detection Offset, Identify Changes, Camera Focus, Slack Notification, Instance Segmentation Model, Pixel Color Count, OpenAI, Anthropic Claude, Local File Sink, SAM 3, Distance Measurement, Byte Tracker, LMM, Time in Zone, Path Deviation, VLM as Detector, Florence-2 Model, Detections Stabilizer, Email Notification, Google Vision OCR, Motion Detection, Google Gemini, Clip Comparison, Cosine Similarity, Detections Classes Replacement, Anthropic Claude, Camera Focus, Detections Filter, Object Detection Model, Instance Segmentation Model, Perspective Correction, EasyOCR, CSV Formatter, VLM as Classifier, Twilio SMS/MMS Notification, OpenAI, Stitch OCR Detections, Line Counter, Detections Transformation, VLM as Detector, SAM 3, Roboflow Custom Metadata, CogVLM, Model Monitoring Inference Aggregator, OCR Model, Time in Zone, Byte Tracker, Roboflow Dataset Upload, Path Deviation, Dynamic Zone, Detections List Roll-Up, PTZ Tracking (ONVIF).md), Line Counter, Keypoint Detection Model, Detections Consensus, Moondream2, Webhook Sink, Google Gemini, OpenAI, Template Matching, Image Contours, JSON Parser, OpenAI, Llama 3.2 Vision, Bounding Rectangle, SIFT Comparison, Gaze Detection, Identify Outliers, Twilio SMS Notification, Single-Label Classification Model, VLM as Classifier, Time in Zone, Florence-2 Model, LMM For Classification, Detections Merge, Object Detection Model, SAM 3, Segment Anything 2 Model, Multi-Label Classification Model, Roboflow Dataset Upload, Overlap Filter, Email Notification
• outputs: Detections Combine, Detections Stitch, Byte Tracker, Velocity, Dynamic Crop, Blur Visualization, Detection Offset, Bounding Box Visualization, Slack Notification, Keypoint Visualization, Trace Visualization, Instance Segmentation Model, Polygon Visualization, Ellipse Visualization, Model Comparison Visualization, Triangle Visualization, Polygon Zone Visualization, SAM 3, Halo Visualization, Distance Measurement, Byte Tracker, Time in Zone, Path Deviation, Florence-2 Model, Single-Label Classification Model, Detections Stabilizer, Circle Visualization, Email Notification, Motion Detection, Camera Focus, Detections Classes Replacement, Detections Filter, Object Detection Model, Instance Segmentation Model, Perspective Correction, Reference Path Visualization, Corner Visualization, Color Visualization, Twilio SMS/MMS Notification, Multi-Label Classification Model, Stitch OCR Detections, Line Counter, Detections Transformation, Roboflow Custom Metadata, Dot Visualization, Model Monitoring Inference Aggregator, Object Detection Model, Label Visualization, Background Color Visualization, Time in Zone, Classification Label Visualization, Byte Tracker, Roboflow Dataset Upload, Keypoint Detection Model, Path Deviation, Mask Visualization, Dynamic Zone, Detections List Roll-Up, Pixelate Visualization, PTZ Tracking (ONVIF).md), Line Counter, Keypoint Detection Model, Detections Consensus, Size Measurement, Webhook Sink, Stability AI Inpainting, Template Matching, Line Counter Visualization, Crop Visualization, Icon Visualization, SIFT Comparison, Gaze Detection, Twilio SMS Notification, Single-Label Classification Model, Time in Zone, Florence-2 Model, Detections Merge, SAM 3, Multi-Label Classification Model, Segment Anything 2 Model, Roboflow Dataset Upload, Overlap Filter, Email Notification

Input and Output Bindings

The available connections depend on its binding kinds. Check what binding kinds PTZ Tracking (ONVIF) in version v1 has.

Bindings

• input

  • predictions (Union[instance_segmentation_prediction, object_detection_prediction]): Object predictions.
  • camera_ip (string): Camera IP address or hostname.
  • camera_port (integer): Camera ONVIF port.
  • camera_username (string): Camera username.
  • camera_password (secret): Camera password.
  • simulate_variable_speed (boolean): Simulate variable speed on a lower end camera by using frequent stop commands.
  • zoom_if_able (boolean): Attempt to zoom into an object so it fills the image.
  • follow_tracker (boolean): Lock to the tracking id of the highest confidence prediction until idle or reset. A tracker must be added to the workflow..
  • dead_zone (integer): Camera will stop once bounding box is within this many pixels of FoV center (or border for zoom). Increasing dead zone helps avoid pan/tilt hunting, but decreasing dead zone helps avoid hunting after zoom..
  • default_position_preset (string): Preset name for default position. This must be a valid camera preset name..
  • move_to_position_after_idle_seconds (integer): Move to the default position after this many seconds of not seeking (0 to disable).
  • camera_update_rate_limit (integer): Minimum number of milliseconds between ONVIF movement updates.
  • flip_x_movement (boolean): Flip X movement if image is mirrored horizontally.
  • flip_y_movement (boolean): Flip Y movement if image is mirrored vertically.
  • minimum_camera_speed (float_zero_to_one): Minimum camera speed as percent (0-1). Some cameras won't honor speeds below a certain amount..
  • pid_kp (float): PID Kp (proportional) constant. Decrease Kp to reduce hunting at the expense of speed..
  • pid_ki (float): PID Ki (integral) constant. Use to reduce steady state error, but it can usually be zero..
  • pid_kd (float): PID Kd (derivative) constant. Increase Kd with lag between video and movement, but excessive Kd can also cause hunting..

• output

  • predictions (object_detection_prediction): Prediction with detected bounding boxes in form of sv.Detections(...) object.
  • seeking (boolean): Boolean flag.

Example JSON definition of step PTZ Tracking (ONVIF) in version v1

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/onvif_sink@v1",
    "predictions": "$steps.object_detection_model.predictions",
    "camera_ip": "<block_does_not_provide_example>",
    "camera_port": "<block_does_not_provide_example>",
    "camera_username": "<block_does_not_provide_example>",
    "camera_password": "<block_does_not_provide_example>",
    "movement_type": "Follow",
    "simulate_variable_speed": true,
    "zoom_if_able": true,
    "follow_tracker": true,
    "dead_zone": 50,
    "default_position_preset": "",
    "move_to_position_after_idle_seconds": "<block_does_not_provide_example>",
    "camera_update_rate_limit": "<block_does_not_provide_example>",
    "flip_x_movement": true,
    "flip_y_movement": true,
    "minimum_camera_speed": "<block_does_not_provide_example>",
    "pid_kp": "<block_does_not_provide_example>",
    "pid_ki": "<block_does_not_provide_example>",
    "pid_kd": "<block_does_not_provide_example>"
}