Skip to content

HybridSort

Paper: Hybrid-SORT: Weak Cues Matter for Online Multi-Object Tracking

Hybrid-SORT argues that MOT pipelines lean too heavily on strong cues such as appearance and overlap, even though those cues often fail together during heavy occlusion. The paper supplements them with weaker but cheap signals such as velocity direction, confidence, and height state, then combines those cues in a training-free online tracker. That makes the method attractive when association needs extra structure without turning into a much heavier offline system.

Python AABB mode also supports optional EdgeTAM mask guidance with --tracker hybridsort --tracker-backend python --asso-func iou --edgetam --mask-guidance-weights edgetam.pt. It requires IoU association and per_class=False, retains this tracker's existing association rules, and adds temporal model inference. Accuracy gains have not been established for this extension.

What BoxMOT Needs For HybridSort

  • A detector plus appearance embeddings when use_embeddings=True. The Python implementation can generate missing embeddings from a supplied Frame or consume embeddings already attached to Detections.
  • Supports both AABB and OBB detections in BoxMOT.
  • A good fit when you want richer association than OC-SORT or BoT-SORT-style matching, especially on crowded MOT benchmarks.

Direct construction accepts reid=ReIDConfig(...) or a prebuilt AppearanceEncoder, as described in the Python API.

Tracker YAML profiles and Python construction use lowercase option names: eg_weight_high_score, eg_weight_low_score, tcm_first_step, tcm_byte_step, and tcm_byte_step_weight. Tuned profiles use these same names.

Python API

Pass algorithm settings through HybridSortConfig, for example HybridSort(config=HybridSortConfig(det_thresh=0.5)). Direct construction and create_tracker("hybridsort") use the same algorithm defaults. See the tracker configuration guide for presets and component settings.

Bases: TrackerConfig

Configure HybridSORT association, confidence prediction, and appearance memory.

Shared history and association settings are inherited from TrackerConfig.

Parameters:

  • motion_fusion (str, default: 'off' ) –

    First-pass Kalman association mode: off, gate, or blend.

  • motion_fusion_lambda (float, default: 0.98 ) –

    Existing-cost weight when motion fusion blends costs.

  • motion_fusion_only_position (bool, default: False ) –

    Gate centers instead of full box geometry.

  • fuse_detection_score (bool, default: False ) –

    Weight first-pass geometry by detector confidence.

  • fuse_iou (bool, default: False ) –

    Fuse first-pass appearance costs with IoU before weighting.

  • cmc_method (str | None, default: 'ecc' ) –

    Camera-motion compensation method; None disables CMC.

  • use_embeddings (bool, default: True ) –

    Use supplied appearance embeddings, generating missing embeddings from image frames with the configured ReID backend.

  • low_thresh (float, default: 0.1 ) –

    Lower detection confidence bound for second-pass matching.

  • delta_t (int, default: 4 ) –

    Observation lookback in frames for estimating motion direction.

  • inertia (float, default: 0.07385224556640951 ) –

    Weight of observed velocity direction in AABB matching.

  • use_byte (bool, default: False ) –

    Enable a second association pass for low-confidence detections.

  • longterm_bank_length (int, default: 270 ) –

    Number of appearance features retained per AABB track.

  • alpha (float, default: 0.9189916764734039 ) –

    Previous-embedding weight in feature smoothing; higher values retain more history. Adaptive smoothing also incorporates confidence.

  • adapfs (bool, default: True ) –

    Enable confidence-adaptive feature smoothing for AABB tracks.

  • track_thresh (float, default: 0.3190991353484191 ) –

    Clamp separating high and low AABB confidence predictions; does not select input detections.

  • confidence_floor (float, default: 0.1 ) –

    Lower clamp for the low AABB confidence prediction; must not exceed track_thresh.

  • eg_weight_high_score (float, default: 3.8961609177336562 ) –

    Appearance-distance weight for high-confidence matches.

  • eg_weight_low_score (float, default: 0.5096125821683565 ) –

    Appearance-distance weight for low-confidence AABB matches.

  • tcm_first_step (bool, default: True ) –

    Enable the first AABB association pass with motion-direction cues.

  • tcm_byte_step (bool, default: True ) –

    Add a confidence-difference penalty to low-score AABB matching.

  • tcm_byte_step_weight (float, default: 1.0 ) –

    Weight of that low-score confidence-difference penalty.

  • with_longterm_reid (bool, default: True ) –

    Include the AABB long-term appearance bank during matching.

  • longterm_reid_weight (float, default: 1.9752492019041523 ) –

    Contribution of long-term appearance distance in AABB matching.

  • with_longterm_reid_correction (bool, default: True ) –

    Reject AABB matches using appearance-distance gates.

  • longterm_reid_correction_thresh (float, default: 0.11310432273756706 ) –

    Appearance-distance gate for high-score matches; in OBB mode, good appearance may rescue a poor geometry match.

  • longterm_reid_correction_thresh_low (float, default: 0.3479740001301599 ) –

    Appearance-distance gate for low-score AABB matches when correction is enabled.

  • det_thresh (float, default: 0.38633684113126876 ) –

    Minimum detection confidence for the shared tracking kernel.

__post_init__ 

__post_init__() -> None

Validate scalar fields and the confidence prediction interval.

Bases: BoxTracker

Track AABB or OBB detections using motion, confidence, and optional appearance.

Attributes:

  • use_embeddings (bool) –

    Whether appearance features are enabled.

  • cmc –

    Camera-motion compensation method.

  • active_tracks (list[KalmanBoxTracker]) –

    Currently active tracks.

Detection selection uses the shared det_thresh. The OBB path uses geometric and appearance matching without the AABB confidence-prediction, TCM, or long-term-bank stages.

Parameters:

  • config (HybridSortConfig | None, default: None ) –

    Immutable algorithm settings. None selects HybridSortConfig defaults.

  • kalman (KalmanConfig | None, default: None ) –

    Immutable filter noise, timing, and supported behavior settings. None preserves tracker defaults.

  • reid (ReIDConfig | AppearanceEncoder | None, default: None ) –

    Immutable encoder configuration or a canonical appearance encoder. Missing embeddings are generated lazily; None selects the default encoder.

  • **kwargs (Unpack[BoxTrackerOptions], default: {} ) –

    Runtime per_class, is_obb, class_ids, class_names, mask_guidance, and edgetam settings.