Generates a distance surface from layer y.

distance_raster(
  y,
  cellsize,
  extent = NULL,
  expand = NULL,
  measure = NULL,
  check = TRUE
)

Arguments

y

feature layer to measure distance to. Expecting an sf point, line or polygon compatible with sf::st_coordinates such as an sf, sfc or sfg object.

cellsize

size, in unit of projection, of pixels of output distance surface.

extent

optional alternative extent bounding box. See details.

expand

0-1 scaling eg. 5% expansion = 0.05. See details.

measure

method used to measure geographic distances. See geodist::geodist for more information. Ignored if CRS of y indicates projected coordinates.

check

default: TRUE. Checks the cellsize against the size of the feature layers y bounding box or optional extent argument.

Value

A distance raster surface.

Details

Calculates the distance of each pixel to the features in layer y. First, generates a regular grid of points in the bounding box of y or optionally provided extent. Then measures the distance from each point to the nearest feature in layer y using distanceto::distance_to(). Finally, returns the grid of distances, rasterized using the excellent package fasterize.

Note: this function is intended to provide a rough, low-res look at your distance surface. The function distanceto::distance_to() should be used for all precise measurements from points to features, as it avoids the costly procedure of generating an entire distance surface by calculating geographic distances directly between points x and features in layer y.

The features in layer y are expected to be an sf object. If the input CRS of features in layer y is longlat, eg. EPSG 4326, the distance is returned as measured by geodist::geodist. Otherwise, if the input CRS indicates projected coordinates, the distance measured is the euclidean distance.

The extent argument can be used to provide an alternative bounding box to generate the distance surface within. This might be useful, for example, if your features in layer y are in a larger area than you require or if you'd like to generate distance surfaces with a specific extent. The expand argument can be used to expand the bounding box calculated for layer y or provided by argument extent. This is just a simple multiplier on the min and max XY of the bounding box to generate a larger surface.

Examples

# Load sf
library(sf)
#> Linking to GEOS 3.9.1, GDAL 3.3.1, PROJ 8.0.1

# Load nc data
nc <- st_read(system.file("shapes/sids.shp", package="spData"))
#> Reading layer `sids' from data source 
#>   `/home/alecr/R/x86_64-pc-linux-gnu-library/4.1/spData/shapes/sids.shp' 
#>   using driver `ESRI Shapefile'
#> Simple feature collection with 100 features and 22 fields
#> Geometry type: MULTIPOLYGON
#> Dimension:     XY
#> Bounding box:  xmin: -84.32385 ymin: 33.88199 xmax: -75.45698 ymax: 36.58965
#> CRS:           NA
st_crs(nc) <- "+proj=longlat +datum=NAD27"

# Select first 5 of nc
ncsub <- nc[1:5,]

# Generate a distance raster from some of nc within extent of all of nc
distance_raster(ncsub, 0.1, st_bbox(nc), measure = 'geodesic')
#> class      : RasterLayer 
#> dimensions : 28, 89, 2492  (nrow, ncol, ncell)
#> resolution : 0.1, 0.1  (x, y)
#> extent     : -84.32385, -75.42385, 33.88199, 36.68199  (xmin, xmax, ymin, ymax)
#> crs        : +proj=longlat +datum=NAD27 +no_defs 
#> source     : memory
#> names      : layer 
#> values     : 0, 357349.6  (min, max)
#>