% 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}{Character indicating algorithm used to determine the order in which
elements are rendered. This controls depth sorting for all geometry types within
a layer, including polygons, points, segments, and text. Default varies by geometry
type.
\itemize{
\item \code{"painter"}: Elements are sorted by the mean depth (distance from
viewer after rotation) of their vertices. This is fast, but can give incorrect
results when primitives overlap in screen space at different depths.
\item \code{"pairwise"}: A more intensive sorting algorithm that compares every
pair of elements to determine occlusion order. Uses type-specific geometric
tests: polygon overlap detection for polygon-polygon pairs, point-in-polygon
tests for polygon-point pairs, line clipping for polygon-segment pairs, and
line intersection for segment-segment pairs. When elements are coplanar,
smaller primitives (points, segments) render on top of larger ones (polygons).
Slower but more accurate.
\item \code{"auto"}: Uses pairwise if the data has fewer than 500 rows, and
painter otherwise.
}}

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

\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.
}
