GeomSketchEngrave: Sketchy engraving: tonal shading by hatch-line density

Description

geom_sketch_engrave() shades a surface the way an etcher or banknote engraver does: continuous tone is built from the density of hand-drawn hatch lines, with cross-hatching deepening the shadows. It takes a regular grid of x, y, and z (like ggplot2::geom_raster()); z is mapped to tone (high = dark by default). Unlike the fill-pattern packages, the tone is computed from geometry (a engrave_fill() ladder), not tiled from a motif.

Usage

GeomSketchEngrave
GeomSketchShade
geom_sketch_engrave(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  levels = 5L,
  base_gap = 0.08,
  gap_ratio = 0.62,
  base_angle = 45,
  cross_after = 3L,
  reverse = FALSE,
  roughness = 0.5,
  bowing = 0.3,
  min_gap_in = 0.012,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)
geom_sketch_shade(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  levels = 5L,
  base_gap = 0.08,
  gap_ratio = 0.62,
  base_angle = 45,
  cross_after = 3L,
  roughness = 0.5,
  bowing = 0.3,
  min_gap_in = 0.012,
  seed = NULL,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Value

A ggplot2 layer object.

Arguments

mapping: Aesthetic mappings created by ggplot2::aes(). geom_sketch_engrave() needs x, y, z; geom_sketch_shade() needs x, y and uses the tone aesthetic (default 0.6).
data: Data to display.
stat: Statistical transformation. Default "identity".
position: Position adjustment. Default "identity".
...: Other arguments passed on to the layer.
levels: Number of hatch layers in the ladder. Default 5.
base_gap: Pitch of the sparsest layer (npc-x fraction). Default 0.08.
gap_ratio: Multiplicative pitch shrink per layer (smaller = densens faster). Default 0.62.
base_angle: Angle of the first hatch layer (degrees). Default 45.
cross_after: Layer index at which cross-hatching begins. Default 3.
reverse: (geom_sketch_engrave() only) Invert the tone mapping so low z is dark. Default FALSE.
roughness: Non-negative stroke roughness. Default 0.5.
bowing: Non-negative bowing multiplier. Default 0.3.
min_gap_in: Pitch floor in inches; finer ladder layers are dropped. Default 0.012.
seed: Integer seed. NULL uses getOption("ggsketch.seed", 1L).
na.rm: Remove missing values silently? Default FALSE.
show.legend: Logical; include in legend?
inherit.aes: Override default aesthetics?

Details

geom_sketch_shade() shades each polygon region with a uniform density set by a tone aesthetic in [0, 1], so a mapped value reads directly as darkness -- a hand-drawn alternative to a solid fill scale.

The hatch ladder is a stack of layers of increasing density and rotating angle (levels, base_gap, gap_ratio, base_angle, cross_after); each layer is drawn only where the tone reaches its threshold, so light areas keep the sparse base layer and shadows accumulate every layer. min_gap_in is a pitch floor (inches) that keeps the darkest tones from exploding into a runaway number of strokes.

Other sketch-geoms: GeomSketchAbline, GeomSketchArrow, GeomSketchBoxplot, GeomSketchBracket, GeomSketchCallout, GeomSketchChicklet, GeomSketchCol, GeomSketchContourFilled, GeomSketchCurve, GeomSketchDotplot, GeomSketchDumbbell, GeomSketchEdge, GeomSketchEllipse, GeomSketchGantt, GeomSketchHex, GeomSketchLine, GeomSketchLinerange, GeomSketchLollipop, GeomSketchMarkCircle, GeomSketchMarkHull, GeomSketchPath, GeomSketchPoint, GeomSketchPolygon, GeomSketchRect, GeomSketchRibbon, GeomSketchRug, GeomSketchSegment, GeomSketchSfPolygon, GeomSketchSlope, GeomSketchSmooth, GeomSketchSpoke, GeomSketchTextRepel, GeomSketchViolin, StatSketchBeeswarm, StatSketchCalendar, StatSketchDensityRidges, StatSketchFunnel, StatSketchPie, StatSketchPyramid, StatSketchRadar, StatSketchStream, StatSketchTreemap, StatSketchWaffle, StatSketchWaterfall, annotate_sketch(), annotate_sketch_arrow(), annotate_sketch_callout(), annotate_sketch_highlight(), geom_sketch_alluvial(), geom_sketch_arc_diagram(), geom_sketch_bin2d(), geom_sketch_bump(), geom_sketch_chord(), geom_sketch_contour(), geom_sketch_count(), geom_sketch_dendrogram(), geom_sketch_density(), geom_sketch_density2d(), geom_sketch_ecdf(), geom_sketch_function(), geom_sketch_histogram(), geom_sketch_jitter(), geom_sketch_marimekko(), geom_sketch_mosaic(), geom_sketch_parallel(), geom_sketch_qq(), geom_sketch_quantile(), geom_sketch_rose(), geom_sketch_sunburst(), geom_sketch_text(), sketch_graph()

Examples

Run this code

library(ggplot2)
ggplot(faithfuld, aes(waiting, eruptions, z = density)) +
  geom_sketch_engrave(seed = 1L) +
  theme_sketch()

# A real surface: an engraved relief map of Maungawhau (Mt Eden),
# the way a 19th-century atlas shades elevation by hatch density.
volcano_df <- expand.grid(
  easting  = seq_len(nrow(volcano)),
  northing = seq_len(ncol(volcano))
)
volcano_df$height <- as.vector(volcano)

ggplot(volcano_df, aes(easting, northing, z = height)) +
  geom_sketch_engrave(
    levels = 8L, base_gap = 0.04, gap_ratio = 0.72,
    roughness = 0.35, bowing = 0.2, seed = 1L
  ) +
  coord_equal() +
  labs(title = "Maungawhau", subtitle = "engraved by elevation") +
  theme_sketch()