% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geom-polygon-3d.R
\name{geom_polygon_3d}
\alias{geom_polygon_3d}
\title{3D polygon geometry with depth sorting}
\usage{
geom_polygon_3d(
  mapping = NULL,
  data = NULL,
  stat = StatIdentity3D,
  position = "identity",
  ...,
  rule = "evenodd",
  sort_method = "auto",
  scale_depth = TRUE,
  force_convex = FALSE,
  cull_backfaces = FALSE,
  light = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)
}
\arguments{
\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}.}

\item{data}{The data to be displayed in this layer. Note that if you specify \code{light} or
\code{cull_backfaces}, behavior will depend on the "winding order" of polygon vertices, with
the counter-clockwise face considered the "front".}

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

\item{position}{Position adjustment, defaults to "identity". To collapse the result
onto one 2D surface, use \code{position_on_face()}.}

\item{...}{Other arguments passed on to the layer function (typically GeomPolygon3D), such as
aesthetics like \code{colour}, \code{fill}, \code{linewidth}, \code{annotate = annotate_3d(...)}, etc.}

\item{rule}{Either \code{"evenodd"} or \code{"winding"}. If polygons with holes are
being drawn (using the \code{subgroup} aesthetic) this argument defines how the
hole coordinates are interpreted. See \code{\link[ggplot2:geom_polygon]{ggplot2::geom_polygon()}} for reference.}

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

\item{scale_depth}{Controls whether polygon linewidths are scaled to make closer lines
wider and farther lines narrower, based on the mean depth of a polygon. \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 gridlines, cube borders, axis ticks,
and axis text.}

\item{force_convex}{Logical indicating whether to remove polygon vertices that are not part of the
convex hull. Default value varies by geom. Specifying TRUE can help reduce artifacts in surfaces
that have polygon tiles that wrap over a visible horizon. For prism-type geoms like columns and
voxels, FALSE is safe because polygons fill always be convex.}

\item{cull_backfaces}{Logical indicating whether to remove back-facing polygons
from rendering. This is primarily for performance optimization but may be useful
for aesthetic reasons in some situations. Backfaces are determined using
screen-space winding order after 3D transformation. Defaults vary by geometry
type: FALSE for open surface-type geometries, TRUE for solid objects (hulls,
voxels, etc. where backfaces are generally hidden unless frontfaces are transparent
or explicitly disabled).}

\item{light}{A lighting specification object created by \code{\link[=light]{light()}}, \code{light("none")}
or the string \code{"none"} to disable lighting, or \code{NULL} to inherit plot-level
lighting. Set plot-level lighting by adding \code{\link[=light]{light()}} to the plot, and
layer-specific lighting via the \code{light} argument of \verb{geom_*_3d()} functions,
which takes precedence.}

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

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

\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics.}
}
\value{
A \code{Layer} object that can be added to a ggplot.
}
\description{
\code{geom_polygon_3d()} renders 3D polygons with proper depth sorting for realistic
3D surface visualization. It's designed to work with surface data
from \code{\link[=stat_hull_3d]{stat_hull_3d()}} and \code{\link[=stat_surface_3d]{stat_surface_3d()}}, as well as regular polygon data like maps.
}
\section{Aesthetics}{

\code{geom_polygon_3d()} requires:
\itemize{
\item \strong{x}: X coordinate
\item \strong{y}: Y coordinate
\item \strong{z}: Z coordinate (for depth sorting)
\item \strong{group}: Polygon grouping variable
}

And understands these additional aesthetics:
\itemize{
\item \code{fill}: Polygon fill color
\item \code{colour}: Border color
\item \code{linewidth}: Border line width
\item \code{linetype}: Border line type
\item \code{alpha}: Transparency
\item \code{subgroup}: Secondary grouping for polygons with holes
\item \code{order}: Vertex order within polygons (for proper polygon construction)
}
}

\examples{
# Typically used via stats such as stat_surface_3d() or stat_hull_3d()
ggplot(sphere_points, aes(x, y, z)) +
  stat_hull_3d(method = "convex", fill = "dodgerblue",
            light = light(fill = TRUE, mode = "hsl")) +
  coord_3d()

# Can be used directly with properly structured data
triangles <- data.frame(x = rep(c(3, 2, 1), 3),
                            y = rep(c(1, 3, 1), 3),
                            z = rep(1:3, each = 3),
                            shape = rep(letters[1:3], each = 3))
ggplot(triangles, aes(x, y, z, fill = shape)) +
  geom_polygon_3d(color = "black") +
  coord_3d()

# Use `sort_method` to choose between depth sorting algorithms
d <- data.frame(group = rep(letters[1:3], each = 4),
                x = c(1, 1, 2, 2,   1, 1, 3, 3,   2, 2, 3, 3),
                y = rep(c(1, 2, 2, 1), 3),
                z = rep(c(1, 1.5, 2), each = 4))
p <- ggplot(d, aes(x, y, z, group = group, fill = group)) +
      coord_3d(pitch = 50, roll = 20, yaw = 0,
               scales = "fixed", light = "none") +
      theme_light()

# fast, but rendering order is incorrect in this particular example
p + geom_polygon_3d(color = "black", linewidth = 1, alpha = .75,
      sort_method = "painter")

# correct rendering order (but slower for large data sets)
p + geom_polygon_3d(color = "black", linewidth = 1, alpha = .75,
      sort_method = "pairwise")

}
