Metadata-Version: 2.4
Name: blue-pebble
Version: 0.4.0
Summary: A Stone Soup plugin for underwater acoustic sensing.
Author-email: Joshua J Wakefield <J.J.Wakefield@liverpool.ac.uk>, Fin Boulton <F.Boulton@liverpool.ac.uk>
Maintainer-email: Joshua J Wakefield <J.J.Wakefield@liverpool.ac.uk>, Fin Boulton <F.Boulton@liverpool.ac.uk>
License-Expression: MIT
Project-URL: Repository, https://github.com/UoL-SignalProcessingGroup/blue-pebble
Project-URL: Documentation, https://blue-pebble.readthedocs.io
Project-URL: Bug Tracker, https://github.com/UoL-SignalProcessingGroup/blue-pebble/issues
Keywords: blue pebble,underwater acoustics,passive sonar,beamforming,detection,tracking,stone soup
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Requires-Dist: stonesoup>=1.8
Requires-Dist: numba>=0.56
Requires-Dist: rocket-fft>=0.3.1
Requires-Dist: tqdm>=4.64
Requires-Dist: plotly>=5
Requires-Dist: dash>=4.0.0
Requires-Dist: cmocean>=4.0.3
Requires-Dist: netCDF4>=1.7.4
Requires-Dist: rtrs>=0.2.3
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: pyright>=1.1.408; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: sphinx-gallery>=0.15; extra == "docs"
Requires-Dist: kaleido>=1.0.0; extra == "docs"
Provides-Extra: examples
Requires-Dist: ipykernel; extra == "examples"
Requires-Dist: ipywidgets; extra == "examples"
Requires-Dist: jupyterlab; extra == "examples"
Dynamic: license-file

# Blue Pebble

[![PyPI version](https://img.shields.io/pypi/v/blue-pebble.svg)](https://pypi.org/project/blue-pebble/)
[![Python versions](https://img.shields.io/pypi/pyversions/blue-pebble.svg)](https://pypi.org/project/blue-pebble/)
[![Documentation](https://readthedocs.org/projects/blue-pebble/badge/?version=latest)](https://blue-pebble.readthedocs.io/en/latest/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/UoL-SignalProcessingGroup/blue-pebble/blob/main/LICENSE)

**Blue Pebble** is a research-oriented simulation framework for underwater acoustic sensing, built as a plugin for [Stone Soup](https://stonesoup.rtfd.io/). It currently focuses on passive sonar: acoustic propagation modelling, beamforming, detection and multi-target tracking.

## Installation

```bash
pip install blue-pebble
```

The package installs as `blue-pebble` and imports as `bluepebble`.

## Getting Started

Start with the [Getting Started tutorial](https://blue-pebble.readthedocs.io/en/latest/auto_tutorials/getting_started.html), which simulates a towed array and beamforms, detects and tracks a single target. The [documentation](https://blue-pebble.readthedocs.io/en/latest/) also has further tutorials, worked examples and the API reference.

## Features

- Towed-array kinematics for the ownship, targets and array elements
- Acoustic propagation, from analytical spreading laws to ray tracing with [rtrs](https://pypi.org/project/rtrs/)
- Environments built from analytical profiles or measured bathymetry and sound-speed data
- Source and noise synthesis, including biological, anthropogenic and ownship noise
- Delay-and-sum and MVDR (Minimum Variance Distortionless Response) beamforming
- CFAR (Constant False Alarm Rate) detection, calibrated from noise or with a fixed threshold
- Detections that feed straight into Stone Soup trackers

## Contributing

See [CONTRIBUTING.md](https://github.com/UoL-SignalProcessingGroup/blue-pebble/blob/main/CONTRIBUTING.md) for the development setup and workflow, and the [roadmap](https://blue-pebble.readthedocs.io/en/latest/roadmap.html) for planned extensions.

## Citation

If you use Blue Pebble in academic work, please cite the associated conference paper and the software release (via DOI when available).

```bibtex
@inproceedings{wakefield2026sonar,
  title={A Sonar Signal Processing Plugin for Stone Soup},
  author={Wakefield, Joshua J and Boulton, Finley and Colquitt, Daniel J. and Ralph, Jason F. and Williams, Duncan P.},
  booktitle={2026 29th International Conference on Information Fusion (FUSION)},
  pages={1--8},
  year={2026},
  organization={IEEE}
}
```

## Licence

Blue Pebble is released under the MIT licence; see [LICENSE](https://github.com/UoL-SignalProcessingGroup/blue-pebble/blob/main/LICENSE) and [NOTICE.md](https://github.com/UoL-SignalProcessingGroup/blue-pebble/blob/main/NOTICE.md). Its ray-tracing dependency, [rtrs](https://pypi.org/project/rtrs/), is also MIT-licensed and installs automatically. The package includes no external data, so users are responsible for complying with the licences of any data they use with it.
