Metadata-Version: 2.4
Name: blue-pebble
Version: 0.1.1
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/)

[![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, currently focused on passive sonar signal processing, acoustic propagation modelling, beamforming, detection, and multi-target tracking.

Designed as a plugin for [Stone Soup](https://stonesoup.rtfd.io/), Blue Pebble supports research in:

- Underwater acoustics
- Passive sonar signal processing
- Towed array modelling
- Acoustic propagation modelling
- Beamforming and detection theory
- Target tracking and data association

Blue Pebble provides modular acoustic propagation backends, ranging from analytical spreading laws to external ray-tracing solvers (e.g., rtrs), enabling trade-offs between physical fidelity and computational efficiency.

> **Naming conventions:** The project is referred to as **Blue Pebble** throughout documentation. The repository and PyPI package use the hyphenated form **blue-pebble** (e.g., `pip install blue-pebble`). Within Python code, the package is imported as **bluepebble** (e.g., `import bluepebble`).

## Research Applications

Blue Pebble is intended for controlled, simulation-based studies, including:

- Evaluation of tracking and data association algorithms  
- End-to-end sonar performance analysis  
- Synthetic dataset generation for validation  
- Sensitivity analysis of propagation effects on detection and estimation  

Although current functionality centres on passive sonar, the architecture supports extension to additional modalities (e.g., active or multistatic configurations).

## Architecture

Blue Pebble follows a modular design that separates physical modelling from signal processing and tracking logic. Core components include:

- **Platform dynamics** - Kinematic modelling of ownship, targets, and arrays  
- **Acoustic propagation** - Pluggable propagation backends (analytical or external solvers)  
- **Signal generation** - Source modelling and noise synthesis  
- **Beamforming** - Array processing algorithms  
- **Detection** - Measurement formation and statistical thresholding  
- **Tracking** - Integration with Stone Soup estimators and data association  

This separation enables systematic experimentation across modelling assumptions and algorithmic choices without tightly coupling components.

## Features

Implemented capabilities include:

- Multi-body kinematic modelling for flexible towed arrays  
- Analytical spreading models and external ray-tracing integration (e.g., rtrs)  
- Configurable source signature synthesis  
- Ambient, biological, and ownship noise modelling  
- Multiple beamforming algorithms  
- Detection algorithms with performance metrics  
- Passive sonar simulation pipelines  
- Integration of real environmental datasets (bathymetry, range-dependent sound speed profiles)
- Incorporation of measured source signatures
- Native integration with Stone Soup tracking workflows  
- Plotting utilities for bearings and Cartesian tracks  
- Notebook-based tutorials and worked examples

## Installation

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

## Development

### Recommended: Dev Container (Easiest Setup)

For a fully configured development environment, use the included Dev Container.

#### Requirements

- Docker Engine (Docker Desktop on Windows/macOS, or Docker on Linux)

Optional:
- Visual Studio Code
- VS Code Dev Containers extension

Clone the repository:
```bash
git clone https://github.com/UoL-SignalProcessingGroup/blue-pebble.git
```

#### Using the Dev Container (VS Code Workflow)

If using Visual Studio Code with the Dev Containers extension:
```bash
cd blue-pebble
code .
```

When prompted, select **"Reopen in Container."**

VS Code will:
- Build the Docker image
- Start the container
- Mount the repository
- Configure the Python interpreter automatically

This provides a fully configured development environment including:
- Python
- All required build dependencies including rtrs

#### Using the Container Without VS Code (CLI Workflow)

You can build and run the container manually:
```bash
docker build -t blue-pebble-dev .
docker run -it --rm -v $(pwd):/workspace blue-pebble-dev
```

On Windows PowerShell:
```bash
docker run -it --rm -v ${PWD}:/workspace blue-pebble-dev
```

This starts an interactive shell inside the container.

## 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}
}
```

## License

Blue Pebble is licensed under the MIT license.

See `LICENSE` and `NOTICE.md` for details.

## Third-Party Components

**Software:** Blue Pebble depends on [rtrs](https://pypi.org/project/rtrs/), which is licensed under the MIT licence and installed automatically as a dependency.

**Data:** Blue Pebble does not distribute external data in its PyPI package. Users are responsible for complying with the licences of any external data they utilise.

## Future Enhancements

Planned and potential extensions include:

### Environmental Modelling
- Coherent ambient noise modelling (wind, rain, wave-induced noise)
- Systematic environmental uncertainty modelling (sound speed and sensor position errors)

### Signal and Source Modelling
- Expanded source directivity modelling

### Detection and Performance Analysis
- Alternative SNR and beam power outputs (e.g., angle-dependent CFAR variants)
- Bearing × time × frequency output volume to support multi-band downstream processing
- Multi-band detector operating across frequency bands simultaneously
- 2D CFAR with training cells spanning both bearing and time, giving the detector access to a limited time history

### Sensing Modalities
- Active sonar modelling
- Multistatic and bistatic configurations
- Additional sensing geometries (hull-mounted arrays, sonobuoys, distributed arrays)
- Explicit hydrophone modelling
