plot_3d: Plot 3D

In tylermorganwall/rayshader: Create Maps and Visualize Data in 2D and 3D

Plot 3D

Description

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

Usage

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

tylermorganwall/rayshader documentation built on Dec. 21, 2024, 4:29 p.m.