rayimage (version 0.15.1)

render_title: 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
)

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.

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.

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