ggcube lets you build 3D figures using ggplot2. Use it to create 3D surfaces, volumes, scatter plots, and complex layered visualizations using familiar ggplot2 syntax with aes(x, y, z) and coord_3d().

The package provides a variety of 3D-specific geoms to render surfaces, prisms, points, paths, and text in 3D; it also works with some standard ggplot2 layer functions. All 3D layers in a panel are depth-sorted together, so surfaces, points, lines, and text from different layers occlude each other correctly. You can control plot geometry with 3D projection parameters, apply a range of 3D lighting models, and mix 3D layers with 2D layers rendered on cube faces. Standard ggplot2 features like faceting, themes, scales, and legends work as expected.
3D plots are wonderful for exploration, storytelling, and data art. But note that for precise quantitative communication, where occlusion and perspective distortion can be problematic, 2D is usually the better choice.
Installation
# You can install the package from CRAN:
install.packages("ggcube")
# Or get the development version from GitHub:
devtools::install_github("matthewkling/ggcube")Quick start
The essential ingredient of a ggcube plot is coord_3d(). Adding this to a standard ggplot, and providing a z aesthetic variable, creates a 3D plot:
library(ggplot2)
library(ggcube)
# Basic 3D scatter plot
ggplot(mpg, aes(x = displ, y = hwy, z = drv, color = class)) +
geom_point() +
coord_3d()
You can control plot rotation, perspective, and dimensions, as well as axis label placement and panel selection, via parameters to coord_3d(). See the 3D view article for a comprehensive guide.
ggplot(mpg, aes(displ, hwy, drv, color = class)) +
geom_point() +
coord_3d(pitch = 0, roll = 60, yaw = 0, dist = 1.4,
ratio = c(2, 1, 1), panels = "all") +
theme(panel.border = element_rect(color = "black"),
panel.foreground = element_rect(alpha = .1))
3D surfaces
ggcube’s surface layer functions draw terrain-like figures with a z value for every combination of x and y:
-
geom_surface_3d()renders surfaces based on existing grid data such as topography -
geom_ridgeline_3d()renders surfaces as a series of cross-sections -
geom_contour_3d()renders surfaces as layer cakes of stacked contours -
geom_function_3d()visualizes mathematical functions -
geom_smooth_3d()fits statistical models with two predictors and visualizes fitted surfaces with confidence intervals -
geom_density_3d()creates perspective visualizations of 2D kernel density estimates -
geom_plane_3d()draws flat planes at arbitrary orientations
See the surfaces article for a full guide to surface options.
Example: a terrain surface using geom_surface_3d():
ggplot(mountain, aes(x, y, z)) +
geom_surface_3d(aes(fill = z)) +
scale_fill_viridis_c() +
coord_3d(ratio = c(1.5, 2, 1), expand = FALSE, panels = "zmin") +
theme_light()
Example: a terrain surface using geom_contour_3d():
ggplot(mountain, aes(x, y, z)) +
geom_contour_3d(fill = "black", color = "white", linewidth = .5) +
coord_3d(yaw = 60, ratio = c(1.5, 2, 1)) +
theme_void()
Example: a mathematical surface using geom_function_3d():
ggplot() +
geom_function_3d(fun = function(x1, x2) cos(x1) * sin(x2),
xlim = c(-pi, pi), ylim = c(-2*pi, 2*pi),
fill = "#7a2100", color = "#b3725b",
grid = "right1", linewidth = .2) +
coord_3d(yaw = 160, roll = -70,
scales = "fixed", ratio = c(1, 1, 2)) +
labs(x = expression(x[1]),
y = expression(x[2]),
z = expression(cos(x[1]) %*% sin(x[2]))) +
theme_minimal()
Example: a fitted model surface using geom_smooth_3d(), with the data points depth-sorted among the fitted and confidence surfaces:
# Generate scattered 3D data
set.seed(123)
d <- data.frame(x = rnorm(200),
y = rnorm(200))
d$z <- d$x + d$x^2 - d$y^2 + rnorm(200)
# Plot GAM fit with uncertainty layers
ggplot(d, aes(x, y, z)) +
geom_smooth_3d(aes(fill = after_stat(level)),
method = "gam", formula = z ~ te(x, y),
se = TRUE, level = 0.99,
color = "black", grid = "equilateral") +
geom_point_3d() +
scale_fill_manual(values = c("red", "darkorchid4", "steelblue")) +
coord_3d(light = "none")
3D volumes
This family of layers draws the boundaries of regions in 3D space, which can fold, nest, and close on themselves:
-
geom_hull_3d()plots triangulated volumes based on convex or alpha hulls of 3D points -
geom_isodensity_3d()estimates the density of 3D points, and draws surfaces enclosing given fractions of it -
geom_isosurface_3d()draws isosurfaces of a 3D field, the 3D analog of contour lines, e.g. of a function of three variables -
geom_isofunction_3d()draws isosurfaces of a function of three variables
See the volumes article for more details.
gyroid <- function(x, y, z) sin(x) * cos(y) + sin(y) * cos(z) + sin(z) * cos(x)
ggplot() +
geom_isofunction_3d(
fun = gyroid, cap = TRUE, fill = "darkorchid", n = 60,
xlim = c(0, 4 * pi), ylim = c(0, 4 * pi), zlim = c(0, 4 * pi)) +
coord_3d() +
theme_void() +
light(highlight = .8, shadow = 1)
3D lines
Line geoms render paths in 3D space with depth-based sorting and scaling, including geom_segment_3d() and geom_path_3d():
butterfly <- ggcube:::lorenz_attractor(n_points = 8000, dt = .01)
ggplot(butterfly, aes(x, y, z, color = time)) +
geom_path_3d(linewidth = 0.1, color = "black",
position = position_on_face(c("xmax", "ymax", "zmin"))) +
geom_path_3d(linewidth = 0.3) +
scale_color_gradientn(colors = c("blue", "purple", "red", "orange")) +
coord_3d() +
theme_light()
3D points
While ggplot2::geom_point() works with ggcube as demonstrated above, geom_point_3d() creates 3D-aware scatter plots with proper point ordering and depth-scaled point sizes. geom_dropline_3d() and position_on_face() add drop lines and reference points projecting 3D points onto 2D face panels:
ggplot(mpg, aes(x = displ, y = hwy, z = drv, fill = class)) +
geom_dropline_3d(faces = c("ymax", "xmax")) +
geom_point_3d(position = position_on_face(c("ymax", "xmax")), flat = TRUE,
size = 3, shape = 21, stroke = .1, alpha = .5, show.legend = FALSE) +
geom_point_3d(size = 3, shape = 21, color = "black", stroke = .1) +
coord_3d()
3D prisms
-
geom_col_3d()produces 3D column charts -
geom_bar_3d()creates 3D histograms of 2D discrete or continuous variables -
geom_voxel_3d()renders sparse 3D pixel data as arrays of cubes
Example: a 3D histogram using geom_bar_3d():
ggplot(faithful, aes(waiting, eruptions)) +
geom_bar_3d(fill = "steelblue", bins = 15, width = .9) +
coord_3d(yaw = 60) +
scale_z_continuous(expand = c(0, 0))
3D text
geom_text_3d() creates 3D-aware text, rendered either as "billboard" text that faces the viewing plane or as 3D "polygon" text that can face any direction:
df <- expand.grid(x = c("B", "H", "N"), y = c("a", "o", "u"), z = c("g", "t"))
df$label <- paste0(df$x, df$y, df$z)
ggplot(df, aes(x, y, z, label = label, fill = x)) +
geom_text_3d(method = "polygon", facing = "zmax",
size = 5, weight = "bold") +
coord_3d(scales = "fixed", rotate_labels = FALSE) +
theme(axis.title = element_blank())
Annotations and reference geometry
annotate_3d() adds points, text, segments, polygons, and other reference geometry at fixed positions, like ggplot2’s annotate(). Reference geometry that spans the panel has its own layer functions: geom_plane_3d() draws planes, geom_refline_3d() infinite lines, and geom_axes_3d() axes through an origin, while geom_dropline_3d() drops lines from points to the panel’s faces. These are all depth-sorted with the rest of the scene, which makes ggcube handy for diagrams:
u <- c(1, .2, .4); v <- c(.3, 1, .7)
vecs <- data.frame(xend = c(u[1], v[1]), yend = c(u[2], v[2]), zend = c(u[3], v[3]),
label = c("u", "v"))
ggplot(vecs, aes(0, 0, 0, xend = xend, yend = yend, zend = zend)) +
annotate_3d("polygon", x = c(0, u[1], v[1]), y = c(0, u[2], v[2]),
z = c(0, u[3], v[3]), fill = "steelblue") +
geom_plane_3d(zintercept = .3, fill = "tomato", alpha = .4) +
geom_axes_3d() +
geom_segment_3d(arrow = arrow(type = "closed", length = unit(8, "pt")),
linewidth = 1) +
geom_text_3d(aes(xend * 1.1, yend * 1.1, zend * 1.1, label = label),
size = 6, on_top = TRUE) +
xlim(-.25, 1.1) + ylim(-.25, 1.1) + zlim(-.25, 1.1) +
coord_3d(panels = "none") +
theme_void()
Lighting effects
Lighting of 3D polygon layers is controlled by adding a light() specification to the plot, or providing it to the light parameter of a layer function or coord_3d(). See the lighting and shading article for a comprehensive guide.
# a unit sphere, centered at x = x0
sphere <- function(x0 = 0, ...) {
geom_isofunction_3d(fun = function(x, y, z) (x - x0)^2 + y^2 + z^2 - 1,
xlim = x0 + c(-1.1, 1.1), ylim = c(-1.1, 1.1), zlim = c(-1.1, 1.1),
n = 40, ...)
}
ggplot() +
coord_3d(scales = "fixed") +
scale_fill_viridis_c() +
theme_dark() +
theme(legend.position = "none") +
# apply shading to solid fill, with a specular highlight for shininess
sphere(fill = "#8a2900",
light = light("hard", specular = 1, specular_size = 10)) +
# apply shading to aesthetic fill
sphere(x0 = 2.5, mapping = aes(fill = after_stat(x)),
light = light(direction = c(0, -1, 0), anchor = "scene")) +
# map surface orientation to 3D RGB color channels
sphere(x0 = 5, light = light(tone = "normals", direction = c(1, 0, -1), anchor = "scene"))
Animation and interaction
A major limitation of 3D figures is that you can’t get a full view of the data from any single angle. One way to mitigate this is by rotating the figure to view the data from different directions. ggcube offers animated rotation via animate_3d(), and interactive drag-to-rotate plots via orbit_3d(). You can also render a plot from multiple views using facet_wrap_views() or facet_grid_views(). See the animation, orbits, and multiple views article for details. Here’s an example of a rotating gif:
mammoth <- data.frame(do.call(rbind, rjson::fromJSON(
file = paste0("https://raw.githubusercontent.com/PAIR-code/",
"understanding-umap/master/raw_data/mammoth_3d_50k.json")
)))
colnames(mammoth) <- c("Y", "X", "Z")
p <- ggplot(mammoth, aes(X, Y, Z)) +
geom_hull_3d(method = "alpha", radius = 8, fill = "red") +
light(direction = c(-1, 1, 0), shadow = 1, highlight = 1) +
coord_3d(roll = -90, scales = "fixed",
panels = "zmin", expand = FALSE) +
theme(axis.text = element_blank(),
axis.ticks = element_blank(),
axis.title = element_blank())
animate_3d(p, yaw = c(0, 360), nframes = 72, fps = 8, width = 700, cores = 8)
Face projection
3D and 2D layers can be mixed by using position_on_face() to project data onto 2D cube faces. We saw this in the geom_path_3d() example above, but here’s another example that mixes different geoms, including natively-2D layers like ggplot2::stat_density_2d():
ggplot(iris, aes(Sepal.Length, Sepal.Width, Petal.Length,
color = Species, fill = Species)) +
coord_3d() + xlim(4, 8) +
# place 2D density plot on zmin face
stat_density_2d(position = position_on_face(faces = "zmin", axes = c("x", "y")),
geom = "polygon", alpha = .1, linewidth = .25) +
# flatten 3D hull layer onto ymax face
geom_hull_3d(position = position_on_face("ymax"), alpha = .5) +
# flatten 3D voxels onto xmax face to create 2D bins
geom_voxel_3d(aes(round(Sepal.Length), round(Sepal.Width), round(Petal.Length)),
position = position_on_face("xmax"), alpha = .15, light = NULL) +
# 3D scatter plot
geom_point_3d(shape = 21, color = "black", stroke = .25)
Related packages
R has several other tools for 3D visualization. ggcube is designed for users who want to stay within the ggplot2 ecosystem. Other packages offer different tradeoffs:
- plotly and rgl provide interactive 3D viewers with rotation and zoom via WebGL/OpenGL, using their own APIs.
- rayshader produces ray-traced renderings of terrain data with photorealistic lighting and shadows; it also makes 3D popups of ggplot2 figures, but not 3D ggplots per se.
- gg3D was another ggplot2 extension for 3D plotting, but is no longer actively maintained.
Learn more
- The getting started vignette gives a tour of the main features.
- The 3D view, surfaces, and lighting and shading articles go deeper on those topics.
- The function reference documents every exported function.
