defineWorld.RdFunction that defines the grid that can be traversed--the "world"--as well as the cells that can be accessed from each individual cell. This is the most time-intensive function.
defineWorld(
source,
source_id = "TILEID",
z_min = NULL,
grid = NULL,
proj = NULL,
grid_id = "TILEID",
cut_slope = Inf,
directions = 16,
neighbor_distance = 10,
z_fix = NULL,
unit = "m",
vals = "location",
precision = 2,
dist = "proj",
r = 6378137,
f = 1/298.257223563,
b = 6356752.3142,
FUN = NULL,
sampling = "bilinear",
water = FALSE,
water_speed = "speed",
uv = TRUE,
priority = "water",
overwrite = FALSE,
filt = 0,
dir = tempdir(),
cols = c("x_i", "y_i", "dz", "dl", "dr"),
...
)An object of class SpatVector, or potential inputs to
makeGrid that define the paths to the original source files
of the desired rasters in the same format as the
output of the makeGrid(sources = TRUE).
If the object is NOT a already a polygon of the appropriate format, set
source_id = NULL and add the necessary makeGrid
parameter
A character string representing the name of the column in the
source polygon containing the unique Tile IDs. Default is source_id = 'TILEID'
The minimum allowable elevation. Useful if DEM source includes
ocean bathymetry as does the SRTM data from AWS. Default is z_min = NULL,
but set to 0 for SRTM data.
An object of class SpatVector representing
the partitioning grid for the maximum possible travel area. Smaller grids increase
the amount of area that can be read into the memory, but require more I/O operations.
Default is grid = source.
A crs object or character string representing the output projection.
Default projection is proj = crs(polys) unless a `z_fix` or `proj` is
provided, in which case the latter is ignored. Great care should be
employed to ensure that the projection is conformal and in meters.
A character string representing the name of the column
in the grid polygon containing the unique Tile IDs. Default is tile_id = 'TILEID'
A number representing the dimensionless maximum slope
of ascent/descent. To ignore, set cut_slope = Inf.
One of the integers c(4, 8, 16),
the character string 'bishop',or a neighborhood matrix.
Default is directions = 16, implying that all 'knight and one-cell
queen moves' are permissible movements on the grid. See adjacent.
An integer representing the distance in meters that tiles are buffered. In other words, to ensure that all transitions in the 'world' are recorded, files for each tile will contain a number of observations that fall outside of the tile in other ones. Default is 100 m, but adjust on raster size.
A SpatRaster or Raster* that will define the resolution, origin, and
projection information for the entire "world" of possible movement. Note that
it does NOT need the same extent. Default resolution is 5, and offset is 0.
Default projection is proj = crs(polys) unless a `z_fix` or `proj` is
provided, in which case the latter is ignored. Great care should be
employed to ensure that the projection is conformal and in meters.
One of c("m", "km", "ft", "mi"), representing the unit of the DEM.
All will be converted to meters, which is the default.
A character string or a SpatRaster or Raster* object. Ignored unless the
polys parameter is a polygon NOT the output of the makeGrid
function as the default is the character string 'location',
AND the appropriate world .gz file is NOT
present in the workspace directory. In which case it must represent either the
original DEM or a character string with the column representing the DEM
filepath or URL.
An integer representing the number of decimals to retain
in the x and y directions. For grid sizes with nice, round numbers precisions
can be low. This factor is controled by rast.
Default is 2.
A character string representing the way distances should be
calculated. Default is dist = 'proj' for the default projection units,
but the following geodesic methods are also available:
c('haversine','cosine','karney','meeus','vincentyEllipsoid','vincentySphere').
The developer recommends 'karney'.
The earth's radius. Employed only if one of the geodesic methods is used.
Default is r = 6378137 for WGS1984.
The earth's ellipsoidal flattening. Employed only if
dist %in% c('karney','meeus','vincentyEllipsoid'). Default is
f=1/298.257223563 for WGS1984
The earth's semiminor axis. Employed only if dist = 'vincentyEllipsoid'.
Default is b=6356752.3142 for WGS1984.
Function to deal with overlapping values for overlapping sectors.
Default is NA, which uses merge.
To use mosaic, provide a compatible function.
How to resample rasters. Default is 'bilinear' interpolation,
although 'ngb' nearest neighbor is available for categorical rasters.
Optional. One of (1) SpatialPolygon* or SpatVector polygon representing
the area covered by water, in which case water_speed must also be provided;
(2) A RasterLayer or single-layer SpatRaster representing the speed of water at a
given location. Flow direction will be calculated from the world's DEM; or (3) A
two layer SpatRaster or Raster* object, representing either the horizontal/vertical
components of water velocity (in m/s) or the absolute water speed and flow direction
(in that order; see uv).
A character representing the column name in
water that contains the average speed of the water in m/s. Required
if water is a polygon.
Logical. If TRUE (the default), a two-layer raster input for
water is taken to be the horizontal and vertical components of water velocity.
If false, a two-layer raster input for water is taken to be the water speed
and flow direction.
One of 'water' (the default), or 'land', indicating
whether land values or water values should take precedence when values for a given
location exist in both datasets.
If a directory with a World subdirectory already exists,
should the latter be overwritten? Default is overwrite = FALSE.
Numeric. Size of moving window to apply a low-pass filter. Default
is filt = 0. Ignored unless the tiles need to be generated from
the raw source files.
A filepath to the directory being used as the workspace.
Default is tempdir() but unless the analyses will only be performed a few
times it is highly recommended to define a permanent workspace.
A character vector. Default is c("x_i","y_i","dz","dl","dr"), and dictates which columns are returned but final values for x and y and final/initial z values are also available
Additional arguments to pass to fix_z.
A /World/ directory, containing /Loc/, /Diff/,
and /Raw/, directories where cropped and transformed files will be stored,
and /callVars.gz/, /z_sources/, /z_grid/,
/z_fix.fst/, and /z_fix.fstproj/ files defining the world.
It first checks to see if the required
files contained within a '/World/' directory have already been created
in the dir workspace. If not it creates them; if the '/World/'
directory exists though, then an error is thrown (default) OR the user has the option
to overwrite the directory.
The default parameters are sufficient for a workflow involving calculating
costs with the calculateCosts function.
# Generate a DEM
n <- 5
dem <- expand.grid(list(x = 1:(n * 100),
y = 1:(n * 100))) / 100
dem <- as.data.table(dem)
dem[, z := 250 * exp(-(x - n/2)^2) +
250 * exp(-(y - n/2)^2)]
#> x y z
#> 1: 0.01 0.01 1.0146139
#> 2: 0.02 0.01 1.0404641
#> 3: 0.03 0.01 1.0675194
#> 4: 0.04 0.01 1.0958300
#> 5: 0.05 0.01 1.1254477
#> ---
#> 249996: 4.96 5.00 1.0711366
#> 249997: 4.97 5.00 1.0428260
#> 249998: 4.98 5.00 1.0157707
#> 249999: 4.99 5.00 0.9899205
#> 250000: 5.00 5.00 0.9652271
dem <- rast(dem)
ext(dem) <- c(10000, 20000, 30000, 40000)
crs(dem) <- "+proj=lcc +lat_1=48 +lat_2=33 +lon_0=-100 +datum=WGS84"
# Export it so it doesn't just exist on the memory
dir <- tempdir()
writeRaster(dem, paste0(dir,"/DEM.tif"),overwrite=TRUE)
# Import raster, get the grid
dem <- rast(paste0(dir,"/DEM.tif"))
grid <- makeGrid(dem = dem, nx = n, ny = n, sources = TRUE)
# Select all tiles that exist between x = (12000,16000) and y = (32000,36000)
tiles <- ext(c(12000,16000,32000,36000))
tiles <- as.polygons(tiles)
crs(tiles) <- crs(grid)
tiles <- whichTiles(region = tiles, polys = grid)
# Make a world but limit it to the DEM grid size
defineWorld(source = grid, cut_slope = 0.5,
res = res(dem), dir = dir, overwrite=TRUE)