gdalwarpFns: 3-Step postProcess sequence for SpatRasters using 'gdalwarp'

In PredictiveEcology/reproducible: Enhance Reproducibility of R Code

3-Step postProcess sequence for SpatRasters using gdalwarp

Description

gdalProject is a thin wrapper around sf::gdal_utils('gdalwarp', ...) with specific options set, notably, -r to method (in the ...), -t_srs to the crs of the toRas, -te to the extent of the toRas, -te_srs to the crs of the toRas, -dstnodata = NA, and -overwrite.

gdalResample is a thin wrapper around sf::gdal_utils('gdalwarp', ...) with specific options set, notably, ⁠"-r", "near"⁠, -te, -te_srs, tr, -dstnodata = NA, -overwrite.

gdalMask is a thin wrapper around sf::gdal_utils('gdalwarp', ...) with specific options set, notably, -cutline, -dstnodata = NA, and -overwrite.

Usage

gdalProject(
  fromRas,
  toRas,
  filenameDest,
  verbose = getOption("reproducible.verbose"),
  ...
)

gdalResample(
  fromRas,
  toRas,
  filenameDest,
  verbose = getOption("reproducible.verbose"),
  ...
)

gdalMask(
  fromRas,
  maskToVect,
  writeTo = NULL,
  verbose = getOption("reproducible.verbose"),
  ...
)

Arguments

fromRas	see from argument from postProcessTo(), but can only be a SpatRaster.
toRas	see to argument from postProcessTo(), but can only be a SpatRaster.
filenameDest	A filename with an appropriate extension (e.g., .tif) for gdal to write the output to. Since this function is conceived to be part of a chain, and not the final step, this function does not use writeTo, which is reserved for the final step in the chain.
verbose	Numeric, -1 silent (where possible), 0 being very quiet, 1 showing more messaging, 2 being more messaging, etc. Default is 1. Above 3 will output much more information about the internals of Caching, which may help diagnose Caching challenges. Can set globally with an option, e.g., ⁠options('reproducible.verbose' = 0) to reduce to minimal⁠
...	For gdalProject, this can be method. For gdalMask can be destinationPath and touches. For all ⁠gdal*⁠, this can also be and datatype.
maskToVect	see maskTo argument from maskTo(), but can only be a SpatVector
writeTo	Optional character string of a filename to use writeRaster to save the final object. Default is NULL, which means there is no writeRaster

Details

These three functions are used within postProcessTo, in the sequence: gdalProject, gdalResample and gdalMask, when from and projectTo are SpatRaster and maskTo is a SpatVector, but only if options(reproducible.gdalwarp = TRUE) is set.

This sequence is a slightly different order than the sequence when gdalwarp = FALSE or the arguments do not match the above. This sequence was determined to be faster and more accurate than any other sequence, including running all three steps in one gdalwarp call (which gdalwarp can do). Using one-step gdalwarp resulted in very coarse pixelation when converting from a coarse resolution to fine resolution, which visually was inappropriate in test cases.

See Also

gdalResample(), and gdalMask() and the overarching postProcessTo()

Examples

# prepare dummy data -- 3 SpatRasters, 2 SpatVectors
# need 2 SpatRaster
rf <- system.file("ex/elev.tif", package = "terra")
elev1 <- terra::rast(rf)
#'
ras2 <- terra::deepcopy(elev1)
ras2[ras2 > 200 & ras2 < 300] <- NA_integer_
terra::values(elev1) <- rep(1L, terra::ncell(ras2))
#'
# a polygon vector
f <- system.file("ex/lux.shp", package = "terra")
vOrig <- terra::vect(f)
v <- vOrig[1:2, ]
#'
utm <- terra::crs("epsg:23028") # $wkt
vInUTM <- terra::project(vOrig, utm)
vAsRasInLongLat <- terra::rast(vOrig, resolution = 0.008333333)
res100 <- 100
rInUTM <- terra::rast(vInUTM, resolution = res100, vals = 1)
# crop, reproject, mask, crop a raster with a vector in a different projection
#  --> gives message about not enough information
t1 <- postProcessTo(elev1, to = vInUTM)
# crop, reproject, mask a raster to a different projection, then mask
t2a <- postProcessTo(elev1, to = vAsRasInLongLat, maskTo = vInUTM)


# using gdal directly --> slightly different mask
opts <- options(reproducible.gdalwarp = TRUE)
t2b <- postProcessTo(elev1, to = vAsRasInLongLat, maskTo = vInUTM)
t3b <- postProcessTo(elev1, to = rInUTM, maskTo = vInUTM)
options(opts)

PredictiveEcology/reproducible documentation built on Dec. 12, 2024, 7:26 p.m.