% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geom-zcontour-3d.R
\name{geom_contour_3d}
\alias{geom_contour_3d}
\alias{stat_contour_3d}
\title{Contours of a 3D surface}
\usage{
geom_contour_3d(
  mapping = NULL,
  data = NULL,
  stat = "surface_3d",
  position = "identity",
  ...,
  bins = 20,
  binwidth = NULL,
  breaks = NULL,
  cull_backfaces = FALSE,
  sort_method = "pairwise",
  scale_depth = TRUE,
  force_convex = FALSE,
  light = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_contour_3d(
  mapping = NULL,
  data = NULL,
  geom = "contour_3d",
  position = "identity",
  ...,
  bins = 20,
  binwidth = NULL,
  breaks = NULL,
  cull_backfaces = FALSE,
  sort_method = "pairwise",
  scale_depth = TRUE,
  force_convex = 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}{Point grid data with x, y, z coordinates.}

\item{stat}{Statistical transformation. Defaults to \code{"surface_3d"}.}

\item{position}{Position adjustment, defaults to "identity".}

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

\item{bins}{Number of contour levels. Default is 20. Ignored if \code{breaks} or
\code{binwidth} is provided.}

\item{binwidth}{Width of each contour band. Overrides \code{bins} if provided.}

\item{breaks}{Numeric vector specifying exact contour break points. Overrides
both \code{bins} and \code{binwidth} if provided.}

\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{sort_method}{Depth sorting algorithm. See \link{sorting_methods} for details.}

\item{scale_depth}{Logical indicating whether polygon linewidths should be scaled to make closer lines
wider and farther lines narrower. Default is TRUE. Scaling is based on the mean depth of a polygon.}

\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{light}{A lighting specification object created by \code{\link[=light]{light()}},\code{"none"} to disable
lighting, or \code{NULL} to inherit plot-level lighting specs from the coord. Specify
plot-level lighting in \code{coord_3d()} and layer-specific lighting in \verb{geom_*3d()}
functions.}

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

\item{geom}{Geometry function used to display the data. Defaults to \code{"surface_3d"}.}
}
\value{
A \code{Layer} object that can be added to a ggplot.
}
\description{
Renders a surface as stacked horizontal contour bands. Each contour band is a
polygon placed at its corresponding z-level.
}
\details{
This geom takes point grid data (like that produced by \code{\link[=stat_surface_3d]{stat_surface_3d()}},
\code{\link[=stat_function_3d]{stat_function_3d()}}, \code{\link[=stat_smooth_3d]{stat_smooth_3d()}}, or \code{\link[=stat_density_3d]{stat_density_3d()}}) and converts
it to filled contour polygons using the \code{isoband} package.
}
\section{Aesthetics}{

\code{geom_contour_3d()} requires:
\describe{
\item{x, y, z}{Point coordinates forming a regular grid}
}

And understands these additional aesthetics:
\describe{
\item{fill}{Band fill color. For automatic coloring by elevation, use
\code{aes(fill = after_stat(z))}. Default is "grey60".}
\item{colour}{Band border color (default: "grey30")}
\item{alpha}{Transparency}
\item{linewidth}{Border width (default: 0.1)}
\item{linetype}{Border line type}
}
}

\section{Computed variables}{

Each contour band is placed at its corresponding z-level (the upper boundary
of the band). To color by elevation, use \code{aes(fill = after_stat(z))}.
}

\examples{
# Basic usage with volcano data
ggplot(mountain, aes(x, y, z)) +
      geom_contour_3d(color = "white", fill = "black") +
      coord_3d(light = "none", ratio = c(1.5, 2, 1))

# Map fill to elevation and customize number of levels
ggplot(mountain, aes(x, y, z, fill = after_stat(z))) +
      geom_contour_3d(bins = 12, color = "white") +
      scale_fill_viridis_c() +
      coord_3d(light = "none", ratio = c(1.5, 2, 1))

# Specify exact breaks
ggplot(mountain, aes(x, y, z, fill = after_stat(z))) +
  geom_contour_3d(breaks = seq(0, 200, by = 5)) +
  scale_fill_viridis_c() +
  coord_3d(light = "none")

# With stat_density_3d
ggplot(faithful, aes(eruptions, waiting)) +
  stat_density_3d(geom = "contour_3d",
    sort_method = "pairwise") +
  coord_3d()

# With stat_function_3d
ggplot() +
  stat_function_3d(
    fun = function(x, y) sin(x) * cos(y),
    xlim = c(-pi, pi), ylim = c(-pi, pi),
    geom = "contour_3d",
    bins = 50, color = "black"
  ) +
  scale_fill_viridis_c(option = "B") +
  coord_3d(light = "none")

}
\seealso{
\code{\link[=geom_surface_3d]{geom_surface_3d()}} for continuous surface rendering,
\code{\link[=geom_ridgeline_3d]{geom_ridgeline_3d()}} for cross-sectional ridgeline rendering,
\code{\link[=stat_function_3d]{stat_function_3d()}} for mathematical function surfaces,
\code{\link[=stat_smooth_3d]{stat_smooth_3d()}} for fitted model surfaces,
\code{\link[=coord_3d]{coord_3d()}} for 3D coordinate systems,
\code{\link[ggplot2:geom_contour]{ggplot2::geom_contour_filled()}} for the 2D equivalent.
}
