vibespatial.raster.io¶

Raster IO: GeoTIFF and COG read/write via rasterio or nvImageCodec.

Host-side decode via rasterio, or GPU-native decode via nvImageCodec. The read_raster dispatcher tries the GPU path first (when available), falling back to rasterio transparently.

ADR-0037: Raster IO Support and Read Paths ADR: vibeSpatial-fx3.6 Phase 5: Streamed windowed IO

Functions¶

`has_nvimgcodec_support`(→ bool)	Check whether nvImageCodec GPU decode is available.
`has_rasterio_support`(→ bool)	Check whether rasterio is available.
`process_raster_streamed`(...)	Process a raster file tile-by-tile without loading the full raster.
`read_raster`(→ vibespatial.raster.buffers.OwnedRasterArray)	Read a raster file into an OwnedRasterArray.
`read_raster_metadata`(...)	Read raster metadata without loading pixel data.
`write_raster`(→ None)	Write an OwnedRasterArray to a raster file.

Module Contents¶

vibespatial.raster.io.has_nvimgcodec_support() → bool¶: Check whether nvImageCodec GPU decode is available.

vibespatial.raster.io.has_rasterio_support() → bool¶: Check whether rasterio is available.

vibespatial.raster.io.process_raster_streamed(input_path: str | pathlib.Path, output_path: str | pathlib.Path, op_fn: collections.abc.Callable[[vibespatial.raster.buffers.OwnedRasterArray], vibespatial.raster.buffers.OwnedRasterArray], plan: vibespatial.raster.buffers.RasterPlan, *, halo: int = 0, compress: str | None = 'deflate', tiled: bool = True, blockxsize: int = 256, blockysize: int = 256) → vibespatial.raster.buffers.RasterMetadata¶

Process a raster file tile-by-tile without loading the full raster.

Reads tiles from the input file via rasterio windowed reads, applies op_fn to each tile, and writes the result to the output file via rasterio windowed writes. At no point is the full raster held in host or device memory — only one tile’s worth of data is live at a time.

Parameters¶

input_pathstr or Path: Path to the input raster file (GeoTIFF, COG, or any rasterio- supported format).
output_pathstr or Path: Path to write the output raster file.
op_fnCallable[[OwnedRasterArray], OwnedRasterArray]: The operation to apply to each tile. Receives a tile-sized OwnedRasterArray and returns a result of the same spatial dimensions as the effective (non-halo) region. When halo > 0 the input includes halo border pixels and the dispatcher trims the result to the effective region.
planRasterPlan: A frozen RasterPlan that controls the tiling strategy. When plan.strategy == WHOLE the entire raster is read, processed, and written in one shot (the fast path). When plan.strategy == TILED, plan.tile_shape specifies the effective tile dimensions (tile_H, tile_W) and the raster is streamed tile-by-tile.
haloint: Number of overlap pixels to include around each tile for stencil operations. The result is trimmed back to the effective region before writing. Default 0 (no overlap).
compressstr or None: Compression algorithm for the output file. Default "deflate". Pass None for no compression.
tiledbool: Whether to write tiled GeoTIFF blocks. Default True.
blockxsize, blockysizeint: GeoTIFF internal tile dimensions when tiled=True.

Returns¶

RasterMetadata: Metadata of the output file.

Raises¶

ValueError: If plan.strategy is TILED but plan.tile_shape is None.
ImportError: If rasterio is not installed.

vibespatial.raster.io.read_raster(path: str | pathlib.Path, *, bands: list[int] | None = None, window: vibespatial.raster.buffers.RasterWindow | None = None, overview_level: int | None = None, residency: vibespatial.residency.Residency = Residency.HOST, decode_backend: str = 'auto') → vibespatial.raster.buffers.OwnedRasterArray¶

Read a raster file into an OwnedRasterArray.

Parameters¶

pathstr or Path: Path to a GeoTIFF, COG, or other rasterio-supported raster file.
bandslist[int] or None: 1-based band indices to read. None reads all bands.
windowRasterWindow or None: Sub-window to read. None reads the full raster.
overview_levelint or None: Overview (pyramid) level to read. None reads full resolution.
residencyResidency: Target residency for the output array.
decode_backendstr: Decode backend selection: "auto" (try GPU first, fall back to rasterio), "nvimgcodec" (GPU-only, raises on failure), or "rasterio" (CPU-only, skip GPU path).

Returns¶

OwnedRasterArray: The raster data with metadata, in the requested residency.

vibespatial.raster.io.read_raster_metadata(path: str | pathlib.Path) → vibespatial.raster.buffers.RasterMetadata¶

Read raster metadata without loading pixel data.

Parameters¶

pathstr or Path: Path to a GeoTIFF, COG, or other rasterio-supported raster file.

Returns¶

RasterMetadata: Shape, dtype, nodata, affine, CRS, and driver information.

vibespatial.raster.io.write_raster(path: str | pathlib.Path, raster: vibespatial.raster.buffers.OwnedRasterArray, *, driver: str = 'GTiff', compress: str | None = 'deflate', tiled: bool = True, blockxsize: int = 256, blockysize: int = 256) → None¶

Write an OwnedRasterArray to a raster file.

Parameters¶

pathstr or Path: Output file path.
rasterOwnedRasterArray: The raster to write.
driverstr: GDAL driver name (default “GTiff”).
compressstr or None: Compression algorithm (default “deflate”). None for no compression.
tiledbool: Whether to write tiled (default True for COG compatibility).
blockxsize, blockysizeint: Tile dimensions when tiled=True.