Tracker Settings

The tracker settings decide how detections become tracks. They are shared by Video, Realtime and Batch Tracking, saved as a versioned YAML file, and written into the JSON beside every result, so a run can always be repeated.

Open the settings window with Settings on the start screen, Settings… on any workflow screen, or Tracker → Settings….

The settings window

Applying does not re-run anything by itself. What it means depends on the screen:

The main settings

More

The cost of matching a detection to a track is distance_weight × distance/gate + iou_weight × (1 − IoU) + axis_weight × axis + size_weight × size, each term between 0 and 1. A pair costing distance_weight + iou_weight or more is never made. None of these weights is a universal constant: compare settings with the Benchmark before changing them.

The Kalman noise levels are relative to the box size, so one setting serves a 20-pixel fly and a 200-pixel mouse. Their ratio matters most: with a process noise far above the measurement noise, the velocity follows every jitter of the detector, and animals crossing at speed swap IDs.

Which settings to change

Start from the defaults, track a short video in Video Tracking, and change one thing at a time:

1. Is the number of animals fixed? Set Number of animals. This is the most effective setting when it applies: the number of IDs can then never exceed it. In a crowded arena especially, give it whenever it is known — without it, a box around two touching animals that the detector scores above Trusted confidence can still start a track of its own.
2. Are the classes behaviours or animals? Behaviours of one animal: leave Match within class only off. Different animals (for example, males and females labelled as separate classes): turn it on.
3. Do IDs break when an animal moves fast? Raise Max distance — it is in pixels, so it depends on your camera’s magnification and frame rate.
4. Do IDs jump to a neighbouring animal? Lower Max distance.
5. Is the detector missing animals for a while? Raise Max age, so a track keeps its ID through longer gaps.
6. Do short-lived IDs appear on false detections? Raise Min hits, or Trusted confidence.

After each change, Apply and Re-track, and look at the number of track IDs and at the frames where IDs are created and lost.

The settings file

yoru-tracker config prints the defaults; Save… in the window writes the settings shown.

uv run yoru-tracker config > tracker.yaml

config_version: 2
tracker:
  mode: lite
  lifecycle:
    max_age: 10
    min_hits: 2
    population: 0
  association:
    distance_weight: 1.0
    iou_weight: 1.0
    axis_weight: 0.25
    size_weight: 0.0
    max_distance: 100.0
    min_iou: 0.0
    class_aware: false
    recovery: true
    recovery_gate_scale: 3.0
    high_confidence: 0.5
    low_confidence_iou: 0.5
    duplicate_iou: 0.5
    hidden_guard: true
  kalman:
    enabled: true
    process_noise: 0.2
    measurement_noise: 0.1
  advanced:
    reid: false
    occlusion_recovery: false
  log_events: false

A file may give only some keys; the rest take their defaults. For a pair of flies in a chamber:

config_version: 2
tracker:
  mode: lite
  lifecycle:
    max_age: 10
    min_hits: 2
    population: 2
  association:
    max_distance: 100.0

Use it with Load… in the window, or --config on the command line. JSON files with the same structure are read too.

Loading is strict

A setting that is wrong is an error naming it, never a silent default — a misspelt max_age that quietly fell back to 10 would change every ID in the output. All the problems of a file are listed at once:

• an unknown key (unknown key lifecycle.max_ages);
• a value of the wrong type, or .nan / .inf;

• a value out of range:

  Key	Allowed
  max_age, population	≥ 0
  min_hits	≥ 1
  the four weights	≥ 0, with distance_weight + iou_weight > 0
  max_distance	> 0
  min_iou, high_confidence, low_confidence_iou, duplicate_iou	0 to 1
  recovery_gate_scale	≥ 1
  process_noise, measurement_noise	> 0

• an unsupported config_version;
• an advanced.* option with a mode other than advanced.

Version 1 files

config_version: 1 files were written before high_confidence, duplicate_iou and hidden_guard existed. They are read with these three off (0, 0, false), so they track exactly as they did when they were written, and are saved again as version 2.

Tracker modes

Trackers from installed plugins are listed as well; see Tracker API.