Sparse polygon rasterization with exact coverage fractions

Source: R/burn_sparse.R

Computes exact coverage fractions for polygon-grid intersections via an exactextract-style flood-fill, returning sparse two-table output: run-length-encoded interior cells and individually weighted boundary cells.

burn_sparse(
  x,
  extent = NULL,
  dimension = NULL,
  resolution = NULL,
  tile_size = 4096L
)

Arguments

x

geometry input, one of:

  • an sfc geometry column (from sf)

  • a geos_geometry vector (from geos)

  • a list of raw vectors containing WKB

extent

numeric vector c(xmin, xmax, ymin, ymax) defining the raster extent. If NULL (default), derived from the bounding box of x.

dimension

integer vector c(ncol, nrow) defining the grid dimensions. If NULL (default), fitted to the extent with at most 256 cells along the longer axis, preserving aspect ratio. Mutually exclusive with resolution.

resolution

numeric, cell size (scalar for square cells, or c(dx, dy)). If supplied, dimension is computed from extent / resolution. Mutually exclusive with dimension.

tile_size

integer, maximum tile dimension (default 4096). The grid is processed in tiles of at most tile_size x tile_size cells to bound memory usage. Set to Inf to disable tiling. (Not relevant on burn_scanline(), whose memory cost is O(perimeter).)

Value

A list with class "controlledburn" containing:

runs

data.frame with columns row, col_start, col_end, id — run-length encoded interior cells (full coverage)

edges

data.frame with columns row, col, fraction, id — boundary cells with partial coverage, fraction in (0, 1)

extent

the raster extent

dimension

the grid dimensions

Row and column indices are 1-based. Row 1 is the top (ymax) row. The id column is a 1-based index into the input geometry vector.

Details

Polygon-only. Line and point input are rejected with an error directing the caller to burn_scanline(), which produces the unified (polygon / line / point) output schema.

Compared to burn_scanline(), this function is older and uses a bounding-box-bounded dense intermediate (hence the tile_size parameter). For polygon input the two functions produce numerically identical results; burn_scanline() is preferred for new code.

Examples

if (requireNamespace("geos", quietly = TRUE)) {
  library(geos)
  poly <- as_geos_geometry("POLYGON ((0.5 0.5, 2.5 0.5, 2.5 2.5, 0.5 2.5, 0.5 0.5))")

  # Explicit extent and dimension
  result <- burn_sparse(poly, extent = c(0, 3, 0, 3), dimension = c(3, 3))

  # Defaults: extent from bbox, 256-cell fitted grid
  result <- burn_sparse(poly)

  # Specify resolution (cell size)
  result <- burn_sparse(poly, resolution = 0.1)
}