Velocity¶

Calculate the velocity and speed of tracked objects across video frames by measuring displacement of object centers over time, applying exponential moving average smoothing to reduce noise, and converting measurements from pixels per second to meters per second for traffic speed monitoring, movement analysis, behavior tracking, and performance measurement workflows.

How This Block Works¶

This block measures how fast objects are moving by tracking their positions across video frames. The block:

1. Receives tracked detection predictions with unique tracker IDs and an image with embedded video metadata
2. Extracts video metadata from the image:
3. Accesses video_metadata to get frame timestamps or frame numbers and frame rate (fps)
4. Extracts video_identifier to maintain separate tracking state for different videos
5. Determines current timestamp using frame_number/fps for video files or frame_timestamp for streams
6. Validates that detections have tracker IDs (required for tracking object movement across frames)
7. Calculates object center positions:
8. Computes the center point (x, y) of each bounding box in the current frame
9. Uses bounding box coordinates to find geometric centers
10. Retrieves or initializes tracking state:
11. Maintains previous positions and timestamps for each tracker_id per video
12. Stores smoothed velocity history for each tracker_id per video
13. Creates new tracking entries for objects appearing for the first time
14. Calculates velocity and speed for each tracked object:
15. For objects with previous positions: Computes displacement (change in position) and time delta (change in time) between current and previous frames
16. Velocity: Calculates velocity vector as displacement divided by time delta (pixels per second)
17. Speed: Computes speed as the magnitude (length) of the velocity vector (total pixels per second regardless of direction)
18. For new objects: Sets velocity and speed to zero (no movement data available yet)
19. Applies exponential moving average smoothing:
20. Smooths velocity measurements using exponential moving average with configurable smoothing factor (alpha)
21. Reduces noise and jitter in velocity calculations from detection variations
22. Lower alpha values provide more smoothing (slower response to changes), higher alpha values provide less smoothing (faster response to changes)
23. Calculates smoothed velocity and smoothed speed for each object
24. Converts units to meters per second:
25. Divides pixel-based velocities and speeds by pixels_per_meter conversion factor
26. Converts all measurements (velocity, speed, smoothed_velocity, smoothed_speed) to real-world units
27. Enables comparison with real-world speed measurements (e.g., km/h, mph)
28. Stores velocity data in detection metadata:
29. Adds four velocity metrics to each detection: velocity (m/s), speed (m/s), smoothed_velocity (m/s), smoothed_speed (m/s)
30. Velocity is a 2D vector [vx, vy] representing direction and magnitude of movement
31. Speed is a scalar value representing total speed regardless of direction
32. All measurements are stored in detections.data for downstream use
33. Updates tracking state for next frame:
    • Saves current positions and timestamps for all tracked objects
    • Stores smoothed velocities for next frame's smoothing calculations
34. Returns detections enhanced with velocity information:
    • Outputs the same detection objects with added velocity metadata
    • Each detection now includes velocity and speed data in its metadata

Velocity is calculated based on the displacement of object centers (bounding box centers) over time. The block maintains separate tracking state for each video, allowing velocity calculation across multiple video streams. Due to perspective distortion and camera positioning, calculated velocity may vary depending on where objects appear in the frame - objects closer to the camera or at different depths will have different pixel-per-second values for the same real-world speed. The smoothing helps reduce noise from detection inaccuracies and frame-to-frame variations.

Common Use Cases¶

• Traffic Speed Monitoring: Measure vehicle speeds on roads and highways (e.g., monitor traffic speeds, detect speeding violations, analyze traffic flow rates), enabling traffic enforcement and analysis workflows
• Sports Performance Analysis: Track athlete movement and speed during sports activities (e.g., measure player speeds, analyze sprint performance, track movement patterns), enabling sports analytics workflows
• Security and Surveillance: Monitor movement speed of people or objects in security scenarios (e.g., detect running or suspicious rapid movement, monitor crowd flow speeds, track object movement rates), enabling security monitoring workflows
• Retail Analytics: Analyze customer movement patterns and walking speeds in retail spaces (e.g., measure customer flow rates, analyze shopping behavior patterns, track movement efficiency), enabling retail behavior analysis workflows
• Wildlife Behavior Studies: Track animal movement speeds and patterns in natural habitats (e.g., measure animal speeds, analyze migration patterns, study movement behavior), enabling wildlife research workflows
• Industrial Monitoring: Monitor speeds of vehicles, equipment, or products in industrial settings (e.g., track conveyor speeds, measure vehicle speeds in facilities, monitor production line movement rates), enabling industrial automation workflows

Connecting to Other Blocks¶

This block receives tracked detections and an image with embedded video metadata, and produces detections enhanced with velocity metadata:

• After Byte Tracker blocks to calculate velocity for tracked objects (e.g., measure speeds of tracked vehicles, analyze tracked person movement, monitor tracked object velocities), enabling tracking-to-velocity workflows
• After object detection or instance segmentation blocks with tracking enabled to measure movement speeds (e.g., calculate vehicle speeds, track person movement rates, monitor object velocities), enabling detection-to-velocity workflows
• Before visualization blocks to display velocity information (e.g., visualize speed overlays, display velocity vectors, show movement speed annotations), enabling velocity visualization workflows
• Before logic blocks like Continue If to make decisions based on speed thresholds (e.g., continue if speed exceeds limit, filter based on velocity ranges, trigger actions on speed violations), enabling speed-based decision workflows
• Before notification blocks to alert on speed violations or threshold events (e.g., alert on speeding violations, notify on rapid movement, trigger speed-based alerts), enabling velocity-based notification workflows
• Before data storage blocks to record velocity measurements (e.g., log speed data, store velocity statistics, record movement metrics), enabling velocity data logging workflows

Requirements¶

This block requires tracked detections with tracker_id information (detections must come from a tracking block like Byte Tracker). The image's video_metadata should include frame rate (fps) for video files or frame timestamps for streamed video to calculate accurate time deltas. The block maintains persistent tracking state across frames for each video using video_identifier, so it should be used in video workflows where frames are processed sequentially. For accurate velocity measurement, detections should be provided consistently across frames with valid tracker IDs. The pixels_per_meter conversion factor should be calibrated based on camera setup and scene geometry for accurate real-world speed measurements. Note that velocity accuracy may vary due to perspective distortion depending on object position in the frame.

Type identifier¶

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

Properties¶

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

Runtime compatibility¶

soft — runtime hosted_serverless, dedicated_deployment; execution remote; input video

Block keeps per-video state in process memory (keyed by video_metadata.video_identifier). With remote step execution on stateless or multi-replica HTTP runtimes, successive requests may be served by different worker processes, so the state resets between calls and the output is meaningless for tracking / counting / aggregation. Use local step execution in an InferencePipeline for stable cross-frame results.

soft — input image

Block depends on temporal context from video or repeated-frame workflows. With a still image/photo, there is no meaningful history to track, compare, aggregate, or visualize, so the block provides little or no benefit.

Available Connections¶

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Velocity in version v1 has.

{
    "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
}