paravis 2.0.0__py3-none-any.whl

paravis/__init__.py

@@ -0,0 +1,25 @@
+"""
+PaRaVis — Parallel Rao's Q Visualization and Analysis
+======================================================
+
+A library for spectral index computation, Rao's Q diversity analysis,
+and raster data visualization.
+
+Main components:
+    paravis.api         — Public API for headless/script usage
+    paravis.core        — Core computation (no Qt dependency)
+    paravis.gui         — PySide6 desktop application
+    paravis.workers     — Background processing threads
+    paravis.utils       — Shared utilities (settings, system profiler)
+"""
+
+from .__version__ import __version__, __version_info__  # noqa: F401
+
+
+def __getattr__(name):
+    """Lazy import of public API to avoid circular imports at package level."""
+    if name in ("compute_indices", "compute_rao_q", "plot_raster", "plot_comparison"):
+        import paravis.api as _api
+        return getattr(_api, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+

paravis/__version__.py

@@ -0,0 +1,4 @@
+"""Version information for PaRaVis."""
+
+__version__ = "2.0.0"
+__version_info__ = (2, 0, 0)

paravis/api/__init__.py

@@ -0,0 +1,18 @@
+"""
+paravis.api — Public API for headless/script usage.
+
+Convenience wrappers around paravis.core that provide sensible defaults
+and return NumPy arrays or xarray-compatible results.
+"""
+
+from .indices import compute_indices, list_available_indices
+from .raoq import compute_rao_q
+from .visualization import plot_raster, plot_comparison
+
+__all__ = [
+    "compute_indices",
+    "list_available_indices",
+    "compute_rao_q",
+    "plot_raster",
+    "plot_comparison",
+]

paravis/api/indices.py

@@ -0,0 +1,116 @@
+"""
+Public API for spectral index computation.
+
+Convenience wrappers around paravis.core.indices with sensible defaults.
+"""
+from typing import Dict, List, Optional, Union
+
+import numpy as np
+
+from paravis.core.raster import read_raster
+from paravis.core.indices import (
+    compute_index as _compute_index,
+    compute_indices as _compute_indices,
+    get_available_indices,
+    is_index_computable,
+    get_default_band_mapping,
+)
+
+
+def list_available_indices() -> List[str]:
+    """List all available spectral index names.
+
+    Returns
+    -------
+    List[str]
+    """
+    return [idx.name for idx in get_available_indices()]
+
+
+def compute_indices(
+    raster_path: str,
+    indices: Optional[List[str]] = None,
+    band_mapping: Optional[Dict[int, str]] = None,
+    constants: Optional[Dict[str, float]] = None,
+    max_pixels: int = 1_000_000,
+) -> Dict[str, np.ndarray]:
+    """Compute spectral indices from a raster file.
+
+    Parameters
+    ----------
+    raster_path : str
+        Path to a multi-band GeoTIFF.
+    indices : List[str], optional
+        Names of indices to compute. If None, computes all computable ones.
+    band_mapping : Dict[int, str], optional
+        Mapping from band number to spectral code.
+        Defaults to Landsat 8/9 mapping.
+    constants : Dict[str, float], optional
+        Override constants for index computation.
+    max_pixels : int
+        Maximum pixels to read (auto-downsamples beyond this).
+
+    Returns
+    -------
+    Dict[str, np.ndarray]
+        Mapping from index name to 2D result array.
+    """
+    if band_mapping is None:
+        band_mapping = get_default_band_mapping()
+
+    # Read raster
+    data_3d, transform, crs = read_raster(raster_path, max_pixels=max_pixels)
+
+    # Ensure 3D
+    if data_3d.ndim == 2:
+        data_3d = data_3d[np.newaxis, :, :]
+
+    # Determine which indices to compute
+    if indices is None:
+        all_indices = get_available_indices()
+        idx_constants = constants or {}
+        indices = [
+            idx.name for idx in all_indices
+            if is_index_computable(idx.name, idx_constants, band_mapping)
+        ]
+
+    # Compute
+    results = _compute_indices(data_3d, band_mapping, indices, constants)
+    return results
+
+
+def compute_index(
+    raster_path: str,
+    index_name: str,
+    band_mapping: Optional[Dict[int, str]] = None,
+    constants: Optional[Dict[str, float]] = None,
+    max_pixels: int = 1_000_000,
+) -> np.ndarray:
+    """Compute a single spectral index from a raster file.
+
+    Parameters
+    ----------
+    raster_path : str
+        Path to a multi-band GeoTIFF.
+    index_name : str
+        Name of the index (e.g. 'NDVI').
+    band_mapping : Dict[int, str], optional
+        Band mapping. Defaults to Landsat 8/9.
+    constants : Dict[str, float], optional
+        Override constants.
+    max_pixels : int
+        Maximum pixels to read.
+
+    Returns
+    -------
+    np.ndarray
+        2D array of the computed index.
+    """
+    if band_mapping is None:
+        band_mapping = get_default_band_mapping()
+
+    data_3d, _, _ = read_raster(raster_path, max_pixels=max_pixels)
+    if data_3d.ndim == 2:
+        data_3d = data_3d[np.newaxis, :, :]
+
+    return _compute_index(data_3d, band_mapping, index_name, constants)

paravis/api/raoq.py

@@ -0,0 +1,105 @@
+"""
+Public API for Rao's Q diversity computation.
+
+Implements the ecological Rao's quadratic entropy formula:
+
+    Q = Σᵢ Σⱼ dᵢⱼ × pᵢ × pⱼ
+
+where each unique spectral profile in a window is treated as a
+"species" (i), dᵢⱼ is the spectral distance between species i and j,
+and pᵢ, pⱼ are their relative abundances (proportion of pixels
+belonging to each unique profile).
+"""
+from typing import Optional
+
+import numpy as np
+
+from paravis.core.raster import read_raster
+from paravis.core.raoq import (
+    compute_rao_q as _compute_rao_q_cpu,
+    RaoQConfig,
+    RaoQResult,
+)
+from paravis.core.raoq.gpu import compute_rao_q_gpu, is_gpu_available
+
+
+def compute_rao_q(
+    raster_path: str,
+    window_size: int = 15,
+    step_size: int = 1,
+    na_tolerance: float = 0.3,
+    backend: str = "auto",
+    n_workers: int = 4,
+    max_pixels: int = 500_000,
+    simplify: int = 2,
+    distance_metric: str = "euclidean",
+    p_minkowski: int = 2,
+) -> np.ndarray:
+    """Compute Rao's Q diversity from a raster file.
+
+    For each moving window, unique spectral profiles are identified
+    as "species", and Rao's Q is computed as:
+
+        Q = Σᵢ Σⱼ dᵢⱼ × pᵢ × pⱼ
+
+    where pᵢ is the relative abundance (frequency) of each unique
+    spectral profile in the window.
+
+    Parameters
+    ----------
+    raster_path : str
+        Path to a multi-band GeoTIFF.
+    window_size : int
+        Size of the moving window (odd number).
+    step_size : int
+        Step between windows (default 1).
+    na_tolerance : float
+        Maximum allowed fraction of NA pixels (0.0 to 1.0).
+    backend : str
+        'auto', 'cpu', 'gpu', or 'parallel'. If 'auto', tries GPU first.
+    n_workers : int
+        Number of CPU workers for 'parallel' backend.
+    max_pixels : int
+        Maximum pixels to read (auto-downsamples beyond this).
+    simplify : int
+        Number of decimal places to round the output to (0 = integers, default 2).
+    distance_metric : str
+        Distance metric: 'euclidean', 'manhattan', 'chebyshev', or 'minkowski'.
+    p_minkowski : int
+        Exponent for Minkowski distance (ignored for other metrics).
+
+    Returns
+    -------
+    np.ndarray
+        2D array of Rao's Q diversity values.
+    """
+    config = RaoQConfig(
+        window_size=window_size,
+        step_size=step_size,
+        na_tolerance=na_tolerance,
+        n_workers=n_workers,
+        simplify=simplify,
+        distance_metric=distance_metric,
+        p_minkowski=p_minkowski,
+    )
+
+    # Read raster
+    data_3d, _, _ = read_raster(raster_path, max_pixels=max_pixels)
+    if data_3d.ndim == 2:
+        data_3d = data_3d[np.newaxis, :, :]
+
+    # Choose backend
+    if backend == "auto":
+        if is_gpu_available():
+            result = compute_rao_q_gpu(data_3d, config)
+        else:
+            result = _compute_rao_q_cpu(data_3d, config)
+    elif backend == "gpu":
+        result = compute_rao_q_gpu(data_3d, config)
+    elif backend == "parallel":
+        from paravis.core.raoq import compute_rao_q_parallel
+        result = compute_rao_q_parallel(data_3d, config)
+    else:
+        result = _compute_rao_q_cpu(data_3d, config)
+
+    return result

paravis/api/visualization.py

@@ -0,0 +1,95 @@
+"""
+Public API for raster visualization.
+
+Provides quick-plot functions for use in scripts and notebooks.
+"""
+from typing import Optional, List, Tuple
+import numpy as np
+
+from paravis.core.raster import read_raster, normalize_data
+
+
+def plot_raster(
+    raster_path: str,
+    title: Optional[str] = None,
+    cmap: str = "viridis",
+    figsize: Tuple[int, int] = (10, 8),
+    max_pixels: int = 1_000_000,
+    show_colorbar: bool = True,
+):
+    """Quick-plot a raster file.
+
+    Parameters
+    ----------
+    raster_path : str
+        Path to a raster file.
+    title : str, optional
+        Plot title.
+    cmap : str
+        Matplotlib colormap name.
+    figsize : Tuple[int, int]
+        Figure size in inches.
+    max_pixels : int
+        Maximum pixels to read.
+    show_colorbar : bool
+        Whether to show a colorbar.
+    """
+    import matplotlib.pyplot as plt
+
+    data, transform, _ = read_raster(raster_path, max_pixels=max_pixels)
+    if data.ndim == 3:
+        data = data[0]
+
+    fig, ax = plt.subplots(figsize=figsize)
+    im = ax.imshow(data, cmap=cmap, interpolation="nearest")
+    if show_colorbar:
+        plt.colorbar(im, ax=ax, shrink=0.75)
+    ax.set_title(title or raster_path.split("/")[-1])
+    ax.set_xlabel("Column")
+    ax.set_ylabel("Row")
+    plt.tight_layout()
+    return fig, ax
+
+
+def plot_comparison(
+    file_paths: List[str],
+    labels: Optional[List[str]] = None,
+    cmap: str = "viridis",
+    figsize: Optional[Tuple[int, int]] = None,
+    max_pixels: int = 500_000,
+):
+    """Plot multiple rasters side by side for comparison.
+
+    Parameters
+    ----------
+    file_paths : List[str]
+        Paths to raster files.
+    labels : List[str], optional
+        Labels for each subplot.
+    cmap : str
+        Colormap name.
+    figsize : Tuple[int, int], optional
+        Figure size.
+    max_pixels : int
+        Maximum pixels to read.
+    """
+    import matplotlib.pyplot as plt
+
+    n = len(file_paths)
+    if figsize is None:
+        figsize = (5 * n, 5)
+
+    fig, axes = plt.subplots(1, n, figsize=figsize, squeeze=False)
+    if labels is None:
+        labels = [p.split("/")[-1] for p in file_paths]
+
+    for i, (path, label) in enumerate(zip(file_paths, labels)):
+        data, _, _ = read_raster(path, max_pixels=max_pixels)
+        if data.ndim == 3:
+            data = data[0]
+        im = axes[0, i].imshow(data, cmap=cmap, interpolation="nearest")
+        axes[0, i].set_title(label)
+        plt.colorbar(im, ax=axes[0, i], shrink=0.75)
+
+    plt.tight_layout()
+    return fig, axes

paravis/core/__init__.py

@@ -0,0 +1,8 @@
+"""
+paravis.core — Pure computation modules (zero Qt dependency).
+
+Sub-packages:
+    core.indices    — Spectral index computation engine
+    core.raoq       — Rao's Q diversity computation (CPU + GPU)
+    core.raster     — Raster I/O utilities
+"""

paravis/core/indices/__init__.py

@@ -0,0 +1,28 @@
+"""Spectral index computation engine."""
+
+from .engine import (
+    compute_index,
+    compute_indices,
+    compute_indices_dask,
+    is_index_computable,
+    get_available_indices,
+    get_default_band_mapping,
+)
+from .registry import register_index, list_custom_indices
+from .constants import get_default_constants, merge_constants
+from .models import SpectralIndex, BandMapping
+
+__all__ = [
+    "compute_index",
+    "compute_indices",
+    "compute_indices_dask",
+    "is_index_computable",
+    "get_available_indices",
+    "get_default_band_mapping",
+    "register_index",
+    "list_custom_indices",
+    "get_default_constants",
+    "merge_constants",
+    "SpectralIndex",
+    "BandMapping",
+]

paravis/core/indices/constants.py

@@ -0,0 +1,52 @@
+"""
+Constants management for spectral index computation.
+
+Handles default values from spyndex and user overrides.
+"""
+from typing import Dict, Optional
+
+import spyndex
+
+
+def get_default_constants() -> Dict[str, float]:
+    """Return all default constant values from spyndex.
+
+    Returns
+    -------
+    Dict[str, float]
+        Mapping from constant name to default value.
+    """
+    constants: Dict[str, float] = {}
+    for name, const in spyndex.constants.items():
+        try:
+            constants[name] = float(getattr(const, "default", 0.0))
+        except (ValueError, TypeError):
+            constants[name] = 0.0
+    return constants
+
+
+def merge_constants(
+    defaults: Dict[str, float],
+    overrides: Dict[str, Optional[float]],
+) -> Dict[str, float]:
+    """Merge user overrides into default constants.
+
+    Parameters
+    ----------
+    defaults : Dict[str, float]
+        Default constant values.
+    overrides : Dict[str, Optional[float]]
+        User overrides. A value of None removes the override (fallback to default).
+
+    Returns
+    -------
+    Dict[str, float]
+        Merged constants dictionary.
+    """
+    merged = dict(defaults)
+    for key, value in overrides.items():
+        if value is not None:
+            merged[key] = value
+        elif key in merged:
+            del merged[key]
+    return merged