% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/geom-point-3d.R
\name{geom_point_3d}
\alias{geom_point_3d}
\alias{stat_point_3d}
\title{3D scatter plot with 2D reference elements}
\usage{
geom_point_3d(
  mapping = NULL,
  data = NULL,
  stat = StatPoint3D,
  position = "identity",
  ...,
  na.rm = FALSE,
  sort_method = "painter",
  scale_depth = TRUE,
  raw_points = TRUE,
  ref_lines = FALSE,
  ref_points = FALSE,
  ref_faces = "zmin",
  ref_circle_radius = 1.5,
  ref_circle_vertices = 16,
  ref_line_color = NULL,
  ref_line_colour = NULL,
  ref_line_linewidth = 0.25,
  ref_line_linetype = NULL,
  ref_line_alpha = NULL,
  ref_point_color = NULL,
  ref_point_colour = NULL,
  ref_point_fill = NULL,
  ref_point_size = NULL,
  ref_point_alpha = NULL,
  ref_point_stroke = NULL,
  ref_point_shape = NULL,
  inherit.aes = TRUE,
  show.legend = NA
)

stat_point_3d(
  mapping = NULL,
  data = NULL,
  geom = GeomPoint3D,
  position = "identity",
  ...,
  na.rm = FALSE,
  sort_method = "painter",
  scale_depth = TRUE,
  raw_points = TRUE,
  ref_lines = FALSE,
  ref_points = FALSE,
  ref_faces = "zmin",
  ref_circle_radius = 1.5,
  ref_circle_vertices = 16,
  ref_line_color = NULL,
  ref_line_colour = NULL,
  ref_line_linewidth = 0.25,
  ref_line_linetype = NULL,
  ref_line_alpha = NULL,
  ref_point_color = NULL,
  ref_point_colour = NULL,
  ref_point_fill = NULL,
  ref_point_size = NULL,
  ref_point_alpha = NULL,
  ref_point_stroke = NULL,
  ref_point_shape = NULL,
  inherit.aes = TRUE,
  show.legend = NA
)
}
\arguments{
\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}}. In addition to
the standard point aesthetics, \code{geom_point_3d()} requires x, y, and z coordinates.}

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

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

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

\item{...}{Other arguments passed on to \code{\link[ggplot2:layer]{ggplot2::layer()}}.}

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

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

\item{scale_depth}{Controls depth-based scaling, drawing closer elements
larger or thicker and farther ones smaller or thinner. \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 panel and axis components.}

\item{raw_points}{Logical indicating whether to show the original 3D points.
Default is \code{TRUE}.}

\item{ref_lines}{Logical indicating whether to show reference lines projecting
from points to cube faces. Default is \code{FALSE}.}

\item{ref_points}{Type of reference points to create. Options:
\itemize{
\item \code{FALSE}: No reference points (default)
\item \code{TRUE or "circles"}: Circular reference points that project properly
\item \code{"points"}: Single-point references (renders faster and supports non-circular shapes,
but point shape is not 3D-transformed)
}}

\item{ref_faces}{Character vector specifying which cube faces to project to.
Valid face names are: "xmin", "xmax", "ymin", "ymax", "zmin", "zmax".
Default is "zmin" (bottom face). Multiple faces can be specified.}

\item{ref_circle_radius}{Radius for circular reference points as percentage of standardized coordinate space.}

\item{ref_circle_vertices}{Number of vertices for circular reference points (higher = smoother).}

\item{ref_line_color, ref_line_colour, ref_line_linewidth, ref_line_linetype, ref_line_alpha}{Styling overrides for reference lines. When NULL, inherits from point aesthetics or uses defaults.
Both American (\code{ref_line_color}) and British (\code{ref_line_colour}) spellings are accepted.}

\item{ref_point_color, ref_point_colour, ref_point_fill, ref_point_size, ref_point_alpha, ref_point_stroke, ref_point_shape}{Styling overrides for reference points and circles. When NULL, inherits from raw point aesthetics
with shape-aware logic (complex shapes 21-25 vs simple shapes 0-20/characters).
Both American (\code{ref_point_color}) and British (\code{ref_point_colour}) spellings are accepted.}

\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{"point_3d"}.}
}
\value{
A \code{Layer} object that can be added to a ggplot.
}
\description{
\code{geom_point_3d()} creates scatter plots in 3D space with automatic depth-based
size scaling. Points closer to the viewer appear larger, while points farther
away appear smaller, creating realistic perspective effects. Optionally adds
reference lines and points projecting to cube faces, to illustrate point locations
in 2D.
}
\details{
StatPoint3D performs identity transformation (passes data through unchanged) while
properly handling discrete scales for 3D coordinate systems. It can optionally
generate reference lines and points projecting to cube faces.
}
\section{Aesthetics}{

\code{geom_point_3d()} supports all the same aesthetics as \code{\link[ggplot2:geom_point]{ggplot2::geom_point()}}, plus \code{z}:
\itemize{
\item \strong{x}: X coordinate (required)
\item \strong{y}: Y coordinate (required)
\item \strong{z}: Z coordinate (required)
\item \code{alpha}: Transparency
\item \code{colour}: Point border color
\item \code{fill}: Point fill color (for certain shapes)
\item \code{shape}: Point shape
\item \code{size}: Point size (gets depth-scaled when \code{scale_depth = TRUE})
\item \code{stroke}: Border width for shapes with borders
}
}

\section{StatPoint3D returns the following computed variables}{

\itemize{
\item \code{x_raw}, \code{y_raw}, \code{z_raw}: Original values before discrete-to-numeric conversion
\item \code{element_type}: Type of element ("raw_point", "ref_point", "ref_line", "ref_circle")
\item \code{segment_id}: ID linking the two endpoints of reference lines
\item \code{ref_face}: Which face reference elements project to
\item \code{ref_circle_radius}: Radius for circular reference points
\item \code{ref_circle_vertices}: Number of vertices for circular reference points
}
}

\section{Depth Scaling}{

The depth scaling uses an inverse relationship with distance, following the
mathematical relationship: \code{apparent_size = base_size * reference_distance / actual_distance}

This creates realistic perspective where:
\itemize{
\item Objects twice as far appear half as big
\item Objects twice as close appear twice as big
\item The center of the plot volume renders at exactly the user-specified size
}
}

\section{Point Rendering}{

ggcube uses shape-aware rendering for improved stroke behavior:
\itemize{
\item \strong{Simple shapes (0-20, characters):} Use \code{size} for fontsize, \code{stroke} for border width, no fill
\item \strong{Complex shapes (21-25):} Use ggplot2's approach: \code{size + 0.5*stroke} for fontsize to prevent gaps
\item Both size and stroke are depth-scaled when \code{scale_depth = TRUE}
\item All shapes preserve stroke depth scaling and parameter control
}
}

\section{Reference Features}{

Reference lines and points help visualize the 3D relationships by projecting
data points onto cube faces:
\itemize{
\item \strong{Reference lines}: Connect each 3D point to its projection on specified faces
\item \strong{Reference points}: Show the projected location on the faces
\item \strong{Reference circles}: Circular projections that appear as realistic 3D shadows
\item \strong{Depth sorting}: All elements (original points, reference lines, reference points)
are automatically depth-sorted for proper 3D rendering
}
}

\section{Aesthetic Inheritance}{

Reference elements intelligently inherit styling from raw points:
\itemize{
\item \strong{Shape-aware}: Complex shapes (21-25) with fill/colour are handled differently from simple shapes (0-20/characters)
\item \strong{Alpha detection}: If all points have alpha=1, uses 0.5 default for ref elements; otherwise inherits mapped alpha
\item \strong{Priority}: Explicit ref_* parameters > mapped aesthetics > smart defaults
}
}

\examples{
library(ggplot2)

# Basic 3D scatter plot with depth scaling
ggplot(expand.grid(x = 1:5, y = 1:5, z = 1:5),
       aes(x, y, z, fill = z)) +
  geom_point_3d(size = 10, shape = 21, color = "white", stroke = .1) +
  coord_3d(pitch = 40, roll = 5, yaw = 0, dist = 1.5) +
  scale_fill_viridis_c()

# Add circular reference points on 2D face panel
ggplot(mtcars, aes(mpg, wt, qsec)) +
  geom_point_3d(size = 3,
    ref_points = TRUE, ref_faces = c("ymax", "xmax")) +
  coord_3d()

}
\seealso{
\code{\link[=geom_segment_3d]{geom_segment_3d()}} for 3D segments, \code{\link[=geom_path_3d]{geom_path_3d()}} for 3D paths,
\code{\link[=coord_3d]{coord_3d()}} for 3D coordinate systems.
}
