Stippled dot pattern fill

fill_stipple() builds a grid::pattern() fill value that scatters a handful of dots at random positions inside each tile, using withr::with_seed() so the same seed always reproduces the same scatter (the same convention used by shape_blob(), shape_ribbon(), and shape_twist()'s noise fields).

Usage

fill_stipple(
  color = "black",
  radius = 0.15,
  spacing = 0.3,
  aspect = NULL,
  n = 4L,
  seed = 1L,
  extend = "repeat"
)

Arguments

color

One or more dot colours. A vector shorter than n is recycled (in order, not randomly) across the scattered dots – a single colour (the default) colours every dot the same, matching the original behaviour. Default "black".

radius

Dot radius, as a "npc" fraction of the tile. Must be a positive number. Default 0.15.

spacing

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

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.

n

Number of dots scattered per tile. Must be a positive integer. Default 4L.

seed

Integer seed for the dot positions. Default 1L.

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

Unlike fill_hatch()/fill_crosshatch(), a dot has no direction, so there's no analogue of their tile-edge "dashing" problem here. There's still a circularity problem to correct for, though: grid::pattern() tiles are sized as a fraction of the target polygon's own bounding box, so a dot drawn with an npc-relative radius renders as an ellipse whenever that bounding box isn't square. aspect corrects for this automatically by default, keeping dots circular (see fill_hatch()'s own aspect docs).

Known rendering risk with multiple dots

On this package's development R build (4.6.1, a very recent/development version), grid::pattern() tiles whose content is a group of several grid::circleGrob()s (i.e. n > 1) were found, in some cases, to render individual dots visibly distorted – clipped into crescents or otherwise not circular – even though each dot's own coordinates are correct and a single dot (n = 1) always renders correctly. This reproduced in a fresh R session (so it isn't specific to a long interactive session), across multiple n and radius values, with no clean rule found for exactly when it triggers; it appeared on both an interactive device and ragg::agg_png(). No fix or reliable workaround was found – this looks like an upstream grid/Cairo issue with multi-shape pattern tile content, not something specific to how this function builds its content. Visually check rendered output before relying on fill_stipple() (or fill_scatter()/ fill_halftone(), which share this risk) for anything beyond casual use, especially on unfamiliar R/grid/graphics-device versions.

See also

Other fill helpers: fill(), fill_charcoal(), fill_checker(), 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_stripe(), fill_vignette()

Examples

draw(shape_circle(fill = fill_stipple(n = 6L, seed = 2091L)))


# more, smaller dots per tile give a denser stipple
draw(shape_circle(
  fill = fill_stipple(n = 15L, radius = 0.06, spacing = 0.5, seed = 2091L)
))


# a colour vector is recycled across the dots
draw(shape_circle(
  fill = fill_stipple(color = c("steelblue", "tomato"), n = 8L, seed = 2091L)
))