Speed Measurement Service¶

servicespeed

The Speed Measurement service enables automatic calculation of vehicle speeds from video recordings. For each tracked object, AITracker knows its precise location in every video frame (motion trajectory). By defining a measurement zone with known real-world dimensions, the system calculates how long each vehicle takes to traverse the zone and derives its average speed.

How It Works¶

Homography-Based Speed Calculation¶

AITracker uses homography transformation to convert pixel coordinates from the video into real-world distances. This geometric transformation maps a 4-point polygon in the video frame to known physical dimensions in meters.

The algorithm:

Polygon Definition - You define 4 points in the video that represent a known rectangular area on the road surface
Real-World Dimensions - You specify the width and length of this area in meters
Homography Calculation - The system computes a transformation matrix between image space and real-world space
Trajectory Tracking - As vehicles move through the polygon, their trajectory is tracked frame-by-frame
Speed Calculation - The distance covered (in meters) divided by time (in seconds) gives the speed

Entry and Exit Detection¶

The system detects when a vehicle enters and exits the measurement zone:

Entry frame - First frame where the vehicle's bottom center is inside the polygon
Exit frame - First frame where the vehicle leaves the polygon

The velocity is calculated as the mean speed between these two points, converted to km/h.

Configuration¶

Distance Zone Setup¶

To enable speed measurement, you must define a Distance object in your scene configuration with:

Parameter	Type	Description
`trajectory`	4 points	Four corner points of the measurement zone (relative coordinates 0.0-1.0)
`width`	float	Real-world width of the zone in meters
`length`	float	Real-world length of the zone in meters

4-Point Polygon Definition¶

The polygon must be defined as 4 corner points representing a quadrilateral on the road surface:

Point 1 ─────────── Point 2
   │                   │
   │   MEASUREMENT     │
   │      ZONE         │
   │                   │
Point 4 ─────────── Point 3

Guidelines for polygon placement:

Place the polygon on a flat road section (no hills, curves, or elevation changes)
Ensure the polygon covers the full lane width for the measured vehicles
The longer the measurement zone, the more accurate the speed estimation
Avoid areas with frequent vehicle occlusions
Keep the camera angle as perpendicular to the road as possible for best accuracy

Real-World Dimensions¶

Accurate speed measurement depends on precise real-world dimensions:

Width - The lateral dimension of the polygon (across the road), in meters
Length - The longitudinal dimension (along the road direction), in meters

Tip: Measure the road surface dimensions in the field before setting up the video analysis. You can use road markings, lane widths, or known reference objects (car lengths, road signs) for calibration.

Technical Parameters¶

The velocity classifier has several configurable parameters:

Parameter	Default	Description
`max_velocity`	160 km/h	Velocities above this are discarded as invalid
`min_time_in_the_zone_ms`	500 ms	Minimum time vehicle must spend in zone for valid measurement
`remove_frames_percent`	10%	Boundary frames removed to reduce noise

Excluded Vehicle Categories from reporting¶

Speed of all objects is being measured, but the following categories are excluded from the generated report:

Bicycles and e-bikes
Personal transporters (UTO)
Scooters
Pedestrians (all categories)
Trains
Warning vehicles

Measurement Accuracy¶

Aspect	Value
Typical accuracy	±5-10%
Best accuracy conditions	Flat road, perpendicular camera, clear weather
Processing speed	up to x5 (24h video in ~5h)

Important: This speed measurement is an estimation and is not certified for law enforcement or traffic violations. The values are suitable for traffic studies, planning, and general analysis.

Generated Output¶

Velocity.csv¶

The main output file contains:

Column	Description
`Time`	Timestamp when vehicle was measured
`Direction`	Movement direction (based on lane classification)
`Label`	Vehicle category
`Velocity`	Measured speed in km/h
`Distance`	Distance covered in meters
`Timespan`	Time spent in measurement zone (seconds)

Visualizations¶

AITracker generates:

VelocityScatter.png - Scatter plot of all measured speeds over time
Velocity.png - Average speed by hour
VelocityPerCategory.png - Average speed by vehicle category
VelocityDistribution.png - Speed distribution histogram

Report¶

The generated Report.docx includes:

Speed statistics by direction
Speed statistics by vehicle category
Measurement precision analysis
Speed limit exceedance summary (if limits configured)

Best Practices¶

Camera Placement
Mount camera high enough to see the full measurement zone
Avoid extreme angles that distort perspective
Ensure stable camera position (no vibration or movement)
Zone Design
Use minimum 10m length for reliable measurements
Match zone width to actual lane width
Position zone away from intersections or stopping areas
Calibration
Use known reference objects to verify dimensions
Test with vehicles of known speed if possible
Account for camera lens distortion

Limitations¶

Speed accuracy depends on correct polygon dimensions
Very fast vehicles (>160 km/h default) may be filtered out
Curved roads reduce measurement accuracy
Camera shake affects trajectory precision
Not suitable for legal speed enforcement