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()
}
