Checkerboard pattern fill

fill_checker() builds a grid::pattern() fill value that renders a checkerboard, generalized from two colours to an arbitrary palette.

Usage

fill_checker(
  color = c("black", "white"),
  spacing = 0.2,
  aspect = NULL,
  extend = "repeat"
)

Arguments

color

Two or more checker colours. Default c("black", "white").

spacing

Baseline tile size, as a fraction of the target's bounding box. Must be a positive number. Default 0.2.

aspect

Width-to-height ratio of the target polygon's bounding box. Must be a positive number, or NULL (the default) to resolve it automatically from the real target's own bounding-box aspect ratio at draw() time – see the fill class. Passing a fixed number instead computes the pattern once, immediately, against that value only.

extend

Passed to grid::pattern(). Default "repeat".

Value

A pattern object as returned by grid::pattern(), suitable for use as the fill argument to grid::gpar().

Details

It's the cheapest member of the hatch family to build: a checkerboard square has no direction the way a hatch line does (compare fill_hatch()'s corner-to-corner diagonal, needed specifically to tile a sloped line seamlessly), so the tile content here is just a grid of plain quadrant rectangles – the same two-colour-grid special case fill_crosshatch() already falls back to when angle is a multiple of 90 degrees, pulled out into its own helper.

The tile is subdivided into an n x n grid, where n = length(color). The colour at grid cell (row, col) (0-indexed) is color[((row + col) %% n) + 1] – for the default two colours this reproduces the classic 2x2 checkerboard exactly; a longer color vector grows the grid rather than adding a separate density argument, since a checkerboard's cell size and colour count aren't independent concepts here.

Known rendering risk with three or more colours

The default two-colour, four-rectangle tile has always rendered correctly, but color vectors of length 3 or more (a 3x3 or larger grid of rectangles) were found, at the default spacing, to trigger the same upstream grid/Cairo issue documented at fill_stipple()'s "Known rendering risk" section – several shapes inside a genuinely repeated grid::pattern() tile can render distorted (here, collapsing to a single solid colour instead of a grid), even though the same tile content renders correctly as a single, non-repeated tile (spacing = 1). Visually check rendered output before relying on more than two colors for anything beyond casual use.

As with the other fill_*() helpers, grid::pattern() tiles are sized as a fraction of the target polygon's own bounding box rather than a fixed physical square, so the checker squares would render as rectangles, not squares, on a non-square bounding box – the same tile-squaring technique fill_stipple() uses for its dots. aspect resolves this automatically by default (see fill_hatch()'s own aspect docs).

See also

Other fill helpers: fill(), fill_charcoal(), fill_crosshatch(), fill_flow(), fill_gradient(), fill_halftone(), fill_hatch(), fill_image(), fill_marble(), fill_noise(), fill_none(), fill_scatter(), fill_scribble(), fill_solid(), fill_stipple(), fill_stripe(), fill_vignette()

Examples

draw(shape_circle(fill = fill_checker(color = c("black", "white"))))


# a coarser, differently-coloured checkerboard
draw(shape_circle(
  fill = fill_checker(color = c("steelblue", "white"), spacing = 0.4)
))


# three or more colours grow the grid rather than alternating just two;
# spacing = 1 avoids the tile-repetition rendering risk noted above
draw(shape_circle(
  fill = fill_checker(color = c("steelblue", "white", "tomato"), spacing = 1)
))