Package 'rayshader'

Description

Overlays an image (with a transparency layer) on the current map.

Usage

add_overlay(
  hillshade = NULL,
  overlay = NULL,
  alphalayer = 1,
  alphacolor = NULL,
  alphamethod = "max",
  rescale_original = FALSE
)

Arguments

Value

Hillshade with overlay.

Examples

#Combining base R plotting with rayshader's spherical color mapping and raytracing:
if(run_documentation()) {
montereybay %>%
  sphere_shade() %>%
  add_overlay(height_shade(montereybay),alphalayer = 0.6)  %>%
  add_shadow(ray_shade(montereybay,zscale=50)) %>%
  plot_map()
}

if(run_documentation()) {
#Add contours with `generate_contour_overlay()`
montereybay %>%
  height_shade() %>%
  add_overlay(generate_contour_overlay(montereybay))  %>%
  add_shadow(ray_shade(montereybay,zscale=50)) %>%
  plot_map()
}

Description

Multiplies a texture array or shadow map by a shadow map.

Usage

add_shadow(hillshade, shadowmap, max_darken = 0.7, rescale_original = FALSE)

Arguments

Value

Shaded texture map.

Examples

#First we plot the sphere_shade() hillshade of `montereybay` with no shadows

if(run_documentation()) {
montereybay %>%
 sphere_shade(colorintensity=0.5) %>%
 plot_map()
}

#Raytrace the `montereybay` elevation map and add that shadow to the output of sphere_shade()
if(run_documentation()) {
montereybay %>%
 sphere_shade(colorintensity=0.5) %>%
 add_shadow(ray_shade(montereybay,sunaltitude=20,zscale=50),max_darken=0.3) %>%
 plot_map()
}

#Increase the intensity of the shadow map with the max_darken argument.
if(run_documentation()) {
montereybay %>%
 sphere_shade(colorintensity=0.5) %>%
 add_shadow(ray_shade(montereybay,sunaltitude=20,zscale=50),max_darken=0.1) %>%
 plot_map()
}

#Decrease the intensity of the shadow map.
if(run_documentation()) {
montereybay %>%
 sphere_shade(colorintensity=0.5) %>%
 add_shadow(ray_shade(montereybay,sunaltitude=20,zscale=50),max_darken=0.7) %>%
 plot_map()
}

Description

Adds a layer of water to a map.

Usage

add_water(hillshade, watermap, color = "imhof1")

Arguments

Examples

#Here we even out a portion of the volcano dataset to simulate water:
island_volcano = volcano
island_volcano[island_volcano < mean(island_volcano)] = mean(island_volcano)

#Setting a minimum area avoids classifying small flat areas as water:
if(run_documentation()) {
island_volcano %>%
 sphere_shade(texture="imhof3") %>%
 add_water(detect_water(island_volcano, min_area = 400),color="imhof3") %>%
 plot_map()
}
 
#We'll do the same thing with the Monterey Bay dataset to fill in the ocean:

montbay_water = montereybay
montbay_water[montbay_water < 0] = 0

if(run_documentation()) {
montereybay %>%
 sphere_shade(texture="imhof4") %>%
 add_water(detect_water(montbay_water),color="imhof4") %>%
 plot_map()
}

Description

Calculates Ambient Occlusion Shadow Map

Usage

ambient_shade(
  heightmap,
  anglebreaks = 90 * cospi(seq(5, 85, by = 5)/180),
  sunbreaks = 24,
  maxsearch = 30,
  multicore = FALSE,
  zscale = 1,
  cache_mask = NULL,
  shadow_cache = NULL,
  progbar = interactive(),
  ...
)

Arguments

Value

Shaded texture map.

Examples

#Here we produce a ambient occlusion map of the `montereybay` elevation map.
if(run_documentation()) {
plot_map(ambient_shade(heightmap = montereybay))
}

#We can increase the distance to look for surface intersections `maxsearch`
#and the density of rays sent out around the point `sunbreaks`.
if(run_documentation()) {
plot_map(ambient_shade(montereybay, sunbreaks = 24,maxsearch = 100, multicore=TRUE))
}
#Create the Red Relief Image Map (RRIM) technique using a custom texture and ambient_shade(),
#with an addition lambertian layer added with lamb_shade() to improve topographic clarity.
if(run_documentation()) {
bigmb = resize_matrix(montereybay, scale=2, method="cubic")
bigmb %>%
 sphere_shade(zscale=3, texture = create_texture("red","red","red","red","white")) %>%
 add_shadow(ambient_shade(bigmb, maxsearch = 100, multicore = TRUE,zscale=1),0) %>%
 add_shadow(lamb_shade(bigmb),0.5) %>%
 plot_map()
}

Description

Calculates the normal unit vector for every point on the grid.

Usage

calculate_normal(heightmap, zscale = 1, progbar = FALSE)

Arguments

Value

Matrix of light intensities at each point.

Examples

#Here we produce a light intensity map of the `volcano` elevation map.

#Cache the normal vectors of the volcano dataset
if(run_documentation()) {
volcanocache = calculate_normal(volcano)
}

#Use the cached vectors to speed up calculation of `sphere_shade()` on a map.
if(run_documentation()) {
sphere_shade(volcano,normalvectors = volcanocache) %>%
 plot_map()
}

Description

Render shadows from the 3D floating cloud layer on the ground. Use this function to add shadows to the map with the 'add_shadow()' function.

For realistic results, argument should match those passed to 'render_clouds()'. The exception to this is 'attenuation_coef', which can be used to adjust the darkness of the resulting shadows.

Usage

cloud_shade(
  heightmap,
  start_altitude = 1000,
  end_altitude = 2000,
  sun_altitude = 90,
  sun_angle = 315,
  time = 0,
  cloud_cover = 0.5,
  layers = 10,
  offset_x = 0,
  offset_y = 0,
  scale_x = 1,
  scale_y = 1,
  scale_z = 1,
  frequency = 0.005,
  fractal_levels = 16,
  attenuation_coef = 1,
  seed = 1,
  zscale = 1
)

Arguments

Value

A 2D shadow matrix.

Examples

if(run_documentation()) {
#Render clouds with cloud shadows on the ground
montereybay  %>%
 sphere_shade()  %>%
 add_shadow(cloud_shade(montereybay,zscale=50), 0.0) %>%
 plot_3d(montereybay,background="darkred",zscale=50)
render_camera(theta=-65, phi = 25, zoom = 0.45, fov = 80)
render_clouds(montereybay, zscale=50)    
render_snapshot()
}
if(run_documentation()) {
#Adjust the light direction for shadows and increase the attenuation for darker clouds
montereybay  %>%
 sphere_shade()  %>%
 add_shadow(cloud_shade(montereybay,zscale=50, sun_altitude=20, attenuation_coef = 3), 0.0) %>%
 plot_3d(montereybay,background="darkred",zscale=50)
render_camera(theta=-65, phi = 25, zoom = 0.45, fov = 80)
render_clouds(montereybay, zscale=50)    
render_snapshot()
}

Description

Generates a constant color layer.

Usage

constant_shade(heightmap, color = "white", alpha = 1)

Arguments

Value

RGB array of a single color layer.

Examples

if(run_documentation()) {
#Shade a red map
montereybay %>%
 constant_shade("red") %>%
 add_shadow(lamb_shade(montereybay),0) |> 
 plot_map()
}
if(run_documentation()) {
#Shade a green map
montereybay %>%
 constant_shade("green") %>%
 add_shadow(lamb_shade(montereybay),0) |> 
 plot_map()
}
if(run_documentation()) {
#Add a blue tint
montereybay %>%
 height_shade() |> 
 add_overlay(constant_shade(montereybay, "dodgerblue", alpha=0.25)) %>%
 add_shadow(lamb_shade(montereybay,zscale=50),0) |> 
 plot_map()
}
if(run_documentation()) {
#Use a blank map on which to draw other data
montereybay %>%
 constant_shade() %>%
 add_overlay(generate_line_overlay(monterey_roads_sf, linewidth=5, color="black",
                                   attr(montereybay,"extent"), width = 1080, height = 1080),
                                   alphalayer=0.8)  %>%
 add_water(detect_water(montereybay < 0), "dodgerblue") %>%
 plot_map()
}

Description

Transforms latitude/longitude/altitude coordinates to the reference system used in 'render_highquality()', so they can be used to create high quality pathtraced animations by passing the output to the 'animation_camera_coords' argument in 'render_highquality()'.

This function converts the path values to rayshader coordinates (by setting 'return_coords = TRUE' in 'render_path()') and then subtracts out the rgl y-offset, which can be obtained by calling the internal function 'rayshader:::get_scene_depth()'.

Usage

convert_path_to_animation_coords(
  lat,
  long = NULL,
  altitude = NULL,
  extent = NULL,
  frames = 360,
  reorder = FALSE,
  reorder_first_index = 1,
  reorder_duplicate_tolerance = 0.1,
  reorder_merge_tolerance = 1,
  simplify_tolerance = 0,
  zscale = 1,
  heightmap = NULL,
  offset = 5,
  type = "bezier",
  offset_lookat = 1,
  constant_step = TRUE,
  curvature_adjust = "none",
  curvature_scale = 30,
  follow_camera = FALSE,
  follow_distance = 100,
  follow_angle = 45,
  follow_rotations = 0,
  follow_fixed = FALSE,
  follow_fixed_offset = c(10, 10, 10),
  damp_motion = FALSE,
  damp_magnitude = 0.1,
  resample_path_evenly = TRUE,
  ...
)

Arguments

Examples

#Generate a circle in Monterey Bay and fly around on top of it
if(run_documentation()) {
montereybay %>%
 sphere_shade() %>%
 plot_3d(montereybay,zscale=50,water=TRUE,
         shadowcolor="#40310a", background = "tan",
         theta=210,  phi=22, zoom=0.40, fov=55)
         
moss_landing_coord = c(36.806807, -121.793332)
t = seq(0,2*pi,length.out=1000)
circle_coords_lat = moss_landing_coord[1] + 0.25 * sin(t)
circle_coords_long = moss_landing_coord[2] + 0.25  *  cos(t)
render_path(extent = attr(montereybay,"extent"), heightmap = montereybay,
           lat = unlist(circle_coords_lat), long = unlist(circle_coords_long),
           zscale=50, color="red", antialias=TRUE,
           offset=100, linewidth=2)
render_snapshot()

camera_path = convert_path_to_animation_coords(extent = attr(montereybay,"extent"), 
                                              heightmap = montereybay,
                                              lat = unlist(circle_coords_lat), 
                                              long = unlist(circle_coords_long),
                                              fovs = 80,
                                              zscale=50, offset=250, frames = 25)

#Render a series of frames, following the path specified above
temp_dir = tempdir()
render_highquality(samples=16, animation_camera_coords = camera_path, 
                  width=200,height=200, filename = sprintf("%s/frame",temp_dir),
                  use_extruded_paths = TRUE,
                  sample_method="sobol_blue")

#Plot all these frames
image_list = list()
for(i in 1:25) {
  image_list[[i]] = png::readPNG(sprintf("%s/frame%d.png",temp_dir,i))
}
rayimage::plot_image_grid(image_list, dim = c(5,5))
}

if(run_documentation()) {
#Now render a third-person view by setting `follow_camera = TRUE`
camera_path = convert_path_to_animation_coords(extent = attr(montereybay,"extent"), 
                                              heightmap = montereybay,
                                              lat = unlist(circle_coords_lat), 
                                              long = unlist(circle_coords_long),
                                              fovs = 80,
                                              follow_camera = TRUE,
                                              zscale=50, offset=250, frames = 25)

#Render a series of frames, following the path specified above
temp_dir = tempdir()
render_highquality(samples=16, animation_camera_coords = camera_path, 
                  width=200,height=200, filename = sprintf("%s/frame",temp_dir),
                  use_extruded_paths = TRUE,
                  sample_method="sobol_blue")

#Plot all these frames
image_list = list()
for(i in 1:25) {
  image_list[[i]] = png::readPNG(sprintf("%s/frame%d.png",temp_dir,i))
}
rayimage::plot_image_grid(image_list, dim = c(5,5))
}

Description

Converts the current RGL rayshader scene to a 'ray_mesh' object (see 'rayvertex' package for more information)

Usage

convert_rgl_to_raymesh(save_shadow = TRUE)

Arguments

Value

A 'ray_mesh' object

Examples

filename_obj = tempfile(fileext = ".obj")
#Save model of volcano
if(run_documentation()) {
volcano %>%
 sphere_shade() %>%
 plot_3d(volcano, zscale = 2)

rm_obj = convert_rgl_to_raymesh()
}

Description

Creates a texture map based on 5 user-supplied colors.

Usage

create_texture(
  lightcolor,
  shadowcolor,
  leftcolor,
  rightcolor,
  centercolor,
  cornercolors = NULL
)

Arguments

Examples

#Here is the `imhof1` palette:
create_texture("#fff673","#55967a","#8fb28a","#55967a","#cfe0a9") %>%
 plot_map()

#Here is the `unicorn` palette:
create_texture("red","green","blue","yellow","white") %>%
 plot_map()

Description

Detects bodies of water (of a user-defined minimum size) within an elevation matrix.

Usage

detect_water(
  heightmap,
  zscale = 1,
  cutoff = 0.999,
  min_area = length(heightmap)/400,
  max_height = NULL,
  normalvectors = NULL,
  keep_groups = FALSE,
  progbar = FALSE
)

Arguments

Value

Matrix indicating whether water was detected at that point. 1 indicates water, 0 indicates no water.

Examples

library(magrittr)
#Here we even out a portion of the volcano dataset to simulate water:
island_volcano = volcano
island_volcano[island_volcano < mean(island_volcano)] = mean(island_volcano)

#Setting a minimum area avoids classifying small flat areas as water:
island_volcano %>%
 sphere_shade(texture="imhof3") %>%
 add_water(detect_water(island_volcano, min_area = 400),color="imhof3") %>%
 plot_map()

Description

3D obj model of a flag (sans pole), to be used with 'render_obj()'. Use 'flag_full_obj()' to get the complete pole, and 'flag_banner_obj()' and 'flag_pole_obj()' to style them separately.

Usage

flag_banner_obj()

Value

File location of the included flag OBJ file (saved with a .txt extension)

Examples

#Print the location of the flag file
flag_banner_obj()

Description

3D obj model of a flag, to be used with 'render_obj()'. Use 'flag_full_obj()' to get the complete pole, and 'flag_banner_obj()' and 'flag_pole_obj()' to style them separately.

Usage

flag_full_obj()

Value

File location of the included flag OBJ file (saved with a .txt extension)

Examples

#Print the location of the flag file
flag_full_obj()

Description

3D obj model of a flag pole, to be used with 'render_obj()'. Use 'full_flag_obj()' to get the complete pole, and 'flag_banner_obj()' and 'flag_pole_obj()' to style them separately.

Usage

flag_pole_obj()

Value

File location of the included flag OBJ file (saved with a .txt extension)

Examples

#Print the location of the flag file
flag_pole_obj()

Description

Using a hillshade and the height map, generates a semi-transparent hillshade to layer onto an existing map.

Usage

generate_altitude_overlay(
  hillshade,
  heightmap,
  start_transition,
  end_transition = NULL,
  lower = TRUE
)

Arguments

Value

4-layer RGB array representing the semi-transparent hillshade.

Examples

#Create a bathymetric hillshade
if(run_documentation()) {
water_palette = colorRampPalette(c("darkblue", "dodgerblue", "lightblue"))(200)
bathy_hs = height_shade(montereybay, texture = water_palette)
plot_map(bathy_hs)
}

if(run_documentation()) {
#Set everything below 0m to water palette
montereybay %>%
 sphere_shade(zscale=10) %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 plot_map()
}

#Add snow peaks by setting `lower = FALSE`  
snow_palette = "white"
snow_hs = height_shade(montereybay, texture = snow_palette)

if(run_documentation()) {
#Set the snow transition region from 500m to 1200m
montereybay %>%
 sphere_shade(zscale=10, texture = "desert") %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  %>%
 add_overlay(generate_altitude_overlay(snow_hs, montereybay, 500, 1200, lower=FALSE))  %>%
 add_shadow(ambient_shade(montereybay,zscale=50,maxsearch=100),0) %>%
 plot_map()
}

Description

This adds the compass

Based on code from "Auxiliary Cartographic Functions in R: North Arrow, Scale Bar, and Label with a Leader Arrow"

Usage

generate_compass_overlay(
  x = 0.85,
  y = 0.15,
  size = 0.075,
  text_size = 1,
  bearing = 0,
  heightmap = NULL,
  width = NA,
  height = NA,
  resolution_multiply = 1,
  color1 = "white",
  color2 = "black",
  text_color = "black",
  border_color = "black",
  border_width = 1,
  halo_color = NA,
  halo_expand = 1,
  halo_alpha = 1,
  halo_offset = c(0, 0),
  halo_blur = 1
)

Arguments

Value

Semi-transparent overlay with a compass.

Examples

if(run_documentation()) {
#Create the water palette
water_palette = colorRampPalette(c("darkblue", "dodgerblue", "lightblue"))(200)
bathy_hs = height_shade(montereybay, texture = water_palette)

#Generate flat water heightmap
mbay = montereybay
mbay[mbay < 0] = 0

base_map = mbay %>% 
 height_shade() %>% 
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  %>%
 add_shadow(lamb_shade(montereybay,zscale=50),0.3)
 
#Plot a compass
base_map %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay)) %>% 
 plot_map()
}

if(run_documentation()) {
#Change the position to be over the water
base_map %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.15)) %>% 
 plot_map()
}
if(run_documentation()) {
#Change the text color for visibility
base_map %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.15, text_color="white")) %>% 
 plot_map()
} 
if(run_documentation()) {
#Alternatively, add a halo color to improve contrast
base_map %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.15, y=0.15,
             halo_color="white", halo_expand = 1)) %>% 
 plot_map()
}
if(run_documentation()) {
#Alternatively, add a halo color to improve contrast
base_map %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.15, y=0.15,
             halo_color="white", halo_expand = 1)) %>% 
 plot_map()
}
if(run_documentation()) {
#Change the color scheme
base_map %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.15, y=0.15,
             halo_color="white", halo_expand = 1, color1 = "purple", color2 = "red")) %>% 
 plot_map()
}
if(run_documentation()) {
#Remove the inner border
base_map %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.15, y=0.15,
             border_color=NA,
             halo_color="white", halo_expand = 1, 
             color1 = "darkolivegreen4", color2 = "burlywood3")) %>% 
 plot_map()
}
if(run_documentation()) {
#Change the size of the compass and text
base_map %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.75, y=0.75,
             halo_color="white", halo_expand = 1, 
             size=0.075*2, text_size = 1.25)) %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.45, y=0.45,
             halo_color="white", halo_expand = 1, 
             size=0.075)) %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.15, y=0.15,
             halo_color="white", halo_expand = 1, 
             size=0.075/2, text_size = 0.75)) %>% 
 plot_map()
}
if(run_documentation()) {
#Change the bearing of the compass
base_map %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.85, y=0.85,
             halo_color="white", halo_expand = 1, bearing=30,
             size=0.075)) %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.5, y=0.5,
             halo_color="white", halo_expand = 1, bearing=15,
             size=0.075)) %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.15, y=0.15,
             halo_color="white", halo_expand = 1, bearing=-45,
             size=0.075)) %>% 
 plot_map()
}
if(run_documentation()) {
#Create a drop shadow effect
base_map %>% 
 add_overlay(generate_compass_overlay(heightmap = montereybay, x = 0.15, y=0.15,
             text_color="white", halo_alpha=0.5, halo_blur=2,
             halo_color="black", halo_expand = 1, halo_offset = c(0.003,-0.003))) %>% 
 plot_map()
}

Description

Calculates and returns an overlay of contour lines for the current height map.

Usage

generate_contour_overlay(
  heightmap,
  levels = NA,
  nlevels = NA,
  zscale = 1,
  width = NA,
  height = NA,
  resolution_multiply = 1,
  color = "black",
  linewidth = 1
)

Arguments

Value

Semi-transparent overlay with contours.

Examples

#Add contours to the montereybay dataset
if(run_documentation()) {
montereybay %>%
 height_shade() %>%
 add_overlay(generate_contour_overlay(montereybay))  %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 plot_map()
}

#Add a different contour color for above and below water, and specify levels manually
water_palette = colorRampPalette(c("darkblue", "dodgerblue", "lightblue"))(200)
bathy_hs = height_shade(montereybay, texture = water_palette)
breaks = seq(range(montereybay)[1],range(montereybay)[2],length.out=50)
water_breaks = breaks[breaks < 0]
land_breaks = breaks[breaks > 0]

if(run_documentation()) {
montereybay %>%
 height_shade() %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 add_overlay(generate_contour_overlay(montereybay, levels = water_breaks, color="white"))  %>%
 add_overlay(generate_contour_overlay(montereybay, levels = land_breaks, color="black"))  %>%
 plot_map()
}
if(run_documentation()) {
#Increase the resolution of the contour to improve the appearance of lines
montereybay %>%
 height_shade() %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 add_overlay(generate_contour_overlay(montereybay, levels = water_breaks, color="white",
                                      height = nrow(montereybay)*2, 
                                      width  = ncol(montereybay)*2))  %>%
 add_overlay(generate_contour_overlay(montereybay, levels = land_breaks, color="black",
                                      height = nrow(montereybay)*2, 
                                      width  = ncol(montereybay)*2))  %>%
 plot_map()
}
if(run_documentation()) {
#Increase the number of breaks and the transparency (via add_overlay)
montereybay %>%
 height_shade() %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 add_overlay(generate_contour_overlay(montereybay, linewidth=2, nlevels=100,
                                      height = nrow(montereybay)*2, color="black",
                                      width  = ncol(montereybay)*2), alphalayer=0.5) %>%
 plot_map()
}
if(run_documentation()) {
#Manually specify the breaks with levels
montereybay %>%
 height_shade() %>%
 add_overlay(generate_contour_overlay(montereybay, linewidth=2, levels = seq(-2000,0,100))) %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 plot_map()
}

Description

This uses the 'car::placeLabel()' function to generate labels for the given scene. Either use an 'sf' object or manually specify the x/y coordinates and label.

Usage

generate_label_overlay(
  labels,
  extent,
  x = NULL,
  y = NULL,
  heightmap = NULL,
  width = NA,
  height = NA,
  resolution_multiply = 1,
  text_size = 1,
  color = "black",
  font = 1,
  pch = 16,
  point_size = 1,
  point_color = NA,
  offset = c(0, 0),
  data_label_column = NULL,
  halo_color = NA,
  halo_expand = 0,
  halo_alpha = 1,
  halo_offset = c(0, 0),
  halo_blur = 1,
  seed = NA
)

Arguments

Value

Semi-transparent overlay with labels.

Examples

#Add the included `sf` object with roads to the montereybay dataset
if(run_documentation()) {
#Create the water palette
water_palette = colorRampPalette(c("darkblue", "dodgerblue", "lightblue"))(200)
bathy_hs = height_shade(montereybay, texture = water_palette)
#Set label font
par(family = "Arial")

#We're plotting the polygon data here for counties around Monterey Bay. We'll first
#plot the county names at the polygon centroids.
bathy_hs %>% 
 add_shadow(lamb_shade(montereybay,zscale=50),0.3) %>%
 add_overlay(generate_polygon_overlay(monterey_counties_sf, palette = rainbow, 
                                      extent = attr(montereybay,"extent"),
                                      heightmap = montereybay)) %>% 
 add_overlay(generate_label_overlay(labels=monterey_counties_sf,
                                    color="black", point_size = 1, text_size = 1,
                                    data_label_column = "NAME",
                                    extent= attr(montereybay,"extent"), heightmap = montereybay,
                                    seed=1))  %>%
 plot_map()
}
if(run_documentation()) {
#It's hard to read these values, so we'll add a white halo.
bathy_hs %>% 
 add_shadow(lamb_shade(montereybay,zscale=50),0.3) %>%
 add_overlay(generate_polygon_overlay(monterey_counties_sf, palette = rainbow, 
                                      extent = attr(montereybay,"extent"),
                                      heightmap = montereybay)) %>% 
 add_overlay(generate_label_overlay(labels=monterey_counties_sf,
                                    color="black", point_size = 1, text_size = 1,
                                    data_label_column = "NAME",
                                    extent= attr(montereybay,"extent"), heightmap = montereybay,
                                    halo_color = "white", halo_expand = 3,
                                    seed=1))  %>%
 plot_map()
}
if(run_documentation()) {
#Plot the actual town locations, using the manual plotting interface instead of the `sf` object
montereybay %>%
 height_shade() %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0)) %>% 
 add_shadow(lamb_shade(montereybay,zscale=50),0.3) %>%
 add_overlay(generate_label_overlay(labels=as.character(monterey_counties_sf$NAME),
                                    x=as.numeric(as.character(monterey_counties_sf$INTPTLON)),
                                    y=as.numeric(as.character(monterey_counties_sf$INTPTLAT)),
                                    color="black", point_size = 1, text_size = 1,
                                    extent= attr(montereybay,"extent"), heightmap = montereybay,
                                    halo_color = "white", halo_expand = 3,
                                    seed=1))  %>%
 plot_map()
}
if(run_documentation()) {
#Adding a softer blurred halo
montereybay %>%
 height_shade() %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0)) %>% 
 add_shadow(lamb_shade(montereybay,zscale=50),0.3) %>%
 add_overlay(generate_label_overlay(labels=as.character(monterey_counties_sf$NAME),
                                    x=as.numeric(as.character(monterey_counties_sf$INTPTLON)),
                                    y=as.numeric(as.character(monterey_counties_sf$INTPTLAT)),
                                    color="black", point_size = 1, text_size = 1,
                                    extent= attr(montereybay,"extent"), heightmap = montereybay,
                                    halo_color = "white", halo_expand = 3, halo_blur=10,
                                    seed=1))  %>%
 plot_map()
}
if(run_documentation()) {
#Changing the seed changes the locations of the labels
montereybay %>%
 height_shade() %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0)) %>% 
 add_shadow(lamb_shade(montereybay,zscale=50),0.3) %>%
 add_overlay(generate_label_overlay(labels=as.character(monterey_counties_sf$NAME),
                                    x=as.numeric(as.character(monterey_counties_sf$INTPTLON)),
                                    y=as.numeric(as.character(monterey_counties_sf$INTPTLAT)),
                                    color="black", point_size = 1, text_size = 1,
                                    extent= attr(montereybay,"extent"), heightmap = montereybay,
                                    halo_color = "white", halo_expand = 3, halo_blur=10,
                                    seed=2))  %>%
 plot_map()
}

Description

Calculates and returns an overlay of lines for the current height map.

Usage

generate_line_overlay(
  geometry,
  extent,
  heightmap = NULL,
  width = NA,
  height = NA,
  resolution_multiply = 1,
  color = "black",
  linewidth = 1,
  lty = 1,
  data_column_width = NULL,
  offset = c(0, 0)
)

Arguments

Value

Semi-transparent overlay with contours.

Examples

#Add the included `sf` object with roads to the montereybay dataset
if(run_documentation()) {
water_palette = colorRampPalette(c("darkblue", "dodgerblue", "lightblue"))(200)
bathy_hs = height_shade(montereybay, texture = water_palette)
montereybay %>% 
 height_shade() %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  %>%
 add_overlay(generate_line_overlay(monterey_roads_sf, 
                                   attr(montereybay,"extent"), heightmap = montereybay))  %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 plot_map()
}
if(run_documentation()) {
#Change the line width, color, and transparency
montereybay %>%
 height_shade() %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  %>%
 add_overlay(generate_line_overlay(monterey_roads_sf, linewidth=3, color="white",
                                   attr(montereybay,"extent"), heightmap = montereybay),
                                   alphalayer=0.8)  %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 plot_map()
}
if(run_documentation()) {
#Manually specify the width and height to improve visual quality of the lines
montereybay %>%
 height_shade() %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 add_overlay(generate_line_overlay(monterey_roads_sf, linewidth=3, color="white",
                                   attr(montereybay,"extent"), width = 1080, height = 1080),
                                   alphalayer=0.8)  %>%
 plot_map()
}

Description

Calculates and returns an overlay of points for the current map.

Usage

generate_point_overlay(
  geometry,
  extent,
  heightmap = NULL,
  width = NA,
  height = NA,
  resolution_multiply = 1,
  pch = 20,
  color = "black",
  size = 1,
  offset = c(0, 0),
  data_column_width = NULL
)

Arguments

Value

Semi-transparent overlay with contours.

Examples

#Add the included `sf` object with roads to the montereybay dataset
if(run_documentation()) {
 monterey_city = sf::st_sfc(sf::st_point(c(-121.893611, 36.603056)))
 montereybay %>% 
   height_shade() %>%
   add_overlay(generate_point_overlay(monterey_city, color="red", size=12, 
                                   attr(montereybay,"extent"), heightmap = montereybay))  %>%
   add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
   plot_map()
}

Description

Transforms an input 'sf' object into an image overlay for the current height map.

Usage

generate_polygon_overlay(
  geometry,
  extent,
  heightmap = NULL,
  width = NA,
  height = NA,
  resolution_multiply = 1,
  offset = c(0, 0),
  data_column_fill = NULL,
  linecolor = "black",
  palette = "white",
  linewidth = 1
)

Arguments

Value

Image overlay representing the input polygon data.

Examples

#Plot the counties around Monterey Bay, CA
if(run_documentation()) {
generate_polygon_overlay(monterey_counties_sf, palette = rainbow, 
                        extent = attr(montereybay,"extent"), heightmap = montereybay) %>%
 plot_map() 
}
if(run_documentation()) {
#These counties include the water, so we'll plot bathymetry data over the polygon
#data to only include parts of the polygon that fall on land.
water_palette = colorRampPalette(c("darkblue", "dodgerblue", "lightblue"))(200)
bathy_hs = height_shade(montereybay, texture = water_palette)

generate_polygon_overlay(monterey_counties_sf, palette = rainbow, 
                        extent = attr(montereybay,"extent"), heightmap = montereybay) %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, start_transition = 0)) %>%
 plot_map()
}
if(run_documentation()) {
#Add a semi-transparent hillshade and change the palette, and remove the polygon lines
montereybay %>%
 sphere_shade(texture = "bw") %>%
 add_overlay(generate_polygon_overlay(monterey_counties_sf, 
                        palette = terrain.colors, linewidth=NA,
                        extent = attr(montereybay,"extent"), heightmap = montereybay),
                        alphalayer=0.7) %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, start_transition = 0)) %>%
 add_shadow(ray_shade(montereybay,zscale=50),0) %>%
 plot_map()
}
if(run_documentation()) {
#Map one of the variables in the sf object and use an explicitly defined color palette
county_palette = c("087" = "red",    "053" = "blue",   "081" = "green", 
                  "069" = "yellow", "085" = "orange", "099" = "purple") 
montereybay %>%
 sphere_shade(texture = "bw") %>%
 add_shadow(ray_shade(montereybay,zscale=50),0) %>%
 add_overlay(generate_polygon_overlay(monterey_counties_sf, linecolor="white", linewidth=3,
                        palette = county_palette, data_column_fill = "COUNTYFP",
                        extent = attr(montereybay,"extent"), heightmap = montereybay),
                        alphalayer=0.7) %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, start_transition = 0)) %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.5) %>%
 plot_map()
}

Description

This function creates an overlay with a scale bar of a user-specified length. It uses the coordinates of the map (specified by passing an extent) and then creates a scale bar at a specified x/y proportion across the map. If the map is not projected (i.e. is in lat/long coordinates) this function will use the 'geosphere' package to create a scale bar of the proper length.

Usage

generate_scalebar_overlay(
  extent,
  length,
  x = 0.05,
  y = 0.05,
  latlong = FALSE,
  thickness = NA,
  bearing = 90,
  unit = "m",
  flip_ticks = FALSE,
  labels = NA,
  text_size = 1,
  decimals = 0,
  text_offset = 1,
  adj = 0.5,
  heightmap = NULL,
  width = NA,
  height = NA,
  resolution_multiply = 1,
  color1 = "white",
  color2 = "black",
  text_color = "black",
  font = 1,
  border_color = "black",
  tick_color = "black",
  border_width = 1,
  tick_width = 1,
  halo_color = NA,
  halo_expand = 1,
  halo_alpha = 1,
  halo_offset = c(0, 0),
  halo_blur = 1
)

Arguments

Value

Semi-transparent overlay with a scale bar.

Examples

if(run_documentation()) {
#Create the water palette
water_palette = colorRampPalette(c("darkblue", "dodgerblue", "lightblue"))(200)
bathy_hs = height_shade(montereybay, texture = water_palette)
#Set scalebar font
par(family = "Arial")

#Generate flat water heightmap
mbay = montereybay
mbay[mbay < 0] = 0

base_map = mbay %>%
height_shade() %>%
add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  %>%
add_shadow(lamb_shade(montereybay,zscale=50),0.3)

#For convenience, the extent of the montereybay dataset is included as an attribute
mb_extent = attr(montereybay, "extent")

#Add a scalebar
base_map %>%
add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 40000,
                                      heightmap = montereybay, 
                                      latlong=TRUE)) %>%
plot_map()
}
if(run_documentation()) {
#Change the text color
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 40000,
                                       text_color = "white",
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) {
#Change the length
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 30000,
                                       text_color = "white",
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) {
#Change the thickness (default is length/20)
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 30000,
                                       text_color = "white", thickness = 30000/10,
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) {
#Change the text offset (given in multiples of thickness)
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 30000,
                                       text_color = "white", thickness = 30000/10,
                                       text_offset = 0.75,
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) {
#Change the primary and secondary colors, along with the border and tick color
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 30000,
                                       text_color = "white", border_color = "white",
                                       tick_color = "white",
                                       color1 = "darkolivegreen4", color2 = "burlywood3",
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) {
#Add a halo
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 40000,
                                       halo_color = "white", halo_expand = 1,
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) {
#Change the orientation, position, text alignment, and flip the ticks to the other side
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 40000, x = 0.07,
                                       bearing=0, adj = 0, flip_ticks = TRUE,
                                       halo_color = "white", halo_expand = 1.5,
                                       heightmap = montereybay, 
                                       latlong=TRUE)) %>%
 plot_map()
}
if(run_documentation()) { 
#64373.8 meters in 40 miles
#Create custom labels, change font and text size, remove the border/ticks, and change the color
#Here, we specify a width and height to double the resolution of the image (for sharper text)
base_map %>%
 add_overlay(generate_scalebar_overlay(extent = mb_extent, length = 64373.8, x = 0.07,
                                       labels = c("0", "20", "40 miles"), thickness=2500,
                                       text_size=3, font = 2, text_offset = 0,
                                       text_color="white", color2="#bf323b", border_color=NA,
                                       tick_color="red", tick_width=0,
                                       bearing=0, adj = 0, flip_ticks = TRUE,
                                       halo_color="black", halo_blur=3, halo_alpha=0.5,
                                       width = ncol(montereybay)*2,
                                       height = nrow(montereybay)*2,
                                       latlong=TRUE), rescale_original=TRUE) %>%
 plot_map()
}

Description

Using a height map or a boolean matrix, generates a semi-transparent waterline overlay to layer onto an existing map. This uses the method described by P. Felzenszwalb & D. Huttenlocher in "Distance Transforms of Sampled Functions" (Theory of Computing, Vol. 8, No. 19, September 2012) to calculate the distance to the coast. This distance matrix can be returned directly by setting the 'return_distance_matrix' argument to 'TRUE'.

Usage

generate_waterline_overlay(
  heightmap,
  color = "white",
  linewidth = 1,
  boolean = FALSE,
  min = 0.001,
  max = 0.2,
  breaks = 9,
  smooth = 0,
  fade = TRUE,
  alpha_dist = max,
  alpha = 1,
  falloff = 1.3,
  evenly_spaced = FALSE,
  zscale = 1,
  cutoff = 0.999,
  width = NA,
  height = NA,
  resolution_multiply = 1,
  min_area = length(heightmap)/400,
  max_height = NULL,
  return_distance_matrix = FALSE
)

Arguments

Value

4-layer RGB array representing the waterline overlay.

Examples

if(run_documentation()) {
#Create a flat body of water for Monterey Bay
montbay = montereybay
montbay[montbay < 0] = 0

#Generate base map with no lines
basemap = montbay %>%
  height_shade() %>%
  add_water(detect_water(montbay), color="dodgerblue") %>%
  add_shadow(texture_shade(montbay, detail=1/3, brightness = 15, contrast = 5),0) %>%
  add_shadow(lamb_shade(montbay,zscale=50),0) 

plot_map(basemap)
}
if(run_documentation()) {
#Add waterlines
basemap %>% 
  add_overlay(generate_waterline_overlay(montbay)) %>% 
  plot_map()
}
if(run_documentation()) {
#Change minimum line distance:
basemap %>% 
  add_overlay(generate_waterline_overlay(montbay, min = 0.02)) %>% 
  plot_map()
}
if(run_documentation()) {
#Change maximum line distance
basemap %>% 
  add_overlay(generate_waterline_overlay(montbay, max = 0.4)) %>% 
  plot_map()
}
if(run_documentation()) {
#Smooth waterlines
basemap %>% 
  add_overlay(generate_waterline_overlay(montbay, max = 0.4, smooth=2)) %>% 
  plot_map()
}
if(run_documentation()) {
#Increase number of breaks
basemap %>% 
  add_overlay(generate_waterline_overlay(montbay, breaks = 20, max=0.4)) %>% 
  plot_map()
}
if(run_documentation()) {
#Make lines evenly spaced:
basemap %>% 
  add_overlay(generate_waterline_overlay(montbay, evenly_spaced = TRUE)) %>% 
  plot_map()
}
if(run_documentation()) {
#Change variable distance between each line
basemap %>% 
  add_overlay(generate_waterline_overlay(montbay, falloff=1.5)) %>% 
  plot_map()
}
if(run_documentation()) {
#Turn off fading
basemap %>% 
  add_overlay(generate_waterline_overlay(montbay, fade=FALSE)) %>% 
  plot_map()
}
if(run_documentation()) {
#Fill up the entire body of water with lines and make them all 50% transparent
basemap %>% 
  add_overlay(generate_waterline_overlay(montbay, fade=FALSE, max=1, alpha = 0.5, color="white",
                                         evenly_spaced = TRUE, breaks=50)) %>% 
  plot_map()
}

Description

Calculates a color for each point on the surface using a direct elevation-to-color mapping.

Usage

height_shade(
  heightmap,
  texture = (grDevices::colorRampPalette(c("#6AA85B", "#D9CC9A", "#FFFFFF")))(256),
  range = NULL,
  keep_user_par = TRUE
)

Arguments

Value

RGB array of hillshaded texture mappings.

Examples

#Create a direct mapping of elevation to color:
montereybay %>%
 height_shade() %>%
 plot_map()
 
#Add a shadow:
if(run_documentation()) {
montereybay %>%
 height_shade() %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 plot_map()
}

#Change the palette:
if(run_documentation()) {
montereybay %>%
 height_shade(texture = topo.colors(256)) %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 plot_map()
}

#Really change the palette:
if(run_documentation()) {
montereybay %>%
 height_shade(texture = rainbow(256)) %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 plot_map()
}

Description

Calculates local shadow map for a elevation matrix by calculating the dot product between light direction and the surface normal vector at that point. Each point's intensity is proportional to the cosine of the normal vector.

Usage

lamb_shade(
  heightmap,
  sunaltitude = 45,
  sunangle = 315,
  zscale = 1,
  zero_negative = TRUE
)

Arguments

Value

Matrix of light intensities at each point.

Examples

if(run_documentation()) {
#Generate a basic hillshade
montereybay %>% 
 lamb_shade(zscale=200) %>% 
 plot_map()
}
if(run_documentation()) {
#Increase the intensity by decreasing the zscale
montereybay %>% 
 lamb_shade(zscale=50) %>% 
 plot_map()
}
if(run_documentation()) { 
#Change the sun direction
montereybay %>% 
 lamb_shade(zscale=200, sunangle=45) %>% 
 plot_map()
}
if(run_documentation()) {
#Change the sun altitude
montereybay %>% 
 lamb_shade(zscale=200, sunaltitude=60) %>% 
 plot_map()
}

Description

This dataset is an 'sf' object containing polygon data from the U.S. Department of Commerce with selected geographic and cartographic information from the U.S. Census Bureau's Master Address File / Topologically Integrated Geographic Encoding and Referencing (MAF/TIGER) Database (MTDB). This data has been trimmed to only include 26 features in the extent of the 'montereybay' dataset.

Usage

monterey_counties_sf

Format

An 'sf' object with MULTIPOLYGON geometry.

Source

https://catalog.data.gov/dataset/tiger-line-shapefile-2016-state-california-current-county-subdivision-state-based

Examples

# This is the full code (commented out) used to generate this dataset from the original data:
#counties = sf::st_read("tl_2016_06_cousub.shp")
#monterey_counties_sf = sf::st_crop(counties, attr(montereybay,"extent"))

Description

This dataset is an 'sf' object containing line data from the U.S. Department of Commerce with selected roads, TIGER/Line Shapefile, 2015, state, California, Primary and Secondary Roads State-based Shapefile. This data has been trimmed to only include 330 features in the extent of the 'montereybay' dataset.

Usage

monterey_roads_sf

Format

An 'sf' object with LINESTRING geometry.

Source

https://www2.census.gov/geo/tiger/TIGER2015/PRISECROADS/tl_2015_06_prisecroads.zip

Examples

# This is the full code (commented out) used to generate this dataset from the original data:
#counties = sf::st_read("tl_2015_06_prisecroads.shp")
#monterey_roads_sf = sf::st_crop(counties, attr(montereybay,"extent"))

Description

This dataset is a downsampled version of a combined topographic and bathymetric elevation matrix representing the Monterey Bay, CA region. Original data from from the NOAA National Map website.

Usage

montereybay

Format

A matrix with 540 rows and 540 columns. Elevation is in meters, and the spacing between each coordinate is 200 meters (zscale = 200). Water level is 0. Raster extent located in "extent" attribute. CRS located in "CRS" attribute.

Source

https://www.ncei.noaa.gov/metadata/geoportal/rest/metadata/item/gov.noaa.ngdc.mgg.dem:3544/html

Examples

# This is the full code (commented out) used to generate this dataset from the original NOAA data:
#raster::raster("monterey_13_navd88_2012.nc")
#bottom_left = c(y=-122.366765, x=36.179392)
#top_right   = c(y=-121.366765, x=37.179392) 
#extent_latlong = sp::SpatialPoints(rbind(bottom_left, top_right), 
#                 proj4string=sp::CRS("+proj=longlat +ellps=WGS84 +datum=WGS84"))
#monterey_cropped = raster::crop(montbay,extent_latlong)
#montbay_mat = raster_to_matrix(montbay_cropped)
#montereybay = resize_matrix(montbay_mat,0.05)
#attr(montereybay, "extent") = extent_latlong
#attr(montereybay, "crs") = crs(monterey_cropped)
#attr(montereybay, "crs") = crs(monterey_cropped)
#attr(montereybay, "rayshader_data") = TRUE

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

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

Description

Plots a ggplot2 object in 3D by mapping the color or fill aesthetic to elevation.

Currently, this function does not transform lines mapped to color into 3D.

If there are multiple legends/guides due to multiple aesthetics being mapped (e.g. color and shape), the package author recommends that the user pass the order of the guides manually using the ggplot2 function "guides()'. Otherwise, the order may change when processing the ggplot2 object and result in a mismatch between the 3D mapping and the underlying plot.

Using the shape aesthetic with more than three groups is not recommended, unless the user passes in custom, solid shapes. By default in ggplot2, only the first three shapes are solid, which is a requirement to be projected into 3D.

Usage

plot_gg(
  ggobj,
  ggobj_height = NULL,
  width = 3,
  height = 3,
  height_aes = NULL,
  invert = FALSE,
  shadow_intensity = 0.5,
  units = c("in", "cm", "mm"),
  scale = 150,
  pointcontract = 0.7,
  offset_edges = FALSE,
  flat_plot_render = FALSE,
  flat_distance = "auto",
  flat_transparent_bg = FALSE,
  flat_direction = "-z",
  shadow = TRUE,
  shadowdepth = "auto",
  shadowcolor = "auto",
  shadow_darkness = 0.5,
  background = "white",
  preview = FALSE,
  raytrace = TRUE,
  sunangle = 315,
  anglebreaks = seq(30, 40, 0.1),
  multicore = FALSE,
  lambert = TRUE,
  triangulate = TRUE,
  max_error = 0.001,
  max_tri = 0,
  verbose = FALSE,
  emboss_text = 0,
  emboss_grid = 0,
  reduce_size = NULL,
  save_height_matrix = FALSE,
  save_shadow_matrix = FALSE,
  saved_shadow_matrix = NULL,
  ...
)

Arguments

Value

Opens a 3D plot in rgl.

Examples

library(ggplot2)
library(viridis)


ggdiamonds = ggplot(diamonds, aes(x, depth)) +
 stat_density_2d(aes(fill = after_stat(nlevel)), geom = "polygon", 
                 n = 200, bins = 50,contour = TRUE) +
 facet_wrap(clarity~.) +
 scale_fill_viridis_c(option = "A")
if(run_documentation()) {
plot_gg(ggdiamonds,multicore = TRUE,width=5,height=5,scale=250,windowsize=c(1400,866),
       zoom = 0.55, phi = 30)
render_snapshot()
}
#Change the camera angle and take a snapshot:
if(run_documentation()) {
render_camera(zoom=0.5,theta=-30,phi=30)
render_snapshot()
}

#Contours and other lines will automatically be ignored. Here is the volcano dataset:
ggvolcano = volcano %>% 
 reshape2::melt() %>%
 ggplot() +
 geom_tile(aes(x=Var1,y=Var2,fill=value)) +
 geom_contour(aes(x=Var1,y=Var2,z=value),color="black") +
 scale_x_continuous("X",expand = c(0,0)) +
 scale_y_continuous("Y",expand = c(0,0)) +
 scale_fill_gradientn("Z",colours = terrain.colors(10)) +
 coord_fixed() + 
 theme(legend.position = "none")
ggvolcano

if(run_documentation()) {
plot_gg(ggvolcano, multicore = TRUE, raytrace = TRUE, width = 7, height = 4, 
       scale = 300, windowsize = c(1400, 866), zoom = 0.6, phi = 30, theta = 30)
render_snapshot()
}

if(run_documentation()) {
#You can specify the color and height separately using the `ggobj_height()` argument.
ggvolcano_surface = volcano %>%
reshape2::melt() %>%
 ggplot() +
 geom_contour(aes(x=Var1,y=Var2,z=value),color="black") +
 geom_contour_filled(aes(x=Var1,y=Var2,z=value))+
 scale_x_continuous("X",expand = c(0,0)) +
 scale_y_continuous("Y",expand = c(0,0)) +
 coord_fixed() +
 theme(legend.position = "none")

plot_gg(ggvolcano_surface, ggobj_height = ggvolcano, 
      multicore = TRUE, raytrace = TRUE, width = 7, height = 4,
      scale = 300, windowsize = c(1400, 866), zoom = 0.6, phi = 30, theta = 30)
render_snapshot()
}
#Here, we will create a 3D plot of the mtcars dataset. This automatically detects 
#that the user used the `color` aesthetic instead of the `fill`.
mtplot = ggplot(mtcars) + 
 geom_point(aes(x=mpg,y=disp,color=cyl)) + 
 scale_color_continuous(limits=c(0,8)) 

#Preview how the plot will look by setting `preview = TRUE`: We also adjust the angle of the light.
if(run_documentation()) {
plot_gg(mtplot, width=3.5, sunangle=225, preview = TRUE)
}
if(run_documentation()) {
plot_gg(mtplot, width=3.5, multicore = TRUE, windowsize = c(1400,866), sunangle=225,
       zoom = 0.60, phi = 30, theta = 45)
render_snapshot()
}
#Now let's plot a density plot in 3D.
mtplot_density = ggplot(mtcars) + 
 stat_density_2d(aes(x=mpg,y=disp, fill=after_stat(!!str2lang("density"))), 
                 geom = "raster", contour = FALSE) +
 scale_x_continuous(expand=c(0,0)) +
 scale_y_continuous(expand=c(0,0)) +
 scale_fill_gradient(low="pink", high="red")
mtplot_density

if(run_documentation()) {
plot_gg(mtplot_density, width = 4,zoom = 0.60, theta = -45, phi = 30, 
       windowsize = c(1400,866))
render_snapshot()
}
#This also works facetted.
mtplot_density_facet = mtplot_density + facet_wrap(~cyl) 

#Preview this plot in 2D:
if(run_documentation()) {
plot_gg(mtplot_density_facet, preview = TRUE)
}
if(run_documentation()) {
plot_gg(mtplot_density_facet, windowsize=c(1400,866),
       zoom = 0.55, theta = -10, phi = 25)
render_snapshot()
}
#That is a little cramped. Specifying a larger width will improve the readability of this plot.
if(run_documentation()) {
plot_gg(mtplot_density_facet, width = 6, preview = TRUE)
}

#That's better. Let's plot it in 3D, and increase the scale.
if(run_documentation()) {
plot_gg(mtplot_density_facet, width = 6, windowsize=c(1400,866),
       zoom = 0.55, theta = -10, phi = 25, scale=300)
render_snapshot()
}

#We can also render a flat version of the plot alongside (or above/below) the 3D version.
if(run_documentation()) {
plot_gg(mtplot_density_facet, width = 6, windowsize=c(1400,866),
       zoom = 0.65, theta = -25, phi = 35, scale=300, flat_plot_render=TRUE,
       flat_direction = "x")
render_snapshot()
}

Description

Displays the map in the current device.

Usage

plot_map(
  hillshade,
  rotate = 0,
  asp = 1,
  title_text = NA,
  title_offset = c(20, 20),
  title_color = "black",
  title_size = 30,
  title_font = "sans",
  title_style = "normal",
  title_bar_color = NULL,
  title_bar_alpha = 0.5,
  title_position = "northwest",
  ...
)

Arguments

Examples

#Plotting the Monterey Bay dataset with bathymetry data
if(run_documentation()) {
water_palette = colorRampPalette(c("darkblue", "dodgerblue", "lightblue"))(200)
bathy_hs = height_shade(montereybay, texture = water_palette)
#For compass text
par(family = "Arial")

#Set everything below 0m to water palette
montereybay %>%
 sphere_shade(zscale=10) %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 plot_map()
}
#Correcting the aspect ratio for the latitude of Monterey Bay

extent_mb = attr(montereybay,"extent")
mean_latitude = mean(c(extent_mb@ymax,extent_mb@ymin))
if(run_documentation()) {
montereybay %>%
 sphere_shade(zscale=10) %>%
 add_overlay(generate_altitude_overlay(bathy_hs, montereybay, 0, 0))  %>%
 add_shadow(ray_shade(montereybay,zscale=50),0.3) %>%
 plot_map(asp = 1/cospi(mean_latitude/180))
}