render_text_image: Generate Text Image

In rayimage: Image Processing for Simulated Cameras

Generate Text Image

Description

Generates an image which tightly fits text.

Usage

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

rayimage documentation built on April 3, 2025, 9:39 p.m.