Settings#

This section describes parameters of the trackengine.conf file. You can use these parameters to configure TrackEngine.

Logging section#

mode#

Specifies a logging mode.

Possible values:

Value	Description
`l2c`	Writes logs to a console only.
`l2f`	Writes logs to a file.
`l2b`	Default. Writes logs to a console and file.

<param name="mode" type="Value::String" text="l2b" />

log-file-path#

Specifies a path to the log file.

The default value is log.txt.

<param name="log-file-path" type="Value::String" text="log.txt" />

severity#

Specifies a logging severity level.

Possible values:

Value	Description
0	Debug level.
1	Info level.
2	Default. Warning level.
3	Error only level.

<param name="severity" type="Value::Int1" x="1" />

Other parameters section#

callback-mode#

Specifies a mode TrackEngine works in.

Possible values:

Value	Description
0	Default. The estimator mode.
1	The asynchronous push or callback mode.

<param name="callback-mode" type="Value::Int1" x="1" />

detector-step#

Specifies a number of frames between frames with full detection.

Possible values are in range 1-30. The lower the number is, the more likely TrackEngine is to detect a new face as soon as it appears. The higher the number is, the higher the performance is. You can use to balance between computation performance and face detection recall.

The default value is 7.

<param name="detector-step" type="Value::Int1" x="7" />

detector-comparer#

Specifies a detector comparer to get the best face detection in a frame based on the following metrics:

Value	Metric	Description
0	DctConfidence	Gets the best face detection by a score.
1	DctCenter	Default. Gets the best face detection if it is located closer to the frame center.
2	DctCenterAndConfidence	Gets the best face detection if it matches the `DctConfidence` and `DctCenter` metrics.
3	DctSize	Gets the face detection of a face that has the biggest size.

The parameter works with the use-one-detection-mode parameter.

<param name="detector-comparer" type="Value::Int1" x="1" />

use-one-detection-mode#

Specifies a detection mode.

Possible values:

Value	Description
0	Default. Tracks all detections in an image.
1	Tracks one detection in an image.

 <param name="use-one-detection-mode" type="Value::Int1" x="0" />

skip-frames#

Specifies a number of frames by which a track must be updated by a detector or re-detector. Otherwise, the track is finished.

Note that very high values may lead to performance degradation.

The parameter applies to face tracking only.

The default value is 18.

<param name="skip-frames" type="Value::Int1" x="18" />

frg-subtractor#

Specifies whether to enable the foreground subtractor. This parameter can improve performance, especially on sources with low activity. Yet, it may reduce face detection recall in rare cases.

Possible values:

Value	Description
0	Disables the foreground subtractor.
1	Default. Enables the foreground subtractor.

<param name="frg-subtractor" type="Value::Int1" x="1" />

frames-buffer-size#

Specifies a size of the internal storage buffer for input frames.

A larger buffer preserves more frames and reduces skipping. If detection performance is not high enough to keep up with the frame submission rate, the buffer prevents frame loss. Yet, increasing this value also increases RAM/VRAM consumption . You can use the parameter to balance between resource utilization and face detection recall.

The minimal value is 10 because of internal algorithm requirements, for example, batching.

The default value is 20.

The parameter is applied per stream and does not affect the estimator API (callback-mode = 0).

<param name="frames-buffer-size" type="Value::Int1" x="20" />

callback-buffer-size#

Specifies a size of the internal storage buffer for all callbacks.

A larger buffer ensures higher performance. Yet, it may use more memory.

The parameter does not affect the estimator API (callback-mode = 0).

The default value is 20.

<param name="callback-buffer-size" type="Value::Int1" x="20" />

tracking-results-buffer-size#

Specifies the maximum buffer size for stored tracking results.

The parameter can limit some other parameters, for example, reid-matching-detections-count.

<param name="tracking-results-buffer-size" type="Value::Int1" x="20" />

detector-scaling#

Specifies whether frame scaling before detection or foreground subtraction is enabled for performance reasons.

Possible values:

Value	Description
0	Disables frame scaling.
1	Default. Enables frame scaling.

<param name="detector-scaling" type="Value::Int1" x="1" />

scale-result-size#

Specifies a size of a frame to be scaled, in pixels, for a detection step, if scaling is enabled.

The default value is 640.

Upper scaling is impossible.

<param name="scale-result-size" type="Value::Int1" x="640" />

max-detection-count#

Specifies the maximum detection count that can be found by one detector call.

The parameter limits performance load. We recommend that you set up a very high value, if you do not want any limits.

The default value is 128.

<param name="max-detection-count" type="Value::Int1" x="128" />

minimal-track-length#

Specifies the minimum detection or re-detection count for a track (see TrackInfo::detectionsCount). This count must be met for a track to be returned in tracking results.

The parameter does not apply to human tracking.

The default value is 1. It allows you to get all track data, but there can be short tracks because of detector faults. In this case, you should implement your own logic to filter such tracks.

<param name="minimal-track-length" type="Value::Int1" x="1" />

tracker-type#

Specifies the tracker type to be used.

The parameter does not apply to body tracking.

Possible values:

kcf
opencv
carkalman
vlTracker
none

The default value is vlTracker.

<param name="tracker-type" type="Value::String" text="" />

kill-intersected-detections#

Specifies whether to remove intersected detections, if the intersection detection area of two tracks in relation to their total area (IOU, intersection over union)is greater than the value of kill-intersection-value.

The parameter applies to face tracking only.

For body and body+face tracking, use the remove-overlapped-strategy parameter. Note that setting remove-overlapped-strategy to a value other than none causes removing detections after a detector. It happens, if the intersection detection area of two tracks in relation to their total area is greater than the value of kill-intersection-value. In this case, the tracks are not affected.

Possible values:

Value	Description
0	Disables the parameter.
1	Default. Enables the parameter.

<param name="kill-intersected-detections" type="Value::Int1" x="1" />

kill-intersection-value#

Specifies a number to be compared with the intersection over union size. If the value of kill-intersection-value is less than the intersection detection area of two tracks in relation to their total area (IOU), the intersected detections will be removed.

The default value is 0.55.

<param name="kill-intersection-value" type="Value::Float1" x="0.55"/>

FRG section#

frg-subtractor-type#

Specifies a type of the foreground subtractor algorithm to be used.

The default value is MOG.

<param name="frg-subtractor-type" type="Value::String" text="MOG" />

use-binary-frg#

Specifies whether to use a binary foreground subtractor on CPU.

Possible values:

Value	Description
0	Disables the parameter. Regions are used for detection. The value improves performance on CPU, but degrades tracking accuracy and recall. For GPU, the binary option is always used because it provides better performance.
1	Default. Enables the parameter. If any region is found by the foreground subtractor, a full frame is used for detection.

<param name="use-binary-frg" type="Value::Int1" x="1" />

frg-update-step#

Specifies an update step of the foreground mask measured in frame count. The value should be greater or equal to the detector-step parameter value.

The default value is 20.

<param name="frg-update-step" type="Value::Int1" x="20" />

frg-scale-size#

Specifies the size of the calculated foreground mask and is used to find regions. A higher value increases accuracy, but decreases performance. The value should be lower than the scale-result-size parameter value.

Do not use this parameter for the MOG foreground subtractor type. For MOG scaling, the value of scale-result-size should be 0.25, that is the original frame size, if detector-scaling is 0.

The default value is 160.

<param name="frg-scale-size" type="Value::Int1" x="160" />

frg-regions-alignment#

Specifies a value by which regions (rectangles) calculated from the foreground are aligned. The parameter is useful for better tracking quality and recall if use-binary-frg is 0.

The parameter works only for CPU.

The parameter is measured in absolute values. It should be in the range 0..scale-result-size if detector-scaling is 1, and [0..frame_max_side_size] if detector-scaling is 0. frame_max_side_size is the maximum side size of the original frame.

You can find an optimal value empirically. High values provide better recall and tracking accuracy, but can degrade performance. The highest possible value equals to binary-frg. Lower values can degrade accuracy but increase performance.

The default value is 360.

<param name="frg-regions-alignment" type="Value::Int1" x="360" />

frg-regions-square-alignment#

Specifies whether to align foreground regions to a rectangle with equal sides. The rectangle's maximum side is chosen. See also frg-regions-alignment.

Possible values:

Value	Description
0	Disables the foreground region alignment to a square.
1	Default. Enables foreground region alignment to a square.

<param name="frg-regions-square-alignment" type="Value::Int1" x="1" />

Vehicle section#

best-shots-number-for-track#

Specifies a number of best shots for tracking.

The default value is 2.

<param name="best-shots-number-for-track" type="Value::Int1" x="2" />

max-processing-fragments-count#

Specifies the maximum number of fragments for a stream being processed in time. Zero value means no limit.

The default value is 1.

<param name="max-processing-fragments-count" type="Value::Int1" x="1" />

Face tracking specific parameters section#

face-landmarks-detection#

Specifies whether to enable face landmark detection. Disabling the parameter improves performance.

Possible values:

Value	Description
0	Disables face landmark detection.
1	Default. Enables face landmark detection.

<param name="face-landmarks-detection" type="Value::Int1" x="1" />

Human/Body tracking specific parameters section#

remove-overlapped-strategy#

Specifies the strategy to be used for removing after detection or re-detection.

Possible values:

none
both
score

The default value is score.

<param name="remove-overlapped-strategy" type="Value::String" text="score" />

remove-horizontal-ratio#

Specifies a width to height ratio threshold. This threshold is used for removing horizontal detections.

The default value is 1.6.

<param name="remove-horizontal-ratio" type="Value::Float1" x="1.6"/>

iou-connection-threshold#

Specifies the intersection over union threshold value. This value is used for matching tracks and detections.

The default value is 0.5.

<param name="iou-connection-threshold" type="Value::Float1" x="0.5"/>

use-body-reid#

Specifies whether to use re-identification of body tracks. Enabling the parameter improves accuracy of body tracking, but reduces performance.

Possible values:

Value	Description
0	Disables using of re-identification of body tracks.
1	Default. Enables using of re-identification of body tracks.

<param name="use-body-reid" type="Value::Int1" x="1"/>

body-reid-version#

Specifies a version of a re-identification neural network used for body tracking.

The default value is 108.

<param name="body-reid-version" type="Value::Int1" x="108"/>

reid-matching-threshold#

Specifies a re-identification similarity threshold. The threshold is used for matching tracks to each other.

The default value is 0.85.

<param name="reid-matching-threshold" type="Value::Float1" x="0.85"/>

reid-matching-detections-count#

Specifies a number of detections that a track must have to be matched by re-identification.

The minimum value is 1.

The default value is 2.

<param name="reid-matching-detections-count" type="Value::Int1" x="2" />

inactive-tracks-lifetime#

Specifies a lifetime of inactive body tracks, which are used for re-identification. It is measured in number of frames and used for matching tracks to each other.

Higher values lead to better quality of re-identification, but reduce performance.

The default value is 100.

<param name="inactive-tracks-lifetime" type="Value::Int1" x="100" />

Detectors section#

use-face-detector#

Specifies whether to use face detection.

Possible values:

Value	Description
0	Disables using of face detection.
1	Default. Enables using of face detection.

<param name="use-face-detector" type="Value::Int1" x="1" />

use-body-detector#

Specifies whether to use body detection.

Possible values:

Value	Description
0	Default. Disables using of body detection.
1	Enables using of body detection.

<param name="use-body-detector" type="Value::Int1" x="0" />

use-vehicle-detector#

Specifies whether to use vehicle detection.

Possible values:

Value	Description
0	Default. Disables using of vehicle detection.
1	Enables using of vehicle detection.

<param name="use-vehicle-detector" type="Value::Int1" x="0" />

use-license-plate-detector#

Specifies whether to use license plate detection.

Possible values:

Value	Description
0	Default. Disables using of license plate detection.
1	Enables using of license plate detection.

<param name="use-license-plate-detector" type="Value::Int1" x="0" />

Experimental parameters section#

Parameter described in this section can be removed, renamed, or moved to other sections in future updates.

detect-max-batch-size#

Specifies the maximum batch size for detection to limit memory consumption.

The default value is 0 and means there is no limit.

<param name="detect-max-batch-size" type="Value::Int1" x="0" />

redetect-max-batch-size#

Specifies the maximum batch size for re-detection to limit memory consumption.

The default value is 0 and means there is no limit.

<param name="redetect-max-batch-size" type="Value::Int1" x="0" />

tracker-max-batch-size#

Specifies the maximum batch size for a tracker to limit memory consumption.

The default value is 0 and means there is no limit.

<param name="tracker-max-batch-size" type="Value::Int1" x="0" />

reid-max-batch-size#

Specifies the maximum batch size for reID to limit memory consumption.

The default value is 0 and means there is no limit.

<param name="reid-max-batch-size" type="Value::Int1" x="0" />

min-frames-batch-size#

Specifies a number of frames per stream that need to be processed.

Possible value are in range [0, 5].

Value 0 means auto fitting of the parameter. Auto fitting depends on TrackEngine internal implementation, possible value is detector-step.

The parameter is associated with the max-frames-batch-gather-timeout parameter. The two parameters regulate processing latency versus throughput and device utilization.

Higher values lead to higher processing latency. Yet, they can increase throughput and device utilization.

The default value is 1 and means that any available stream frames will be processed.

<param name="min-frames-batch-size" type="Value::Int1" x="1" />

max-frames-batch-gather-timeout#

Specifies the maximum available timeout per stream, in milliseconds, to gather the next frame batch. This timeout starts from the last processing begin time point.

Value 0 means no timeout and equals to min-frames-batch-size = [0-1].

This parameter is associated with min-frames-batch-size. If min-frames-batch-size is not 1, this parameter regulates timeout of batch waiting.

Higher values lead to higher processing latency. Yet, they can increase throughput and device utilization.

The default value is 100.

<param name="max-frames-batch-gather-timeout" type="Value::Int1" x="100" />

<!-- ## Debug parameters section

save-debug-info#

Specifies whether to calculate and enable getting extra information in tracking results for debug purposes, for example, foreground masks.

Possible values:

Value	Description
0	Default. Disables saving debug information.
1	Enables saving debug information.

 <param name="save-debug-info" type="Value::Int1" x="0" />

show-profiling-data#

Specifies whether to show profile data on TrackEngine de-initialization.

Possible values:

Value	Description
0	Default. Disables showing profiling data.
1	Enables showing profiling data.

<param name="show-profiling-data" type="Value::Int1" x="0" />

save-buffer-log#

Specifies whether to save buffer size for each frame on TrackEngine de-initialization.

Possible values:

Value	Description
0	Default. Disables saving buffer size.
1	Enables saving buffer size.

<param name="save-buffer-log" type="Value::Int1" x="0" />

batched-processing#

Specifies whether to process stream frames in a batch or separately.

Value	Description
0	Processes stream frames in a batch.
1	Default. Processes stream frames separately.

<param name="batched-processing" type="Value::Int1" x="1" />
``` -->

## Config example

```xml
<?xml version="1.0"?>

<settings>
    <section name="logging">
        <param name="mode" type="Value::String" text="l2b" />
        <param name="log-file-path" type="Value::String" text="log.txt" />
        <param name="severity" type="Value::Int1" x="1" />
    </section>

    <section name="other">
        <param name="callback-mode" type="Value::Int1" x="1" />
        <param name="detector-step" type="Value::Int1" x="7" />
        <param name="detector-comparer" type="Value::Int1" x="1" />
        <param name="use-one-detection-mode" type="Value::Int1" x="0" />
        <param name="skip-frames" type="Value::Int1" x="18" />
        <param name="frg-subtractor" type="Value::Int1" x="1" />
        <param name="frames-buffer-size" type="Value::Int1" x="20" />
        <param name="callback-buffer-size" type="Value::Int1" x="20" />
        <param name="tracking-results-buffer-size" type="Value::Int1" x="20" />
        <param name="detector-scaling" type="Value::Int1" x="1" />
        <param name="scale-result-size" type="Value::Int1" x="640" />
        <param name="max-detection-count" type="Value::Int1" x="128" />
        <param name="minimal-track-length" type="Value::Int1" x="1" />
        <param name="tracker-type" type="Value::String" text="" />
        <param name="kill-intersected-detections" type="Value::Int1" x="1" />
         <param name="kill-intersection-value" type="Value::Float1" x="0.55"/>
    </section>

    <section name="FRG">
        <param name="frg-subtractor-type" type="Value::String" text="MOG" />
        <param name="use-binary-frg" type="Value::Int1" x="1" />
        <param name="frg-update-step" type="Value::Int1" x="20" />
        <param name="frg-scale-size" type="Value::Int1" x="160" />
        <param name="frg-regions-alignment" type="Value::Int1" x="360" />
        <param name="frg-regions-square-alignment" type="Value::Int1" x="1" />

    </section>

    <section name="vehicle">
        <param name="best-shots-number-for-track" type="Value::Int1" x="2" />
        <param name="max-processing-fragments-count" type="Value::Int1" x="1" />
    </section>

    <section name="face">
        <param name="face-landmarks-detection" type="Value::Int1" x="1" />
    </section>

    <section name="human">
        <param name="human-landmarks-detection" type="Value::Int1" x="0" />
        <param name="remove-overlapped-strategy" type="Value::String" text="score" />
        <param name="remove-horizontal-ratio" type="Value::Float1" x="1.6"/>
        <param name="iou-connection-threshold" type="Value::Float1" x="0.5"/>
        <param name="use-body-reid" type="Value::Int1" x="1"/>
       <param name="body-reid-version" type="Value::Int1" x="108"/>
       <param name="reid-matching-threshold" type="Value::Float1" x="0.85"/>
       <param name="reid-matching-detections-count" type="Value::Int1" x="2" />
       <param name="inactive-tracks-lifetime" type="Value::Int1" x="100" />
    </section>

    <section name="detectors">
        <param name="use-face-detector" type="Value::Int1" x="1" />
        <param name="use-body-detector" type="Value::Int1" x="0" />
        <param name="use-vehicle-detector" type="Value::Int1" x="0" />
        <param name="use-license-plate-detector" type="Value::Int1" x="0" />
    </section>

    <section name="experimental">
        <param name="detect-max-batch-size" type="Value::Int1" x="0" />
        <param name="redetect-max-batch-size" type="Value::Int1" x="0" />
        <param name="tracker-max-batch-size" type="Value::Int1" x="0" />
        <param name="reid-max-batch-size" type="Value::Int1" x="0" />
        <param name="min-frames-batch-size" type="Value::Int1" x="1" />
      <param name="max-frames-batch-gather-timeout" type="Value::Int1" x="100" />
    </section>

    <section name="debug">
        <param name="save-debug-info" type="Value::Int1" x="0" />
        <param name="show-profiling-data" type="Value::Int1" x="0" />
        <param name="save-buffer-log" type="Value::Int1" x="0" />
        <param name="batched-processing" type="Value::Int1" x="1" />
    </section>

</settings>