% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geom-col-3d.R
\name{geom_col_3d}
\alias{geom_col_3d}
\alias{stat_col_3d}
\title{3D columns from grid data}
\usage{
geom_col_3d(
  mapping = NULL,
  data = NULL,
  stat = StatCol3D,
  position = "identity",
  ...,
  width = 1,
  faces = "all",
  zmin = NULL,
  light = NULL,
  cull_backfaces = TRUE,
  sort_method = NULL,
  scale_depth = TRUE,
  force_convex = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_col_3d(
  mapping = NULL,
  data = NULL,
  geom = GeomPolygon3D,
  position = "identity",
  ...,
  width = 1,
  faces = "all",
  zmin = NULL,
  light = NULL,
  cull_backfaces = TRUE,
  sort_method = NULL,
  scale_depth = TRUE,
  force_convex = FALSE,
  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.}

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

\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{width}{Numeric value controlling box width as a fraction of grid spacing.
Default is 1.0 (volumes touch each other). Use 0.8 for small gaps, 1.2 for overlap.
Grid spacing is determined automatically using \code{ggplot2::resolution()}}

\item{faces}{Character vector specifying which faces to render. Options:
\itemize{
\item \code{"all"} (default): Render all 6 faces
\item \code{"none"}: Render no faces
\item Vector of face names: \code{c("zmax", "xmin", "ymax")}, etc.
}
Valid face names: "xmin", "xmax", "ymin", "ymax", "zmin", "zmax".
Note that this setting acts jointly with backface culling, which removes faces whose
interior faces the viewer -- e.g., when \code{cull_backfaces = TRUE} and \code{faces = "all"}
(the default), only front faces are rendered.}

\item{zmin}{Base level for all columns. When provided as a parameter, overrides any
\code{zmin} aesthetic mapping. If \code{NULL} (the default), uses the \code{zmin}
aesthetic if mapped, otherwise defaults to 0.}

\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{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{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}{The geometric object used to display the data. Defaults to \code{GeomPolygon3D}.}
}
\value{
A \code{Layer} object that can be added to a ggplot.
}
\description{
Creates 3D columns (rectangular prisms) from grid data in which x and y fall on a
regular grid. Works with both complete and sparse grid data. Each data point becomes
a rectangular 3D column extending from a base level to the data value.
}
\details{
This is analogous to \code{\link[ggplot2:geom_bar]{ggplot2::geom_col()}} for 3D plots. For automatic counting or
binning, see \code{\link[=geom_bar_3d]{geom_bar_3d()}}.

Note that column geometries often require pairwise depth sorting for correct rendering.
This is the default for smaller data sets, but not for larger data sets due to compute speed;
in those cases you may wish to manually specify \code{sort_method = "pairwise"} for good results.
}
\section{Aesthetics}{

\code{stat_col_3d()} requires the following aesthetics:
\itemize{
\item \strong{x}: X coordinate (grid position)
\item \strong{y}: Y coordinate (grid position)
\item \strong{z}: Z coordinate (column top height)
}

And optionally understands:
\itemize{
\item \strong{zmin}: Base level for each column (can be overridden by the \code{zmin} parameter)
}
}

\section{Computed variables}{

\itemize{
\item \code{normal_x}, \code{normal_y}, \code{normal_z}: Face normal components
\item \code{col_id}: Sequential column number
\item \code{face_type}: Face name ("zmax", "xmin", etc.)
}
}

\examples{
# Basic 3D bar chart from regular grid
# (columns extend from z=0 by default)
d <- expand.grid(x = 1:5, y = 1:5)
d$z <- d$x + d$y + rnorm(25, 0, 0.5)
ggplot(d, aes(x, y, z)) +
  geom_col_3d() +
  coord_3d()

# Set uniform base level using `zmin` parameter
ggplot(d, aes(x, y, z)) +
  geom_col_3d(aes(fill = z), color = "white",
              zmin = 5) +
  coord_3d()

# Set variable base levels using `zmin` aesthetic
d$base_level <- runif(nrow(d), -5, 1)
ggplot(d, aes(x, y, z = z, zmin = base_level)) +
  geom_col_3d(color = "black") +
  coord_3d()

# Show only a subset of column faces
ggplot(d, aes(x, y, z)) +
  geom_col_3d(faces = c("zmax", "ymin"),
    cull_backfaces = FALSE,
    fill = "steelblue", color = "black") +
  coord_3d()

# With gaps between columns
ggplot(d, aes(x, y, z)) +
  geom_col_3d(color = "black", width = 0.6) +
  coord_3d()

}
\seealso{
\code{\link[=geom_bar_3d]{geom_bar_3d()}} for automatic counting/binning, \code{\link[=stat_surface_3d]{stat_surface_3d()}} for smooth
surface rendering, \code{\link[=coord_3d]{coord_3d()}} for 3D coordinate systems, \code{\link[=light]{light()}} for lighting
specifications.
}
