% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geom-segment-3d.R
\name{geom_segment_3d}
\alias{geom_segment_3d}
\alias{stat_segment_3d}
\title{3D line segments}
\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{
\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. Requires x, y, z
for start coordinates and xend, yend, zend for end coordinates.}

\item{data}{The data to be displayed in this layer.}

\item{stat}{The statistical transformation to use on the data. Defaults to \code{"segment_3d"}.}

\item{position}{Position adjustment, defaults to "identity".}

\item{...}{Other arguments passed on to \code{\link[ggplot2:layer]{ggplot2::layer()}}.}

\item{sort_method}{Depth sorting algorithm. See \link{sorting_methods} for details.}

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

\item{arrow}{Specification for arrow heads, created by \code{\link[=arrow]{arrow()}}.}

\item{lineend}{Line end style, one of "round", "butt", "square".}

\item{na.rm}{If \code{FALSE}, missing values are removed with a warning.}

\item{show.legend}{Logical indicating whether this layer should be included in legends.}

\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics.}

\item{geom}{The geometric object used to display the data. Defaults to \code{"segment_3d"}.}
}
\value{
A \code{Layer} object that can be added to a ggplot.
}
\description{
\code{geom_segment_3d()} and \code{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).
}
\section{Aesthetics}{

\code{geom_segment_3d()} understands the following aesthetics:
\itemize{
\item \strong{x, y, z}: Start coordinates (required)
\item \strong{xend, yend, zend}: End coordinates (required)
\item \code{colour}: Line color
\item \code{linewidth}: Line width (gets depth-scaled when \code{scale_depth = TRUE})
\item \code{linetype}: Line type
\item \code{alpha}: Transparency
}
}

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

}
\seealso{
\code{\link[=geom_path_3d]{geom_path_3d()}} for connected paths.
}
