DOCSEARCHbyAlgolia
Submit Docs

Stone Soup Documentation

repository·main·Indexed 20 days ago

https://github.com/dstl/stone-soup

A Python-based framework for developing, testing, and evaluating target tracking and state estimation algorithms. It provides tools for multi-object tracking, including components for transition and measurement models, Kalman filtering, data association via Global Nearest Neighbour (GNN), and track lifecycle management. The framework supports various data sources including CSV files, video clips, and real-time RTSP streams, and integrates with TensorFlow for object detection.

Tokens
38.1K
Snippets
101
Records
158
Agent score
69%

What's inside Stone Soup

  1. Overview of Stone Soup Predictors

    main

    Stone Soup provides a variety of Predictor implementations used to propagate state estimates forward in time. Predictors are categorized by their underlying mathematical approach, allowing users to choose between parametric (e.g., Kalman), non-parametric (e.g., Particle, Kernel), or hybrid methods.

    Available predictor types include:

    • Kalman: Parametric predictors based on Kalman filtering techniques.
    • Particle: Non-parametric predictors using particle filters.
    • Kernel: Predictors based on kernel density estimation.
    • Ensemble: Predictors that use an ensemble of models or states.
    • Information: Predictors operating in the information (inverse covariance) domain.
    • Accumulated State Densities (ASD): Predictors that manage state representations via accumulated densities.
    • Categorical: Predictors for discrete or categorical state spaces.
    • Composite: Predictors that combine multiple other predictor types.

  2. Overview of Stone Soup Data Types

    main
    Stone Soup uses a structured hierarchy of data types to represent various elements in tracking and estimation problems. These types are organized into specialized modules covering everything from basic numeric and time primitives to complex tracking constructs like tracks, hypotheses, and sensor data. Most types are designed to be used within estimation pipelines to ensure type safety and consistent data exchange between components.

  3. Overview of Stone Soup components and architecture

    main

    Stone Soup is a framework for building trackers using modular components. These components are categorized into two main groups:

    Enabling Components

    These components are used to build the overall tracker infrastructure and environment. They include:

    • stonesoup.architecture: The structural layout of the tracker.
    • stonesoup.detector: Logic for detecting objects.
    • stonesoup.feeder: Mechanisms for feeding data into the system.
    • stonesoup.metricgenerator: Generation of metrics.
    • stonesoup.movable: Components representing movable objects.
    • stonesoup.platform: The environment or platform context.
    • stonesoup.reader: Data ingestion from external sources.
    • stonesoup.sensor: Sensor models and logic.
    • stonesoup.sensormanager: Management of multiple sensors.
    • stonesoup.simulator: Simulation environments.
    • stonesoup.tracker: The core tracker implementation.
    • stonesoup.writer: Data output to external sources.

    Algorithm Components

    These components implement the mathematical and logical steps of the tracking algorithm, such as:

    • stonesoup.dataassociator: Data association logic.
    • stonesoup.deleter: Logic for removing tracks.
    • stonesoup.gater: Gating logic for measurements.
    • stonesoup.kernel: Core algorithmic kernels.
    • stonesoup.hypothesiser: Hypothesis generation.
    • stonesoup.initiator: Track initiation logic.
    • stonesoup.mixturereducer: Mixture reduction algorithms.
    • stonesoup.models: Motion and measurement models.
    • stonesoup.predictor: Prediction steps.
    • stonesoup.proposal: Proposal generation.
    • stonesoup.regulariser: Regularization logic.
    • stonesoup.resampler: Resampling methods.
    • stonesoup.sampler: Sampling logic.
    • stonesoup.smoother: Smoothing algorithms.
    • stonesoup.updater: State update logic.

  4. Overview of Data Association in Stone Soup

    main

    Data association in Stone Soup is used to link observations to existing tracks or to identify new tracks. The stonesoup.dataassociator module provides a variety of algorithms for different association scenarios, ranging from simple proximity-based methods to complex probabilistic models.

    Available association strategies include:

    • General Association: Generic association frameworks.
    • Neighbour: Association based on spatial proximity (nearest neighbors).
    • Probability: Probabilistic association methods (e.g., using likelihoods).
    • Track-to-track Association: Associating tracks from different sensor/processing streams.
    • CLEAR MOT Association: Implementation of algorithms used in Multiple Object Tracking (MOT) benchmarks.
    • Trees: Association using tree-based structures.
    • Multi-Frame Assignment (MFA): Algorithms designed for association across multiple time steps.

  5. Overview of Stone Soup

    main
    Stone Soup is a software framework designed for the target tracking and state estimation community. It provides tools for the development and testing of tracking and state estimation algorithms.

  6. Overview of Stone Soup Updaters

    main
    Updaters in Stone Soup are responsible for updating a state estimate (such as a state density or a point process) based on new observations. The stonesoup.updater module provides the base abstractions for these operations. Depending on your state representation and the nature of your observations, you can choose from several specialized updater implementations including Kalman, Particle, Kernel, Ensemble, and more.

  7. Overview of Hypothesiser implementations in Stone Soup

    main

    In Stone Soup, a Hypothesiser is used to generate hypotheses about the state of a system (e.g., target tracks) based on measurements or previous states. The stonesoup.hypothesiser module provides several specialized implementations depending on the mathematical model and assignment logic required:

    • Simple: Basic hypothesis generation.
    • Distance: Uses spatial distance metrics to associate measurements with tracks.
    • Probability: Uses probabilistic models for association.
    • Gaussian Mixture: Specifically designed for handling Gaussian Mixture Models (GMMs).
    • Categorical: Handles categorical state distributions.
    • Composite: Allows combining multiple hypothesiser strategies.
    • Multi-Frame Assignment (MFA): Handles hypothesis generation across multiple time frames rather than just single-frame associations.

  8. Use Metric Generators to evaluate tracking performance

    main

    Stone Soup provides a suite of MetricGenerator classes to evaluate the performance of tracking algorithms. These generators compare estimated tracks against ground truth data.

    Available metric categories include:

    • Basic Metrics: Fundamental tracking performance measures.
    • Track-to-Truth Metrics: Metrics specifically designed to compare estimated tracks against ground truth.
    • OSPA Metrics: Optimal Subpattern Assignment (OSPA) metrics for multi-target tracking.
    • PCRB Metrics: Posterior Cramér-Rao Bound metrics to assess theoretical performance limits.
    • Uncertainty Metrics: Metrics for evaluating the quality of state uncertainty estimates.
    • ClearMOT Metrics: Metrics following the ClearMOT (Clear Multiple Object Tracking) standard.
    • Plotter: Tools for visualizing metric results.

  10. Use Stone Soup base data types

    main

    Stone Soup provides a set of specialized base data types used to represent various elements in tracking and estimation workflows. These types are organized by their functional role in the system:

    Mathematical & State Representations

    • Matrix: A fundamental array type for linear algebra operations.
    • StateVector: A specialized vector representing the state of a system.
    • State: Represents the state of an object at a specific time.
    • Particle: Used in particle filtering to represent a sample of the state distribution.

    Tracking & Estimation Entities

    • Detection: A measurement or observation from a sensor.
    • Track: A sequence of states representing a single object's trajectory.
    • Prediction: An estimate of a future state.
    • Update: The result of combining a prediction with a new measurement.
    • SensorData: Encapsulates raw or processed data from a sensor.

    Hypothesis & Association

    • Association: Represents the link between two entities (e.g., a detection and a track).
    • Hypothesis: A single proposed explanation of the system state.
    • MultipleHypothesis: A collection of multiple hypotheses, often used in multi-hypothesis tracking (MHT).

    Ground Truth & Evaluation

    • GroundTruthState: The true state of an object at a specific time.
    • GroundTruthPath: The true trajectory of an object over time.
    • Metric: A value used to quantify the performance of an estimator or tracker.

  11. Use Stone Soup Readers to ingest data

    main

    Stone Soup provides a variety of Reader implementations to ingest data from different sources into the Stone Soup ecosystem. Readers are used to convert external data formats (like YAML, HDF5, or Kafka streams) into Stone Soup objects.

    Available reader types include:

    • File-based: YAMLReader, HDF5Reader
    • Streaming/Network: KafkaReader, AISHubReader, OpenSkyReader
    • Media: ImageReader, VideoReader
    • Data Structures: PandasDataFrameReader
    • Generic: GenericReader for custom implementations.

  12. Use the stonesoup.gater module for data association and filtering

    main
    The stonesoup.gater module provides tools for gating, which is the process of determining which measurements or tracks are eligible for association based on a distance metric. It includes base classes for defining gating logic and specific implementations for distance-based and filtered gating.