README.md

# 🌍 TerraVision

### Sharper Earth. Brighter Decisions.

**TerraVision** is a GIS-based satellite imagery analysis platform that uses **Sentinel-2 satellite data** and the official **ESA OpenSR LDSR-S2 + SEN2SR super-resolution pipeline** to generate model-based **2.5 m resolution imagery** from freely available Sentinel-2 data.

The platform combines satellite image super-resolution, geospatial processing, spectral analysis, visualization, and GeoTIFF export into a single web-based workflow.

---

## 🚀 Overview

Sentinel-2 provides freely available multispectral imagery, but its spatial resolution can be limiting for detailed geospatial analysis.

TerraVision addresses this challenge by:

1. Selecting a location using latitude/longitude or an interactive map.
2. Selecting a date range for Sentinel-2 imagery.
3. Retrieving Sentinel-2 L2A data.
4. Applying the **ESA LDSR-S2 + SEN2SR** super-resolution pipeline.
5. Generating a model-based **2.5 m resolution, 10-band output**.
6. Producing multiple GIS analysis layers.
7. Providing an original-vs-super-resolved comparison.
8. Exporting georeferenced GeoTIFF files and a ZIP containing all outputs.

> **Important:** The 2.5 m imagery generated by TerraVision is a model-based reconstruction. It is not native 2.5 m satellite observation.

---

# ✨ Key Features

### 🛰️ Sentinel-2 Data
- Sentinel-2 L2A imagery
- 10 spectral bands
- User-defined geographical location
- User-defined date range

### 🔬 AI-Based Super Resolution
- ESA OpenSR **LDSR-S2 + SEN2SR**
- 10 m input
- Model-generated 2.5 m output
- 4× spatial upscaling
- 10-band super-resolved output

### 🗺️ GIS Visualization
TerraVision generates:

- Super-Resolved RGB
- Original Sentinel-2 RGB
- False Color / Infrared
- SWIR Composite
- NDVI
- NDWI
- NDBI
- NBR
- LDSR-S2 Uncertainty

### 📊 Image Comparison
An interactive before/after comparison allows users to visually compare:

**Original Sentinel-2 → Super-Resolved Output**

### 💾 Geospatial Export
Users can download:

- Individual GeoTIFF layers
- Complete ZIP package containing all generated layers

All exported layers preserve their geospatial reference information.

---

# 🧠 Super-Resolution Pipeline

TerraVision uses the official ESA OpenSR approach combining:

```text
Sentinel-2 L2A
      │
      ▼
Data Retrieval
      │
      ▼
10-band Sentinel-2 Input
      │
      ▼
LDSR-S2 + SEN2SR
      │
      ▼
2.5 m Super-Resolved Output
      │
      ├── B02
      ├── B03
      ├── B04
      ├── B05
      ├── B06
      ├── B07
      ├── B08
      ├── B8A
      ├── B11
      └── B12
      │
      ▼
GIS Analysis Layers
````

The pipeline combines the strengths of:

### LDSR-S2

Latent diffusion super-resolution for Sentinel-2 RGB-NIR information.

### SEN2SR

Super-resolution processing for the additional Sentinel-2 spectral bands.

Together, they provide the 10-band super-resolved output used by TerraVision.

---

# 🛰️ Sentinel-2 Bands

| Band | Description         | Resolution |
| ---- | ------------------- | ---------- |
| B02  | Blue                | 10 m       |
| B03  | Green               | 10 m       |
| B04  | Red                 | 10 m       |
| B05  | Vegetation Red Edge | 20 m       |
| B06  | Vegetation Red Edge | 20 m       |
| B07  | Vegetation Red Edge | 20 m       |
| B08  | NIR                 | 10 m       |
| B8A  | Narrow NIR          | 20 m       |
| B11  | SWIR 1              | 20 m       |
| B12  | SWIR 2              | 20 m       |

The super-resolution pipeline produces these bands at the model-generated 2.5 m output scale.

---

# 📊 Spectral Analysis

TerraVision converts the super-resolved bands into several commonly used remote-sensing indices.

## 🌱 NDVI

**Normalized Difference Vegetation Index**

```text
NDVI = (B08 - B04) / (B08 + B04)
```

Used to analyze vegetation density and vegetation condition.

---

## 💧 NDWI

TerraVision uses the Green-NIR formulation:

```text
NDWI = (B03 - B08) / (B03 + B08)
```

Used to highlight water-related features.

---

## 🏙️ NDBI

**Normalized Difference Built-up Index**

```text
NDBI = (B11 - B08) / (B11 + B08)
```

Used for identifying built-up and urban areas.

---

## 🔥 NBR

**Normalized Burn Ratio**

```text
NBR = (B08 - B12) / (B08 + B12)
```

Useful for analyzing burn-affected areas and vegetation disturbance.

---

# 🎨 Visualization Layers

TerraVision provides several visualization products.

### RGB Composite

```text
R = B04
G = B03
B = B02
```

Provides a natural-color representation.

### False Color Composite

```text
R = B08
G = B04
B = B03
```

Useful for vegetation analysis.

### SWIR Composite

```text
R = B12
G = B11
B = B04
```

Useful for analyzing moisture, soil, built-up areas and burned regions.

---

# 📈 Uncertainty Map

TerraVision also exposes the uncertainty estimation available from the underlying **LDSR-S2 RGB-NIR component**.

The uncertainty map highlights areas where the super-resolution model has greater variation across generated samples.

```text
Dark  → Lower estimated uncertainty
Bright → Higher estimated uncertainty
```

### Important limitation

This should **not** be interpreted as a calibrated confidence score for the complete 10-band output.

The current implementation calculates uncertainty from the underlying **4-band LDSR-S2 RGB-NIR model**.

---

# 🗺️ TerraVision Workflow

```text
User
 │
 ├── Select Location
 │       └── Latitude / Longitude
 │
 ├── Select Date Range
 │
 ▼
Sentinel-2 L2A Data
 │
 ▼
Preprocessing
 │
 ▼
ESA LDSR-S2 + SEN2SR
 │
 ▼
2.5 m Super-Resolved Imagery
 │
 ├── RGB
 ├── False Color
 ├── SWIR
 ├── NDVI
 ├── NDWI
 ├── NDBI
 ├── NBR
 └── Uncertainty
 │
 ▼
Interactive Visualization
 │
 ▼
GeoTIFF / ZIP Export
```

---

# 🛠️ Technology Stack

## Frontend / UI

* Python
* Gradio
* Interactive visualization
* Image comparison slider
* GIS map integration

## Machine Learning

* PyTorch
* ESA OpenSR
* LDSR-S2
* SEN2SR

## Geospatial Processing

* Rasterio
* Rioxarray
* GeoPandas
* PyProj
* Xarray
* Dask
* Cubo

## Satellite Data

* Sentinel-2 L2A
* STAC-based data access

## Model / Data Management

* MLSTAC
* Hugging Face ecosystem

## Deployment

* Hugging Face Spaces
* Gradio
* ZeroGPU-compatible architecture

---

# 📦 Installation

Clone the repository:

```bash
git clone https://github.com/prateeksharmacoder-sys/satellite-LDRS-SEN2SR.git
cd TerraVision
```

Create a virtual environment:

```bash
python -m venv venv
```

Activate it.

### Windows

```bash
venv\Scripts\activate
```

### Linux / macOS

```bash
source venv/bin/activate
```

Install dependencies:

```bash
pip install -r requirements.txt
```

---

# ▶️ Running the Application

Run:

```bash
python app.py
```

The Gradio interface will provide a local web address.

For development, the application can also be launched with:

```python
demo.launch()
```

---

# 📁 Project Structure

```text
TerraVision/
│
├── app.py
├── requirements.txt
├── README.md
│
├── models/
│   └── model configuration / model assets
│
├── utils/
│   ├── preprocessing.py
│   ├── visualization.py
│   ├── geotiff.py
│   └── analysis.py
│
├── outputs/
│   └── generated products
│
└── assets/
    └── UI images / project assets
```

> The exact structure may vary depending on the final deployment version.

---

# 🔬 Technical Implementation

### 1. Data Retrieval

TerraVision retrieves Sentinel-2 L2A imagery using a STAC-based workflow.

The application requests:

```text
B02
B03
B04
B05
B06
B07
B08
B8A
B11
B12
```

---

### 2. Preprocessing

Sentinel-2 reflectance values are converted into normalized floating-point values before inference.

```python
low_resolution = low_resolution / 10000
```

---

### 3. Super Resolution

The combined model is loaded and executed using SEN2SR:

```python
super_resolution = sen2sr.predict_large(
    model=model,
    X=low_resolution,
    overlap=16
)
```

The model converts:

```text
10 × 128 × 128
```

into approximately:

```text
10 × 512 × 512
```

---

### 4. Spectral Products

The generated bands are used to calculate spectral indices such as:

```python
NDVI = (B08 - B04) / (B08 + B04)
NDWI = (B03 - B08) / (B03 + B08)
NDBI = (B11 - B08) / (B11 + B08)
NBR  = (B08 - B12) / (B08 + B12)
```

---

### 5. Geospatial Export

Generated products are exported as GeoTIFF files while preserving:

* CRS
* Spatial transform
* Resolution
* Geographic bounds

The prototype output was verified at:

```text
Resolution: 2.5 m
CRS: EPSG:32630
Output size: 512 × 512
```

The exact CRS changes according to the selected geographic location.

---

# 📥 Output Files

A typical output package contains:

```text
terravision_layers.zip
│
├── sr_rgb.tif
├── false_color.tif
├── swir.tif
├── ndvi.tif
├── ndwi.tif
├── ndbi.tif
├── nbr.tif
└── uncertainty.tif
```

---

# ⚡ Performance

The current prototype has been successfully tested end-to-end with:

```text
Sentinel-2 input:       10 × 128 × 128
Super-resolution:       10 × 512 × 512
Output resolution:      2.5 m
Analysis layers:        8
GeoTIFF export:         Successful
ZIP generation:         Successful
```

The super-resolution inference is the computationally expensive part of the pipeline.

Uncertainty estimation requires additional inference and is therefore treated as an optional computational component for deployment optimization.

---

# ⚠️ Limitations

TerraVision currently has several limitations.

### 1. Model-Based Resolution

The 2.5 m output is reconstructed by an AI model and is not equivalent to native 2.5 m satellite imagery.

### 2. Reconstruction Errors

Super-resolution models can introduce artifacts or reconstruct details that are not directly observed in the original imagery.

### 3. Cloud and Atmospheric Effects

Clouds, haze and poor-quality Sentinel-2 observations can affect the output.

### 4. Scientific Validation

The current prototype has been technically validated for:

* successful model inference
* correct output dimensions
* spectral layer generation
* GeoTIFF generation
* geospatial referencing

A comprehensive validation against independent high-resolution reference imagery using metrics such as **PSNR, SSIM and spectral consistency** remains future work.

### 5. Uncertainty

The current uncertainty output represents the LDSR-S2 RGB-NIR component rather than a calibrated uncertainty estimate for all 10 bands.

### 6. Temporal Analysis

Change detection such as **dNBR** requires pre-event and post-event imagery and is not part of the current single-image workflow.

---

# 🔮 Future Scope

Potential future improvements include:

* Multi-date satellite analysis
* Automated change detection
* dNDVI / dNBR analysis
* Cloud masking
* Larger-area processing
* Batch processing
* More advanced GIS layers
* Scientific validation using higher-resolution reference imagery
* Performance optimization
* GPU acceleration
* Caching of satellite data
* Production-scale deployment
* User accounts and project history
* Export to additional GIS formats

---

# 🌐 Deployment

TerraVision is designed to be deployed as a Gradio application.

The planned deployment architecture is:

```text
User
  │
  ▼
TerraVision Web Interface
  │
  ▼
Gradio Application
  │
  ├── Satellite Data Retrieval
  │
  ├── GPU Inference
  │
  ├── Spectral Analysis
  │
  └── GeoTIFF Generation
  │
  ▼
Results + Downloads
```

The application can be adapted for GPU-backed deployment using **Hugging Face Spaces ZeroGPU**.

---

# 🧪 Validation Status

| Component                       | Status         |
| ------------------------------- | -------------- |
| Sentinel-2 data retrieval       | ✅ Tested       |
| 10-band input generation        | ✅ Tested       |
| LDSR-S2 + SEN2SR inference      | ✅ Tested       |
| 2.5 m output generation         | ✅ Tested       |
| RGB generation                  | ✅ Tested       |
| False Color                     | ✅ Tested       |
| SWIR                            | ✅ Tested       |
| NDVI                            | ✅ Tested       |
| NDWI                            | ✅ Tested       |
| NDBI                            | ✅ Tested       |
| NBR                             | ✅ Tested       |
| LDSR-S2 uncertainty             | ✅ Tested       |
| GeoTIFF export                  | ✅ Tested       |
| Georeferencing                  | ✅ Verified     |
| ZIP export                      | ✅ Tested       |
| Interactive web UI              | ✅ Prototype    |
| Scientific benchmark validation | 🔄 Future work |
| Production-scale deployment     | 🔄 Planned     |

---

# 🎯 Use Cases

TerraVision can support exploratory analysis in areas such as:

* 🌱 Vegetation monitoring
* 💧 Water-body analysis
* 🏙️ Urban expansion studies
* 🔥 Burn-area analysis
* 🌾 Agricultural monitoring
* 🛰️ Remote-sensing research
* 🗺️ GIS analysis
* 🌍 Environmental monitoring

---

# 📚 Acknowledgements

TerraVision builds upon open-source satellite super-resolution research and software from the **European Space Agency (ESA) OpenSR project**, including LDSR-S2 and SEN2SR.

The project also uses open geospatial and satellite-data technologies including:

* Sentinel-2
* Cubo
* MLSTAC
* PyTorch
* Rasterio
* Xarray
* Gradio

---

# 📜 Disclaimer

TerraVision is a research and demonstration project.

The generated 2.5 m imagery should not automatically be treated as equivalent to native high-resolution satellite imagery. Results may contain model reconstruction artifacts and should be independently validated before being used for critical scientific, commercial, legal, or operational decisions.

---

# 👨‍💻 Project

**TerraVision**

> *Sharper Earth. Brighter Decisions.*

Built as a geospatial AI project for exploring the potential of satellite-image super-resolution and GIS analysis.

---

## ⭐ If you find TerraVision interesting

Consider giving the repository a ⭐ and exploring the implementation.

````

### Recommended GitHub repository files

For your current project, I would keep the repository clean like this:

```text
TerraVision/
│
├── README.md              ← this file
├── app.py                 ← main Gradio application
├── requirements.txt
├── .gitignore
│
├── utils/
│   ├── satellite.py
│   ├── analysis.py
│   ├── visualization.py
│   └── geotiff.py
│
└── assets/
    └── screenshots/
````

**One important point:** don't upload the ~1.4 GB model file directly into GitHub. Your code can download/load the model from its Hugging Face model repository at runtime.

If you want, I can also create the **actual `README.md` file for you as a downloadable file**, ready to put directly into your GitHub repository.