+
+
+
+
+
+`trackers` gives you clean, modular re-implementations of leading multi-object tracking algorithms released under the permissive Apache 2.0 license. You combine them with any detection model you already use.
+
+## Install
+
+You can install and use `trackers` in a [**Python>=3.10**](https://www.python.org/) environment. For detailed installation instructions, including installing from source and setting up a local development environment, check out our [install](learn/install.md) page.
+
+!!! example "Installation"
+
+ [](https://badge.fury.io/py/trackers)
+ [](https://pypistats.org/packages/trackers)
+ [](https://github.com/roboflow/trackers/blob/release/stable/LICENSE.md)
+ [](https://badge.fury.io/py/trackers)
+
+ === "pip"
+
+ ```bash
+ pip install trackers
+ ```
+
+ === "uv"
+
+ ```bash
+ uv pip install trackers
+ ```
+
+## Tutorials
+
+
+
+
+
+- **How to Track Objects with SORT**
+
+ ---
+
+ [](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-track-objects-with-sort-tracker.ipynb)
+
+ End-to-end example showing how to run RF-DETR detection with the SORT tracker.
+
+ [:simple-googlecolab: Run Google Colab](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-track-objects-with-sort-tracker.ipynb)
+
+- **How to Track Objects with ByteTrack**
+
+ ---
+
+ [](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-track-objects-with-bytetrack-tracker.ipynb)
+
+ End-to-end example showing how to run RF-DETR detection with the ByteTrack tracker.
+
+ [:simple-googlecolab: Run Google Colab](https://colab.research.google.com/github/roboflow-ai/notebooks/blob/main/notebooks/how-to-track-objects-with-bytetrack-tracker.ipynb)
+
+
+
+## Tracking Algorithms
+
+Clean, modular implementations of leading trackers. For comparisons, see the [tracker comparison](trackers/comparison.md) page.
+
+| Algorithm | MOT17 HOTA | SportsMOT HOTA | SoccerNet HOTA |
+| :-------: | :--------: | :------------: | :------------: |
+| SORT | 58.4 | 70.9 | 81.6 |
+| ByteTrack | 60.1 | **73.0** | **84.0** |
+| OC-SORT | **61.9** | 71.5 | 78.6 |
+| BoT-SORT | — | — | — |
+| McByte | — | — | — |
+
+## Integration
+
+With a modular design, `trackers` lets you combine object detectors from different libraries with the tracker of your choice. See the [Track guide](learn/track.md) for CLI usage and more options. These examples use `opencv-python` for decoding and display.
+
+=== "RF-DETR"
+
+ ```python
+ import cv2
+ from rfdetr import RFDETRNano
+ from trackers import ByteTrackTracker
+
+ model = RFDETRNano()
+ tracker = ByteTrackTracker()
+
+ cap = cv2.VideoCapture("source.mp4")
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ frame_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+ detections = model.predict(frame_rgb)
+ detections = tracker.update(detections)
+ ```
+
+=== "Inference"
+
+ ```python
+ import cv2
+ import supervision as sv
+ from inference import get_model
+ from trackers import ByteTrackTracker
+
+ model = get_model(model_id="rfdetr-nano")
+ tracker = ByteTrackTracker()
+
+ cap = cv2.VideoCapture("source.mp4")
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ result = model.infer(frame)[0]
+ detections = sv.Detections.from_inference(result)
+ detections = tracker.update(detections)
+ ```
+
+=== "Ultralytics"
+
+ ```python
+ import cv2
+ import supervision as sv
+ from ultralytics import YOLO
+ from trackers import ByteTrackTracker
+
+ model = YOLO("yolo11n.pt")
+ tracker = ByteTrackTracker()
+
+ cap = cv2.VideoCapture("source.mp4")
+ while True:
+ ret, frame = cap.read()
+ if not ret:
+ break
+
+ result = model(frame)[0]
+ detections = sv.Detections.from_ultralytics(result)
+ detections = tracker.update(detections)
+ ```
diff --git a/docs/javascripts/cli_builder_framework.js b/docs/javascripts/cli_builder_framework.js
new file mode 100644
index 0000000..3cddd07
--- /dev/null
+++ b/docs/javascripts/cli_builder_framework.js
@@ -0,0 +1,696 @@
+/**
+ * Reusable terminal-style CLI command builder framework.
+ * Use this as a base and provide command-specific configuration.
+ */
+(function registerTrackersCLIBuilderFramework(global) {
+ "use strict";
+
+ if (global.TrackersCLIBuilderFramework) {
+ return;
+ }
+
+ class TerminalCommandBuilder {
+ constructor(options) {
+ this.root = options.root;
+ this.defaults = { ...(options.defaults || {}) };
+ this.numericFields = { ...(options.numericFields || {}) };
+ this.state = { ...(options.initialState || {}) };
+ this.generateCommand = options.generateCommand || (() => "");
+ this.getValidationErrors = options.getValidationErrors || (() => []);
+ this.renderBody = options.renderBody || (() => {});
+ this.inputSanitizers = options.inputSanitizers || {};
+ this.onInputChange = options.onInputChange || null;
+ this.onCheckboxChange = options.onCheckboxChange || null;
+ this.onSelectorChange = options.onSelectorChange || null;
+ this.copyButtonFeedbackMs = options.copyButtonFeedbackMs || 1200;
+
+ this.ids = {
+ command: "cb-command",
+ errors: "cb-errors",
+ ...(options.ids || {}),
+ };
+ this.containerClassName = options.containerClassName || "cb-container";
+
+ this.commandEl = null;
+ this.errorsEl = null;
+
+ this.numericHoldTimeout = null;
+ this.numericHoldInterval = null;
+ this.activeNumericHoldButton = null;
+ this.eventsBound = false;
+
+ this.boundHandlePointerDown = this.handlePointerDown.bind(this);
+ this.boundHandleClick = this.handleClick.bind(this);
+ this.boundHandleChange = this.handleChange.bind(this);
+ this.boundHandleInput = this.handleInput.bind(this);
+ this.boundClearNumericHold = this.clearNumericHold.bind(this);
+ this.boundVisibilityChange = this.handleVisibilityChange.bind(this);
+ this.boundApplyNativeMetrics = this.applyNativeMetrics.bind(this);
+ }
+
+ init() {
+ if (!this.root) return false;
+ this.render();
+ this.bindEvents();
+ this.syncNativeMetricsWithRetries();
+ window.addEventListener("resize", this.boundApplyNativeMetrics);
+ return true;
+ }
+
+ destroy() {
+ this.unbindEvents();
+ window.removeEventListener("resize", this.boundApplyNativeMetrics);
+ this.clearNumericHold();
+ this.root = null;
+ this.commandEl = null;
+ this.errorsEl = null;
+ }
+
+ render() {
+ if (!this.root) return;
+
+ this.root.innerHTML = "";
+ this.root.className = this.containerClassName;
+
+ const codeBlock = document.createElement("div");
+ codeBlock.className = "cb-code-block language-text highlight";
+
+ const pre = document.createElement("pre");
+ const code = document.createElement("code");
+ code.className = "cb-code";
+
+ this.renderBody(code, this.getRenderApi());
+
+ const errors = document.createElement("div");
+ errors.id = this.ids.errors;
+ errors.className = "cb-errors";
+ code.appendChild(errors);
+
+ pre.appendChild(code);
+ codeBlock.appendChild(pre);
+ this.root.appendChild(codeBlock);
+
+ const output = this.createCommandOutputBlock();
+ this.root.appendChild(output.block);
+
+ this.commandEl = output.commandCode;
+ this.errorsEl = errors;
+
+ this.refresh();
+ }
+
+ getRenderApi() {
+ return {
+ ids: this.ids,
+ defaults: this.defaults,
+ numericFields: this.numericFields,
+ state: this.state,
+ root: this.root,
+ createHeader: this.createHeader.bind(this),
+ createSelector: this.createSelector.bind(this),
+ createCheckbox: this.createCheckbox.bind(this),
+ createTextInputRow: this.createTextInputRow.bind(this),
+ createNumericInputRow: this.createNumericInputRow.bind(this),
+ createSelectorRow: this.createSelectorRow.bind(this),
+ };
+ }
+
+ createCommandOutputBlock() {
+ const commandBlock = document.createElement("div");
+ commandBlock.className = "language-text highlight cb-output";
+
+ const commandPre = document.createElement("pre");
+ commandPre.appendChild(document.createElement("span"));
+
+ const commandCode = document.createElement("code");
+ commandCode.id = this.ids.command;
+ commandPre.appendChild(commandCode);
+ commandBlock.appendChild(commandPre);
+
+ const commandNav = document.createElement("nav");
+ commandNav.className = "md-code__nav";
+
+ const copyButton = document.createElement("button");
+ copyButton.type = "button";
+ copyButton.className = "md-code__button";
+ copyButton.title = "Copy to clipboard";
+ copyButton.setAttribute("aria-label", "Copy to clipboard");
+ copyButton.setAttribute("data-md-type", "copy");
+ copyButton.setAttribute("data-clipboard-target", `#${this.ids.command}`);
+ copyButton.addEventListener("click", async () => {
+ // Fallback clipboard handling for dynamically-rendered blocks.
+ const commandText = (this.commandEl?.textContent || "").replace(/\\\n\s+/g, " ");
+ if (!commandText) return;
+ try {
+ await navigator.clipboard.writeText(commandText);
+ copyButton.classList.add("md-code__button--active");
+ window.setTimeout(() => {
+ copyButton.classList.remove("md-code__button--active");
+ }, this.copyButtonFeedbackMs);
+ } catch (_error) {
+ // Native Material copy handler remains available when present.
+ }
+ });
+
+ commandNav.appendChild(copyButton);
+ commandBlock.appendChild(commandNav);
+
+ return { block: commandBlock, commandCode };
+ }
+
+ refresh() {
+ if (this.commandEl) {
+ this.commandEl.textContent = this.generateCommand(this.state, this);
+ }
+
+ if (!this.errorsEl) return;
+
+ const errors = this.getValidationErrors(this.state, this);
+ if (errors.length > 0) {
+ this.errorsEl.innerHTML = errors
+ .map((errorText) => `# ${errorText}`)
+ .join("\n");
+ this.errorsEl.style.display = "block";
+ } else {
+ this.errorsEl.style.display = "none";
+ }
+ }
+
+ bindEvents() {
+ if (this.eventsBound || !this.root) return;
+
+ this.root.addEventListener("pointerdown", this.boundHandlePointerDown);
+ this.root.addEventListener("click", this.boundHandleClick);
+ this.root.addEventListener("change", this.boundHandleChange);
+ this.root.addEventListener("input", this.boundHandleInput);
+
+ document.addEventListener("pointerup", this.boundClearNumericHold);
+ document.addEventListener("pointercancel", this.boundClearNumericHold);
+ window.addEventListener("blur", this.boundClearNumericHold);
+ document.addEventListener("visibilitychange", this.boundVisibilityChange);
+
+ this.eventsBound = true;
+ }
+
+ unbindEvents() {
+ if (!this.eventsBound || !this.root) return;
+
+ this.root.removeEventListener("pointerdown", this.boundHandlePointerDown);
+ this.root.removeEventListener("click", this.boundHandleClick);
+ this.root.removeEventListener("change", this.boundHandleChange);
+ this.root.removeEventListener("input", this.boundHandleInput);
+
+ document.removeEventListener("pointerup", this.boundClearNumericHold);
+ document.removeEventListener("pointercancel", this.boundClearNumericHold);
+ window.removeEventListener("blur", this.boundClearNumericHold);
+ document.removeEventListener("visibilitychange", this.boundVisibilityChange);
+
+ this.eventsBound = false;
+ }
+
+ handleVisibilityChange() {
+ if (document.hidden) {
+ this.clearNumericHold();
+ }
+ }
+
+ handlePointerDown(event) {
+ const numericButton = event.target.closest(".cb-num-btn");
+ if (!numericButton) return;
+ if (event.pointerType === "mouse" && event.button !== 0) return;
+
+ event.preventDefault();
+ this.startNumericHold(numericButton);
+ }
+
+ handleClick(event) {
+ const selectorButton = event.target.closest(".cb-selector");
+ if (selectorButton) {
+ this.handleSelectorSelection(selectorButton);
+ return;
+ }
+
+ const numericButton = event.target.closest(".cb-num-btn");
+ if (!numericButton) return;
+
+ // Pointer interaction is handled by pointerdown to support hold-repeat.
+ // Keep click handling for keyboard activation.
+ if (event.detail !== 0) return;
+ this.stepNumericField(numericButton.dataset.key, numericButton.dataset.action);
+ }
+
+ handleSelectorSelection(selectorButton) {
+ const group = selectorButton.dataset.group;
+ const value = selectorButton.dataset.value;
+ if (!group) return;
+
+ this.state[group] = value;
+ this.updateSelectorGroup(group, value);
+
+ if (typeof this.onSelectorChange === "function") {
+ this.onSelectorChange({
+ group,
+ value,
+ button: selectorButton,
+ builder: this,
+ state: this.state,
+ });
+ }
+
+ this.refresh();
+ }
+
+ updateSelectorGroup(group, selectedValue) {
+ this.root.querySelectorAll(`.cb-selector[data-group="${group}"]`).forEach((button) => {
+ const isActive = button.dataset.value === selectedValue;
+ button.classList.toggle("cb-selector--active", isActive);
+ });
+ }
+
+ handleChange(event) {
+ const input = event.target;
+ const key = input?.dataset?.key;
+ if (!key) return;
+
+ if (input.type === "checkbox") {
+ this.processCheckboxInput(input);
+ return;
+ }
+
+ this.processValueInput(input, { isCommit: true });
+ }
+
+ handleInput(event) {
+ const input = event.target;
+ const key = input?.dataset?.key;
+ if (!key || input.type === "checkbox") return;
+
+ this.processValueInput(input, { isCommit: false });
+ }
+
+ processCheckboxInput(input) {
+ const key = input.dataset.key;
+ const checked = input.checked;
+
+ this.state[key] = checked;
+
+ const checkbox = input.closest(".cb-checkbox");
+ if (checkbox) {
+ this.updateCheckboxVisual(checkbox, checked);
+ }
+
+ this.toggleCollapsibleForKey(key, checked);
+
+ if (typeof this.onCheckboxChange === "function") {
+ this.onCheckboxChange({ key, checked, input, builder: this, state: this.state });
+ }
+
+ this.refresh();
+ }
+
+ processValueInput(input, options) {
+ const key = input.dataset.key;
+ const isCommit = Boolean(options?.isCommit);
+
+ const sanitizedValue = this.sanitizeInputValue(key, input.value, input, isCommit);
+ if (sanitizedValue !== input.value) {
+ input.value = sanitizedValue;
+ }
+
+ this.state[key] = input.value;
+
+ if (input.classList.contains("cb-num-input")) {
+ this.updateNumericModifiedState(input);
+ }
+
+ if (typeof this.onInputChange === "function") {
+ this.onInputChange({
+ key,
+ value: input.value,
+ input,
+ isCommit,
+ builder: this,
+ state: this.state,
+ });
+ }
+
+ this.refresh();
+ }
+
+ sanitizeInputValue(key, value, input, isCommit) {
+ const sanitizer = this.inputSanitizers[key];
+ if (typeof sanitizer !== "function") {
+ return value;
+ }
+ return sanitizer(value, { key, input, isCommit, state: this.state, builder: this });
+ }
+
+ updateCheckboxVisual(checkbox, checked) {
+ const marker = checkbox.querySelector(".cb-check-marker");
+ if (marker) {
+ marker.textContent = checked ? "[x]" : "[ ]";
+ }
+ checkbox.classList.toggle("cb-checkbox--active", checked);
+ }
+
+ toggleCollapsibleForKey(key, visible) {
+ const collapsible = this.root.querySelector(`[data-collapsible-for="${key}"]`);
+ if (collapsible) {
+ collapsible.style.display = visible ? "block" : "none";
+ }
+ }
+
+ setCheckboxField(key, checked, options = {}) {
+ const shouldRefresh = options.refresh !== false;
+ this.state[key] = checked;
+
+ const input = this.root.querySelector(`input[type="checkbox"][data-key="${key}"]`);
+ if (input) {
+ input.checked = checked;
+ const checkbox = input.closest(".cb-checkbox");
+ if (checkbox) {
+ this.updateCheckboxVisual(checkbox, checked);
+ }
+ }
+
+ this.toggleCollapsibleForKey(key, checked);
+
+ if (shouldRefresh) {
+ this.refresh();
+ }
+ }
+
+ setElementVisibleById(id, visible) {
+ const target = this.root.querySelector(`#${id}`);
+ if (target) {
+ target.style.display = visible ? "block" : "none";
+ }
+ }
+
+ getNumericInputForKey(key) {
+ return this.root.querySelector(`input[data-key="${key}"].cb-num-input`);
+ }
+
+ updateNumericModifiedState(input) {
+ const isModified = input.value !== input.dataset.default;
+ input.classList.toggle("cb-modified", isModified);
+ }
+
+ stepNumericField(key, action) {
+ const input = this.getNumericInputForKey(key);
+ if (!input) return;
+
+ const step = parseFloat(input.dataset.step);
+ const min = parseFloat(input.dataset.min);
+ const max = parseFloat(input.dataset.max);
+ const decimals = parseInt(input.dataset.decimals, 10);
+
+ let value = parseFloat(input.value);
+ if (Number.isNaN(value)) {
+ value = parseFloat(input.dataset.default);
+ }
+ if (Number.isNaN(value)) {
+ value = min;
+ }
+
+ if (action === "increment") {
+ value = Math.min(max, value + step);
+ } else {
+ value = Math.max(min, value - step);
+ }
+
+ const nextValue = decimals === 0 ? String(Math.round(value)) : value.toFixed(decimals);
+
+ this.state[key] = nextValue;
+ input.value = nextValue;
+ this.updateNumericModifiedState(input);
+
+ this.refresh();
+ }
+
+ startNumericHold(button) {
+ this.clearNumericHold();
+
+ this.activeNumericHoldButton = button;
+ this.stepNumericField(button.dataset.key, button.dataset.action);
+
+ this.numericHoldTimeout = window.setTimeout(() => {
+ this.numericHoldInterval = window.setInterval(() => {
+ if (!this.activeNumericHoldButton || !this.root.contains(this.activeNumericHoldButton)) {
+ this.clearNumericHold();
+ return;
+ }
+
+ this.stepNumericField(
+ this.activeNumericHoldButton.dataset.key,
+ this.activeNumericHoldButton.dataset.action
+ );
+ }, 90);
+ }, 350);
+ }
+
+ clearNumericHold() {
+ if (this.numericHoldTimeout !== null) {
+ window.clearTimeout(this.numericHoldTimeout);
+ this.numericHoldTimeout = null;
+ }
+ if (this.numericHoldInterval !== null) {
+ window.clearInterval(this.numericHoldInterval);
+ this.numericHoldInterval = null;
+ }
+ this.activeNumericHoldButton = null;
+ }
+
+ // Sync sizing metrics from a native MkDocs code block/button.
+ applyNativeMetrics() {
+ if (!this.root) return;
+
+ const refCode =
+ document.querySelector(".tabbed-block .language-text.highlight pre code") ||
+ document.querySelector(".language-text.highlight pre code");
+ if (refCode) {
+ const codeStyles = window.getComputedStyle(refCode);
+ this.root.style.setProperty("--cb-native-code-font-size", codeStyles.fontSize);
+ this.root.style.setProperty("--cb-native-code-line-height", codeStyles.lineHeight);
+ this.root.style.setProperty("--cb-native-code-font-family", codeStyles.fontFamily);
+ }
+
+ const refButton =
+ document.querySelector(".tabbed-block .md-code__button[data-md-type='copy']") ||
+ document.querySelector(".md-code__button[data-md-type='copy']");
+ if (refButton) {
+ const buttonStyles = window.getComputedStyle(refButton);
+ this.root.style.setProperty("--cb-native-copy-button-width", buttonStyles.width);
+ this.root.style.setProperty("--cb-native-copy-button-height", buttonStyles.height);
+ this.root.style.setProperty("--cb-native-copy-button-font-size", buttonStyles.fontSize);
+ }
+
+ const refNav =
+ document.querySelector(".tabbed-block .md-code__nav") || document.querySelector(".md-code__nav");
+ if (refNav) {
+ const navStyles = window.getComputedStyle(refNav);
+ this.root.style.setProperty("--cb-native-copy-nav-padding", navStyles.padding);
+ this.root.style.setProperty("--cb-native-copy-nav-right", navStyles.right);
+ this.root.style.setProperty("--cb-native-copy-nav-top", navStyles.top);
+ this.root.style.setProperty("--cb-native-copy-nav-border-radius", navStyles.borderRadius);
+ }
+ }
+
+ syncNativeMetricsWithRetries() {
+ let attempts = 0;
+ const maxAttempts = 30;
+
+ const tick = () => {
+ this.applyNativeMetrics();
+ attempts += 1;
+ if (attempts < maxAttempts) {
+ window.setTimeout(tick, 100);
+ }
+ };
+
+ tick();
+ }
+
+ createSelector(label, value, group, isSelected) {
+ const button = document.createElement("button");
+ button.type = "button";
+ button.className = `cb-selector ${isSelected ? "cb-selector--active" : ""}`;
+ button.textContent = `[ ${label} ]`;
+ button.dataset.value = value;
+ button.dataset.group = group;
+ return button;
+ }
+
+ createCheckbox(label, key, checked) {
+ const wrapper = document.createElement("label");
+ wrapper.className = `cb-checkbox ${checked ? "cb-checkbox--active" : ""}`;
+
+ const input = document.createElement("input");
+ input.type = "checkbox";
+ input.checked = checked;
+ input.dataset.key = key;
+
+ const marker = document.createElement("span");
+ marker.className = "cb-check-marker";
+ marker.textContent = checked ? "[x]" : "[ ]";
+
+ const text = document.createElement("span");
+ text.className = "cb-check-label";
+ text.textContent = label;
+
+ wrapper.appendChild(input);
+ wrapper.appendChild(marker);
+ wrapper.appendChild(text);
+ return wrapper;
+ }
+
+ createHeader(title) {
+ const header = document.createElement("div");
+ header.className = "cb-header";
+ header.textContent = `# ${title.toUpperCase()}`;
+ return header;
+ }
+
+ createTextInputRow(label, placeholder, key, value, rowClass = "") {
+ const row = document.createElement("div");
+ row.className = `cb-row ${rowClass}`.trim();
+
+ const labelEl = document.createElement("span");
+ labelEl.className = "cb-label";
+ labelEl.textContent = label;
+
+ const equals = document.createElement("span");
+ equals.className = "cb-equals";
+ equals.textContent = "=";
+
+ const valueWrap = document.createElement("span");
+ valueWrap.className = "cb-value-wrap cb-value-wrap--text";
+
+ const leftBracket = document.createElement("span");
+ leftBracket.className = "cb-bracket";
+ leftBracket.textContent = "[";
+
+ const input = document.createElement("input");
+ input.type = "text";
+ input.className = "cb-text-input";
+ input.placeholder = placeholder;
+ input.value = value;
+ input.dataset.key = key;
+ input.dataset.placeholder = placeholder;
+
+ const rightBracket = document.createElement("span");
+ rightBracket.className = "cb-bracket";
+ rightBracket.textContent = "]";
+
+ valueWrap.appendChild(leftBracket);
+ valueWrap.appendChild(input);
+ valueWrap.appendChild(rightBracket);
+
+ row.appendChild(labelEl);
+ row.appendChild(equals);
+ row.appendChild(valueWrap);
+
+ return row;
+ }
+
+ createNumericInputRow(label, key, value, config, rowClass = "") {
+ const row = document.createElement("div");
+ row.className = `cb-row ${rowClass}`.trim();
+
+ const labelEl = document.createElement("span");
+ labelEl.className = "cb-label";
+ labelEl.textContent = label;
+
+ const equals = document.createElement("span");
+ equals.className = "cb-equals";
+ equals.textContent = "=";
+
+ const controls = document.createElement("div");
+ controls.className = "cb-numeric-controls";
+
+ const decButton = document.createElement("button");
+ decButton.type = "button";
+ decButton.className = "cb-num-btn";
+ decButton.textContent = "[-]";
+ decButton.dataset.action = "decrement";
+ decButton.dataset.key = key;
+
+ const valueWrap = document.createElement("span");
+ valueWrap.className = "cb-value-wrap cb-value-wrap--numeric";
+
+ const leftBracket = document.createElement("span");
+ leftBracket.className = "cb-bracket";
+ leftBracket.textContent = "[";
+
+ const input = document.createElement("input");
+ input.type = "text";
+ input.className = "cb-num-input";
+ input.value = value;
+ input.dataset.key = key;
+ input.dataset.step = config.step;
+ input.dataset.min = config.min;
+ input.dataset.max = config.max;
+ input.dataset.decimals = config.decimals;
+ input.dataset.default = Object.prototype.hasOwnProperty.call(this.defaults, key)
+ ? this.defaults[key]
+ : value;
+
+ const rightBracket = document.createElement("span");
+ rightBracket.className = "cb-bracket";
+ rightBracket.textContent = "]";
+
+ const incButton = document.createElement("button");
+ incButton.type = "button";
+ incButton.className = "cb-num-btn";
+ incButton.textContent = "[+]";
+ incButton.dataset.action = "increment";
+ incButton.dataset.key = key;
+
+ valueWrap.appendChild(leftBracket);
+ valueWrap.appendChild(input);
+ valueWrap.appendChild(rightBracket);
+
+ controls.appendChild(decButton);
+ controls.appendChild(valueWrap);
+ controls.appendChild(incButton);
+
+ row.appendChild(labelEl);
+ row.appendChild(equals);
+ row.appendChild(controls);
+
+ return row;
+ }
+
+ createSelectorRow(label, options, group, selectedValue, rowClass = "") {
+ const row = document.createElement("div");
+ row.className = `cb-row ${rowClass}`.trim();
+
+ const labelEl = document.createElement("span");
+ labelEl.className = "cb-label";
+ labelEl.textContent = label;
+
+ const equals = document.createElement("span");
+ equals.className = "cb-equals";
+ equals.textContent = "=";
+
+ const selectors = document.createElement("div");
+ selectors.className = "cb-selectors";
+
+ options.forEach((option) => {
+ selectors.appendChild(
+ this.createSelector(option, option, group, option === selectedValue)
+ );
+ });
+
+ row.appendChild(labelEl);
+ row.appendChild(equals);
+ row.appendChild(selectors);
+
+ return row;
+ }
+ }
+
+ global.TrackersCLIBuilderFramework = {
+ TerminalCommandBuilder,
+ };
+})(window);
diff --git a/docs/javascripts/command_builder.js b/docs/javascripts/command_builder.js
new file mode 100644
index 0000000..ef1b5dd
--- /dev/null
+++ b/docs/javascripts/command_builder.js
@@ -0,0 +1,410 @@
+/**
+ * Track command widget built on top of the reusable CLI builder framework.
+ */
+document.addEventListener("DOMContentLoaded", function () {
+ const root = document.getElementById("command-builder-widget");
+ const framework = window.TrackersCLIBuilderFramework;
+ if (!root || !framework || !framework.TerminalCommandBuilder) return;
+
+ // Default values for reference
+ const defaults = {
+ source: "source.mp4",
+ confidence: "0.5",
+ classes: "",
+ lostTrackBuffer: "30",
+ trackActivationThreshold: "0.25",
+ minimumConsecutiveFrames: "3",
+ minimumIouThreshold: "0.3",
+ output: "",
+ };
+
+ // Field configurations for numeric inputs
+ const numericFields = {
+ confidence: { step: 0.05, min: 0.05, max: 1, decimals: 2 },
+ trackActivationThreshold: { step: 0.05, min: 0.05, max: 1, decimals: 2 },
+ minimumIouThreshold: { step: 0.05, min: 0.05, max: 1, decimals: 2 },
+ lostTrackBuffer: { step: 1, min: 1, max: 999, decimals: 0 },
+ minimumConsecutiveFrames: { step: 1, min: 1, max: 99, decimals: 0 },
+ };
+
+ // State
+ const initialState = {
+ source: "",
+ modelType: "detection",
+ modelSize: "nano",
+ confidence: "0.5",
+ device: "auto",
+ classes: "",
+ tracker: "bytetrack",
+ lostTrackBuffer: "30",
+ trackActivationThreshold: "0.25",
+ minimumConsecutiveFrames: "3",
+ minimumIouThreshold: "0.3",
+ display: false,
+ showBoxes: true,
+ showMasks: false,
+ showConfidence: false,
+ showLabels: false,
+ showIds: true,
+ showTrajectories: false,
+ output: "",
+ overwrite: false,
+ showModelOptions: false,
+ showTrackerOptions: false,
+ };
+
+ // Validation functions
+ function isValidDecimal01(value, min = 0) {
+ if (value === "") return true;
+ const num = parseFloat(value);
+ return !isNaN(num) && num >= min && num <= 1;
+ }
+
+ function isValidPositiveInt(value) {
+ if (value === "") return true;
+ const num = parseInt(value, 10);
+ return !isNaN(num) && num > 0 && String(num) === value;
+ }
+
+ function isValidClasses(value) {
+ return /^[\w,\s]*$/.test(value);
+ }
+
+ // Generate command from state
+ function generateCommand(state) {
+ const parts = ["trackers track"];
+
+ const sourceValue = state.source.trim() || defaults.source;
+ if (sourceValue) {
+ parts.push(`--source ${sourceValue}`);
+ }
+
+ const prefix = state.modelType === "segmentation" ? "rfdetr-seg-" : "rfdetr-";
+ parts.push(`--model ${prefix}${state.modelSize}`);
+
+ if (state.showModelOptions) {
+ if (state.confidence !== defaults.confidence && isValidDecimal01(state.confidence, 0.05)) {
+ parts.push(`--model.confidence ${state.confidence}`);
+ }
+ if (state.device !== "auto") {
+ parts.push(`--model.device ${state.device}`);
+ }
+ if (state.classes && isValidClasses(state.classes)) {
+ parts.push(`--classes ${state.classes}`);
+ }
+ }
+
+ parts.push(`--tracker ${state.tracker}`);
+
+ if (state.showTrackerOptions) {
+ if (state.lostTrackBuffer !== defaults.lostTrackBuffer && isValidPositiveInt(state.lostTrackBuffer)) {
+ parts.push(`--tracker.lost_track_buffer ${state.lostTrackBuffer}`);
+ }
+ if (
+ state.trackActivationThreshold !== defaults.trackActivationThreshold &&
+ isValidDecimal01(state.trackActivationThreshold, 0.05)
+ ) {
+ parts.push(`--tracker.track_activation_threshold ${state.trackActivationThreshold}`);
+ }
+ if (
+ state.minimumConsecutiveFrames !== defaults.minimumConsecutiveFrames &&
+ isValidPositiveInt(state.minimumConsecutiveFrames)
+ ) {
+ parts.push(`--tracker.minimum_consecutive_frames ${state.minimumConsecutiveFrames}`);
+ }
+ if (
+ state.minimumIouThreshold !== defaults.minimumIouThreshold &&
+ isValidDecimal01(state.minimumIouThreshold, 0.05)
+ ) {
+ parts.push(`--tracker.minimum_iou_threshold ${state.minimumIouThreshold}`);
+ }
+ }
+
+ if (state.display) parts.push("--display");
+ if (!state.showBoxes) parts.push("--no-boxes");
+ if (state.showMasks) parts.push("--show-masks");
+ if (state.showConfidence) parts.push("--show-confidence");
+ if (state.showLabels) parts.push("--show-labels");
+ if (!state.showIds) parts.push("--no-ids");
+ if (state.showTrajectories) parts.push("--show-trajectories");
+
+ const outputValue = state.output.trim();
+ if (outputValue) {
+ parts.push(`--output ${outputValue}`);
+ if (state.overwrite) {
+ parts.push("--overwrite");
+ }
+ }
+
+ return parts.join(" \\\n ");
+ }
+
+ // Get validation errors
+ function getValidationErrors(state) {
+ const errors = [];
+
+ if (state.showModelOptions) {
+ if (state.confidence && !isValidDecimal01(state.confidence, 0.05)) {
+ errors.push("Confidence must be between 0.05 and 1");
+ }
+ if (state.classes && !isValidClasses(state.classes)) {
+ errors.push("Classes must contain only names, numbers, commas, and spaces");
+ }
+ }
+
+ if (state.showTrackerOptions) {
+ if (state.lostTrackBuffer && !isValidPositiveInt(state.lostTrackBuffer)) {
+ errors.push("lost_track_buffer must be a positive integer");
+ }
+ if (state.trackActivationThreshold && !isValidDecimal01(state.trackActivationThreshold, 0.05)) {
+ errors.push("track_activation_threshold must be between 0.05 and 1");
+ }
+ if (state.minimumConsecutiveFrames && !isValidPositiveInt(state.minimumConsecutiveFrames)) {
+ errors.push("minimum_consecutive_frames must be a positive integer");
+ }
+ if (state.minimumIouThreshold && !isValidDecimal01(state.minimumIouThreshold, 0.05)) {
+ errors.push("minimum_iou_threshold must be between 0.05 and 1");
+ }
+ }
+
+ return errors;
+ }
+
+ const builder = new framework.TerminalCommandBuilder({
+ root,
+ defaults,
+ numericFields,
+ initialState,
+ ids: {
+ command: "cb-command",
+ errors: "cb-errors",
+ overwrite: "cb-overwrite",
+ },
+ generateCommand,
+ getValidationErrors,
+ inputSanitizers: {
+ classes(value) {
+ return value.replace(/[^\w,\s]/g, "");
+ },
+ },
+ onInputChange({ key, value, isCommit, builder: instance }) {
+ if (key !== "output") return;
+
+ const hasOutput = value.trim() !== "";
+ instance.setElementVisibleById(instance.ids.overwrite, hasOutput);
+
+ if (isCommit && !hasOutput) {
+ instance.setCheckboxField("overwrite", false, { refresh: false });
+ }
+ },
+ renderBody(code, api) {
+ const {
+ ids,
+ state,
+ numericFields: numberConfig,
+ createHeader,
+ createSelector,
+ createCheckbox,
+ createTextInputRow,
+ createNumericInputRow,
+ createSelectorRow,
+ } = api;
+
+ // MODEL Section
+ code.appendChild(createHeader("Model"));
+
+ const modelTypeGrid = document.createElement("div");
+ modelTypeGrid.className = "cb-model-type-grid cb-option-indent";
+
+ const detectionSelector = createSelector(
+ "detection",
+ "detection",
+ "modelType",
+ state.modelType === "detection"
+ );
+ detectionSelector.style.gridColumn = "1";
+ detectionSelector.classList.add("cb-selector--nudge-left");
+
+ const segmentationSelector = createSelector(
+ "segmentation",
+ "segmentation",
+ "modelType",
+ state.modelType === "segmentation"
+ );
+ segmentationSelector.style.gridColumn = "3";
+
+ modelTypeGrid.appendChild(detectionSelector);
+ modelTypeGrid.appendChild(segmentationSelector);
+ code.appendChild(modelTypeGrid);
+
+ const modelSizeGrid = document.createElement("div");
+ modelSizeGrid.className = "cb-model-size-grid cb-option-indent cb-model-size-grid--before-toggle";
+ ["nano", "small", "medium", "large"].forEach((size) => {
+ modelSizeGrid.appendChild(
+ createSelector(size, size, "modelSize", state.modelSize === size)
+ );
+ });
+ code.appendChild(modelSizeGrid);
+
+ // Model Options
+ const modelOptionsToggle = createCheckbox(
+ "options",
+ "showModelOptions",
+ state.showModelOptions
+ );
+ modelOptionsToggle.classList.add("cb-option-indent", "cb-option-toggle");
+ code.appendChild(modelOptionsToggle);
+
+ const modelOptionsContent = document.createElement("div");
+ modelOptionsContent.className = "cb-options cb-option-indent";
+ modelOptionsContent.dataset.collapsibleFor = "showModelOptions";
+ modelOptionsContent.style.display = state.showModelOptions ? "block" : "none";
+ modelOptionsContent.appendChild(
+ createNumericInputRow(
+ "confidence",
+ "confidence",
+ state.confidence,
+ numberConfig.confidence,
+ "cb-row--anchor-3"
+ )
+ );
+ modelOptionsContent.appendChild(
+ createSelectorRow(
+ "device",
+ ["auto", "cpu", "cuda", "mps"],
+ "device",
+ state.device,
+ "cb-row--anchor-3"
+ )
+ );
+ modelOptionsContent.appendChild(
+ createTextInputRow("classes", "person, car", "classes", state.classes, "cb-row--anchor-3")
+ );
+ code.appendChild(modelOptionsContent);
+
+ // TRACKER Section
+ code.appendChild(createHeader("Tracker"));
+
+ const trackerSelectors = document.createElement("div");
+ trackerSelectors.className =
+ "cb-tracker-type-grid cb-option-indent cb-selectors-row--before-toggle";
+ const bytetrackSelector = createSelector(
+ "bytetrack",
+ "bytetrack",
+ "tracker",
+ state.tracker === "bytetrack"
+ );
+ bytetrackSelector.style.gridColumn = "1";
+ const sortSelector = createSelector("sort", "sort", "tracker", state.tracker === "sort");
+ sortSelector.style.gridColumn = "3";
+ trackerSelectors.appendChild(bytetrackSelector);
+ trackerSelectors.appendChild(sortSelector);
+ code.appendChild(trackerSelectors);
+
+ // Tracker Options
+ const trackerOptionsToggle = createCheckbox(
+ "options",
+ "showTrackerOptions",
+ state.showTrackerOptions
+ );
+ trackerOptionsToggle.classList.add("cb-option-indent", "cb-option-toggle");
+ code.appendChild(trackerOptionsToggle);
+
+ const trackerOptionsContent = document.createElement("div");
+ trackerOptionsContent.className = "cb-options cb-option-indent";
+ trackerOptionsContent.dataset.collapsibleFor = "showTrackerOptions";
+ trackerOptionsContent.style.display = state.showTrackerOptions ? "block" : "none";
+ trackerOptionsContent.appendChild(
+ createNumericInputRow(
+ "lost_track_buffer",
+ "lostTrackBuffer",
+ state.lostTrackBuffer,
+ numberConfig.lostTrackBuffer,
+ "cb-row--anchor-3"
+ )
+ );
+ trackerOptionsContent.appendChild(
+ createNumericInputRow(
+ "track_activation_threshold",
+ "trackActivationThreshold",
+ state.trackActivationThreshold,
+ numberConfig.trackActivationThreshold,
+ "cb-row--anchor-3"
+ )
+ );
+ trackerOptionsContent.appendChild(
+ createNumericInputRow(
+ "minimum_consecutive_frames",
+ "minimumConsecutiveFrames",
+ state.minimumConsecutiveFrames,
+ numberConfig.minimumConsecutiveFrames,
+ "cb-row--anchor-3"
+ )
+ );
+ trackerOptionsContent.appendChild(
+ createNumericInputRow(
+ "minimum_iou_threshold",
+ "minimumIouThreshold",
+ state.minimumIouThreshold,
+ numberConfig.minimumIouThreshold,
+ "cb-row--anchor-3"
+ )
+ );
+ code.appendChild(trackerOptionsContent);
+
+ // VISUALIZATION Section
+ code.appendChild(createHeader("Visualization"));
+
+ const vizCheckboxes = document.createElement("div");
+ vizCheckboxes.className = "cb-checkboxes cb-option-indent";
+
+ const vizOptions = [
+ { key: "display", label: "display", checked: state.display },
+ { key: "showBoxes", label: "boxes", checked: state.showBoxes },
+ { key: "showMasks", label: "masks", checked: state.showMasks },
+ { key: "showConfidence", label: "confidence", checked: state.showConfidence },
+ { key: "showLabels", label: "labels", checked: state.showLabels },
+ { key: "showIds", label: "ids", checked: state.showIds },
+ { key: "showTrajectories", label: "trajectories", checked: state.showTrajectories },
+ ];
+
+ vizOptions.forEach((option) => {
+ vizCheckboxes.appendChild(createCheckbox(option.label, option.key, option.checked));
+ });
+ code.appendChild(vizCheckboxes);
+
+ // SOURCE Section
+ code.appendChild(createHeader("Source"));
+ code.appendChild(
+ createTextInputRow(
+ "path",
+ "source.mp4",
+ "source",
+ state.source,
+ "cb-option-indent cb-row--anchor-3"
+ )
+ );
+
+ // OUTPUT Section
+ code.appendChild(createHeader("Output"));
+ code.appendChild(
+ createTextInputRow(
+ "path",
+ "output.mp4",
+ "output",
+ state.output,
+ "cb-option-indent cb-row--anchor-3"
+ )
+ );
+
+ const overwriteWrapper = document.createElement("div");
+ overwriteWrapper.id = ids.overwrite;
+ overwriteWrapper.className = "cb-option-indent";
+ overwriteWrapper.style.display = state.output.trim() ? "block" : "none";
+ overwriteWrapper.appendChild(createCheckbox("overwrite", "overwrite", state.overwrite));
+ code.appendChild(overwriteWrapper);
+ },
+ });
+
+ builder.init();
+});
diff --git a/docs/javascripts/pycon_copy.js b/docs/javascripts/pycon_copy.js
new file mode 100644
index 0000000..e2ba452
--- /dev/null
+++ b/docs/javascripts/pycon_copy.js
@@ -0,0 +1,193 @@
+/**
+ * Custom copy handler for Python console (pycon) code blocks.
+ * Strips >>> and ... prompts when copying code examples.
+ */
+document.addEventListener("DOMContentLoaded", function () {
+ const COPY_BUTTON_SELECTOR = ".md-clipboard, .md-code__button";
+
+ function handleCopyButtonClick(event) {
+ const copyButton = event.target.closest(COPY_BUTTON_SELECTOR);
+ if (!copyButton) return;
+
+ const codeBlock = findCodeBlockForCopyButton(copyButton);
+ if (!codeBlock) return;
+
+ const rawText = codeBlock.textContent || "";
+ if (!shouldStripPrompts(codeBlock, rawText)) return;
+
+ const strippedText = stripPythonPrompts(rawText);
+ primeClipboardButton(copyButton, strippedText);
+ }
+
+ function handleCopyButtonPointerDown(event) {
+ const copyButton = event.target.closest(COPY_BUTTON_SELECTOR);
+ if (!copyButton) return;
+
+ const codeBlock = findCodeBlockForCopyButton(copyButton);
+ if (!codeBlock) return;
+
+ const rawText = codeBlock.textContent || "";
+ if (!shouldStripPrompts(codeBlock, rawText)) return;
+
+ const strippedText = stripPythonPrompts(rawText);
+ primeClipboardButton(copyButton, strippedText);
+ }
+
+ function handleSelectionCopy(event) {
+ const selection = window.getSelection();
+ if (!selection || selection.rangeCount === 0) return;
+
+ const range = selection.getRangeAt(0);
+ const anchorNode = range.commonAncestorContainer;
+ const codeBlock =
+ anchorNode.nodeType === Node.ELEMENT_NODE
+ ? anchorNode.closest("code")
+ : anchorNode.parentElement?.closest("code");
+
+ if (!codeBlock) return;
+
+ const rawText = selection.toString();
+ if (!shouldStripPrompts(codeBlock, rawText)) return;
+
+ event.preventDefault();
+ event.stopPropagation();
+
+ const strippedText = stripPythonPrompts(rawText);
+ event.clipboardData?.setData("text/plain", strippedText);
+ }
+
+ function bindCopyButtons(root) {
+ root.querySelectorAll(COPY_BUTTON_SELECTOR).forEach((button) => {
+ button.removeEventListener("click", handleCopyButtonClick, true);
+ button.addEventListener("click", handleCopyButtonClick, true);
+ button.removeEventListener(
+ "pointerdown",
+ handleCopyButtonPointerDown,
+ true
+ );
+ button.addEventListener(
+ "pointerdown",
+ handleCopyButtonPointerDown,
+ true
+ );
+ });
+ }
+
+ function observeDynamicCopyButtons() {
+ const observer = new MutationObserver((mutations) => {
+ for (const mutation of mutations) {
+ if (mutation.type !== "childList") continue;
+ mutation.addedNodes.forEach((node) => {
+ if (node.nodeType !== Node.ELEMENT_NODE) return;
+ if (node.matches?.(COPY_BUTTON_SELECTOR)) {
+ bindCopyButtons(node.parentElement || document);
+ return;
+ }
+ if (node.querySelectorAll) {
+ const hasButtons = node.querySelectorAll(COPY_BUTTON_SELECTOR);
+ if (hasButtons.length > 0) {
+ bindCopyButtons(node);
+ }
+ }
+ });
+ }
+ });
+
+ observer.observe(document.body, { childList: true, subtree: true });
+ }
+
+ document.addEventListener("click", handleCopyButtonClick, true);
+ document.addEventListener("pointerdown", handleCopyButtonPointerDown, true);
+ document.addEventListener("copy", handleSelectionCopy, true);
+ bindCopyButtons(document);
+ observeDynamicCopyButtons();
+});
+
+function primeClipboardButton(copyButton, strippedText) {
+ copyButton.setAttribute("data-clipboard-text", strippedText);
+ copyButton.removeAttribute("data-clipboard-target");
+ copyButton.setAttribute("data-md-clipboard", "true");
+}
+
+function shouldStripPrompts(codeBlock, rawText) {
+ const hasReplPrompts = /(^|\n)[ \t]*(>>>|\.\.\.)/.test(rawText);
+ return (
+ hasReplPrompts ||
+ codeBlock.classList.contains("language-pycon") ||
+ codeBlock.closest("pre")?.classList.contains("pycon") ||
+ codeBlock.closest(".pycon") !== null ||
+ codeBlock.closest(".highlight")?.classList.contains("pycon")
+ );
+}
+
+function findCodeBlockForCopyButton(copyButton) {
+ const targetSelector = copyButton.getAttribute("data-clipboard-target");
+ if (targetSelector) {
+ const target = document.querySelector(targetSelector);
+ const targetCode = target?.querySelector?.("code") || target;
+ if (targetCode?.tagName?.toLowerCase() === "code") {
+ return targetCode;
+ }
+ }
+ return (
+ copyButton.closest("pre")?.querySelector("code") ||
+ copyButton.parentElement?.querySelector("pre code") ||
+ copyButton
+ .closest(".highlight, .codehilite, .md-typeset__scrollwrap, .md-typeset")
+ ?.querySelector("pre code") ||
+ copyButton
+ .closest(".highlight, .codehilite, .md-typeset__scrollwrap, .md-typeset")
+ ?.querySelector("code")
+ );
+}
+
+/**
+ * Strips Python REPL prompts (>>> and ...) from code text.
+ * Also removes output lines (lines that don't start with >>> or ...).
+ *
+ * NOTE: This is a best-effort parser. It preserves unprompted lines inside
+ * triple-quoted strings, but it does not fully model Python's tokenizer.
+ */
+function stripPythonPrompts(text) {
+ const lines = text.split("\n");
+ const codeLines = [];
+ let inTripleQuotedString = false;
+
+ function toggleTripleQuoteState(sourceLine) {
+ const tripleQuotePattern = /("""|''')/g;
+ const matches = sourceLine.match(tripleQuotePattern);
+ if (!matches) return;
+ if (matches.length % 2 === 1) {
+ inTripleQuotedString = !inTripleQuotedString;
+ }
+ }
+
+ for (const line of lines) {
+ const trimmedLine = line.trimEnd();
+ // Primary prompt: ">>> "
+ if (trimmedLine.startsWith(">>> ")) {
+ const stripped = trimmedLine.slice(4);
+ codeLines.push(stripped);
+ toggleTripleQuoteState(stripped);
+ }
+ // Continuation prompt: "... "
+ else if (trimmedLine.startsWith("... ")) {
+ const stripped = trimmedLine.slice(4);
+ codeLines.push(stripped);
+ toggleTripleQuoteState(stripped);
+ }
+ // Handle prompts without space after (edge case)
+ else if (trimmedLine === ">>>") {
+ codeLines.push("");
+ } else if (trimmedLine === "...") {
+ codeLines.push("");
+ } else if (inTripleQuotedString) {
+ codeLines.push(trimmedLine);
+ toggleTripleQuoteState(trimmedLine);
+ }
+ // Skip output lines (lines that don't start with prompts)
+ // This intentionally excludes output like "1.0" from the copied text
+ }
+
+ return codeLines.join("\n").trim();
+}
diff --git a/docs/learn/evaluate.md b/docs/learn/evaluate.md
new file mode 100644
index 0000000..45ba841
--- /dev/null
+++ b/docs/learn/evaluate.md
@@ -0,0 +1,210 @@
+# Evaluate Trackers
+
+Measure how well your multi-object tracker performs using standard MOT metrics (CLEAR, HOTA, Identity). Get clear, reproducible scores for development, comparison, and publication.
+
+**What you'll learn:**
+
+- Evaluate single and multi-sequence tracking results
+- Interpret HOTA, MOTA, and IDF1 scores
+- Prepare datasets in MOT Challenge format
+
+---
+
+## Installation
+
+```bash
+pip install trackers
+```
+
+For alternative methods, see the [Install guide](install.md).
+
+---
+
+## Quickstart
+
+Evaluate a single sequence by pointing to your ground-truth and tracker files, then view the results as a formatted table.
+
+=== "Python"
+
+ ```python
+ from trackers.eval import evaluate_mot_sequence
+
+ result = evaluate_mot_sequence(
+ gt_path="data/gt/MOT17-02-FRCNN.txt",
+ tracker_path="data/trackers/MOT17-02-FRCNN.txt",
+ metrics=["CLEAR", "HOTA", "Identity"],
+ )
+
+ print(result.table(columns=["MOTA", "HOTA", "IDF1", "IDSW"]))
+ ```
+
+ **Output:**
+
+ ```
+ Sequence MOTA HOTA IDF1 IDSW
+ ----------------------------------------------------------
+ MOT17-02-FRCNN 75.600 62.300 72.100 42
+ ```
+
+=== "CLI"
+
+ ```bash
+ trackers eval \
+ --gt data/gt/MOT17-02-FRCNN.txt \
+ --tracker data/trackers/MOT17-02-FRCNN.txt \
+ --metrics CLEAR HOTA Identity \
+ --columns MOTA HOTA IDF1 IDSW
+ ```
+
+ **Output:**
+
+ ```
+ Sequence MOTA HOTA IDF1 IDSW
+ ----------------------------------------------------------
+ MOT17-02-FRCNN 75.600 62.300 72.100 42
+ ```
+
+---
+
+## Data Format
+
+Ground truth and tracker files use MOT Challenge text format — a simple comma-separated .txt file where each line describes one detection.
+
+```
+,| Argument | +Description | +Default | +
|---|---|---|
--tracker |
+ Tracking algorithm. Options: bytetrack, sort, ocsort. |
+ bytetrack |
+
--tracker.lost_track_buffer |
+ Frames to retain a track without detections. Higher values improve occlusion handling but risk ID drift. | +30 |
+
--tracker.track_activation_threshold |
+ Minimum confidence to start a new track. Lower values catch more objects but increase false positives. | +0.25 |
+
--tracker.minimum_consecutive_frames |
+ Consecutive detections required before a track is confirmed. Suppresses spurious detections. | +3 |
+
--tracker.minimum_iou_threshold |
+ Minimum IoU overlap to match a detection to an existing track. Higher values require tighter alignment. | +0.3 |
+
| Argument | +Description | +Default | +
|---|---|---|
--model |
+ Model identifier. Pretrained: rfdetr-nano, rfdetr-small, rfdetr-medium, rfdetr-large. Segmentation: rfdetr-seg-*. |
+ rfdetr-nano |
+
--model.confidence |
+ Minimum confidence threshold. Lower values increase recall but may add noise. | +0.5 |
+
--model.device |
+ Compute device. Options: auto, cpu, cuda, cuda:0, mps. |
+ auto |
+
--classes |
+ Comma-separated class names or IDs to track. Example: person,car or 0,2. |
+ all | +
--model.api_key |
+ Roboflow API key for custom hosted models. | +none | +
| Argument | +Description | +Default | +
|---|---|---|
--display |
+ Opens a live preview window. Press q or ESC to quit. |
+ false |
+
--show-boxes |
+ Draw bounding boxes around tracked objects. | +true |
+
--show-masks |
+ Draw segmentation masks. Only available with rfdetr-seg-* models. |
+ false |
+
--show-confidence |
+ Show detection confidence scores in labels. | +false |
+
--show-labels |
+ Show class names in labels. | +false |
+
--show-ids |
+ Show tracker IDs in labels. | +true |
+
--show-trajectories |
+ Draw motion trails showing recent positions of each track. | +false |
+
| Argument | +Description | +Default | +
|---|---|---|
--source |
+ Input source. Accepts file paths (.mp4, .avi), device indices (0, 1), stream URLs (rtsp://), or image directories. |
+ — | +
| Argument | +Description | +Default | +
|---|---|---|
--output |
+ Path for output video. If a directory is given, saves as output.mp4 inside it. |
+ none | +
--overwrite |
+ Allow overwriting existing output files. Without this flag, existing files cause an error. | +false |
+
{{ lang.t("meta.comments") }}
+ + + + + +{% endif %} diff --git a/docs/overrides/partials/header.html b/docs/overrides/partials/header.html new file mode 100644 index 0000000..6157b74 --- /dev/null +++ b/docs/overrides/partials/header.html @@ -0,0 +1,181 @@ +{% set class = "md-header" %} +{% if "navigation.tabs.sticky" in features %} + {% set class = class ~ " md-header--shadow md-header--lifted" %} +{% elif "navigation.tabs" not in features %} + {% set class = class ~ " md-header--shadow" %} +{% endif %} + + +Visualization of ground-truth annotations for MOT17.
+ +| Tracker | HOTA | IDF1 | MOTA | +| :-------: | :------: | :------: | :------: | +| SORT | 58.4 | 69.9 | 67.2 | +| ByteTrack | 60.1 | 73.2 | 74.1 | +| OC-SORT | **61.9** | **76.1** | **76.7** | + +## [SportsMOT](https://arxiv.org/abs/2304.05170) + +Sports broadcast tracking with fast motion, camera pans, and similar-looking targets. Tests association under speed and appearance ambiguity. + + +Visualization of ground-truth annotations for SportsMOT.
+ +| Tracker | HOTA | IDF1 | MOTA | +| :-------: | :------: | :------: | :------: | +| SORT | 70.9 | 68.9 | 95.7 | +| ByteTrack | **73.0** | **72.5** | **96.4** | +| OC-SORT | 71.5 | 71.2 | 95.2 | + +## [SoccerNet-tracking](https://arxiv.org/abs/2204.06918) + +Long sequences with dense interactions and partial occlusions. Tests long-term ID consistency. + + +Visualization of ground-truth annotations for SoccerNet.
+ +| Tracker | HOTA | IDF1 | MOTA | +| :-------: | :------: | :------: | :------: | +| SORT | 81.6 | 76.2 | 95.1 | +| ByteTrack | **84.0** | **78.1** | **97.8** | +| OC-SORT | 78.6 | 72.7 | 94.5 | + +## [DanceTrack](https://arxiv.org/abs/2111.14690) + +Group dancing tracking with uniform appearance, diverse motions, and extreme articulation. Tests motion-based association without relying on visual discrimination. + + +Visualization of ground-truth annotations for DanceTrack.
+ +| Tracker | HOTA | IDF1 | MOTA | +| :-------: | :------: | :------: | :------: | +| SORT | 45.0 | 39.0 | 80.6 | +| ByteTrack | 50.2 | 49.9 | 86.2 | +| OC-SORT | **51.8** | **50.9** | **87.3** | + +**Note:** DanceTrack test set is not available at the moment, that's why the table uses valid set. Default parameters are used in each tracker, for better performance it is possible to adjust the parameters to the dataset. diff --git a/docs/trackers/ocsort.md b/docs/trackers/ocsort.md new file mode 100644 index 0000000..180da3c --- /dev/null +++ b/docs/trackers/ocsort.md @@ -0,0 +1,146 @@ +--- +comments: true +--- + +# OC-SORT + +## Overview + +OC-SORT remains Simple, Online, and Real-Time like ([SORT](../sort/tracker.md)) but improves robustness during occlusion and non-linear motion. +It recognizes limitations from SORT and the linear motion assumption of the Kalman filter, and adds three mechanisms to enhance tracking. These +mechanisms help having better Kalman Filter parameters after an occlusion, add a term to the association process to incorporate how consistent is the direction with the new association with respect to the tracks' previous direction and add a second-stage association step between the last observation of unmatched tracks and the unmatched observations after the usual association to attempt to recover tracks that were lost +due to object stopping or short-term occlusion. + +## Comparison + +For comparisons with other trackers, plus dataset context and evaluation details, see the [tracker comparison](comparison.md) page. + +| Dataset | HOTA | IDF1 | MOTA | +| :-------: | :--: | :--: | :--: | +| MOT17 | 61.9 | 76.1 | 76.7 | +| SportsMOT | 71.5 | 71.2 | 95.2 | +| SoccerNet | 78.6 | 72.7 | 94.5 | + +## Run on video, webcam, or RTSP stream + +These examples use OpenCV for decoding and display. Replace `