--- title: "Introduction to ggcube" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Introduction to ggcube} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 5, dpi = 150, warning = FALSE, message = FALSE ) ``` ggcube is a ggplot2 extension for 3D plotting. It provides 3D geoms, stats, and a 3D coordinate system that let you build 3D visualizations using the familiar ggplot2 grammar: map your data to aesthetics, add layers, and customize the result with scales, guides, and themes. ```{r setup, message = FALSE} library(ggcube) ``` ## The basics The essential ingredient of a ggcube plot is `coord_3d()`. Adding it to a standard ggplot that includes a `z` aesthetic creates a 3D plot: ```{r basics} ggplot(mpg, aes(x = displ, y = hwy, z = drv, color = class)) + geom_point() + coord_3d() ``` Some standard ggplot2 layers like `geom_point()` work in 3D automatically. ggcube also provides 3D-specific layer functions for surfaces, paths, volumes, and text, described below. Because ggcube works within ggplot2's 2D graphics engine, there are some important things to understand about how rendering works. Each 3D layer projects its geometry onto a 2D plane, with depth sorting to determine which elements appear in front of others. This sorting happens *within* each layer, but not *across* layers — just as in standard ggplot2, later layers are drawn on top of earlier ones regardless of their 3D depth. This means that layer order in your code matters, and complex multi-layer scenes may require some thought about stacking. ## Controlling the view `coord_3d()` controls how the 3D scene is projected onto 2D. Rotation is specified via three angles --- `pitch` (tilt around the x-axis), `roll` (tilt around the y-axis), and `yaw` (spin around the z-axis): ```{r rotation, fig.height = 4} 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)) ``` Perspective projection is on by default, making distant objects appear smaller. The `dist` parameter controls the strength of this effect (larger values = less distortion), and `persp = FALSE` switches to orthographic projection where parallel lines stay parallel. The `scales` parameter controls how axis ranges map to visual size. `"free"` (the default) stretches each axis independently to fill the cube, while `"fixed"` preserves the relative scale of the data (like `coord_fixed()` in 2D). The `ratio` parameter lets you set custom proportions for the three axes. And `zoom` adjusts overall framing without changing the rotation or projection. See the [3D view](https://matthewkling.github.io/ggcube/articles/coord_3d.html) article for a comprehensive guide to all view parameters. ## 3D layers Most standard ggplot2 geoms are designed around 2D coordinate assumptions, and won't render correctly with `coord_3d()`. (An exception is `geom_point()`, which works out of the box as shown above, albeit with ordering and sizing limitations.) ggcube provides a range of 3D-native layer functions that cover common 3D plot types, including points, surfaces, bars, paths, and text. Here's a quick tour of the main categories. ### Surfaces Several geoms and stats work together to render surfaces. `geom_surface_3d()` renders data as a tessellated surface, `geom_contour_3d()` creates layer-cake contour stacks, and `geom_ridgeline_3d()` shows cross-sectional slices: ```{r surface} ggplot(mountain, aes(x, y, z)) + geom_surface_3d(aes(fill = z, color = z)) + scale_fill_viridis_c() + scale_color_viridis_c() + coord_3d(ratio = c(1.5, 2, 1), expand = FALSE, panels = "zmin", light = light(direction = c(1, 0, 0))) + guides(fill = guide_colorbar_3d()) + theme_light() ``` Stats like `stat_function_3d()`, `stat_smooth_3d()`, and `stat_density_3d()` generate surface data from functions, model fits, or kernel density estimates. These stats can be paired with any of the surface geoms. See the [3D surfaces](https://matthewkling.github.io/ggcube/articles/surfaces.html) article for more detail on surface plotting options. ### Points `geom_point_3d()` extends scatter plots with depth-scaled point sizes (closer points shown larger), proper depth sorting (closer points plotted on top), and optional reference lines and points that project onto cube faces: ```{r points} ggplot(mpg, aes(x = displ, y = hwy, z = drv, fill = class)) + geom_point_3d(size = 3, shape = 21, color = "black", stroke = .1, ref_lines = TRUE, ref_faces = c("ymax", "xmax")) + coord_3d() ``` ### Paths `geom_path_3d()` connects observations with depth-sorted, depth-scaled line segments: ```{r paths} x <- seq(0, 20*pi, pi/16) spiral <- data.frame(x = x, y = sin(x), z = cos(x), time = 1:length(x)) ggplot(spiral, aes(x, y, z, color = time)) + geom_path_3d() + scale_color_gradientn(colors = c("blue", "purple", "red", "orange")) + coord_3d() + theme_light() ``` `geom_segment_3d()` is also available for drawing individual segments defined by start and end coordinates. ### Prisms `geom_col_3d()` produces 3D column charts, `geom_bar_3d()` creates 3D histograms with automatic binning, and `geom_voxel_3d()` renders arrays of cubes: ```{r bar} ggplot(iris, aes(Species, Sepal.Length, fill = Species)) + geom_bar_3d(bins = 20, width = c(.5, 1)) + coord_3d(scales = "fixed", ratio = c(1, 3, .25), yaw = 60) + scale_z_continuous(expand = c(0, 0)) + theme(legend.position = "none") ``` ### Hulls `geom_hull_3d()` computes and renders triangulated hulls from 3D point clouds, including convex and alpha hulls: ```{r hull} ggplot(sphere_points, aes(x, y, z)) + geom_hull_3d(method = "convex", fill = "#9e2602", color = "#5e1600") + coord_3d() ``` ### Distributions `stat_distributions_3d()` computes 1D kernel density estimates per group and arranges them as ridgeline surfaces, the 3D analog of `ggridges::geom_density_ridges()`: ```{r distributions} ggplot(iris, aes(y = Sepal.Length, x = Species, fill = Species)) + stat_distributions_3d() + scale_z_continuous(expand = expansion(mult = c(0, NA))) + coord_3d() + theme(legend.position = "none") ``` ### Text `geom_text_3d()` renders text in 3D, either as "billboard" labels that always face the camera, or as polygon outlines that can be oriented in any direction: ```{r text} df <- expand.grid(x = c("H", "B"), 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", light = NULL) ``` ## Lighting Lighting modifies the fill and/or color of polygon faces based on their orientation relative to a light source, giving surfaces a sense of depth and shape. It's controlled via the `light()` function, which can be passed to `coord_3d()` (applying to all layers) or to individual layer functions (overriding the coord-level setting): ```{r lighting} p <- ggplot(sphere_points, aes(x, y, z)) + geom_hull_3d(fill = "#9e2602", color = "#5e1600") p + coord_3d(light = light(method = "direct", mode = "hsl", direction = c(0, 0, 1))) ``` Use `light = "none"` to disable lighting entirely, or `light = NULL` in a layer to inherit the coord-level setting. For a comprehensive guide to lighting methods, color modes, light direction, and backface handling, see the [lighting](https://matthewkling.github.io/ggcube/articles/lighting.html) article. ## Scales, guides, and themes ### Z-axis scales ggcube provides `scale_z_continuous()` and `scale_z_discrete()` for controlling the z-axis, with the same interface as their x/y counterparts. `zlim()` is a shorthand for setting z-axis limits: ```{r zlim, fig.show = "hide"} ggplot(mtcars, aes(mpg, wt, z = qsec)) + geom_point() + zlim(15, 20) + coord_3d() ``` ### Shaded guides When lighting is active, standard color guides don't reflect the shading visible in the plot. `guide_colorbar_3d()` and `guide_legend_3d()` create guides that show the range of shaded colors: ```{r guide, fig.show = "hide"} ggplot(mountain, aes(x, y, z, fill = z)) + stat_surface_3d(light = light(mode = "hsl", direction = c(1, 0, 0))) + guides(fill = guide_colorbar_3d()) + scale_fill_gradientn(colors = c("tomato", "dodgerblue")) + coord_3d() ``` ### Panels and themes The `panels` argument to `coord_3d()` controls which cube faces are drawn. Faces behind the data are "background" panels; faces in front are "foreground" panels (which default to semi-transparent so they don't obscure the data): ```{r theme} ggplot(sphere_points, aes(x, y, z)) + geom_hull_3d() + coord_3d(panels = "all") + theme(panel.background = element_rect(color = "black"), panel.border = element_rect(color = "black"), panel.foreground = element_rect(alpha = .3), panel.grid.foreground = element_line(color = "gray", linewidth = .25), axis.text = element_text(color = "darkblue"), axis.text.z = element_text(color = "darkred"), axis.title = element_text(margin = margin(t = 30)), axis.title.x = element_text(color = "magenta")) ``` Standard ggplot2 themes and `theme()` customization work as expected. ggcube adds foreground-specific elements (`panel.foreground`, `panel.grid.foreground`, `panel.border.foreground`) and z-axis text elements (`axis.text.z`, `axis.title.z`). ggcube's `element_rect()` extends ggplot2's version with an `alpha` parameter for transparency. For details, see the theming section of the [3D coordinates](https://matthewkling.github.io/ggcube/articles/coord_3d.html) article. ## Annotations `annotate_3d()` adds reference geometry --- points, text labels, or segments --- to any 3D layer. Unlike adding a separate layer, annotations are embedded within the host layer so they participate in the same depth sorting: ```{r annotate, eval = FALSE} summit <- filter(mountain, z == max(z)) ggplot(mountain, aes(x, y, z)) + geom_contour_3d( annotate = list( annotate_3d("point", x = summit$x, y = summit$y, z = summit$z, color = "red"), annotate_3d("text", x = summit$x, y = summit$y, z = summit$z, color = "red", label = "Summit", fontface = "bold", vjust = -1) ), fill = "black" ) + coord_3d(ratio = c(2, 3, 1.5), light = "none") ``` ## Mixing 2D and 3D `position_on_face()` lets you project layers onto cube faces, enabling a mix of 3D and 2D content. You can flatten a 3D layer onto a face, or place a natively 2D layer (like `stat_density_2d()`) onto a specific face using the `axes` parameter: ```{r face_projection} ggplot(iris, aes(Sepal.Length, Sepal.Width, Petal.Length, color = Species, fill = Species)) + coord_3d() + xlim(4, 8) + stat_density_2d(position = position_on_face(faces = "zmin", axes = c("x", "y")), geom = "polygon", alpha = .1, linewidth = .25) + geom_hull_3d(position = position_on_face("ymax"), alpha = .5) + geom_point_3d(shape = 21, color = "black", stroke = .25) ``` ## Animation `animate_3d()` creates animated rotations of any ggcube plot. Rotation angles are specified as keyframe vectors that get interpolated across frames: ```{r animation, eval = FALSE} p <- ggplot(mountain, aes(x, y, z)) + geom_contour_3d(fill = "black", color = "white", linewidth = .5) + coord_3d(ratio = c(1.5, 2, 1), light = "none", zoom = 1.5) + theme_void() animate_3d(p, yaw = c(0, 360)) ``` Output format is controlled via renderers: `gifski_renderer_3d()` (GIF, the default), `av_renderer_3d()` (MP4), or `file_renderer_3d()` (individual frames). Use `anim_save_3d()` to save the result to a file.