Generate Text Image — render_text

Generates an image which tightly fits text.

render_text_image(
  text,
  lineheight = 1,
  color = "black",
  size = 12,
  font = "sans",
  just = "left",
  background_color = "white",
  background_alpha = 1,
  use_ragg = TRUE,
  width = NA,
  height = NA,
  filename = NULL,
  check_text_width = TRUE,
  check_text_height = TRUE,
  preview = FALSE
)

Arguments

text: Text to turn into an image.
lineheight: Default 1. Multiplier for the lineheight.
color: Default "black". String specifying the color of the text.
size: Default 12. Numeric value specifying the font size of the text.
font: Default "sans". String specifying the font family for the text. Common options include "sans", "mono", "serif", "Times", "Helvetica", etc.
just: Default "left". Horizontal alignment of the text: "left", "center", or "right".
background_color: Default "white". Color of the background.
background_alpha: Default 1. Transparency of the background. A value between 0 (fully transparent) and 1 (fully opaque).
use_ragg: Default TRUE. Whether to use the ragg package as the graphics device. Required for emojis.
width: Default NA. User-defined textbox width.
height: Default NA. User-defined textbox width.
filename: Default NULL. String specifying the file path to save the resulting image. If NULL and preview = FALSE, the function returns the processed RGB array.
check_text_width: Default TRUE. Whether to manually adjust the bounding box of the resulting image to ensure the string bbox is wide enough for the text. Not all systems provide accurate font sizes: this ensures the string is not cut off at the edges, at the cost of needing to repeatedly render the image internally until a suitable image is found.
check_text_height: Default FALSE. Whether to manually adjust the bounding box of the resulting image to ensure the string bbox is tall enough for the text. This will ensure a tight vertical bounding box on the text.
preview: Default FALSE. Boolean indicating whether to display the image after processing. If TRUE, the image is displayed but not saved or returned.

Value

A 3-layer RGB array of the processed image if filename = NULL and preview = FALSE. Otherwise, writes the image to the specified file or displays it if preview = TRUE.

Examples

if (run_documentation()) {
  #Generate an image of some text
  render_text_image("Some text", preview = TRUE)
}

if (run_documentation()) {
  #Change the font size
  render_text_image("Some text", size = 100, preview = TRUE)
}

if (run_documentation()) {
  #Change the font color
  render_text_image("Some text", size = 100, color="red",preview = TRUE)
}

if (run_documentation()) {
  #Change the background color and transparency
  render_text_image("Some text", size = 50, color="purple",
                      background_color="purple", background_alpha = 0.5,
                      preview = TRUE)
}

if (run_documentation()) {
  # Plot an emoji with the agg device.
  render_text_image("\U0001F600\U0001F680", size = 50, color = "purple", use_ragg = TRUE,
                    background_alpha = 0,
                    preview = TRUE)
}


if (run_documentation()) {
  # Plot an emoji with the agg device and adjust the height and width (which
  # is on by default) to be a tight fit.
  render_text_image("\U0001F600\U0001F680", size = 50, color = "purple", use_ragg = TRUE,
                    background_alpha = 0, check_text_width = TRUE,
                    check_text_height = TRUE,
                    preview = TRUE)
}