Metadata-Version: 2.4
Name: synapse-sr
Version: 0.4.2
Summary: Observation-consistent super-resolution of Sentinel-2 imagery to a 2 m grid
Author-email: Sharadh Naidu <sharadhanaidu@rvu.edu.in>
License: CC0-1.0
Project-URL: Homepage, https://github.com/SharadhNaidu/synapse-sr
Project-URL: Documentation, https://sharadhnaidu.github.io/synapse-sr/
Project-URL: Source, https://github.com/SharadhNaidu/synapse-sr
Project-URL: Issues, https://github.com/SharadhNaidu/synapse-sr/issues
Project-URL: Weights, https://huggingface.co/SharadhNaiduTrains/synapse-sr
Keywords: synapse-sr,synapse,sentinel-2,sentinel2,image-super-resolution,super-resolution,satellite-imagery,remote-sensing,earth-observation,deep-learning,mamba,geotiff,gis,copernicus,uncertainty,ndvi,change-detection,cartosat,india
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=1.13
Requires-Dist: numpy>=1.21
Requires-Dist: numpy<2; sys_platform == "darwin" and platform_machine == "x86_64"
Requires-Dist: safetensors>=0.3
Requires-Dist: rasterio>=1.3
Requires-Dist: affine>=2.3
Requires-Dist: scipy>=1.7
Requires-Dist: rich>=12
Requires-Dist: matplotlib>=3.3
Provides-Extra: stac
Requires-Dist: pystac-client>=0.6; extra == "stac"
Provides-Extra: xarray
Requires-Dist: xarray>=0.20; extra == "xarray"
Provides-Extra: cuda
Requires-Dist: mamba-ssm>=1.1; extra == "cuda"
Provides-Extra: openvino
Requires-Dist: openvino>=2024.4; extra == "openvino"
Provides-Extra: onnx
Requires-Dist: onnxruntime>=1.17; extra == "onnx"
Requires-Dist: onnxscript>=0.1; extra == "onnx"
Provides-Extra: onnx-gpu
Requires-Dist: onnxruntime-gpu>=1.17; extra == "onnx-gpu"
Requires-Dist: onnxscript>=0.1; extra == "onnx-gpu"
Provides-Extra: all
Requires-Dist: pystac-client>=0.6; extra == "all"
Requires-Dist: xarray>=0.20; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: pytest-cov>=4; extra == "test"
Requires-Dist: xarray>=0.20; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/SharadhNaidu/synapse-sr/main/docs/assets/logo-wordmark-dark.svg">
    <img src="https://raw.githubusercontent.com/SharadhNaidu/synapse-sr/main/docs/assets/logo-wordmark-card.png" alt="SYNAPSE-SR, Sentinel-2 super-resolution" width="440">
  </picture>
</p>
<h1 align="center">SYNAPSE-SR: Sentinel-2 super-resolution to 2 m</h1>

<h3 align="center">Sentinel-2 at 2 m, with every pixel accounted for</h3>

<p align="center">
  <a href="https://pypi.org/project/synapse-sr/"><img src="https://img.shields.io/pypi/v/synapse-sr?color=black" alt="PyPI"></a>
  <a href="https://pepy.tech/projects/synapse-sr"><img src="https://static.pepy.tech/personalized-badge/synapse-sr?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads" alt="PyPI Downloads"></a>
  <a href="https://github.com/SharadhNaidu/synapse-sr/actions/workflows/tests.yml"><img src="https://github.com/SharadhNaidu/synapse-sr/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
  <a href="https://sharadhnaidu.github.io/synapse-sr/"><img src="https://img.shields.io/badge/docs-online-black" alt="docs"></a>
  <a href="https://huggingface.co/SharadhNaiduTrains/synapse-sr"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20weights-Hugging%20Face-black" alt="Hugging Face weights"></a>
  <a href="https://colab.research.google.com/github/SharadhNaidu/synapse-sr/blob/main/notebooks/quickstart.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open in Colab"></a>
  <a href="https://kaggle.com/kernels/welcome?src=https://github.com/SharadhNaidu/synapse-sr/blob/main/notebooks/quickstart.ipynb"><img src="https://kaggle.com/static/images/open-in-kaggle.svg" alt="Open in Kaggle"></a>
  <a href="https://youtu.be/WCMb76ykUls"><img src="https://img.shields.io/badge/video-5%20min%20explainer-black?logo=youtube" alt="5-minute video explainer"></a>
  <a href="https://github.com/SharadhNaidu/synapse-sr/stargazers"><img src="https://img.shields.io/github/stars/SharadhNaidu/synapse-sr?style=social" alt="GitHub stars"></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/SharadhNaidu/synapse-sr/main/docs/assets/gifs/rv_university.gif" alt="RV University, Bengaluru: Sentinel-2 10 m and synapse-sr 2 m" width="440">
</p>

<p align="center"><b>Free Sentinel-2 imagery of anywhere on Earth, enhanced from 10 m to 2 m resolution, on a laptop.</b><br>
If it is useful to you, a ⭐ helps other people find it.</p>

**synapse-sr** turns a Sentinel-2 L2A scene into a 2.0 m red / green / blue / near-infrared GeoTIFF. A physical model
of the instrument pins everything the satellite measured. The network only adds what 10 m pixels cannot show, and
every output says which pixels came from the measurement and which came from the learned prior.

```bash
pip install synapse-sr
```

```python
import synapse_sr

r = synapse_sr.super_resolve("sentinel2_l2a.tif")   # progress bar, then a 5x larger result
r.save("sentinel2_2m.tif")                           # georeferenced, same CRS and bounds
r.summary()                                          # size, consistency, support, time
```

```bash
synapse-sr sentinel2_l2a.tif sentinel2_2m.tif        # the same from the shell
synapse-sr --fetch 12.92,77.50 --dates 2025-01-01:2025-03-15 out.tif --preview preview.png   # download + run
synapse-sr scenes/ scenes_2m/ --cog                  # a whole folder, as Cloud-Optimised GeoTIFFs
```

Every common task on one page: **[cheat sheet](https://sharadhnaidu.github.io/synapse-sr/cheatsheet/)**. AI assistants
and agents can read the whole documentation from [`llms.txt`](https://sharadhnaidu.github.io/synapse-sr/llms.txt).

## On real places

<table>
  <tr>
    <td align="center"><img src="https://raw.githubusercontent.com/SharadhNaidu/synapse-sr/main/docs/assets/gifs/bengaluru_urban.gif" alt="Bengaluru city centre: Sentinel-2 10 m and synapse-sr 2 m" width="260"><br><sub>Bengaluru city centre</sub></td>
    <td align="center"><img src="https://raw.githubusercontent.com/SharadhNaidu/synapse-sr/main/docs/assets/gifs/punjab_fields.gif" alt="Farm fields in Punjab: Sentinel-2 10 m and synapse-sr 2 m" width="260"><br><sub>Farm fields, Punjab</sub></td>
    <td align="center"><img src="https://raw.githubusercontent.com/SharadhNaidu/synapse-sr/main/docs/assets/gifs/wayanad_landslide.gif" alt="Wayanad landslide area: Sentinel-2 10 m and synapse-sr 2 m" width="260"><br><sub>Wayanad landslide, Kerala</sub></td>
  </tr>
</table>

Each pair is the same Sentinel-2 L2A scene at its native 10 m and after synapse-sr. Run your own place with
`synapse-sr --fetch LAT,LON out.tif`, or [watch the 5-minute explainer](https://youtu.be/WCMb76ykUls).

## Benchmarks

Official [opensr-test](https://github.com/ESAOpenSR/opensr-test) protocol (Aybar et al.): Sentinel-2 L2A input, harmonised
high-resolution references, `opensr_test.Metrics()` defaults, mean over its five datasets (NAIP, SPOT, Spain urban,
Spain crops, VENµS; 178 scenes). Every model at its native scale, compared on the reference grid.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/SharadhNaidu/synapse-sr/main/docs/assets/benchmark-dark.png">
    <img src="https://raw.githubusercontent.com/SharadhNaidu/synapse-sr/main/docs/assets/benchmark-light.png" alt="Official Sentinel-2 super-resolution benchmark: SYNAPSE leads on 5 of 7 measures" width="100%">
  </picture>
</p>

| Model | Improvement ↑ | Omission ↓ | Hallucination ↓ | Detail corr. ↑ | RMSE ↓ | Spectral error ↓ | Reflectance error ↓ |
|---|---|---|---|---|---|---|---|
| **SYNAPSE Flash** | 0.155 | 0.748 | 0.097 | **0.300** | **0.0234** | 0.401 | 0.0018 |
| **SYNAPSE Pro** | **0.199** | 0.631 | 0.171 | 0.289 | 0.0254 | **0.223** | **0.0011** |
| SEN2SR | 0.150 | 0.759 | 0.091 | 0.284 | 0.0235 | 0.665 | 0.0025 |
| SEN2SR-Lite | 0.152 | 0.749 | 0.099 | 0.290 | **0.0234** | 0.463 | 0.0019 |
| LDSR-S2 | 0.197 | 0.599 | 0.204 | 0.206 | 0.0240 | 1.015 | 0.0036 |
| Satlas ESRGAN | 0.129 | **0.181** | 0.690 | 0.089 | 0.0443 | 7.787 | 0.0242 |
| Bicubic | 0.102 | 0.830 | **0.068** | 0.279 | **0.0234** | 0.601 | 0.0028 |

**Best** in bold. SYNAPSE runs with the package defaults (`synapse_sr.super_resolve`). SYNAPSE is best on five of the
seven columns: Pro on improvement, spectral and reflectance error, Flash on detail correlation and (tied) RMSE. Flash processes
a 1.28 km scene in about 1 s on a laptop CPU; Pro in about 5 s on a GPU.

## What it is for

| | One line | |
|---|---|---|
| **Crop monitoring** | `r.indices()["ndvi"]`, `synapse_sr.boundaries(r, "field")` | NDVI, SAVI, EVI, red-edge NDRE, field edges at 2 m |
| **Urban analysis** | `synapse_sr.boundaries(r, "urban")`, `r.indices()["ndbi"]` | buildings, roads, built-up index |
| **Water and floods** | `synapse_sr.change(before, after, "ndwi")` | flooded area in km², shoreline strength |
| **Disaster assessment** | `synapse_sr.change(before, after, "nbr")` | burn scars, landslides, debris; changes flagged only where both dates are trustworthy |

Worked examples for each: [Applications](https://sharadhnaidu.github.io/synapse-sr/applications/).

## Flash or Pro

| | **Flash** (default) | **Pro** |
|---|---|---|
| Network | ~0.6 M-parameter re-parameterised CNN, distilled from Pro | 14.4 M-parameter state-space (Mamba) model |
| Speed (1.28 km scene) | ~1 s on a laptop CPU; 10 km x 10 km in ~14 s | ~5 s on a GPU (Colab / Kaggle T4, workstations) |
| Runs on | any CPU, laptops, integrated graphics, Apple silicon, ARM, any GPU | GPU recommended; CPU works, slower |
| Choose it | `synapse_sr.super_resolve(src)` | `synapse_sr.super_resolve(src, model="pro")` |
| Load | `Flash.from_pretrained()` | `Pro.from_pretrained()` |
| Tuned for | balanced fidelity: best detail correlation, lowest RMSE (tied), measured 10 m mean reflectance restored exactly | maximum detail: best improvement, spectral and reflectance error |
| Physics, support map, calibrated uncertainty | yes | yes |

Both run the same observation-consistent pipeline. Use **Flash** for speed, anywhere-deployment and the most faithful
output, **Pro** for the most recovered detail on a GPU. `synapse-sr --models` lists
every published checkpoint.

## Why trust the output

```python
import synapse_sr
r = synapse_sr.super_resolve("scene.tif")

r.x_base        # what the 10 m observation determines
r.prior         # what the network added (x_base + prior == image), invisible to the sensor
r.support       # per pixel: 2 observation-determined, 1 medium, 0 prior-dominated or invalid
r.uncertainty() # calibrated expected error per pixel and band
r.consistency   # how closely re-observing the output reproduces the input, in sensor-noise units
```

`x_hat = x_base + P_N(delta)`: `P_N` removes every component the sensor could have seen from the network's
output, so the network cannot contradict the measurement. See [How it works](https://sharadhnaidu.github.io/synapse-sr/method/).

## Runs everywhere

| Platform | What you get |
|---|---|
| Colab / Kaggle GPU | Pro with a Triton scan kernel, compiled on first use (no extra installs) |
| Linux GPU + `mamba-ssm` | fused CUDA kernel (`pip install "synapse-sr[cuda]"`) |
| Windows / macOS / CPU-only / ARM | exact PyTorch path; Flash recommended |
| Offline / air-gapped | `Pro.from_pretrained(weights="model.safetensors")` |

`synapse-sr --env` shows what is active on your machine.

See [Hardware compatibility](https://sharadhnaidu.github.io/synapse-sr/guide/hardware/) for the full device and runtime matrix (CUDA, ROCm, MPS, OpenVINO, ONNX Runtime, TensorRT), including preview backends.

## Documentation

[Quick start](https://sharadhnaidu.github.io/synapse-sr/quickstart/) ·
[Colab and Kaggle](https://sharadhnaidu.github.io/synapse-sr/guide/notebooks/) ·
[Applications](https://sharadhnaidu.github.io/synapse-sr/applications/) ·
[Examples](https://sharadhnaidu.github.io/synapse-sr/examples/) ·
[API](https://sharadhnaidu.github.io/synapse-sr/api/)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Report security issues privately per
[SECURITY.md](SECURITY.md); accessibility barriers are tracked as bugs, see
[ACCESSIBILITY.md](ACCESSIBILITY.md). Bug reports and feature requests use the
issue templates; pull requests follow the PR template checklist.

<details>
<summary>Citation and acknowledgements</summary>

```bibtex
@software{synapse_sr,
  title  = {synapse-sr: observation-consistent super-resolution of Sentinel-2 imagery},
  author = {Naidu, Sharadh},
  year   = {2026},
  url    = {https://github.com/SharadhNaidu/synapse-sr}
}
```

- Third-party components and their licences are listed in `THIRD_PARTY_NOTICES`.
- The optional fused kernel comes from [mamba-ssm](https://github.com/state-spaces/mamba) (Apache-2.0).
- Sentinel-2 data: Copernicus programme, European Space Agency.

</details>

## Star history

<a href="https://star-history.com/#SharadhNaidu/synapse-sr&Date">
  <img src="https://api.star-history.com/svg?repos=SharadhNaidu/synapse-sr&type=Date" alt="Star history of synapse-sr" width="600">
</a>
