Stone Soup is a framework for tracking work, not a tracker

A framework for the algorithm, not the algorithm itself

Stone Soup describes itself as a software project to provide the target tracking and state estimation community with a framework for the development and testing of tracking and state estimation algorithms. That phrasing is doing real work. The deliverable is not a tracker you configure and run, but a place where tracking and state estimation code is developed, exercised and compared.

The audience implied by that is narrow and worth naming: people who already work in the field. The project comes from the Defence Science and Technology Laboratory in the United Kingdom, and it ships a DOI, a CITATION.cff file and a GOV.UK article describing its background, with links to sample data. Citation metadata is unusual in a research utility and says something about how the maintainers expect the code to be used downstream.

The framing also explains the packaging. The project is published to PyPI as stonesoup and to conda-forge, with documentation hosted on Read the Docs at stonesoup.readthedocs.io. Its declared purpose is infrastructure for the community rather than a product with a UI.

The dependency list reveals the domain

The packaging metadata is the most concrete evidence of what the framework covers, and it is short enough to read in full. The core dependency list is matplotlib, numpy>=1.17, ordered-set, plotly>=5.0, pymap3d, rtree, ruamel.yaml>=0.16.5, scipy and utm.

Several of those names place the library in geospatial and estimation work: pymap3d and utm sit alongside scipy and numpy, rtree covers spatial indexing, and matplotlib and plotly cover visualisation. That combination suggests tracking problems where positions live in geographic coordinates and the state is estimated numerically. The presence of ruamel.yaml points at configuration files being read and written as YAML, which is consistent with a framework that expects you to describe an experiment declaratively rather than hard-code it in a script.

Two details in the metadata matter for adoption. The build backend is setuptools with setuptools_scm, and version is dynamic, so the released version number comes from the source control tag rather than a hard-coded string. The classifier list includes Development Status :: 5 - Production/Stable and requires-python is >=3.10.

Installing stonesoup and the extras that decide what you can run

There is no install command in the project README. The README points to the PyPI listing and the conda-forge channel through badges, so the practical route is to install the published package from one of those two places, with Python 3.10 or newer. The declared core dependencies, verbatim from the packaging metadata, are:

[project]
name = "stonesoup"
description = "A tracking and state estimation framework"
requires-python = ">=3.10"
dependencies = [
    "matplotlib",
    "numpy>=1.17",
    "ordered-set",
    "plotly>=5.0",
    "pymap3d",
    "rtree",
    "ruamel.yaml>=0.16.5",
    "scipy",
    "utm",
]

The optional dependency groups are where the real weight sits. The dev group exists for contributors and includes the test and documentation tooling:

dev = [
    "cbor2",
    "confluent-kafka",
    "coverage>=7.2",
    "flake8",
    "folium",
    "graphviz",
    "h5py",
    "networkx",
    "ortools",
    "pandas",
    "pillow",
    "pydot",
    "pytest-cov",
    "pytest-remotedata",
    "pytest-skip-slow",
]

Note that ffmpeg-python, moviepy, opencv-python and yt-dlp sit in a separate video group rather than in dev, so the test tooling is not the heaviest part of a development install.

video = [
    "ffmpeg-python",
    "moviepy>=2.0",
    "opencv-python",
    "yt-dlp",
]

That separation is the useful design decision here. A user wanting only the core framework pays for numpy and scipy, not for a video stack and an optimiser solver.

Where the heavy model dependencies are grouped

Machine learning models are optional extras rather than core requirements, and each sits in its own named group. The tensorflow group pins a minimum version, and the ultralytics group exists for detector-based workflows:

tensorflow = [
    "tensorflow>=2.2.0",
]

ultralytics = [
    "ultralytics",
]

Solver-based components are grouped the same way, with ortools appearing both as a standalone group and inside the dev set, and optuna sitting in its own group for hyperparameter search. The docs group carries geopandas, pyehm and torch.

The consequence for an adopter is that the choice of group encodes which algorithm families you intend to use, and a framework this configurable will not tell you at install time whether you installed the group your model needs. If a component fails on import because its group was skipped, the fix is to add that extra rather than to debug the tracking code. This is the most common friction point in a package with this many optional paths, and it is a packaging consequence rather than a design flaw.

The alternative to a local install is a Binder notebook

Stone Soup's own documentation offers a second route that is worth weighing before you install anything. The README links to tutorials, examples and demonstrations, and it points at Binder with a direct link to the notebooks directory of the main branch. That gives you a hosted environment running the notebooks without touching a local Python setup.

The difference in approach is real rather than cosmetic. A Binder session gives you the framework plus its examples in a fixed environment, which suits trying out a tutorial, reproducing a published example, or teaching a lab session. A local install gives you the extras you choose and the ability to run the model code you are actually writing, which a Binder environment with a fixed dependency set will not cover if your model needs a group that is not preinstalled.

For a project whose core value is development and testing rather than end-user operation, that distinction is the whole decision. Trying the tutorials without installing is cheap; building on the framework means committing to the packaging above.

Where the project is thin, and where it stops

The documentation surface is a sphinx-gallery build under docs/ with a source tree, a Binder configuration in binder/, and separate tutorials, examples and demonstrations sections, all linked from the README. What is not there is a quickstart command or a list of the tracking algorithms shipped, and the README does not explain how the pieces of the framework fit together.

This is a library that assumes domain knowledge it does not hand you. The naming of the documentation sections tells you the intended workflow: learn the framework in tutorials, copy a working case in examples, then present a full system in demonstrations. A newcomer without a supervisor and without prior familiarity with the tracking literature will find the tutorials demanding.

The right tool question follows from that. If you want a maintained multi-target tracking system that runs on your data today, the framework is the wrong shape, since the algorithms are for you to assemble and evaluate. If you want to compare your own detector-plus-filter combination against someone else's on the same data and plotting setup, the scaffolding is exactly the point. The dependency grouping reinforces this: model code lives in extras, so the framework is designed to be extended rather than merely called.

MIT licence and a release cadence with a long gap

The licence is MIT, stated plainly in the README and in the packaging metadata, and it permits reuse and modification with attribution. The maintainer entry is the Defence Science and Technology Laboratory UK with the contact address [email protected], and the project URLs section points to the GitHub repository, the Read the Docs documentation, the GitHub releases page for release notes and the GitHub issues tracker.

The release history is where an adopter should look before upgrading. The most recent tagged releases are v1.9.1 on 2026-06-24 and v1.9 on 2026-06-18, with v1.8 dated 2025-10-07 ahead of them. The repository is not archived and the last push was on 2026-10-22, which is several months after the v1.9.1 release date. Work has therefore continued on the main branch without a new tag, and the difference between what you would install from PyPI and what is on the default branch is not zero.

The continuous integration setup backs the releases rather than being cosmetic: the repository carries a.circleci directory and a.codecov.yml file, the README links a CircleCI tests badge and a Codecov coverage badge, and the dev extra includes coverage>=7.2, pytest-cov, pytest-remotedata and pytest-skip-slow. A tracked project with a long gap between tag and branch head is a normal state for research code, and it means version pinning should be deliberate.

Editorial conclusion

Stone Soup fits research groups and defence analysts who already know the tracking literature and want a common harness, shared example data and citable provenance rather than a one-line install. It does not fit a team wanting a finished multi-target tracker with a fixed model, since the package ships a framework rather than a tuned solution. Before adopting it, read the v1.9 release notes against your own code, check which optional extra each model you plan to use actually requires, and confirm that the release on PyPI matches the commit you intend to pin.

Frequently asked questions

Official sources

1. dstl/Stone-Soup on GitHub
2. License: MIT
3. Project website
4. README
5. Releases