memery (version 0.6.0)

meme: Generate a meme

Description

Generate a meme with a background image, text label and optional inset graphic.

Usage

meme(
  img,
  label,
  file,
  size = 1,
  family = "Impact",
  col = "white",
  shadow = "black",
  label_pos = text_position(length(label)),
  inset = NULL,
  ggtheme = memetheme(),
  inset_bg = inset_background(),
  inset_pos = inset_position(),
  width,
  height,
  bg = "transparent",
  mult = 1
)
meme_gif(
  img,
  label,
  file,
  size = 1,
  family = "Impact",
  col = "white",
  shadow = "black",
  label_pos = text_position(length(label)),
  inset = NULL,
  ggtheme = memetheme(),
  inset_bg = inset_background(),
  inset_pos = inset_position(),
  width,
  height,
  bg = "transparent",
  mult = 1,
  fps = 10,
  frame = 0,
  ...
)

Value

nothing is returned; file written to disk.

Arguments

img

path to image file, png or jpg.

label

character, meme text. May be a vector, matched to label_pos.

file

output file, png or jpg.

size

label size. Actual size affected by image size, i.e., cex.

family

character, defaults to "Impact", the classic meme font. See details.

col

label color.

shadow

label shadow/outline color.

label_pos

named list of position elements for the meme text w, h, x and y. Each element may be a vector. See details.

inset

a ggplot object. This is an optional inset plot and may be excluded.

ggtheme

optional ggplot2 theme. If ignored, the default memery ggplot2 theme is used.

inset_bg

a list of background settings for the plotting region containing inset. See details.

inset_pos

named list of position elements for the inset inset plot: w, h, x and y.

width

numeric, width of overall meme plot in pixels. If missing, taken from img size.

height

numeric, height of overall meme plot in pixels. If missing, taken from img size.

bg

character, background color for graphics device.

mult

numeric, a multiplier. Used to adjust width and height. See details.

fps

frames per second, only applicable to meme_gif(). See details.

frame

integer, frame numbers to include. The default frame = 0 retains all frames. Only applicable to meme_gif(). See details.

...

additional arguments passed to meme_gif().

Fonts

Memes use the Impact font by default. This is a Windows font. If using memery on Linux for example, you would have to first install the font if not already installed on the system. If Impact or any other font family passed to meme(), e.g. family = "Consolas", is not installed on an operating system, meme() will ignore it and fall back on family = "serif" internally. If unfamiliar, explore the documentation and examples available for the showtext and sysfonts packages, which merery leverages.

Text labels

List elements in label_pos must all be the same length and must match the length of label. This is provided for generality but is most suited to length-2 cases; the use of meme title/subtitle or top/bottom text pairs. Similarly, size, family, col and shadow may be vectorized. For example, top and bottom text can have different font size and family and the font text and shadow can be different colors.

Inset graphic

The meme plot may optionally include an inset plot by passing a ggplot object to inset. This makes the memes more fun for data analysts. See examples.

The plotting region containing inset is a specific viewport in the grid layout. inset_bg is a list of arguments that affect the background of this part of the meme plot. They define a rectangle that by default is semi-transparent with rounded corners and no border color. This can be changed via the list arguments fill, col and r.

The inset plot inset is placed above this layer and also fills the region. The default ggplot2 theme used my meme(), memetheme(), uses transparent ggplot plot and panel background fill and plot border color that allow the background viewport rectangle and its rounded corners to show through. The default theme also has no plot margins.

If you supply a different theme via ggtheme, you can provide different plot and panel background fill and plot border color as part of the theme. For similar no-margin themes, if the plot background fill or border color are not fully transparent, set the viewport rectangle corner radius to zero so that rounded corners do not show inside the panel background. For opaque plot background fill this will not matter.

Of course, the plot and panel background fill should still be transparent or semi-transparent if occupying a large amount of the total meme plot area or it will obscure the meme image itself. An alternative is to use inset as, for example, a tiny thumbnail in the corner of the meme plot, in which case full opacity is not necessarily an issue. If you do not want to override the theme of your plot and do not wish to pass a theme explicitly by ggtheme, you can set ggtheme = NULL.

Dimensions and image processing

Specifying width and height is not required. By default, output file dimensions are taken from the input file, img. However, these arguments can be used to override the default dimension matching. The aspect ratio is fixed so if you change the two disproportionately, you will increasing the canvas, adding bars on two sides; it will not stretch the image.

mult can be set less than one if relying on img dimension for meme plot width and height and img is large. It is equivalent to scaling proportionately with width and height maintaining the original aspect ratio. Whether or not width and/or height are provided, mult is always applied (defaults to mult = 1).

Beyond this basic resizing to help control output file size, it is not the intent of memery to offer general image processing capabilities. If adjustments to source images are desired, you should use a dedicated package for image processing. magick is recommended.

Reading and writing gifs

Reading and writing gifs requires the magick package. Since this is not required for any other part of memery and it represents a minor use case, the package does not have these dependencies. magick is listed as a suggested package for memery; it is not imported as a dependency. meme_gif() is an optional extra function. In order to use it, install the magick package.

See the example below if your system meets these requirements. As with jpg or png image inputs, if additional control is required for making custom adjustments to gif image frames, use the magick package for image pre-processing. meme() only provides basic control over output size and meme_gif() only adds control over gif frame selection and rate.

Details

This function generates and saves a meme as a jpg or png file.

Examples

# Prepare data and make a graph
library(ggplot2)
x <- seq(0, 2*pi, length.out = 50)
panels <- rep(c("Plot A", "Plot B"), each = 50)
d <- data.frame(x = x, y = sin(x), grp = panels)
txt <- c("Philosoraptor's plots", "I like to make plots",
  "Figure 1. (A) shows a plot and (B) shows another plot.")
out <- tempfile("meme", fileext = c("1.png", "2.png", "3.png", "4.gif"))

p <- ggplot(d, aes(x, y)) + geom_line(colour = "cornflowerblue", linewidth = 2) +
  geom_point(colour = "orange", size = 4) + facet_wrap(~grp) +
  labs(title = txt[1], subtitle = txt[2], caption = txt[3])

# meme image background and text labels
img <- system.file("philosoraptor.jpg", package = "memery")
lab <- c("Title meme text", "Subtitle text")

if (FALSE) {
# Not run due to file size
# basic meme
meme(img, lab[1:2], out[1])
# data analyst's meme
meme(img, lab[1:2], out[2], size = 2, inset = p, mult = 2)
}

# data meme with additional content control
vp_bg <- list(fill = "#FF00FF50", col = "#FFFFFF80") # graph background
# arbitrary number of labels, placement, and other vectorized attributes
lab <- c(lab, "Middle plot text")
pos <- list(w = rep(0.9, 3), h = rep(0.3, 3), x = c(0.35, 0.65, 0.5),
  y = c(0.95, 0.85, 0.3))
fam <- c("Impact", "serif", "Impact")
clrs1 <- c("black", "orange", "white")
clrs2 <- clrs1[c(2, 1, 1)]

if (FALSE) {
meme(img, lab, out[3], size = c(2, 1.5, 1), family = fam, col = clrs1,
  shadow = clrs2, label_pos = pos, inset = p, inset_bg = vp_bg, mult = 2)
}

if (FALSE) {
# Not run due to file size, software requirements, web source
# GIF meme. Requires magick package.
p <- ggplot(d, aes(x, y)) + geom_line(colour = "white", linewidth = 2) +
  geom_point(colour = "orange", size = 1) + facet_wrap(~grp) +
  labs(title = "The wiggles", subtitle = "Plots for cats",
       caption = "Figure 1. Gimme sine waves.")
lab <- c("R plots for cats", "Sine wave sine wave sine wave sine wave...")
pos <- list(w = rep(0.9, 2), h = rep(0.3, 2), x = rep(0.5, 2), y = c(0.9, 0.75))
img <- "https://raw.githubusercontent.com/leonawicz/memery/master/data-raw/cat.gif"
meme_gif(img, lab, out[4], size = c(1.5, 0.75), label_pos = pos,
         inset = p, inset_bg = list(fill = "#00BFFF80"), mult = 1.5, fps = 20)
}