% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/annotation-gspace.R
\name{annotation_gspace}
\alias{annotation_gspace}
\alias{annotation_gspace_image}
\title{Annotate a GraphSpace Plot}
\usage{
annotation_gspace(..., type = "image")

annotation_gspace_image(
  raster,
  interpolate = FALSE,
  opacity = 1,
  flip.v = FALSE,
  flip.h = FALSE
)
}
\arguments{
\item{...}{Arguments forwarded to the annotation handler selected by
\code{type}.}

\item{type}{A string specifying the annotation type. Currently available:
\code{"image"} (default), dispatched to \code{annotation_gspace_image()}.}

\item{raster}{An image to be displayed. Accepted types:
\itemize{
\item A \code{\link{GraphSpace}} object — the image is extracted via
\code{\link{gs_image}}.
\item A \code{raster} object
(see \code{\link[grDevices]{as.raster}}).
\item A \code{matrix} or 3D array (RGB/RGBA), coerced to
\code{raster} automatically.
}}

\item{interpolate}{A logical value indicating whether to apply linear
interpolation when the image is rendered at a different resolution than
its native size. Defaults to \code{FALSE}.}

\item{opacity}{A numeric value in \code{[0, 1]} controlling the
transparency of the image. \code{1} is fully opaque (default);
\code{0} is fully transparent.}

\item{flip.v}{A logical value; if \code{TRUE}, the image is flipped
vertically (top-to-bottom). Defaults to \code{FALSE}.}

\item{flip.h}{A logical value; if \code{TRUE}, the image is flipped
horizontally (left-to-right). Defaults to \code{FALSE}.}
}
\value{
A ggplot2 layer object that can be added to a \code{ggplot()}
call with \code{+}, or \code{invisible(NULL)} with a warning if the
image could not be resolved.
}
\description{
\code{annotation_gspace()} is a generic dispatcher for adding annotation
layers to a \code{ggplot}-based \code{GraphSpace} plot. The \code{type}
argument selects the annotation type; additional arguments are forwarded
to the corresponding handler.
}
\examples{

# Assuming 'gs' is a GraphSpace object with 
# an image stored in gs_image(gs)

\dontrun{
# Pass a GraphSpace object directly
ggplot(gs) +
  annotation_gspace(gs) +
  geom_edgespace() +
  geom_nodespace()

# Extract the image explicitly
ggplot(gs) +
  annotation_gspace(gs_image(gs)) +
  geom_edgespace() +
  geom_nodespace()

# Dim the background and flip vertically
ggplot(gs) +
  annotation_gspace(gs, opacity = 0.5, flip.v = TRUE) +
  geom_edgespace() +
  geom_nodespace()
  
}
}
\seealso{
\code{\link[ggplot2]{annotation_raster}},
\code{\link{gs_image}},
\code{\link{geom_nodespace}},
\code{\link{geom_edgespace}}
}
