Metadata-Version: 2.4
Name: blue-pebble
Version: 0.1.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
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/)
[![Coverage](https://codecov.io/gh/jjwakefield/blue-pebble/branch/main/graph/badge.svg)](https://codecov.io/gh/jjwakefield/blue-pebble)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jjwakefield/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

### Basic Installation (Core Models Only)

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

This installs the core framework with built-in propagation models.

### Optional: Ray Tracing with rtrs

Blue Pebble supports ray traced propagation via the rtrs package.

rtrs is currently private, but will be made public in the near future. In the meantime, provided you have access it can be installed as follows.

#### Installing rtrs

Clone the repository:
```bash
git clone https://github.com/fincb/rtrs.git
```

With a Blue Pebble virtual environment activated, install with pip:
```bash
pip install -e /path/to/rtrs
```

## 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/jjwakefield/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 .
```

To include the optional rtrs backend, set `RTRS_URL` in your shell before opening VS Code:
```bash
export RTRS_URL="https://<token>@github.com/fincb/rtrs.git"
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
- Required build dependencies
- Optional propagation model backends (e.g., 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
```

To include the optional rtrs backend, pass its URL as a build argument:
```bash
docker build --build-arg RTRS_URL="https://<token>@github.com/fincb/rtrs.git" -t 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:** The optional rtrs backend is licensed under the MIT licence and is not distributed with Blue Pebble. Users are responsible for installing it separately.

**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
