hyperbench 0.1.0__py3-none-any.whl

hyperbench/__about__.py

@@ -0,0 +1,7 @@
+# Author: Ritik Shah
+
+"""Package metadata for HyperBench."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

hyperbench/__init__.py

@@ -0,0 +1,157 @@
+# Author: Ritik Shah
+
+"""HyperBench: synthetic benchmarking for hyperspectral super-resolution."""
+
+from .__about__ import __version__
+
+from .adapters import (
+    BaseAdapter,
+    CallableAdapter,
+    PipelineAdapter,
+    ReconstructionInputs,
+    TensorFlowModelAdapter,
+    TorchModelAdapter,
+)
+from .benchmark import (
+    BenchmarkCase,
+    BenchmarkConfig,
+    BenchmarkResults,
+    DegradationSpec,
+    SyntheticCase,
+    generate_cases,
+    run_benchmark,
+)
+from .config import benchmark_config_from_dict, load_benchmark_config
+from .degradations import (
+    AVAILABLE_PSFS,
+    SUPPORTED_SRF_BAND_COUNTS,
+    make_psf,
+    normalize_image,
+    spatial_degradation,
+    spectral_degradation,
+)
+from .exceptions import (
+    AdapterError,
+    AdapterOutputError,
+    ConfigurationError,
+    FrameworkAvailabilityError,
+    HyperBenchError,
+    IOValidationError,
+    MetricsError,
+    PipelineError,
+    SceneKeyError,
+    ShapeMismatchError,
+    UnsupportedPSFError,
+    UnsupportedSRFError,
+)
+from .io import load_hsi
+from .metrics import (
+    AVAILABLE_METRICS,
+    DEFAULT_METRICS,
+    compute_ergas,
+    compute_psnr,
+    compute_rmse,
+    compute_sam,
+    compute_ssim,
+    compute_uiqi,
+    evaluate_metrics,
+)
+from .types import Array, Metadata, PathLike
+from .utils import (
+    convert_prediction_to_numpy_hwc,
+    get_preferred_tensorflow_device,
+    get_preferred_torch_device,
+    get_tensorflow_device_info,
+    get_torch_device_info,
+    is_tensorflow_available,
+    is_torch_available,
+    numpy_hwc_to_tf_image,
+    numpy_hwc_to_torch_image,
+    numpy_prediction_to_hwc,
+    numpy_to_tf_matrix,
+    numpy_to_torch_matrix,
+    plot_spectra,
+    print_data_stats,
+    print_framework_device_summary,
+    tf_image_to_numpy_hwc,
+    tf_matrix_to_numpy,
+    torch_image_to_numpy_hwc,
+    torch_matrix_to_numpy,
+    visualize_band,
+    visualize_hsi,
+    visualize_multispectral_with_srf,
+    visualize_psfs,
+)
+
+__all__ = [
+    "__version__",
+    "Array",
+    "PathLike",
+    "Metadata",
+    "HyperBenchError",
+    "ConfigurationError",
+    "IOValidationError",
+    "SceneKeyError",
+    "ShapeMismatchError",
+    "UnsupportedPSFError",
+    "UnsupportedSRFError",
+    "AdapterError",
+    "AdapterOutputError",
+    "PipelineError",
+    "MetricsError",
+    "FrameworkAvailabilityError",
+    "BaseAdapter",
+    "CallableAdapter",
+    "PipelineAdapter",
+    "TorchModelAdapter",
+    "TensorFlowModelAdapter",
+    "ReconstructionInputs",
+    "DegradationSpec",
+    "BenchmarkConfig",
+    "BenchmarkCase",
+    "SyntheticCase",
+    "BenchmarkResults",
+    "generate_cases",
+    "run_benchmark",
+    "benchmark_config_from_dict",
+    "load_benchmark_config",
+    "load_hsi",
+    "AVAILABLE_PSFS",
+    "SUPPORTED_SRF_BAND_COUNTS",
+    "make_psf",
+    "normalize_image",
+    "spatial_degradation",
+    "spectral_degradation",
+    "AVAILABLE_METRICS",
+    "DEFAULT_METRICS",
+    "compute_rmse",
+    "compute_psnr",
+    "compute_ssim",
+    "compute_uiqi",
+    "compute_ergas",
+    "compute_sam",
+    "evaluate_metrics",
+    "print_data_stats",
+    "visualize_hsi",
+    "visualize_band",
+    "visualize_multispectral_with_srf",
+    "plot_spectra",
+    "visualize_psfs",
+    "is_torch_available",
+    "is_tensorflow_available",
+    "get_torch_device_info",
+    "get_tensorflow_device_info",
+    "get_preferred_torch_device",
+    "get_preferred_tensorflow_device",
+    "print_framework_device_summary",
+    "numpy_hwc_to_tf_image",
+    "tf_image_to_numpy_hwc",
+    "numpy_to_tf_matrix",
+    "tf_matrix_to_numpy",
+    "numpy_hwc_to_torch_image",
+    "torch_image_to_numpy_hwc",
+    "numpy_to_torch_matrix",
+    "torch_matrix_to_numpy",
+    "numpy_prediction_to_hwc",
+    "convert_prediction_to_numpy_hwc",
+]

hyperbench/adapters/__init__.py

@@ -0,0 +1,19 @@
+# Author: Ritik Shah
+
+"""Model adapter layer for HyperBench."""
+
+from .base import BaseAdapter, ReconstructionInputs, ShapePolicy
+from .callable import CallableAdapter
+from .pipeline import PipelineAdapter
+from .tensorflow import TensorFlowModelAdapter
+from .torch import TorchModelAdapter
+
+__all__ = [
+    "ShapePolicy",
+    "ReconstructionInputs",
+    "BaseAdapter",
+    "CallableAdapter",
+    "PipelineAdapter",
+    "TorchModelAdapter",
+    "TensorFlowModelAdapter",
+]

hyperbench/adapters/base.py

@@ -0,0 +1,178 @@
+# Author: Ritik Shah
+
+"""Base adapter abstractions for HyperBench."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Literal, Optional
+
+import numpy as np
+
+
+Array = np.ndarray
+ShapePolicy = Literal["strict", "crop", "pad"]
+
+
+@dataclass
+class ReconstructionInputs:
+    """Canonical inference-time input bundle for HyperBench."""
+
+    lr_hsi: Array
+    hr_msi: Array
+    srf: Optional[Array] = None
+    psf: Optional[Array] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class BaseAdapter:
+    """Base class for all HyperBench adapters."""
+
+    def __init__(
+        self,
+        name: str,
+        shape_policy: ShapePolicy = "strict",
+        hr_multiple: int = 1,
+        lr_multiple: int = 1,
+    ) -> None:
+        if shape_policy not in {"strict", "crop", "pad"}:
+            raise ValueError(
+                "shape_policy must be one of {'strict', 'crop', 'pad'}, got {!r}".format(
+                    shape_policy
+                )
+            )
+
+        self.name = name
+        self.shape_policy = shape_policy
+        self.hr_multiple = int(hr_multiple)
+        self.lr_multiple = int(lr_multiple)
+
+        self.config = {
+            "adapter_name": self.name,
+            "adapter_type": type(self).__name__,
+            "shape_policy": self.shape_policy,
+            "hr_multiple": self.hr_multiple,
+            "lr_multiple": self.lr_multiple,
+        }
+
+    def predict(self, inputs: ReconstructionInputs) -> Any:
+        """Run model inference for one HyperBench case.
+
+        Valid returns:
+        - prediction
+        - (prediction, stats_dict)
+        """
+        raise NotImplementedError
+
+    def _validate_multiple(self, value: int, name: str) -> None:
+        if value < 1:
+            raise ValueError("{} must be >= 1, got {}".format(name, value))
+
+    def prepare_inputs(self, inputs: ReconstructionInputs) -> ReconstructionInputs:
+        """Apply shape policy before inference."""
+        self._validate_multiple(self.hr_multiple, "hr_multiple")
+        self._validate_multiple(self.lr_multiple, "lr_multiple")
+
+        if self.shape_policy == "strict":
+            self._ensure_valid_shapes(inputs)
+            return inputs
+        elif self.shape_policy == "crop":
+            return self._crop_inputs_to_valid(inputs)
+        elif self.shape_policy == "pad":
+            return self._pad_inputs_to_valid(inputs)
+        else:
+            raise ValueError("Unsupported shape_policy {!r}".format(self.shape_policy))
+
+    def _ensure_valid_shapes(self, inputs: ReconstructionInputs) -> None:
+        hr_h, hr_w = inputs.hr_msi.shape[:2]
+        lr_h, lr_w = inputs.lr_hsi.shape[:2]
+
+        if hr_h % self.hr_multiple != 0 or hr_w % self.hr_multiple != 0:
+            raise ValueError(
+                "HR input shape {} is not divisible by hr_multiple={}".format(
+                    inputs.hr_msi.shape[:2], self.hr_multiple
+                )
+            )
+
+        if lr_h % self.lr_multiple != 0 or lr_w % self.lr_multiple != 0:
+            raise ValueError(
+                "LR input shape {} is not divisible by lr_multiple={}".format(
+                    inputs.lr_hsi.shape[:2], self.lr_multiple
+                )
+            )
+
+    def _crop_inputs_to_valid(self, inputs: ReconstructionInputs) -> ReconstructionInputs:
+        hr_h, hr_w = inputs.hr_msi.shape[:2]
+        lr_h, lr_w = inputs.lr_hsi.shape[:2]
+
+        new_hr_h = hr_h - (hr_h % self.hr_multiple)
+        new_hr_w = hr_w - (hr_w % self.hr_multiple)
+        new_lr_h = lr_h - (lr_h % self.lr_multiple)
+        new_lr_w = lr_w - (lr_w % self.lr_multiple)
+
+        if new_hr_h <= 0 or new_hr_w <= 0:
+            raise ValueError("Cropping would result in invalid HR shape")
+        if new_lr_h <= 0 or new_lr_w <= 0:
+            raise ValueError("Cropping would result in invalid LR shape")
+
+        return ReconstructionInputs(
+            lr_hsi=inputs.lr_hsi[:new_lr_h, :new_lr_w, :],
+            hr_msi=inputs.hr_msi[:new_hr_h, :new_hr_w, :],
+            srf=inputs.srf,
+            psf=inputs.psf,
+            metadata=dict(inputs.metadata),
+        )
+
+    def _compute_padding(self, size: int, multiple: int) -> int:
+        remainder = size % multiple
+        return 0 if remainder == 0 else multiple - remainder
+
+    def _pad_inputs_to_valid(self, inputs: ReconstructionInputs) -> ReconstructionInputs:
+        lr_h, lr_w, lr_c = inputs.lr_hsi.shape
+        hr_h, hr_w, hr_c = inputs.hr_msi.shape
+
+        pad_lr_h = self._compute_padding(lr_h, self.lr_multiple)
+        pad_lr_w = self._compute_padding(lr_w, self.lr_multiple)
+        pad_hr_h = self._compute_padding(hr_h, self.hr_multiple)
+        pad_hr_w = self._compute_padding(hr_w, self.hr_multiple)
+
+        lr_padded = np.pad(
+            inputs.lr_hsi,
+            ((0, pad_lr_h), (0, pad_lr_w), (0, 0)),
+            mode="reflect",
+        ).astype(np.float32)
+
+        hr_padded = np.pad(
+            inputs.hr_msi,
+            ((0, pad_hr_h), (0, pad_hr_w), (0, 0)),
+            mode="reflect",
+        ).astype(np.float32)
+
+        metadata = dict(inputs.metadata)
+        metadata["_original_lr_shape"] = (lr_h, lr_w, lr_c)
+        metadata["_original_hr_shape"] = (hr_h, hr_w, hr_c)
+
+        return ReconstructionInputs(
+            lr_hsi=lr_padded,
+            hr_msi=hr_padded,
+            srf=inputs.srf,
+            psf=inputs.psf,
+            metadata=metadata,
+        )
+
+    def _restore_output_shape(self, output: Array, inputs: ReconstructionInputs) -> Array:
+        """Restore output to original HR shape when using pad policy."""
+        if self.shape_policy != "pad":
+            return output
+
+        original_hr_shape = inputs.metadata.get("_original_hr_shape")
+        if original_hr_shape is None:
+            return output
+
+        h, w, c = original_hr_shape
+        return output[:h, :w, :c]
+
+    @property
+    def csv_metadata(self) -> Dict[str, Any]:
+        """Optional static metadata to merge into CSV rows."""
+        return {}

hyperbench/adapters/callable.py

@@ -0,0 +1,62 @@
+# Author: Ritik Shah
+
+"""Callable adapter for HyperBench."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Tuple
+
+import numpy as np
+
+from hyperbench.utils import numpy_prediction_to_hwc
+
+from .base import BaseAdapter, ReconstructionInputs, ShapePolicy
+
+
+Array = np.ndarray
+
+
+class CallableAdapter(BaseAdapter):
+    """Wrap a plain Python callable as a HyperBench adapter."""
+
+    def __init__(
+        self,
+        fn: Callable,
+        name: str = "callable_model",
+        shape_policy: ShapePolicy = "strict",
+        hr_multiple: int = 1,
+        lr_multiple: int = 1,
+    ) -> None:
+        super().__init__(
+            name=name,
+            shape_policy=shape_policy,
+            hr_multiple=hr_multiple,
+            lr_multiple=lr_multiple,
+        )
+        self.fn = fn
+
+    def predict(self, inputs: ReconstructionInputs) -> Any:
+        prepared = self.prepare_inputs(inputs)
+
+        result = self.fn(
+            prepared.lr_hsi,
+            prepared.hr_msi,
+            srf=prepared.srf,
+            psf=prepared.psf,
+            metadata=prepared.metadata,
+        )
+
+        if isinstance(result, tuple):
+            if len(result) != 2 or not isinstance(result[1], dict):
+                raise ValueError(
+                    "CallableAdapter functions may return either prediction or "
+                    "(prediction, stats_dict)."
+                )
+            prediction, stats = result
+            prediction = numpy_prediction_to_hwc(prediction, remove_batch_dim=True)
+            prediction = self._restore_output_shape(prediction, prepared)
+            return prediction.astype(np.float32), stats
+
+        prediction = numpy_prediction_to_hwc(result, remove_batch_dim=True)
+        prediction = self._restore_output_shape(prediction, prepared)
+        return prediction.astype(np.float32)

hyperbench/adapters/pipeline.py

@@ -0,0 +1,192 @@
+# Author: Ritik Shah
+
+"""Generic pipeline adapter for HyperBench.
+
+This adapter is the recommended path for real-world research models.
+
+Expected user-side contract:
+- an object with a `run_pipeline(...)` method, or
+- a callable function itself
+
+The pipeline should accept:
+    run_pipeline(HR_MSI, LR_HSI, srf, psf=None, metadata=None)
+
+Valid returns:
+- prediction
+- (prediction, stats_dict)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+from hyperbench.utils import (
+    convert_prediction_to_numpy_hwc,
+    get_preferred_tensorflow_device,
+    get_preferred_torch_device,
+    numpy_hwc_to_tf_image,
+    numpy_hwc_to_torch_image,
+    numpy_to_tf_matrix,
+    numpy_to_torch_matrix,
+    numpy_prediction_to_hwc,
+)
+
+from .base import BaseAdapter, ReconstructionInputs, ShapePolicy
+
+
+Array = np.ndarray
+
+
+class PipelineAdapter(BaseAdapter):
+    """Generic adapter for model wrappers exposing `run_pipeline(...)`."""
+
+    def __init__(
+        self,
+        pipeline: Any,
+        name: str = "pipeline_model",
+        input_backend: str = "numpy",
+        output_backend: Optional[str] = None,
+        add_batch_dim: bool = True,
+        device: str = "auto",
+        shape_policy: ShapePolicy = "strict",
+        hr_multiple: int = 1,
+        lr_multiple: int = 1,
+    ) -> None:
+        super().__init__(
+            name=name,
+            shape_policy=shape_policy,
+            hr_multiple=hr_multiple,
+            lr_multiple=lr_multiple,
+        )
+
+        backend = input_backend.lower()
+        if backend not in {"numpy", "tensorflow", "torch"}:
+            raise ValueError(
+                "input_backend must be one of {'numpy', 'tensorflow', 'torch'}, got {!r}".format(
+                    input_backend
+                )
+            )
+
+        out_backend = output_backend.lower() if output_backend is not None else backend
+        if out_backend not in {"numpy", "tensorflow", "torch"}:
+            raise ValueError(
+                "output_backend must be one of {'numpy', 'tensorflow', 'torch'}, got {!r}".format(
+                    output_backend
+                )
+            )
+
+        self.pipeline = pipeline
+        self.input_backend = backend
+        self.output_backend = out_backend
+        self.add_batch_dim = bool(add_batch_dim)
+        self.device = device
+
+        self.config.update(
+            {
+                "input_backend": self.input_backend,
+                "output_backend": self.output_backend,
+                "add_batch_dim": self.add_batch_dim,
+                "device": self.device,
+            }
+        )
+
+    def _resolve_device(self) -> str:
+        if self.device != "auto":
+            return self.device
+
+        if self.input_backend == "torch":
+            return get_preferred_torch_device()
+        elif self.input_backend == "tensorflow":
+            return get_preferred_tensorflow_device()
+        else:
+            return "cpu"
+
+    def _prepare_image_input(self, image: Array, device: str) -> Any:
+        if self.input_backend == "numpy":
+            out = np.asarray(image, dtype=np.float32)
+            if self.add_batch_dim:
+                out = np.expand_dims(out, axis=0)
+            return out
+        elif self.input_backend == "tensorflow":
+            return numpy_hwc_to_tf_image(image, add_batch_dim=self.add_batch_dim)
+        elif self.input_backend == "torch":
+            return numpy_hwc_to_torch_image(
+                image,
+                add_batch_dim=self.add_batch_dim,
+                device=device,
+            )
+        else:
+            raise ValueError("Unsupported input_backend {!r}".format(self.input_backend))
+
+    def _prepare_matrix_input(self, matrix: Optional[Array], device: str) -> Any:
+        if matrix is None:
+            return None
+
+        if self.input_backend == "numpy":
+            return np.asarray(matrix, dtype=np.float32)
+        elif self.input_backend == "tensorflow":
+            return numpy_to_tf_matrix(matrix)
+        elif self.input_backend == "torch":
+            return numpy_to_torch_matrix(matrix, device=device)
+        else:
+            raise ValueError("Unsupported input_backend {!r}".format(self.input_backend))
+
+    def _get_pipeline_callable(self):
+        if hasattr(self.pipeline, "run_pipeline"):
+            return self.pipeline.run_pipeline
+        elif callable(self.pipeline):
+            return self.pipeline
+        else:
+            raise ValueError(
+                "pipeline must be a callable or an object exposing run_pipeline(...)."
+            )
+
+    def _normalize_result(self, result: Any, prepared: ReconstructionInputs):
+        if isinstance(result, tuple):
+            if len(result) != 2 or not isinstance(result[1], dict):
+                raise ValueError(
+                    "PipelineAdapter pipelines may return either prediction or "
+                    "(prediction, stats_dict)."
+                )
+            prediction, stats = result
+        else:
+            prediction, stats = result, None
+
+        if self.output_backend == "numpy":
+            pred_np = numpy_prediction_to_hwc(prediction, remove_batch_dim=self.add_batch_dim)
+        else:
+            pred_np = convert_prediction_to_numpy_hwc(
+                prediction,
+                output_backend=self.output_backend,
+                remove_batch_dim=self.add_batch_dim,
+            )
+
+        pred_np = self._restore_output_shape(pred_np, prepared)
+        pred_np = np.asarray(pred_np, dtype=np.float32)
+
+        if stats is None:
+            return pred_np
+        return pred_np, stats
+
+    def predict(self, inputs: ReconstructionInputs) -> Any:
+        prepared = self.prepare_inputs(inputs)
+        device = self._resolve_device()
+
+        LR_HSI = self._prepare_image_input(prepared.lr_hsi, device=device)
+        HR_MSI = self._prepare_image_input(prepared.hr_msi, device=device)
+        srf = self._prepare_matrix_input(prepared.srf, device=device)
+        psf = self._prepare_matrix_input(prepared.psf, device=device)
+
+        pipeline_fn = self._get_pipeline_callable()
+
+        result = pipeline_fn(
+            HR_MSI=HR_MSI,
+            LR_HSI=LR_HSI,
+            srf=srf,
+            psf=psf,
+            metadata=prepared.metadata,
+        )
+
+        return self._normalize_result(result, prepared)

hyperbench/adapters/tensorflow.py

@@ -0,0 +1,67 @@
+# Author: Ritik Shah
+
+"""TensorFlow model adapter for HyperBench."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import BaseAdapter, ReconstructionInputs, ShapePolicy
+
+
+Array = np.ndarray
+
+
+class TensorFlowModelAdapter(BaseAdapter):
+    """Adapter for TensorFlow / Keras models."""
+
+    def __init__(
+        self,
+        model,
+        name: str = "tensorflow_model",
+        shape_policy: ShapePolicy = "strict",
+        hr_multiple: int = 1,
+        lr_multiple: int = 1,
+        add_batch_dim: bool = True,
+    ) -> None:
+        super().__init__(
+            name=name,
+            shape_policy=shape_policy,
+            hr_multiple=hr_multiple,
+            lr_multiple=lr_multiple,
+        )
+        self.model = model
+        self.add_batch_dim = add_batch_dim
+
+        self.config.update(
+            {
+                "add_batch_dim": self.add_batch_dim,
+            }
+        )
+
+    def predict(self, inputs: ReconstructionInputs) -> Array:
+        try:
+            import tensorflow as tf
+        except ImportError as exc:
+            raise ImportError(
+                "TensorFlow is not installed. Install it separately before using "
+                "TensorFlowModelAdapter."
+            ) from exc
+
+        from hyperbench.utils import (
+            numpy_hwc_to_tf_image,
+            numpy_to_tf_matrix,
+            tf_image_to_numpy_hwc,
+        )
+
+        prepared = self.prepare_inputs(inputs)
+
+        lr = numpy_hwc_to_tf_image(prepared.lr_hsi, add_batch_dim=self.add_batch_dim)
+        hr = numpy_hwc_to_tf_image(prepared.hr_msi, add_batch_dim=self.add_batch_dim)
+        srf = numpy_to_tf_matrix(prepared.srf) if prepared.srf is not None else None
+        psf = numpy_to_tf_matrix(prepared.psf) if prepared.psf is not None else None
+
+        output = self.model(lr, hr, srf=srf, psf=psf)
+        output = tf_image_to_numpy_hwc(output, remove_batch_dim=self.add_batch_dim)
+        output = self._restore_output_shape(output, prepared)
+        return np.asarray(output, dtype=np.float32)