spintrack tracks the 3D rotation of a trackball (spherical treadmill) under a tethered animal from one camera's video, and integrates the animal's fictive path. It streams FicTrac's records, so closed-loop rigs keep working, writes them to Parquet with named columns, and on synthetic scenes its per-frame error is about a tenth of FicTrac's.
uv tool install --torch-backend auto git+https://github.com/NeLy-EPFL/spintrack--torch-backend auto picks the PyTorch build for the machine's GPU; PyTorch runs SAM 3, which finds the ball (its 3.4 GB checkpoint downloads on first use). Until wheels are released, the install builds a Rust extension and needs a Rust toolchain. Streaming over a serial port needs the serial extra; spintrack doctor reports what the installation can do.
git clone https://github.com/NeLy-EPFL/spintrack && cd spintrack
spintrack run examples/sample/sample.mp4 --set camera.azimuth_deg=180
spintrack gui examples/sample/sample.mp4The run finds the ball, the field of view and the camera's elevation in the video; which side the camera films the fly from (180: behind it) is the one thing to say. It prints a link to a live view of the run, and writes tracks.parquet, a summary and the config as run into examples/sample/sample_spintrack/. spintrack gui tracks a clip over and over while you fix what a run got wrong, and saves a config for the rig.
Full documentation: https://nely-epfl.github.io/spintrack/
- Quickstart: the example run, step by step.
- User guide: from a recording to a tracked file, and how to tell whether to trust it.
- Output files: every column, with its unit, frame and sign.
- Coming from FicTrac: config keys, records, and what differs.
- Benchmark: accuracy and speed against FicTrac.
- Python API:
spintrack.track, and aTrackerto feed frame by frame.
Contributing: see CONTRIBUTING.md.
There is no paper on spintrack yet; if you use it, please cite the software (CITATION.cff holds the same reference), and FicTrac, whose output it reproduces: Moore, R. J. D., Taylor, G. J., Paulk, A. C., Pearson, T., van Swinderen, B., & Srinivasan, M. V. (2014). FicTrac: a visual method for tracking spherical motion and generating fictive animal paths. Journal of Neuroscience Methods, 225, 106–119. doi:10.1016/j.jneumeth.2014.01.010
@software{lam_spintrack_2026,
author = {Lam, Thomas Ka Chung},
title = {spintrack: track the rotation of a spherical treadmill from video},
year = {2026},
url = {https://github.com/NeLy-EPFL/spintrack},
}spintrack is developed in the Neuroengineering Laboratory (Ramdya lab) at EPFL. It follows FicTrac, whose record format and path integration it reproduces, and finds the ball with Meta's SAM 3. The full credits, with the methods it reimplements from the literature and the libraries it runs on, are on the Citing and credits page.
spintrack was developed with extensive help from AI coding assistants, mainly Claude Code (Anthropic). Directed by the author, they wrote much of the code, tests, and documentation, including this README, and ran many of the validation and benchmark experiments behind the accuracy figures in the documentation. The author set the goals, made the design decisions, reviewed the changes, and checked the results against data, and is responsible for the software. As with any tool, validate its output on your own recordings before relying on it.
Apache-2.0; see LICENSE.