Type:	Package
Title:	Image Processing for Simulated Cameras
Version:	0.15.1
Maintainer:	Tyler Morgan-Wall <tylermw@gmail.com>
Description:	Uses convolution-based techniques to generate simulated camera bokeh, depth of field, and other camera effects, using an image and an optional depth map. Accepts both filename inputs and in-memory array representations of images and matrices. Includes functions to perform 2D convolutions, reorient and resize images/matrices, add image and text overlays, generate camera vignette effects, and add titles to images.
License:	GPL-3
LazyData:	true
Depends:	R (≥ 4.1.0)
Imports:	Rcpp, png, jpeg, grDevices, grid, tiff, systemfonts
Suggests:	magick, testthat (≥ 3.0.0), ragg
LinkingTo:	Rcpp, RcppArmadillo, progress
RoxygenNote:	7.3.2
Encoding:	UTF-8
URL:	https://www.rayimage.dev, https://github.com/tylermorganwall/rayimage
BugReports:	https://github.com/tylermorganwall/rayimage/issues
Config/testthat/edition:	3
Config/build/compilation-database:	true
NeedsCompilation:	yes
Packaged:	2025-02-01 21:26:23 UTC; tyler
Author:	Tyler Morgan-Wall [aut, cph, cre], Sean Barrett [ctb, cph]
Repository:	CRAN
Date/Publication:	2025-02-01 21:50:02 UTC

Add Overlay (Deprecated)

Description

Takes an RGB array/filename and adds an image overlay.

Usage

add_image_overlay(...)

Arguments

Value

3-layer RGB array of the processed image.

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
add_image_overlay(dragon_clipped, image_overlay = rgba_array,
                 alpha=0.5, preview = TRUE)
}

add_multi_padding

Description

Adds multiple levels padding to the matrix

Usage

add_multi_padding(input, pad = 1)

Arguments

Value

Matrix with edges padded

add_padding

Description

Adds padding to the matrix

Usage

add_padding(input)

Arguments

Value

Matrix with edges padded

Add Title Function (deprecated)

Description

Add Title Function (deprecated)

Usage

add_title(...)

Arguments

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

#Deprecated add_title function. Will display a warning.
if(run_documentation()) {
render_title(dragon, preview = TRUE, title_text = "Dragon", title_size=20)
}

Add Vignette Effect (Deprecated)

Description

Takes an RGB array/filename and adds a camera vignette effect.

Usage

add_vignette(...)

Arguments

Value

3-layer RGB array of the processed image.

Examples

if(run_documentation()){
#Plot the dragon
plot_image(dragon)
}
if(run_documentation()){
#Add a vignette effect:
add_vignette(dragon, preview = TRUE, vignette = 0.5)
}

Calculate Bokeh Size

Description

Calculates the amount of blurring at each point with camera characteristics.

Usage

calc_bokeh_size(z, zfocus, f, N, ramp)

Arguments

Value

Matrix of bokeh sizes.

Convert Color

Description

Convert Color

Usage

convert_color(color, as_hex = FALSE)

Arguments

Value

Color vector

Examples

#none

Plot Image

Description

Displays the image in the current device.

Usage

convert_to_native_raster(input)

Arguments

Dragon Image

Description

Dragon Image

Usage

dragon

Format

An RGB 3-layer HDR array with 200 rows and 200 columns, generated using the rayrender package.

Dragon Depthmap

Description

Dragon Depthmap

Usage

dragondepth

Format

An matrix with 200 rows and 200 columns, representing the depth into the dragon image scene. Generated using the rayrender package. Distances range from 847 to 1411.

expand to fit

Description

Pads to a rect

Usage

expand_to_fit(dim, kernel)

Value

Hillshade with edges trimmed

Flip Left-Right

Description

Flip Left-Right

Usage

fliplr(x)

Arguments

Value

Flipped matrix

Examples

#Fake example

Flip Up-Down

Description

Flip Up-Down

Usage

flipud(x)

Arguments

Value

Flipped matrix

Examples

#Fake example

Generate 2D Disk

Description

Generates a 2D disk with a gradual falloff.

Disk generated using the following formula:

The origin of the coordinate system is the center of the matrix.

Usage

generate_2d_disk(dim = c(11, 11), radius = 1, rescale_unity = FALSE)

Arguments

Examples

if(run_documentation()){
image(generate_2d_disk(101), asp=1)
}

Generate 2D exponential Distribution

Description

Generates a 2D exponential distribution, with an optional argument to take the exponential to a user-defined power.

Usage

generate_2d_exponential(
  falloff = 1,
  dim = c(11, 11),
  width = 3,
  rescale_unity = FALSE
)

Arguments

Examples

if(run_documentation()){
image(generate_2d_exponential(1,31,3), asp=1)
}

Generate 2D Gaussian Distribution

Description

Generates a 2D gaussian distribution, with an optional argument to take the gaussian to a user-defined power.

Usage

generate_2d_gaussian(
  sd = 1,
  power = 1,
  dim = c(11, 11),
  width = 3,
  rescale_unity = FALSE
)

Arguments

Examples

if(run_documentation()){
image(generate_2d_gaussian(1,1,31), asp=1)
}

Check Filename

Description

Check Filename

Usage

get_file_type(file)

Arguments

Value

Flipped matrix

Examples

#Fake example

Get String Dimensions

Description

Calculates font metrics for a specified font, font size, and style.

Usage

get_string_dimensions(string, font = "sans", size = 12, align = "center", ...)

Arguments

Details

The function renders specific characters ("d" for ascender, "g" for descender, "x" for neutral) using the specified font parameters. It calculates the bounding box of each character to determine the necessary adjustments for accurate text positioning.

Value

A data.frame listing the string dimensions.

Examples

# Get height of basic sans font
get_string_dimensions("This is a string", size=24)

Handle Image Output

Description

Handles image output logic: returning, saving to a file, or previewing.

Usage

handle_image_output(image, filename = NULL, preview = FALSE)

Arguments

Value

If filename = NULL and preview = FALSE, returns the image array invisibly. Otherwise, saves to file or displays the image.

Matrix/Array Interpolation

Description

Given a series of X and Y coordinates and an array/matrix, interpolates the Z coordinate using bilinear interpolation.

Usage

interpolate_array(image, x, y)

Arguments

Value

Either a vector of values (if image is a matrix) or a list of interpolated values from each layer.

Examples

#if(interactive()){
#Interpolate a matrix
interpolate_array(volcano,c(10,10.1,11),c(30,30.5,33))
#Interpolate a 3-layer array (returns list for each channel)
interpolate_array(dragon,c(10,10.1,11),c(30,30.5,33))
#end}

Make Vignette Overlay

Description

Makes an overlay to simulate vignetting in a camera

Usage

make_vignette_overlay(
  width,
  height,
  intensity = 0.3,
  radius_multiplier = 1.3,
  radius = NULL,
  color = "#000000"
)

Arguments

pad to fit

Description

Pads to a rect

Usage

pad_to_fit(dim, kernel)

Value

Hillshade with edges trimmed

Plot Native Raster with Custom Aspect Ratio

Description

Plot Native Raster with Custom Aspect Ratio

Usage

plot_asp_native_raster(
  nr,
  asp = 1,
  show = FALSE,
  return_grob = FALSE,
  gp = grid::gpar()
)

Plot Image

Description

Displays the image in the current device.

Usage

plot_image(
  image,
  rotate = 0,
  draw_grid = FALSE,
  ignore_alpha = FALSE,
  asp = 1,
  new_page = TRUE,
  return_grob = FALSE,
  gp = grid::gpar()
)

Arguments

Examples

#if(interactive()){
#Plot the dragon array
plot_image(dragon)
#Make pixels twice as wide as tall
plot_image(dragon, asp = 2)
#Plot non-square images
plot_image(dragon[1:100,,])
#Make pixels twice as tall as wide
plot_image(dragon[1:100,,], asp = 1/2)
#end}

Plot Image Grid

Description

Displays the image in the current device.

Usage

plot_image_grid(
  input_list,
  dim = c(1, 1),
  asp = 1,
  draw_grid = FALSE,
  gp = grid::gpar()
)

Arguments

Examples

if(run_documentation()){
#Plot the dragon array
plot_image_grid(list(dragon, 1-dragon), dim = c(1,2))
}
if(run_documentation()){
plot_image_grid(list(dragon, 1-dragon), dim = c(2,1))
}
if(run_documentation()){
plot_image_grid(list(dragon, NULL, 1-dragon), dim = c(2,2), asp = c(2,1,1/2))
}
if(run_documentation()){
plot_image_grid(list(dragon, NULL, NULL, dragon), dim = c(2,2), asp = c(2,1,1,1/2))
}
if(run_documentation()){
#Plot alongside the depth matrix
dragon_depth_reoriented = render_reorient(dragondepth,
                                         transpose = TRUE,
                                         flipx = TRUE)/2000
plot_image_grid(list(dragondepth/2000, dragon, dragon, dragondepth/2000),
               dim = c(2,2))
}

Preview Focus

Description

Displays the focal point

Usage

preview_focus(image, depthmap, focus, imagetype, depthtype)

Arguments

Examples

#Plot the dragon

Read Image

Description

Takes an RGB array/filename and adds an image overlay.

Usage

ray_read_image(image, convert_to_array = TRUE, preview = FALSE, ...)

Arguments

Value

3-layer RGB array of the processed image.

Examples

if(run_documentation()){
#Write as a png
tmparr = tempfile(fileext=".png")
ray_read_image(dragon) |>
 ray_write_image(tmparr)
ray_read_image(tmparr) |>
 plot_image()
}
if(run_documentation()){
#Write as a JPEG (passing quality arguments via ...)
tmparr = tempfile(fileext=".jpg")
ray_read_image(dragon) |>
 ray_write_image(tmparr, quality = 0.2)
ray_read_image(tmparr) |>
 plot_image()
}
if(run_documentation()){
#Write as a tiff
tmparr = tempfile(fileext=".tiff")
ray_read_image(dragon) |>
 ray_write_image(tmparr)
ray_read_image(tmparr) |>
  plot_image()
}

Write Image

Description

Takes an RGB array/filename and writes it to file.

Usage

ray_write_image(image, filename, clamp = TRUE, ...)

Arguments

Value

3-layer RGB array of the processed image.

Examples

if(run_documentation()){
#Write as a png
tmparr = tempfile(fileext=".png")
ray_read_image(dragon) |>
 ray_write_image(tmparr)
ray_read_image(tmparr) |>
 plot_image()
}
if(run_documentation()){
#Write as a JPEG (passing quality arguments via ...)
tmparr = tempfile(fileext=".jpg")
ray_read_image(dragon) |>
 ray_write_image(tmparr, quality = 0.2)
ray_read_image(tmparr) |>
 plot_image()
}
if(run_documentation()){
#Write as a tiff
tmparr = tempfile(fileext=".tiff")
ray_read_image(dragon) |>
 ray_write_image(tmparr)
ray_read_image(tmparr) |>
  plot_image()
}

Render Bokeh

Description

Takes an image and a depth map to render the image with depth of field (i.e. similar to "Portrait Mode" in an iPhone). User can specify a custom bokeh shape, or use one of the built-in bokeh types.

Usage

render_bokeh(
  image,
  depthmap,
  focus = 0.5,
  focallength = 100,
  fstop = 4,
  filename = NULL,
  preview = TRUE,
  preview_focus = FALSE,
  bokehshape = "circle",
  bokehintensity = 1,
  bokehlimit = 0.8,
  rotation = 0,
  aberration = 0,
  gamma_correction = TRUE,
  progress = interactive(),
  ...
)

Arguments

Value

3-layer RGB array of the processed image.

Examples

if(run_documentation()){
#Plot the dragon
plot_image(dragon)
}
if(run_documentation()){
#Plot the depth map
plot_image(dragondepth/1500)
}
if(run_documentation()){
#Preview the focal plane:
render_bokeh(dragon, dragondepth, focus=950, preview_focus = TRUE)
}
if(run_documentation()){
#Change the focal length:
render_bokeh(dragon, dragondepth, focus=950, focallength=300)
}
if(run_documentation()){
#Add chromatic aberration:
render_bokeh(dragon, dragondepth, focus=950, focallength=300, aberration = 0.5)
}
if(run_documentation()){
#Change the focal distance:
render_bokeh(dragon, dragondepth, focus=600, focallength=300)
render_bokeh(dragon, dragondepth, focus=1300, focallength=300)
}
if(run_documentation()){
#Change the bokeh shape to a hexagon:
render_bokeh(dragon, dragondepth, bokehshape = "hex",
            focallength=300, focus=600)
}
if(run_documentation()){
#Change the bokeh intensity:
render_bokeh(dragon, dragondepth,
            focallength=400, focus=900, bokehintensity = 1)
render_bokeh(dragon, dragondepth,
            focallength=400, focus=900, bokehintensity = 3)
}
if(run_documentation()){
#Rotate the hexagonal shape:
render_bokeh(dragon, dragondepth, bokehshape = "hex", rotation=15,
            focallength=300, focus=600)
}

Render Boolean Distance

Description

Takes an matrix (or and returns the nearest distance to each TRUE.

Usage

render_boolean_distance(boolean, rescale = FALSE)

Arguments

Value

Matrix of distance values.

Examples

if(run_documentation()){
#Measure distance to
plot_image(render_boolean_distance(t(volcano) > 150))
plot_image(render_boolean_distance(t(volcano) < 150))
}
if(run_documentation()){
#If we want to rescale this to zero to one (to visualize like an image), set rescale=TRUE
plot_image(render_boolean_distance(t(volcano) > 150,rescale=TRUE))
}

Render Black and White

Description

Transforms an image to black and white, preserving luminance.

Usage

render_bw(
  image,
  rgb_coef = c(0.2126, 0.7152, 0.0722),
  filename = NULL,
  preview = FALSE
)

Arguments

Value

3-layer RGB resized array or matrix.

Examples

if(run_documentation()){
#Plot the image with a title
dragon |>
 render_title("Dragon", title_offset=c(10,10), title_bar_color="black",
           title_size=20, title_color = "white") |>
 render_bw(preview = TRUE)
}

Clamp Image

Description

Clamps an image to a user-specified range

Usage

render_clamp(image, min_value = 0, max_value = 1, preview = FALSE, ...)

Arguments

Value

3-layer RGB array of the processed image.

Examples

if(run_documentation()){
#The rnage of the unchanged image
range(dragon)
}
if(run_documentation()){
#Clamp the maximum and minimum values to one and zero
render_clamp(dragon) |>
 range()
}

Render Convolution

Description

Takes an image and applys a convolution operation to it, using a user-supplied or built-in kernel. Edges are calculated by limiting the size of the kernel to only that overlapping the actual image (renormalizing the kernel for the edges).

Usage

render_convolution(
  image,
  kernel = "gaussian",
  kernel_dim = 11,
  kernel_extent = 3,
  absolute = TRUE,
  min_value = NULL,
  filename = NULL,
  preview = FALSE,
  gamma_correction = FALSE,
  progress = FALSE
)

Arguments

Value

3-layer RGB array of the processed image.

Examples

if(run_documentation()){
#Perform a convolution with the default gaussian kernel
plot_image(dragon)
}
if(run_documentation()){
#Perform a convolution with the default gaussian kernel
render_convolution(dragon, preview = TRUE)
}
if(run_documentation()){
#Increase the width of the kernel
render_convolution(dragon, kernel = 2, kernel_dim=21,kernel_extent=6, preview = TRUE)
}
if(run_documentation()){
#Perform edge detection using a edge detection kernel
edge = matrix(c(-1,-1,-1,-1,8,-1,-1,-1,-1),3,3)
render_convolution(render_bw(dragon), kernel = edge, preview = TRUE, absolute=FALSE)
}
if(run_documentation()){
#Perform edge detection with Sobel matrices
sobel1 = matrix(c(1,2,1,0,0,0,-1,-2,-1),3,3)
sobel2 = matrix(c(1,2,1,0,0,0,-1,-2,-1),3,3,byrow=TRUE)
sob1 = render_convolution(render_bw(dragon), kernel = sobel1)
sob2 = render_convolution(render_bw(dragon), kernel = sobel2)
sob_all = sob1 + sob2
plot_image(sob1)
plot_image(sob2)
plot_image(sob_all)
}

if(run_documentation()){
#Only perform the convolution on bright pixels (bloom)
render_convolution(dragon, kernel = 5, kernel_dim=24, kernel_extent=24,
                  min_value=1, preview = TRUE)
}
if(run_documentation()){
#Use a built-in kernel:
render_convolution(dragon, kernel = generate_2d_exponential(falloff=2, dim=31, width=21),
                  preview = TRUE)
}
if(run_documentation()){
#We can also apply this function to matrices:
volcano |> image()
volcano |>
 render_convolution(kernel=generate_2d_gaussian(sd=1,dim=31)) |>
 image()
}
if(run_documentation()){
#Use a custom kernel (in this case, an X shape):
custom = diag(10) + (diag(10)[,10:1])
plot_image(custom)
render_convolution(dragon, kernel = custom, preview = TRUE)
}

Render Convolution FFT

Description

Takes an image and applys a convolution operation to it, using a user-supplied or built-in kernel. This function uses a fast-fourier transform and does the convolution in the frequency domain, so it should be faster for much larger kernels.

Usage

render_convolution_fft(
  image,
  kernel = "gaussian",
  kernel_dim = c(11, 11),
  kernel_extent = 3,
  absolute = TRUE,
  pad = 50,
  filename = NULL,
  preview = FALSE,
  gamma_correction = FALSE
)

Arguments

Value

3-layer RGB array of the processed image.

Examples

if(run_documentation()){
#Perform a convolution with the default gaussian kernel
plot_image(dragon)
}
if(run_documentation()){
#Perform a convolution with the default gaussian kernel
render_convolution_fft(dragon, kernel=0.1,preview = TRUE)
}
if(run_documentation()){
#Increase the width of the kernel
render_convolution_fft(dragon, kernel = 2, kernel_dim=21,kernel_extent=6, preview = TRUE)
}
if(run_documentation()){
#Use a built-in kernel:
render_convolution_fft(dragon, kernel = generate_2d_exponential(falloff=2, dim=31, width=21),
                      preview = TRUE)
}
if(run_documentation()){
#Perform edge detection
edge = matrix(c(-1,-1,-1,-1,8,-1,-1,-1,-1),3,3)
render_convolution_fft(render_bw(dragon), kernel = edge, preview = TRUE)
}
if(run_documentation()){
#Perform edge detection with Sobel matrices
sobel1 = matrix(c(1,2,1,0,0,0,-1,-2,-1),3,3)
sobel2 = matrix(c(1,2,1,0,0,0,-1,-2,-1),3,3,byrow=TRUE)
sob1 = render_convolution_fft(render_bw(dragon), kernel = sobel1)
sob2 = render_convolution_fft(render_bw(dragon), kernel = sobel2)
sob_all = sob1 + sob2
plot_image(sob1)
plot_image(sob2)
plot_image(sob_all)
}
if(run_documentation()){
#We can also apply this function to matrices:
volcano |> image()
volcano |>
 render_convolution_fft(kernel=generate_2d_gaussian(sd=1,dim=31)) |>
 image()
}
if(run_documentation()){
# Because this function uses the fast-fourier transform, large kernels will be much faster
# than the same size kernels in `render_convolution()`
render_convolution_fft(dragon, kernel_dim = c(200,200) , preview = TRUE)
}
if(run_documentation()){
#Use a custom kernel (in this case, an X shape):
custom = diag(10) + (diag(10)[,10:1])
#Normalize
custom = custom / 20
plot_image(custom*20)
render_convolution_fft(dragon, kernel = custom, preview = TRUE)
}

Add Overlay

Description

Takes an RGB array/filename and adds an image overlay.

Usage

render_image_overlay(
  image,
  image_overlay = NULL,
  rescale_original = FALSE,
  alpha = NULL,
  filename = NULL,
  preview = FALSE
)

Arguments

Value

3-layer RGB array of the processed image.

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

Reorient Image

Description

Reorients an image or matrix. Transformations are applied in this order: x, y, and transpose.

Usage

render_reorient(
  image,
  flipx = FALSE,
  flipy = FALSE,
  transpose = FALSE,
  filename = NULL,
  preview = FALSE
)

Arguments

Value

3-layer RGB reoriented array or matrix.

Examples

if(run_documentation()){
#Original orientation
plot_image(dragon)
}
if(run_documentation()){
#Flip the dragon image horizontally
dragon |>
 render_reorient(flipx = TRUE) |>
 plot_image()
}
if(run_documentation()){
#Flip the dragon image vertically
dragon |>
 render_reorient(flipy = TRUE) |>
 plot_image()
}
if(run_documentation()){
#Transpose the dragon image
dragon |>
 render_reorient(transpose = TRUE) |>
 plot_image()
}

Resize Image

Description

Resizes an image or a matrix, using bilinear interpolation.

Usage

render_resized(
  image,
  mag = 1,
  dims = NULL,
  filename = NULL,
  preview = FALSE,
  method = "tri"
)

Arguments

Value

3-layer RGB resized array or matrix.

Examples

if(run_documentation()){
#Plot the image with a title
dragon |>
 render_title("Dragon", title_offset=c(10,10), title_bar_color="black",
           title_size=20, title_color = "white") |>
 plot_image()
}
if(run_documentation()){
#Half of the resolution
render_resized(dragon, mag = 1/2) |>
 render_title("Dragon (half res)", title_offset=c(5,5), title_bar_color="black",
           title_size=10, title_color = "white") |>
 plot_image()
}
if(run_documentation()){
#Double the resolution
render_resized(dragon, mag = 2) |>
 render_title("Dragon (2x res)", title_offset=c(20,20), title_bar_color="black",
           title_size=40, title_color = "white") |>
 plot_image()
}
if(run_documentation()){
#Specify the exact resulting dimensions
render_resized(dragon, dim = c(320,160)) |>
 render_title("Dragon (custom size)", title_offset=c(10,10), title_bar_color="black",
           title_size=20, title_color = "white") |>
 plot_image()
}

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

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

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

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

Add Vignette Effect

Description

Takes an RGB array/filename and adds a camera vignette effect.

Usage

render_vignette(
  image,
  vignette = 0.5,
  color = "#000000",
  radius = 1.3,
  filename = NULL,
  preview = FALSE
)

Arguments

Value

3-layer RGB array of the processed image.

Examples

if(run_documentation()){
#Plot the dragon
plot_image(dragon)
}
if(run_documentation()){
#Add a vignette effect:
render_vignette(dragon, preview = TRUE, vignette = 0.5)
}
if(run_documentation()){
#Darken the vignette effect:
render_vignette(dragon, preview = TRUE, vignette = 1)
}
if(run_documentation()){
#Change the radius:
render_vignette(dragon, preview = TRUE, vignette = 1, radius=1.5)
render_vignette(dragon, preview = TRUE, vignette = 1, radius=0.5)
}
if(run_documentation()){
#Change the color:
render_vignette(dragon, preview = TRUE, vignette = 1, color="white")
}
if(run_documentation()){
#Increase the width of the blur by 50%:
render_vignette(dragon, preview = TRUE, vignette = c(1,1.5))
}

Run Documentation

Description

This function determines if the examples are being run in pkgdown. It is not meant to be called by the user.

Usage

run_documentation()

Value

Boolean value.

Examples

# See if the documentation should be run.
run_documentation()

Save PNG

Description

Writes the hillshaded map to file.

Usage

save_png(hillshade, filename, rotate = 0)

Arguments

Examples

#internal

trim_padding

Description

Trims padding

Usage

trim_padding(input, pad = 1)

Arguments

Value

Matrix with edges trimmed