render_title: Render a Title on an Image

In rayimage: Image Processing for Simulated Cameras

Render a Title on an Image

Description

Adds a title with optional styling and a title bar to an image. The image can be previewed or saved to a file. Supports both the grid-based method and (deprecated) magick package for rendering the title.

Usage

render_title(
  image,
  title_text = "",
  title_size = 30,
  title_offset = rep(title_size/2, 2),
  title_lineheight = 1,
  title_color = "black",
  title_font = "Arial",
  title_style = "plain",
  title_bar_color = NA,
  title_bar_alpha = 0.5,
  title_bar_width = NULL,
  title_position = NA,
  title_just = "left",
  use_magick = FALSE,
  filename = NULL,
  preview = FALSE
)

Arguments

image	Image filename or 3-layer RGB array. Specifies the image to process.
title_text	Default "". Text string to be added as the title to the image.
title_size	Default 30. Numeric value specifying the font size of the title text.
title_offset	Default c(15,15). Numeric vector specifying the horizontal and vertical offset of the title text, relative to its anchor position.
title_lineheight	Default 1. Multiplier for the lineheight.
title_color	Default "black". String specifying the color of the title text.
title_font	Default "Arial". String specifying the font family for the title text. Common options include "sans", "mono", "serif", "Times", "Helvetica", etc.
title_style	Default "plain". String specifying the font style, such as "plain", "italic", or "bold".
title_bar_color	Default NULL. Color of the optional title bar. If NULL, no bar is added.
title_bar_alpha	Default 0.5. Transparency level of the title bar. A value between 0 (fully transparent) and 1 (fully opaque).
title_bar_width	Default NULL. Numeric value for the height of the title bar in pixels. If NULL, it is automatically calculated based on the text size and line breaks.
title_position	Default "northwest". String specifying the position of the title text. Only used when use_magick = TRUE. Common options include "northwest", "center", "south", etc.
title_just	Default "left". Horizontal alignment of the title text: "left", "center", or "right".
use_magick	Default FALSE. Boolean indicating whether to use the magick package for rendering titles. This option will be deprecated in future versions.
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.
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.

Note

The use_magick parameter and all functionality tied to the magick package are planned for deprecation. It is recommended to use the grid-based method for future compatibility.

Examples

if(run_documentation()){
#Plot the dragon
render_title(dragon, preview = TRUE, title_text = "Dragon", title_size=20)
}
if(run_documentation()){
#That's hard to see--let's add a title bar:
render_title(dragon, preview = TRUE, title_text = "Dragon", title_size=20,
         title_bar_color="white")
}
if(run_documentation()){
#Change the width of the bar:
render_title(dragon, preview = TRUE, title_text = "Dragon", title_size=20,
         title_bar_color="white", title_offset = c(8,8))
}
if(run_documentation()){
#The width of the bar will also automatically adjust for newlines:
render_title(dragon, preview = TRUE, title_text = "Dragon\n(Blue)", title_size=20,
         title_bar_color="white")
}
if(run_documentation()){
#Change the color and title color:
render_title(dragon, preview = TRUE, title_text = "Dragon", title_size=20,
         title_bar_color="red", title_color = "white")
}
if(run_documentation()){
#Change the transparency:
render_title(dragon, preview = TRUE, title_text = "Dragon",
            title_size=20, title_bar_alpha = 0.8,
            title_bar_color="red", title_color = "white")
}
if(run_documentation()){
#Read directly from a file
temp_image = tempfile(fileext = ".png")
ray_write_image(dragon, temp_image)
render_title(temp_image, preview = TRUE, title_text = "Dragon",
             title_size=20, title_bar_alpha = 0.8,
             title_bar_color="red", title_color = "white")
}

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