Frequently asked questions

This page answers the questions a developer meeting SushiTrack for the first time tends to ask: what it is, what it needs, how to build and call it, where it runs, what it leaves to the caller and how it is licensed. Each answer links to the manual page that holds the detail.

What is SushiTrack?

SushiTrack is a multi-object tracking library in C++17. It takes the detections of one frame and returns tracks with stable identities. A detection is a box with a top-left origin, a score and a label: (x, y, width, height, score, label).

The pipeline follows the ByteTrack two-stage association: detections at or above track_thresh are matched first, then the tracks left over try the low-score detections. Appearance ReID, Mahalanobis gating, the NSA and IMM motion estimators, observation-centric momentum and observation-centric re-update are optional and off in the compiled defaults. The architecture overview describes each stage.

The repository also holds a Python binding, the st developer CLI, a MOTChallenge and DanceTrack regression harness and a YOLOX video inference pipeline.

What do I need to build SushiTrack?

A C++17 compiler, CMake 3.14 or later, Ninja, GoogleTest and Python 3.11. environment.yml defines a conda environment that installs Python, CMake, Ninja, GoogleTest and the Python packages the evaluator and the inference pipeline use:

conda env create -f environment.yml
conda activate sushitrack

Eigen, TrackEval and YOLOX are git submodules, so run git submodule update --init after cloning. Docker is optional; CUDA inference in the container needs Engine 20.10 or later with the NVIDIA Container Toolkit. Installing lists every version.

How do I install the st command?

st is the developer CLI of this repository, also installed as sushitrack. It is a Python package in cli/, installed with pipx:

pipx install cli/

cli/pyproject.toml requires sushicore>=0.7.0, and PyPI carries sushicore 0.1.0 to 0.4.0. Until 0.7.0 is published, pipx install cli/ cannot resolve that requirement. Install sushicore from a checkout into one environment with pip install -e /path/to/sushicore, then the CLI beside it with pip install -e cli. The conda environment pins sushicore==0.4.0, so an environment built from environment.yml needs the same step; see Installing.

st --help lists every command and st --version prints the installed version of sushitrack-cli.

How do I build and test SushiTrack?

st build
st test

st build configures and compiles the library and every test target; st build --no-test compiles the library only. The build type is release unless --type names debug, relwithdebinfo or minsizerel. The library lands at build/bin/{Release,Debug}/sushitrack.{dll,so}.

st test runs the functional suite, which is the unit, integration and regression suites together. st test --suite unit runs one of them. Building holds the CMake options and the command line reference holds every flag.

How do I use SushiTrack from Python?

After st build, put bindings/python on PYTHONPATH. The module finds the library under build/ by itself.

from sushitrack import Tracker

tracker = Tracker(config="auto")              # reads sushitrack.json
tracks = tracker.update([(100.0, 100.0, 50.0, 80.0, 0.9, 0)], dt=1.0 / 30.0)
for t in tracks:
    print(t.track_id, t.x, t.y, t.width, t.height)
tracker.close()

bindings/python/sushitrack.py is a ctypes binding with no dependency outside the standard library. For a project outside this repository, st build --deploy python assembles package/ with the binding and the native library side by side; copy its sushitrack/ directory into your source tree. The binding README lists the constructor arguments and the order in which the module looks for the library, and Deploy packages shows the package layout.

How do I use SushiTrack from a C or C++ project?

Through the C API in include/SushiTrack/sushitrack_c.h, linked against the compiled sushitrack shared library. The header includes SushiTrack/sushitrack_export.hpp, which holds preprocessor macros only, and nothing else from the library, so a C consumer needs no Eigen and no C++ header. Fill a sushitrack_params_t with sushitrack_get_default_params, create the tracker with sushitrack_create_ex, and call sushitrack_update once per frame with an array of sushitrack_object_t; it returns the number of sushitrack_track_t records written. The C API reference has the status codes and the track fields.

st build --deploy cpp assembles package/ with the headers, the library, a default sushitrack.json and example/example.c with its CMakeLists.txt. Add package/include to the include path and link against package/lib/sushitrack.lib on Windows or package/lib/libsushitrack.so on Linux. Deploy packages covers how the runtime library is found at load time.

Which platforms and compilers does SushiTrack support?

SushiTrack builds on Windows and Linux. The compilers listed are MSVC 19.20 or later, GCC 9 or later and Clang 10 or later. The library is built as a shared library with hidden-by-default symbol visibility on every platform; only functions carrying SUSHITRACK_API are exported.

A deploy package is platform-specific: st build --deploy copies the artefacts of the operating system it runs on, a .dll and .lib on Windows or a .so on Linux. There is no cross-compilation, so shipping both platforms means running the deploy once on each.

st container build builds an image from Dockerfile on a CUDA 12.1, Ubuntu 22.04 base, and st container run starts it with the repository mounted at /workspace/sushitrack. See Installing.

How do I change the tracker’s parameters?

Edit sushitrack.json. The library parses the file itself, so a compiled build is retuned with no recompilation. It looks for the file in the SUSHITRACK_CONFIG environment variable first, then searches upward from the working directory for sushitrack.json. A key absent from the file keeps its compiled default.

The shipped sushitrack.json enables the tentative lifecycle, observation-centric momentum and observation-centric re-update. A caller that fills sushitrack_params_t in code and passes it to the create call bypasses the file and gets the compiled defaults, where those three are off. In Python, Tracker(config="auto") resolves the file through the library, and keyword overrides win over the file. Configuration lists every parameter with its default.

How does SushiTrack compare with ByteTrack and OC-SORT?

Benchmarks records two runs on the MOT17 and MOT20 train sets and on DanceTrack against the bundled ByteTrack and OC-SORT references. In the linear Kalman run (kalman_type=0, with the tentative lifecycle, OCM and ORU on and ReID off) the overall figures are:

On DanceTrack alone, OC-SORT scores 45.6 % HOTA in that run and SushiTrack 44.9 %. The second run changes only kalman_type to 2, the IMM estimator: SushiTrack reaches 45.8 % overall HOTA at 218 µs per frame. Latency is the mean per-frame update() time, single-threaded, excluding I/O. The date, the commit and the machine of the runs were not recorded.

st eval --compare runs all three trackers side by side and prints the same metrics table; see the evaluation pipeline.

How does SushiTrack relate to the other Sushi Systems parts?

The st CLI is built on sushicore, the Sushi Systems package that gives every Sushi CLI (sr, se, sa, sb, sd, hub) its console, configuration layering and build driver. st setup, st doctor, st link and st unlink come from sushicore and behave the same in each of them.

Inside a SushiStack workspace, hub add sushitrack installs the CLI, and st link and st unlink register a checkout in a workspace or remove it. cli/sushistack.deps.toml is the SushiStack dependency fragment; it names GoogleTest, the only port SushiTrack does not vendor. st setup provisions what that fragment lists.

The library itself links Eigen and JSON for Modern C++. The Python binding depends on the compiled library and on nothing else in the repository.

What does SushiTrack not do?

The manual states these limits:

• It does not compute appearance embeddings. With enable_reid=1, each detection carries an external embedding as a seventh tuple element.
• It associates across all detections regardless of label. Partition the detections before update if you need per-class tracking.
• A single tracker instance is not designed for concurrent update calls. Construct one instance per stream.
• The C API does not report which input detection produced each track.
• No Ultralytics adapter is shipped. Ultralytics integration is a recipe whose snippets you copy into your own project.
• No built Docker image is published, and st deploy copies no licence file into package/.

Contributions from outside Sushi Systems are not accepted yet. Recorded defects are in Known issues; among them, sushitrack_update returns 0 both on a caught exception and on a rejected argument, which a caller cannot tell from a frame with no tracks, and no CI workflow exists.

How is SushiTrack licensed?

SushiTrack is source-available under the PolyForm Noncommercial License 1.0.0, free for non-commercial use. LICENSE is the binding text and lists the permitted purposes: personal, non-commercial use, and use by the non-commercial organisations it names.

Any commercial purpose needs a separate, paid licence from Sushi Systems. That includes use inside a company, use in paid client work, and use in a product or service that is sold. To ask for one, write to hello@sushisystems.io with what you want to build and who will use it; see COMMERCIAL.md.

Third-party code and data keep their own licences, listed in NOTICE.md. The repository’s licence does not cover the MOT17, MOT20 and DanceTrack files under tests/regression/evaluator/data/.