rasterize {gdalraster}

Burn vector geometries into a raster

Description

rasterize() burns vector geometries (points, lines, or polygons) into the band(s) of a raster dataset. Vectors are read from any GDAL OGR-supported vector format. This function is a wrapper for the gdal_rasterize command-line utility (https://gdal.org/programs/gdal_rasterize.html).

Usage

rasterize(
  src_dsn,
  dstfile,
  band = NULL,
  layer = NULL,
  where = NULL,
  sql = NULL,
  burn_value = NULL,
  burn_attr = NULL,
  invert = NULL,
  te = NULL,
  tr = NULL,
  tap = NULL,
  ts = NULL,
  dtName = NULL,
  dstnodata = NULL,
  init = NULL,
  fmt = NULL,
  co = NULL,
  add_options = NULL,
  quiet = FALSE
)

Arguments

src_dsn

Data source name for the input vector layer (filename or connection string).

dstfile

Filename of the output raster. Must support update mode access. This file will be created (or overwritten if it already exists - see Note).

band

Numeric vector. The band(s) to burn values into (for existing dstfile). The default is to burn into band 1. Not used when creating a new raster.

layer

Character vector of layer names(s) from src_dsn that will be used for input features. At least one layer name or a sql option must be specified.

where

An optional SQL WHERE style query string to select features to burn in from the input layer(s).

sql

An SQL statement to be evaluated against src_dsn to produce a virtual layer of features to be burned in (alternative to layer).

burn_value

A fixed numeric value to burn into a band for all features. A numeric vector can be supplied, one burn value per band being written to.

burn_attr

Character string. Name of an attribute field on the features to be used for a burn-in value. The value will be burned into all output bands.

invert

Logical scalar. TRUE to invert rasterization. Burn the fixed burn value, or the burn value associated with the first feature, into all parts of the raster not inside the provided polygon.

te

Numeric vector of length four. Sets the output raster extent. The values must be expressed in georeferenced units. If not specified, the extent of the output raster will be the extent of the vector layer.

tr

Numeric vector of length two. Sets the target pixel resolution. The values must be expressed in georeferenced units. Both must be positive.

tap

Logical scalar. (target aligned pixels) Align the coordinates of the extent of the output raster to the values of tr, such that the aligned extent includes the minimum extent. Alignment means that xmin / resx, ymin / resy, xmax / resx and ymax / resy are integer values.

ts

Numeric vector of length two. Sets the output raster size in pixels (xsize, ysize). Note that ts cannot be used with tr.

dtName

Character name of output raster data type, e.g., Byte, Int16, UInt16, Int32, UInt32, Float32, Float64. Defaults to Float64.

dstnodata

Numeric scalar. Assign a nodata value to output bands.

init

Numeric vector. Pre-initialize the output raster band(s) with these value(s). However, it is not marked as the nodata value in the output file. If only one value is given, the same value is used in all the bands.

fmt

Output raster format short name (e.g., "GTiff"). Will attempt to guess from the output filename if fmt is not specified.

co

Optional list of format-specific creation options for the output raster in a vector of "NAME=VALUE" pairs (e.g., options = c("TILED=YES","COMPRESS=LZW") to set LZW compression during creation of a tiled GTiff file).

add_options

An optional character vector of additional command-line options to gdal_rasterize (see the gdal_rasterize documentation at the URL above for all available options).

quiet

Logical scalar. If TRUE, a progress bar will not be displayed. Defaults to FALSE.

Value

Logical indicating success (invisible TRUE). An error is raised if the operation fails.

Note

The function creates a new target raster when any of the fmt, dstnodata, init, co, te, tr, tap, ts, or dtName arguments are used. The resolution or size must be specified using the tr or ts argument for all new rasters. The target raster will be overwritten if it already exists and any of these creation-related options are used.

See Also

polygonize()

Examples

# MTBS fire perimeters for Yellowstone National Park 1984-2022
dsn <- system.file("extdata/ynp_fires_1984_2022.gpkg", package="gdalraster")
sql <- "SELECT * FROM mtbs_perims ORDER BY mtbs_perims.ig_year"
out_file <- file.path(tempdir(), "ynp_fires_1984_2022.tif")

rasterize(src_dsn = dsn,
          dstfile = out_file,
          sql = sql,
          burn_attr = "ig_year",
          tr = c(90,90),
          tap = TRUE,
          dtName = "Int16",
          dstnodata = -9999,
          init = -9999,
          co = c("TILED=YES","COMPRESS=LZW"))

ds <- new(GDALRaster, out_file)
pal <- scales::viridis_pal(end = 0.8, direction = -1)(6)
ramp <- scales::colour_ramp(pal)
plot_raster(ds, legend = TRUE, col_map_fn = ramp, na_col = "#d9d9d9",
            main="YNP Fires 1984-2022 - Most Recent Burn Year")

ds$close()
deleteDataset(out_file)