Package 'sketchpad'

Description

canvas bundles the settings draw() applies to a sketch as a whole, before drawing any of its shapes: a background fill and an optional fixed xlim/ylim frame. It plays the same role for sketch that style() plays for a single drawable – a small, reusable settings object, validated independently and stored as a property (sketch's own canvas) rather than a flat list of arguments.

Usage

canvas(background = fill_none(), xlim = NULL, ylim = NULL, clip = FALSE)

Arguments

Details

xlim/ylim only fix the coordinate scale draw() maps onto the page – they do not, by themselves, clip content that falls outside that range; a shape wider than its sketch's canvas still renders in full, spilling past the frame, exactly as passing xlim/ylim to draw() directly already behaves. This is a deliberate default: shapes built from a noise_field/noise_bridge (e.g. shape_blob(), shape_twist()) can have somewhat unpredictable extents, and silently cropping part of one away is a worse failure mode than a visibly overflowing shape, which is an obvious cue to adjust the sketch's parameters. Set clip = TRUE to opt into hard clipping at xlim/ylim instead – most useful once background is also set to something other than fill_none(), since an opaque background otherwise has visible content bleeding past its own edge onto the bare page. clip has no visible effect when xlim/ylim are both left NULL, since draw() then computes them from the sketch's own shapes, which by construction never exceed that range.

See Also

Other core structure: draw(), drawable(), group(), sketch(), style(), xy()

Examples

canvas()
canvas(background = "grey90")

# a background is drawn beneath every shape in the sketch
draw(sketch(canvas = canvas(background = "grey90")) + shape_blob(radius = 1))

# xlim/ylim alone only fix the coordinate scale -- a shape wider than the
# frame still overflows it
overflowing <- sketch(canvas = canvas(
  background = "white", xlim = c(-1, 1), ylim = c(-1, 1)
)) + shape_circle(radius = 1.4)
draw(overflowing)

# clip = TRUE hard-clips content at xlim/ylim instead
overflowing@canvas@clip <- TRUE
draw(overflowing)

Description

Multiplies each colour's own alpha channel (1, i.e. fully opaque, for a colour with none already set) by alpha, via grDevices::adjustcolor() – the same mechanism style()'s own color_alpha/fill_alpha properties use internally at draw() time (see ?style). Since an ordinary opaque colour's own alpha is 1, this has the effect of setting the result's alpha to alpha directly for any color with no alpha of its own already.

Usage

color_alpha(color, alpha = 0.5)

Arguments

Value

A character vector of hex colour strings (including an alpha channel), the same length as the longer of color/alpha.

See Also

Other color helpers: color_greyscale(), color_invert(), color_jitter(), color_lighten(), color_mix(), color_rotate_hue(), color_saturate()

Examples

color_alpha("black", alpha = 0.5)
color_alpha(palette_manual(index = 1), alpha = c(1, 0.75, 0.5, 0.25, 0.1))

Description

A thin wrapper around color_desaturate() with amount = 1 – every colour's HSL saturation is dropped to 0, leaving only its own lightness. This is a plain HSL desaturation, not a perceptual (luminance-weighted) greyscale conversion – two colours with very different perceived brightness but the same HSL lightness (e.g. a saturated yellow and a saturated blue) convert to the same grey.

Usage

color_greyscale(color)

Arguments

Value

A character vector of hex colour strings, the same length as color.

See Also

Other color helpers: color_alpha(), color_invert(), color_jitter(), color_lighten(), color_mix(), color_rotate_hue(), color_saturate()

Examples

color_greyscale(palette_manual(index = 1))
draw(effect_swatch(color = color_greyscale(palette_manual(index = 1))))

Description

Inverts each colour's RGB channels (1 - channel), the classic "photo negative" transform. Unlike color_rotate_hue(degrees = 180), which keeps HSL saturation/lightness fixed and only flips hue, RGB inversion also flips lightness (e.g. white inverts to black, not to another light colour).

Usage

color_invert(color)

Arguments

Value

A character vector of hex colour strings, the same length as color.

See Also

Other color helpers: color_alpha(), color_greyscale(), color_jitter(), color_lighten(), color_mix(), color_rotate_hue(), color_saturate()

Examples

color_invert("white")
color_invert(palette_manual(index = 1))
draw(effect_swatch(color = color_invert(palette_manual(index = 1))))

Description

Nudges each colour's HSL hue/saturation/lightness by independent Gaussian noise – hue by amount * 360 degrees (wrapped, ⁠%% 360⁠), saturation/lightness by amount (reflected back into ⁠[0, 1]⁠ at the boundary via the same triangle-wave technique palette_walk() uses for its own random steps) – giving each colour an independent, organic variation rather than palette_walk()'s own correlated sequence of colours.

Usage

color_jitter(color, amount = 0.05, seed = 1L)

Arguments

Value

A character vector of hex colour strings, the same length as color.

See Also

Other color helpers: color_alpha(), color_greyscale(), color_invert(), color_lighten(), color_mix(), color_rotate_hue(), color_saturate()

Examples

color_jitter(palette_manual(index = 1), amount = 0.05, seed = 8241)
draw(effect_swatch(color = color_jitter(rep("steelblue", 8), amount = 0.1, seed = 8241)))

Description

Shifts each colour's HSL lightness by amount, clamped to ⁠[0, 1]⁠. color_lighten() and color_darken() shift in opposite directions by the same amount – there is no single signed-amount function, since separate verbs read more clearly at a call site.

Usage

color_lighten(color, amount = 0.1)

color_darken(color, amount = 0.1)

Arguments

Value

A character vector of hex colour strings, the same length as the longer of color/amount.

See Also

Other color helpers: color_alpha(), color_greyscale(), color_invert(), color_jitter(), color_mix(), color_rotate_hue(), color_saturate()

Examples

color_lighten("steelblue", amount = 0.2)
color_darken(palette_manual(index = 1), amount = 0.15)
draw(effect_swatch(color = color_lighten("steelblue", amount = seq(0, 0.4, 0.1))))

Description

Mixes color1 and color2 channel-by-channel in linear RGB space, amount of the way from color1 to color2 (amount = 0 returns color1 unchanged, amount = 1 returns color2). Unlike palette_gradient() (which interpolates through a sequence of colours to produce a longer palette), color_mix() blends two same-length (or recyclable) vectors pointwise – useful for tinting an existing palette toward a shared accent colour. As with palette_gradient()'s own space argument, space = "Lab" blends perceptually more evenly than "rgb", particularly for color1/ color2 pairs far apart in hue (a plain RGB blend of two saturated, near-complementary colours often passes through a dull, muddy midpoint that a Lab blend avoids) – but unlike "rgb", which always stays in gamut by construction, a "Lab" blend's midpoint can occasionally land just outside the representable sRGB gamut; this is clipped back into ⁠[0, 1]⁠ per channel rather than erroring.

Usage

color_mix(color1, color2, amount = 0.5, space = c("rgb", "Lab"))

Arguments

Value

A character vector of hex colour strings, the same length as the longest of color1/color2/amount.

See Also

Other color helpers: color_alpha(), color_greyscale(), color_invert(), color_jitter(), color_lighten(), color_rotate_hue(), color_saturate()

Examples

color_mix("steelblue", "tomato", amount = 0.5)
color_mix(palette_manual(index = 1), "white", amount = 0.3)
color_mix("tomato", "seagreen", amount = 0.5, space = "Lab")
draw(effect_swatch(color = color_mix("steelblue", "tomato", amount = seq(0, 1, 0.2))))

Description

Adds degrees to each colour's HSL hue, wrapping around the colour wheel (⁠%% 360⁠). Generalizes the fixed hue offsets palette_harmony() uses internally into a plain, arbitrary-angle operation on an existing colour vector.

Usage

color_rotate_hue(color, degrees = 30)

Arguments

Value

A character vector of hex colour strings, the same length as the longer of color/degrees.

See Also

Other color helpers: color_alpha(), color_greyscale(), color_invert(), color_jitter(), color_lighten(), color_mix(), color_saturate()

Examples

color_rotate_hue("tomato", degrees = 180)
color_rotate_hue(palette_manual(index = 1), degrees = c(0, 30, 60, 90, 120))
draw(effect_swatch(color = color_rotate_hue("tomato", degrees = seq(0, 300, 60))))

Description

Shifts each colour's HSL saturation by amount, clamped to ⁠[0, 1]⁠. color_saturate() and color_desaturate() shift in opposite directions by the same amount, mirroring color_lighten()/ color_darken()'s own paired-verb shape.

Usage

color_saturate(color, amount = 0.1)

color_desaturate(color, amount = 0.1)

Arguments

Value

A character vector of hex colour strings, the same length as the longer of color/amount.

See Also

Other color helpers: color_alpha(), color_greyscale(), color_invert(), color_jitter(), color_lighten(), color_mix(), color_rotate_hue()

Examples

color_saturate("slategray", amount = 0.3)
color_desaturate(palette_manual(index = 1), amount = 0.5)
draw(effect_swatch(color = color_desaturate(palette_manual(index = 1), amount = 0.5)))

Description

curve_arc is shape_wedge()'s arc alone, with no centroid vertex: an open path of n points on the circle centred at ⁠(x, y)⁠ with the given radius, sweeping from angle start to end (radians).

curve_arcs() is a vectorized version of curve_arc(): each argument may be a vector, recycled against the others. The result is a sketch containing one curve_arc() per recycled row, rather than a single drawable.

Usage

curve_arc(
  x = 0,
  y = 0,
  radius = 1,
  start = 0,
  end = pi/2,
  n = 100L,
  trans = trans_identity(),
  ...
)

curve_arcs(
  x = 0,
  y = 0,
  radius = 1,
  start = 0,
  end = pi/2,
  n = 100L,
  trans = trans_identity(),
  ...
)

Arguments

Details

Shares its point computation and argument validation with shape_wedge() via two internal helpers factored into R/shape_wedge.R (arc_points(), validate_arc_args()), differing only in which drawable(geometry = ...) they construct from and the missing centroid vertex.

style@fill has no effect for curve_arc() – see drawable's geometry documentation for why "path" geometries have no interior to fill. Passing fill via ... is still accepted (it's simply ignored at draw time), since style() is shared across every geometry.

Recycling uses purrr::pmap()'s own vctrs-based rules: any length-1 element is broadcast to the common length; mismatched lengths greater than 1 raise an error.

Value

A drawable.

For curve_arcs(), a sketch.

See Also

Other 1D curves: curve_bezier(), curve_line(), curve_raw(), curve_scribble(), curve_spiral(), curve_twist()

Examples

draw(curve_arc(start = 0, end = 3 * pi / 2))

# unlike shape_wedge(), there's no centroid vertex or fill -- just the
# arc itself
draw(curve_arc(start = pi / 4, end = pi, linewidth = 4, lineend = "round"))

# a start greater than end sweeps clockwise instead of counterclockwise
draw(curve_arc(start = pi, end = 0))

draw(curve_arcs(start = 0, end = seq(pi / 2, 2 * pi, length.out = 3)))

# concentric arcs of growing radius, all sweeping the same angle range
draw(curve_arcs(radius = seq(0.2, 1, length.out = 5), start = 0, end = pi))

Description

curve_bezier is a drawable whose path follows a Bezier curve defined by an arbitrary number of control points (x, y), using the same Bernstein-polynomial machinery as shape_bezier(). Where shape_bezier() always closes back to its first control point (a consequence of every "polygon"-geometry drawable being rendered as a closed grid::polygonGrob()), curve_bezier() sets geometry = "path" and is rendered as an open grid::polylineGrob() instead, stopping at its last control point rather than looping back.

curve_beziers() is a vectorized version of curve_bezier(). Since x/y are themselves numeric vectors of control points for a single curve, curve_beziers() takes them as a list() of numeric vectors instead – one vector of control points per curve.

Usage

curve_bezier(x, y, n = 100L, trans = trans_identity(), ...)

curve_beziers(x, y, n = 100L, trans = trans_identity(), ...)

Arguments

Details

style@fill has no effect for curve_bezier() – see drawable's geometry documentation for why "path" geometries have no interior to fill. Passing fill via ... is still accepted (it's simply ignored at draw time), since style() is shared across every geometry.

Every other argument may be a plain vector, recycled against x/y via purrr::pmap()'s own vctrs-based rules (any length-1 element is broadcast to the common length; mismatched lengths greater than 1 raise an error). The result is a sketch containing one curve_bezier() per list element/recycled row, rather than a single drawable.

Value

A drawable.

For curve_beziers(), a sketch.

See Also

Other 1D curves: curve_arc(), curve_line(), curve_raw(), curve_scribble(), curve_spiral(), curve_twist()

Examples

draw(curve_bezier(x = c(0, 0.5, 1), y = c(0, 1, 0)))

# unlike shape_bezier(), the curve stops at its last control point
# rather than closing back to the first
draw(curve_bezier(
  x = c(0, 0.25, 0.75, 1), y = c(0, 1, -1, 0), linewidth = 3
))

# a ribbon can be built around any curve_*() path with shape_strokepath()
draw(shape_strokepath(
  curve_bezier(x = c(0, 0.5, 1), y = c(0, 1, 0)),
  width = 0.15
))

draw(curve_beziers(
  x = list(c(0, 0.5, 1), c(2, 2.5, 3)),
  y = list(c(0, 1, 0), c(0, 1, 0))
))

Description

curve_line is a drawable whose path connects an arbitrary number of control points ⁠(x, y)⁠ with straight segments, in order. With two control points this is a single line segment; with more, an open polyline.

curve_lines() is a vectorized version of curve_line(). Since x/y are themselves numeric vectors of control points for a single polyline, curve_lines() takes them as a list() of numeric vectors instead – one vector of control points per polyline.

Usage

curve_line(x, y, trans = trans_identity(), ...)

curve_lines(x, y, trans = trans_identity(), ...)

Arguments

Details

Unlike curve_bezier()/shape_bezier(), the control points are not smoothed or resampled – points is exactly ⁠(x, y)⁠, so there is no n argument.

style@fill has no effect for curve_line() – see drawable's geometry documentation for why "path" geometries have no interior to fill. Passing fill via ... is still accepted (it's simply ignored at draw time), since style() is shared across every geometry.

Every other argument may be a plain vector, recycled against x/y via purrr::pmap()'s own vctrs-based rules (any length-1 element is broadcast to the common length; mismatched lengths greater than 1 raise an error). The result is a sketch containing one curve_line() per list element/recycled row, rather than a single drawable.

Value

A drawable.

For curve_lines(), a sketch.

See Also

Other 1D curves: curve_arc(), curve_bezier(), curve_raw(), curve_scribble(), curve_spiral(), curve_twist()

Examples

draw(curve_line(x = c(0, 1, 1, 2), y = c(0, 1, 0, 1)))

# a thick, square-capped line reads very differently from a thin,
# round-capped one
draw(curve_line(
  x = c(0, 1, 2), y = c(0, 1, 0), linewidth = 12, lineend = "square"
))

# layer several jittered copies for a hand-drawn look
draw(effect_tremor(
  curve_line(x = c(0, 1, 1, 2), y = c(0, 1, 0, 1)),
  layers = 5L
))

draw(curve_lines(
  x = list(c(0, 1, 1, 2), c(2, 3, 3, 4)),
  y = list(c(0, 1, 0, 1), c(0, 1, 0, 1))
))

# a simple hatched grid of crossing lines
draw(curve_lines(
  x = list(c(0, 5), c(0, 5), c(0, 5)),
  y = list(c(0, 5), c(1, 4), c(2, 3))
))

Description

curve_raw is shape_raw's "path"-geometry analog: the user supplies x/y coordinates directly, connected by straight segments in the order given, with no smoothing, resampling, or implicit closing edge. Unlike curve_line() (which requires at least two control points, since a single-point "line" isn't meaningful), curve_raw places no minimum on length(x), matching shape_raw's own leniency – it exists primarily as a convert() target for "freezing" any "path"-geometry drawable's computed points, the same role shape_raw plays for "polygon"-geometry drawables.

curve_raws() is a vectorized version of curve_raw(). Since x/y are themselves numeric vectors of vertex coordinates for a single path, curve_raws() takes them as a list() of numeric vectors instead – one vector of vertices per path.

Usage

curve_raw(x, y, id = NULL, trans = trans_identity(), ...)

curve_raws(x, y, id = NULL, trans = trans_identity(), ...)

Arguments

Details

style@fill has no effect for curve_raw() – see drawable's geometry documentation for why "path" geometries have no interior to fill. Passing fill via ... is still accepted (it's simply ignored at draw time), since style() is shared across every geometry.

id optionally groups x/y into multiple sub-paths (see xy's own id), letting a single curve_raw() render as several disjoint strokes sharing one style.

Every other argument may be a plain vector, recycled against x/y via purrr::pmap()'s own vctrs-based rules (any length-1 element is broadcast to the common length; mismatched lengths greater than 1 raise an error). The result is a sketch containing one curve_raw() per list element/recycled row, rather than a single drawable.

Value

A drawable.

For curve_raws(), a sketch.

See Also

Other 1D curves: curve_arc(), curve_bezier(), curve_line(), curve_scribble(), curve_spiral(), curve_twist()

Examples

draw(curve_raw(x = c(0, 1, 2), y = c(0, 1, 0)))

# useful for "freezing" a wandering path's own computed points
frozen <- S7::convert(
  curve_twist(
    x = 0, y = 0, xend = 1, yend = 0,
    path_distortion = noise_bridge(seed = 99)
  ),
  curve_raw
)
draw(frozen)

# id groups x/y into several disjoint strokes sharing one style
draw(curve_raw(
  x = c(0, 1, 2, 3), y = c(0, 1, 0, 1),
  id = c(1, 1, 2, 2)
))

draw(curve_raws(
  x = list(c(0, 1, 2), c(2, 3, 4)),
  y = list(c(0, 1, 0), c(0, 1, 0))
))

Description

curve_scribble is a drawable whose path is a single random wandering line – a random finite sum of sine harmonics – built from the same internal scribble_lines() generator that fill_scribble() uses to texture a tile's interior, but scaled here into an arbitrary bounding box on the sketch's own coordinate plane rather than tiled inside a fill pattern. Where fill_scribble() scatters several such lines across a repeating tile as a texture, curve_scribble() draws exactly one as a standalone open curve.

curve_scribbles() is a vectorized version of curve_scribble(): each argument may be a vector, recycled against the others via purrr::pmap()'s own vctrs-based rules (any length-1 element is broadcast to the common length; mismatched lengths greater than 1 raise an error).

Usage

curve_scribble(
  x = 0,
  y = 0,
  width = 1,
  height = 1,
  direction = "horizontal",
  n_harmonics = 3L,
  amplitude = 0.35,
  n = 200L,
  seed = 1L,
  trans = trans_identity(),
  ...
)

curve_scribbles(
  x = 0,
  y = 0,
  width = 1,
  height = 1,
  direction = "horizontal",
  n_harmonics = 3L,
  amplitude = 0.35,
  n = 200L,
  seed = 1L,
  trans = trans_identity(),
  ...
)

Arguments

Details

The underlying line is generated in ⁠(along, across)⁠ form, along running from 0 to 1 and across wandering around a random baseline near 0.5 (see scribble_lines()'s own details for why this particular construction was chosen – periodicity, needed for tiling, is irrelevant here). x/y place the curve's origin, and width/ height scale it: for direction = "horizontal" (the default), along maps to x + along * width and across to y + across * height, so the curve runs left-to-right; for direction = "vertical", the mapping swaps (along maps to y, across to x), so the curve runs bottom-to-top instead.

style@fill has no effect for curve_scribble() – see drawable's geometry documentation for why "path" geometries have no interior to fill. Passing fill via ... is still accepted (it's simply ignored at draw time), since style() is shared across every geometry.

Varying seed per curve is usually what makes several scribbles look distinct from each other. The result is a sketch containing one curve_scribble() per recycled row, rather than a single drawable.

Value

A drawable.

For curve_scribbles(), a sketch.

See Also

Other 1D curves: curve_arc(), curve_bezier(), curve_line(), curve_raw(), curve_spiral(), curve_twist()

Examples

draw(curve_scribble(width = 2, height = 0.5, seed = 5591))

# more harmonics and higher amplitude give a more agitated wiggle
draw(curve_scribble(
  width = 2, height = 0.5, n_harmonics = 8, amplitude = 0.6, seed = 5591
))

# direction = "vertical" runs the curve bottom-to-top instead
draw(curve_scribble(
  width = 0.5, height = 2, direction = "vertical", seed = 5591
))

draw(curve_scribbles(x = 1:3, width = 0.8, height = 0.5, seed = 1:3))

# stacked scribbles, like several strands of hatching
draw(curve_scribbles(y = 1:6, width = 3, height = 0.6, seed = 1:6))

Description

curve_spiral is a drawable whose path winds around a centroid ⁠(x, y)⁠, sweeping through turns full revolutions while its radius interpolates linearly from radius_start to radius_end. With radius_start = radius_end this traces a circle repeated turns times (visually indistinguishable from a single circle, since the path retraces itself); the usual case has radius_start != radius_end, giving an Archimedean-style spiral that grows or shrinks outward.

curve_spirals() is a vectorized version of curve_spiral(): each argument may be a vector, recycled against the others via purrr::pmap()'s own vctrs-based rules (any length-1 element is broadcast to the common length; mismatched lengths greater than 1 raise an error). The result is a sketch containing one curve_spiral() per recycled row, rather than a single drawable.

Usage

curve_spiral(
  x = 0,
  y = 0,
  radius_start = 0,
  radius_end = 1,
  turns = 3,
  n = 200L,
  trans = trans_identity(),
  ...
)

curve_spirals(
  x = 0,
  y = 0,
  radius_start = 0,
  radius_end = 1,
  turns = 3,
  n = 200L,
  trans = trans_identity(),
  ...
)

Arguments

Details

style@fill has no effect for curve_spiral() – see drawable's geometry documentation for why "path" geometries have no interior to fill. Passing fill via ... is still accepted (it's simply ignored at draw time), since style() is shared across every geometry.

Value

A drawable.

For curve_spirals(), a sketch.

See Also

Other 1D curves: curve_arc(), curve_bezier(), curve_line(), curve_raw(), curve_scribble(), curve_twist()

Examples

draw(curve_spiral(radius_start = 0, radius_end = 1, turns = 4))

# radius_start > radius_end spirals inward instead of outward
draw(curve_spiral(
  radius_start = 1, radius_end = 0.1, turns = 5, linewidth = 2
))

# equal start/end radii retrace a circle -- rarely useful on its own,
# but shows turns has no effect on shape when radius doesn't change
draw(curve_spiral(radius_start = 1, radius_end = 1, turns = 3))

draw(curve_spirals(x = c(0, 3, 6), turns = c(2, 3, 4)))

# nested spirals sharing a centroid, growing radius each time
draw(curve_spirals(
  radius_start = seq(0.1, 0.5, length.out = 4),
  radius_end = seq(0.6, 1, length.out = 4)
))

Description

curve_twist is shape_twist()'s path alone, with no ribbon width: an open curve_line()-like polyline between ⁠(x, y)⁠ and ⁠(xend, yend)⁠, displaced away from a straight line by a noise_bridge, giving a wandering, twisted appearance.

curve_twists() is a vectorized version of curve_twist(): each argument may be a vector, recycled against the others via purrr::pmap()'s own vctrs-based rules. The result is a sketch containing one curve_twist() per recycled row, rather than a single drawable.

Usage

curve_twist(
  x = 0,
  y = 0,
  xend = 1,
  yend = 1,
  scale = 0.2,
  n = 100L,
  path_distortion = noise_bridge(),
  trans = trans_identity(),
  ...
)

curve_twists(
  x = 0,
  y = 0,
  xend = 1,
  yend = 1,
  scale = 0.2,
  n = 100L,
  path_distortion = noise_bridge(),
  trans = trans_identity(),
  ...
)

Arguments

Details

Where shape_twist() also modulates a filled ribbon's width along this same kind of path (via a separate distortion noise_field), curve_twist() has no width or fill at all – just the displaced backbone itself, rendered as an open grid::polylineGrob() (geometry = "path"). Shares its path computation with shape_twist() via the internal twisted_path_points() helper (R/shape_twist.R) rather than duplicating it.

style@fill has no effect for curve_twist() – see drawable's geometry documentation for why "path" geometries have no interior to fill. Passing fill via ... is still accepted (it's simply ignored at draw time), since style() is shared across every geometry.

Any length-1 element is broadcast to the common length; mismatched lengths greater than 1 raise an error. A shared path_distortion noise_bridge is automatically recycled across every path; pass a list() of several different noise_bridges instead to vary it per path.

Value

A drawable.

For curve_twists(), a sketch.

See Also

Other 1D curves: curve_arc(), curve_bezier(), curve_line(), curve_raw(), curve_scribble(), curve_spiral()

Examples

draw(curve_twist(
  x = 0, y = 0, xend = 1, yend = 0,
  path_distortion = noise_bridge(seed = 7734)
))

# a larger scale wanders further from the straight line between the
# endpoints
draw(curve_twist(
  x = 0, y = 0, xend = 1, yend = 0, scale = 0.6,
  path_distortion = noise_bridge(seed = 7734)
))

# curve_twist() is shape_twist()'s backbone alone, with no ribbon width
draw(shape_twist(
  x = 0, y = 0, xend = 1, yend = 0,
  path_distortion = noise_bridge(seed = 7734)
))

draw(curve_twists(x = 1:3, y = 0, xend = 2:4, yend = 1))

# a bundle of independently-wandering strands between the same endpoints
draw(curve_twists(
  x = 0, y = 0, xend = 3, yend = 0,
  path_distortion = list(
    noise_bridge(seed = 1),
    noise_bridge(seed = 2),
    noise_bridge(seed = 3)
  )
))

Description

draw() is a generic function that renders a drawable or sketch object to the current graphics device using grid. Methods accept optional xlim/ylim arguments giving axis limits; if omitted, limits are computed from the object's points.

Usage

draw(object, ...)

Arguments

See Also

Other core structure: canvas(), drawable(), group(), sketch(), style(), xy()

Examples

draw(shape_circle(radius = 1))

s <- sketch() + shape_circle(radius = 1) + shape_blob(x = 2, radius = 0.5)
draw(s)

# an explicit xlim/ylim overrides both the sketch's own canvas and the
# range of its shapes' own points, useful for zooming in/out or padding
draw(shape_circle(radius = 1), xlim = c(-2, 2), ylim = c(-2, 2))

# a non-drawable object is ignored, with a warning, rather than erroring
draw("not a drawable")

Description

drawable enforces structure on its subclasses: every drawable must carry a style, a geometry, and expose a computed points property, of class xy. It is not intended to be instantiated directly; use one of its subclasses (shape_raw, shape_circle, shape_blob, shape_ribbon, shape_twist, curve_raw, points_raw, ...) instead.

Usage

drawable(..., geometry = "polygon", trans = trans_identity(), pathlike = FALSE)

Arguments

Details

geometry tells draw() which grid grob a drawable's points map to, following a dimensional reading: "points" (0D, grid::pointsGrob(), e.g. points_raw()), "path" (1D, an open grid::polylineGrob(), e.g. curve_line()/curve_raw()), or "polygon" (2D, a closed grid::polygonGrob() – the default, and the only value any ⁠shape_*()⁠ constructor uses). style@fill is ignored for "points"/"path" geometries, since only a closed polygon has an interior to fill.

trans is a trans (an affine map: trans_translate(), trans_rotate(), trans_scale(), trans_reflect(), trans_shear(), trans_affine()), a trans_warp (a non-rigid, noise-based deformation), a trans_fn (a non-rigid deformation from an arbitrary caller-supplied displacement function), or a trans_chain combining several via +, applied to a drawable's computed points as the very last step – after any shape-specific geometry (and, for shape_blob()/shape_ribbon()/ shape_twist(), any noise-based distortion) has already been computed. This means a drawable's own defining parameters (e.g. shape_circle()'s centroid/radius) are never mutated or flattened by a transform – only the final rendered coordinates are affected. Default trans_identity() (no transform).

pathlike marks whether x/y (where present) hold a genuine, caller-ordered, perturbable control-point path – as opposed to x/y meaning something else entirely (e.g. shape_circle()'s centroid, or one fixed endpoint of shape_ribbon()'s two-point segment). This is the distinction effect_tremor()/effect_bristle() need to decide whether jittering x/y produces a meaningful wobble; it's orthogonal to geometry – a pathlike drawable can have any geometry (a future ⁠points_*()⁠ constructor could reasonably be pathlike despite geometry == "points"). Currently TRUE for shape_raw(), curve_raw(), curve_line(), shape_stroke(), shape_bezier(), curve_bezier(), and points_raw(); FALSE (the default) for every other concrete drawable, including shape_ribbon()/shape_twist()/ curve_twist() – these do have a conceptual backbone, but it's exposed via x/y/xend/yend (or additional named control-point pairs), not a plain x/y vector. Whether a pathlike subclass actually has x/y properties is not enforced by drawable's own validator – every subclass constructor first builds a scaffold drawable() instance (validated on its own, before any subclass property exists) and only merges in x/y afterward via S7::new_object(), so a cross-property check here would fire on that scaffold and reject every pathlike subclass unconditionally (see "Gotchas"). Setting pathlike = TRUE on a subclass with no x/y is therefore an author error caught only when an effect tries to read object@x/object@y, not at construction time.

See Also

Other core structure: canvas(), draw(), group(), sketch(), style(), xy()

Examples

circ <- shape_circle(radius = 1)
S7::S7_inherits(circ, drawable)

# geometry controls which grob draw() builds: a closed outline, an open
# stroke, or unconnected markers
draw(shape_circle(radius = 1, n = 8))
draw(curve_line(x = c(0, 1, 2, 3), y = c(0, 1, 0, 1), linewidth = 3))
draw(points_raw(x = runif(30), y = runif(30)))

# trans applies after a shape's own geometry/distortion is computed, so
# shape_rectangle()'s centroid/width/height stay fixed -- only the final
# rendered corners rotate
draw(shape_rectangle(
  width = 1.5,
  height = 0.5,
  trans = trans_rotate(pi / 6)
))

Description

effect_bristle() builds a group of n_bristles copies of a template drawable, fanned out perpendicular to its own backbone path.

Usage

effect_bristle(
  object,
  n_bristles = 9L,
  spread = 0.3,
  width_jitter = 0.3,
  fray = 0.15,
  jitter = 0.015,
  jitter_frequency = 1.2,
  n = 100L,
  seed = 1L
)

Arguments

Details

Like effect_tremor(), no single drawable can express this by itself, since a dry-brush look comes from several independently-frayed, independently wobbling strands laid side by side, not one stroke. Each bristle is a copy of object (via S7::set_props()) that:

• is offset from the backbone by a fixed perpendicular distance (via the same per-point unit normal shape_stroke() itself uses, stroke_normals()), evenly spaced across spread;

• is trimmed to a random sub-range of the backbone's own length (fray controls how much), so bristles start/end raggedly rather than in one clean line – the same "frayed edge" a real brush's outer bristles show as it runs dry;

• has its own randomly-scaled width (via width_jitter, applied to object@width); and

• is independently wobbled via effect_tremor() (layers = 1L, since the fanning here already does the layering work effect_tremor() normally provides – one wobbling copy per bristle position, not several wobbling copies of one path).

Every other property of object – style, distortion, trans, ... – carries over to every bristle unchanged, since each is built with S7::set_props() rather than a fresh constructor call. shape_stroke()'s own taper-to-zero at both ends does double duty as each bristle's tip fade, needing no extra work here. Randomization (fray range, width scaling) is scoped per bristle with withr::with_seed(), the same reproducibility convention fill_stipple()/fill_scatter()/fill_halftone() already use, so it never leaks into the caller's global random state.

Value

A group containing n_bristles drawables.

See Also

Other effects: effect_grain(), effect_swatch(), effect_tremor()

Examples

t <- seq(0, 8, length.out = 200)
template <- shape_stroke(
  x = t, y = sin(t) * 1.2, width = 0.06,
  fill = "black", fill_alpha = 0.4, color = NA_character_
)

# before: a single plain stroke
draw(template)

# after: fanned into a dry-brush bristle effect
draw(effect_bristle(template, n_bristles = 11L, spread = 0.3))

# a wider spread and more fraying gives a rougher, more ragged brush
draw(effect_bristle(template, n_bristles = 15L, spread = 0.5, fray = 0.3))

Description

effect_grain takes an existing polygon-geometry drawable (object, e.g. shape_stroke(), shape_blob(), shape_ribbon()) and renders its own outline (object@points) not with a style()⁠@fill⁠ via the ordinary draw()/geometry_grob() path, but by compositing a rasterised paper-grain texture and masking it to the outline's exact polygon shape via grid::as.mask().

Usage

effect_grain(
  object,
  grain = noise_field(frequency = 15, octaves = 2L, seed = 2L),
  resolution = 150L,
  color = "gray15",
  alpha = 1,
  background = NA_character_
)

Arguments

Details

This is the same masking technique fill_vignette() already uses for its own radial fade, but applied to object's own real (possibly concave, tapering-to-a-point) silhouette rather than a synthetic circle drawn purely to build the mask.

This is a different effect than filling object with fill_charcoal()/fill_noise() (already a good option for a shape's interior – see fill_charcoal()'s docs): those tile a periodic texture that repeats across the shape via grid::pattern(), sized relative to the target's own bounding box. effect_grain() instead samples its grain noise_field once, directly, across object's own world coordinates – a single non-repeating raster the size of the whole shape, with no tiling seam to manage, at the cost of needing its own draw() method rather than reusing geometry_grob()'s existing "polygon"/"path"/"points" branches (effect_grain is not a drawable subclass at all, since its rendering isn't expressible as a single points-based grob).

Grain is rendered as varying opacity of color, from fully transparent at the noise field's minimum to alpha at its maximum – exactly fill_noise()'s own opacity convention – optionally revealing a solid background colour underneath (as fill_vignette()'s own background argument does) rather than true transparency, which reads as a solid, mottled ink stroke instead of a sparse one.

Value

An effect_grain object.

See Also

Other effects: effect_bristle(), effect_swatch(), effect_tremor()

Examples

t <- seq(0, 8, length.out = 150)
template <- shape_stroke(x = t, y = sin(t), width = 0.4)

# before: a plain filled stroke
draw(template)

# after: the same outline rendered as textured grain instead of a
# solid style() fill
draw(effect_grain(template, color = "gray10", alpha = 0.9))

# a non-NA background reveals a solid colour underneath the grain,
# instead of true transparency
draw(effect_grain(
  template,
  color = "gray5",
  alpha = 0.85,
  background = "gray30"
))

# a coarser grain field (lower frequency) reads less like paper texture
# and more like a mottled brushstroke
draw(effect_grain(template, grain = noise_field(frequency = 3, seed = 2)))

Description

effect_swatch() builds a group of length(color) copies of a template drawable, laid out left to right and each independently filled from color – a colour-preview effect for any ⁠palette_*()⁠ function's own output (or any other character vector of colours).

Usage

effect_swatch(object = shape_rectangle(color = NA_character_), color, gap = 0)

Arguments

Details

Every property of object besides style@fill – its own size, style@color/linewidth, trans, ... – carries over unchanged to every copy, via the same S7::set_props() contract effect_tremor()/ effect_bristle() already use. Unlike those two, object need not be pathlike (see drawable's own pathlike docs) – a shape_rectangle()'s own x/y is a centroid, not a perturbable control-point path – so each copy is instead repositioned by composing a trans_translate() onto object's own trans, the one mechanism every drawable class supports uniformly regardless of what its own x/y means. This also means object can be any drawable, not just a rectangle – swatch a palette across circles, blobs, or stars by passing a different template.

Swatches render with hard edges rather than blending into one another, since that's a more honest representation of a palette whose colours are meant to be used as-is (e.g. palette_manual()/palette_harmony()) – a smooth interpolation between swatches would show shades that aren't actually part of the palette.

Value

A group of length(color) copies of object.

See Also

Other effects: effect_bristle(), effect_grain(), effect_tremor()

Examples

draw(effect_swatch(color = palette_manual(index = 3)))
draw(effect_swatch(color = palette_harmony("steelblue", scheme = "triadic"), gap = 0.1))

# any drawable can serve as the template, not just a rectangle
draw(effect_swatch(shape_circle(radius = 0.5), palette_tonal("darkorchid", n = 6)))

Description

effect_tremor() builds a group of layers such copies: each is a copy of object (via S7::set_props()) with its x/y displaced by smooth, seed-offset simplex noise sampled along the path's own normalized arc-length.

Usage

effect_tremor(
  object,
  layers = 4L,
  jitter = 0.05,
  jitter_frequency = 0.5,
  seed = 1L
)

Arguments

Details

No single drawable can express a hand-drawn ink/pencil look on its own – what reads as hand-drawn is several independently wobbling copies of the same nominal path layered on top of each other, not one perfectly smooth line. This is the same ad hoc technique used, during development, to add a wobbling pencil edge on top of a shape_stroke()'s tapered outline, or to layer a plain curve_line() into a shakier-looking line by itself.

Noise is sampled at each control point's own position along arc-length (0 to 1), not at its raw x/y coordinates, so the jitter's shape is independent of the path's own scale or aspect ratio – a long, shallow path and a short, steep one with the same number of control points get comparably-shaped wobble. Each layer's noise is seed-offset from the last (seed + 2 * (i - 1) for the x displacement, one more for y, following the same seed-offset convention trans_warp()/twisted_path_points() already use for their own independent-axis noise), so layers wobble independently rather than moving in lockstep.

Because each layer is built with S7::set_props() from object itself, every other property – style, width/distortion for a shape_stroke(), trans, ... – carries over unchanged; effect_tremor() only varies x/y across layers. Vary color_alpha down and/or layers up (on object and via the layers argument, respectively) for a denser, more overlapping pencil/ink texture.

Value

A group containing layers drawables.

See Also

Other effects: effect_bristle(), effect_grain(), effect_swatch()

Examples

template <- curve_line(x = c(0, 1, 2, 3), y = c(0, 1, 0, 1))
faded <- curve_line(x = c(0, 1, 2, 3), y = c(0, 1, 0, 1), color_alpha = 0.4)

# before: a single crisp line
draw(template)

# after: several jittered, faded copies read as hand-drawn
draw(effect_tremor(faded))

draw(effect_tremor(
  shape_stroke(
    x = c(0, 1, 2, 3), y = c(0, 1, 0, 1),
    width = 0.3, fill_alpha = 0.5, color = NA_character_
  ),
  layers = 3L, jitter = 0.03
))

# more layers and higher jitter give a denser, shakier scribble
draw(effect_tremor(faded, layers = 10L, jitter = 0.15))

Description

fill is the common representation stored in style()'s fill property and canvas()'s background property: a value (a plain colour string, or the GridPattern output of a ⁠fill_*()⁠ pattern/ gradient helper) plus an optional resolve function. resolve, when present, is called with the real target's own bounding-box aspect ratio at draw() time to rebuild value with the correct tile shape – see the internal resolvable_fill()/resolve_fill() helpers (R/fill.R), and fill_hatch()'s own aspect argument docs for the problem this solves. resolve is NULL whenever a helper's aspect was supplied explicitly (a fixed aspect, never automatically recomputed) or for a fill with no aspect-dependence at all (fill_solid(), fill_none()).

Usage

fill(value = "black", resolve = NULL)

Arguments

Details

Not usually constructed directly – every ⁠fill_*()⁠ helper already returns one, and style()/canvas() coerce a bare colour string or GridPattern into one automatically (via the internal as_fill() helper) if passed directly.

See Also

Other fill helpers: 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_stipple(), fill_stripe(), fill_vignette()

Description

fill_charcoal() is a fill_noise() preset – same field, same rendering, just different defaults – tuned to read as hand-drawn charcoal or marker grain rather than fill_noise()'s more general-purpose rasterized field: a lighter base tone, finer/denser tiling, and finer noise detail.

Usage

fill_charcoal(
  color = "gray15",
  spacing = 0.25,
  aspect = NULL,
  resolution = 32L,
  alpha = 1,
  frequency = 4,
  octaves = 3L,
  seed = 1L,
  extend = "repeat"
)

Arguments

Details

Found, while prototyping shape_stroke()'s interior texture, to be a substantially better fit than fill_scribble() for a curved stroke's body – fill_scribble()'s angle is a single fixed value for the whole tile (and only tiles exactly seamlessly at a multiple of 90 degrees; see its "Known limitation" docs section), so it can't track a curved path's own continuously-varying tangent, producing hatching that visibly cuts across the stroke at odd angles wherever the path bends, while fill_noise()'s directionless mottling has no orientation to clash with the curve.

Value

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

See Also

Other fill helpers: fill(), 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_stipple(), fill_stripe(), fill_vignette()

Examples

draw(shape_stroke(
  x = c(0, 1, 2, 3), y = c(0, 1, 0, 1), width = 0.4,
  fill = fill_charcoal(), color = NA_character_
))

# a lighter tone and a curved backbone -- fill_charcoal()'s directionless
# mottling tracks a bend that fill_scribble()'s fixed direction wouldn't
t <- seq(0, 2 * pi, length.out = 200)
draw(shape_stroke(
  x = t, y = sin(t), width = 0.3,
  fill = fill_charcoal(color = "gray40"), color = NA_character_
))

Description

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

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.

Value

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

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)
))

Description

fill_crosshatch() builds a grid::pattern() fill value that renders two mirror-symmetric hatch lines, at angle and -angle, forming an "X" inside each tile.

Usage

fill_crosshatch(
  color = "black",
  angle = 45,
  spacing = 0.1,
  aspect = NULL,
  linewidth = 1,
  extend = "repeat"
)

Arguments

Details

It shares fill_hatch()'s tile-shape technique: both lines are drawn as the two corner-to-corner diagonals of a single rectangular tile (rather than at an arbitrary baked-in slope), so both tile seamlessly under extend = "repeat", and the tile's width/height ratio – not the diagonals' own coordinates – determines the rendered angle. See fill_hatch()'s details for why this matters.

Because both lines share one tile shape, they are only perpendicular when angle = 45 (the classic crosshatch look); for other angles the two lines are symmetric about the horizontal axis but not at right angles to each other. Genuinely perpendicular hatching at an arbitrary angle would need two differently-shaped tiles layered as separate fills, which this function does not attempt.

At angle a multiple of 90 degrees, the two mirrored diagonals would coincide, so this case is handled separately by drawing a horizontal line and a vertical line instead (a simple grid).

Value

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

See Also

Other fill helpers: fill(), fill_charcoal(), fill_checker(), 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_crosshatch(angle = 30)))

# at a multiple of 90 degrees, the mirrored diagonals would coincide,
# so a plain horizontal/vertical grid is drawn instead
draw(shape_circle(fill = fill_crosshatch(angle = 0, spacing = 0.15)))

# only angle = 45 gives genuinely perpendicular lines; other angles are
# symmetric about the horizontal axis but not at right angles
draw(shape_circle(fill = fill_crosshatch(angle = 20, spacing = 0.12)))

# a two-colour vector colours the two lines independently
draw(shape_circle(
  fill = fill_crosshatch(color = c("steelblue", "tomato"), angle = 45)
))

Description

fill_flow() is a swirlier variant of fill_noise(): before sampling the final noise field, the tile's own ⁠(theta_u, theta_v)⁠ angles (see fill_noise() details for why angles, not raw ⁠(u, v)⁠) are displaced by a second, independent torus-periodic noise field – the "fBm of fBm" domain-warping recipe popularized for flowing, curl-noise-like textures, adapted here so the warp field is itself torus-periodic rather than sampled directly, keeping the whole result seamless.

Usage

fill_flow(
  color = "black",
  spacing = 0.5,
  aspect = NULL,
  resolution = 32L,
  alpha = 1,
  warp = 2,
  warp_frequency = 1,
  warp_octaves = 1L,
  frequency = 1,
  octaves = 2L,
  seed = 1L,
  extend = "repeat"
)

Arguments

Details

The warp field needs to be decorrelated from the final field and from itself along each axis, but ambient::gen_simplex()'s 4 input dimensions are already fully spent on the ⁠(theta_u, theta_v)⁠ torus trick, leaving no spare dimension to offset. fill_flow() decorrelates by seed instead: the u- and v-displacement fields are sampled at seed + 104729L and seed + 200003L respectively (arbitrary large primes, chosen only to make collisions with a user's own nearby seed choices unlikely), before the final field is sampled at seed itself.

Displacing a periodic field's own periodic coordinates by another periodic field preserves periodicity: shifting u from 0 to 1 still advances theta_u by exactly 2 * pi (a full turn), and the warp added at each end is identical since it's sampled from a field that's periodic in u itself – so the warped angle wraps around exactly as the unwarped one did, with no seam.

As with fill_noise(), a faint tile-boundary rasterization seam can still be visible on some devices despite the field being exactly periodic (see its details); larger warp values tend to make this more noticeable, for the same reason described at fill_marble().

Value

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

See Also

Other fill helpers: fill(), fill_charcoal(), fill_checker(), fill_crosshatch(), 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_flow(warp = 3, seed = 9350L)))

# a larger warp gives a swirlier, more curl-noise-like look; warp = 0
# reduces to plain fill_noise()
draw(shape_circle(fill = fill_flow(warp = 0, seed = 9350L)))
draw(shape_circle(fill = fill_flow(warp = 6, seed = 9350L)))

# two or more colours blend across the field, as in fill_noise()
draw(shape_circle(
  fill = fill_flow(color = c("steelblue", "white", "tomato"), seed = 9350L)
))

Description

fill_gradient() builds a grid::pattern() fill value whose tile content is a single rectangle filled with a grid::linearGradient() or grid::radialGradient(), depending on type.

Usage

fill_gradient(
  color = c("white", "black"),
  type = c("linear", "radial"),
  angle = 45,
  stops = NULL,
  spacing = 1,
  aspect = NULL,
  extend = "pad"
)

Arguments

Details

Like the other ⁠fill_*()⁠ helpers, this needs the target's bounding-box aspect ratio (aspect, resolved automatically by default – see fill_hatch()'s own aspect docs) to render true rather than stretched – but the correction is applied differently here. Rather than adjusting the gradient's own coordinates (the way fill_hatch() adjusts a segment's direction), fill_gradient() corrects the tile itself to be physically square, exactly as fill_stipple() does for its dots: once the tile is square, a gradient specified inside it in plain "npc" needs no further correction to render at the requested angle, or as a true circle for type = "radial".

This also means a gradient tile has none of fill_hatch()'s periodicity concerns: adjacent tiles are simply identical copies of the same square gradient, with nothing analogous to a hatch line's tile-edge dashing to avoid.

With the default spacing = 1, one tile spans (and, for a non-square bounding box, slightly overshoots) the target's entire bounding box, giving a single smooth gradient across the whole shape – the overshoot is invisibly clipped away by the target's own outline. Set spacing < 1 for a repeating pattern of small gradient motifs instead.

Value

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

See Also

Other fill helpers: fill(), fill_charcoal(), fill_checker(), fill_crosshatch(), fill_flow(), 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_gradient(c("white", "steelblue"))))
draw(shape_circle(fill = fill_gradient(c("yellow", "red"), type = "radial")))

# three or more colours interpolate in sequence; angle rotates a linear
# gradient's direction
draw(shape_circle(
  fill = fill_gradient(c("yellow", "orange", "red"), angle = 90)
))

# spacing < 1 repeats the gradient as a small tiled motif instead of one
# smooth sweep across the whole shape
draw(shape_circle(
  fill = fill_gradient(c("white", "steelblue"), spacing = 0.3)
))

Description

fill_halftone() is fill_stipple()'s other variant: instead of scattering dots of one fixed size, each dot's radius is drawn uniformly at random from radius, giving a mottled halftone-print look rather than a uniform stipple.

Usage

fill_halftone(
  color = "black",
  radius = c(0.05, 0.2),
  spacing = 0.3,
  aspect = NULL,
  n = 4L,
  seed = 1L,
  extend = "repeat"
)

Arguments

Details

Like fill_stipple() (and unlike fill_scatter()), it scatters plain grid::circleGrob()s, so it's immune to the polygon-specific rendering problems documented at fill_scatter() – but it shares fill_stipple()'s own, separate "Known rendering risk with multiple dots" (repeated tiles containing several circleGrobs were, in testing, sometimes visibly distorted on this package's development R build; see that section for details). There is no known way to avoid this while still getting a genuine scattered-dot texture, so check rendered output visually here too.

As with fill_stipple(), aspect corrects for the target's own bounding-box aspect ratio automatically by default, keeping the dots circular rather than elliptical (see fill_hatch()'s own aspect docs). Dot centres are kept at least max(radius) from each tile edge, so even the largest possible dot isn't clipped away near a boundary.

Value

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

See Also

Other fill helpers: fill(), fill_charcoal(), fill_checker(), fill_crosshatch(), fill_flow(), fill_gradient(), 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_halftone(radius = c(0.05, 0.15), seed = 3187L)
))

# a wider radius range gives more size contrast between dots
draw(shape_circle(
  fill = fill_halftone(radius = c(0.02, 0.22), n = 6L, seed = 3187L)
))

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

Description

fill_hatch() builds a grid::pattern() fill value that renders a repeating diagonal hatch line. It's meant to be used as the fill argument to grid::gpar() (and eventually style()'s fill property), in place of a plain colour.

Usage

fill_hatch(
  color = "black",
  angle = 45,
  spacing = 0.1,
  aspect = NULL,
  linewidth = 1,
  extend = "repeat"
)

Arguments

Details

grid::pattern() tiles are sized as a fraction of the target polygon's own bounding box, not a fixed physical square, so a tile that looks square in that relative sense can be a stretched rectangle in absolute terms whenever the target's bounding box isn't square itself – which distorts any angle baked directly into the pattern content. This is corrected automatically: aspect defaults to NULL, resolved against the real target's own bounding-box aspect ratio (width / height) at draw() time (see the fill class); pass a fixed number instead to compute the pattern once, immediately, against that value only.

Internally, the hatch line is always drawn as a plain diagonal from one tile corner to the opposite corner (or the mirror image, for a negative-sloped angle) – never at an arbitrary slope baked into the segment's own coordinates. A corner-to-corner diagonal is the only slope that tiles seamlessly under grid::pattern()'s extend = "repeat", which translates tile copies by whole tile-widths/heights only; any other local slope leaves a visible mismatch ("dashing") at every tile edge. The desired angle is instead achieved entirely by choosing the tile's width/height ratio. Exactly horizontal/vertical angles are handled as a special case, since a straight (non-diagonal) line tiles seamlessly at any tile aspect ratio.

Value

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

See Also

Other fill helpers: fill(), fill_charcoal(), fill_checker(), fill_crosshatch(), fill_flow(), fill_gradient(), fill_halftone(), 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_hatch(angle = 30, spacing = 0.15)))

# a steeper angle and finer spacing
draw(shape_circle(fill = fill_hatch(angle = 75, spacing = 0.06)))

# exactly horizontal/vertical are handled as a special case (no
# diagonal-tile trick needed)
draw(shape_circle(fill = fill_hatch(angle = 0, spacing = 0.1)))

# aspect corrects the rendered angle for a non-square bounding box --
# without it, a 45 degree hatch looks skewed on a wide rectangle
draw(shape_rectangle(width = 3, height = 1, fill = fill_hatch(angle = 45)))
draw(shape_rectangle(
  width = 3,
  height = 1,
  fill = fill_hatch(angle = 45, aspect = 3)
))

Description

fill_image() builds a grid::pattern() fill value whose tile content is an arbitrary bitmap, rather than a texture generated by this package. It plugs any raster the caller already has in memory into the same grid::pattern() machinery fill_noise() uses for its own generated raster – but with the raster supplied, not computed.

Usage

fill_image(
  image,
  preserve_aspect = TRUE,
  spacing = 1,
  aspect = NULL,
  interpolate = TRUE,
  extend = "repeat"
)

Arguments

Details

fill_image() doesn't read image files itself, to avoid adding an image I/O dependency (png/jpeg/magick, ...) to a package that otherwise has none. Load the file first with whichever of those packages is already on hand, then pass the result (or grDevices::as.raster() of it) as image – e.g. fill_image(png::readPNG("logo.png")) or fill_image(magick::image_read("logo.png")). Anything grDevices::as.raster() accepts works: a "raster" object, a character matrix of colour strings, or a numeric array of 0-1 RGB/RGBA intensities.

Unlike the other ⁠fill_*()⁠ helpers, fill_image()'s content has its own pixel aspect ratio to account for, on top of the usual target-bounding-box correction every helper needs (aspect, defaulting to automatic resolution exactly as every other helper – see fill_hatch()'s own aspect docs – and corrected for exactly as fill_noise() does – keeping the tile physically square). With preserve_aspect = TRUE (the default), the image is letterboxed to fit that square tile without distorting it: whichever of width/height is smaller in the image's own pixel dimensions is shrunk to fit, leaving the tile's remaining margin transparent. Set preserve_aspect = FALSE to stretch the image to fill the tile exactly instead, matching fill_noise()'s own (always-stretched) behaviour.

Value

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

See Also

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

Examples

img <- matrix(c("red", "white", "white", "blue"), nrow = 2)
draw(shape_circle(fill = fill_image(img, preserve_aspect = FALSE)))

# a non-square image, letterboxed (default) vs. stretched to fill the tile
wide_img <- matrix(c("red", "white", "blue"), nrow = 1)
draw(shape_rectangle(width = 2, height = 1, fill = fill_image(wide_img)))
draw(shape_rectangle(
  width = 2,
  height = 1,
  fill = fill_image(wide_img, preserve_aspect = FALSE)
))

Description

fill_marble() builds a grid::pattern() fill value resembling veined marble: a set of stripes parallel bands running around the tile's u axis, displaced by a fill_noise()-style torus-periodic turbulence field (via the shared internal torus_grid()/torus_noise() helpers) rather than left straight – the classic "sine of a coordinate plus turbulence" recipe for procedural marble.

Usage

fill_marble(
  color = c("white", "black"),
  spacing = 0.5,
  aspect = NULL,
  resolution = 32L,
  stripes = 3L,
  warp = 4,
  frequency = 1,
  octaves = 3L,
  seed = 1L,
  extend = "repeat"
)

Arguments

Details

Periodicity needs two things, both already true here: the undisplaced bands (sin(theta_u * stripes)) are periodic in u for any integer stripes, since theta_u itself advances by exactly 2 * pi over one tile width; and the turbulence added on top is periodic in both u and v because it comes from torus_noise(), the same torus-sampling technique fill_noise() uses for its own field. Adding one periodic function to another (here, inside a further sin()) stays periodic, so the combined result still tiles with no seam.

Unlike fill_noise() (opacity of one colour), the banding is rendered as a blend across color via grDevices::colorRamp(), since a marble texture's visual interest is the veining pattern itself rather than a fade to transparency.

fill_noise()'s own faint tile-boundary rasterization seam (see its details) can be more noticeable here: sin() turns a small mismatch in the turbulence field into a visibly sharper edge in a band than the same mismatch would produce in a plain opacity fade.

Value

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

See Also

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

Examples

draw(shape_circle(fill = fill_marble(stripes = 4L, seed = 1274L)))

# more stripes and stronger warp give busier, more tangled veining
draw(shape_circle(fill = fill_marble(stripes = 8L, warp = 8, seed = 1274L)))

# a different colour pair changes the veining's contrast entirely
draw(shape_circle(
  fill = fill_marble(
    color = c("black", "goldenrod"),
    stripes = 4L,
    seed = 1274L
  )
))

# three or more colours blend across the band in sequence
draw(shape_circle(
  fill = fill_marble(
    color = c("black", "goldenrod", "white"),
    stripes = 4L,
    seed = 1274L
  )
))

Description

fill_noise() builds a grid::pattern() fill value from a rasterised simplex/fractal noise field, using the same noise machinery as shape_blob()'s wobbly outline (ambient::fracture() / ambient::gen_simplex() / ambient::fbm(), with matching frequency, octaves, and seed arguments), so a noise-filled shape and a noise-wobbled outline share one visual vocabulary.

Usage

fill_noise(
  color = "black",
  spacing = 0.5,
  aspect = NULL,
  resolution = 32L,
  alpha = 1,
  frequency = 1,
  octaves = 2L,
  seed = 1L,
  extend = "repeat"
)

Arguments

Details

Noise is rendered as varying opacity of a single color, from fully transparent at the noise field's minimum to alpha at its maximum – a mottled, cloud-like texture rather than a hard-edged one.

A raster tile has no baked-in direction the way a hatch line does, so fill_hatch()'s tile-edge "dashing" problem doesn't apply directly, but an ordinary noise field still isn't periodic, and grid::pattern()'s extend = "repeat" will visibly seam wherever one tile edge fails to match the next. fill_noise() avoids this by sampling the noise on a torus: each raster pixel's ⁠(u, v)⁠ tile coordinate is mapped onto a pair of circles (ambient::gen_simplex()'s 4 dimensions, x/y for u and z/t for v) rather than sampled directly, so the field is mathematically periodic in both directions and tiles with no visible seam, at the cost of the noise "wrapping around" within each tile rather than varying smoothly across a larger area.

In practice, a very faint seam can still be visible at tile boundaries on some devices, even though the underlying field is exactly periodic; this appears to be an artifact of how the graphics device samples a repeated raster tile (it persists regardless of interpolate and doesn't improve with higher resolution), not a flaw in the noise field itself, and is far subtler than the tile-edge mismatch fill_hatch() has to actively avoid.

Value

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

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_none(), fill_scatter(), fill_scribble(), fill_solid(), fill_stipple(), fill_stripe(), fill_vignette()

Examples

draw(shape_circle(fill = fill_noise(seed = 8843L)))

# higher frequency/octaves give finer-grained texture
draw(shape_circle(
  fill = fill_noise(frequency = 4, octaves = 4L, seed = 8843L)
))

# a lower alpha lets the shape's own outline/background show through more
draw(shape_circle(
  fill = fill_noise(color = "steelblue", alpha = 0.5, seed = 8843L)
))

# two or more colours blend across the field instead of fading to transparent
draw(shape_circle(
  fill = fill_noise(color = c("steelblue", "white", "tomato"), seed = 8843L)
))

Description

fill_none() leaves a drawable's interior entirely unfilled, while still stroking its outline (per style()'s color/linewidth). It's a thin, self-documenting wrapper around fill_solid(NA_character_): NA is already a valid colour to grid::gpar() (rendered as fully transparent), but spelling that out as fill_none() reads more clearly at a call site than a bare NA_character_, and groups discoverably with the rest of the ⁠fill_*()⁠ family.

Usage

fill_none()

Details

Since every drawable is currently rendered as a closed grid::polygonGrob() (see the "Deferred: open/stroked curve support" item in .agents/PLAN.md), fill_none() gives an unfilled closed outline – the edge connecting the last point back to the first is still drawn. It does not, by itself, produce an open/unstroked curve.

Value

A fill object wrapping NA_character_.

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_scatter(), fill_scribble(), fill_solid(), fill_stipple(), fill_stripe(), fill_vignette()

Examples

draw(shape_circle(fill = fill_none(), linewidth = 2))

# still a closed outline: the edge from the last point back to the
# first is drawn even though the interior isn't filled
draw(shape_polygon(
  n = 5L,
  fill = fill_none(),
  color = "steelblue",
  linewidth = 3
))

Description

fill_scatter() generalizes fill_stipple(): instead of a fixed dot, it scatters copies of an arbitrary small drawable – rendered with its own style (colour, fill, linewidth), which may itself be another ⁠fill_*()⁠ pattern – at random positions inside each tile, using withr::with_seed() for reproducibility exactly as fill_stipple() does.

Usage

fill_scatter(
  unit = shape_circle(radius = 1),
  n = 6L,
  size = 0.2,
  color = NULL,
  spacing = 1,
  aspect = NULL,
  seed = 1L,
  extend = "repeat"
)

Arguments

Details

unit's own points are rescaled (preserving its own aspect ratio) to a bounding box of size size and re-centred at each scattered position; its absolute coordinates, position, and radius/width/etc. don't matter, only its shape.

This needed two corrections neither fill_stipple()'s circles nor fill_gradient()'s/fill_checker()'s rectangles did:

• Every other ⁠fill_*()⁠ helper's tile-squaring correction (height = spacing * aspect, keeping the tile physically square) was, by itself, enough to keep circular/rectangular content correctly proportioned. Arbitrary polygon content does not get the same treatment: empirically, a grid::polygonGrob() (or grid::pathGrob()) used as pattern content renders as though it inherits the target's own, uncorrected bounding-box distortion directly, regardless of the tile-squaring correction applied around it – confirmed by testing a hand-built circular polygon side by side with an equivalent grid::circleGrob() in the same corrected tile: the circle stayed circular, the polygon became an ellipse. So fill_scatter() applies a second, explicit correction directly to unit's own vertex x-coordinates (dividing by aspect) on top of the usual tile-squaring.

• Repeated (tiled) polygon content can render with visible clipping artifacts on Cairo devices – confirmed interactively: a single stamp, comfortably inside its tile's margins, rendered as a clean shape when the tile spans the whole target (spacing = 1, so extend = "repeat" is present but never actually exercised within the visible, clipped area) but as a "bitten" partial shape once spacing < 1 made the device actually tile multiple copies. This matches grid::pattern()'s own documented warning that "on Cairo devices, use of clipping in the pattern definition should be avoided because it is very likely to result in distortion of the pattern tile." Circles/rectangles/rasters didn't show this in the rest of the family, but arbitrary polygon geometry did. spacing therefore defaults to 1 here (one tile spans the whole shape, scattering all n copies across it at once) rather than the smaller, densely-tiled defaults used elsewhere; setting spacing < 1 is still possible for a repeating scattered motif, but may show this distortion. (Later testing on fill_stipple() found the same actually-repeated tile with multiple shapes combination distorts circleGrob content too, not just polygons – see its "Known rendering risk" section. A single tile with multiple shapes, as used by this function's default, was never observed to have the problem; only real repetition, spacing < 1, was.)

Value

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

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_scribble(), fill_solid(), fill_stipple(), fill_stripe(), fill_vignette()

Examples

draw(shape_circle(
  fill = fill_scatter(unit = shape_circle(radius = 1), n = 8L, size = 0.15)
))

# any small drawable works as the scattered unit, e.g. a triangle
draw(shape_circle(
  fill = fill_scatter(
    unit = shape_polygon(n = 3, fill = "steelblue"),
    n = 10L,
    size = 0.2
  )
))

# a color vector overrides unit's own style colour, recycled per stamp
draw(shape_circle(
  fill = fill_scatter(
    color = c("steelblue", "tomato", "goldenrod"),
    n = 9L,
    size = 0.15
  )
))

Description

fill_scribble() builds a grid::pattern() fill value from several randomly wandering lines, each a random finite sum of sine harmonics (see the internal scribble_lines() helper) rather than a smooth noise field or a scattered discrete motif – giving a loose, hand-drawn scribble texture built from genuinely continuous strokes.

Usage

fill_scribble(
  color = "black",
  angle = 0,
  n_lines = 5L,
  n_harmonics = 3L,
  amplitude = 0.35,
  resolution = 200L,
  linewidth = 1,
  spacing = 0.25,
  aspect = NULL,
  seed = 1L,
  extend = "repeat"
)

Arguments

Details

A wandering open line poses a tiling problem none of the other ⁠fill_*()⁠ helpers have: fill_hatch()'s diagonal and fill_noise()'s raster both tile by construction (a straight corner-to-corner line, or an already-periodic field), and fill_stipple()/fill_scatter()/ fill_halftone() sidestep the problem entirely by keeping their scattered content margined well clear of the tile edge. A wandering line that's meant to look continuous can't stay clear of the edge – it has to run all the way to it, and pick up again at exactly the right place, in both position and slope, on the opposite edge, or the seam shows as a visible kink. fill_scribble() gets this for free by building each line as a random sum of sine harmonics at integer frequencies only: over one full period, such a sum always returns exactly to its starting value and slope (to floating-point precision), so consecutive tile copies join with no visible seam – confirmed visually with extend = "repeat" at small spacing, including repeated copies (unlike the polygon-in-a-genuinely-repeated-tile issue documented at fill_scatter(), open-line content showed no clipping or distortion in testing).

Value

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

Known limitation – arbitrary angle is only approximate

Every other angled helper (fill_hatch()/fill_crosshatch()/ fill_stripe()) achieves an arbitrary angle by reshaping the tile itself (via hatch_tile_dims()) around content that's a plain corner-to-corner diagonal. That trick doesn't generalize here: reshaping the tile around a wandering line just anisotropically stretches its wiggle rather than rotating it, since the line's content isn't a bare diagonal the tile shape can reinterpret. A genuinely rotated wandering line would need the tile built as a rotated/sheared parallelogram with edge-matching worked out for a curve rather than a segment – no such technique exists in this package. At angle a multiple of 90 degrees, fill_scribble() instead swaps/reflects the along/across axes directly (no trigonometry involved), so tiling stays exactly seamless – this is what angle = 0/90 (the old direction = "horizontal"/"vertical") already relied on, now extended to 180/270 for free. Any other angle instead rotates the whole tile's content about its own centre, which is only an approximation: the underlying wandering line is periodic along its own local axis, not around an arbitrary rotated one, so a non-right-angle rotation can leave a visible seam where adjacent tile copies meet, and may leave small gaps near the tile corners that no line's wiggle reaches. Revisit if a real sketch needs a genuinely seamless arbitrary angle.

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_solid(), fill_stipple(), fill_stripe(), fill_vignette()

Examples

draw(shape_circle(fill = fill_scribble(n_lines = 4L, seed = 6602L)))

# angle = 90 runs the wandering lines top-to-bottom instead, tiling
# exactly as seamlessly as angle = 0
draw(shape_circle(
  fill = fill_scribble(n_lines = 4L, angle = 90, seed = 6602L)
))

# any other angle rotates the tile content -- an approximation only,
# so a seam can be visible at the tile edges
draw(shape_circle(
  fill = fill_scribble(n_lines = 4L, angle = 30, seed = 6602L)
))

# more harmonics and higher amplitude give a more agitated scribble
draw(shape_circle(
  fill = fill_scribble(
    n_lines = 6L,
    n_harmonics = 6L,
    amplitude = 0.6,
    seed = 6602L
  )
))

# a colour vector is recycled across the wandering lines
draw(shape_circle(
  fill = fill_scribble(
    color = c("steelblue", "tomato"),
    n_lines = 4L,
    seed = 6602L
  )
))

Description

fill_solid() is the trivial member of the ⁠fill_*()⁠ family: a plain colour needs no grid::pattern() machinery, since grid::gpar()'s fill argument already accepts a colour string directly. It exists so that a plain colour can be requested with the same ⁠fill_*()⁠ naming as the pattern-based helpers (grouping them together in autocomplete), and so style()'s fill property has one uniform family of constructors to accept – including for its own default – once it's extended to take ⁠fill_*()⁠ outputs alongside a bare colour string.

Usage

fill_solid(color = "black")

Arguments

Value

A fill object wrapping color.

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_stipple(), fill_stripe(), fill_vignette()

Examples

fill_solid("steelblue")
draw(shape_circle(fill = fill_solid("tomato")))

# equivalent to passing the colour string directly, since style()'s own
# `fill` default is fill_solid("black")
draw(shape_circle(fill = "tomato"))

Description

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

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).

Value

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

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)
))

Description

fill_stripe() builds a grid::pattern() fill value that renders repeating solid bands, at a given angle, generalized from two colours to an arbitrary palette.

Usage

fill_stripe(
  color = c("black", "white"),
  angle = 45,
  spacing = 0.2,
  aspect = NULL,
  extend = "repeat"
)

Arguments

Details

Unlike fill_hatch(), this doesn't use the corner-to-corner-diagonal tile-shape technique at all – because a filled band, unlike a thin hatch line, needs every point along a tile's edge to match its neighbour, not just the points where a thin line happens to cross, a single diagonal split of a tile turns out not to tile seamlessly at an arbitrary angle the way a thin hatch line does. Instead, fill_stripe() sidesteps grid::pattern()'s tile-copy repetition altogether: the stripe angle and period come from a grid::linearGradient() with hard colour stops (no smooth transition) and extend = "repeat", which repeats itself continuously along its own axis – a fundamentally different (and for this purpose, simpler) mechanism than tiling a rasterised copy. grid::pattern() is still used around this gradient, but only once, as a single square (automatically aspect-corrected – see fill_hatch()'s own aspect docs) tile spanning the whole target shape, exactly as fill_gradient() does by default – not to create repetition, which the gradient already provides.

Each of the n = length(color) colours gets an equal-width band by default (1/n of the period); there's no separate argument for unequal bands – repeat a colour in color instead (e.g. c("steelblue", "steelblue", "white") gives a 2:1 ratio between the two colours), which reuses the same recycling mechanism rather than adding a second one.

Value

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

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_stipple(), fill_vignette()

Examples

draw(shape_circle(fill = fill_stripe(angle = 30)))

# repeating a colour biases the band widths, rather than a separate argument
draw(shape_circle(
  fill = fill_stripe(color = c("steelblue", "steelblue", "white"))
))

# narrower spacing gives more, thinner stripes
draw(shape_circle(fill = fill_stripe(angle = 90, spacing = 0.08)))

# three or more colours repeat through the same period
draw(shape_circle(
  fill = fill_stripe(color = c("steelblue", "white", "tomato"), angle = 30)
))