Build a variable-width stroke as a closed polygon ribbon

Offsets a centreline left and right by a per-vertex half-width and closes the loop into a single polygon, so a hand-drawn stroke can taper, swell with pressure, or vary like a broad calligraphic nib – effects grid cannot do with a constant-lwd polyline. The centreline is used as supplied (roughen it first with roughen_polyline() for a sketchy edge); this routine only offsets, so it is deterministic apart from jitter_w.

Usage

stroke_ribbon(
  x,
  y,
  width,
  taper = c("none", "both", "start", "end"),
  taper_frac = 0,
  pressure = NULL,
  nib_angle = NULL,
  nib_floor = 0.15,
  jitter_w = 0,
  cap = c("round", "butt"),
  miter_limit = 3,
  seed = NULL
)

Arguments

x, y

Numeric vectors of centreline vertices in inch space (same length).

width

Full stroke width in inches: a scalar, or a per-vertex vector.

taper

Where the stroke narrows to a tip: "none" (default), "both", "start", or "end".

taper_frac

Tip width as a fraction of width (0 = sharp point, 1 = no narrowing). Default 0.

pressure

Optional vectorised function f(t) over normalised arc-length t in [0, 1] returning a width multiplier (see stroke_profile()). NULL (default) is constant pressure.

nib_angle

Optional broad-nib angle in degrees for a calligraphic stroke: the half-width is scaled by |sin(segment_dir - nib_angle)| (with a small floor), so the line is thick across the nib and thin along it. NULL (default) disables it.

nib_floor

Minimum nib multiplier in [0, 1], so a calligraphic stroke never fully vanishes. Default 0.15.

jitter_w

Width roughening in [0, 1]: random per-vertex modulation of the half-width, for a dry / inky edge. Default 0.

cap

End-cap style: "round" (default) or "butt".

miter_limit

Clamp on the joint miter factor, capping how far an outside corner extends at a sharp turn. Default 3.

seed

Integer seed for jitter_w (ADR-0004).

Value

A 2-column (x, y) matrix giving the closed ribbon polygon (right side forward, end cap, left side back, start cap). Fill it with the stroke colour and no border for a solid variable-width stroke.

See also

Other sketch-core: arrowhead(), curve_fill(), engrave_fill(), engrave_ladder(), hachure_fill(), hachure_fill_multi(), leader_path(), repel_layout(), rough_arc(), rough_bezier(), rough_ellipse(), roughen_polyline(), sketch_arrowheads(), sketch_fill(), sketch_fill_multi(), spray_scatter(), stroke_profile(), treemap_layout(), wash_bleed(), watercolor_wash(), watercolor_wash_multi()