Przejdź do treści

Video Properties Configuration

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

  3. Some cameras produce VFR (Variable Frame Rate) files

  4. Manual FPS setting uses average frame rate

  5. Re-encoded videos

  6. Videos converted between formats may have incorrect metadata

  7. Original recording parameters may differ from current file

  8. Corrupted video headers

  9. Damaged files may report zero or invalid dimensions

  10. Manual override allows processing despite corruption

  11. Cloud processing requirements

  12. Ensuring consistent parameters across multiple files
  13. 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:
  5. Open Video Properties tab
  6. Enter correct FPS: 15.0
  7. Enable "Force video parameters" checkbox
  8. Save configuration
  9. Reclassification: Run reclassification to recalculate speeds
  10. Validation: Verify speeds are now realistic (30-50 km/h)
  • 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