% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/animate-3d.R
\name{animate_3d}
\alias{animate_3d}
\title{Animate a 3D plot}
\usage{
animate_3d(
  plot,
  pitch = NULL,
  roll = NULL,
  yaw = NULL,
  nframes = NULL,
  fps = NULL,
  duration = NULL,
  width = 480,
  height = 480,
  res = 96,
  renderer = gifski_renderer_3d(),
  start_pause = 0,
  end_pause = 0,
  rewind = FALSE,
  cores = 1,
  device = "png",
  progress = interactive()
)
}
\arguments{
\item{plot}{A ggplot object that uses \code{\link[=coord_3d]{coord_3d()}}.}

\item{pitch, roll, yaw}{Rotation parameters to animate. Each can be:
\itemize{
\item \code{NULL} (default): Hold at the value specified in the plot's
\code{\link[=coord_3d]{coord_3d()}} call.
\item A single numeric value: Hold at this value for all frames
(overriding the plot's coord).
\item A numeric vector of length 2+: Keyframe values that are
interpolated linearly across the animation. Keyframes are evenly
spaced, so \code{c(0, 180, 180)} with 100 frames means: start at 0,
reach 180 at frame 50, hold at 180 until frame 100.
}}

\item{nframes, fps, duration}{Control animation length and speed. Specify
any two of three; the third is computed as
\code{duration = nframes / fps}. Defaults: \code{nframes = 100},
\code{fps = 10}.}

\item{width, height}{Dimensions of the animation in pixels. Defaults to
480 x 480.}

\item{res}{Resolution in ppi for the rendered frames. Default is 96.
Controls the size of point-based text/lines/point elements relative to
the plot. See \code{?grDevices::png} for details.}

\item{renderer}{A renderer function that combines image frames into
an animation file. Built-in options:
\itemize{
\item \code{gifski_renderer_3d()} (default): Renders a GIF using the
\pkg{gifski} package.
\item \code{av_renderer_3d()}: Renders a video using the \pkg{av}
package.
\item \code{file_renderer_3d()}: Returns the frame image files
without combining them.
}
Any function with signature \code{function(frames, fps)} can be used.}

\item{start_pause, end_pause}{Number of frames to hold at the beginning
and end of the animation. Default is 0.}

\item{rewind}{Logical. If \code{TRUE}, the animation plays in reverse
after completing, creating a seamless loop. Default is \code{FALSE}.}

\item{cores}{Number of CPU cores for parallel frame rendering. Default
is 1 (sequential). Values greater than 1 use \code{\link[parallel:clusterApply]{parallel::parLapply()}}
to render frames in parallel, which can significantly speed up
animation of complex plots. Note that progress reporting is not
available during parallel rendering.}

\item{device}{The graphics device to use for rendering frames.
Default is \code{"png"}. Other options include \code{"ragg_png"}
(requires the \pkg{ragg} package).}

\item{progress}{Whether to print a progress bar. Ignored when \code{cores > 1}.}
}
\value{
The return value of the renderer function. For
\code{gifski_renderer_3d()}, a \code{gif_3d} object (a file path with
class attributes for display in RStudio and knitr). For
\code{av_renderer_3d()}, a \code{video_3d} object (a file path with
class attributes for display). For \code{file_renderer_3d()}, a
character vector of file paths to the rendered frame images.
}
\description{
Renders an animated GIF or MP4 of a rotating ggplot with \code{\link[=coord_3d]{coord_3d()}},
smoothly interpolating rotation angles across frames.
}
\examples{
\dontshow{if (requireNamespace("gifski", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
\donttest{
# Plot to animate. Note `anchor = "camera"` keeps light source from rotating.
p <- ggplot() +
  geom_function_3d(
    fun = function(x, y) sin(x) * cos(y),
    xlim = c(-pi, pi), ylim = c(-pi, pi),
    fill = "steelblue", color = "steelblue", linewidth = .5) +
  coord_3d(light = light(mode = "hsl", anchor = "camera",
                         direction = c(1, 1, 0))) +
  theme_void()

# Simple turntable rotation
animate_3d(p, yaw = c(-30, 330))

# Multi-segment orbit with pitch change
animate_3d(p, yaw = c(0, 720), roll = c(-90, 0, -90),
           nframes = 120, fps = 15)

# Save to file (writes to a temporary path; specify your own to keep it)
anim <- animate_3d(p, yaw = c(0, 360))
anim_save_3d(anim, file.path(tempdir(), "rotating_surface.gif"))
}
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=anim_save_3d]{anim_save_3d()}} for saving animations to file.
\code{\link[=gifski_renderer_3d]{gifski_renderer_3d()}} and \code{\link[=file_renderer_3d]{file_renderer_3d()}} for renderer options.
}
