Skip to contents

3D line segments with depth-based scaling and proper depth sorting

Source: R/geom-segment-3d.R
geom_segment_3d.Rd

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

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 StatSegment3D for proper discrete scale handling.

position

Position adjustment, defaults to "identity".

...

Other arguments passed on to layer().

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.

scale_depth

Logical indicating whether to apply depth-based scaling to linewidth. When TRUE (default), segments closer to the viewer appear thicker, and segments farther away appear thinner.

arrow

Specification for arrow heads, created by arrow().

lineend

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

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, geom_segment() for 2D segments, coord_3d() for 3D coordinate systems.

Examples

library(ggplot2)

# Basic 3D segments
segments_data <- data.frame(
  x = c(0, 1, 2), y = c(0, 1, 2), z = c(0, 1, 2),
  xend = c(1, 2, 3), yend = c(1, 2, 3), zend = c(1, 2, 3)
)

ggplot(segments_data, aes(x, y, z, xend = xend, yend = yend, zend = zend)) +
  geom_segment_3d() +
  coord_3d()


# With different colors and arrow heads
ggplot(segments_data, aes(x, y, z, xend = xend, yend = yend, zend = zend,
                         color = factor(1:3))) +
  geom_segment_3d(arrow = arrow(length = unit(0.2, "inches")),
                  linewidth = 2) +
  coord_3d()