Title:	Pixel Filters for 'ggplot2' and 'grid'
Version:	1.0.1
Description:	Provides a range of filters that can be applied to layers from the 'ggplot2' package and its extensions, along with other graphic elements such as guides and theme elements. The filters are applied at render time and thus uses the exact pixel dimensions needed.
License:	MIT + file LICENSE
Encoding:	UTF-8
Imports:	magick (≥ 2.7.1), ragg, grid, ggplot2, grDevices, gtable, rlang
RoxygenNote:	7.2.1
URL:	https://ggfx.data-imaginist.com, https://github.com/thomasp85/ggfx
BugReports:	https://github.com/thomasp85/ggfx/issues
Suggests:	covr, knitr, rmarkdown, farver (≥ 2.1.0)
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2022-08-22 07:41:01 UTC; thomas
Author:	Thomas Lin Pedersen [aut, cre], RStudio [cph, fnd]
Maintainer:	Thomas Lin Pedersen <thomasp85@gmail.com>
Repository:	CRAN
Date/Publication:	2022-08-22 08:00:06 UTC

ggfx: Pixel Filters for 'ggplot2' and 'grid'

Description

Provides a range of filters that can be applied to layers from the 'ggplot2' package and its extensions, along with other graphic elements such as guides and theme elements. The filters are applied at render time and thus uses the exact pixel dimensions needed.

Author(s)

Maintainer: Thomas Lin Pedersen thomasp85@gmail.com (ORCID)

Other contributors:

• RStudio [copyright holder, funder]

See Also

Useful links:

• https://ggfx.data-imaginist.com

• https://github.com/thomasp85/ggfx

• Report bugs at https://github.com/thomasp85/ggfx/issues

Set a channel of interest from a layer

Description

Some effects uses a particular channel for specific parameters, such as with_displacement(), which grabs the relative x and y displacements from different channels in some other layer. To facilitate specifying which channel to use from a layer (which is always multichannel), you can wrap the specification in a channel specifier given below. If a filter requires a specific channel and none is specified it will default to luminance (based on the hcl colour space)

Usage

ch_red(x, colourspace = "sRGB", invert = FALSE)

ch_green(x, colourspace = "sRGB", invert = FALSE)

ch_blue(x, colourspace = "sRGB", invert = FALSE)

ch_alpha(x, colourspace = "sRGB", invert = FALSE)

ch_hue(x, colourspace = "HCL", invert = FALSE)

ch_chroma(x, colourspace = "HCL", invert = FALSE)

ch_luminance(x, colourspace = "HCL", invert = FALSE)

ch_saturation(x, colourspace = "HSL", invert = FALSE)

ch_lightness(x, colourspace = "HSL", invert = FALSE)

ch_cyan(x, colourspace = "CMYK", invert = FALSE)

ch_magenta(x, colourspace = "CMYK", invert = FALSE)

ch_yellow(x, colourspace = "CMYK", invert = FALSE)

ch_black(x, colourspace = "CMYK", invert = FALSE)

ch_key(x, colourspace = "CMYK", invert = FALSE)

ch_custom(x, channel, colourspace, invert = FALSE)

Arguments

Value

x with a channel spec attached

Examples

library(ggplot2)
volcano_long <- data.frame(
  x = as.vector(col(volcano)),
  y  = as.vector(row(volcano)),
  z = as.vector(volcano)
)

# invert the green channel
ggplot(volcano_long, aes(y, x)) +
  as_reference(
    geom_contour_filled(aes(z = z, fill = after_stat(level))),
    id = 'contours'
  ) +
  as_colourspace(
    ch_red('contours'),
    ch_green('contours', invert = TRUE),
    ch_blue('contours')
  )

Collect channels into a single layer of a specific colourspace

Description

If you need to work on single channels one by one you can use the different ch_*() selectors. If the result needs to be combined again into a colour layer you can use as_colourspace and pass in the required channels to make up the colourspace. By default the alpha channel will be created as the combination of the alpha channels from the provided channel layers. Alternatively you can set auto_opacity = FALSE and provide one additional channel which will then be used as alpha.

Usage

as_colourspace(
  ...,
  colourspace = "sRGB",
  auto_opacity = TRUE,
  id = NULL,
  include = is.null(id)
)

Arguments

Value

A list of Layer objects

See Also

Other layer references: as_group(), as_reference()

Examples

library(ggplot2)

segments <- data.frame(
  x = runif(300),
  y = runif(300),
  xend = runif(300),
  yend = runif(300)
)

# We use 'white' as that is the maximum value in all channels
ggplot(mapping = aes(x, y, xend = xend, yend = yend)) +
  as_colourspace(
    geom_segment(data = segments[1:100,], colour = 'white'),
    geom_segment(data = segments[101:200,], colour = 'white'),
    geom_segment(data = segments[201:300,], colour = 'white'),
    colourspace = 'CMY'
  )

Collect layers into a group that can be treated as a single layer

Description

While you often want to apply filters to layers one by one, there are times when one filter should be applied to a collection of layers as if they were one. This can be achieved by first combining all the layers into a group with as_group() and applying the filter to the resulting group. This can only be done to ggplot2 layers and grobs as the other supported objects are not part of a graphic stack.

Usage

as_group(..., id = NULL, include = is.null(id))

Arguments

Value

A list of Layer objects or a gTree depending on the input

See Also

Other layer references: as_colourspace(), as_reference()

Examples

library(ggplot2)

# With no grouping the filters on layers are applied one by one
ggplot(mtcars, aes(mpg, disp)) +
  with_shadow(geom_smooth(alpha = 1), sigma = 4) +
  with_shadow(geom_point(), sigma = 4)

# Grouping the layers allows you to apply a filter on the combined result
ggplot(mtcars, aes(mpg, disp)) +
  as_group(
    geom_smooth(alpha = 1),
    geom_point(),
    id = 'group_1'
  ) +
  with_shadow('group_1', sigma = 4)

Create a reference to a layer for use in other filters

Description

This function is basically synonymous with with_raster() but exist to make the intend of marking a layer with a specific id clear.

Usage

as_reference(x, id = NULL, include = is.null(id))

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

See Also

Other layer references: as_colourspace(), as_group()

Examples

library(ggplot2)

ggplot() +
  as_reference(
    geom_point(aes(20, 300), size = 100, colour = 'white'),
    id = 'mask_layer'
  ) +
  with_mask(
    geom_point(aes(mpg, disp), mtcars, size = 5),
    mask = 'mask_layer'
  )

Raster Helpers

Description

Raster Helpers

Usage

blend_raster(x, bg_layer, blend_type = "Over", flip_order = FALSE, alpha = NA)

blend_custom_raster(x, bg_layer, a, b, c, d, flip_order = FALSE, alpha = NA)

bloom_raster(
  x,
  threshold_lower = 80,
  threshold_upper = 100,
  sigma = 5,
  strength = 1,
  keep_alpha = TRUE
)

blur_raster(x, sigma = 0.5, stack = FALSE)

displace_raster(x, x_map, y_map = x_map, x_scale = 1, y_scale = x_scale)

dither_raster(x, max_colours = 256, colourspace = "sRGB")

inner_glow_raster(x, colour = "black", sigma = 3, expand = 0)

interpolate_raster(x, bg_layer, src_percent, bg_percent)

convolve_grob(
  x,
  kernel,
  iterations = 1,
  scaling = NULL,
  bias = NULL,
  stack = FALSE
)

mask_raster(x, mask, invert = FALSE)

motion_blur_raster(x, sigma = 0.5, angle = 0)

ordered_dither_raster(x, map, colourspace = "sRGB", offset = NULL)

outer_glow_raster(x, colour = "black", sigma = 3, expand = 0)

shade_raster(
  x,
  height_map,
  azimuth = 30,
  elevation = 30,
  strength = 10,
  sigma = 0,
  blend_type = "overlay"
)

variably_blur_raster(
  x,
  x_sigma,
  y_sigma = x_sigma,
  angle = NULL,
  x_scale = 1,
  y_scale = x_scale,
  angle_range = 0
)

Value

A nativeRaster object

Supported object types

Description

The different filters provided by ggfx are applicable to a wide range of object types. Rather than documenting how to use them with each type in every documentation entry, the information is collected here. While the examples will use with_blur() they are general and applicable to all filters in ggfx.

Value

All filters will generally return a new version of the same object, the only exception being filtering of rasters, functions, and references which returns a Layer object

Method specific arguments

• id: A string that identifies the result of this filter, to be referenced by other filters in the same graphic.

• include: A logical flag that indicates whether the filtered image should be displayed. By default, the result will not be displayed if it is given an id (as it is assumed that it is meant for later use), but this can be overewritten by setting include = TRUE.

• ignore_background: Should the background of the plot be removed before applying the filter and re-added afterwards?

• background: A grob to draw below the result of the filter. Mainly for internal use for supporting ignore_background.

Filtering layers

This is perhaps the most common and obvious use of ggfx, and the one show-cased in the respective docs of each filter. In order to apply a filter to a ggplot2 layer you wrap it around the layer constructor (usually a ⁠geom_*()⁠ function) and pass in additional parameters after it:

ggplot(mtcars) +
  with_blur(
    geom_point(aes(x = mpg, y = disp)),
    sigma = 4
  )

Apart from the arguments specific to the filter, layer filters also take an id, and include argument. Providing an id (as a string) will make this filter be referable by other filters. By default this turns of rendering of the result, but setting include = TRUE will turn rendering back on (while still making it referable). Referable layers should always come before whatever other layer ends up referring to them, since ggfx does not have control over the rendering order. Not following this rule will have undefined consequences (either an error or a weird plot - or maybe the correct result)

Filtering layer references

While the first argument to a filter is mostly some sort of graphic generating object, it can also be a text string referring to another filter. This allows you to string together filters, should you so choose. The big caveat is that filtering a reference will always result in a layer - i.e. it is not compatible outside of ggplot2.

ggplot(mtcars) +
  with_blur(
    geom_point(aes(x = mpg, y = disp)),
    sigma = 4,
    id = 'blurred_points'
  ) +
  with_shadow(
    'blurred_points'
  )

Filtering guides

ggplot2 does not only consist of layers - there are all sort of other graphic elements around them. Guides are one such type of element and these can be filtered by wrapping the filter around the guide constructor:

ggplot(mtcars) +
  geom_point(aes(x = mpg, y = disp, colour = gear)) +
  guides(colour = with_blur(guide_colourbar(), sigma = 4))

There is a caveat here in that it is not possible to use this with the string shorthand (i.e. with_blur('colourbar') won't work) — you have to use the functional form.

Filtering theme elements

Theme elements, like guides, is another non-layer graphic that is amenable to filtering. It can be done by wrapping the ⁠element_*()⁠ constructor with a filter:

ggplot(mtcars) +
  geom_point(aes(x = mpg, y = disp)) +
  ggtitle("A blurry title") +
  theme(plot.title = with_blur(element_text(), sigma = 4))

There is a caveat here as well. The filtering doesn't get carried through inheritance so you cannot set filtering at a top-level element and expect all child elements to be filtered.

Filtering ggplots

While you normally only want to add a filter to a part of the plot, it is also possible to add it to everthing, simply by wrapping the filter function around the plot. You can elect to remove the background element while applying the filter and add it back on afterwards by setting ignore_background = TRUE on the filter

p <- ggplot(mtcars) +
  geom_point(aes(x = mpg, y = disp))

with_blur(p, sigma = 4)

An alternative is to put the filter around the ggplot() call, which will have the same effect and may fit better with your plot construction code

with_blur(ggplot(mtcars), sigma = 4) +
  geom_point(aes(x = mpg, y = disp))

Filtering grobs

At the lowest level, it is possible to apply a filter to a grob. This is what powers all of the above at some level and that power is also available to you. It is done in the same manner as all of the above, by wrapping the grob in a filter:

blurred_circle <- with_blur(circleGrob(), sigma = 4)

grid.newpage()
grid.draw(blurred_circle)

As with layers, filters applied to grobs also take an id and include argument and they have the same effect. It should be noted that it can be difficult to grasp the rendering order of elements in a manually created grid graphics, so take care when using filters that refer to each other as the rule about the rendering order still applies.

There are not a lot of people who use grid directly, but if you develop ggplot2 extensions the ability to apply filters to grobs means that you can create geoms with filters build right into them!

Control placements of raster in the plot

Description

When using raster objects directly you need to somehow define how it should be located in resized in the plot. These function can be used to inform the filter on how it should be used. They only work on raster type object, so cannot be used around functions or layer id's.

Usage

ras_fill(raster, align_to = "canvas")

ras_fit(raster, align_to = "canvas")

ras_stretch(raster, align_to = "canvas")

ras_place(raster, align_to = "canvas", anchor = "topleft", offset = c(0, 0))

ras_tile(
  raster,
  align_to = "canvas",
  anchor = "topleft",
  offset = c(0, 0),
  flip = FALSE
)

Arguments

Value

The input with additional information attached

Examples

library(ggplot2)
logo <- as.raster(magick::image_read(
  system.file('help', 'figures', 'logo.png', package = 'ggfx')
))

# Default is to fill the viewport area, preserving the aspect ratio of the
# raster
ggplot(mtcars) +
  with_blend(
    geom_point(aes(mpg, disp)),
    logo
  )

# But you can change that with these functions:
ggplot(mtcars) +
  with_blend(
    geom_point(aes(mpg, disp)),
    ras_place(logo, 'vp', 'bottomright')
  )

# Here we tile it with flipping, centering on the middle of the canvas
ggplot(mtcars) +
  with_blend(
    geom_point(aes(mpg, disp)),
    ras_tile(logo, anchor = 'center', flip = TRUE)
  )

Rendering information

Description

These utility functions can help when creating custom filters (using with_custom()) as they can provide information about the current rendering context.

Usage

viewport_location()

index_raster(raster, cols, rows)

get_raster_area(raster, xmin, ymin, xmax, ymax)

set_raster_area(raster, value, xmin, ymin)

get_viewport_area(raster)

set_viewport_area(raster, value)

viewport_is_clipping()

current_resolution()

to_pixels(x, y_axis = FALSE, location = FALSE)

from_pixels(x)

Arguments

Details

• viewport_location(): Returns the bounding box defining the current viewport in pixels in the order xmin, ymin, xmax, ymax

• index_raster(): Is a version of the classic ⁠[,]⁠ indexing that is aware of the row-major order of rasters

• get_raster_area(): Extracts an area of a raster based on a bounding box

• set_raster_area(): Sets an area of a raster to a new raster value

• get_viewport_area(): A version of get_raster_area() that specifically extract the area defined by the current viewport

• set_viewport_area(): A version of set_raster_area() that specifically sets the area defined by the current viewport

• viewport_is_clipping(): Returns TRUE if the current viewport has clipping turned on

• current_resolution(): Returns the resolution of the active device in ppi (pixels-per-inch)

• to_pixels(x): Converts x to pixels if x is given as a unit object. It is assumed that x encodes a dimension and not a location. If x is a numeric it is assumed to already be in pixels

• from_pixels: Converts a numeric giving some pixel dimension to a unit object.

Value

Depends on the function - see details.

Examples

# These functions are intended to be used inside filter functions, e.g.
library(ggplot2)

flip_raster <- function(raster, horizontal = TRUE) {
  # Get the viewport area of the raster
  vp <- get_viewport_area(raster)

  # Get the columns and rows of the raster - reverse order depending on
  # the value of horizontal
  dims <- dim(vp)
  rows <- seq_len(dims[1])
  cols <- seq_len(dims[2])
  if (horizontal) {
    cols <- rev(cols)
  } else {
    rows <- rev(rows)
  }

  # change the order of columns or rows in the viewport raster
  vp <- index_raster(vp, cols, rows)

  # Assign the modified viewport back
  set_viewport_area(raster, vp)
}

ggplot() +
  with_custom(
    geom_text(aes(0.5, 0.75, label = 'Flippediflop!'), size = 10),
    filter = flip_raster,
    horizontal = TRUE
  )

Blend a layer with a reference

Description

This filter blends the layer with a reference according to one of many rules as laid out in the Details section.

Usage

with_blend(
  x,
  bg_layer,
  blend_type = "over",
  flip_order = FALSE,
  alpha = NA,
  ...
)

Arguments

Details

Two images can be blended in a variety of ways as described below. In the following source will refer to the top-most image, and destination to the bottom-most image. Note that which is which can be controlled with the flip_order argument.

Duff-Porter alpha blend modes

This is a set of well-defined blend types for composing two images, taking their opacity into account:

• "source": Completely disregards the destination, leaving only the source

• "destination": Completely disregards the source, leaving only the destination

• "clear": Disregards both destination and source

• "xor": Composes source on top of destination, setting shared areas to transparent

• "over": Composes source on top of destination

• "in": Shows source, but only where the destination is opaque

• "out": Shows source but only where the destination is transparent

• "atop": Composes source on top of destination, keeping the transparency of destination

• "copy": Like source, but will only affect the area occupied by the source image

Mathmathical blend modes

These blend modes perform often complex channel operations based on the different channel values in the source and destination:

• "multiply": Multiplies the channel values of source and destination together (after scaling them to 0-1) to obtain new channel values

• "screen": As multiply except that the channels are scaled to 1-0 before multiplication, and the result is reversed again before being used

• "bumpmap": Like multiple, except source is converted to greyscale first

• "divide": Divide the channel values in source by the channel values in destination

• "plus": Add the channel values together including the alpha channel

• "minus": Subtracts the destination channels from the source channels

• "modulus_plus": As plus, but overflow will wrap around instead of being capped

• "modulus_minus": As minus but overflow (underflow) will wrap around instead of being capped

• "difference": Takes the absolute difference in channel values between source and destination

• "exclusion": source + destination - 2*source*destination. A sort of averaged difference

• "lighten": Will pick the lightest pixel at each pixel

• "darken": Will pick the darkest pixel at each pixel

• "lighten_intensity": Will pick the most intense colour at each pixel

• "darken_intensity": Will pick the least intense colour at each pixel

Lighting blend modes

These blend modes are designed to provide different lighting effects:

• "overlay": Simultaneously multiplies and screens at the same time based on the colour values of the destination. Will colorize midtones in the destination with the source

• "hard_light": The inverse of overlay (i.e. the source acts as the destination and vice versa)

• "soft_light": Like overlay but will extent the range of colorization past the midtones

• "pegtop_light": Like soft-light, but without any discontinuity in the blend

• "linear_light": Combines dodging and burning so that the destination will be dodged (lightened) when the source is light and burned (darkened) when the source is dark

• "vivid_light": A refinement of linear-light that better avoids shading intense colours

• "pin_light": Preserves midtones of the destination and only shades lighter and darker parts, resulting in harsh, contrasty lightning.

• "linear_dodge": Lighten the destination if the source is light

• "linear_burn": Darked the destination if the source is dark

• "color_dodge": Like linear-dodge, but preserves blacks in the destination image

• "color_burn": Like linear-burn but preserve whites in the destination image

Channel copying blends

These blend modes copies a single channel from the source to the destination

• "copy_opacity": Will set the opacity of destination to the grayscale version of source. To copy the opacity of source into destination use blend_type = "in" with flip_order = TRUE.

• "copy_red": Copies the red channel in source into the red channel in destination

• "copy_green": Copies the green channel in source into the green channel in destination

• "copy_blue": Copies the blue channel in source into the blue channel in destination

• "hue": Replaces the hue of the destination with the hue of the source

• "saturate": Replaces the saturation of the destination with the saturation of the source

• "luminize": Replaces the luminance of the destination with the luminance of the source

• "colorize": Combines hue and saturate

Special blends

• "unique": Only keep pixels in the source that differ from the destination.

The above is obviously a very quick overview. More information can be found in https://legacy.imagemagick.org/Usage/compose/

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

See Also

Other blend filters: with_blend_custom(), with_interpolate(), with_mask()

Examples

library(ggplot2)
ggplot() +
  as_reference(
    geom_text(aes(0.5, 0.5, label = 'Blend Modes!'), size = 10, fontface = 'bold'),
    id = "text"
  ) +
  with_blend(
    geom_polygon(aes(c(0, 1, 1), c(0, 0, 1)), colour = NA, fill = 'magenta'),
    bg_layer = "text",
    blend_type = 'xor'
  )

Create a custom blend type

Description

Many of the blend types available in with_blend() are variations over the formula: a*src*dst + b*src + c*dst + d, where src stands for the channel value in the source image and dst stands for the destination image (the background). Multiply is e.g. defined as ⁠a:1, b:0, c:0, d:0⁠. This filter gives you free reign over setting the coefficient of the blend calculation.

Usage

with_blend_custom(
  x,
  bg_layer,
  a = 0,
  b = 0,
  c = 0,
  d = 0,
  flip_order = FALSE,
  alpha = NA,
  ...
)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

See Also

Other blend filters: with_blend(), with_interpolate(), with_mask()

Examples

library(ggplot2)
ggplot(mpg, aes(class, hwy)) +
  as_reference(geom_boxplot(fill = 'green'), 'box') +
  with_blend_custom(geom_point(colour = 'red'),
                    bg_layer = 'box', a = -0.5, b = 1, c = 1)

Apply bloom to your layer

Description

Bloom is the effect of strong light sources spilling over into neighbouring dark areas. It is used a lot in video games and movies to give the effect of strong light, even though the monitor is not itself capable of showing light at that strength.

Usage

with_bloom(
  x,
  threshold_lower = 80,
  threshold_upper = 100,
  sigma = 5,
  strength = 1,
  keep_alpha = TRUE,
  ...
)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

Examples

library(ggplot2)
points <- data.frame(
  x = runif(1000),
  y = runif(1000),
  col = runif(1000)
)
ggplot(points, aes(x, y, colour = col)) +
  with_bloom(
    geom_point(size = 10),
  ) +
  scale_colour_continuous(type = 'viridis')

Apply a gaussian blur to your layer

Description

This filter adds a blur to the provided ggplot layer. The amount of blur can be controlled and the result can optionally be put underneath the original layer.

Usage

with_blur(x, sigma = 0.5, stack = FALSE, ...)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

See Also

Other blur filters: with_motion_blur(), with_variable_blur()

Examples

library(ggplot2)
ggplot(mtcars, aes(mpg, disp)) +
  with_blur(geom_point(data = mtcars, size = 3), sigma = 3)

Dither image using a threshold dithering map

Description

These filters reduces the number of colours in your layer and uses various threshold maps along with a dithering algorithm to disperse colour error.

Usage

with_circle_dither(
  x,
  map_size = 7,
  levels = NULL,
  black = TRUE,
  colourspace = "sRGB",
  offset = NULL,
  ...
)

with_custom_dither(
  x,
  map = "checks",
  levels = NULL,
  colourspace = "sRGB",
  offset = NULL,
  ...
)

with_halftone_dither(
  x,
  map_size = 8,
  levels = NULL,
  angled = TRUE,
  colourspace = "sRGB",
  offset = NULL,
  ...
)

with_ordered_dither(x, map_size = 8, levels = NULL, colourspace = "sRGB", ...)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

See Also

Other dithering filters: with_dither()

Examples

library(ggplot2)

# Ordered dither
ggplot(faithfuld, aes(waiting, eruptions)) +
  with_ordered_dither(
    geom_raster(aes(fill = density), interpolate = TRUE)
  ) +
  scale_fill_continuous(type = 'viridis')

# Halftone dither
ggplot(faithfuld, aes(waiting, eruptions)) +
  with_halftone_dither(
    geom_raster(aes(fill = density), interpolate = TRUE)
  ) +
  scale_fill_continuous(type = 'viridis')

# Circle dither with offset
ggplot(faithfuld, aes(waiting, eruptions)) +
  with_circle_dither(
    geom_raster(aes(fill = density), interpolate = TRUE),
    offset = 29,
    colourspace = 'cmyk'
  ) +
  scale_fill_continuous(type = 'viridis')

Apply a custom filter

Description

This function allows you to apply a custom filtering function to a layer. The function must take a nativeRaster object as the first argument along with any other arguments passed to .... Be aware that the raster spans the full device size and not just the viewport currently rendered to. This is because graphics may extend outside of the viewport depending on the clipping settings. You can use get_viewport_area() along with all the other raster helpers provided by ggfx to facilitate working with the input raster. See the example below for some inspiration.

Usage

with_custom(x, filter, ...)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

Examples

library(ggplot2)
flip_raster <- function(raster, horizontal = TRUE) {
  # Get the viewport area of the raster
  vp <- get_viewport_area(raster)

  # Get the columns and rows of the raster - reverse order depending on
  # the value of horizontal
  dims <- dim(vp)
  rows <- seq_len(dims[1])
  cols <- seq_len(dims[2])
  if (horizontal) {
    cols <- rev(cols)
  } else {
    rows <- rev(rows)
  }

  # change the order of columns or rows in the viewport raster
  vp <- index_raster(vp, cols, rows)

  # Assign the modified viewport back
  set_viewport_area(raster, vp)
}

ggplot() +
  with_custom(
    geom_text(aes(0.5, 0.75, label = 'Flippediflop!'), size = 10),
    filter = flip_raster,
    horizontal = TRUE
  )

ggplot() +
  with_custom(
    geom_text(aes(0.5, 0.75, label = 'Flippediflop!'), size = 10),
    filter = flip_raster,
    horizontal = FALSE
  )

Apply a displacement map to a layer

Description

This filter displaces the pixels based on the colour values of another layer or raster object. As such it can be used to distort the content of the layer.

Usage

with_displacement(x, x_map, y_map = x_map, x_scale = 1, y_scale = x_scale, ...)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

Examples

library(ggplot2)
ggplot() +
  as_reference(
    geom_polygon(aes(c(0, 1, 1), c(0, 0, 1)), colour = NA, fill = 'magenta' ),
    id = "displace_map"
  ) +
  with_displacement(
    geom_text(aes(0.5, 0.5, label = 'Displacements!'), size = 10),
    x_map = ch_red("displace_map"),
    y_map = ch_blue("displace_map"),
    x_scale = unit(0.025, 'npc'),
    y_scale = unit(0.025, 'npc')
  )

Dither image using Floyd-Steinberg error correction dithering

Description

This filter reduces the number of colours in your layer and uses the Floyd-Steinberg algorithm to even out the error introduced by the colour reduction.

Usage

with_dither(x, max_colours = 256, colourspace = "sRGB", ...)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

See Also

Other dithering filters: with_circle_dither()

Examples

library(ggplot2)
ggplot(faithfuld, aes(waiting, eruptions)) +
  with_dither(
    geom_raster(aes(fill = density), interpolate = TRUE),
    max_colours = 10
  ) +
  scale_fill_continuous(type = 'viridis')

Apply an inner glow to your layer

Description

This filter adds an inner glow to your layer with a specific colour and size. The best effect is often had by drawing the stroke separately so the glow is only applied to the fill.

Usage

with_inner_glow(x, colour = "black", sigma = 3, expand = 0, ...)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

See Also

Other glow filters: with_outer_glow()

Examples

library(ggplot2)

ggplot(mtcars, aes(as.factor(gear), disp)) +
  with_inner_glow(
    geom_boxplot(),
    colour = 'red',
    sigma = 10
  )

# This gives a red tone to the lines as well which may not be desirable
# This can be fixed by drawing fill and stroke separately
ggplot(mtcars, aes(as.factor(gear), disp)) +
  with_inner_glow(
    geom_boxplot(colour = NA),
    colour = 'red',
    sigma = 10
  ) +
  geom_boxplot(fill = NA)

Blend two layerrs together by averaging them out

Description

Two layers can be blended together in the literal sense (not like with_blend()) so that the result is the average of the two. This is the purpose of with_interpolate().

Usage

with_interpolate(x, bg_layer, src_percent, bg_percent = 100 - src_percent, ...)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

See Also

Other blend filters: with_blend_custom(), with_blend(), with_mask()

Examples

library(ggplot2)
ggplot(mpg, aes(class, hwy)) +
  as_reference(geom_boxplot(), 'box') +
  with_interpolate(geom_point(), bg_layer = 'box', src_percent = 70)

Apply a gaussian blur to your layer

Description

This filter allows you to apply a custom kernel to your layer, thus giving you more control than e.g. with_blur() which is also applying a kernel.

Usage

with_kernel(
  x,
  kernel = "Gaussian:0x2",
  iterations = 1,
  scaling = NULL,
  bias = NULL,
  stack = FALSE,
  ...
)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

Examples

library(ggplot2)
# Add directional blur using the comet kernel
ggplot(mtcars, aes(mpg, disp)) +
  with_kernel(geom_point(size = 3), 'Comet:0,10')

Apply a mask to a layer

Description

This filter applies a mask to the given layer, i.e. sets the opacity of the layer based on another layer

Usage

with_mask(x, mask, invert = FALSE, ...)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

See Also

Other blend filters: with_blend_custom(), with_blend(), with_interpolate()

Examples

library(ggplot2)
volcano_raster <- as.raster((volcano - min(volcano))/diff(range(volcano)))
circle <- data.frame(
  x = cos(seq(0, 2*pi, length.out = 360)),
  y = sin(seq(0, 2*pi, length.out = 360))
)

ggplot() +
  as_reference(
    geom_polygon(aes(x = x, y = y), circle),
    id = 'circle'
  ) +
  with_mask(
    annotation_raster(volcano_raster, -1, 1, -1, 1, TRUE),
    mask = ch_alpha('circle')
  )

# use invert = TRUE to flip the mask
ggplot() +
  as_reference(
    geom_polygon(aes(x = x, y = y), circle),
    id = 'circle'
  ) +
  with_mask(
    annotation_raster(volcano_raster, -1, 1, -1, 1, TRUE),
    mask = ch_alpha('circle'),
    invert = TRUE
  )

Apply a motion blur to your layer

Description

This filter adds a directional blur to the provided ggplot layer. The amount of blur, as well as the angle, can be controlled.

Usage

with_motion_blur(x, sigma = 0.5, angle = 0, ...)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

See Also

Other blur filters: with_blur(), with_variable_blur()

Examples

library(ggplot2)
ggplot(mtcars, aes(mpg, disp)) +
  with_motion_blur(
    geom_point(size = 3),
    sigma = 6,
    angle = -45
  )

Apply an outer glow to your layer

Description

This filter adds an outer glow to your layer with a specific colour and size. For very thin objects such as text it may be beneficial to add some expansion. See the examples for this.

Usage

with_outer_glow(x, colour = "black", sigma = 3, expand = 0, ...)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

See Also

Other glow filters: with_inner_glow()

Examples

library(ggplot2)

ggplot(mtcars, aes(as.factor(gear), disp)) +
  with_outer_glow(
    geom_boxplot(),
    colour = 'red',
    sigma = 10
  )

# For thin objects (as the whiskers above) you may need to add a bit of
# expansion to make the glow visible:

ggplot(mtcars, aes(mpg, disp)) +
  geom_point() +
  with_outer_glow(
    geom_text(aes(label = rownames(mtcars))),
    colour = 'white',
    sigma = 10,
    expand = 10
  )

Convert a layer to a raster

Description

This filter simply converts the given layer, grob, or ggplot to a raster and inserts it back again. It is useful for vector graphics devices such as svglite if a layer contains a huge amount of primitives that would make the file slow to render. as_reference(x, id) is a shorthand for with_raster(x, id = id, include = FALSE) that makes the intent of using this grob or layer as only a filter reference clear.

Usage

with_raster(x, ...)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

Examples

library(ggplot2)
ggplot(mtcars, aes(mpg, disp)) +
  with_raster(geom_point(data = mtcars, size = 3))

Apply a gaussian blur to your layer

Description

This filter adds a blur to the provided ggplot layer. The amount of blur can be controlled and the result can optionally be put underneath the original layer.

Usage

with_shade(
  x,
  height_map,
  azimuth = 30,
  elevation = 30,
  strength = 10,
  sigma = 0,
  blend_type = "overlay",
  ...
)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

Examples

library(ggplot2)
volcano_long <- data.frame(
  x = as.vector(col(volcano)),
  y  = as.vector(row(volcano)),
  z = as.vector(volcano)
)
ggplot(volcano_long, aes(y, x)) +
  as_reference(
    geom_raster(aes(alpha = z), fill = 'black', interpolate = TRUE, show.legend = FALSE),
    id = 'height_map'
  ) +
  with_shade(
    geom_contour_filled(aes(z = z, fill = after_stat(level))),
    height_map = ch_alpha('height_map'),
    azimuth = 150,
    height = 5,
    sigma = 10
  ) +
  coord_fixed() +
  guides(fill = guide_coloursteps(barheight = 10))

Apply a drop shadow to a layer

Description

This filter applies the familiar drop-shadow effect on elements in a layer. It takes the outline of each shape, offsets it from its origin and applies a blur to it.

Usage

with_shadow(
  x,
  colour = "black",
  x_offset = 10,
  y_offset = 10,
  sigma = 1,
  stack = TRUE,
  ...
)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

Examples

library(ggplot2)
ggplot(mtcars, aes(mpg, disp)) +
  with_shadow(geom_point(colour = 'red', size = 3), sigma = 3)

Apply a variable blur to a layer

Description

This filter will blur a layer, but in contrast to with_blur() the amount and nature of the blur need not be constant across the layer. The blurring is based on a weighted ellipsoid, with width and height based on the values in the corresponding x_sigma and y_sigma layers. The angle of the ellipsoid can also be controlled and further varied based on another layer.

Usage

with_variable_blur(
  x,
  x_sigma,
  y_sigma = x_sigma,
  angle = NULL,
  x_scale = 1,
  y_scale = x_scale,
  angle_range = 0,
  ...
)

Arguments

Value

Depending on the input, either a grob, Layer, list of Layers, guide, or element object. Assume the output can be used in the same context as the input.

See Also

Other blur filters: with_blur(), with_motion_blur()

Examples

library(ggplot2)
cos_wave <- function(width, height) {
  x <- matrix(0, ncol = width, nrow = height)
  x <- cos(col(x)/100)
  as.raster((x + 1) / 2)
}
ggplot() +
  as_reference(
    cos_wave,
    id = "wave"
  ) +
  with_variable_blur(
    geom_point(aes(disp, mpg), mtcars, size = 4),
    x_sigma = ch_red("wave"),
    y_sigma = ch_alpha("wave"),
    angle = ch_red("wave"),
    x_scale = 15,
    y_scale = 15,
    angle_range = c(-45, 45)
  )