Citing and credits¶
Citation¶
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},
}
If you publish results obtained with SAM 3, which spintrack uses to find the ball and the animal, acknowledge it as well: its license asks publications to.
Acknowledgments¶
spintrack is developed in the Neuroengineering Laboratory (Ramdya lab) at EPFL. It follows FicTrac, whose record format and path integration it reproduces, and builds on the following work.
Methods reimplemented from the literature
| Work | Where in spintrack |
|---|---|
| FicTrac: Moore, R. J. D., Taylor, G. J., Paulk, A. C., Pearson, T., van Swinderen, B., & Srinivasan, M. V. (2014), Journal of Neuroscience Methods 225, 106–119, doi:10.1016/j.jneumeth.2014.01.010 | the 25-field record and its line format, the fictive path's integration scheme (reimplemented in closed form), the surface map's density, and loading FicTrac sphere-map PNGs |
| Baker, S., & Matthews, I. (2004), Lucas-Kanade 20 years on: a unifying framework, International Journal of Computer Vision 56, 221–255, doi:10.1023/B:VISI.0000011205.11775.fd | the Gauss-Newton alignment of each frame against the surface map |
| Huber, P. J. (1964), The Annals of Mathematical Statistics 35, 73–101, doi:10.1214/aoms/1177703732; Beaton, A. E., & Tukey, J. W. (1974), Technometrics 16, 147–185, doi:10.1080/00401706.1974.10489171 | the robust weights of the per-frame solve and of the rim fit |
| Kåsa, I. (1976), IEEE Transactions on Instrumentation and Measurement IM-25, 8–14, doi:10.1109/TIM.1976.6312298 | the algebraic circle fit of the ball's rim |
| Fischler, M. A., & Bolles, R. C. (1981), Communications of the ACM 24, 381–395, doi:10.1145/358669.358692 | the RANSAC start of the rim fit |
| Lepskii, O. V. (1991), Theory of Probability & Its Applications 35, 454–466, doi:10.1137/1135065 | the ball follower's choice of how many looks to fit (Lepski's rule) |
| Brown, C. (2017), Bringing pixels front and center in VR video, Google | the equi-angular cubemap of the surface map |
Models and libraries
- SAM 3 (SAM License): Carion, N., Gustafson, L., Hu, Y.-T., Debnath, S., et al. (2025). SAM 3: Segment Anything with Concepts. arXiv:2511.16719. It finds the ball and the animal, through Transformers (Apache-2.0); spintrack downloads an ungated copy of Meta's checkpoint, byte-identical to it.
- PyO3, rust-numpy and maturin, which bind the Rust core to Python.
- NumPy, OpenCV, PyAV (FFmpeg), Polars, pydantic, PyTorch, Pillow, FastAPI, Typer and pySerial, on which everything runs.
spintrack vendors no third-party files: its web page's scripts and styles are its own. The example clips in examples/ were recorded in the Ramdya lab.
Use of AI¶
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.