ITEP-80577 Tracker improvements in time-chunking and time-based parameters

[tdorauintc]

📝 Description

Changes:

• Replace frame-based parameters with time-based parameters in high level tracker configuration. Benefits: it is a more intuitive definition and it is independent from camera FPS
• Introduce a new parameter effective_object_update_rate used as a reference frame rate for deriving tracker internal frame-based parameters from high level time-based parameters. The parameter reflects the real rate of objects observations as seen by the tracker
• Remove the logic intended to dynamically scale time-based tracker parameters based on current camera FPS (which didn't work because of bug in controller: time-based parameters were never really updated based on actual camera FPS due to wrong dictionary key used - frame_rate instead of rate).
• Use time chunking rate as reference camera rate in time-chunked tracker configuration, so that internal frame-based parameters are correctly calculated in the tracker (based on the real frequency of camera updates, which is time-chunking rate)
• Replace time_chunking_interval_milliseconds configuration parameter with time_chunking_rate_fps
• Adjusted time chunking rate in default configuration to OOB demo videos (10 FPS)
• Minor code cleanup
• User guide updated

✨ Type of Change

Select the type of change your PR introduces:

• 🐞 Bug fix – Non-breaking change which fixes an issue
• 🚀 New feature – Non-breaking change which adds functionality
• 🔨 Refactor – Non-breaking change which refactors the code base
• 💥 Breaking change – Changes that break existing functionality
• 📚 Documentation update
• 🔒 Security update
• 🧪 Tests
• 🚂 CI

🧪 Testing Scenarios

Time-chunking disabled

Low-level tracker parameters before applying PR changes (main branch):

scene-1  | 2026-01-12 19:36:46 Multiple Object Tracker <IntelLabsTracking(IntelLabsTracking, initial)> initialized
scene-1  | 2026-01-12 19:36:46 Tracker config: TrackManagerConfig( non_measurement_time_dynamic:0.266667, non_measurement_time_static:0.533333, max_unreliable_time:0.333333, reactivation_frames:1, default_process_noise:0.000100, default_measurement_noise:0.200000, init_state_covariance:1.000000 motion_models: CV CA CTRV)
scene-1  | Updated parameters for reference camera frame rate = 30fps
scene-1  | max_unreliable_frames = 10
scene-1  | non_measurement_frames_dynamic = 8
scene-1  | non_measurement_frames_static = 16

Low-level tracker parameters after applying PR changes (time-chunking-improvements branch):

scene-1  | non_measurement_frames_static = 16
scene-1  | 2026-01-12 19:42:24 Multiple Object Tracker <IntelLabsTracking(IntelLabsTracking, initial)> initialized
scene-1  | 2026-01-12 19:42:24 Tracker config: TrackManagerConfig( non_measurement_time_dynamic:0.800000, non_measurement_time_static:1.600000, max_unreliable_time:1.000000, reactivation_frames:1, default_process_noise:0.000100, default_measurement_noise:0.200000, init_state_covariance:1.000000 motion_models: CV CA CTRV)
scene-1  | Updated parameters for reference camera frame rate = 10fps
scene-1  | max_unreliable_frames = 10
scene-1  | non_measurement_frames_dynamic = 8
scene-1  | non_measurement_frames_static = 16

Time-chunking enabled

Low-level tracker parameters before applying PR changes (main branch):

scene-1  | 2026-01-12 19:41:44 Started IntelLabs tracker <IntelLabsTracking(IntelLabsTracking, started 129969105659584)> thread for category person
scene-1  | 2026-01-12 19:41:44 Failed to connect to VDMS container: [Errno -2] Name or service not known
scene-1  | 2026-01-12 19:41:51 Multiple Object Tracker <IntelLabsTracking(IntelLabsTracking, initial)> initialized
scene-1  | 2026-01-12 19:41:51 Tracker config: TrackManagerConfig( non_measurement_time_dynamic:0.133333, non_measurement_time_static:0.266667, max_unreliable_time:0.166667, reactivation_frames:1, default_process_noise:0.000100, default_measurement_noise:0.200000, init_state_covariance:1.000000 motion_models: CV CA CTRV)
scene-1  | Updated parameters for reference camera frame rate = 30fps
scene-1  | max_unreliable_frames = 5
scene-1  | non_measurement_frames_dynamic = 4
scene-1  | non_measurement_frames_static = 8

Low-level tracker parameters after applying PR changes (time-chunking-improvements branch):

scene-1  | 2026-01-12 19:43:52 Started IntelLabs tracker <IntelLabsTracking(IntelLabsTracking, started 137673662523072)> thread for category person
scene-1  | 2026-01-12 19:43:52 Multiple Object Tracker <IntelLabsTracking(IntelLabsTracking, initial)> initialized
scene-1  | 2026-01-12 19:43:52 Tracker config: TrackManagerConfig( non_measurement_time_dynamic:0.800000, non_measurement_time_static:1.600000, max_unreliable_time:1.000000, reactivation_frames:1, default_process_noise:0.000100, default_measurement_noise:0.200000, init_state_covariance:1.000000 motion_models: CV CA CTRV)
scene-1  | Updated parameters for reference camera frame rate = 10fps
scene-1  | max_unreliable_frames = 10
scene-1  | non_measurement_frames_dynamic = 8
scene-1  | non_measurement_frames_static = 16

Describe how the changes were tested and how reviewers can test them too:

• ✅ Tested manually
• 🤖 Ran automated end-to-end tests

✅ Checklist

Before submitting the PR, ensure the following:

• 🔍 PR title is clear and descriptive
• 📝 For internal contributors: If applicable, include the JIRA ticket number (e.g., ITEP-123456) in the PR title. Do not include full URLs
• 💬 I have commented my code, especially in hard-to-understand areas
• 📄 I have made corresponding changes to the documentation
• ✅ I have added tests that prove my fix is effective or my feature works

[saratpoluri]

Please request a fresh review when the comments are addressed.

[Copilot]

Pull request overview

This PR refactors the tracker configuration from frame-based to time-based parameters, improving intuitiveness and camera FPS independence. It fixes a bug where dynamic FPS scaling was ineffective due to incorrect dictionary key usage, and adjusts time-chunking configuration to use rate (FPS) instead of interval (milliseconds).

Changes:

• Replaced frame-based tracker parameters with time-based equivalents (seconds instead of frame counts)
• Introduced effective_object_update_rate parameter to define tracker's reference frame rate
• Changed time-chunking from interval-based (ms) to rate-based (FPS) configuration
• Removed non-functional dynamic FPS scaling logic
• Updated documentation with conversion guidelines

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/system/metric/test_data/tracker-config.json	Updated to use time-based parameters instead of frame-based
tests/system/metric/test_data/tracker-config-time-chunking.json	Converted to time-based parameters and rate-based time-chunking
tests/system/metric/tc_tracker_metric.py	Updated to read new time-based parameters and rate-based time-chunking
controller/src/controller/tracking.py	Added effective_object_update_rate constant and threading parameter passing
controller/src/controller/time_chunking.py	Refactored from interval-based to rate-based time-chunking configuration
controller/src/controller/scene_controller.py	Implemented validation and extraction logic for new time-based parameters
controller/src/controller/scene.py	Updated Scene initialization to use effective_object_update_rate and removed dynamic FPS logic
controller/src/controller/ilabs_tracking.py	Updated to accept and use effective_object_update_rate parameter
controller/src/controller/cache_manager.py	Updated to include effective_object_update_rate in scene data
controller/docs/user-guide/How-to-configure-tracker.md	Comprehensive documentation update with parameter descriptions and conversion examples
controller/config/tracker-config.json	Updated default configuration to time-based parameters
controller/config/tracker-config-time-chunking.json	Updated time-chunking configuration to use rate instead of interval

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[saratpoluri]

LGTM. Haven't checked if time chunking still works. @jdanieck please verify.