Add Overlay — render_image_overlay • rayimage

Takes an RGB array/filename and adds an image overlay. Can optionally resize and position the overlay at a specific pixel location.

render_image_overlay(
  image,
  image_overlay = NULL,
  rescale_original = FALSE,
  convert_overlay_colorspace = TRUE,
  alpha = NA,
  overlay_coords = NULL,
  overlay_dims = NULL,
  overlay_anchor = "nw",
  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 dimension of the image if it does not match exactly.
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).
overlay_coords: Default NULL. Pixel coordinate c(x, y) at which to anchor 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. Options: "nw", "ne", "sw", "se". The overlay is cropped to the image bounds if necessary.
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

if(run_documentation()){
#Plot the dragon
plot_image(dragon)
}

if(run_documentation()){
#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)
}

if (run_documentation()) {
  # 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_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_color = "white", title_color = "#c300ff", title_bar_alpha=1)

  plot_image_grid(list(comp1, comp2), dim = c(1, 2))
}
#> Error in render_title(render_image_overlay(photo_aces, logo_aces, convert_overlay_colorspace = FALSE),     title_text = "#c300ff: Match", title_color = "white", title_color = "#c300ff",     title_bar_alpha = 1): formal argument "title_color" matched by multiple actual arguments