% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geom-hull-3d.R
\name{geom_hull_3d}
\alias{geom_hull_3d}
\alias{stat_hull_3d}
\title{3D convex and alpha hulls}
\usage{
geom_hull_3d(
  mapping = NULL,
  data = NULL,
  stat = StatHull3D,
  position = "identity",
  ...,
  method = "convex",
  radius = NULL,
  light = NULL,
  cull_backfaces = TRUE,
  sort_method = NULL,
  scale_depth = TRUE,
  inherit.aes = TRUE,
  show.legend = TRUE
)

stat_hull_3d(
  mapping = NULL,
  data = NULL,
  geom = GeomPolygon3D,
  position = "identity",
  ...,
  method = "convex",
  radius = NULL,
  light = NULL,
  cull_backfaces = TRUE,
  sort_method = NULL,
  scale_depth = TRUE,
  inherit.aes = TRUE,
  show.legend = TRUE
)
}
\arguments{
\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. The required
aesthetics are \code{x}, \code{y}, and \code{z}. Additional aesthetics can use computed
variables with \code{\link[ggplot2:aes_eval]{ggplot2::after_stat()}}.}

\item{data}{The data to be displayed in this layer.}

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

\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{method}{Triangulation method. Either:
\itemize{
\item \code{"convex"}: Convex hull triangulation (default). Requires the \pkg{geometry} package.
\item \code{"alpha"}: Alpha shape triangulation (can capture non-convex topologies)
}}

\item{radius}{Square root of "alpha" parameter when alpha method is used.
A face is included in the resulting alpha shape if it can be "exposed" by a sphere of this radius.
If NULL (the default), a simple heuristic based on the data scale is used to calculate a radius value.
Note that alpha shapes are quite sensitive to the coordinate scales of your data. See Details section.}

\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{inherit.aes}{If \code{FALSE}, overrides the default aesthetics.}

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

\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{
Turns 3D point clouds into surface hulls consisting of triangular polygons,
using either convex hull or alpha shape algorithms.
}
\section{Grouping}{

Hulls respect ggplot2 grouping aesthetics. To create separate hulls for different
subsets of your data, use \code{aes(group = category_variable)} or similar grouping aesthetics.
Each group will get its own independent hull.
}

\section{Alpha scale sensitivity}{

Alpha shape method is highly sensitive to coordinate scales. The \code{alpha} parameter
that works for data scaled 0-1 will likely fail for data scaled 0-1000.
Guidelines for choosing radius:
\itemize{
\item Start with \code{alpha = 1.0} and adjust based on results
\item For data with mixed scales (e.g., x: 0-1, y: 0-1000), consider rescaling your data first
\item Larger alpha values → smoother, more connected surfaces
\item Smaller alpha values → more detailed surfaces, but may fragment
\item If you get no triangles, try increasing alpha by 10x
\item If surface fills unwanted holes, try decreasing alpha by 10x
}
}

\section{Aesthetics}{

\code{stat_hull_3d()} requires the following aesthetics:
\itemize{
\item \strong{x}: X coordinate
\item \strong{y}: Y coordinate
\item \strong{z}: Z coordinate
}
}

\section{Computed variables}{

\itemize{
\item \code{normal_x}, \code{normal_y}, \code{normal_z}: Surface normal components
}
}

\examples{
\dontshow{if (requireNamespace("geometry", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
# Convex hull
ggplot(sphere_points, aes(x, y, z)) +
  geom_hull_3d(method = "convex", fill = "gray40") +
  coord_3d()

# Alpha shape (for sphere data, gives similar result to convex)
\donttest{
ggplot(sphere_points, aes(x, y, z)) +
  geom_hull_3d(method = "alpha", radius = 2, fill = "gray40") +
  coord_3d()
}

# Use `cull_backfaces = FALSE` to render far side of hull
ggplot(sphere_points, aes(x, y, z)) +
  geom_hull_3d( # default culling for comparison
    method = "convex", light = NULL,
    fill = "steelblue", color = "darkred", linewidth = .5, alpha = .5) +
  geom_hull_3d( # culling disabled
    aes(x = x + 2.5), cull_backfaces = FALSE,
    method = "convex", light = NULL,
    fill = "steelblue", color = "darkred", linewidth = .5, alpha = .5) +
  coord_3d(scales = "fixed")

# Use grouping to build separate hulls for data subsets
ggplot(iris, aes(Petal.Length, Sepal.Length, Sepal.Width,
                 color = Species, fill = Species)) +
      geom_hull_3d() +
      coord_3d(scales = "fixed")
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=coord_3d]{coord_3d()}} for 3D coordinate systems, \link{geom_polygon_3d} for the
default geometry with depth sorting, \code{\link[=light]{light()}} for lighting specifications.
}
