% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geom-text-3d.R
\name{geom_text_3d}
\alias{geom_text_3d}
\alias{stat_text_3d}
\title{3D text labels}
\usage{
geom_text_3d(
  mapping = NULL,
  data = NULL,
  position = "identity",
  ...,
  method = c("billboard", "polygon"),
  facing = "zmax",
  coord = NULL,
  aspect_adjust = 1,
  light = "none",
  angle = 0,
  nudge_x = 0,
  nudge_y = 0,
  nudge_z = 0,
  size = 3.88,
  hjust = 0.5,
  vjust = 0.5,
  lineheight = 1.2,
  scale_depth = TRUE,
  family = "sans",
  weight = "normal",
  italic = FALSE,
  fontface = "plain",
  spacing = 0,
  tolerance = 0.01,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_text_3d(
  mapping = NULL,
  data = NULL,
  geom = NULL,
  position = "identity",
  ...,
  method = c("billboard", "polygon"),
  facing = "zmax",
  coord = NULL,
  aspect_adjust = 1,
  light = "none",
  angle = 0,
  nudge_x = 0,
  nudge_y = 0,
  nudge_z = 0,
  size = 3.88,
  hjust = 0.5,
  vjust = 0.5,
  lineheight = 1.2,
  scale_depth = TRUE,
  family = "sans",
  weight = "normal",
  italic = FALSE,
  fontface = "plain",
  spacing = 0,
  tolerance = 0.01,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)
}
\arguments{
\item{mapping}{Set of aesthetic mappings. See \code{\link[ggplot2:aes]{ggplot2::aes()}}.}

\item{data}{A data frame containing the variables to plot.}

\item{position}{Position adjustment. Defaults to \code{"identity"}.}

\item{...}{Other arguments passed to the layer.}

\item{method}{Rendering method: \code{"billboard"} (default) for flat camera-facing
text, or \code{"polygon"} for 3D-oriented filled text.}

\item{facing}{(Polygon method only) Direction the text should face. One of
\code{"xmin"}, \code{"xmax"}, \code{"ymin"}, \code{"ymax"}, \code{"zmin"}, \code{"zmax"} (default),
\code{"camera"}, a numeric vector of length 3, or a \code{camera_facing()} specification.
Use \code{"camera"} with the \code{coord} parameter to automatically face the camera.
Ignored with a warning for billboard method.}

\item{coord}{(Polygon method only) A \code{coord_3d()} object. When provided:
(1) if \code{facing = "camera"}, extracts rotation parameters automatically;
(2) uses the coord's \code{ratio} and \code{scales} parameters to correct text aspect
ratio so text doesn't appear stretched. Ignored for billboard method.}

\item{aspect_adjust}{(Polygon method only) Scalar multiplier for text height
relative to width. Default is 1 (normal proportions). Values > 1 make text
taller, values < 1 make text wider. When \code{coord} is provided, this is
multiplied by the computed aspect correction. Ignored for billboard method.}

\item{light}{(Polygon method only) Either a lighting specification created by
\code{\link[=light]{light()}}, \code{"none"} (the default) for no lighting, or \code{NULL} to inherit
plot-level lighting from \code{coord_3d()}. When provided, text polygons are
shaded based on their facing direction. Ignored for billboard method.}

\item{angle}{Rotation angle in degrees. For polygon method, rotates around
the facing axis. For billboard method, rotates in the view plane.}

\item{nudge_x, nudge_y, nudge_z}{Offset to apply to text position in data units.}

\item{size}{Font size in mm (same units as \code{\link[ggplot2:geom_text]{ggplot2::geom_text()}}). Default
is 3.88, which corresponds to approximately 11pt text.}

\item{hjust, vjust}{Horizontal and vertical justification of text (0-1).}

\item{lineheight}{Line height multiplier for multi-line text.}

\item{scale_depth}{Logical; if TRUE (default), scale by depth for perspective
effect. For billboard method, this scales the font size. For polygon method,
this scales the outline linewidth (the polygon fill is always depth-scaled
by the 3D projection).}

\item{family}{Font family.}

\item{weight}{(Polygon method only) Font weight: "normal", "bold", "thin",
"light", etc.}

\item{italic}{(Polygon method only) Logical; use italic font variant.}

\item{fontface}{Font face (for billboard method): "plain", "bold", "italic",
or "bold.italic".}

\item{spacing}{(Polygon method only) Additional letter spacing in em units.}

\item{tolerance}{(Polygon method only) Bezier curve tolerance for text
outlines. Lower values give smoother curves but more vertices.}

\item{na.rm}{If TRUE, silently remove missing values.}

\item{show.legend}{Logical. Should this layer be included in the legends?}

\item{inherit.aes}{If TRUE, inherit aesthetics from the plot's default.}

\item{geom}{The geometric object to use. Defaults based on method.}
}
\value{
A ggplot2 layer
}
\description{
\code{geom_text_3d()} renders text labels in 3D space. Two rendering methods are
available: \code{"billboard"} (default) renders text as flat labels that always
face the camera, while \code{"polygon"} renders text as filled polygons that can
be oriented in any direction.
}
\section{Methods}{

\itemize{
\item \code{"billboard"} (default): Fast, simple text rendering using native
fonts. Text is always parallel to the view plane (like a billboard).
Only uses the \code{colour} aesthetic for text color.
\item \code{"polygon"}: Renders text as filled polygon outlines. Text can be
oriented to face any direction using the \code{facing} parameter. Uses both
\code{fill} (text fill) and \code{colour} (text outline) aesthetics.
}
}

\section{Orientation (polygon method only)}{

The \code{facing} parameter controls which direction the text faces:
\itemize{
\item \code{"zmax"} (default): Text faces upward (readable from above)
\item \code{"xmin"}, \code{"xmax"}, \code{"ymin"}, \code{"ymax"}, \code{"zmin"}: Text faces
toward the specified cube face
\item A numeric vector \code{c(x, y, z)}: Text faces the specified direction
\item \code{camera_facing(...)}: Text faces the camera
}

The \code{angle} parameter rotates the text around its facing axis (in degrees).
With \code{angle = 0}, the text baseline is oriented as horizontally as possible
(parallel to the x-y plane when the facing direction allows).
}

\section{Camera-facing text}{

For billboard method, text automatically faces the camera - no configuration
needed.

For polygon method, there are two ways to make text face the camera:
\enumerate{
\item Use \code{facing = "camera"} with the \code{coord} parameter (recommended):
}

\if{html}{\out{<div class="sourceCode">}}\preformatted{my_coord <- coord_3d(pitch = 20, roll = -60, yaw = -30)
ggplot(df, aes(x, y, z = z, label = label)) +
  geom_text_3d(method = "polygon", facing = "camera", coord = my_coord) +
  my_coord
}\if{html}{\out{</div>}}
\enumerate{
\item Pass \code{camera_facing()} directly to \code{facing}:
}

\if{html}{\out{<div class="sourceCode">}}\preformatted{ggplot(df, aes(x, y, z = z, label = label)) +
  geom_text_3d(method = "polygon",
               facing = camera_facing(pitch = 20, roll = -60, yaw = -30)) +
  coord_3d(pitch = 20, roll = -60, yaw = -30)
}\if{html}{\out{</div>}}
}

\section{Aspect Ratio Correction}{

For polygon method, text can appear stretched if the x, y, and z axes have
different data ranges. Providing a \code{coord_3d()} object via the \code{coord}
parameter enables automatic aspect ratio correction based on the coord's
\code{ratio} and \code{scales} settings.

If other layers in your plot have different data ranges that affect the
final scale limits, you can fine-tune the correction with \code{aspect_adjust}:
\itemize{
\item \code{aspect_adjust = 1} (default): Use the computed correction
\item \code{aspect_adjust > 1}: Make text taller
\item \code{aspect_adjust < 1}: Make text wider
}
}

\section{Size and Scaling}{

Text size is specified in mm via the \code{size} parameter, matching the units
used by \code{\link[ggplot2:geom_text]{ggplot2::geom_text()}}. The default size of 3.88 corresponds to
approximately 11pt text.

Both methods use the same size units, so switching between \code{"billboard"}
and \code{"polygon"} methods with the same \code{size} value will produce similarly
sized text (assuming a typical 6 inch plot).

When \code{scale_depth = TRUE} (the default), text farther from the viewer
appears smaller, creating a natural perspective effect. For billboard
method, this scales the font size. For polygon method, this scales the
outline linewidth (the polygon fill is always depth-scaled by the 3D
projection).
}

\section{Aesthetics}{

\code{geom_text_3d()} understands the following aesthetics (required in bold):

\strong{Both methods:}
\itemize{
\item \strong{x}, \strong{y}, \strong{z}, \strong{label}
\item \code{alpha}
}

\strong{Billboard method only:}
\itemize{
\item \code{colour} - text color
}

\strong{Polygon method only:}
\itemize{
\item \code{fill} - text fill color
\item \code{colour} - text outline color
\item \code{linewidth} - outline thickness
\item \code{linetype} - outline line type
\item \code{group}
}

Other text properties (\code{size}, \code{hjust}, \code{vjust}, \code{angle}, \code{family},
\code{fontface}, \code{lineheight}, and for the polygon method \code{weight}, \code{italic},
\code{spacing}, \code{tolerance}) are currently accepted only as fixed values passed
as arguments to \code{geom_text_3d()}, not as mappable aesthetics in \code{aes()}.
}

\examples{
df <- expand.grid(x = c("B", "H", "N"), y = c("a", "o", "u"), z = c("g", "t"))
df$label <- paste0(df$x, df$y, df$z)

# Billboard text (default) - automatically faces camera
ggplot(df, aes(x, y, z, label = label)) +
  geom_text_3d() +
  coord_3d(scales = "fixed")

# Polygon text - can face any direction
ggplot(df, aes(x, y, z, label = label, fill = z)) +
  geom_text_3d(method = "polygon", facing = "zmax") +
  coord_3d(scales = "fixed")

# Polygon text facing camera (using coord parameter)
my_coord <- coord_3d(pitch = 0, roll = -60, yaw = -30, scales = "fixed")
ggplot(df, aes(x, y, z, label = label)) +
  geom_text_3d(method = "polygon", facing = "camera", coord = my_coord,
               color = "red", linewidth = .1) +
  my_coord

# Text with styling
ggplot(df, aes(x, y, z, label = label, fill = factor(x))) +
  geom_text_3d(method = "polygon", facing = "xmin",
               family = "serif", weight = "bold", italic = TRUE,
               size = 6, aspect_adjust = 2) +
  coord_3d(scales = "fixed")

}
\seealso{
\code{\link[=camera_facing]{camera_facing()}} for camera-facing specifications, \code{\link[=text_outlines]{text_outlines()}}
for text-to-polygon conversion
}
