% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/theme.R
\name{cube_theming}
\alias{cube_theming}
\title{Using themes to style 3D panels and axis labels}
\description{
In ggcube, standard ggplot2 themes generally influence 3D plots as expected, including adding
complete themes like \code{ggplot2::theme_dark()} and modifying theme elements like
\verb{theme(panel.background = element_rect(fill = "darkblue")}. However, ggcube also
provides additional theme elements that control 3D-specific styling of panels
and labels.
}
\section{Text elements}{

\itemize{
\item \code{axis.text.z}: Styling for z-axis tick labels (inherits from \code{axis.text})
\item \code{axis.title.z}: Styling for z-axis title (inherits from \code{axis.title})
\item \code{axis.text}, \code{axis.title}: Standard styling with \code{element_text()}.
}

Use \code{element_text(margin = margin(...))} to adjust text padding, with left/right
margins affecting axis text and top/bottom margins affecting axis titles;
since placement and justification of these elements varies dynamically,
no distinction is made between left and right margins, or between top and
bottom margins -- you can set either, and the maximum of the two will be used.
}

\section{Axis ticks}{

\itemize{
\item \code{axis.ticks.z}: Styling for z-axis ticks (inherits from \code{axis.ticks})
\item \code{axis.ticks}, \code{axis.ticks.x}, \code{axis.ticks.y}: Standard styling with \code{element_line()}.
\item \code{axis.ticks.length}, \code{axis.ticks.length.x/y/z}: Tick length.
}

Ticks are 3D geometry rather than screen-space annotation: each one continues
its gridline past the cube edge, and is projected like everything else. They
therefore foreshorten with the view, and a tick pointing away from the viewer
is drawn shorter than one lying across it.

Because of this, \code{axis.ticks.length} is an upper bound rather than an exact
length. It is calibrated so that a tick along the least foreshortened axis
renders at the requested size, with ticks along the other axes coming in
shorter. Tick length does not vary with axis \code{ratio}; a stretched axis gets
the same ticks as a compressed one.

As in 2D ggplot2, \code{axis.ticks.length} also contributes to the spacing between
the cube and the axis text, whether or not ticks are drawn. Setting
\code{axis.ticks = element_blank()} removes the ticks but leaves that spacing
intact; set \code{axis.ticks.length = unit(0, "pt")} to close the gap as well.
Negative lengths point ticks inward, and do not displace the axis text.
}

\section{Panel elements}{

\itemize{
\item \code{panel.foreground}: Styling for cube faces rendered in front of data (inherits from \code{panel.background}).
Foreground panels default to 20\% opacity to keep them from obscuring the data; this can be
overridden by setting \code{alpha} on either \code{panel.foreground} or \code{panel.background}.
\item \code{panel.border.foreground}: Styling for cube faces rendered in front of data (inherits from \code{panel.border})
\item \code{panel.grid.foreground}: Styling for grid lines on foreground faces (inherits from \code{panel.grid})
\item \code{panel.grid.major.foreground}: Major grid lines on foreground faces (inherits from \code{panel.grid.foreground})
}

Background panels use standard \code{panel.background}, \code{panel.border}, \code{panel.grid}, etc., while foreground panels
use the \verb{*.foreground} variants listed above. Since the foreground elements inherit from the standard background
and grid elements, you can use \code{panel.background}, etc. to style both background and foreground faces simultaneously.
This also extends to \code{alpha} set via the enhanced \code{element_rect()} below: setting \code{alpha} on \code{panel.background}
will tint both background and foreground panels (overriding the foreground's 20\% default), unless an explicit
\code{alpha} is also set on \code{panel.foreground}.
}

\section{Depth scaling}{

Under perspective projection, gridlines, borders, ticks, and axis text are (by default)
sized by their distance from the viewer. An element at the center of the cube
renders at exactly the size the theme specifies, with nearer elements drawn
larger and farther ones smaller. Axis titles are never scaled this way, and
orthographic plots are unaffected. You can use \code{coord_3d(scale_depth = )} to reduce or
disable the depth-scaling effect, per element or globally.
}

\section{Enhanced elements}{

\itemize{
\item \code{element_rect()} extends \code{ggplot2::element_rect()} by adding an \code{alpha} parameter for transparency effects
on \code{coord_3d()}'s foreground and background panels.
}
}

\examples{
# example code
p <- ggplot(sphere_points, aes(x, y, z)) +
  geom_hull_3d() +
  coord_3d(panels = "all") +
  theme(panel.background = element_rect(color = "black"),
          panel.border = element_rect(color = "black"),
          panel.foreground = element_rect(alpha = .3),
          panel.grid.foreground = element_line(color = "gray", linewidth = .25),
          axis.text = element_text(color = "darkblue"),
          axis.text.z = element_text(color = "darkred"),
          axis.title = element_text(margin = margin(t = 30)), # add padding
          axis.title.x = element_text(color = "magenta"))

}
