track is now a thin Python tool around the ubon_cstuff / ubon_pycstuff tracking pipeline. It is responsible for:

• loading input sequence metadata files such as MOT-style JSON/INI annotations
• running the upyc tracker on those inputs
• evaluating results with MOT metrics
• replaying tracked runs with debug overlays
• comparing configs and searching parameters
• reading and writing the canonical UBTRK2 tracker-run format

The repo no longer supports utrack, bytetrack, or botsort.

git clone https://github.com/ubonpartners/track.git
cd track
conda env create -f environment.yml
conda activate track
python track.py --help

Runtime requirements:

• ubon_pycstuff / ubon_cstuff for tracking and optional C metrics
• ffmpeg on PATH for MP4 → H.264 conversion in the upyc path
• datasets reachable under /mldata/... or via equivalent local layout

These remain supported as tracking inputs:

• MOT seqinfo.ini + gt/gt.txt
• JSON/YAML annotation files used as input sequence metadata, for example /mldata/tracking/mot/annotation/MOT17-05.json
• Caltech .vbb

These are input formats, not the canonical stored tracker-result format.

Tracked runs are stored in the canonical UBTRK2 container implemented in stuff.ubtrk2.

Container layout:

1. top-level ubtf box (file header/version)
2. top-level meta box (UTF-8 YAML metadata payload)
3. repeated top-level fram boxes (one frame per processed frame)

The same frame-record schema is intended for:

• disk persistence
• network transport
• offline tracker-component analysis

The metadata payload is UTF-8 YAML with stable string keys. Current keys written by track include:

• schema_version
• kind
• source_video
• frame_rate
• width
• height
• classes
• payload_encoding

Each fram box contains typed child boxes. Current frame payload includes:

• fhdr: frame header (frame_time, result_type, motion_score, motion_roi, inference_roi)
• trks: tracked objects map
• dets: optional detector output list
• dbug: debug entry map
• imgp: source image path (optional)
• xtra: extension map for forward-compatible fields

objects is a map keyed by track_id.

Current stored object fields use detector-aligned names:

• class
• confidence
• box
• subbox
• subbox_conf
• face_points
• pose_points
• attrs
• reid_vector
• face_embedding
• clip_embedding
• face_jpeg
• clip_jpeg
• fiqa_score

debug is a map of named debug entries. Viewer-supported typed entries currently include:

• detections
• roi
• box_prediction
• motion_field
• cost_map

Large arrays, vectors, embeddings, and JPEG blobs are stored inline as typed payload wrappers rather than in sidecar files.

For low-level container and payload wrapper documentation, see the stuff repo README and stuff/stuff/ubtrk2.py.

python track.py --view --trackset /path/to/input.json
python track.py --view --trackset /path/to/run.ubtrk2

The viewer accepts:

• input sequence metadata files
• UBTRK2 tracked-run files

python track.py \
  --track \
  --trackset /mldata/tracking/mot/annotation/MOT17-05.json \
  --config /mldata/config/track/trackers/uc_v10.yaml \
  --save-trackset /tmp/MOT17-05.ubtrk2 \
  --display

This will:

• load the input sequence metadata
• run the upyc tracker
• compute metrics
• optionally display the run
• optionally save the full tracked run in UBTRK2 format

python track.py --test configs/tests.yaml

python track.py --compare compare.yaml --trackset /mldata/.../annotation.json

python track.py --search configs/search.yaml

Search now assumes upyc-style configs only. Parameters are found by key name within the loaded config tree, and ambiguous repeated keys are rejected.

• --test benchmarks tracker configs over datasets with caching and summary tables
• --metrics c uses ubon_pycstuff.c_mota_metrics for faster metric computation
• the replay viewer can inspect saved UBTRK2 runs directly
• the UBTRK2 run format is tested in the shared stuff repo

Format documentation is intentionally split by ownership:

• stuff: authoritative low-level UBTRK2 container and payload encoding docs
• track: how tracker runs use that format for replay, metrics, and analysis
• ubon_cstuff: runtime result/debug schema emitted before serialization

See also:

• TRACKER_DEBUG.md

Dual license:

• AGPL (non-commercial)
• Ubon Cooperative License (https://github.com/ubonpartners/license/blob/main/LICENSE)

Questions? contact bernandocribbenza@gmail.com (subject yolo-dpa question).