Metadata-Version: 2.4
Name: parammadrz
Version: 2.5.1
Summary: Parallel Rao's Q Visualization and Analysis — Spectral indices, Rao's Q diversity, raster visualization
Author: Mohammadreza Fathi
License: MIT
Project-URL: Homepage, https://github.com/mmadrz/paravis
Project-URL: Documentation, https://github.com/mmadrz/paravis/docs/user_guide
Project-URL: Source, https://github.com/mmadrz/paravis
Project-URL: BugTracker, https://github.com/mmadrz/paravis/issues
Keywords: remote sensing,spectral indices,spectral variation hypothesis,spectral diversity,Rao's Q,raster visualization,CPU/GPU computing,GUI
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: rasterio>=1.3
Requires-Dist: spyndex>=0.4
Requires-Dist: matplotlib>=3.5
Requires-Dist: seaborn>=0.12
Requires-Dist: psutil>=5.0
Provides-Extra: gui
Requires-Dist: PySide6>=6.5; extra == "gui"
Provides-Extra: gpu
Requires-Dist: cupy>=12.0; extra == "gpu"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-qt>=4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# PaRaVis

> **Pa**rallel **Ra**o's **Q** **Vis**ualization and Analysis

<p align="center">
  <img src="https://raw.githubusercontent.com/mmadrz/paravis/main/paravis/gui/theme/logo.png" alt="PaRaVis Logo" width="1200">
</p>

<div align="center">

[![PyPI version](https://img.shields.io/pypi/v/paravis?style=flat-square&logo=pypi)](https://pypi.org/project/paravis/)
[![Python versions](https://img.shields.io/pypi/pyversions/paravis?style=flat-square&logo=python)](https://pypi.org/project/paravis/)
[![License](https://img.shields.io/pypi/l/paravis?style=flat-square)](https://github.com/mmadrz/paravis/blob/main/LICENSE)
[![Tests](https://img.shields.io/badge/tests-369%20passed-success?style=flat-square)](https://github.com/mmadrz/paravis/actions)
[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20windows%20%7C%20macOS-lightgrey?style=flat-square)](https://github.com/mmadrz/paravis)

</div>

A cross-platform Python library and desktop GUI for **spectral index computation**, **Rao's Q diversity analysis**, and **raster data visualization**. PaRaVis combines a professional PySide6 interface with a lightweight headless API — equally at home in interactive exploration and automated HPC batch pipelines.

---

## Features

- **190+ Spectral Indices** — NDVI, EVI, SAVI, NDWI, NBR, BAI, and more via Spyndex. Register custom indices with the `@register_index` decorator.
- **Rao's Q Diversity** — Moving-window quadratic entropy with three backends: CPU (NumPy), multi-core parallel (`ProcessPoolExecutor`), and GPU-accelerated (CuPy + custom CUDA `RawKernel`).
- **6 Distance Metrics** — Euclidean, Manhattan, Chebyshev, Minkowski, Canberra, and Bray-Curtis — all supported on every backend.
- **Raster I/O** — Automatic downsampling for large files, LZW-compressed GeoTIFF output, multi-band support.
- **Desktop GUI** — Three-panel layout, drag-and-drop, light/dark themes, splash screen, full-screen mode, and persistent settings.
- **Headless API** — Zero-Qt core modules usable in scripts, notebooks, and HPC clusters.

---

## Quick Start

```bash
pip install paravis[gui]         # install with GUI
paravis                          # launch the desktop app
```

```python
from paravis.api import compute_indices, compute_rao_q

# Compute vegetation indices
results = compute_indices("scene.tif", indices=["NDVI", "EVI"])
print(results["NDVI"].mean())

# Rao's Q diversity (auto-selects GPU if available)
diversity = compute_rao_q("scene.tif", window_size=15, backend="auto")
```

---

## Installation

```bash
pip install paravis               # headless (scripts, notebooks, HPC)
pip install paravis[gui]          # + desktop GUI
pip install paravis[gpu]          # + GPU acceleration (needs NVIDIA + CUDA)
pip install paravis[gui,gpu,dev]  # everything
```

### Dependencies

| Package     | Minimum | Needed for                |
|-------------|---------|---------------------------|
| numpy       | ≥1.21   | Core arrays               |
| rasterio    | ≥1.3    | GeoTIFF I/O               |
| spyndex     | ≥0.4    | Spectral index formulas   |
| matplotlib  | ≥3.5    | Plotting                  |
| seaborn     | ≥0.12   | Statistical visualisations|
| psutil      | ≥5.0    | CPU/RAM detection         |
| PySide6     | ≥6.5    | Desktop GUI (`[gui]`)     |
| cupy        | ≥12.0   | GPU Rao's Q (`[gpu]`)     |

> **Note:** `rasterio` requires the GDAL system library. On Linux: `apt install libgdal-dev`. On Windows/macOS the pip wheel includes it.

---

## How Rao's Q Works

Rao's Quadratic Entropy measures spectral diversity using a **species-abundance approach**: identical spectral profiles in a window are treated as the same "species", their frequencies counted, and pairwise spectral distances are weighted by relative abundance:

$$Q = \sum_{i=1}^{S} \sum_{j=1}^{S} d_{ij} \cdot p_i \cdot p_j$$

Where $S$ = unique profiles (species), $d_{ij}$ = spectral distance between species $i$ and $j$, $p_i$ = relative abundance of species $i$.

The `simplify` parameter controls **input truncation** precision before species identification — higher precision means more distinct species detected, yielding a more detailed diversity map but at greater computational cost.

Six distance metrics are available: Euclidean, Manhattan, Chebyshev, Minkowski (tunable $p$), Canberra, and Bray-Curtis. All work on every backend.

> **→ Full theory, formulas, and parameter details in [docs/user_guide.md](docs/user_guide.md)**

---

## Backends

| Backend | Command | Best for |
|---------|---------|----------|
| **CPU** (NumPy) | `backend="cpu"` | Small rasters, any hardware |
| **Parallel CPU** | `backend="parallel"` | Multi-core workstations, HPC nodes |
| **GPU** (CUDA kernel) | `backend="gpu"` or `"auto"` | Large rasters, NVIDIA GPUs |

All three implement the **identical species-abundance formula**, producing bitwise-comparable results. The GPU uses three automatic paths: a fast shared-memory CUDA kernel, a per-thread fallback kernel, and a pure CuPy fallback if compilation fails.

> **→ Full backend comparison and GPU architecture in [docs/user_guide.md](docs/user_guide.md)**

---

## API Overview

```python
from paravis.api import (
    compute_indices,      # → dict of 2D arrays
    compute_index,        # → single 2D array
    compute_rao_q,        # → 2D Rao's Q map
    plot_raster,          # → (figure, axes)
    plot_comparison,      # → (figure, axes)
    list_available_indices, # → list of index names
)
```

```python
# Spectral indices with custom band mapping
compute_indices("sentinel2.tif", indices=["NDVI", "NDWI"],
                band_mapping={4: "R", 8: "N"})

# Rao's Q with full control
compute_rao_q("scene.tif", window_size=11, na_tolerance=0.3,
              backend="parallel", n_workers=8,
              simplify=2, distance_metric="braycurtis")

# Read / write rasters
from paravis.core.raster import read_raster, write_geotiff
data, transform, crs = read_raster("input.tif")
write_geotiff(result, "output.tif", transform=transform, crs=crs)
```

> **→ Full API reference with all parameters in [docs/user_guide.md](docs/user_guide.md)**

---

## Desktop GUI

```bash
paravis                    # launch
python -m paravis.gui.app  # or via module
```

Three-panel layout: **Left** — controls and index selection, **Centre** — Rao's Q processing, **Right** — visualisation with five plot modes (individual, stats, diff+heatmap, split comparison, time series with GIF export). Light/dark themes, keyboard shortcuts, persistent settings.

> **→ Full GUI walkthrough in [docs/user_guide.md](docs/user_guide.md)**

---

## System Requirements

- **Python** ≥ 3.9
- **RAM**: 4 GB minimum, 8 GB recommended for GUI
- **GPU** (optional): NVIDIA with Compute Capability 6.0+, driver ≥ 450.0, CuPy ≥ 12.0

---

## Citation

```bibtex
@software{paravis2026,
  author = {{PaRaVis Contributors}},
  title = {PaRaVis: Parallel Rao's Q Visualization and Analysis},
  year = {2026},
  version = {2.0.1},
  url = {https://github.com/mmadrz/paravis}
}

