Metadata-Version: 2.4
Name: parammadrz
Version: 2.5.3
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="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)
[![Coverage](https://codecov.io/gh/mmadrz/PaRaVis1/branch/main/graph/badge.svg)](https://codecov.io/gh/mmadrz/PaRaVis1)
[![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.

---
in 
## Features

- **200+ 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** — Downsampling for large files, LZW-compressed GeoTIFF output, multi-band support.
- **Desktop GUI** — Three-panel layout, light/dark themes, splash screen, and full-screen mode for a better experience.
- **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


| Core | Optional |
|:----:|:--------:|
| <a href="https://numpy.org"><img src="https://img.shields.io/badge/numpy-%3E%3D1.21-013243?style=flat-square&logo=numpy&logoColor=white" alt="numpy"></a> <a href="https://rasterio.readthedocs.io"><img src="https://img.shields.io/badge/rasterio-%3E%3D1.3-2C8EBB?style=flat-square" alt="rasterio"></a> <a href="https://spyndex.readthedocs.io"><img src="https://img.shields.io/badge/spyndex-%3E%3D0.4-FF6F00?style=flat-square" alt="spyndex"></a> <a href="https://matplotlib.org"><img src="https://img.shields.io/badge/matplotlib-%3E%3D3.5-11557C?style=flat-square" alt="matplotlib"></a> <a href="https://seaborn.pydata.org"><img src="https://img.shields.io/badge/seaborn-%3E%3D0.12-7DB0D6?style=flat-square" alt="seaborn"></a> <a href="https://psutil.readthedocs.io"><img src="https://img.shields.io/badge/psutil-%3E%3D5.0-003D7A?style=flat-square" alt="psutil"></a> | <a href="https://doc.qt.io/qtforpython-6"><img src="https://img.shields.io/badge/PySide6-%3E%3D6.5-41CD52?style=flat-square&logo=qt&logoColor=white" alt="PySide6"></a> <a href="https://cupy.dev"><img src="https://img.shields.io/badge/cupy-%3E%3D12.0-E90000?style=flat-square" alt="cupy"></a> |

> **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}
}

