Package 'ggcube'

Description

This function extends ggplot2::aes() to support positional mapping to the z aesthetic. It maintains full backward compatibility with the original aes() function while enabling the convenient aes(x, y, z) syntax for 3D plots.

Usage

aes(x, y, z, ...)

Arguments

Details

This function is a lightweight wrapper around ggplot2::aes() that:

• Maintains full backward compatibility with existing 2D plots

• Enables positional z mapping: aes(x_var, y_var, z_var)

• Works with any geom that uses the z aesthetic (contour, raster, 3D plots)

• Passes through all other aesthetics unchanged

Value

An aesthetic mapping object, same as ggplot2::aes()

See Also

aes for the original aesthetic mapping function, coord_3d for 3D coordinate systems

Examples

library(ggplot2)

# 2D plots work like regular ggplot2
ggplot(mtcars, aes(mpg, wt)) + geom_point()

# 3D plots can use positional syntax, or explicitly map to z
# same as: ggplot(mtcars, aes(mpg, wt, z = qsec)) + geom_point() + coord_3d()
ggplot(mtcars, aes(mpg, wt, qsec)) + geom_point() + coord_3d()

# Also works with non-ggcube z-aesthetic geoms
ggplot(mountain, aes(x, y, z)) + geom_contour()

Description

Saves an animation object produced by animate_3d() to a file. If no animation is provided, saves the most recently rendered animation.

Usage

anim_save_3d(animation = NULL, filename)

Arguments

Value

Invisibly returns the output file path (a character string). Called primarily for its side effect of copying the animation to filename.

Examples

p <- ggplot() +
  geom_function_3d(
    fun = function(x, y) sin(x) * cos(y),
    xlim = c(-pi, pi), ylim = c(-pi, pi),
    fill = "steelblue", color = "steelblue") +
  coord_3d()

animate_3d(p, yaw = c(0, 360))
anim_save_3d(filename = file.path(tempdir(), "my_animation.gif"))

Description

Renders an animated GIF or MP4 of a rotating ggplot with coord_3d(), smoothly interpolating rotation angles across frames.

Usage

animate_3d(
  plot,
  pitch = NULL,
  roll = NULL,
  yaw = NULL,
  nframes = NULL,
  fps = NULL,
  duration = NULL,
  width = 480,
  height = 480,
  res = 96,
  renderer = gifski_renderer_3d(),
  start_pause = 0,
  end_pause = 0,
  rewind = FALSE,
  cores = 1,
  device = "png",
  progress = interactive()
)

Arguments

Value

The return value of the renderer function. For gifski_renderer_3d(), a gif_3d object (a file path with class attributes for display in RStudio and knitr). For av_renderer_3d(), a video_3d object (a file path with class attributes for display). For file_renderer_3d(), a character vector of file paths to the rendered frame images.

See Also

anim_save_3d() for saving animations to file. gifski_renderer_3d() and file_renderer_3d() for renderer options.

Examples

# Plot to animate. Note `anchor = "camera"` keeps light source from rotating.
p <- ggplot() +
  geom_function_3d(
    fun = function(x, y) sin(x) * cos(y),
    xlim = c(-pi, pi), ylim = c(-pi, pi),
    fill = "steelblue", color = "steelblue", linewidth = .5) +
  coord_3d(light = light(mode = "hsl", anchor = "camera",
                         direction = c(1, 1, 0))) +
  theme_void()

# Simple turntable rotation
# (using small `nframes` to minimize runtime)
animate_3d(p, yaw = c(-30, 330), nframes = 12)

# Multi-segment orbit with pitch change
animate_3d(p, yaw = c(0, 720), roll = c(-90, 0, -90),
           nframes = 12, fps = 15)

# Save to file (writes to a temporary path; specify your own to keep it)
anim <- animate_3d(p, yaw = c(0, 360), nframes = 12)
anim_save_3d(anim, file.path(tempdir(), "rotating_surface.gif"))

Description

Defines fixed-position annotations to be embedded within a 3D layer. Annotations are depth-sorted together with the primary geometry, unlike ggplot2's annotate() which creates a separate layer.

Usage

annotate_3d(type, ...)

Arguments

Details

Parameters can be vectors to create multiple annotations of the same type in one call, with scalar values recycled as needed (matching ggplot2::annotate() behaviour).

Point annotations

Requires x, y, z. Optional styling: colour/color, fill, size, shape, alpha, stroke.

Text annotations

Requires x, y, z, label. Optional styling: colour/color, size, alpha, family, fontface, hjust, vjust, angle, lineheight.

Segment annotations

Requires x, y, z, xend, yend, zend. Optional styling: colour/color, linewidth, linetype, alpha.

Value

An S3 object of class "annotate_3d".

Examples

p <- ggplot(mountain, aes(x, y, z)) +
  coord_3d(ratio = c(2, 3, 1),
           light = light(mode = "hsl", direction = c(-1, 0, 0)))

# Basic point annotation
p + geom_surface_3d(
  annotate = annotate_3d("point", x = .5, y = .25, z = 100,
                         color = "red", size = 3))

# Vectorized: multiple points in one call
p + geom_surface_3d(
  annotate = annotate_3d("point", x = .5, y = .25, z = seq(50, 100, 5),
                         color = "red", size = 3))

# Multiple annotation types
p + geom_surface_3d(
  annotate = list(
    annotate_3d("point", x = .5, y = .25, z = 100,
                color = "red", size = 3),
    annotate_3d("text", x = .5, y = .25, z = 100,
                color = "red", label = "Look here!",
                vjust = -1, fontface = "bold"),
    annotate_3d("segment", x = .5, y = .25, z = 100,
                xend = .5, yend = .25, zend = 50,
                color = "red", size = 3)))

Description

Creates a specification for camera-facing "billboard" text that will compute the appropriate facing direction for each label position.

Usage

camera_facing(
  coord = NULL,
  pitch = 0,
  roll = -60,
  yaw = -30,
  dist = 2,
  mode = c("plane", "point")
)

Arguments

Details

With mode = "plane", all text labels face the same direction (parallel to the viewing plane), similar to traditional billboard rendering. This produces clean, readable labels.

With mode = "point", each label faces directly toward the camera's position in 3D space. Labels near the edges of the plot will angle inward, which is geometrically correct but can look less clean.

Since geom_text_3d() computes vertex positions before the view is known, you must specify the view parameters here and use the same values in coord_3d().

Value

A camera_facing_spec object to pass to the facing parameter of geom_text_3d().

See Also

geom_text_3d() for rendering 3D text labels

Examples

# Parallel billboard text (default) - all labels face same direction
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 = z, label = label)) +
  geom_text_3d(method = "polygon",
               facing = camera_facing(pitch = 20, roll = -60, yaw = -30)) +
  coord_3d(pitch = 20, roll = -60, yaw = -30)

# Point-facing text - labels angle toward camera position
ggplot(df, aes(x, y, z = z, label = label)) +
  geom_text_3d(method = "polygon",
               facing = camera_facing(pitch = 20, roll = -60, yaw = -30,
                                      mode = "point")) +
  coord_3d(pitch = 20, roll = -60, yaw = -30)

Description

coord_3d is a 3D coordinate system that creates a 2D view of 3D data. This is the essential core component of any plot made with ggcube. It supports rotation, perspective projection, and options for controlling plot aspect ratios, panel selection, axis label placement, and lighting.

Usage

coord_3d(
  pitch = 0,
  roll = -60,
  yaw = -30,
  persp = TRUE,
  dist = 2,
  expand = TRUE,
  clip = "off",
  panels = "background",
  xlabels = "auto",
  ylabels = "auto",
  zlabels = "auto",
  title_position = c("auto", "center"),
  rotate_labels = TRUE,
  scales = "free",
  ratio = c(1, 1, 1),
  zoom = 1,
  light = ggcube::light(),
  ...
)

Arguments

Value

A Coord object that can be added to a ggplot.

See Also

light() for lighting specification, cube_theming for panel and text styling, polygon_params for 3D-related parameters for polygon layers.

Examples

# base plot used in examples
p <- ggplot() +
  geom_function_3d(
    aes(fill = after_stat(z), color = after_stat(z)),
    fun = function(x, y) sin(x) * cos(y),
    xlim = c(-pi, pi), ylim = c(-pi, pi),
    n = 50, light = light("direct", contrast = .7)) +
  scale_fill_viridis_c() +
  scale_color_viridis_c() +
  theme(legend.position = "none")

# 3D plot with default coord settings
p + coord_3d()



# Use `pitch`, `roll`, `yaw` to control plot rotation ----------------------

# zero rotation gives view from x-y face
p + coord_3d(pitch = 0, roll = 0, yaw = 0)

# pitch rotates plot around y axis
p + coord_3d(pitch = 30, roll = 0, yaw = 0)

# roll rotates plot around x axis
p + coord_3d(pitch = 0, roll = 30, yaw = 0)

# yaw rotates plot around z axis
p + coord_3d(pitch = 0, roll = 0, yaw = 30)

# combine them to achieve arbitrary rotations
p + coord_3d(pitch = 20, roll = 40, yaw = 60)


# Use `persp` and `dist` to control perspective effects --------------------

# strong perspective effect as if seen from very close
p + coord_3d(dist = 1)

# weaker perspective effects as if seen from far away
p + coord_3d(dist = 3)

# orthographic projection (`dist = Inf` would be equivalent but it errors)
p + coord_3d(persp = FALSE)


# Use `scales` and `ratio` to control aspect ratio -------------------------

# The default "free" scales shown above give cube with maximum visual range.
# Use "fixed" scales to make figure match data scales, like coord_fixed.
p + coord_3d(scales = "fixed")

# Custom aspect ratios: make y twice as long visually
p + coord_3d(scales = "free", ratio = c(1, 2, 1))

# Combine behaviors: fix scales and make y twice as long
p + coord_3d(scales = "fixed", ratio = c(1, 2, 1))


# Use `panels` to select which cube faces to render ------------------------

p + coord_3d(panels = c("xmin", "xmax", "zmax"))

# foreground panels default to 20% opaque (can be styled using `theme()`)
p + coord_3d(panels = "all")


# Use label params to control axis text placement and rotation -------------

p + coord_3d(xlabels = c("ymax", "zmax"),
             zlabels = c("xmax", "ymin"))

p + coord_3d(rotate_labels = FALSE)

Description

In ggcube, standard ggplot2 themes generally influence 3D plots as expected, including adding complete themes like ggplot2::theme_dark() and modifying theme elements like ⁠theme(panel.background = element_rect(fill = "darkblue")⁠. However, ggcube also provides additional theme elements that control 3D-specific styling of panels and labels.

Text elements

• axis.text.z: Styling for z-axis tick labels (inherits from axis.text)

• axis.title.z: Styling for z-axis title (inherits from axis.title)

• axis.text, axis.title: Standard styling with element_text().

Use element_text(margin = margin(...)) to adjust text padding, with left/right margins affecting axis text and top/bottom margins affecting axis titles; since placement and justification of these elements varies dynamically, no distinction is made between left and right margins, or between top and bottom margins – you can set either, and the maximum of the two will be used.

Panel elements

• panel.foreground: Styling for cube faces rendered in front of data (inherits from panel.background). Foreground panels default to 20% opacity to keep them from obscuring the data; this can be overridden by setting alpha on either panel.foreground or panel.background.

• panel.border.foreground: Styling for cube faces rendered in front of data (inherits from panel.border)

• panel.grid.foreground: Styling for grid lines on foreground faces (inherits from panel.grid)

• panel.grid.major.foreground: Major grid lines on foreground faces (inherits from panel.grid.foreground)

Background panels use standard panel.background, panel.border, panel.grid, etc., while foreground panels use the ⁠*.foreground⁠ variants listed above. Since the foreground elements inherit from the standard background and grid elements, you can use panel.background, etc. to style both background and foreground faces simultaneously. This also extends to alpha set via the enhanced element_rect() below: setting alpha on panel.background will tint both background and foreground panels (overriding the foreground's 20% default), unless an explicit alpha is also set on panel.foreground.

Enhanced elements

• element_rect() extends ggplot2::element_rect() by adding an alpha parameter for transparency effects on coord_3d()'s foreground and background panels.

Examples

# example code
p <- 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)), # add padding
          axis.title.x = element_text(color = "magenta"))

Description

This function extends ggplot2::element_rect() to support transparency via an alpha parameter, which is attached to the returned element as an R attribute ("ggcube_alpha"). The attribute survives ggplot2's theme inheritance machinery, so the alpha value set here is available to the renderer at draw time. The alpha parameter is consumed only by coord_3d()'s panel rendering and has no effect on other theme elements.

Usage

element_rect(fill = NULL, alpha = NA, ...)

Arguments

Value

A ggplot2::element_rect theme element with an attached "ggcube_alpha" attribute.

See Also

element_rect for the original function, coord_3d for 3D coordinate systems that utilize foreground panels

Examples

# Basic 3D plot with semi-transparent foreground panels
ggplot(mountain, aes(x, y, z)) +
  stat_surface_3d(fill = "darkblue", color = "lightblue", linewidth = .1) +
  coord_3d(panels = c("background", "ymin")) +
  theme(panel.foreground = element_rect(alpha = 0.6))

# Completely transparent foreground panels
ggplot(mtcars, aes(mpg, wt, qsec)) +
  geom_point() +
  coord_3d(panels = "all") +
  theme(panel.border = element_rect(color = "black"),
        panel.foreground = element_rect(fill = "blue", alpha = 0))

Description

Creates 3D bar charts by automatically counting discrete data or binning continuous data. This is the 3D analogue of ggplot2::geom_bar() and ggplot2::geom_histogram().

Usage

geom_bar_3d(
  mapping = NULL,
  data = NULL,
  stat = StatBar3D,
  position = "identity",
  ...,
  bins = 10,
  binwidth = NULL,
  drop = TRUE,
  width = 1,
  faces = "all",
  light = NULL,
  cull_backfaces = TRUE,
  sort_method = NULL,
  scale_depth = TRUE,
  force_convex = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_bar_3d(
  mapping = NULL,
  data = NULL,
  geom = GeomPolygon3D,
  position = "identity",
  ...,
  bins = 10,
  binwidth = NULL,
  drop = TRUE,
  width = 1,
  faces = "all",
  light = NULL,
  cull_backfaces = TRUE,
  sort_method = NULL,
  scale_depth = TRUE,
  force_convex = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

The stat automatically detects whether x and y are discrete or continuous:

• Both discrete: Counts occurrences of each (x, y) combination

• Both continuous: Performs 2D binning (like a 3D histogram)

• Mixed: Bins the continuous axis while preserving discrete groups

For pre-computed bar heights, use geom_col_3d() instead.

Value

A Layer object that can be added to a ggplot.

Aesthetics

stat_bar_3d() requires the following aesthetics:

• x: X coordinate

• y: Y coordinate

And optionally understands:

• weight: Observation weights for counting

Computed variables

These variables can be used with after_stat() to map to aesthetics:

• count: Number of observations in each bin (default for z)

• proportion: Count divided by total count (sums to 1)

• ncount: Count scaled to maximum of 1

• density: Count divided by (total count × bin area); integrates to 1 for continuous data

• ndensity: Density scaled to maximum of 1

See Also

geom_col_3d() for pre-computed heights, coord_3d() for 3D coordinate systems, light() for lighting specifications.

Examples

# Discrete x and y: count combinations
d_discrete <- data.frame(
  x = sample(letters[1:4], 200, replace = TRUE),
  y = sample(LETTERS[1:3], 200, replace = TRUE)
)
ggplot(d_discrete, aes(x, y)) +
  geom_bar_3d() +
  coord_3d()

# Continuous x and y: 2D histogram
d_cont <- data.frame(x = rnorm(1000), y = rnorm(1000))
ggplot(d_cont, aes(x, y)) +
  geom_bar_3d() +
  coord_3d()

# Mixed: one discrete, one continuous
d_mixed <- data.frame(
  group = rep(c("A", "B", "C"), each = 100),
  value = c(rnorm(100, 2), rnorm(100, 1, 2), rnorm(100, 0))
)
ggplot(d_mixed, aes(x = group, y = value, fill = group)) +
  geom_bar_3d(bins = 20, width = c(.5, 1)) +
  coord_3d(scales = "fixed", ratio = c(1, 1, .1))

# Use density instead of count for z
ggplot(d_mixed,
      aes(x = group, y = value, z = after_stat(density))) +
  geom_bar_3d(bins = 20, width = c(.5, 1)) +
  coord_3d()

# Show empty bins with drop = FALSE
ggplot(d_cont, aes(x, y)) +
  geom_bar_3d(drop = FALSE) +
  coord_3d()

Description

Creates 3D columns (rectangular prisms) from grid data in which x and y fall on a regular grid. Works with both complete and sparse grid data. Each data point becomes a rectangular 3D column extending from a base level to the data value.

Usage

geom_col_3d(
  mapping = NULL,
  data = NULL,
  stat = StatCol3D,
  position = "identity",
  ...,
  width = 1,
  faces = "all",
  zmin = NULL,
  light = NULL,
  cull_backfaces = TRUE,
  sort_method = NULL,
  scale_depth = TRUE,
  force_convex = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_col_3d(
  mapping = NULL,
  data = NULL,
  geom = GeomPolygon3D,
  position = "identity",
  ...,
  width = 1,
  faces = "all",
  zmin = NULL,
  light = NULL,
  cull_backfaces = TRUE,
  sort_method = NULL,
  scale_depth = TRUE,
  force_convex = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

This is analogous to ggplot2::geom_col() for 3D plots. For automatic counting or binning, see geom_bar_3d().

Note that column geometries often require pairwise depth sorting for correct rendering. This is the default for smaller data sets, but not for larger data sets due to compute speed; in those cases you may wish to manually specify sort_method = "pairwise" for good results.

Value

A Layer object that can be added to a ggplot.

Aesthetics

stat_col_3d() requires the following aesthetics:

• x: X coordinate (grid position)

• y: Y coordinate (grid position)

• z: Z coordinate (column top height)

And optionally understands:

• zmin: Base level for each column (can be overridden by the zmin parameter)

Computed variables

• normal_x, normal_y, normal_z: Face normal components

• col_id: Sequential column number

• face_type: Face name ("zmax", "xmin", etc.)

See Also

geom_bar_3d() for automatic counting/binning, stat_surface_3d() for smooth surface rendering, coord_3d() for 3D coordinate systems, light() for lighting specifications.

Examples

# Basic 3D bar chart from regular grid
# (columns extend from z=0 by default)
d <- expand.grid(x = 1:5, y = 1:5)
d$z <- d$x + d$y + rnorm(25, 0, 0.5)
ggplot(d, aes(x, y, z)) +
  geom_col_3d() +
  coord_3d()

# Set uniform base level using `zmin` parameter
ggplot(d, aes(x, y, z)) +
  geom_col_3d(aes(fill = z), color = "white",
              zmin = 5) +
  coord_3d()

# Set variable base levels using `zmin` aesthetic
d$base_level <- runif(nrow(d), -5, 1)
ggplot(d, aes(x, y, z = z, zmin = base_level)) +
  geom_col_3d(color = "black") +
  coord_3d()

# Show only a subset of column faces
ggplot(d, aes(x, y, z)) +
  geom_col_3d(faces = c("zmax", "ymin"),
    cull_backfaces = FALSE,
    fill = "steelblue", color = "black") +
  coord_3d()

# With gaps between columns
ggplot(d, aes(x, y, z)) +
  geom_col_3d(color = "black", width = 0.6) +
  coord_3d()

Description

Renders a surface as stacked horizontal contour bands. Each contour band is a polygon placed at its corresponding z-level.

Usage

geom_contour_3d(
  mapping = NULL,
  data = NULL,
  stat = "surface_3d",
  position = "identity",
  ...,
  bins = 20,
  binwidth = NULL,
  breaks = NULL,
  cull_backfaces = FALSE,
  sort_method = "pairwise",
  scale_depth = TRUE,
  force_convex = FALSE,
  light = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_contour_3d(
  mapping = NULL,
  data = NULL,
  geom = "contour_3d",
  position = "identity",
  ...,
  bins = 20,
  binwidth = NULL,
  breaks = NULL,
  cull_backfaces = FALSE,
  sort_method = "pairwise",
  scale_depth = TRUE,
  force_convex = FALSE,
  light = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

This geom takes point grid data (like that produced by stat_surface_3d(), stat_function_3d(), stat_smooth_3d(), or stat_density_3d()) and converts it to filled contour polygons using the isoband package.

Value

A Layer object that can be added to a ggplot.

Aesthetics

geom_contour_3d() requires:

x, y, z

Point coordinates forming a regular grid

And understands these additional aesthetics:

fill

Band fill color. For automatic coloring by elevation, use aes(fill = after_stat(z)). Default is "grey60".

colour

Band border color (default: "grey30")

alpha

Transparency

linewidth

Border width (default: 0.1)

linetype

Border line type

Computed variables

Each contour band is placed at its corresponding z-level (the upper boundary of the band). To color by elevation, use aes(fill = after_stat(z)).

See Also

geom_surface_3d() for continuous surface rendering, geom_ridgeline_3d() for cross-sectional ridgeline rendering, stat_function_3d() for mathematical function surfaces, stat_smooth_3d() for fitted model surfaces, coord_3d() for 3D coordinate systems, ggplot2::geom_contour_filled() for the 2D equivalent.

Examples

# Basic usage with volcano data
ggplot(mountain, aes(x, y, z)) +
      geom_contour_3d(color = "white", fill = "black") +
      coord_3d(light = "none", ratio = c(1.5, 2, 1))

# Map fill to elevation and customize number of levels
ggplot(mountain, aes(x, y, z, fill = after_stat(z))) +
      geom_contour_3d(bins = 12, color = "white") +
      scale_fill_viridis_c() +
      coord_3d(light = "none", ratio = c(1.5, 2, 1))

# Specify exact breaks
ggplot(mountain, aes(x, y, z, fill = after_stat(z))) +
  geom_contour_3d(breaks = seq(0, 200, by = 5)) +
  scale_fill_viridis_c() +
  coord_3d(light = "none")

# With stat_density_3d
ggplot(faithful, aes(eruptions, waiting)) +
  stat_density_3d(geom = "contour_3d",
    sort_method = "pairwise") +
  coord_3d()

# With stat_function_3d
ggplot() +
  stat_function_3d(
    fun = function(x, y) sin(x) * cos(y),
    xlim = c(-pi, pi), ylim = c(-pi, pi),
    geom = "contour_3d",
    bins = 50, color = "black"
  ) +
  scale_fill_viridis_c(option = "B") +
  coord_3d(light = "none")

Description

A 3D version of ggplot2::stat_density_2d(). Creates surfaces from 2D point data using kernel density estimation. The density values become the z-coordinates of the surface, allowing visualization of data concentration as peaks and valleys in 3D space.

Usage

geom_density_3d(
  mapping = NULL,
  data = NULL,
  stat = "density_3d",
  position = "identity",
  ...,
  grid = "rectangle",
  n = 40,
  direction = "x",
  trim = TRUE,
  h = NULL,
  adjust = 1,
  pad = 0.1,
  min_ndensity = 0,
  light = NULL,
  cull_backfaces = FALSE,
  sort_method = NULL,
  force_convex = FALSE,
  scale_depth = TRUE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_density_3d(
  mapping = NULL,
  data = NULL,
  geom = "surface_3d",
  position = "identity",
  ...,
  grid = "rectangle",
  n = 40,
  direction = "x",
  trim = TRUE,
  h = NULL,
  adjust = 1,
  pad = 0.1,
  min_ndensity = 0,
  light = NULL,
  cull_backfaces = FALSE,
  sort_method = NULL,
  force_convex = FALSE,
  scale_depth = TRUE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A Layer object that can be added to a ggplot.

Aesthetics

stat_density_3d() requires the following aesthetics from input data:

• x: X coordinate of data points

• y: Y coordinate of data points

And optionally understands:

• group: Grouping variable for computing separate density surfaces

• Additional aesthetics are passed through for surface styling

Computed variables specific to StatDensity3D

• density: The kernel density estimate at each grid point

• ndensity: Density estimate scaled to maximum of 1 within each group

• count: Density estimate × number of observations in group (expected count)

• n: Number of observations in each group

Grouping

When aesthetics like colour or fill are mapped to categorical variables, stat_density_3d() computes separate density surfaces for each group, just like stat_density_2d(). Each group gets its own density calculation with proper count and n values.

Computed variables

The following computed variables are available via after_stat():

• x, y, z: Grid coordinates and function values

• normal_x, normal_y, normal_z: Surface normal components

• slope: Gradient magnitude from surface calculations

• aspect: Direction of steepest slope from surface calculations

• dzdx, dzdy: Partial derivatives from surface calculation

See Also

ggplot2::stat_density_2d() for 2D density contours, stat_surface_3d() for surfaces from existing grid data, light() for lighting specifications, coord_3d() for 3D coordinate systems.

Examples

# Basic density surface from scattered points
p <- ggplot(faithful, aes(eruptions, waiting)) +
  coord_3d() +
  scale_fill_viridis_c()
p + geom_density_3d() + guides(fill = guide_colorbar_3d())



# Specify alternative grid geometry and light model
p + geom_density_3d(grid = "equilateral", n = 30, direction = "y",
                    light = light("direct"),
                    color = "white", linewidth = .1) +
  guides(fill = guide_colorbar_3d())

# Color by alternative density metric
p + geom_density_3d(aes(fill = after_stat(count)))

# Adjust bandwidth for smoother or more detailed surfaces
p + geom_density_3d(adjust = 0.5, n = 100, color = "white")  # More detail
p + geom_density_3d(adjust = 2, color = "white")   # Smoother

# As contour plot instead of default surface plot
p + stat_density_3d(geom = "contour_3d", light = "none",
                    color = "black", bins = 25,
                    sort_method = "pairwise")

# Multiple density surfaces by group,
# using normalized density to equalize peak heights
ggplot(iris, aes(Petal.Length, Sepal.Length, fill = Species)) +
  geom_density_3d(aes(z = after_stat(ndensity), group = Species),
                  color = "black", alpha = .7, light = NULL) +
  coord_3d()

# Same, but with extra padding to remove edge effects and
# with density filtering to remove rectangular artifacts
ggplot(iris, aes(Petal.Length, Sepal.Length, fill = Species)) +
  geom_density_3d(aes(z = after_stat(ndensity)),
                  pad = .3, min_ndensity = .001,
                  color = "black", alpha = .7, light = NULL) +
  coord_3d(ratio = c(3, 3, 1))

Description

Turns 3D point clouds into surface hulls consisting of triangular polygons, using either convex hull or alpha shape algorithms.

Usage

geom_hull_3d(
  mapping = NULL,
  data = NULL,
  stat = StatHull3D,
  position = "identity",
  ...,
  method = "convex",
  radius = NULL,
  light = NULL,
  cull_backfaces = TRUE,
  sort_method = NULL,
  scale_depth = TRUE,
  inherit.aes = TRUE,
  show.legend = TRUE
)

stat_hull_3d(
  mapping = NULL,
  data = NULL,
  geom = GeomPolygon3D,
  position = "identity",
  ...,
  method = "convex",
  radius = NULL,
  light = NULL,
  cull_backfaces = TRUE,
  sort_method = NULL,
  scale_depth = TRUE,
  inherit.aes = TRUE,
  show.legend = TRUE
)

Arguments

Value

A Layer object that can be added to a ggplot.

Grouping

Hulls respect ggplot2 grouping aesthetics. To create separate hulls for different subsets of your data, use aes(group = category_variable) or similar grouping aesthetics. Each group will get its own independent hull.

Alpha scale sensitivity

Alpha shape method is highly sensitive to coordinate scales. The alpha parameter that works for data scaled 0-1 will likely fail for data scaled 0-1000. Guidelines for choosing radius:

• Start with alpha = 1.0 and adjust based on results

• For data with mixed scales (e.g., x: 0-1, y: 0-1000), consider rescaling your data first

• Larger alpha values → smoother, more connected surfaces

• Smaller alpha values → more detailed surfaces, but may fragment

• If you get no triangles, try increasing alpha by 10x

• If surface fills unwanted holes, try decreasing alpha by 10x

Aesthetics

stat_hull_3d() requires the following aesthetics:

• x: X coordinate

• y: Y coordinate

• z: Z coordinate

Computed variables

• normal_x, normal_y, normal_z: Surface normal components

See Also

coord_3d() for 3D coordinate systems, geom_polygon_3d for the default geometry with depth sorting, light() for lighting specifications.

Examples

# Convex hull
ggplot(sphere_points, aes(x, y, z)) +
  geom_hull_3d(method = "convex", fill = "gray40") +
  coord_3d()

# Alpha shape (for sphere data, gives similar result to convex)

ggplot(sphere_points, aes(x, y, z)) +
  geom_hull_3d(method = "alpha", radius = 2, fill = "gray40") +
  coord_3d()


# Use `cull_backfaces = FALSE` to render far side of hull
ggplot(sphere_points, aes(x, y, z)) +
  geom_hull_3d( # default culling for comparison
    method = "convex", light = NULL,
    fill = "steelblue", color = "darkred", linewidth = .5, alpha = .5) +
  geom_hull_3d( # culling disabled
    aes(x = x + 2.5), cull_backfaces = FALSE,
    method = "convex", light = NULL,
    fill = "steelblue", color = "darkred", linewidth = .5, alpha = .5) +
  coord_3d(scales = "fixed")

# Use grouping to build separate hulls for data subsets
ggplot(iris, aes(Petal.Length, Sepal.Length, Sepal.Width,
                 color = Species, fill = Species)) +
      geom_hull_3d() +
      coord_3d(scales = "fixed")

Description

Connects observations in 3D space in the order they appear in the data. It converts path data into individual segments for proper depth sorting while maintaining the appearance of connected paths. Each path is divided into segments that can be depth-sorted independently.

Usage

geom_path_3d(
  mapping = NULL,
  data = NULL,
  stat = StatPath3D,
  position = "identity",
  ...,
  sort_method = "painter",
  scale_depth = TRUE,
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_path_3d(
  mapping = NULL,
  data = NULL,
  geom = GeomSegment3D,
  position = "identity",
  ...,
  sort_method = "painter",
  scale_depth = TRUE,
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A Layer object that can be added to a ggplot.

Aesthetics

geom_path_3d() understands the following aesthetics:

• x, y, z: Coordinates (required)

• group: Grouping variable to create separate paths

• colour: Line color

• linewidth: Line width (gets depth-scaled when scale_depth = TRUE)

• linetype: Line type

• alpha: Transparency

Computed variables for StatSegment3D

• x, y, z: Start coordinates of each segment

• xend, yend, zend: End coordinates of each segment

• group: Hierarchical group identifier preserving original grouping

Grouping

Multiple paths are created based on grouping aesthetics (group, colour, etc.). Each group forms a separate path, and segments from different paths can be interleaved during depth sorting for proper 3D rendering.

See Also

geom_segment_3d() for individual segments.

Examples

library(ggplot2)

x <- seq(0, 20*pi, pi/16)
spiral <- data.frame(
  x = x,
  y = sin(x),
  z = cos(x))

# Basic path
ggplot(spiral, aes(x, y, z)) +
  geom_path_3d() +
  coord_3d()

# With aesthetic coloring
ggplot(spiral, aes(x, y, z, color = y)) +
  geom_path_3d(linewidth = 1, lineend = "round") +
  coord_3d() +
  scale_color_gradientn(colors = c("red", "purple", "blue"))

# With grouping
ggplot(spiral, aes(x, y, z, color = x > 30)) +
  geom_path_3d(linewidth = 1, lineend = "round") +
  coord_3d()

Description

geom_point_3d() creates scatter plots in 3D space with automatic depth-based size scaling. Points closer to the viewer appear larger, while points farther away appear smaller, creating realistic perspective effects. Optionally adds reference lines and points projecting to cube faces, to illustrate point locations in 2D.

Usage

geom_point_3d(
  mapping = NULL,
  data = NULL,
  stat = StatPoint3D,
  position = "identity",
  ...,
  na.rm = FALSE,
  sort_method = "painter",
  scale_depth = TRUE,
  raw_points = TRUE,
  ref_lines = FALSE,
  ref_points = FALSE,
  ref_faces = "zmin",
  ref_circle_radius = 1.5,
  ref_circle_vertices = 16,
  ref_line_color = NULL,
  ref_line_colour = NULL,
  ref_line_linewidth = 0.25,
  ref_line_linetype = NULL,
  ref_line_alpha = NULL,
  ref_point_color = NULL,
  ref_point_colour = NULL,
  ref_point_fill = NULL,
  ref_point_size = NULL,
  ref_point_alpha = NULL,
  ref_point_stroke = NULL,
  ref_point_shape = NULL,
  inherit.aes = TRUE,
  show.legend = NA
)

stat_point_3d(
  mapping = NULL,
  data = NULL,
  geom = GeomPoint3D,
  position = "identity",
  ...,
  na.rm = FALSE,
  sort_method = "painter",
  scale_depth = TRUE,
  raw_points = TRUE,
  ref_lines = FALSE,
  ref_points = FALSE,
  ref_faces = "zmin",
  ref_circle_radius = 1.5,
  ref_circle_vertices = 16,
  ref_line_color = NULL,
  ref_line_colour = NULL,
  ref_line_linewidth = 0.25,
  ref_line_linetype = NULL,
  ref_line_alpha = NULL,
  ref_point_color = NULL,
  ref_point_colour = NULL,
  ref_point_fill = NULL,
  ref_point_size = NULL,
  ref_point_alpha = NULL,
  ref_point_stroke = NULL,
  ref_point_shape = NULL,
  inherit.aes = TRUE,
  show.legend = NA
)

Arguments

Details

StatPoint3D performs identity transformation (passes data through unchanged) while properly handling discrete scales for 3D coordinate systems. It can optionally generate reference lines and points projecting to cube faces.

Value

A Layer object that can be added to a ggplot.

Aesthetics

geom_point_3d() supports all the same aesthetics as ggplot2::geom_point(), plus z:

• x: X coordinate (required)

• y: Y coordinate (required)

• z: Z coordinate (required)

• alpha: Transparency

• colour: Point border color

• fill: Point fill color (for certain shapes)

• shape: Point shape

• size: Point size (gets depth-scaled when scale_depth = TRUE)

• stroke: Border width for shapes with borders

StatPoint3D returns the following computed variables

• x_raw, y_raw, z_raw: Original values before discrete-to-numeric conversion

• element_type: Type of element ("raw_point", "ref_point", "ref_line", "ref_circle")

• segment_id: ID linking the two endpoints of reference lines

• ref_face: Which face reference elements project to

• ref_circle_radius: Radius for circular reference points

• ref_circle_vertices: Number of vertices for circular reference points

Depth Scaling

The depth scaling uses an inverse relationship with distance, following the mathematical relationship: apparent_size = base_size * reference_distance / actual_distance

This creates realistic perspective where:

• Objects twice as far appear half as big

• Objects twice as close appear twice as big

• The center of the plot volume renders at exactly the user-specified size

Point Rendering

ggcube uses shape-aware rendering for improved stroke behavior:

• Simple shapes (0-20, characters): Use size for fontsize, stroke for border width, no fill

• Complex shapes (21-25): Use ggplot2's approach: size + 0.5*stroke for fontsize to prevent gaps

• Both size and stroke are depth-scaled when scale_depth = TRUE

• All shapes preserve stroke depth scaling and parameter control

Reference Features

Reference lines and points help visualize the 3D relationships by projecting data points onto cube faces:

• Reference lines: Connect each 3D point to its projection on specified faces

• Reference points: Show the projected location on the faces

• Reference circles: Circular projections that appear as realistic 3D shadows

• Depth sorting: All elements (original points, reference lines, reference points) are automatically depth-sorted for proper 3D rendering

Aesthetic Inheritance

Reference elements intelligently inherit styling from raw points:

• Shape-aware: Complex shapes (21-25) with fill/colour are handled differently from simple shapes (0-20/characters)

• Alpha detection: If all points have alpha=1, uses 0.5 default for ref elements; otherwise inherits mapped alpha

• Priority: Explicit ref_* parameters > mapped aesthetics > smart defaults

See Also

geom_segment_3d() for 3D segments, geom_path_3d() for 3D paths, coord_3d() for 3D coordinate systems.

Examples

library(ggplot2)

# Basic 3D scatter plot with depth scaling
ggplot(expand.grid(x = 1:5, y = 1:5, z = 1:5),
       aes(x, y, z, fill = z)) +
  geom_point_3d(size = 10, shape = 21, color = "white", stroke = .1) +
  coord_3d(pitch = 40, roll = 5, yaw = 0, dist = 1.5) +
  scale_fill_viridis_c()

# Add circular reference points on 2D face panel
ggplot(mtcars, aes(mpg, wt, qsec)) +
  geom_point_3d(size = 3,
    ref_points = TRUE, ref_faces = c("ymax", "xmax")) +
  coord_3d()

Description

geom_polygon_3d() renders 3D polygons with proper depth sorting for realistic 3D surface visualization. It's designed to work with surface data from stat_hull_3d() and stat_surface_3d(), as well as regular polygon data like maps.

Usage

geom_polygon_3d(
  mapping = NULL,
  data = NULL,
  stat = StatIdentity3D,
  position = "identity",
  ...,
  rule = "evenodd",
  sort_method = "auto",
  scale_depth = TRUE,
  force_convex = FALSE,
  cull_backfaces = FALSE,
  light = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A Layer object that can be added to a ggplot.

Aesthetics

geom_polygon_3d() requires:

• x: X coordinate

• y: Y coordinate

• z: Z coordinate (for depth sorting)

• group: Polygon grouping variable

And understands these additional aesthetics:

• fill: Polygon fill color

• colour: Border color

• linewidth: Border line width

• linetype: Border line type

• alpha: Transparency

• subgroup: Secondary grouping for polygons with holes

• order: Vertex order within polygons (for proper polygon construction)

Examples

# Typically used via stats such as stat_surface_3d() or stat_hull_3d()
ggplot(sphere_points, aes(x, y, z)) +
  stat_hull_3d(method = "convex", fill = "dodgerblue",
            light = light(fill = TRUE, mode = "hsl")) +
  coord_3d()

# Can be used directly with properly structured data
triangles <- data.frame(x = rep(c(3, 2, 1), 3),
                            y = rep(c(1, 3, 1), 3),
                            z = rep(1:3, each = 3),
                            shape = rep(letters[1:3], each = 3))
ggplot(triangles, aes(x, y, z, fill = shape)) +
  geom_polygon_3d(color = "black") +
  coord_3d()

# Use `sort_method` to choose between depth sorting algorithms
d <- data.frame(group = rep(letters[1:3], each = 4),
                x = c(1, 1, 2, 2,   1, 1, 3, 3,   2, 2, 3, 3),
                y = rep(c(1, 2, 2, 1), 3),
                z = rep(c(1, 1.5, 2), each = 4))
p <- ggplot(d, aes(x, y, z, group = group, fill = group)) +
      coord_3d(pitch = 50, roll = 20, yaw = 0,
               scales = "fixed", light = "none") +
      theme_light()

# fast, but rendering order is incorrect in this particular example
p + geom_polygon_3d(color = "black", linewidth = 1, alpha = .75,
      sort_method = "painter")

# correct rendering order (but slower for large data sets)
p + geom_polygon_3d(color = "black", linewidth = 1, alpha = .75,
      sort_method = "pairwise")

Description

Renders a point grid as ridgeline polygons (Joy Division style). Each slice along one axis becomes a filled polygon, creating a cross-sectional view of the surface.

Usage

geom_ridgeline_3d(
  mapping = NULL,
  data = NULL,
  stat = "identity_3d",
  position = "identity",
  ...,
  direction = "x",
  base = NULL,
  cull_backfaces = FALSE,
  sort_method = "pairwise",
  scale_depth = TRUE,
  force_convex = FALSE,
  light = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A Layer object that can be added to a ggplot.

Aesthetics

x, y, z

Point coordinates (required)

fill

Polygon fill color (default: "grey70")

colour

Polygon border color (default: "black")

alpha

Transparency

linewidth

Border width

linetype

Border type

See Also

geom_surface_3d(), stat_function_3d(), coord_3d()

Examples

# From point grid
grid_data <- expand.grid(x = seq(-3, 3, 0.5), y = seq(-3, 3, 0.1))
grid_data$z <- with(grid_data, dnorm(y) * dnorm(x) * 10)

ggplot(grid_data, aes(x, y, z = z)) +
  geom_ridgeline_3d() +
  coord_3d()

# With fill
ggplot(grid_data, aes(x, y, z = z, fill = x)) +
  geom_ridgeline_3d(colour = "white", linewidth = 0.3) +
  scale_fill_viridis_c() +
  coord_3d()

# Ridges in y direction
ggplot(grid_data, aes(x, y, z = z)) +
  geom_ridgeline_3d(direction = "y", fill = "steelblue") +
  coord_3d()

# With stat_function_3d
ggplot() +
  stat_function_3d(fun = function(x, y) sin(x) * cos(y),
                   xlim = c(-pi, pi), ylim = c(-pi, pi),
                   n = 30,
                   geom = "ridgeline_3d") +
  coord_3d()

Description

geom_segment_3d() and stat_segment_3d() draw line segments in 3D space with automatic depth-based linewidth scaling and proper depth sorting. Each segment is defined by start coordinates (x, y, z) and end coordinates (xend, yend, zend).

Usage

geom_segment_3d(
  mapping = NULL,
  data = NULL,
  stat = StatSegment3D,
  position = "identity",
  ...,
  sort_method = "painter",
  scale_depth = TRUE,
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_segment_3d(
  mapping = NULL,
  data = NULL,
  geom = GeomSegment3D,
  position = "identity",
  ...,
  sort_method = "painter",
  scale_depth = TRUE,
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A Layer object that can be added to a ggplot.

Aesthetics

geom_segment_3d() understands the following aesthetics:

• x, y, z: Start coordinates (required)

• xend, yend, zend: End coordinates (required)

• colour: Line color

• linewidth: Line width (gets depth-scaled when scale_depth = TRUE)

• linetype: Line type

• alpha: Transparency

See Also

geom_path_3d() for connected paths.

Examples

# Basic 3D segments
ggplot(sphere_points,
      aes(x, y, z, xend = 0, yend = 0, zend = 0)) +
  geom_segment_3d() +
  coord_3d()

# 3D vector field
data <- expand.grid(x = -1:2, y = -1:2, z = -1:2)
data2 <- data + seq(-.5, .5, length.out = length(as.matrix(data)))
data <- cbind(data, setNames(data2, c("x2", "y2", "z2")))
ggplot(data, aes(x, y, z,
      xend = x2, yend = y2, zend = z2, color = x)) +
  geom_segment_3d(arrow = arrow(length = unit(0.1, "inches"),
                  type = "closed", angle = 15),
                  linewidth = .5) +
  coord_3d()

Description

A 3D version of ggplot2::geom_smooth(). Creates surfaces by fitting smoothing models to scattered (x,y,z) data points. The fitted statistical model is evaluated on a regular grid and rendered as a 3D surface with optional standard error surfaces.

Usage

geom_smooth_3d(
  mapping = NULL,
  data = NULL,
  stat = StatSmooth3D,
  position = "identity",
  ...,
  method = "loess",
  formula = NULL,
  method.args = list(),
  xlim = NULL,
  ylim = NULL,
  n = NULL,
  grid = NULL,
  direction = NULL,
  trim = NULL,
  domain = c("bbox", "chull"),
  se = FALSE,
  level = 0.95,
  se_fill = NULL,
  se_colour = NULL,
  se_color = NULL,
  se_alpha = 0.5,
  se_linewidth = NULL,
  points = FALSE,
  point_colour = "black",
  point_color = NULL,
  point_fill = NA,
  point_size = 1.5,
  point_shape = 19,
  point_alpha = 1,
  point_stroke = 0.5,
  residuals = FALSE,
  residual_colour = "black",
  residual_color = NULL,
  residual_linewidth = 0.5,
  residual_linetype = 1,
  residual_alpha = 1,
  light = NULL,
  cull_backfaces = FALSE,
  sort_method = NULL,
  force_convex = TRUE,
  scale_depth = TRUE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_smooth_3d(
  mapping = NULL,
  data = NULL,
  geom = GeomPolygon3D,
  position = "identity",
  ...,
  method = "loess",
  formula = NULL,
  method.args = list(),
  xlim = NULL,
  ylim = NULL,
  n = NULL,
  grid = NULL,
  direction = NULL,
  trim = NULL,
  domain = c("bbox", "chull"),
  se = FALSE,
  level = 0.95,
  se_fill = NULL,
  se_colour = NULL,
  se_color = NULL,
  se_alpha = 0.5,
  se_linewidth = NULL,
  points = FALSE,
  point_colour = "black",
  point_color = NULL,
  point_fill = NA,
  point_size = 1.5,
  point_shape = 19,
  point_alpha = 1,
  point_stroke = 0.5,
  residuals = FALSE,
  residual_colour = "black",
  residual_color = NULL,
  residual_linewidth = 0.5,
  residual_linetype = 1,
  residual_alpha = 1,
  light = NULL,
  cull_backfaces = FALSE,
  sort_method = NULL,
  force_convex = TRUE,
  scale_depth = TRUE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A Layer object that can be added to a ggplot.

Aesthetics

stat_smooth_3d() requires the following aesthetics from input data:

• x: X coordinate

• y: Y coordinate

• z: Z coordinate (response variable to be smoothed)

Computed variables specific to StatSmooth3D

• level: Type of surface ("fitted", "upper CI", or "lower CI" for confidence bands)

• fitted: Smoothed predictions (same as z when level == "fitted")

• se: Standard errors of the fitted values (available when se = TRUE)

Computed variables

The following computed variables are available via after_stat():

• x, y, z: Grid coordinates and function values

• normal_x, normal_y, normal_z: Surface normal components

• slope: Gradient magnitude from surface calculations

• aspect: Direction of steepest slope from surface calculations

• dzdx, dzdy: Partial derivatives from surface calculation

See Also

stat_surface_3d() for surfaces from existing grid data, stat_function_3d() for mathematical function surfaces.

Examples

# Generate scattered 3D data
set.seed(123)
d <- data.frame(
  x = runif(100, -1, 3),
  y = runif(100, -3, 3)
)
d$z <- abs(1 + d$x^2 - d$y^2 + rnorm(100, 0, 1))

# Base plot
p <- ggplot(d, aes(x, y, z)) +
  coord_3d(light = NULL) +
  scale_fill_viridis_c()

# Basic smooth surface with default loess model
p + geom_smooth_3d()



# Show data points
p + geom_smooth_3d(points = TRUE)

# Show data points with residual lines
p + geom_smooth_3d(points = TRUE, residuals = TRUE,
      point_color = "red", alpha = .8)

# Linear model surface with 90% confidence intervals
p + geom_smooth_3d(aes(fill = after_stat(level)),
      method = "lm", color = "black", se = TRUE,
      level = 0.99, se_alpha = .7, n = 10) +
      scale_fill_manual(values = c("red", "darkorchid4", "steelblue"))

# Linear model surface with custom model formula
p + geom_smooth_3d(method = "lm", n = 10,
      formula = z ~ poly(x, 2) + poly(y, 2) + x:y)

# Loess with custom span parameter, and lighting effects
p + geom_smooth_3d(
      method = "loess", method.args = list(span = 0.3),
      fill = "steelblue", color = "white", n = 20,
      light = light(direction = c(0, -1, 0), color = FALSE))

# GLM with gamma family and log link
p + geom_smooth_3d(
      method = "glm", n = 10,
      method.args = list(family = Gamma(link = "log")),
      formula = z ~ poly(x, 2) + poly(y, 2))

# Visualize uncertainty with computed "standard error" variable
p + geom_smooth_3d(aes(fill = after_stat(se * 2))) +
  scale_fill_viridis_c()

# Extend surface beyond training data range (explicit extrapolation)
p + geom_smooth_3d(method = "lm", xlim = c(-5, 5), ylim = c(-5, 5))

# Clip surface to predictor convex hull
# to prevent extrapolation into corner areas
p + geom_smooth_3d(method = "lm", domain = "chull")

# Specify alternative grid geometry
p + geom_smooth_3d(grid = "right1", n = 30, direction = "y")

# Separate fits for data subgroups
ggplot(mtcars, aes(wt, mpg, qsec, fill = factor(cyl))) +
  geom_smooth_3d(method = "lm", alpha = .7,
    xlim = c(0, 5), ylim = c(0, 40)) + # specify shared domain
  coord_3d() + theme_light()

Description

geom_text_3d() renders text labels in 3D space. Two rendering methods are available: "billboard" (default) renders text as flat labels that always face the camera, while "polygon" renders text as filled polygons that can be oriented in any direction.

Usage

geom_text_3d(
  mapping = NULL,
  data = NULL,
  position = "identity",
  ...,
  method = c("billboard", "polygon"),
  facing = "zmax",
  coord = NULL,
  aspect_adjust = 1,
  light = "none",
  angle = 0,
  nudge_x = 0,
  nudge_y = 0,
  nudge_z = 0,
  size = 3.88,
  hjust = 0.5,
  vjust = 0.5,
  lineheight = 1.2,
  scale_depth = TRUE,
  family = "sans",
  weight = "normal",
  italic = FALSE,
  fontface = "plain",
  spacing = 0,
  tolerance = 0.01,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_text_3d(
  mapping = NULL,
  data = NULL,
  geom = NULL,
  position = "identity",
  ...,
  method = c("billboard", "polygon"),
  facing = "zmax",
  coord = NULL,
  aspect_adjust = 1,
  light = "none",
  angle = 0,
  nudge_x = 0,
  nudge_y = 0,
  nudge_z = 0,
  size = 3.88,
  hjust = 0.5,
  vjust = 0.5,
  lineheight = 1.2,
  scale_depth = TRUE,
  family = "sans",
  weight = "normal",
  italic = FALSE,
  fontface = "plain",
  spacing = 0,
  tolerance = 0.01,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer

Methods

• "billboard" (default): Fast, simple text rendering using native fonts. Text is always parallel to the view plane (like a billboard). Only uses the colour aesthetic for text color.

• "polygon": Renders text as filled polygon outlines. Text can be oriented to face any direction using the facing parameter. Uses both fill (text fill) and colour (text outline) aesthetics.

Orientation (polygon method only)

The facing parameter controls which direction the text faces:

• "zmax" (default): Text faces upward (readable from above)

• "xmin", "xmax", "ymin", "ymax", "zmin": Text faces toward the specified cube face

• A numeric vector c(x, y, z): Text faces the specified direction

• camera_facing(...): Text faces the camera

The angle parameter rotates the text around its facing axis (in degrees). With angle = 0, the text baseline is oriented as horizontally as possible (parallel to the x-y plane when the facing direction allows).

Camera-facing text

For billboard method, text automatically faces the camera - no configuration needed.

For polygon method, there are two ways to make text face the camera:

1. Use facing = "camera" with the coord parameter (recommended):

my_coord <- coord_3d(pitch = 20, roll = -60, yaw = -30)
ggplot(df, aes(x, y, z = z, label = label)) +
  geom_text_3d(method = "polygon", facing = "camera", coord = my_coord) +
  my_coord

1. Pass camera_facing() directly to facing:

ggplot(df, aes(x, y, z = z, label = label)) +
  geom_text_3d(method = "polygon",
               facing = camera_facing(pitch = 20, roll = -60, yaw = -30)) +
  coord_3d(pitch = 20, roll = -60, yaw = -30)

Aspect Ratio Correction

For polygon method, text can appear stretched if the x, y, and z axes have different data ranges. Providing a coord_3d() object via the coord parameter enables automatic aspect ratio correction based on the coord's ratio and scales settings.

If other layers in your plot have different data ranges that affect the final scale limits, you can fine-tune the correction with aspect_adjust:

• aspect_adjust = 1 (default): Use the computed correction

• aspect_adjust > 1: Make text taller

• aspect_adjust < 1: Make text wider

Size and Scaling

Text size is specified in mm via the size parameter, matching the units used by ggplot2::geom_text(). The default size of 3.88 corresponds to approximately 11pt text.

Both methods use the same size units, so switching between "billboard" and "polygon" methods with the same size value will produce similarly sized text (assuming a typical 6 inch plot).

When scale_depth = TRUE (the default), text farther from the viewer appears smaller, creating a natural perspective effect. For billboard method, this scales the font size. For polygon method, this scales the outline linewidth (the polygon fill is always depth-scaled by the 3D projection).

Aesthetics

geom_text_3d() understands the following aesthetics (required in bold):

Both methods:

• x, y, z, label

• alpha

Billboard method only:

• colour - text color

Polygon method only:

• fill - text fill color

• colour - text outline color

• linewidth - outline thickness

• linetype - outline line type

• group

Other text properties (size, hjust, vjust, angle, family, fontface, lineheight, and for the polygon method weight, italic, spacing, tolerance) are currently accepted only as fixed values passed as arguments to geom_text_3d(), not as mappable aesthetics in aes().

See Also

camera_facing() for camera-facing specifications, text_outlines() for text-to-polygon conversion

Examples

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)

# Billboard text (default) - automatically faces camera
ggplot(df, aes(x, y, z, label = label)) +
  geom_text_3d() +
  coord_3d(scales = "fixed")

# Polygon text - can face any direction
ggplot(df, aes(x, y, z, label = label, fill = z)) +
  geom_text_3d(method = "polygon", facing = "zmax") +
  coord_3d(scales = "fixed")

# Polygon text facing camera (using coord parameter)
my_coord <- coord_3d(pitch = 0, roll = -60, yaw = -30, scales = "fixed")
ggplot(df, aes(x, y, z, label = label)) +
  geom_text_3d(method = "polygon", facing = "camera", coord = my_coord,
               color = "red", linewidth = .1) +
  my_coord

# Text with styling
ggplot(df, aes(x, y, z, label = label, fill = factor(x))) +
  geom_text_3d(method = "polygon", facing = "xmin",
               family = "serif", weight = "bold", italic = TRUE,
               size = 6, aspect_adjust = 2) +
  coord_3d(scales = "fixed")

Description

Creates 3D voxel visualizations from sparse 3D point data. Each data point becomes a fixed-size cube centered on its coordinates. Useful for volumetric data and 3D pixel art.

Usage

geom_voxel_3d(
  mapping = NULL,
  data = NULL,
  stat = StatVoxel3D,
  position = "identity",
  ...,
  width = 1,
  faces = "all",
  light = NULL,
  cull_backfaces = TRUE,
  sort_method = NULL,
  scale_depth = TRUE,
  force_convex = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_voxel_3d(
  mapping = NULL,
  data = NULL,
  geom = GeomPolygon3D,
  position = "identity",
  ...,
  width = 1,
  faces = "all",
  light = NULL,
  cull_backfaces = TRUE,
  sort_method = NULL,
  scale_depth = TRUE,
  force_convex = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Details

Note that voxel geometries sometimes require pairwise depth sorting for correct rendering. This is the default for smaller data sets, but not for larger data sets due to compute speed; in those cases you may wish to manually specify sort_method = "pairwise".

Value

A Layer object that can be added to a ggplot.

Aesthetics

Voxel 3D requires the following aesthetics:

• x: X coordinate (voxel center position)

• y: Y coordinate (voxel center position)

• z: Z coordinate (voxel center position)

Computed variables

• normal_x, normal_y, normal_z: Face normal components

• voxel_id: Sequential voxel number

• face_type: Face name ("zmax", "xmin", etc.)

See Also

stat_col_3d() for variable-height columns, stat_surface_3d() for smooth surfaces, coord_3d() for 3D coordinate systems, light() for lighting specifications.

Examples

# Sparse 3D voxel data
voxel_data <- data.frame(
  x = round(rnorm(100, 0, 2)),
  y = round(rnorm(100, 0, 2)),
  z = round(rnorm(100, 0, 2))
)

p <- ggplot(voxel_data, aes(x, y, z)) + coord_3d()

# Basic 3D voxel plot
p + geom_voxel_3d(fill = "steelblue")

# With aesthetic fill
p + stat_voxel_3d(aes(fill = z)) +
  scale_fill_viridis_c() +
  guides(fill = guide_colorbar_3d())

# Show only some voxel faces
p + geom_voxel_3d(fill = "steelblue",
                  faces = c("zmax", "ymin", "xmin"))

Description

Parameters defining the geometry, resolution, and orientation of a regular grid of surface tiles, as used by various ggcube layer functions including geom_smooth_3d(), geom_function_3d(), geom_density_3d(), and geom_surface_3d().

Arguments