Annotate a plot with icons at fixed positions

annotation_icon() draws one or more icons at fixed (x, y) positions, the icon analogue of ggplot2::annotation_custom() / ggplot2::annotation_raster(): a single call that adds icons directly, without a data frame or aes() mapping. Unlike those, though, annotation_icon() does train the panel's position scales, since a fixed-position icon is more usefully treated like a point annotation (e.g. ggplot2::annotate()) than like an arbitrary grob pinned to the panel's corners, so placing one outside the data's range still expands the axes to fit it.

Usage

annotation_icon(
  icon,
  x,
  y,
  colour = "black",
  fill = NA,
  size = 6,
  alpha = NA,
  angle = 0,
  size.unit = "mm"
)

Arguments

icon

An icon vector from the icons package. Character ids are not resolved; pass an actual icon vector.

x, y

The position(s) to draw the icon(s) at, in data coordinates.

colour, fill

Fill colour for the icon; fill wins when both are set.

size

The icon's width/height, in size.unit.

alpha

Transparency, from 0 (fully transparent) to 1 (opaque).

angle

Rotation, in degrees.

size.unit

The unit in which size is interpreted, one of "mm" (default), "pt", "cm", "in", or another grid::unit()-compatible absolute unit.

Value

A ggplot2 layer.

Details

icon, x, y and the style arguments are all recycled to a common length, so a single call can place several icons at once (e.g. annotation_icon(icon = c(rocket, star), x = c(1, 2), y = c(1, 1))).

Aesthetics

annotation_icon() sets the same per-icon properties geom_icon() understands as aesthetics, but as plain arguments instead:

• icon (required): an icon vector from the icons package, an icon object (e.g. from icons::read_icon() or icons::fontawesome$solid$rocket) or an icons::icon_find() result.

• x, y: the position(s) to draw at, in data coordinates.

• colour/fill: both map to the icon's single fill colour (icons don't have a separate border); fill wins when both are set.

• alpha

• size: the icon's width/height, in size.unit (default millimetres).

• angle: rotation, in degrees.

stroke/linewidth don't apply, since icons are filled shapes, not framed ones.

See also

geom_icon()

Examples

library(ggplot2)

# bundled placeholder shapes; a real pack (e.g. icons::fontawesome) works the same
shapes <- icons::icon_set(system.file("icons", package = "ggicons"))
ggplot(data.frame(x = 1:3, y = c(1, 3, 2)), aes(x, y)) +
  geom_point() +
  annotation_icon(
    icon = shapes$star,
    x = 2, y = 3, size = 12, colour = "steelblue"
  )
#> Error in annotation_icon(icon = shapes$star, x = 2, y = 3, size = 12,     colour = "steelblue"): Problem while converting geom to grob.
#> ℹ Error occurred in the 2nd layer.
#> Caused by error in `loadNamespace()`:
#> ! there is no package called ‘grImport2’