% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geom-path-3d.R
\name{geom_path_3d}
\alias{geom_path_3d}
\alias{stat_path_3d}
\title{3D paths connecting observations}
\usage{
geom_path_3d(
  mapping = NULL,
  data = NULL,
  stat = StatPath3D,
  position = "identity",
  ...,
  sort_method = "painter",
  scale_depth = TRUE,
  arrow = NULL,
  lineend = "butt",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_path_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
coordinates. Grouping aesthetics determine separate paths.}

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

\item{stat}{The statistical transformation to use on the data. Defaults to \code{"path_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{
Connects observations in 3D space in the order they appear
in the data. It converts path data into individual segments for proper depth
sorting while maintaining the appearance of connected paths. Each path is
divided into segments that can be depth-sorted independently.
}
\section{Aesthetics}{

\code{geom_path_3d()} understands the following aesthetics:
\itemize{
\item \strong{x, y, z}: Coordinates (required)
\item \code{group}: Grouping variable to create separate paths
\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
}
}

\section{Computed variables for StatSegment3D}{

\itemize{
\item \code{x}, \code{y}, \code{z}: Start coordinates of each segment
\item \code{xend}, \code{yend}, \code{zend}: End coordinates of each segment
\item \code{group}: Hierarchical group identifier preserving original grouping
}
}

\section{Grouping}{

Multiple paths are created based on grouping aesthetics (group, colour, etc.).
Each group forms a separate path, and segments from different paths can be
interleaved during depth sorting for proper 3D rendering.
}

\examples{
library(ggplot2)

x <- seq(0, 20*pi, pi/16)
spiral <- data.frame(
  x = x,
  y = sin(x),
  z = cos(x))

# Basic path
ggplot(spiral, aes(x, y, z)) +
  geom_path_3d() +
  coord_3d()

# With aesthetic coloring
ggplot(spiral, aes(x, y, z, color = y)) +
  geom_path_3d(linewidth = 1, lineend = "round") +
  coord_3d() +
  scale_color_gradientn(colors = c("red", "purple", "blue"))

# With grouping
ggplot(spiral, aes(x, y, z, color = x > 30)) +
  geom_path_3d(linewidth = 1, lineend = "round") +
  coord_3d()

}
\seealso{
\code{\link[=geom_segment_3d]{geom_segment_3d()}} for individual segments.
}
