track — Run the tracking stack

Runs the context generator and, unless --record-only is set, the configured inference pipeline. It can record datasets, launch the VisPy UI, or publish live exports to a visualizer uplink.

Usage

# Live gstreamer cameras, UI enabled
s6 track -i gst -v

# Replay a dataset directory in a loop (headless)
s6 track -i ./datasets/session_001 --repeat

# Push live telemetry into a local visualizer uplink (headless)
s6 track -i gst --uplink

# Override pipeline parameters and run level
s6 track --config configs/pipeline.config.yaml --run-level performance

How it works

  • Selects a context generator from s6.app._contextgenerators based on --input:

    • gst → RemoteGSTContextGenerator

    • gst-local → LocalGSTContextGenerator

    • gst-local-v2 → LocalGSTContextGeneratorV2

    • any dataset directory path → DatasetContextGenerator

  • Loads the pipeline from --config and validates shared config fields with PipelineConfigBase before resolving pipeline_name to the concrete pipeline class. --run-level overrides the config value at load time.

  • Unless --record-only is set, the selected pipeline mutates each newest context in place and writes context["export"] for downstream consumers.

  • With -v/--ui, track starts a Qt/VisPy MainWindow in the foreground and runs capture plus inference in a spawned worker process owned by TrackRuntime.

  • In UI mode, dataset inputs enable playback controls. Live GST inputs keep streaming and leave replay-only controls disabled.

  • In UI mode, -o/--output-dataset starts recording immediately. If -o is omitted, track prepares a generated temp/track_* dataset path and waits for the Record button before writing frames.

  • With --uplink [WS_URL], track runs headless and publishes {"export": ...} snapshots to the visualizer WebSocket. This mode is mutually exclusive with --ui. The spawned worker forwards only the export snapshot across its multiprocessing queue before the publisher serializes it to WebSocket.

Common flags

  • -i, --input — data source (gst, gst-local, gst-local-v2, or a dataset path)

  • -o, --output-dataset — write a dataset to this directory

    • Supports path placeholders such as $datetime / $dt, $date, $time, $input, $config, $host, $pid, and $runid.

    • Quote or escape $... in the shell so the placeholder reaches s6 track, for example -o 'temp/data_$datetime' or -o temp/data_\\$datetime.

  • -x, --output-log — write logs under logs/runs/YYYMMDD_HHMMSS.

  • -r, --record-only — skip inference and only record frames.

  • -v, --ui — enable the VisPy UI.

  • --path — parsed by the CLI today, but not consumed by the current track runtime. The supported inputs remain gst, gst-local, and dataset-directory replay.

  • --enable-plots — show the plot panel in the UI.

  • --uplink [WS_URL] — push live telemetry snapshots into a visualizer uplink.

    • Uses ws://127.0.0.1:4173/ws/uplink when passed without a value.

    • Headless only; it cannot be combined with --ui.

  • --repeat — loop dataset playback when the input is a dataset directory.

  • --realtime-playback — pace dataset replay using recorded timestamp deltas.

  • --config — path to a pipeline config file (JSON/YAML).

    • Defaults to configs/pipeline.config.yaml.

  • --run-level — override the pipeline runtime feature level.

    • Choices: performance, normal, dev, debug.

Config Notes

  • Pipeline config files define shared fields such as pipeline_name, platform, run_cpp, run_level, and calibration_file.

  • The checked-in defaults under sense-core/configs/ currently point at PipelineT1 in configs/pipeline.config.yaml.

  • GStreamer source settings live in the pipeline config under platform.gstreamer; s6 track does not require a separate gstreamer config file.

  • gst-local-v2 reuses platform.gstreamer.local but captures one compositor stream through direct Gst appsink capture instead of using MultiCameraCapture.

  • In gst-local-v2, sync-only local capture settings (stale_frame_timeout_sec, max_seq_skew) are ignored because the runtime reads one combined frame stream rather than synchronizing multiple sources.

Retirement note

  • Database-backed replay has been retired from s6 track; export remote data to a dataset directory before replaying it locally.

  • See ../retired_streamer.md for impacted commands and scripts.