Skip to contents

3D coordinate system

Source: R/coord-3d.R
coord_3d.Rd

coord_3d creates 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 panel selection and axis label placement.

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",
  rotate_labels = TRUE,
  scales = "free",
  ratio = c(1, 1, 1)
)

Arguments

roll, pitch, yaw

Rotation around x, y, and z axes, respectively, in degrees. Positive values rotate the near face of the plot "downward", "rightward", and clockwise, respectively.

persp

Logical indicating whether to apply perspective projection. When TRUE (the default), objects farther from the viewer appear smaller. When FALSE, produces an orthographic projection in which lines that are parallel in 3D space render as parallel in the plot.

dist

Distance from viewer to center of the data cube. Only used when persp = TRUE. Larger values create less perspective distortion. Default is 2. Values less than 1 are allowed but can be problematic for rendering.

expand

Logical indicating whether to expand axis ranges beyond the data range, similar to standard ggplot2 behavior. If TRUE (the default), expansion behavior can be controlled using standard axis scaling functions, e.g. ... + scale_x_continuous(expand = expansion(.5)).

clip

Character string indicating clipping behavior. Use "off" (the default, recommended for some 3D plots) to allow drawing outside the plot panel.

panels

Character string specifying which panels to render. Options include "all", "background", "foreground", "none", or specific panel names like "xmin", "ymax", etc. (Panel styling is handled separately, via the normal theme() approach.)

xlabels, ylabels, zlabels

Character strings or length-2 character vectors specifying axis label (text and title) placement. Each parameter accepts:

  • "auto" (default): Automatic edge selection based on an algorithm that prioritizes edges that are visible on the periphery of the plot and considers several attributes of face geometry for better readability.

  • c("face1", "face2"): Manual edge specification using two adjacent face names (e.g., c("xmin", "ymin") selects the edge shared by the xmin and ymin faces). The first face in the vector determines which face the axis labels will be aligned with, while the second face identifies which edge of this face gets labelled. Available face names are: "xmin", "xmax", "ymin", "ymax", "zmin", "zmax".

rotate_labels

Logical indicating whether axis labels (text and titles) should automatically rotate to align with the projected axis directions. When FALSE, uses theme text and title angle settings.

scales

Character string specifying aspect ratio behavior:

  • "free" (default): Each axis scales independently to fill cube space, then ratio applies to standardized coordinates. This gives maximum visual range for each dimension.

  • "fixed": Maintains proportional relationships in raw data values, as scaled by ratio. Similar to coord_fixed() but for 3D (visual ratios match the labeled axis ranges).

ratio

Numeric vector of length 3 specifying relative axis lengths as c(x, y, z). Defaults to c(1, 1, 1) for equal proportions.

  • With scales = "free": Ratios apply to scaled cube coordinates

  • With scales = "fixed": Ratios apply to original data coordinates

3D Theming

3D plots support additional theme elements beyond standard ggplot2 themes:

Z-axis 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)

Panel elements:

  • panel.foreground: Styling for cube faces rendered in front of data (inherits from 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)

Enhanced elements:

  • element_rect() supports an alpha parameter for transparency effects, particularly useful for panel.foreground

The panels parameter controls which cube faces are rendered, while theme() controls their visual styling. 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.

Examples

library(ggplot2)
p <- ggplot(mtcars, aes(mpg, wt, qsec)) +
  geom_point_3d(fill = "darkred", color = "white",
                stroke = .25, shape = 21, size = 3)

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


# Use `pitch`, `roll`, `yaw` to control plot rotation
p + coord_3d(pitch = 0, roll = 0, yaw = 0) # viewed from x-y face

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

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

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

p + coord_3d(pitch = 10, roll = 20, yaw = 30) # combined use


# Use `persp` and `dist` to control perspective effects
p + coord_3d(dist = 1) # strong perspective effect as if seen from very close

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

p + coord_3d(persp = FALSE) # orthographic projection, effectively dist = Inf


# Use `scales` and `ratio` to modify aspect ratio
p + coord_3d() # Default free scales (maximum visual range)

p + coord_3d(scales = "fixed") # Fixed scales (proportions match data scales, like coord_fixed)

p + coord_3d(scales = "free", ratio = c(1, 2, 1)) # Custom cube ratios (make z twice as tall visually)

p + coord_3d(scales = "fixed", ratio = c(1, 2, 1)) # Custom scale ratios (y gets twice the visual space relative to its data range)


# Use `panels` to select which cube faces to render
# and use `theme()` elements to control their styling
p + coord_3d(panels = c("zmin", "xmax"))

p + coord_3d(panels = "all") +
    theme(panel.background = element_rect(color = "black"),
          panel.foreground = element_rect(alpha = .3),
          panel.grid.foreground = element_line(color = "gray", linewidth = .25))


# Use label parameters to control axis text placement and rotation
p + coord_3d(xlabels = c("ymin", "zmax"))
#> Warning: Neither ymin nor zmax is visible, falling back to auto selection

p + coord_3d(rotate_labels = FALSE)