vibespatial.raster.tiling¶

Tiling execution engine for raster operations.

Phase 1 (vibeSpatial-fx3.2): pointwise (zero-overlap) tiling. Processes rasters in spatial chunks that fit in VRAM, enabling large-raster GPU processing without OOM. Each tile undergoes a HOST->DEVICE->HOST round trip independently so that the full raster never needs to reside on the GPU at once.

Phase 2 (vibeSpatial-fx3.3): halo tiling for stencil/focal operations. Extends Phase 1 with overlap (halo) pixels so that each tile includes enough border context for neighbourhood kernels (convolution, slope, hillshade, morphology, focal statistics). The result is trimmed back to the effective tile region and stitched seamlessly.

Phase 3 (vibeSpatial-fx3.4): accumulator tiling for reduce operations. Map-reduce pattern for operations that summarize a raster into non-raster data (histograms, percentiles, zonal statistics). Each tile produces a partial accumulator which is merged pairwise via a caller-provided merge_fn.

Phase 4 (vibeSpatial-fx3.5): multi-pass tiling for CCL and distance transform. Two-pass pattern for operations that require cross-tile communication: (1) local pass processes each tile independently, (2) boundary merge reconciles results across tile seams on host.

ADR: vibeSpatial-fx3.2 Phase 1: Trivial tiling for pointwise operations ADR: vibeSpatial-fx3.3 Phase 2: Halo tiling for stencil operations ADR: vibeSpatial-fx3.4 Phase 3: Accumulator tiling for histogram/zonal ADR: vibeSpatial-fx3.5 Phase 4: Multi-pass tiling for CCL/distance

Functions¶

`dispatch_tiled`(...)	Execute a unary pointwise operation using spatial tiling.
`dispatch_tiled_accumulator`(→ T)	Execute a reduce operation over spatial tiles using map-reduce.
`dispatch_tiled_binary`(...)	Execute a binary pointwise operation using spatial tiling.
`dispatch_tiled_halo`(...)	Execute a unary stencil/focal operation using halo-aware spatial tiling.
`dispatch_tiled_multipass`(...)	Execute a multi-pass operation using spatial tiling with boundary merge.

Module Contents¶

vibespatial.raster.tiling.dispatch_tiled(raster: vibespatial.raster.buffers.OwnedRasterArray, op_fn: collections.abc.Callable[[vibespatial.raster.buffers.OwnedRasterArray], vibespatial.raster.buffers.OwnedRasterArray], plan: vibespatial.raster.buffers.RasterPlan) → vibespatial.raster.buffers.OwnedRasterArray¶

Execute a unary pointwise operation using spatial tiling.

Parameters¶

raster:: Input raster (single- or multi-band). Must be HOST-resident for the TILED path; the WHOLE fast path accepts any residency.
op_fn:: The operation to apply per tile. Receives a tile-sized OwnedRasterArray and returns a result of the same spatial dimensions. The operation may internally transfer the tile to device and back – this is the expected pattern for tiled GPU processing.
plan:: A frozen RasterPlan produced by analyze_raster_plan().

Returns¶

OwnedRasterArray: Result raster with the same shape, affine, CRS, and nodata as the input. The dtype is determined by op_fn’s output.

Raises¶

ValueError: If plan.strategy is TILED but plan.tile_shape is None, or if the raster is DEVICE-resident on the TILED path.

vibespatial.raster.tiling.dispatch_tiled_accumulator[T](raster: vibespatial.raster.buffers.OwnedRasterArray, tile_fn: collections.abc.Callable[[vibespatial.raster.buffers.OwnedRasterArray], T], merge_fn: collections.abc.Callable[[T, T], T], plan: vibespatial.raster.buffers.RasterPlan) → T¶

Execute a reduce operation over spatial tiles using map-reduce.

Unlike dispatch_tiled() which produces a raster output of the same spatial dimensions, this function produces an aggregated result by:

Splitting the raster into non-overlapping tiles (using plan.tile_shape).
Applying tile_fn to each tile to get a partial accumulator.
Merging partial accumulators left-to-right using merge_fn.

Parameters¶

raster:: Input raster (single- or multi-band). Must be HOST-resident for the TILED path; the WHOLE fast path accepts any residency.
tile_fn:: Maps a tile OwnedRasterArray to a partial accumulator of type T. For histogram: returns (counts_array, bin_edges_array). For zonal stats: returns {zone_id: {stat: value}}.
merge_fn:: Combines two partial accumulators into one. Must be associative (caller’s responsibility). For histogram: sums counts, keeps bin_edges. For zonal stats: merges per-zone sums/counts/min/max.
plan:: A frozen RasterPlan. Uses plan.tile_shape for tiling dimensions. plan.halo is ignored (accumulator ops don’t need overlap).

Returns¶

T: The final merged accumulator.

Raises¶

ValueError: If plan.strategy is TILED but plan.tile_shape is None, or if the raster is DEVICE-resident on the TILED path, or if the raster has degenerate (zero) spatial dimensions.

vibespatial.raster.tiling.dispatch_tiled_binary(a: vibespatial.raster.buffers.OwnedRasterArray, b: vibespatial.raster.buffers.OwnedRasterArray, op_fn: collections.abc.Callable[[vibespatial.raster.buffers.OwnedRasterArray, vibespatial.raster.buffers.OwnedRasterArray], vibespatial.raster.buffers.OwnedRasterArray], plan: vibespatial.raster.buffers.RasterPlan) → vibespatial.raster.buffers.OwnedRasterArray¶

Execute a binary pointwise operation using spatial tiling.

Same tiling strategy as dispatch_tiled() but extracts the same tile region from both input rasters and passes them to a binary op_fn.

Parameters¶

a, b:: Input rasters. Must have the same spatial dimensions. Must be HOST-resident for the TILED path.
op_fn:: Binary operation. Receives two tile-sized OwnedRasterArray objects and returns a result of the same spatial dimensions.
plan:: A frozen RasterPlan produced by analyze_raster_plan().

Returns¶

OwnedRasterArray: Result raster with the same shape, affine, CRS, and nodata as a. The dtype is determined by op_fn’s output.

Raises¶

ValueError: If a and b have different spatial dimensions, if plan.strategy is TILED but plan.tile_shape is None, or if either input is DEVICE-resident on the TILED path.

vibespatial.raster.tiling.dispatch_tiled_halo(raster: vibespatial.raster.buffers.OwnedRasterArray, op_fn: collections.abc.Callable[[vibespatial.raster.buffers.OwnedRasterArray], vibespatial.raster.buffers.OwnedRasterArray], plan: vibespatial.raster.buffers.RasterPlan) → vibespatial.raster.buffers.OwnedRasterArray¶

Execute a unary stencil/focal operation using halo-aware spatial tiling.

Similar to dispatch_tiled() but each tile is extracted with extra halo border pixels so that neighbourhood kernels (convolution, slope, hillshade, morphology, focal statistics) have sufficient context at tile edges. After op_fn processes the full physical tile the halo border is trimmed and only the interior (effective) region is stitched into the output.

Parameters¶

raster:: Input raster (single- or multi-band). Must be HOST-resident for the TILED path; the WHOLE fast path accepts any residency.
op_fn:: The stencil operation to apply per tile. Receives a tile-sized OwnedRasterArray that includes halo border pixels and returns a result of the same spatial dimensions as its input (i.e. the operation does not strip the halo itself). The dispatcher handles trimming.
plan:: A frozen RasterPlan produced by analyze_raster_plan(). plan.halo specifies the overlap pixels. plan.tile_shape specifies the effective (output) tile dimensions, not including the halo.

Returns¶

OwnedRasterArray: Result raster with the same shape, affine, CRS, and nodata as the input. The dtype is determined by op_fn’s output.

Raises¶

ValueError: If plan.strategy is TILED but plan.tile_shape is None, or if the raster is DEVICE-resident on the TILED path.

vibespatial.raster.tiling.dispatch_tiled_multipass(raster: vibespatial.raster.buffers.OwnedRasterArray, local_fn: collections.abc.Callable[[vibespatial.raster.buffers.OwnedRasterArray], vibespatial.raster.buffers.OwnedRasterArray], merge_fn: collections.abc.Callable[[numpy.ndarray, list[tuple[int, int, int, int]]], numpy.ndarray], plan: vibespatial.raster.buffers.RasterPlan) → vibespatial.raster.buffers.OwnedRasterArray¶

Execute a multi-pass operation using spatial tiling with boundary merge.

Designed for operations that require cross-tile communication (CCL, distance transform). The executor runs two passes:

Local pass: Process each tile independently via local_fn. Results are assembled into a full-size intermediate array on host.
Boundary merge: Call merge_fn on the full intermediate array with tile boundary information so that cross-tile inconsistencies (disconnected labels, truncated distances) can be reconciled.

Parameters¶

raster:

Input raster (single- or multi-band). Must be HOST-resident for the TILED path; the WHOLE fast path accepts any residency.

local_fn:

Applied to each tile independently in the first pass. Takes a tile-sized OwnedRasterArray and returns a result of the same spatial dimensions. The operation may internally transfer the tile to device and back – this is the expected pattern for tiled GPU processing.

merge_fn:

Applied to the full assembled intermediate result (on host) to reconcile tile boundaries. Takes:

intermediate: The assembled numpy array from all local_fn results, shape (H, W) or (bands, H, W).
tile_bounds_list: List of (row_start, row_end, col_start, col_end) tuples for each tile (row-major order), so merge_fn knows where tile boundaries are.

Returns the corrected numpy array (same shape). merge_fn runs entirely on host.

plan:

A frozen RasterPlan produced by analyze_raster_plan(). plan.halo is used for the local pass if > 0 (same semantics as dispatch_tiled_halo).

Returns¶

OwnedRasterArray: Result raster with the same shape, affine, CRS, and nodata as the input. The dtype is determined by local_fn’s output.

Raises¶

ValueError: If plan.strategy is TILED but plan.tile_shape is None, or if the raster is DEVICE-resident on the TILED path.