Skip to contents

Specify existing images, taxonomic names, or PhyloPic uuids to add PhyloPic silhouettes as a separate layer to an existing ggplot plot.


  img = NULL,
  name = NULL,
  uuid = NULL,
  filter = NULL,
  ysize = Inf,
  alpha = 1,
  color = NA,
  fill = "black",
  horizontal = FALSE,
  vertical = FALSE,
  angle = 0,
  remove_background = TRUE,
  verbose = FALSE



A Picture or png array object, e.g., from using get_phylopic().


character. A taxonomic name to be passed to get_uuid().


character. A valid uuid for a PhyloPic silhouette (such as that returned by get_uuid() or pick_phylopic()).


character. Filter by usage license if name is defined. Use "by" to limit results to images which do not require attribution, "nc" for images which allows commercial usage, and "sa" for images without a ShareAlike clause. The user can also combine these filters as a vector.


numeric. x value of the silhouette center.


numeric. y value of the silhouette center.


numeric. Height of the silhouette. The width is determined by the aspect ratio of the original image. If "Inf", the default, the height will be as tall as will fit within the plot area.


numeric. A value between 0 and 1, specifying the opacity of the silhouette (0 is fully transparent, 1 is fully opaque).


character. Color of silhouette outline. If "original" or NA is specified, the original color of the silhouette outline will be used (usually the same as "transparent"). To remove the outline, you can set this to "transparent".


character. Color of silhouette. If "original" is specified, the original color of the silhouette will be used (usually the same as "black"). If color is specified and fill is NA, color will be used as the fill color (for backwards compatibility). To remove the fill, you can set this to "transparent".


logical. Should the silhouette be flipped horizontally?


logical. Should the silhouette be flipped vertically?


numeric. The number of degrees to rotate the silhouette clockwise. The default is no rotation.


logical. Should any white background be removed from the silhouette(s)? See recolor_phylopic() for details.


logical. Should the attribution information for the used silhouette(s) be printed to the console (see get_attribution())?


One (and only one) of img, name, or uuid must be specified. Use parameters x, y, and ysize to place the silhouette at a specified position on the plot. The aspect ratio of the silhouette will always be maintained.

x and/or y may be vectors of numeric values if multiple silhouettes should be plotted at once. In this case, any other arguments (except for remove_background) may also be vectors of values, which will be recycled as necessary.

When specifying a horizontal and/or vertical flip and a rotation, the flip(s) will always occur first. If you would like to customize this behavior, you can flip and/or rotate the image within your own workflow using flip_phylopic() and rotate_phylopic().

Note that png array objects can only be rotated by multiples of 90 degrees. Also, outline colors do not currently work for png array objects.


if (FALSE) {
# Put a silhouette behind a plot based on a taxonomic name
ggplot(iris) +
  add_phylopic(x = 6.1, y = 3.2, name = "Iris", alpha = 0.2) +
  geom_point(aes(x = Sepal.Length, y = Sepal.Width))

# Put a silhouette in several places based on UUID
posx <- runif(10, 0, 10)
posy <- runif(10, 0, 10)
sizey <- runif(10, 0.4, 2)
angle <- runif(10, 0, 360)
hor <- sample(c(TRUE, FALSE), 10, TRUE)
ver <- sample(c(TRUE, FALSE), 10, TRUE)
fills <- sample(c("black", "darkorange", "grey42", "white"), 10,
  replace = TRUE)
alpha <- runif(10, 0.3, 1)

p <- ggplot(data.frame(cat.x = posx, cat.y = posy), aes(cat.x, cat.y)) +
  geom_blank() +
  add_phylopic(uuid = "23cd6aa4-9587-4a2e-8e26-de42885004c9",
               x = posx, y = posy, ysize = sizey,
               fill = fills, alpha = alpha, angle = angle,
               horizontal = hor, vertical = ver)
p + ggtitle("R Cat Herd!!")