Displays the shaded map in 3D with the `rgl` package.

Note: Calling `plot_3d()` resets the scene cache for the `render_snapshot()`, `render_depth()`, and `render_highquality()`

plot_3d(
  hillshade,
  heightmap,
  zscale = 1,
  baseshape = "rectangle",
  solid = TRUE,
  soliddepth = "auto",
  solidcolor = "grey20",
  solidlinecolor = "grey30",
  shadow = TRUE,
  shadowdepth = "auto",
  shadowcolor = "auto",
  shadow_darkness = 0.5,
  shadowwidth = "auto",
  water = FALSE,
  waterdepth = 0,
  watercolor = "dodgerblue",
  wateralpha = 0.5,
  waterlinecolor = NULL,
  waterlinealpha = 1,
  linewidth = 2,
  lineantialias = FALSE,
  soil = FALSE,
  soil_freq = 0.1,
  soil_levels = 16,
  soil_color_light = "#b39474",
  soil_color_dark = "#8a623b",
  soil_gradient = 2,
  soil_gradient_darken = 4,
  theta = 45,
  phi = 45,
  fov = 0,
  zoom = 1,
  background = "white",
  windowsize = 600,
  precomputed_normals = NULL,
  asp = 1,
  triangulate = FALSE,
  max_error = 0,
  max_tri = 0,
  verbose = FALSE,
  plot_new = TRUE,
  close_previous = TRUE,
  clear_previous = TRUE
)

Arguments

hillshade

Hillshade/image to be added to 3D surface map.

heightmap

A two-dimensional matrix, where each entry in the matrix is the elevation at that point. All points are assumed to be evenly spaced.

zscale

Default `1`. The ratio between the x and y spacing (which are assumed to be equal) and the z axis. For example, if the elevation levels are in units of 1 meter and the grid values are separated by 10 meters, `zscale` would be 10. Adjust the zscale down to exaggerate elevation features.

baseshape

Default `rectangle`. Shape of the base. Options are `c("rectangle","circle","hex")`.

solid

Default `TRUE`. If `FALSE`, just the surface is rendered.

soliddepth

Default `auto`, which sets it to the lowest elevation in the matrix minus one unit (scaled by zscale). Depth of the solid base. If heightmap is uniform and set on `auto`, this is automatically set to a slightly lower level than the uniform elevation.

solidcolor

Default `grey20`. Base color.

solidlinecolor

Default `grey30`. Base edge line color.

shadow

Default `TRUE`. If `FALSE`, no shadow is rendered.

shadowdepth

Default `auto`, which sets it to `soliddepth - soliddepth/10`. Depth of the shadow layer.

shadowcolor

Default `auto`. Color of the shadow, automatically computed as `shadow_darkness` the luminance of the `background` color in the CIELuv colorspace if not specified.

shadow_darkness

Default `0.5`. Darkness of the shadow, if `shadowcolor = "auto"`.

shadowwidth

Default `auto`, which sizes it to 1/10th the smallest dimension of `heightmap`. Width of the shadow in units of the matrix.

water

Default `FALSE`. If `TRUE`, a water layer is rendered.

waterdepth

Default `0`. Water level.

watercolor

Default `lightblue`. Color of the water.

wateralpha

Default `0.5`. Water transparency.

waterlinecolor

Default `NULL`. Color of the lines around the edges of the water layer.

waterlinealpha

Default `1`. Water line tranparency.

linewidth

Default `2`. Width of the edge lines in the scene.

lineantialias

Default `FALSE`. Whether to anti-alias the lines in the scene.

soil

Default `FALSE`. Whether to draw the solid base with a textured soil layer.

soil_freq

Default `0.1`. Frequency of soil clumps. Higher frequency values give smaller soil clumps.

soil_levels

Default `16`. Fractal level of the soil.

soil_color_light

Default `"#b39474"`. Light tint of soil.

soil_color_dark

Default `"#8a623b"`. Dark tint of soil.

soil_gradient

Default `2`. Sharpness of the soil darkening gradient. `0` turns off the gradient entirely.

soil_gradient_darken

Default `4`. Amount to darken the `soil_color_dark` value for the deepest soil layers. Higher numbers increase the darkening effect.

theta

Default `45`. Rotation around z-axis.

phi

Default `45`. Azimuth angle.

fov

Default `0`--isometric. Field-of-view angle.

zoom

Default `1`. Zoom factor.

background

Default `grey10`. Color of the background.

windowsize

Default `600`. Position, width, and height of the `rgl` device displaying the plot. If a single number, viewport will be a square and located in upper left corner. If two numbers, (e.g. `c(600,800)`), user will specify width and height separately. If four numbers (e.g. `c(200,0,600,800)`), the first two coordinates specify the location of the x-y coordinates of the bottom-left corner of the viewport on the screen, and the next two (or one, if square) specify the window size. NOTE: The absolute positioning of the window does not currently work on macOS (tested on Mojave), but the size can still be specified.

precomputed_normals

Default `NULL`. Takes the output of `calculate_normals()` to save computing normals internally.

asp

Default `1`. Aspect ratio of the resulting plot. Use `asp = 1/cospi(mean_latitude/180)` to rescale lat/long at higher latitudes to the correct the aspect ratio.

triangulate

Default `FALSE`. Reduce the size of the 3D model by triangulating the height map. Set this to `TRUE` if generating the model is slow, or moving it is choppy. Will also reduce the size of 3D models saved to disk.

max_error

Default `0.001`. Maximum allowable error when triangulating the height map, when `triangulate = TRUE`. Increase this if you encounter problems with 3D performance, want to decrease render time with `render_highquality()`, or need to save a smaller 3D OBJ file to disk with `save_obj()`,

max_tri

Default `0`, which turns this setting off and uses `max_error`. Maximum number of triangles allowed with triangulating the height map, when `triangulate = TRUE`. Increase this if you encounter problems with 3D performance, want to decrease render time with `render_highquality()`, or need to save a smaller 3D OBJ file to disk with `save_obj()`,

verbose

Default `TRUE`, if `interactive()`. Prints information about the mesh triangulation if `triangulate = TRUE`.

plot_new

Default `TRUE`, opens new window with each `plot_3d()` call. If `FALSE`, the data will be plotted in the same window.

close_previous

Default `TRUE`. Closes any previously open `rgl` window. If `FALSE`, old windows will be kept open.

clear_previous

Default `TRUE`. Clears the previously open `rgl` window if `plot_new = FALSE`.

Examples

#Plotting a spherical texture map of the built-in `montereybay` dataset.
if(run_documentation()) {
montereybay %>%
 sphere_shade(texture="desert") %>%
 plot_3d(montereybay,zscale=50)
render_snapshot()
}


#With a water layer  
if(run_documentation()) {
montereybay %>%
 sphere_shade(texture="imhof2") %>%
 plot_3d(montereybay, zscale=50, water = TRUE, watercolor="imhof2", 
         waterlinecolor="white", waterlinealpha=0.5)
render_snapshot()
}


#With a soil texture to the base  
if(run_documentation()) {
montereybay %>%
 sphere_shade(texture="imhof3") %>%
 plot_3d(montereybay, zscale=50, water = TRUE,  watercolor="imhof4", 
         waterlinecolor="white", waterlinealpha=0.5, soil=TRUE)
render_camera(theta=225, phi=7, zoom=0.5, fov=67)
render_snapshot()
}


#We can also change the base by setting "baseshape" to "hex" or "circle"
if(run_documentation()) {
montereybay %>%
 sphere_shade(texture="imhof1") %>%
 plot_3d(montereybay, zscale=50, water = TRUE, watercolor="imhof1", theta=-45, zoom=0.7,
         waterlinecolor="white", waterlinealpha=0.5,baseshape="circle")
render_snapshot()
}


if(run_documentation()) {
montereybay %>%
 sphere_shade(texture="imhof1") %>%
 plot_3d(montereybay, zscale=50, water = TRUE, watercolor="imhof1", theta=-45, zoom=0.7,
         waterlinecolor="white", waterlinealpha=0.5,baseshape="hex")
render_snapshot()
}




#Or we can carve out the region of interest ourselves, by setting those entries to NA
#to the elevation map passed into `plot_3d`

#Here, we only include the deep bathymetry data by setting all points greater than -10
#in the copied elevation matrix to NA.

mb_water = montereybay
mb_water[mb_water > -10] = NA

if(run_documentation()) {
montereybay %>%
 sphere_shade(texture="imhof1") %>%
 plot_3d(mb_water, zscale=50, water = TRUE, watercolor="imhof1", theta=-45,
         waterlinecolor="white", waterlinealpha=0.5)
render_snapshot()
}