pansharpening_evaluation

KO | EN

gitlite — search

#javascript #python #hacktoberfest #ai #golang #machine-learning #deep-learning #docker #nodejs #macos #vue #mcp #openai #open-source

pansharpening_evaluation

(★ 10)

A simple framework to evaluate pansharpening metrics within the HQNR protocol, parallelized using dask for large data cubes.

pansharpening_evaluation Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Pansharpening Quality Metrics

Efficient (it should be at least) reference-free quality assessment for hyperspectral pansharpening, optimized for large images using Dask.

**This code has been mainly tested on PRISMA images, based on my own projects. If you encounter any kind of problem, just open an Issue and we'll work it out! Feel free to contribute as well!**

![alt text](https://raw.githubusercontent.com/notprime/pansharpening_evaluation/main/repoinanutshell.png)
(This image was generated by nano banana and well... I kinda like it a lot lol 😂)

## Overview

This package implements three standard quality metrics for evaluating pansharpening results without requiring reference images:

- **D_λ (D_lambda)**: Spectral distortion index (lower is better)
- **D_s**: Spatial distortion index (lower is better)
- **HQNR**: Hybrid Quality with No Reference = (1 - D_λ) × (1 - D_s) (higher is better)

## Installation

```bash
git clone https://github.com/notprime/pansharpening_evaluation.git
cd pansharpening_evaluation
pip install -r requirements.txt
pip install -e .
```

## Quick Start

### Command Line (Simplest)

```bash
# Basic usage
python main.py sharp.tif pan.tif hs.tif

# With custom parameters
python main.py sharp.tif pan.tif hs.tif --ratio 6 --sensor PRISMA

# Save results to JSON
python main.py sharp.tif pan.tif hs.tif --output results.json
```

### Python API (Recommended)

```python
from pansharpening_metrics import compute_metrics, preprocess_for_metrics, MetricsConfig
import rasterio

# Load images (converts to H × W × C format automatically)
sharp = rasterio.open('sharp.tif').read().transpose(1, 2, 0)
pan = rasterio.open('pan.tif').read().transpose(1, 2, 0)
hs = rasterio.open('hs.tif').read().transpose(1, 2, 0)

# Preprocess (adjust ratio to match your data)
sharp, pan, hs = preprocess_for_metrics(sharp, pan, hs, ratio=6)

# Compute metrics
metrics = compute_metrics(sharp, pan, hs, ratio=6)

# Display results
print(f"D_lambda: {metrics['D_lambda']:.4f}")
print(f"D_s:      {metrics['D_s']:.4f}")
print(f"HQNR:     {metrics['HQNR']:.4f}")
```

## Image Format Requirements

All images must be in **H × W × C** format (Height × Width × Channels):

- **Hyperspectral (HS)**: `(H, W, C)` at low resolution (e.g., 30m for PRISMA)
- **Panchromatic (PAN)**: `(H×ratio, W×ratio, 1)` at high resolution (e.g., 5m)
- **Sharpened**: `(H×ratio, W×ratio, C)` at high resolution

**Example for PRISMA (30m → 5m, ratio=6):**
```python
hs.shape    # (512, 512, 180)    - 30m resolution
pan.shape   # (3072, 3072, 1)    - 5m resolution (512×6=3072)
sharp.shape # (3072, 3072, 180)  - 5m resolution, 180 bands
```

**Note:** The `load_data` function in `main.py` handles transpose operations automatically when loading from GeoTIFF files, as I expect `rasterio` to load the channels in the first dimension.

## Usage

### Command Line Interface

**All options:**
```bash
python main.py sharp.tif pan.tif hs.tif \
    --ratio 6 \
    --sensor PRISMA \
    --config config.yaml \
    --output results.json \
    --q_block_size 32 \
    --n_workers 0.9
```

**Arguments:**
- `sharp.tif`: Path to sharpened hyperspectral image (required)
- `pan.tif`: Path to panchromatic image (required)
- `hs.tif`: Path to low-resolution hyperspectral image (required)
- `--ratio`: Resolution ratio between PAN and HS (default: 6)
- `--sensor`: Sensor name for MTF filters (default: PRISMA)
- `--config`: Path to YAML configuration file
- `--output, -o`: Save results to JSON file
- `--q_block_size`: Q window size for quality indices
- `--n_workers`: Fraction of CPU cores to use (0-1, default: 0.9)
- `--dask_chunk_size`: Chunk size for parallelization (H W)

**Supported sensors:**
- PRISMA
- QuickBird
- Ikonos
- GeoEye1
- WorldView-2
- WorldView-3

To add a custom sensor, modify the `resize_hs` and `resize_pan` functions in `pansharpening_metrics/downsampling.py` with appropriate Modulation Transfer Function (MTF) parameters, and add your custom sensor in the `pansharpening_metrics/sensors.py` file.

### Python API

**Basic usage:**
```python
from pansharpening_metrics import compute_metrics

# With default configuration
metrics = compute_metrics(sharp, pan, hs, ratio=6)
```

**Custom configuration:**
```python
from pansharpening_metrics import compute_metrics, MetricsConfig

config = MetricsConfig(
    q_block_size=32,        # Window size for Q/Q2n indices
    q_shift=32,             # Stride for sliding windows
    dask_chunk_size=(128, 128),  # Chunk size for parallelization
    n_workers=0.9,          # Fraction of CPU cores
    exponent=1              # Lp norm exponent for distortion
)
metrics = compute_metrics(sharp, pan, hs, ratio=6, config=config)
```

**Using presets:**
```python
# Conservative: low memory usage
config = MetricsConfig.conservative()

# Balanced: recommended for most cases (default)
config = MetricsConfig.balanced()

# Aggressive: maximum performance
config = MetricsConfig.aggressive()

metrics = compute_metrics(sharp, pan, hs, ratio=6, config=config)
```

### Configuration File (YAML)

Create a `config.yaml`:

```yaml
q_block_size: 32              # Window size for quality indices
q_shift: 32                   # Stride for sliding windows
dask_chunk_size: [128, 128]   # Chunk size for parallelization
n_workers: 0.9                # Fraction of CPU cores (0-1)
exponent: 1                   # Exponent for distortion metrics
```

Use it:
```bash
python main.py sharp.tif pan.tif hs.tif --config config.yaml
```

### Configuration Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `q_block_size` | 32 | Window size for Q and Q2n quality indices |
| `q_shift` | 32 | Stride for sliding windows (32 = non-overlapping) |
| `dask_chunk_size` | (64, 64) | Spatial chunk size for parallel processing |
| `n_workers` | 0.9 | Fraction of CPU cores to use (0-1) |
| `exponent` | 1 | Exponent for Lp norm in distortion metrics |

## Understanding the Metrics

### D_lambda (Spectral Distortion)

Measures preservation of spectral relationships between bands.

- **Range**: [0, 1]
- **Interpretation**: 0 = perfect spectral preservation, higher = more distortion
- **Method**: Compares Q2n index between band pairs at low resolution

### D_s (Spatial Distortion)

Measures preservation of spatial details.

- **Range**: [0, 1]  
- **Interpretation**: 0 = perfect spatial preservation, higher = more distortion
- **Method**: Compares Q index at high and low resolutions for each band

### HQNR (Hybrid Quality with No Reference)

Overall quality combining spectral and spatial preservation.

- **Formula**: HQNR = (1 - D_λ) × (1 - D_s)
- **Range**: [0, 1]
- **Interpretation**: 1 = perfect quality, 0 = complete failure
- **Balance**: Captures trade-off between spectral and spatial fidelity

## Examples

### Example 1: Command Line

```bash
python main.py data/sharp.tif data/pan.tif data/hs.tif --sensor PRISMA
```

**Output:**
```
======================================================================
PANSHARPENING QUALITY METRICS
======================================================================

Loading images...
  Sharp: (3072, 3072, 180)
  PAN:   (3072, 3072, 1)
  HS:    (512, 512, 180)

Computing metrics...
Configuration: q_block_size=32, chunk_size=(64, 64), n_workers=0.9

======================================================================
RESULTS
======================================================================
D_lambda (spectral): 0.1235
D_s (spatial):       0.2346
HQNR (overall):      0.6789
======================================================================
```

### Example 2: Python Script with JSON Export

```python
from pansharpening_metrics import compute_metrics, preprocess_for_metrics, MetricsConfig
import rasterio
import json

# Load images
sharp = rasterio.open('sharp.tif').read().transpose(1, 2, 0)
pan = rasterio.open('pan.tif').read().transpose(1, 2, 0)
hs = rasterio.open('hs.tif').read().transpose(1, 2, 0)

# Preprocess and compute
sharp, pan, hs = preprocess_for_metrics(sharp, pan, hs, ratio=6)
config = MetricsConfig.balanced()
metrics = compute_metrics(sharp, pan, hs, ratio=6, config=config)

# Save results
with open('results.json', 'w') as f:
    json.dump(metrics, f, indent=2)

print(f"HQNR: {metrics['HQNR']:.4f}")
```

## Performance Tips

### For Large Images (>5000×5000 pixels)

Use larger chunks and more workers:

```python
config = MetricsConfig(
    dask_chunk_size=(256, 256),
    n_workers=0.9
)
```

### Memory Issues

If encountering memory errors, use the conservative preset:

```python
config = MetricsConfig.conservative()
```

## Project Structure

```
pansharpening_evaluation/
├── pansharpening_metrics/    # Main package
│   ├── __init__.py           # Public API exports
│   ├── config.py             # MetricsConfig class and presets
│   ├── utils.py              # Preprocessing utilities
│   ├── quality_indices.py    # Q and Q2n implementations
│   ├── metrics.py            # D_lambda, D_s, HQNR
│   ├── sensors.py            # Sensor properties
│   └── downsampling.py       # Sensor-specific MTF filtering
├── main.py                   # Command-line interface
├── config.yaml               # Example configuration
├── requirements.txt          # Python dependencies
├── setup.py                  # Package installation
└── README.md                 # Documentation
```

## Troubleshooting

**Import errors:**
```bash
pip install -e .  # Install in development mode
```

**Memory errors on large images:**
```python
config = MetricsConfig.conservative()
```

**Slow computation:**
```python
config = MetricsConfig.aggressive()
```

## References

1. **Musto et al. (2024)**: "Advancing Prisma Pansharpening: A Deep Learning Approach with Synthetic Data Pretraining and Transfer Learning", WHISPERS
2. **Scarpa et al. (2021)**: "Full-resolution quality assessment for pansharpening", arXiv:2108.06144
3. **Garzelli & Nencini (2009)**: "Hypercomplex quality assessment of multi/hyper-spectral images", IEEE GRSL
4. **Alparone et al. (2008)**: "Multispectral and panchromatic data fusion assessment without reference", Photogrammetric Engineering & Remote Sensing
5. **Vivone et al. (2020)**: "A new benchmark based on recent advances in multispectral pansharpening", IEEE GRSM

## Citation

If you use this package in your research, please cite:

```bibtex
@software{pansharpening_metrics,
  author = {Riccardo Musto},
  title = {Pansharpening Quality Metrics for Hyperspectral Images},
  year = {2025},
  url = {https://github.com/notprime/pansharpening_evaluation},
  version = {1.0.0}
}
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please submit issues and pull requests on GitHub. **I used to work on the original code a while ago (and never actually thoroughly tested it), so if you notice anything wrong, let me know asap :D**

## Author

**Riccardo Musto**  
GitHub: [@notprime](https://github.com/notprime)

pansharpening_evaluation

pansharpening_evaluation Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

pansharpening_evaluation

pansharpening_evaluation Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README