Video Properties

The Video Properties tab displays and allows manual configuration of video file parameters. This is crucial for ensuring accurate traffic analysis, speed calculations, and proper object detection.

Overview

AITracker automatically reads video metadata from file headers (width, height, FPS). However, sometimes this metadata is incorrect or missing, which can negatively impact:

• Object detection accuracy

• Speed and velocity calculations

• Timestamp synchronization

• Report generation

The Video Properties configuration allows you to override these parameters manually when needed.

Video Parameters

Video Width (px)

Default: Auto-detected from video file Range: 256 - 9999 pixels Purpose: Defines the horizontal resolution of the video frame

• Used for coordinate system calculations

• Affects object size detection

• Critical for perspective correction

Video Height (px)

Default: Auto-detected from video file Range: 256 - 9999 pixels Purpose: Defines the vertical resolution of the video frame

• Used for coordinate system calculations

• Affects object size detection

• Important for trajectory calculations

Video FPS (Frames Per Second)

Default: Auto-detected from video file Range: 1 - 256 FPS Purpose: Defines the frame rate of the video

• Critical for speed calculations - incorrect FPS leads to wrong velocity measurements

• Affects temporal accuracy of object tracking

• Impacts timestamp generation in reports

• Essential for synchronization of multiple video sources

Force Video Parameters

Checkbox: VideoForce Purpose: When enabled, overrides auto-detected values with manually specified parameters

When to Use Manual Override

Common scenarios requiring manual configuration:

1. Incorrect FPS in video header

   Example: Video file reports 25 FPS in metadata, but was actually recorded at 15 FPS. This 67% difference will cause massive errors in speed calculations.

2. Variable frame rate videos

   • Some cameras produce VFR (Variable Frame Rate) files

   • Manual FPS setting uses average frame rate

3. Re-encoded videos

   • Videos converted between formats may have incorrect metadata

   • Original recording parameters may differ from current file

4. Corrupted video headers

   • Damaged files may report zero or invalid dimensions

   • Manual override allows processing despite corruption

5. Cloud processing requirements

   • Ensuring consistent parameters across multiple files

   • Standardizing video properties for batch processing

Validation Rules

When updating from UI (update_from_ui method):

Width validation:

• Must be a valid number

• Range: 256 ≤ width ≤ 9999

• Logged error if out of range

Height validation:

• Must be a valid number

• Range: 256 ≤ height ≤ 9999

• Logged error if out of range

FPS validation:

• Must be a valid float number

• Range: 1.0 ≤ fps ≤ 256.0

• Logged error if out of range

How Forcing Works

When forced:

• Manual parameters override auto-detected values

• All video readers use specified dimensions and FPS

• Parameters are saved with configuration

• Applied consistently across all processing stages

Impact on Processing

Speed Calculations

Incorrect FPS has the most severe impact on speed measurements:

Actual FPS	Reported FPS	Speed Error
15	25	+67% (speeds appear faster)
25	15	-40% (speeds appear slower)
30	25	+20% (speeds appear faster)

Object Detection

Incorrect dimensions affect:

• AI detector performance - smaller objects in frame reduce detection accuracy

• Perspective calculations - wrong aspect ratio distorts trajectory analysis

• Cross-section positioning - coordinates may not align properly

Cloud Processing

When processing in cloud:

• Forced parameters ensure consistency

• Prevents automatic detection errors

• Maintains accuracy across distributed processing nodes

Best Practices

1. Verify Before Processing

Always check video properties before starting analysis:

• Play video in media player (VLC, ffplay) to verify actual FPS

• Use ffprobe or mediainfo tools to inspect metadata

• Compare reported values with camera specifications

2. Test Configuration

Before processing large batches:

• Test with forced parameters on single file

• Verify speed calculations are reasonable

• Check that object detection works properly

3. Document Overrides

When using manual parameters:

• Document why override was necessary

• Record original vs. corrected values

• Keep notes for future reference

4. Validate Results

After processing with forced parameters:

• Review speed statistics for reasonableness

• Check object counts against expectations

• Verify timestamps align with known events

Example Workflow

Problem: Incorrect FPS

1. Detection: Notice unrealistic speeds in results (e.g., cars traveling 150 km/h in city)

2. Investigation: Check video metadata - shows 25 FPS

3. Verification: Play video in VLC - actual framerate is 15 FPS

4. Correction:

   • Open Video Properties tab

   • Enter correct FPS: 15.0

   • Enable "Force video parameters" checkbox

   • Save configuration

5. Reclassification: Run reclassification to recalculate speeds

6. Validation: Verify speeds are now realistic (30-50 km/h)

Related Features

• Reclassification - After changing video parameters, reclassify to recalculate speeds

• Speed/distance measurement - Heavily dependent on correct FPS values

• Configuration management - Video properties are saved per configuration

Notes

• Video properties are non-modifiable after counting - changing them requires re-processing or reclassification

• Parameters are stored in config.json for each configuration

• Default values (0) mean "use auto-detected values"

• Forced parameters override defaults for all files in the location