How Does rayshader Work?

The core idea: elevation matrix → shade → render

• Input — a matrix of numeric values (elevation, density, anything)
• sphere_shade() — applies color texture simulating how light hits a sphere
• ray_shade() — calculates where a sun-like light source casts shadows
• ambient_shade() — darkens crevices where light gets trapped
• plot_map() — renders everything as a flat 2D image
• plot_3d() — projects the surface into an interactive 3D scene
• plot_gg() — takes any ggplot2 object and renders it in 3D

Demo 1: The Built-in volcano Dataset

R ships with volcano — an 87×61 matrix of elevation values from New Zealand

library(rayshader)

# volcano is a built-in dataset
volcano_map <- volcano |>
  sphere_shade(texture = "desert") |>
  add_shadow(ray_shade(volcano), 0.5) |>
  add_shadow(ambient_shade(volcano), 0)

# 2D flat render
plot_map(volcano_map)

# 3D interactive render
plot_3d(volcano_map, volcano, zscale = 2, zoom = 0.75, phi = 45, theta = 45)

# phi is the vertical angle, theta is the horizontal rotation

Demo 2: Turning a ggplot into 3D

Any ggplot2 object can be rendered in 3D with just one extra function 📊

library(rayshader)
library(ggplot2)

gg <- ggplot(faithful, aes(x = eruptions, y = waiting)) +
  stat_density_2d(aes(fill = after_stat(density)), 
                  geom = "raster", 
                  contour = FALSE) +
  scale_fill_viridis_c() +
  labs(title = "Old Faithful Geyser Eruptions",
       x = "Eruption Duration (mins)",
       y = "Wait Time (mins)")

plot_gg(gg, width = 3, height = 3, scale = 200, zoom = 0.6, phi = 35, theta = 30)
render_snapshot("images/ggplot_3d.png")

Where can rayshader be Used?

• Geography & Science — visualizing real elevation data from anywhere on Earth, seafloor topology, geological terrain analysis
• Urban Planning — rendering city elevation models to visualize how buildings affect wind and shadow patterns
• Data Journalism — news outlets use 3D maps to visualize flood zones, wildfire spread, or population density
• Game Development — generating and previewing heightmaps, the exact same concept used in open world terrain generation
• Any ggplot — if your data has a natural height dimension, plot_gg() makes it instantly more readable