Velocity block (w/ Byte Tracker)

[reedajohns]

Description

Implemented VelocityBlockV1:

• Developed a new analytics block to calculate and embed velocities and speeds of Byte Tracked objects across video frames.
• Supports smoothing of velocity measurements using an exponential moving average with configurable smoothing_alpha.
• Incorporated unit conversion from pixels to meters via the pixels_per_meter parameter (e.g., pixels_per_meter=1000 for 1000 pixels = 1 meter).

Key Features:

• Velocity Calculation: Computes raw and smoothed velocities based on object movements between frames.
• Speed Calculation: Determines the magnitude of velocity vectors to obtain speed.

List any dependencies that are required for this change.

This requires the input of Byte Track detections and appends the velocity / speed to the detections metadata for use downstream:

Example:
'velocity': {4: [-9.669, 14.509]}, 'speed': {4: 17.432}, 'smoothed_velocity': {4: [-6.033, 9.555]}, 'smoothed_speed': {4: 11.300}}

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

How has this change been tested, please provide a testcase or example of how you tested the change?

Unit Tests:

• Test Scenarios:
  • Basic Calculations: Verified accurate velocity and speed computations across consecutive frames.
  • New Tracker Handling: Ensured the block correctly initializes velocities for newly appearing objects.
  • Error Conditions: Confirmed that invalid inputs (e.g., missing tracker_id, invalid smoothing_alpha, non-positive pixels_per_meter) raise appropriate ValueError exceptions.
  • Edge Cases: Tested scenarios such as zero time difference between frames and large object movements to validate robustness.

[grzegorz-roboflow]

Video metadata kind was deprecated, (changelog), please use WorkflowImageData.metadata

[grzegorz-roboflow]

I'd add disclaimer, that this might not apply to all scenes and/or all movement directions (due to perspective and camera distortions; i.e. for some field of view 5px far away will result in different speed than 5px near the camera)

[grzegorz-roboflow]

We have StabilizeTrackedDetectionsBlock which might be already delivering some functionality that is being achieved here

Also - you can use FLOAT_ZERO_TO_ONE_KIND if this parameter is expected to only store values between (0, 1) - that way the value of parameter will be checked during compilation