render_sprite_overlay: Add Sprite Overlay

In rayimage: Image Processing for Simulated Cameras

Add Sprite Overlay

Description

Places an image overlay at a pixel location without resizing it to the full destination image. This is intended for sprite-like or billboard-like overlays such as labels, icons, glyphs, and screen-space annotations.

Usage

render_sprite_overlay(
  image,
  image_overlay = NULL,
  convert_overlay_colorspace = TRUE,
  alpha = NA,
  overlay_coords = c(1, 1),
  overlay_dims = NULL,
  overlay_anchor = "nw",
  overlay_just = NULL,
  hjust = NULL,
  vjust = NULL,
  preserve_channels = TRUE,
  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 the sprite 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).
overlay_coords	Default c(1, 1). Pixel coordinate c(x, y) used to position the overlay. x increases from left to right and y from top to bottom, starting at 1.
overlay_dims	Default NULL. Dimensions for the overlay in pixels. If provided, the overlay is resized with render_resized() before compositing.
overlay_anchor	Default "nw". Which corner of the overlay is placed at overlay_coords when no numeric justification is supplied. Options: "nw", "ne", "sw", "se".
overlay_just	Default NULL. Optional numeric c(hjust, vjust) justification used to place the overlay relative to overlay_coords. If set, the overlay's left/top pixel is computed as round(x - hjust * overlay_width) and round(y - vjust * overlay_height).
hjust	Default NULL. Optional horizontal justification. Overrides the first value of overlay_just.
vjust	Default NULL. Optional vertical justification. Overrides the second value of overlay_just.
preserve_channels	Default TRUE. If TRUE, RGB input images return RGB output and RGBA input images return RGBA output.
filename	Default NULL. File to save the image to. If NULL and preview = FALSE, returns an image array.
preview	Default FALSE. If TRUE, it will display the image in addition to returning it.

Value

A rayimg array.

Examples

dragon_clipped = dragon
dragon_clipped[dragon_clipped > 1] = 1

# Render a transparent dragon emoji and center it on a pixel with hjust/vjust:
dragon_emoji = render_text_image(
 "\U0001F409",
 size = 80,
 background_alpha = 0,
 use_ragg = TRUE,
 trim = TRUE,
 trim_padding = 8
)
render_sprite_overlay(
 dragon_clipped,
 image_overlay = dragon_emoji,
 overlay_coords = c(ncol(dragon_clipped) / 2, nrow(dragon_clipped) / 2),
 hjust = 0.5,
 vjust = 0.5,
 preview = TRUE
)

# The same justification can be supplied as overlay_just = c(hjust, vjust):
render_sprite_overlay(
 dragon_clipped,
 image_overlay = dragon_emoji,
 overlay_coords = c(ncol(dragon_clipped), nrow(dragon_clipped)),
 overlay_just = c(1, 1),
 preview = TRUE
)

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