calculate_bigfoot: Gridded feature statistics for large sets of building footprint polygons

Source: R/calculate_pixel_footstats.R

Calculate selected metrics of building footprints for high-spatial resolution gridded outputs.

calculate_bigfoot(
  X,
  what = "all",
  how = "all",
  focalRadius = 0,
  controlZone = list(zoneName = "zoneID", method = "centroid"),
  controlUnits = list(areaUnit = "m^2", perimUnit = "m", distUnit = "m"),
  controlDist = list(maxSearch = 100, method = "centroid", unit =
    controlUnits$distUnit),
  filter = list(minArea = NULL, maxArea = NULL),
  template = NULL,
  tileSize = c(500, 500),
  parallel = TRUE,
  nCores = max(1, parallel::detectCores() - 1),
  outputPath = tempdir(),
  outputTag = NULL,
  tries = 100,
  restart = NULL,
  verbose = TRUE
)

# S3 method for sf
calculate_bigfoot(
  X,
  what = "all",
  how = "all",
  focalRadius = 0,
  controlZone = list(zoneName = "zoneID", method = "centroid"),
  controlUnits = list(areaUnit = "m^2", perimUnit = "m", distUnit = "m"),
  controlDist = list(maxSearch = 100, method = "centroid", unit =
    controlUnits$distUnit),
  filter = list(minArea = NULL, maxArea = NULL),
  template = NULL,
  tileSize = c(500, 500),
  parallel = TRUE,
  nCores = max(1, parallel::detectCores() - 1),
  outputPath = tempdir(),
  outputTag = NULL,
  tries = 100,
  restart = NULL,
  verbose = TRUE
)

# S3 method for sp
calculate_bigfoot(
  X,
  what = "all",
  how = "all",
  focalRadius = 0,
  controlZone = list(zoneName = "zoneID", method = "centroid"),
  controlUnits = list(areaUnit = "m^2", perimUnit = "m", distUnit = "m"),
  controlDist = list(maxSearch = 100, method = "centroid", unit =
    controlUnits$distUnit),
  filter = list(minArea = NULL, maxArea = NULL),
  template = NULL,
  tileSize = c(500, 500),
  parallel = TRUE,
  nCores = max(1, parallel::detectCores() - 1),
  outputPath = tempdir(),
  outputTag = NULL,
  tries = 100,
  restart = NULL,
  verbose = TRUE
)

# S3 method for character
calculate_bigfoot(
  X,
  what = "all",
  how = "all",
  focalRadius = 0,
  controlZone = list(zoneName = "zoneID", method = "centroid"),
  controlUnits = list(areaUnit = "m^2", perimUnit = "m", distUnit = "m"),
  controlDist = list(maxSearch = 100, method = "centroid", unit =
    controlUnits$distUnit),
  filter = list(minArea = NULL, maxArea = NULL),
  template = NULL,
  tileSize = c(500, 500),
  parallel = TRUE,
  nCores = max(1, parallel::detectCores() - 1),
  outputPath = tempdir(),
  outputTag = NULL,
  tries = 100,
  restart = NULL,
  verbose = TRUE
)

Arguments

X

object with building footprint polygons. This argument can take multiple spatial types, including sf and sp, or a filepath string to a file, or a list where each member provides a spatial object or a filepath string.
what

list of strings naming the columns or built-in geometry measures to calculate for each footprint. Other options include 'all' or 'nodist' to calculate all available characteristics and all except nearest-neighbour distance metrics.
how

list of strings naming functions to be used to calculate summary statistics. The functions can be built-in functions (e.g. "mean","sd"), or user-defined function names.
focalRadius

numeric. Distance in meters for a buffer around each template pixel. Creates a focal processing window for metrics.
controlZone

(optional) named list. Setting controls passed on to zonalIndex. Elements can include zoneName and method.
controlUnits

(optional) named list. Elements can include areaUnit, perimUnit, and distUnit. The values for these items should be strings that can be coerced into a units object.
controlDist

(optional) named list to override default options for distance calculations. Elements can include maxSearch and method. Ignored if metrics does not include a distance calculation. See fs_nndist.
filter

(optional) named list with minArea and maxArea. These are numeric values to filter footprints prior to processing. Default values are NULL and do not filter any records.
template

(optional). When creating a gridded output, a supplied stars or raster dataset to align the data.
tileSize

number of pixels per side of a tile. Can be a vector of length 2 (rows, column pixels). Default is c(500, 500).
parallel

logical. Should a parallel backend be used to process the tiles. Default is TRUE.
nCores

number of CPU cores to use if parallel is TRUE. Default is 1 less than the available CPUs.
outputPath

(optional). When creating a gridded output, a path for the location of the output. Default is the temp directory.
outputTag

(optional). A character string that will be added to the beginning of the output name for the gridded files.
tries

(optional). The number of attempts to write a tile to the output file. Default is 100.
restart

(optional). A tile index (or vector of tile indices) from which to restart processing. Default is NULL to always process from the beginning.
verbose

logical. Should progress messages be printed and a log of processed tiles be created. Default TRUE.

Value

Invisible. Returns a vector of paths to the output files.

Details

calculate_bigfoot

calculate_bigfoot provides a wrapper for a workflow to process vector polygons of structures to create a gridded output summary of morphology measures. The function wraps calculate_footstats along with other geometry functions of foot and read/writing functions from stars and sf.

The suggested way of using this function is to supply character strings for X and template rather than objects. Using strings is more memory-efficient. This function processes based on 'tiles' or sub-regions of the template grid and will only read in the portion of the object needed for the calculations.

See also

calculate_footstats

Examples

data("kampala", package="foot")
buildings <- kampala$buildings
templateGrid <- kampala$mastergrid

calculate_bigfoot(X=buildings,
                  what=list(list("shape"), list("perimeter")),
                  how=list(list("mean"), list("sum")),
                  controlUnits=list(areaUnit="m^2"),
                  filter = list(minArea=50,  # footprints must be larger than 50 m^2
                                maxArea=1000),  # footprints must be smaller than 1000 m^2
                  template=templateGrid, 
                  outputPath=tempdir(),  
                  outputTag="kampala",
                  parallel=FALSE,
                  verbose=TRUE)  

#> Loading required package: raster
#> Loading required package: sp
#> Reading template grid 
#> trying to read file: C:\Users\Admin\Documents\GitHub\foot\wd\in\kampala_grid.tif
#> Selecting metrics 
#> Setting control values 
#> Creating output grids 
#> Creating list of processing tiles 
#> 
#> Tile: 1 of 1
#> Reading footprints 
#> Reading template grid 
#> Selecting metrics 
#> Setting control values. 
#> Pre-calculating areas 
#> Pre-calculating perimeters 
#> Linking to GEOS 3.9.0, GDAL 3.2.1, PROJ 7.2.1
#> WARNING: different compile-time and runtime versions for GEOS found:
#> Linked against: 3.9.0-CAPI-1.16.2 compiled against: 3.8.1-CAPI-1.13.3
#> It is probably a good idea to reinstall sf, and maybe rgeos and rgdal too
#> Pre-calculating shape 
#> Creating zonal index 
#>  Filtering features larger than 50 
#>  Filtering features smaller than 1000 
#> 
#> Calculating  2  metrics ... 
#>    shape mean  
#>    perimeter sum  
#> Finished calculating metrics. 
#> Writing output tiles 
#> Finished writing grids
#> 
#> Finished processing all tiles: 2021-11-10 18:01:38

# read one of the output files and plot as a raster layer
outGrid <- raster::raster(file.path(tempdir(), "kampala_count.tif"))

#> Error in .local(.Object, ...) : 
#> 
#> Error in .rasterObjectFromFile(x, band = band, objecttype = "RasterLayer",     ...): Cannot create a RasterLayer object from this file. (file does not exist)
raster::plot(outGrid)

#> Error in h(simpleError(msg, call)): error in evaluating the argument 'x' in selecting a method for function 'plot': object 'outGrid' not found