render_image_overlay: Add Overlay

In rayimage: Image Processing for Simulated Cameras

Add Overlay

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 render_sprite_overlay().

Usage

render_image_overlay(
  image,
  image_overlay = NULL,
  rescale_original = FALSE,
  convert_overlay_colorspace = TRUE,
  alpha = NA,
  filename = NULL,
  preview = FALSE
)

Arguments

image	3-layer RGB/4-layer RGBA array, rayimg class, or filename of an image.
image_overlay	Default NULL. 3-layer RGB/4-layer RGBA array, rayimg class, or filename of an image. This image will be resized to the dimensions of image if it does not match exactly, unless rescale_original = TRUE.
rescale_original	Default FALSE. If TRUE, function will resize the original image to match the overlay.
convert_overlay_colorspace	Default TRUE. Whether to convert the overlay's colorspace to match the underlying image.
alpha	Default 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).
filename	Default NULL. File to save the image to. If NULL and preview = FALSE, returns an RGB array.
preview	Default FALSE. If TRUE, it will display the image in addition to returning it.

Value

A rayimg RGBA array.

Examples

#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))

rayimage documentation built on June 12, 2026, 5:06 p.m.