% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/render_image_overlay.R
\name{render_image_overlay}
\alias{render_image_overlay}
\title{Add Overlay}
\usage{
render_image_overlay(
  image,
  image_overlay = NULL,
  rescale_original = FALSE,
  convert_overlay_colorspace = TRUE,
  alpha = NA,
  filename = NULL,
  preview = FALSE
)
}
\arguments{
\item{image}{3-layer RGB/4-layer RGBA array, \code{rayimg} class, or filename of an image.}

\item{image_overlay}{Default \code{NULL}. 3-layer RGB/4-layer RGBA array, \code{rayimg} class, or filename of an image.
This image will be resized to the dimensions of \code{image} if it does not match
exactly, unless \code{rescale_original = TRUE}.}

\item{rescale_original}{Default \code{FALSE}. If \code{TRUE}, function will resize the original image to match
the overlay.}

\item{convert_overlay_colorspace}{Default \code{TRUE}. Whether to convert the overlay's colorspace
to match the underlying image.}

\item{alpha}{Default \code{NA}, using overlay's alpha channel. Otherwise, this sets the alpha transparency
by multiplying the existing alpha channel by this value (between 0 and 1).}

\item{filename}{Default \code{NULL}. File to save the image to. If \code{NULL} and \code{preview = FALSE},
returns an RGB array.}

\item{preview}{Default \code{FALSE}. If \code{TRUE}, it will display the image in addition
to returning it.}
}
\value{
A \code{rayimg} RGBA array.
}
\description{
Takes an RGB array/filename and composites an image overlay over
the full image. For pixel-positioned sprite, label, glyph, or billboard
overlays, use \code{\link[=render_sprite_overlay]{render_sprite_overlay()}}.
}
\examples{
\dontshow{if (interactive() || identical(Sys.getenv("IN_PKGDOWN"), "true")) withAutoprint(\{ # examplesIf}
#Plot the dragon
plot_image(dragon)
#Add an overlay of a red semi-transparent circle:
circlemat = generate_2d_disk(min(dim(dragon)[1:2]))
circlemat = circlemat/max(circlemat)

#Create RGBA image, with a transparency of 0.5
rgba_array = array(1, dim=c(nrow(circlemat),ncol(circlemat),4))
rgba_array[,,1] = circlemat
rgba_array[,,2] = 0
rgba_array[,,3] = 0
dragon_clipped = dragon
dragon_clipped[dragon_clipped > 1] = 1
render_image_overlay(dragon_clipped, image_overlay = rgba_array,
                 alpha=0.5, preview = TRUE)

	# Read photo, convert to ACEScg with CAT (scene)
	photo = ray_read_image(sunset_image, normalize = FALSE)
	photo_aces = render_convert_colorspace(
		photo,
		to_mats = CS_ACESCG,
		adapt_white = TRUE
	)
	tmp_txt = tempfile(fileext = ".png")
	render_text_image(
		"Sunset",
		size = 60,
		filename = tmp_txt,
		color = "#c300ff",
		background_alpha = 0
	)
	# Read logo (display-referred), convert primaries only (no CAT)
	logo = ray_read_image(tmp_txt, normalize = FALSE) # sRGB/D65
	logo_aces = render_convert_colorspace(
		logo,
		to_mats = CS_ACESCG,
		adapt_white = FALSE
	)

	# Composite in ACEScg, then display (plot_image converts to sRGB/D65 + OETF)
	# Here, we also turn overlay conversion in [render_image_overlay()] off,
 # to show what happens when you don't account for the colorspace difference.
 # By default [render_image_overlay()] will do this for you.
	comp1 = render_image_overlay(
		photo_aces,
		logo_aces,
		convert_overlay_colorspace = FALSE
	) |>
   render_title(title_text = "#c300ff: Match",
                title_bar_color = "white", title_color = "#c300ff", title_bar_alpha=1)
	comp2 = render_image_overlay(
		photo_aces,
		logo,
		convert_overlay_colorspace = FALSE
	) |>
	 render_title(title_text = "#c300ff: Incorrect",
               title_bar_color = "white", title_color = "#c300ff", title_bar_alpha=1)

	plot_image_grid(list(comp1, comp2), dim = c(1, 2))
\dontshow{\}) # examplesIf}
}
