% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/annotate-3d.R
\name{annotate_3d}
\alias{annotate_3d}
\title{Create a 3D annotation specification}
\usage{
annotate_3d(type, ...)
}
\arguments{
\item{type}{Character string specifying the annotation type. One of
\code{"point"}, \code{"text"}, or \code{"segment"}.}

\item{...}{Type-specific parameters. See Details.}
}
\value{
An S3 object of class \code{"annotate_3d"}.
}
\description{
Defines fixed-position annotations to be embedded within a 3D layer.
Annotations are depth-sorted together with the primary geometry, unlike
ggplot2's \code{annotate()} which creates a separate layer.
}
\details{
Parameters can be vectors to create multiple annotations of the same type
in one call, with scalar values recycled as needed (matching
\code{ggplot2::annotate()} behaviour).
\subsection{Point annotations}{

Requires \code{x}, \code{y}, \code{z}. Optional styling: \code{colour}/\code{color}, \code{fill}, \code{size},
\code{shape}, \code{alpha}, \code{stroke}.
}

\subsection{Text annotations}{

Requires \code{x}, \code{y}, \code{z}, \code{label}. Optional styling: \code{colour}/\code{color}, \code{size},
\code{alpha}, \code{family}, \code{fontface}, \code{hjust}, \code{vjust}, \code{angle}, \code{lineheight}.
}

\subsection{Segment annotations}{

Requires \code{x}, \code{y}, \code{z}, \code{xend}, \code{yend}, \code{zend}. Optional styling:
\code{colour}/\code{color}, \code{linewidth}, \code{linetype}, \code{alpha}.
}
}
\examples{
p <- ggplot(mountain, aes(x, y, z)) +
  coord_3d(ratio = c(2, 3, 1),
           light = light(mode = "hsl", direction = c(-1, 0, 0)))

# Basic point annotation
p + geom_surface_3d(
  annotate = annotate_3d("point", x = .5, y = .25, z = 100,
                         color = "red", size = 3))

# Vectorized: multiple points in one call
p + geom_surface_3d(
  annotate = annotate_3d("point", x = .5, y = .25, z = seq(50, 100, 5),
                         color = "red", size = 3))

# Multiple annotation types
p + geom_surface_3d(
  annotate = list(
    annotate_3d("point", x = .5, y = .25, z = 100,
                color = "red", size = 3),
    annotate_3d("text", x = .5, y = .25, z = 100,
                color = "red", label = "Look here!",
                vjust = -1, fontface = "bold"),
    annotate_3d("segment", x = .5, y = .25, z = 100,
                xend = .5, yend = .25, zend = 50,
                color = "red", size = 3)))

}
