tracker

Tracking settings.

A single 'active' selector chooses which tracker drives 'geotrax extract'. The complete parameter set for all six supported trackers is kept below, so you can switch algorithm by changing one line. Only the active tracker's block is used; the others are ignored. Full reference: https://docs.ultralytics.com/modes/track/

Generated from geotrax/cfg/default.yaml; every row below is a key of that file with its shipped default and its inline comment.

Key	Default	CLI	Description
active	botsort		Active tracking algorithm; choices: [botsort, bytetrack, ocsort, deepocsort, fasttrack, tracktrack]

tracker.botsort

BoT-SORT — strong all-round accuracy; motion-based with optional appearance (ReID) and in-tracker GMC.

Key	Default	CLI	Description
tracker_type	botsort		Tracker backend; botsort enables GMC and optional ReID; [botsort, bytetrack, ocsort, deepocsort, fasttrack, tracktrack]
track_high_thresh	0.25		Detection confidence threshold for first-stage (high-confidence) association; [0.0, 1.0]
track_low_thresh	0.1		Detection confidence threshold for second-stage (low-confidence) recovery; [0.0, 1.0]
new_track_thresh	0.25		Minimum confidence to initialise a new track; higher reduces false track initiations; [0.0, 1.0]
track_buffer	30		Frames to keep a lost track alive before deletion; higher tolerates longer occlusions; [1, inf)
match_thresh	0.8		Max association cost (1 - IoU) for track-detection matching; higher = looser (accepts lower-IoU matches); [0.0, 1.0]
fuse_score	true		Fuse detection confidence with the IoU cost matrix; improves weak-detection robustness; [true, false]

BoT-SORT specific

Key	Default	CLI	Description
gmc_method	sparseOptFlow		Global motion compensation method; choices: [sparseOptFlow, orb, sift, ecc, none]

ReID (appearance-based re-identification)

Key	Default	CLI	Description
proximity_thresh	0.5		Minimum IoU for tracks to be considered proximate enough for ReID comparison; [0.0, 1.0]
appearance_thresh	0.8		Minimum cosine similarity for ReID match acceptance; higher reduces identity swaps; [0.0, 1.0]
with_reid	false		Enable ReID model; requires additional model weights and increases compute; [true, false]
model	auto		ReID model name or path; "auto" uses detector-derived features if available; string

tracker.bytetrack

ByteTrack — fastest and simplest; two-stage association, no ReID/GMC.

Key	Default	CLI	Description
tracker_type	bytetrack		Tracker backend; bytetrack is faster but lacks ReID/GMC; [botsort, bytetrack, ocsort, deepocsort, fasttrack, tracktrack]
track_high_thresh	0.25		Detection confidence threshold for first-stage (high-confidence) association; [0.0, 1.0]
track_low_thresh	0.1		Detection confidence threshold for second-stage (low-confidence) recovery; [0.0, 1.0]
new_track_thresh	0.25		Minimum confidence to initialise a new track; higher reduces false track initiations; [0.0, 1.0]
track_buffer	30		Frames to keep a lost track alive before deletion; higher tolerates longer occlusions; [1, inf)
match_thresh	0.8		Max association cost (1 - IoU) for track-detection matching; higher = looser (accepts lower-IoU matches); [0.0, 1.0]
fuse_score	true		Fuse detection confidence with the IoU cost matrix; improves weak-detection robustness; [true, false]

tracker.ocsort

OC-SORT — observation-centric, motion-only, ReID-free; robust to occlusion and non-linear motion.

Key	Default	CLI	Description
tracker_type	ocsort		Tracker backend; [botsort, bytetrack, ocsort, deepocsort, fasttrack, tracktrack]
track_high_thresh	0.25		Detection confidence threshold for first-stage (high-confidence) association; [0.0, 1.0]
track_low_thresh	0.1		Detection confidence threshold for second-stage recovery; only used when use_byte=true; [0.0, 1.0]
new_track_thresh	0.25		Minimum confidence to initialise a new track; higher reduces false track initiations; [0.0, 1.0]
track_buffer	30		Frames to keep a lost track alive before deletion; higher tolerates longer occlusions; [1, inf)
match_thresh	0.8		Max association cost (1 - IoU) for track-detection matching; higher = looser (accepts lower-IoU matches); [0.0, 1.0]
fuse_score	true		Fuse detection confidence with the IoU cost matrix; improves weak-detection robustness; [true, false]

OC-SORT specific

Key	Default	CLI	Description
delta_t	3		Temporal window [frames] for velocity-direction estimation in the OCM module; higher smooths more; [1, inf)
inertia	0.2		Weight of the velocity-consistency cost in association; higher penalises direction changes; [0.0, 1.0]
use_byte	false		Enable a ByteTrack-style low-confidence second association pass; [true, false]

tracker.deepocsort

Deep OC-SORT — OC-SORT plus appearance (ReID) features and optional GMC; fewer ID switches in crowds.

Key	Default	CLI	Description
tracker_type	deepocsort		Tracker backend; [botsort, bytetrack, ocsort, deepocsort, fasttrack, tracktrack]
track_high_thresh	0.3		Detection confidence threshold for first-stage (high-confidence) association; [0.0, 1.0]
track_low_thresh	0.1		Detection confidence threshold for second-stage recovery; only used when use_byte=true; [0.0, 1.0]
new_track_thresh	0.3		Minimum confidence to initialise a new track; higher reduces false track initiations; [0.0, 1.0]
track_buffer	30		Frames to keep a lost track alive before deletion; higher tolerates longer occlusions; [1, inf)
match_thresh	0.8		Max association cost (1 - IoU) for track-detection matching; higher = looser (accepts lower-IoU matches); [0.0, 1.0]
fuse_score	true		Fuse detection confidence with the IoU cost matrix; improves weak-detection robustness; [true, false]

OC-SORT specific (inherited)

Key	Default	CLI	Description
delta_t	3		Temporal window [frames] for velocity-direction estimation in the OCM module; higher smooths more; [1, inf)
inertia	0.2		Weight of the velocity-consistency cost in association; higher penalises direction changes; [0.0, 1.0]
use_byte	false		Enable a ByteTrack-style low-confidence second association pass; [true, false]

Deep OC-SORT specific

Key	Default	CLI	Description
gmc_method	none		Global motion compensation method; choices: [sparseOptFlow, orb, sift, ecc, none] — enable for moving-camera scenes
with_reid	false		Enable the ReID appearance model; requires extra weights and increases compute; [true, false]
model	auto		ReID model name or path; "auto" uses detector-derived features if available; string
proximity_thresh	0.5		Minimum IoU for tracks to be considered proximate enough for ReID comparison; [0.0, 1.0]
appearance_thresh	0.9		Minimum appearance (cosine) similarity for ReID match acceptance; higher reduces identity swaps; [0.0, 1.0]
alpha_fixed_emb	0.95		Base EMA factor for updating track embeddings; higher = slower embedding update; [0.0, 1.0]

tracker.fasttrack

FastTracker — occlusion-aware ByteTrack variant with Kalman rollback and init-IoU suppression; ReID-free.

Key	Default	CLI	Description
tracker_type	fasttrack		Tracker backend; [botsort, bytetrack, ocsort, deepocsort, fasttrack, tracktrack]
track_high_thresh	0.25		Detection confidence threshold for first-stage (high-confidence) association; [0.0, 1.0]
track_low_thresh	0.1		Detection confidence threshold for second-stage (low-confidence) recovery; [0.0, 1.0]
new_track_thresh	0.25		Minimum confidence to initialise a new track; higher reduces false track initiations; [0.0, 1.0]
track_buffer	30		Frames to keep a lost track alive before deletion; higher tolerates longer occlusions; [1, inf)
match_thresh	0.8		Max association cost (1 - IoU) for track-detection matching; higher = looser (accepts lower-IoU matches); [0.0, 1.0]
fuse_score	true		Fuse detection confidence with the IoU cost matrix; improves weak-detection robustness; [true, false]

FastTracker specific (occlusion handling)

Key	Default	CLI	Description
reset_velocity_offset_occ	5		History frames to roll back for restoring Kalman velocity at occlusion onset; [0, inf)
reset_pos_offset_occ	3		History frames to roll back for restoring Kalman position at occlusion onset; [0, inf)
enlarge_bbox_occ	1.1		One-shot bbox-height scale while occluded (widens the search region); [1.0, inf)
dampen_motion_occ	0.5		Velocity dampening factor applied while occluded; [0.0, 1.0]
active_occ_to_lost_thresh	10		Max consecutive occluded frames before a track is marked lost; [1, inf)
occ_cover_thresh	0.7		Fraction of a track's area covered by another to declare occlusion; [0.0, 1.0]
occ_reappear_window	40		Frames a recently-occluded lost track stays re-findable; [1, inf)
init_iou_suppress	0.7		Suppress new-track init if IoU with any active track >= this (1.0 disables); [0.0, 1.0]

tracker.tracktrack

TrackTrack — multi-cue cost (HMIoU + ReID + confidence + angle) with iterative assignment; optional ReID/GMC.

Key	Default	CLI	Description
tracker_type	tracktrack		Tracker backend; [botsort, bytetrack, ocsort, deepocsort, fasttrack, tracktrack]
track_high_thresh	0.6		Detection confidence threshold for first-stage (high-confidence) association; [0.0, 1.0]
track_low_thresh	0.25		Detection confidence threshold for second-stage (low-confidence) recovery; [0.0, 1.0]
new_track_thresh	0.7		Minimum confidence to initialise a new track via track-aware initialisation (TAI); [0.0, 1.0]
track_buffer	30		Frames to keep a lost track alive before deletion; higher tolerates longer occlusions; [1, inf)
match_thresh	0.7		Initial cost gate for iterative assignment; higher = looser (accepts higher-cost matches); [0.0, 1.0]
lost_match_thr	0.0		Relaxed rebind-cost gate for still-Lost tracks; 0 disables the second pass; raise (e.g. 0.9) for long-occlusion scenes; [0.0, 1.0]

Association weights

Key	Default	CLI	Description
iou_weight	0.5		Weight of the HMIoU distance in the cost matrix; [0.0, 1.0]
reid_weight	0.5		Weight of the cosine distance (HMIoU fallback if no ReID) in the cost matrix; [0.0, 1.0]
conf_weight	0.1		Weight of the confidence distance in the cost matrix; [0.0, 1.0]
angle_weight	0.05		Weight of the corner-angle distance in the cost matrix; [0.0, 1.0]

Iterative assignment

Key	Default	CLI	Description
penalty_p	0.2		Cost penalty applied to low-confidence detections; [0.0, 1.0]
penalty_q	0.4		Cost penalty applied to deleted/recovered detections; [0.0, 1.0]
reduce_step	0.05		Threshold reduction applied per iteration; [0.0, 1.0]

Track-Aware Initialisation (TAI)

Key	Default	CLI	Description
tai_thr	0.55		IoU threshold for TAI non-maximum suppression; [0.0, 1.0]
min_track_len	3		Minimum history length before a track is confirmed; [1, inf)

Global motion compensation

Key	Default	CLI	Description
gmc_method	sparseOptFlow		Global motion compensation method; choices: [sparseOptFlow, orb, sift, ecc, none]

ReID (appearance-based re-identification)

Key	Default	CLI	Description
with_reid	false		Enable the ReID appearance model; requires extra weights and increases compute; [true, false]
model	auto		ReID model name or path; "auto" uses detector-derived features if available; string