BluEcho

Local sonar inspection, detection, and evidence review.

Live dashboard · Model weights · PyPI package · Source code · Documentation · Report an issue

BluEcho is a Python toolkit and local dashboard for turning sonar imagery into reviewable detection results. It brings together model inference, annotated images, human review, and structured exports in a workflow that can run offline after dependencies and model files have been prepared.

Created for the Smart India Hackathon (SIH) 2026 by Khushi Mhamane, Sharon Melhi, Kirti Rajput, Peeyush Rampal, and Aditya Banerjee.

The project is a research prototype. Its side-scan sonar (SSS) and forward-looking sonar (FLS) routes use separate models with different evidence and limitations; the capability table below explains what each route supports.

What BluEcho provides

• Sonar detection: explicit model and sensor selection, with predictions expressed in original image coordinates.
• Local inspection dashboard: a bundled React interface and Python API for running inspections, examining candidates, and reviewing results.
• Traceable human review: persistent review history, corrected boxes, labels, and false-alert decisions while preserving original predictions.
• Portable evidence: annotated images, object crops, JSON/CSV, GeoJSON, and local HTML review bundles through the relevant inspection and export commands.
• Source-bound geolocation: coordinate enrichment when verified raster metadata or a matching sidecar supports it. Results without defensible locations retain null geometry.
• Controlled model setup: explicit acquisition or local import, pinned model hashes, and separate model/data licence information.

Website and on-device inference

The redesigned BluEcho website runs the pipeline ONNX model inside your browser. Sonar images and review records stay in browser storage; no Python API or paid cloud inference server is required. First use downloads the hash-verified 10.6 MB model from Hugging Face and the WebAssembly runtime from the site.

The web edition supports PNG, JPEG, BMP and PBM/portable images (32 MiB, up to 8 million pixels), tiled pipeline detection, image/map review, source-bound affine JSON metadata in EPSG:4326 or EPSG:3857, and JSON/CSV/GeoJSON/HTML/ZIP downloads. Keep the tab open during inference and export reports before clearing site data. Browser reports use the explicit bluecho-browser/1.0 schema; the Python API retains its existing schema.

The local application provides raw XTF, TIFF/GeoTIFF, additional model routes and broader metadata support. Browser execution is a separate runtime check, not a new accuracy benchmark. The public web detector labels pipelines only.

Installation

The full application is tested on Linux x86-64 with Python 3.12. A GPU is not required for the CPU setup below. Other platforms are not verified for the complete workflow.

Create a virtual environment and install the CPU PyTorch build before the inference dependencies:

python3.12 -m venv .venv
source .venv/bin/activate

python -m pip install torch==2.4.1+cpu torchvision==0.19.1+cpu \
  --index-url https://download.pytorch.org/whl/cpu
python -m pip install 'bluecho-sonar[inspection,inference,onnx,api]==0.1.5'

bluecho --version
bluecho doctor
bluecho capabilities

The package name is bluecho-sonar; the Python import and command are both bluecho. The base package requires only NumPy and Pillow. Optional extras provide inspection, inference, ONNX, geospatial, API, and training dependencies. Add the geospatial extra when working with raster georeferencing.

Large detector weights and datasets are acquired separately. The distribution includes model metadata and small fitted verifier parameters. See the model setup guide for acquisition, verification, licensing, and offline installation.

Quick start

1. Prepare a model

The experimental SSS route has a pinned ONNX download of approximately 43 MiB. Review its model/data terms using bluecho capabilities before use:

bluecho models fetch --model sss-wreck-experimental \
  --registry "$HOME/.cache/bluecho/models"
bluecho models verify --model sss-wreck-experimental \
  --registry "$HOME/.cache/bluecho/models"

This route produces experimental candidates; an independent wreck benchmark is unavailable.

2. Inspect a local image

Replace the example paths with your own input and a new output directory:

bluecho inspect '/absolute/path/sonar.jpg' \
  --modality SSS \
  --model sss-wreck-experimental \
  --registry "$HOME/.cache/bluecho/models" \
  --output '/absolute/path/new-inspection'

inspect runs on CPU and writes model results and a separate inspection record per window. Select the route that matches the source sensor; SSS and FLS inputs are not interchangeable.

3. Open the dashboard

bluecho serve \
  --registry "$HOME/.cache/bluecho/models" \
  --storage "$HOME/bluecho-inspections" \
  --port 8010

Open http://127.0.0.1:8010 in your browser. The frontend is included in the package, so running it does not require Node.js. The local server provides interactive API documentation at /docs.

See the dashboard guide for the inspection workflow, review controls, exports, and troubleshooting.

Models and evidence

The FLS debris labels are can, bottle, drink-carton, chain, propeller, tire, hook, valve, shampoo-bottle, and standing-bottle. A bottle label alone does not establish plastic composition. FLS cylinder support does not establish SSS cylinder detection. Verified real ghost-net detection is unavailable.

For the pipeline route, keep the original manifest.json beside your authorized native checkpoint, then import it:

bluecho models import --model sss-pipeline-v3 \
  --registry "$HOME/.cache/bluecho/models" \
  --local '/absolute/path/sss-v3/native.pt'

bluecho inspect '/absolute/path/pipeline.pbm' \
  --modality SSS_LF \
  --model sss-pipeline-v3 \
  --registry "$HOME/.cache/bluecho/models" \
  --output '/absolute/path/new-pipeline-inspection'

Interpreting results

Detection scores are uncalibrated model scores, not probabilities of correct identification. Repeated views within a survey are correlated, and development results do not establish performance at new sites or across the ocean. An empty result is not proof that an area is clear.

Geolocation depends on verified source metadata and sensor assumptions. BluEcho does not invent latitude, longitude, altitude, surveyed area, or physical object identity when those inputs are absent. Image-based acoustic verifiers remain exploratory and do not establish a physics-informed neural network or foundation model.

Human review records are retained separately from automatic predictions. Reviewing an image does not trigger training or silently change the detector.

Documentation

Team · SIH 2026

BluEcho was made for the Smart India Hackathon 2026 by:

• Khushi Mhamane
• Sharon Melhi
• Kirti Rajput
• Peeyush Rampal
• Aditya Banerjee

Licence and acknowledgements

The BluEcho source code is licensed under AGPL-3.0-or-later. See LICENSE.

Third-party models, datasets, and examples retain their own licences and attribution requirements. The software licence does not replace those terms. BluEcho acknowledges the researchers and maintainers whose sonar datasets, model releases, and open-source tools support this work; consult the model documentation and packaged manifests for source-specific details.

For reproducible bug reports, include the package version, platform, selected model and modality, the command used, and a non-sensitive description of the input. Submit reports through GitHub Issues.