3D line segments

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",
  ...,
  annotate = deprecated(),
  sort_method = deprecated(),
  scale_depth = TRUE,
  on_top = FALSE,
  arrow = NULL,
  arrow.fill = 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 = deprecated(),
  scale_depth = TRUE,
  arrow = NULL,
  arrow.fill = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

mapping

Set of aesthetic mappings created by aes(). Requires x, y, z for start coordinates and xend, yend, zend for end coordinates.

data

The data to be displayed in this layer.

stat

The statistical transformation to use on the data. Defaults to "segment_3d".

position

Position adjustment, defaults to "identity".

...

Other arguments passed on to ggplot2::layer().

annotate

Deprecated. Add annotations to the plot with + annotate_3d() instead. All 3D layers in a panel are depth-sorted together, so annotations no longer need to be embedded in a layer.

sort_method

Deprecated. All 3D layers in a panel are now depth-sorted together, pairwise, so this has no effect. See sorting_methods.

scale_depth

Controls depth-based scaling, drawing closer elements larger or thicker and farther ones smaller or thinner. TRUE (the default) applies full scaling and FALSE disables it; a number sets the strength directly, where 1 matches TRUE, 0 matches FALSE, values below 1 subdue the effect and values above 1 exaggerate it. This affects the layer only; use coord_3d(scale_depth = ) for panel and axis components.

on_top

If TRUE, the layer is drawn on top of the rest of the scene instead of being depth-sorted with it, so other geometry never hides or cuts it, e.g. to keep labels legible. The layers drawn on top are depth-sorted among themselves. Default FALSE.

arrow

Specification for arrow heads, created by arrow().

arrow.fill

Fill colour for closed arrowheads. Defaults to the segment colour.

lineend

Line end style, one of "round", "butt", "square".

na.rm

If FALSE, missing values are removed with a warning.

show.legend

Logical indicating whether this layer should be included in legends.

inherit.aes

If FALSE, overrides the default aesthetics.

geom

The geometric object used to display the data. Defaults to "segment_3d".

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()