plot3D: Interactive Maps of 3D surfaces

Description

Interactive maps showing the 3-dimensional (XYZ) variability in raster layers representing continuous variables. The XYZ reference positions will be obtained from an elevation layer and the values of the continuous variables will be used as a surface color gradient. For this function to work, there must be a raster layer of elevation (e.g., digital terrain model) and at least one continuous variable among the raster layers to map. The maps produced are interactive, meaning that manual axis rotation and zoom are possible. Special consideration must be taken with large raster layers (large spatial coverage and/or high spatial resolution). This function can aggregates the spatial resolution (i.e., cell size) in order to handle large raster layers. This is achieved by internally calling aggregate. An aggregation factor will determine the final cell size, where final cell size = cell size*aggregation factor. In addition, a spatial extent can be provided to reduce the total mapping area and thus, to further reduce processing time. This function uses the plotly library. See Details for current limitations.

Usage

plot3D(
  var.rast,
  z,
  ex = 0.1,
  agg = FALSE,
  fact = NULL,
  spext = NULL,
  pals = NA,
  rev = NA
)

Value

List with plotly-htmlwidget objects. Each object calls the 3D map for a continuous variable in var.rast.

Arguments

var.rast: SpatRaster, as in rast. Multi-layer SpatRaster of n continuous variables and one layer representing the surface/terrain elevation.
z: Integer. Position (index) of the raster layer of elevation in var.rast.
ex: Numeric. Value indicating the exaggeration factor for the Z axis. This can be useful to enhance the visualization of subtle topographic variability. Default: 0.1
agg: Boolean. Should the spatial resolution be aggregated to reduce processing time? Default: FALSE
fact: Numeric. If agg = TRUE, value indicating the aggregation factor. Default: NULL
spext: Numeric. List with the coordinates of the bounding box for spatial subset (xmin, xmax, ymin, ymax). SpatRaster or SpatVector from which a spatial extent can be calculated are also an acceptable input. Default: NULL
pals: Character. List of strings with the names of the n color ramps (one per continuous variable). See hcl.colors. Default: NA
rev: Character. List of n Booleans indicating whether or not to reverse the color ramp for each continuous variable. Default: NA

Details

Currently, this function does not allow to adjust the labels for XY axes so that actual coordinates are shown. Instead, the relative position values are shown on these axes.

Examples

Run this code

require(terra)
p <- system.file("exdat", package = "rassta")
# Multi-layer SpatRaster of topographic variables
ft <- list.files(path = p, pattern = "^height|^slope|^wetness",
                 full.names = TRUE
                )
tvars <- terra::rast(ft)
# Single-layer SpatRaster of terrain elevation
fe <- list.files(path = p, pattern = "^elevation", full.names = TRUE)
e <- terra::rast(fe)
# Add elevation to the SpatRaster of topographic variables
etvars <- c(e, tvars)
# Interactive 3D maps
maps <- plot3D(var.rast = etvars, z = 1, ex = 0.2,
               pals = c("Zissou", "Plasma", "Spectral")
              )
if(interactive()){maps}