vibespatial.raster.histogram¶

GPU-accelerated histogram, CDF, equalization, and percentile operations.

GPU path: CCCL histogram_even for bin counting, CCCL exclusive_scan for CDF, and a custom NVRTC remap kernel for histogram equalization. All computation stays on-device until the final result transfer.

CPU path: numpy.histogram, numpy.cumsum, numpy-based equalization.

Functions¶

`raster_cumulative_distribution`(→ tuple[numpy.ndarray, ...)	Compute cumulative distribution function of raster pixel values.
`raster_histogram`(→ tuple[numpy.ndarray, ...)	Compute histogram of raster pixel values.
`raster_histogram_equalize`(...)	Apply histogram equalization to a raster.
`raster_percentile`(→ numpy.ndarray \| list[numpy.ndarray])	Compute percentile values from a raster using histogram-based CDF.

Module Contents¶

vibespatial.raster.histogram.raster_cumulative_distribution(raster: vibespatial.raster.buffers.OwnedRasterArray, bins: int = 256, *, range_min: float | None = None, range_max: float | None = None, use_gpu: bool | None = None) → tuple[numpy.ndarray, numpy.ndarray]¶

Compute cumulative distribution function of raster pixel values.

Computes the histogram, then takes the cumulative sum to get the CDF. Nodata pixels are excluded.

Parameters¶

rasterOwnedRasterArray: Input raster.
binsint: Number of histogram bins (default: 256).
range_min, range_maxfloat or None: Value range. If None, inferred from valid pixels.
use_gpubool or None: Force GPU (True), force CPU (False), or auto-dispatch (None).

Returns¶

tuple[np.ndarray, np.ndarray]: (cdf, bin_edges) where cdf has shape (bins,) and is monotonically non-decreasing, and bin_edges has shape (bins + 1,).

vibespatial.raster.histogram.raster_histogram(raster: vibespatial.raster.buffers.OwnedRasterArray, bins: int = 256, *, range_min: float | None = None, range_max: float | None = None, use_gpu: bool | None = None) → tuple[numpy.ndarray, numpy.ndarray] | list[tuple[numpy.ndarray, numpy.ndarray]]¶

Compute histogram of raster pixel values.

Nodata pixels are excluded from the histogram.

Parameters¶

rasterOwnedRasterArray: Input raster.
binsint: Number of histogram bins (default: 256).
range_min, range_maxfloat or None: Value range for the histogram. If None, inferred from valid pixels.
use_gpubool or None: Force GPU (True), force CPU (False), or auto-dispatch (None).

Returns¶

tuple[np.ndarray, np.ndarray]: For single-band: (counts, bin_edges) where counts has shape (bins,) and bin_edges has shape (bins + 1,).
list[tuple[np.ndarray, np.ndarray]]: For multiband: list of (counts, bin_edges) tuples, one per band.

vibespatial.raster.histogram.raster_histogram_equalize(raster: vibespatial.raster.buffers.OwnedRasterArray, *, use_gpu: bool | None = None) → vibespatial.raster.buffers.OwnedRasterArray¶

Apply histogram equalization to a raster.

Redistributes pixel values to achieve a roughly uniform histogram distribution across the 0-255 range. Output dtype is uint8. Nodata pixels are preserved.

For multiband rasters, each band is equalized independently and the results are reassembled into a multiband OwnedRasterArray.

GPU pipeline: histogram (CCCL) -> CDF (CCCL exclusive_sum) -> LUT build (CuPy element-wise) -> remap kernel (NVRTC). All computation stays on-device until the final D2H transfer.

Parameters¶

rasterOwnedRasterArray: Input raster.
use_gpubool or None: Force GPU (True), force CPU (False), or auto-dispatch (None).

Returns¶

OwnedRasterArray: Equalized raster with dtype uint8 and values in [0, 255].

vibespatial.raster.histogram.raster_percentile(raster: vibespatial.raster.buffers.OwnedRasterArray, percentiles: list[float] | float, *, bins: int = 256, use_gpu: bool | None = None) → numpy.ndarray | list[numpy.ndarray]¶

Compute percentile values from a raster using histogram-based CDF.

Avoids a full sort by computing percentiles from the histogram CDF, which is O(bins) rather than O(n log n). Nodata pixels are excluded.

Parameters¶

rasterOwnedRasterArray: Input raster.
percentileslist[float] or float: Percentile(s) to compute, in range [0, 100].
binsint: Number of histogram bins for CDF computation (default: 256). More bins = higher precision.
use_gpubool or None: Force GPU (True), force CPU (False), or auto-dispatch (None).

Returns¶

np.ndarray: For single-band: array of percentile values with shape (len(percentiles),).
list[np.ndarray]: For multiband: list of per-band percentile arrays, one per band.