|
| 1 | +# How to Configure the Tracker |
| 2 | + |
| 3 | +This document guides users and developers on configuring the tracker for specific use cases during Intel® SceneScape deployment. |
| 4 | + |
| 5 | +## Tracker Configuration with Time-Based Parameters |
| 6 | + |
| 7 | +### Enabling Time-Based Parameters |
| 8 | + |
| 9 | +A `tracker-config.json` file is pre-stored in the `controller` directory. The only change required is to mount this file to the Docker container in the `scene` service. The `scene` service in the `docker-compose.yml` file should look as follows. Note the `configs` section. |
| 10 | + |
| 11 | +```yaml |
| 12 | +scene: |
| 13 | + image: scenescape-controller:${VERSION:-latest} |
| 14 | + # ... |
| 15 | + # mount the trackerconfig file to the container |
| 16 | + configs: |
| 17 | + - source: tracker-config |
| 18 | + target: /home/scenescape/SceneScape/tracker-config.json |
| 19 | +``` |
| 20 | +
|
| 21 | +The default content of the `tracker-config.json` file is shown below. It is recommended to keep the default values of these parameters unchanged. |
| 22 | + |
| 23 | +``` |
| 24 | +{ |
| 25 | + "max_unreliable_frames": 10, |
| 26 | + "non_measurement_frames_dynamic": 8, |
| 27 | + "non_measurement_frames_static": 16, |
| 28 | + "baseline_frame_rate": 30, |
| 29 | + "time_chunking_enabled": false |
| 30 | +} |
| 31 | +``` |
| 32 | +
|
| 33 | +Here is a brief description of each time-based configuration parameter: |
| 34 | +
|
| 35 | +- `max_unreliable_frames`: Defines the number of frames the tracker will wait before publishing a tracked object to the web interface. Expects a positive integer. |
| 36 | +
|
| 37 | +- `non_measurement_frames_dynamic`: Defines the number of frames the tracker will wait before deleting a dead tracked object if the object was dynamic (i.e., had non-zero velocity). Expects a positive integer. |
| 38 | +
|
| 39 | +- `non_measurement_frames_static`: Defines the number of frames the tracker will wait before deleting a dead tracked object if the object was static (i.e., had zero velocity). Expects a positive integer. |
| 40 | +
|
| 41 | +- `baseline_frame_rate`: The frame rate (in FPS) for which the above three parameters are optimized. Expects a positive integer. |
| 42 | +
|
| 43 | +### How Time-Based Parameters Work |
| 44 | +
|
| 45 | +Time-based tracker parameters enable automatic adjustment of the following three values as a function of the camera feed frame rate (instead of using fixed values): |
| 46 | +
|
| 47 | +- `max_unreliable_frames` |
| 48 | +
|
| 49 | +- `non_measurement_frames_dynamic` |
| 50 | +
|
| 51 | +- `non_measurement_frames_static` |
| 52 | +
|
| 53 | +For instance, if `max_unreliable_frames` is set to a fixed value, the wait time for publishing reliable tracklets will vary with camera FPS. This creates a significant lag between the camera feed and scene updates for low-FPS cameras. When `max_unreliable_frames = 10`, the wait time for a 10 FPS camera is 1 second, compared to 10 seconds for a 1 FPS camera (too long). |
| 54 | +
|
| 55 | +When time-based parameters are enabled, these three parameters are scaled as a linear function of the camera FPS: |
| 56 | +
|
| 57 | +``` |
| 58 | +updated max_unreliable_frames = (default max_unreliable_frames / baseline_frame_rate) × incoming camera frame rate |
| 59 | +``` |
| 60 | +
|
| 61 | +The default values of `max_unreliable_frames` and `baseline_frame_rate` are defined in the `tracker-config.json` file. The same applies to the other two parameters. |
| 62 | +
|
| 63 | +**Note**: If the scene contains multiple cameras publishing at different frame rates, the minimum frame rate among all cameras is used for the update. |
| 64 | +
|
| 65 | +### Note on Changing Camera Frame Rate |
| 66 | +
|
| 67 | +Restarting the Scene Controller is necessary if one or more camera frame rates are changed after the initial deployment. In these cases, first use `docker compose down` to terminate the current deployment, make the necessary modifications to video sources in the `docker-compose.yml` file, and then relaunch with `docker compose up`. |
| 68 | +
|
| 69 | +## Time-Chunking Configuration |
| 70 | +
|
| 71 | +If time-chunking is disabled, the tracker processes each camera frame individually, meaning it processes data at a rate equal to the cumulative camera FPS (frames per second). Cumulative camera FPS is the sum of FPS for all cameras. |
| 72 | +
|
| 73 | +Enabling time-chunking changes how the tracker processes input data: the tracker processes data at a constant rate defined by `time_chunking_interval_milliseconds`. Detections from different cameras within the time interval are processed in one chunk. If multiple frames from a single camera fall within the time window, only the latest frame is included in the chunk. |
| 74 | +
|
| 75 | +### When to Use Time-Chunking |
| 76 | +
|
| 77 | +Time-chunking should be used to reduce the load on the tracker when high cumulative camera FPS prevents the tracker from processing new detections within the given time budget, effectively causing input data to be dropped. This manifests as `Tracker work queue is not empty` warnings in controller logs. This typically occurs when the number of cameras is high, even if individual camera FPS is at the minimum acceptable level. |
| 78 | +
|
| 79 | +If high FPS from individual cameras is causing pressure on the tracker, it is recommended to first reconfigure the cameras to use the lowest acceptable FPS for the use case. |
| 80 | +
|
| 81 | +### Enabling Time-Chunking |
| 82 | +
|
| 83 | +In the `configs` section of your `docker-compose.yml`, change the `tracker-config` to point to `controller/config/tracker-config-time-chunking.json`: |
| 84 | +
|
| 85 | +```yaml |
| 86 | +configs: |
| 87 | + tracker-config: |
| 88 | + # Use this configuration file to run tracking with time-chunking enabled |
| 89 | + file: ./controller/config/tracker-config-time-chunking.json |
| 90 | + # file: ./controller/config/tracker-config.json |
| 91 | +``` |
| 92 | + |
| 93 | +The content of the `tracker-config-time-chunking.json` file is shown below. |
| 94 | + |
| 95 | +```json |
| 96 | +{ |
| 97 | + "max_unreliable_frames": 5, |
| 98 | + "non_measurement_frames_dynamic": 4, |
| 99 | + "non_measurement_frames_static": 8, |
| 100 | + "baseline_frame_rate": 30, |
| 101 | + "time_chunking_enabled": true, |
| 102 | + "time_chunking_interval_milliseconds": 66 |
| 103 | +} |
| 104 | +``` |
| 105 | + |
| 106 | +Here is a brief description of the time-chunking-specific configuration parameters: |
| 107 | + |
| 108 | +- `time_chunking_enabled`: Enables or disables the time-chunking feature. Set to `true` to enable. |
| 109 | +- `time_chunking_interval_milliseconds`: Defines the interval in milliseconds at which the tracker processes data in chunks. The effective tracker processing rate is `1000 / time_chunking_interval_milliseconds` Hz. For example, if the interval is 66 ms, the tracker processing rate is 15.15 Hz. |
| 110 | + |
| 111 | +### How to Set Time-Chunking Interval |
| 112 | + |
| 113 | +The rule of thumb for setting the time-chunking interval is to adjust it to the camera with the highest frame rate: `time_chunking_interval_milliseconds = 1000 / highest_camera_FPS`. This way, no input data will be dropped during time-chunking. |
| 114 | + |
| 115 | +The time-chunking interval may be further increased beyond the recommended value if additional performance improvements are needed. However, in this case, more than one frame from a camera might fall within a time chunk, and the potential accuracy loss caused by dropped frames should be carefully balanced against performance benefits. |
| 116 | + |
| 117 | +### Adjusting Time-Based Parameters for Time-Chunking |
| 118 | + |
| 119 | +The mechanism of time-based parameters described above still applies when time-chunking is enabled. What may change with time-chunking enabled is the track refresh rate, which is the rate at which a track is updated with new detections. When time-chunking is disabled, each track is refreshed at a rate equal to the cumulative FPS of cameras observing the object. With time-chunking enabled, each track is refreshed at the tracker processing rate, which is `1000 / time_chunking_interval_milliseconds` Hz. |
| 120 | + |
| 121 | +This means that if all cameras use comparable FPS and time-chunking is enabled with the interval set as recommended above, the time-based parameters may need adjustment depending on camera overlap. For example, if most of the scene is covered by two cameras, the track refresh rate may drop by a factor of two after enabling time-chunking. To compensate, the time-based parameters (`max_unreliable_frames`, `non_measurement_frames_dynamic`, `non_measurement_frames_static`) may need to be reduced by a factor of 2. However, it should always be experimentally verified which parameters work best for a given use case. |
0 commit comments