Metadata-Version: 2.4
Name: bluecho-sonar
Version: 0.2.1
Summary: Offline sonar inference, physics-aware inspection and source-bound review
Author: Khushi Mhamane, Sharon Melhi, Kirti Rajput, Peeyush Rampal, Aditya Banerjee
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/Sharon-codes/SIH-2026
Project-URL: Repository, https://github.com/Sharon-codes/SIH-2026
Project-URL: Issues, https://github.com/Sharon-codes/SIH-2026/issues
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy==1.26.4
Requires-Dist: Pillow==12.3.0
Provides-Extra: inspection
Requires-Dist: psutil<8,>=7; extra == "inspection"
Requires-Dist: jsonschema<5,>=4.26; extra == "inspection"
Requires-Dist: pyproj==3.7.2; extra == "inspection"
Requires-Dist: pyxtf==1.4.2; extra == "inspection"
Provides-Extra: inference
Requires-Dist: ultralytics==8.4.150; extra == "inference"
Requires-Dist: opencv-python==4.11.0.86; extra == "inference"
Provides-Extra: onnx
Requires-Dist: onnxruntime==1.20.1; extra == "onnx"
Provides-Extra: geospatial
Requires-Dist: rasterio==1.4.3; extra == "geospatial"
Requires-Dist: pyproj==3.7.2; extra == "geospatial"
Provides-Extra: api
Requires-Dist: fastapi<1,>=0.115; extra == "api"
Requires-Dist: uvicorn<1,>=0.30; extra == "api"
Requires-Dist: python-multipart>=0.0.18; extra == "api"
Requires-Dist: httpx<1,>=0.27; extra == "api"
Provides-Extra: training
Requires-Dist: PyYAML==6.0.3; extra == "training"
Requires-Dist: psutil<8,>=7; extra == "training"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: jsonschema<5,>=4.26; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Requires-Dist: httpx<1,>=0.27; extra == "dev"
Dynamic: license-file

# BluEcho

**Local sonar inspection, detection, and evidence review.**

[Live dashboard](https://bluecho-sih-2026.vercel.app) · [Model weights](https://huggingface.co/SharonMelhi/BluEcho-SSS-Pipeline) · [PyPI package](https://pypi.org/project/bluecho-sonar/) · [Source code](https://github.com/Sharon-codes/SIH-2026) · [Documentation](https://github.com/Sharon-codes/SIH-2026/tree/main/docs) · [Report an issue](https://github.com/Sharon-codes/SIH-2026/issues)

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](https://bluecho-sih-2026.vercel.app) 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:

```bash
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 --upgrade 'bluecho-sonar[inspection,inference,onnx,api]'

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](https://github.com/Sharon-codes/SIH-2026/blob/main/docs/MODELS.md) 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:

```bash
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:

```bash
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

```bash
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](https://github.com/Sharon-codes/SIH-2026/blob/main/docs/DASHBOARD.md) for the inspection workflow, review controls, exports, and troubleshooting.

## Models and evidence

| Model | Sensor route | Intended labels | Current evidence and setup |
| --- | --- | --- | --- |
| `sss-pipeline-v3` | `SSS_LF` | Pipeline | Evaluated on correlated development observations from one survey. Requires verified local weights and their original manifest. |
| `sss-wreck-experimental` | `SSS` | Experimental pipeline and wreck candidates | Pinned ONNX download. Independent wreck performance is unavailable; additional native labels remain unvalidated proposals. |
| `uatd-fls` | `FLS_UATD` | Ten native classes, including cylinder | Selected compatibility sample; source overlap is unknown. Pinned acquisition with restricted conversion on Linux. |
| `fls-debris-development` | `FLS_ARIS` | Ten debris classes | Trained development detector without an independent benchmark. Requires verified local import; inherited CC BY-NC-SA terms apply. |

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:

```bash
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

| Guide | Contents |
| --- | --- |
| [Dashboard](https://github.com/Sharon-codes/SIH-2026/blob/main/docs/DASHBOARD.md) | Local setup, demonstration, review, exports, and troubleshooting |
| [Models and licences](https://github.com/Sharon-codes/SIH-2026/blob/main/docs/MODELS.md) | Model acquisition, hashes, offline use, and inherited terms |
| [CLI and Python interfaces](https://github.com/Sharon-codes/SIH-2026/blob/main/docs/INTERFACES.md) | Programmatic integration and command reference |
| [Validation](https://github.com/Sharon-codes/SIH-2026/blob/main/docs/VALIDATION.md) | Evaluation evidence and limitations |
| [Review workflow](https://github.com/Sharon-codes/SIH-2026/blob/main/docs/REVIEW.md) | Persistent review records and controlled export |
| [Geolocation](https://github.com/Sharon-codes/SIH-2026/blob/main/docs/GEOLOCATION.md) | Source binding, coordinate enrichment, and missing metadata |
| [Physics assumptions](https://github.com/Sharon-codes/SIH-2026/blob/main/docs/PHYSICS.md) | Sonar geometry, altitude prerequisites, and uncertainty |
| [SSS detection workflow](https://github.com/Sharon-codes/SIH-2026/blob/main/docs/SSS_DETECTION_PHASE1.md) | Boxes, crops, structured outputs, and local HTML reports |
| [Experimental verifiers](https://github.com/Sharon-codes/SIH-2026/blob/main/docs/FINAL_IMPROVEMENT.md) | Optional learned review scores and development comparisons |

## 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](https://github.com/Sharon-codes/SIH-2026/blob/main/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](https://github.com/Sharon-codes/SIH-2026/blob/main/docs/MODELS.md) 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](https://github.com/Sharon-codes/SIH-2026/issues).
