Generate a meme with a background image, text label and optional inset graphic.
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,
...
)path to image file, png or jpg.
character, meme text. May be a vector, matched to label_pos.
output file, png or jpg.
label size. Actual size affected by image size, i.e., cex.
character, defaults to "Impact", the classic meme font. See
details.
label color.
label shadow/outline color.
named list of position elements for the meme text w, h,
x and y. Each element may be a vector. See details.
a ggplot object. This is an optional inset plot and may be excluded.
optional ggplot2 theme. If ignored, the default memery
ggplot2 theme is used.
a list of background settings for the plotting region
containing inset. See details.
named list of position elements for the inset inset plot:
w, h, x and y.
numeric, width of overall meme plot in pixels. If missing, taken
from img size.
numeric, height of overall meme plot in pixels. If missing,
taken from img size.
character, background color for graphics device.
numeric, a multiplier. Used to adjust width and height. See details.
frames per second, only applicable to meme_gif(). See details.
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().
nothing is returned; file written to disk.
This function generates and saves a meme as a jpg or png file.
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.
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.
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.
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 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.
# 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) { # \dontrun{
# 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) { # \dontrun{
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) { # \dontrun{
# 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)
} # }