% 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}{Character indicating algorithm used to determine the order in which
elements are rendered. This controls depth sorting for all geometry types within
a layer, including polygons, points, segments, and text. Default varies by geometry
type.
\itemize{
\item \code{"painter"}: Elements are sorted by the mean depth (distance from
viewer after rotation) of their vertices. This is fast, but can give incorrect
results when primitives overlap in screen space at different depths.
\item \code{"pairwise"}: A more intensive sorting algorithm that compares every
pair of elements to determine occlusion order. Uses type-specific geometric
tests: polygon overlap detection for polygon-polygon pairs, point-in-polygon
tests for polygon-point pairs, line clipping for polygon-segment pairs, and
line intersection for segment-segment pairs. When elements are coplanar,
smaller primitives (points, segments) render on top of larger ones (polygons).
Slower but more accurate.
\item \code{"auto"}: Uses pairwise if the data has fewer than 500 rows, and
painter otherwise.
}}

\item{scale_depth}{Logical indicating whether to apply depth-based scaling
to point sizes, point stroke widths, and reference line widths.
When \code{TRUE} (default), points/lines closer to the viewer appear larger/wider, and
points farther away appear smaller. When \code{FALSE}, all points/lines have uniform size/width.}

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