Package 'vellum'

Description

Wrap a grob (or list of grobs) as a mask for vl_viewport(mask = ...). The mask content is rendered to an isolated layer; its coverage then modulates the visibility of the viewport's contents.

Usage

as_mask(grob, type = c("alpha", "luminance"))

Arguments

Value

A vellum_mask object.

Examples

as_mask(circle_grob(r = 0.4, gp = vl_gpar(fill = "white", col = NA)))

Description

as_scene_spec() turns a rendered-ready scene into a plain nested list of R vectors, and from_scene_spec() rebuilds the scene from it. Together they make a compiled scene a value you can store or send, rather than something that only exists inside the session that built it.

Usage

as_scene_spec(scene)

from_scene_spec(spec)

Arguments

Details

This is one level below vellumplot's plot spec. A plot spec is portable and re-renderable at any size; a scene spec is the resolved artifact — the grobs, units and viewports as they will actually be drawn. They compose: keep the plot spec to re-render, keep the scene spec to reproduce exactly this scene.

The conversion is generic over the S7 property model rather than written per grob type, so a grob added to vellum later serializes with no change here.

Value

as_scene_spec(): a nested list, with a version element. from_scene_spec(): a vellum_scene.

See Also

scene_write(), scene_diff(), scene_hash()

Examples

s <- vl_scene(3, 2) |>
  draw(circle_grob(r = 0.3, gp = vl_gpar(fill = "tomato", col = NA)))
spec <- as_scene_spec(s)
spec$version
identical(as_scene_spec(from_scene_spec(spec)), spec)

Description

as_vellum() converts a grid grob tree — or a ggplot2 plot — into a vl_scene() by letting an offscreen grid device resolve all coordinates to absolute units, then emitting vellum grobs. render_grid() does that and writes the result. This is the interop path (grid-based graphics rendered by vellum's deterministic backend); a native graphics device is future work.

Usage

as_vellum(x, width = 7, height = 7, dpi = 96, bg = "white")

render_grid(
  x,
  path,
  width = 7,
  height = 7,
  dpi = 96,
  bg = "white",
  text = c("native", "outline")
)

Arguments

Value

as_vellum(): a vellum_scene. render_grid(): path, invisibly.

Examples

## Not run: 
library(ggplot2)
p <- ggplot(mtcars, aes(wt, mpg)) + geom_point()
render_grid(p, "plot.png", width = 6, height = 4)

## End(Not run)

Description

The extensible seam a higher-level package (e.g. a grammar layer) implements to compile its own plot object into a vl_scene(). render() coerces its input through this generic, so render(x, path) works for any x that has an as_vellum_scene() method. An identity method for vellum_scene is provided.

Usage

as_vellum_scene(x, ...)

Arguments

Details

This is the stable compiler-backend entry point: downstream packages should target as_vellum_scene() (and the exported grob/viewport/unit constructors) rather than vellum's internal compile() / .scene_to_backend() helpers.

Value

A vellum_scene.

Examples

sc <- vl_scene()
identical(as_vellum_scene(sc), sc) # the identity method returns its input

Description

For data beyond the point where drawing one marker each is practical (overplotted, millions of points), the fast and overplotting-honest approach is not to draw markers faster but to not draw markers at all: bin the points into a canvas-sized grid in one pass, then colour each cell by its density. This is what makes datashader fast — aggregation decouples cost from both point count and overplotting. datashade() returns a single raster_grob() you draw like any other grob.

Usage

datashade(
  x,
  y,
  weight = NULL,
  width = 600L,
  height = 400L,
  xlim = NULL,
  ylim = NULL,
  category = NULL,
  colors = c("#deebf7", "#08306b"),
  how = c("eq_hist", "log", "cbrt", "linear"),
  span = NULL,
  clip = NULL,
  spread = NULL,
  interpolate = FALSE,
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL
)

Arguments

Details

The points are binned over xlim x ylim into a width x height grid, so to line the image up with data axes draw it inside a vl_viewport() whose xscale / yscale match xlim / ylim (it fills the viewport, npc ⁠0..1⁠). For crisp bins make width/height match the viewport's pixel size and keep interpolate = FALSE.

Value

A grob (a raster), drawable with draw().

Categorical shading (count_cat)

Pass category (a factor or vector, one value per point) to shade by category rather than plain density: each category is aggregated into its own count grid in the same single pass, and each cell is coloured by the count-weighted average of the category hues it contains, with opacity driven by the cell's total density (via how). This reveals which category dominates where and where categories mix, without overplotting bias. When category is set, colors is a per-category hue vector (named by level, or one colour per level in level order) instead of a low-to-high ramp.

See Also

datashade_lines() and datashade_segments() for the line/segment (dense-timeseries, network-edge) counterparts, and dynspread()/spread().

Examples

set.seed(1)
n <- 1e6
x <- rnorm(n); y <- x * 0.5 + rnorm(n)
g <- datashade(x, y, width = 400, height = 300)
s <- vl_scene(6, 4.5) |>
  push(vl_viewport(xscale = range(x), yscale = range(y))) |>
  draw(g)

# Categorical: colour each cell by which group dominates it
grp <- sample(c("a", "b"), n, replace = TRUE)
gc <- datashade(x, y, category = grp, colors = c(a = "#e41a1c", b = "#377eb8"))

Description

The line/segment analogue of datashade(). Past a few hundred thousand line vertices — a dense stack of timeseries, or the edges of a large graph — drawing each line as a vector primitive overplots into a solid mass and balloons the output. datashade_lines() and datashade_segments() instead rasterise the lines into a canvas-sized grid in one pass: each cell accumulates the (anti-aliased) coverage of the lines crossing it, so overlapping lines add and the grid records true line density. The grid is shaded exactly like datashade() (colors/how/span/clip) and returned as a single raster_grob().

Usage

datashade_lines(
  x,
  y,
  group = NULL,
  weight = NULL,
  width = 600L,
  height = 400L,
  xlim = NULL,
  ylim = NULL,
  colors = c("#deebf7", "#08306b"),
  how = c("eq_hist", "log", "cbrt", "linear"),
  span = NULL,
  clip = NULL,
  spread = NULL,
  interpolate = FALSE,
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL
)

datashade_segments(
  x0,
  y0,
  x1,
  y1,
  weight = NULL,
  width = 600L,
  height = 400L,
  xlim = NULL,
  ylim = NULL,
  colors = c("#deebf7", "#08306b"),
  how = c("eq_hist", "log", "cbrt", "linear"),
  span = NULL,
  clip = NULL,
  spread = NULL,
  interpolate = FALSE,
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL
)

Arguments

Details

• datashade_lines() takes a connected polyline: a segment is drawn between each consecutive ⁠(x, y)⁠. Pass group to pack several series into one call — the line breaks wherever the group changes; an NA in x/y also breaks it. This is the dense-timeseries path.

• datashade_segments() takes independent segments ⁠(x0, y0) -> (x1, y1)⁠, one per element. This is the network-edge / mark_segment path.

Line coverage is anti-aliased (a Wu accumulator) and summed, so a line deposits roughly weight per cell it spans and dense bundles brighten honestly rather than saturating. As with datashade(), align the raster to data axes by drawing it in a vl_viewport() whose xscale/yscale match xlim/ylim.

Value

A grob (a raster), drawable with draw().

See Also

datashade() for points; dynspread()/spread() for keeping thin lines visible.

Examples

set.seed(1)
# Dense timeseries: 400 random walks of 500 steps, packed into one raster.
k <- 400; m <- 500
walks <- apply(matrix(rnorm(k * m), m, k), 2, cumsum)
t <- rep(seq_len(m), k)
g <- datashade_lines(t, as.vector(walks), group = rep(seq_len(k), each = m),
                     width = 400, height = 300)

# Network edges: random segments shaded by edge density.
n <- 5000
e <- datashade_segments(rnorm(n), rnorm(n), rnorm(n), rnorm(n))

Description

Attach (or replace) an accessible name (title) and long description (desc, the alt text) on an existing scene. The SVG backend then emits role="img" + ⁠<title>⁠/⁠<desc>⁠, and the PDF backend tags the page as a Figure with the description as Alt text — meeting WCAG 1.1.1 (text alternative). Equivalent to passing title/desc to vl_scene().

Usage

describe(scene, title = NULL, desc = NULL)

Arguments

Value

The scene, with the accessibility fields set (a new value).

Examples

vl_scene(2, 2) |>
  draw(points_grob(c(0.3, 0.7), 0.5, gp = vl_gpar(fill = "red"))) |>
  describe(title = "Two red dots", desc = "Two red points on a white field.")

Description

display() re-renders scene to fill the current graphics device and draws it there. Interactively this is the RStudio / Positron Plots pane; inside a knitr / Quarto chunk it becomes the chunk's figure (it draws to the chunk's device). This is the seam any package built on vellum can call to show output instead of writing a file: scene is coerced via as_vellum_scene(), so it also accepts e.g. a grammar's plot spec.

Usage

display(scene, ...)

Arguments

Details

To fill the window (no letterbox margins, like ggplot2) the scene is re-rendered at the device's size and pixel density, so its relative (npc/native/layout) content reflows to the window and absolute (mm/⁠in⁠/pt) content keeps its physical size. It draws through a grid grob that re-rasterizes on every draw, so resizing the Plots pane re-renders the scene crisply at the new size (round markers stay round) rather than stretching one bitmap. Use render() to write the scene at its authored width/height. Auto-printing a scene at the console (or calling plot() on it) displays it.

Inside a knitr / Quarto chunk the chunk's dpi option wins, so knitr::opts_chunk$set(dpi = 200) yields a genuine 200-dpi figure even on knitr's default dev = "png" device (which misreports its pixel density); outside knitting the scene's authored vl_scene() dpi is honored unless the live device reports a trustworthy higher density (e.g. a resized Plots pane).

Value

The (coerced) scene, invisibly.

Examples

## Not run: 
vl_scene(4, 3) |>
  draw(circle_grob(r = 0.3, gp = vl_gpar(fill = "tomato", col = NA))) |>
  display()

## End(Not run)

Description

datashader's dynspread: pick the smallest spread radius (up to max_px) at which the shaded pixels become "connected enough" — the fraction of non-empty pixels with a non-empty neighbour reaches threshold — then spread() by it. Denser images spread less, sparse ones more, so a mix of dense and sparse regions all stay legible.

Usage

dynspread(
  grob,
  max_px = 3L,
  threshold = 0.5,
  shape = c("circle", "square"),
  how = c("over", "add")
)

Arguments

Value

A raster grob with the chosen spread applied.

See Also

spread(), datashade(), datashade_lines().

Examples

set.seed(1)
g <- datashade_segments(rnorm(2000), rnorm(2000), rnorm(2000), rnorm(2000))
g2 <- dynspread(g)

Description

Returns the resolved device-pixel geometry of every keyed element: the two endpoints of a segment, the vertices of a line or polygon, the centre of a round mark, the opposite corners of a rect.

Usage

element_geometry(scene)

Arguments

Details

This is what a host needs to hit-test exactly without asking the engine per event. scene_model() gives bounding boxes, which are right for a brush and misleading for diagonal or thin marks; this gives the shape the box was standing in for, once, so a browser can compute point-to-geometry distances locally at whatever rate it likes.

Value

A data frame of key, kind, vertex (1-based within the element), ring (1-based within the element), x and y. Zero rows if the scene has no keyed elements.

Reading the result

One row per vertex, grouped by key. What the vertices mean depends on kind:

Coordinates are device pixels with y growing down, matching scene_model()'s boxes and the rendered SVG's coordinate system.

ring groups the vertices of a multi-ring path – a polygon with a hole, or a multipart feature – so a host can hit-test it the way the engine does. Without it the concatenated vertices are lossy: treating them as one closed ring invents a phantom edge from each ring's last vertex to the next ring's first. Split on ring and test the rings separately. Every other kind is a single ring, so ring is 1 throughout.

See Also

vl_nearest(), scene_model()

Examples

s <- vl_scene(4, 3, dpi = 96, bg = "white") |>
  draw(segments_grob(0.1, 0.1, 0.9, 0.9, key = "diagonal"))
element_geometry(s)

Description

font_pin() records the fonts a scene resolved to. font_check() re-resolves the same scene and reports what changed — a different file, a missing file, or a family that now resolves somewhere else.

Usage

font_pin(scene)

font_check(scene, pin, on_mismatch = c("warn", "error", "ignore"))

Arguments

Value

font_pin(): a vellum_font_pin object. font_check(): invisibly, a data frame of differences (zero rows when everything matches), with a status of "changed", "missing" or "new".

Why this exists

vellum's determinism claim is that the same scene renders to the same pixels on every OS and in CI. Layout, shaping and rasterisation deliver that. Font resolution does not, and cannot: "sans" is a different file on macOS, Linux and Windows, and even the same family name can resolve to a different version of the same font.

So the claim holds only if the fonts are the same, and until now nothing checked. A pin turns "identical pixels" from an assumption into an assertion: record the manifest next to a reference image, and font_check() will say whether a pixel difference is your change or the machine's font stack.

What this does not do

It does not make fonts reproducible — it cannot install a font, and vellum deliberately resolves fonts through systemfonts so that it agrees with the rest of the R graphics ecosystem. Bundling font files with a scene would break that agreement and raises licensing questions vellum should not answer for you. The honest tool is a check, not a substitute.

The reliable fix, when you need it, is to register the exact file you mean with systemfonts::register_font() and pin that.

Examples

s <- vl_scene(4, 2) |> draw(text_grob("hello"))
pin <- font_pin(s)
pin
# In a test, next to a reference image:
nrow(font_check(s, pin)) == 0

Description

Create a linear or radial gradient to use as a fill in vl_gpar(). A gradient interpolates between colour stops. Its geometry (x1/y1/... or cx/cy/r) is given in the coordinate system named by units and is resolved against the viewport at draw time, so the gradient transforms with the grob just like its outline.

Usage

linear_gradient(
  colours,
  stops = NULL,
  x1 = 0,
  y1 = 0,
  x2 = 1,
  y2 = 0,
  units = "npc",
  extend = "pad",
  interpolation = "srgb"
)

radial_gradient(
  colours,
  stops = NULL,
  cx = 0.5,
  cy = 0.5,
  r = 0.5,
  fx = cx,
  fy = cy,
  fr = 0,
  units = "npc",
  extend = "pad",
  interpolation = "srgb"
)

Arguments

Details

A radial gradient runs between two circles: the focal (start) circle fx/fy/fr at stop offset 0 and the outer (end) circle cx/cy/r at offset 1. By default they are concentric (fx = cx, fy = cy, fr = 0) — the classic centred highlight. Offsetting fx/fy moves the highlight off-centre (as for a sphere lit from one side); a non-zero fr gives an annular ramp between the two circles.

By default stops are blended in sRGB (each backend's native behaviour). Set interpolation = "oklab" to blend in the perceptually-uniform Oklab space instead, which removes the muddy, over-dark midtones and hue drift of sRGB blending — the ramp stays even and vivid. interpolation = "oklch" blends in the polar form of the same space (lightness, chroma, hue): hue and chroma move independently, so a ramp between two saturated colours keeps its chroma through the middle instead of dipping toward grey the way a straight line in Oklab can — at the cost of sweeping through the intermediate hues along the shorter arc (e.g. blue→yellow passes through green). All modes work identically on the raster, SVG, and PDF backends.

Value

A vellum_gradient object, suitable for vl_gpar(fill = ...).

Examples

linear_gradient(c("white", "navy"))
linear_gradient(c("blue", "yellow"), interpolation = "oklab")
linear_gradient(c("blue", "yellow"), interpolation = "oklch")
radial_gradient(c("yellow", "red"), cx = 0.5, cy = 0.5, r = 0.5)
# off-centre highlight (a lit sphere): focal point up and to the left
radial_gradient(c("white", "navy"), cx = 0.5, cy = 0.5, r = 0.6,
                fx = 0.35, fy = 0.65)

Description

Grobs are immutable value objects describing something to draw. Build them with the constructors below, add them to a scene with draw(), and render with render(). Coordinates accept a vl_unit() vector or a bare numeric (interpreted in the default_units, usually "npc").

Usage

rect_grob(
  x = 0.5,
  y = 0.5,
  width = 1,
  height = 1,
  sketch = NULL,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL,
  key = NULL,
  meta = NULL
)

roundrect_grob(
  x = 0.5,
  y = 0.5,
  width = 1,
  height = 1,
  r = 0.1,
  sketch = NULL,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL,
  key = NULL,
  meta = NULL
)

lines_grob(
  x,
  y,
  arrow = NULL,
  start_cap = NULL,
  end_cap = NULL,
  offset = NULL,
  sketch = NULL,
  lwd_profile = NULL,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL,
  key = NULL,
  meta = NULL
)

polygon_grob(
  x,
  y,
  sketch = NULL,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL,
  key = NULL,
  meta = NULL
)

bezier_grob(
  x,
  y,
  n = 60,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL
)

spline_grob(
  x,
  y,
  shape = 1,
  n = 20,
  open = TRUE,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL
)

circle_grob(
  x = 0.5,
  y = 0.5,
  r = 0.25,
  sketch = NULL,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL,
  key = NULL,
  meta = NULL
)

points_grob(
  x,
  y,
  size = vl_unit(2, "mm"),
  shape = "circle",
  sketch = NULL,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL,
  key = NULL,
  meta = NULL
)

hexagon_grob(
  x = 0.5,
  y = 0.5,
  size = vl_unit(2, "mm"),
  width = NULL,
  height = NULL,
  fill = NULL,
  orientation = c("flat", "pointy"),
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL,
  key = NULL,
  meta = NULL
)

sector_grob(
  x = 0.5,
  y = 0.5,
  r0 = 0,
  r1 = 0.5,
  theta0 = 0,
  theta1 = 2 * pi,
  fill = NULL,
  arrow = NULL,
  sketch = NULL,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL,
  key = NULL,
  meta = NULL
)

loop_grob(
  x = 0.5,
  y = 0.5,
  size = vl_unit(4, "mm"),
  foot = vl_unit(0, "mm"),
  angle = 0,
  width = 1,
  arrow = NULL,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL
)

segments_grob(
  x0,
  y0,
  x1,
  y1,
  arrow = NULL,
  start_cap = NULL,
  end_cap = NULL,
  offset = NULL,
  sketch = NULL,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL,
  key = NULL,
  meta = NULL,
  col = NULL,
  lwd = NULL
)

path_grob(
  x,
  y,
  id = NULL,
  rule = c("winding", "evenodd"),
  sketch = NULL,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  role = NULL,
  key = NULL,
  meta = NULL
)

raster_grob(
  image,
  x = 0.5,
  y = 0.5,
  width = 1,
  height = 1,
  interpolate = TRUE,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL
)

text_grob(
  label,
  x = 0.5,
  y = 0.5,
  just = "centre",
  rot = 0,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL,
  width = NULL,
  height = NULL,
  align = "left",
  fit = FALSE,
  key = NULL,
  meta = NULL
)

Arguments

Details

sector_grob() draws a batch of annular sectors (pie / donut / rose wedges) in a single call. gp$fill recycles per sector; gp$col/lwd give a uniform stroke.

Passing r0 == r1 gives an open arc (stroke only). Combined with an absolute (mm) radius at a "native" centre and an vl_arrow(), the radius is resolved to a device length at render (like a marker size), so the arc tracks an mm size at any page size or dpi; the arrowhead sits tangent to the outer arc's end. (For node-link self-loops, prefer loop_grob() — a teardrop, not a ring.)

loop_grob() draws self-loops for node-link diagrams as an igraph-style cubic Bézier teardrop: it leaves the vertex ⁠(x, y)⁠ (a "native" anchor), bulges out to size along angle, and returns, with an optional vl_arrow() head tangent to the curve at the returning foot. size and foot are absolute and resolved to device px at render, so the loop is a fixed physical size that scales with the mm node markers — no native-per-mm estimation, exact at any figure size/dpi.

Value

A grob object.

Description

grobwidth(grob) and grobheight(grob) return a vl_unit() equal to the drawn width/height of grob — handy for sizing a vl_viewport() or grid_layout() track to its contents (e.g. a margin to an axis label). The extent is measured eagerly to absolute millimetres at construction, so it is exact for text and absolute-unit (mm/⁠in⁠/pt) grobs. A grob sized in npc/native has no viewport-independent extent and is measured against a fixed reference, so for those prefer npc/native directly.

Usage

grobwidth(grob, mult = 1)

grobheight(grob, mult = 1)

Arguments

Value

A unit (in millimetres).

Examples

grobwidth(text_grob("A wide axis label", gp = vl_gpar(fontsize = 14)))
grobheight(rect_grob(height = vl_unit(8, "mm")))

Description

Find the topmost node drawn under a point. The scene is compiled into a colour pick-buffer (each grob drawn in a colour encoding its id, respecting clipping and paint order) using the same code path that renders it, so the result is geometry-, clip- and overlap-exact by construction. Markers and text are matched by their bounding box; lines and segments by a small pick band. grid ships no equivalent: grid.locator() waits for one interactive click and returns coordinates rather than a node.

Usage

hit_test(scene, x, y, units = c("npc", "px"))

Arguments

Value

The hit node's name (character); NA_character_ if the topmost grob there is unnamed; or NULL if nothing is drawn at the point.

Description

md() builds a styled label from a small markdown/HTML-free subset, for use as the label of text_grob() (and anywhere a label is measured with grobwidth()/grobheight()). The base font/size/colour come from gp; markup spans override per run.

Usage

md(text)

Arguments

Details

Supported markup:

• ⁠**bold**⁠

• ⁠*italic*⁠ or ⁠_italic_⁠

• ⁠^sup^⁠ (superscript) and ⁠~sub~⁠ (subscript)

• ⁠[text]{#c00}⁠ — a coloured span (any R colour: name or hex)

Spans nest (e.g. ⁠**a^2^**⁠). md() with no markup is equivalent to the plain string. Embedded newlines (⁠\n⁠) start a new line (stacked baseline-to-baseline).

md() is vectorised: a length-1 input returns a single vellum_md_label; a longer vector returns a list of them (one per element), so a vellumplot mark can carry a per-datum rich label.

Value

A vellum_md_label (length-1 text) or a list of them (length > 1).

Examples

lab <- md("R^2^ = **0.91**")
labs <- md(c("*a*", "**b**")) # a list of two labels

Description

node_names() lists the names in a scene. get_node() returns the first node with a given name. edit_node() returns a new scene with that node's properties updated (copy-on-modify).

Usage

node_names(scene)

get_node(scene, name)

edit_node(scene, name, ...)

Arguments

Value

node_names(): character. get_node(): a node. edit_node(): a vellum_scene.

Description

render() writes one page. This writes a document: a report's worth of figures, one facet per page, an animation as a contact sheet.

Usage

pdf_pages(scenes, path = NULL)

Arguments

Details

Pages may differ in size — each carries its own page box — so a landscape figure can sit between two portrait ones.

Tagging follows each page's own metadata, exactly as it does for a single-page render (see vignette("accessible-output")): the pages are drawn by the same code, so a document cannot drift from a single-page file.

Value

path invisibly, or a raw vector when path is NULL.

See Also

render() for a single page.

Examples

pages <- lapply(c("tomato", "steelblue", "seagreen"), function(col) {
  vl_scene(4, 3, dpi = 96, bg = "white") |>
    draw(circle_grob(r = 0.3, gp = vl_gpar(fill = col)))
})
f <- tempfile(fileext = ".pdf")
pdf_pages(pages, f)
file.size(f) > 0

Description

Attributes render cost to the individual marks that caused it, and splits the three phases a render goes through: build (constructing the R value), compile (the R→Rust replay, including text shaping), and raster (drawing). Turns "this plot is slow" into a specific answer.

Usage

profile_render(scene, reps = 3)

Arguments

Details

Read the phase split first. Compile time is R-side — S7 property validation, grob construction, unit records — and on scenes with many small grobs it routinely dominates, in which case no amount of backend tuning will help. The per-node table only accounts for raster time.

Timing is armed only for this call, so ordinary renders pay nothing for it.

Value

A data frame ordered by cost, with columns kind, name, n (elements), seconds and pct (share of raster time). Rows are aggregated per mark — a vectorised text_grob() of 200 labels compiles to 200 nodes but reports as one row — so the table reads as "which of my marks is expensive". The phase split is attached as the "phases" attribute and shown when printed.

See Also

vl_lint(), scene_stats()

Examples

set.seed(1)
s <- vl_scene(4, 3) |>
  draw(points_grob(runif(2000), runif(2000))) |>
  draw(text_grob("title", y = 0.95, gp = vl_gpar(fontsize = 16)))
profile_render(s)

Description

Renders a list of independent scenes across cores. This is embarrassingly parallel — one whole scene per worker, nothing shared — which is why it exists while tiling a single raster across threads does not: that needs synchronised access to one pixmap and is declined in PERFORMANCE.md.

Usage

render_all(scenes, paths, workers = NULL, ...)

Arguments

Details

The saving is real when the scenes are substantial and there are several of them. For a handful of small figures the process/thread overhead dominates and a plain lapply(scenes, render) is as fast; this reports enough to tell.

Value

The paths written, invisibly.

See Also

render(), pdf_pages()

Examples

scenes <- list(
  a = vl_scene(3, 2, dpi = 96) |> draw(circle_grob(gp = vl_gpar(fill = "tomato"))),
  b = vl_scene(3, 2, dpi = 96) |> draw(rect_grob(gp = vl_gpar(fill = "steelblue")))
)
render_all(scenes, file.path(tempdir(), c("a.png", "b.png")))

Description

Compares two scenes structurally and reports the differences in terms of the scene — "the node axis-x moved", "3 marks changed fill" — rather than as a pixel diff.

Usage

scene_diff(a, b, max_depth = 40L)

Arguments

Details

This is a better basis for visual-regression testing than comparing rendered images, for one specific reason: an image diff is sensitive to the font stack, so the same code compared across two machines produces differences that swamp the real change. A structural diff compares what was asked for, and is unaffected.

Value

A data frame with columns path (where in the tree), change ("added", "removed", or "changed"), and detail. Empty when the two scenes are equivalent. Printing shows a readable summary.

See Also

scene_hash() for a yes/no answer, as_scene_spec().

Examples

a <- vl_scene(3, 2) |> draw(circle_grob(r = 0.3, gp = vl_gpar(fill = "red")))
b <- vl_scene(3, 2) |> draw(circle_grob(r = 0.4, gp = vl_gpar(fill = "blue")))
scene_diff(a, b)

Description

Reports the font files a scene's text resolved to, read off the shaped glyphs rather than re-resolved from family names — so it says what was used, not what would be picked if asked again.

Usage

scene_fonts(scene)

Arguments

Value

A data frame with path, index (the face within a font collection), glyphs (how many glyphs came from that face), file (the basename) and exists. Zero rows if the scene has no text.

See Also

font_pin() to record this and check it later.

Examples

s <- vl_scene(4, 2) |> draw(text_grob("hello", gp = vl_gpar(fontfamily = "serif")))
scene_fonts(s)

Description

A stable hash of everything that defines the scene — geometry, style, page size, background. Two scenes that would render identically hash identically; any change to what is drawn changes the hash.

Usage

scene_hash(scene)

Arguments

Details

Useful for caching (has this scene changed since I last rendered it?) and for asserting in tests that a refactor did not alter the scene.

Value

A length-1 character hash.

See Also

scene_diff() to see what changed, as_scene_spec().

Examples

a <- vl_scene(2, 2) |> draw(circle_grob(gp = vl_gpar(fill = "red")))
b <- vl_scene(2, 2) |> draw(circle_grob(gp = vl_gpar(fill = "blue")))
scene_hash(a) == scene_hash(a)
scene_hash(a) == scene_hash(b)

Description

Places a whole scene inside a region of another one. Because a scene is a retained tree with a known resolved size, this is a graft rather than a re-render: the guest's grobs are spliced under a viewport of the host, and the result is an ordinary scene you can keep building on, edit by name, or inset again.

Usage

scene_inset(
  host,
  guest,
  x = 0.5,
  y = 0.5,
  width = 0.3,
  height = 0.3,
  name = NULL,
  ...
)

Arguments

Details

This is the mechanism a composition layer needs — inset maps, small multiples assembled from independently-built plots, a legend built separately and dropped into a corner. The policy (should panel edges align across composed plots? should axes be shared?) belongs above vellum, in a grammar; what the engine provides is the ability to nest one scene in another at all.

The guest's npc coordinates become relative to the region it is placed in, so a guest built on a square page and inset into a wide region will stretch. Match the aspect ratio, or build the guest at the aspect you want.

Value

A vellum_scene.

See Also

vl_viewport(), as_scene_spec()

Examples

main <- vl_scene(4, 3) |>
  draw(rect_grob(gp = vl_gpar(fill = "#eef2f6", col = NA)))
mini <- vl_scene(1, 1) |>
  draw(circle_grob(r = 0.4, gp = vl_gpar(fill = "tomato", col = NA)))
scene_inset(main, mini, x = 0.8, y = 0.75, width = 0.3, height = 0.35)

Description

scene_model() walks a rendered scene and returns one row per drawn element of the keyable marks (points, circles, rects, hexagons, sectors, segments), pairing each element's grammar-supplied identity — its data key, free-form meta, grob id/name, and enclosing panel — with its resolved device-pixel bounding box. It is the host-agnostic bridge underlying interactivity: a host renders the SVG (each element tagged with data-key, see scene_svg()) and uses this table to map an event back to the originating datum.

Usage

scene_model(scene)

Arguments

Details

Elements are returned in paint order. key/meta are NA/NULL for marks drawn without them, so a plain scene still yields a geometry table.

Value

A list with two data frames:

• elements — one row per element: key, mark, id, name, panel, the device-px bbox ⁠x0,y0,x1,y1⁠, its centre/size ⁠x,y,w,h⁠, and a meta list-column.

• panels — one row per named panel: name and its elements' bounding box ⁠x0,y0,x1,y1⁠.

See Also

scene_svg()

Description

Like render() with a .png / .pdf path, but returns the encoded document as a raw vector instead of writing a file. These are the in-memory entry points for a host that needs the bytes rather than a path — embedding a base64 data URI in an HTML widget, serving a plot from a web API, or writing to a connection — without a temp-file round-trip.

Usage

scene_png(scene, scale = 1, cvd = "none")

scene_pdf(scene)

Arguments

Details

Together with scene_svg() (a string) and scene_raster() (pixels), every output format vellum supports can now be produced without touching disk.

Backend degradation warnings (see render()) are surfaced here too, so a PDF that could not honour a pattern or mask reports it exactly as writing a file would.

Value

A raw vector: the encoded PNG or PDF document.

See Also

render(), scene_svg(), scene_raster()

Examples

s <- vl_scene(2, 2) |> draw(circle_grob(gp = vl_gpar(fill = "steelblue")))
png_bytes <- scene_png(s)
length(png_bytes)
rawToChar(png_bytes[2:4]) # "PNG"

Description

scene_raster() renders scene and returns its pixels as an integer array with dimensions c(channel, x, y) — RGBA channels in 0:255, top-left origin, y increasing downward. This is the form most convenient for probing or testing (e.g. scene_raster(s)[1, x, y] is the red value at pixel ⁠(x, y)⁠).

Usage

scene_raster(scene, cvd = "none")

Arguments

Details

An grDevices::as.raster() method returns the same image as a raster object (a character matrix of hex colours), drawable with graphics::plot() or grid::rasterGrob().

Value

scene_raster(): an integer array of dimension c(4, width, height). The as.raster() method: a raster (character matrix, c(height, width)).

Examples

s <- vl_scene(2, 1, bg = "white") |>
  draw(circle_grob(r = 0.3, gp = vl_gpar(fill = "red", col = NA)))
dim(scene_raster(s)) # c(4, width_px, height_px)

Description

How much of the canvas a scene actually covers, and how hard it is working to do it. overplot is the honest signal for "should this be datashade()-ed?": a count of marks says nothing about whether they overlap, whereas thirty thousand well-separated points are fine and eight thousand piled on top of each other are not.

Usage

scene_stats(scene)

Arguments

Value

A one-row data frame:

elements

total drawn elements.

ink

fraction of canvas pixels differing from the background.

colours

distinct colours in the rendered image.

overplot

summed element-box area divided by inked area — an estimate of how many times an average inked pixel was drawn over. 1 means no overlap. It is computed from bounding boxes, so it over-estimates for non-rectangular marks (a circle fills ~79% of its box); treat it as an index, not a measurement. Marks the element table does not cover — text, and unkeyed lines/polygons/paths — contribute to ink but not to overplot.

See Also

vl_lint(), profile_render(), datashade()

Examples

set.seed(1)
sparse <- vl_scene(4, 3) |> draw(points_grob(runif(200), runif(200)))
dense <- vl_scene(4, 3) |> draw(points_grob(rnorm(20000, 0.5, 0.05),
                                            rnorm(20000, 0.5, 0.05)))
rbind(sparse = scene_stats(sparse), dense = scene_stats(dense))

Description

Like render() with an .svg path, but returns the SVG document as a character string instead of writing a file. This is the in-memory entry point for hosting a scene interactively (an htmlwidget embeds the markup directly) and for tests that assert on emitted attributes such as data-key.

Usage

scene_svg(scene, text = c("native", "outline"))

Arguments

Value

A length-1 character vector: the SVG document.

See Also

render(), scene_png(), scene_model()

Description

Persist a scene so it can be rebuilt later, in another session, or in another process. .rds is the default and needs nothing extra; .json produces a portable text format and needs the jsonlite package.

Usage

scene_write(scene, path)

scene_read(path)

Arguments

Details

What this buys you: caching a built scene without re-running the code that built it, sending one over a wire for a worker to render, and keeping a reproducible intermediate between "the code" and "the pixels".

Value

scene_write(): path, invisibly. scene_read(): a vellum_scene.

See Also

as_scene_spec(), scene_diff(), scene_hash()

Examples

s <- vl_scene(2, 2) |> draw(circle_grob(gp = vl_gpar(fill = "steelblue")))
f <- tempfile(fileext = ".rds")
scene_write(s, f)
identical(as_scene_spec(scene_read(f)), as_scene_spec(s))

Description

Attach to a grob's sketch argument to render it in a hand-drawn, sketchy style (the Rough.js look): wobbly outlines and hachure fills. Supported by rect_grob(), polygon_grob(), lines_grob(), and circle_grob(). Output is deterministic given seed.

Usage

sketch(
  roughness = 1,
  bowing = 1,
  fill_style = c("hachure", "solid", "crosshatch", "zigzag", "dots"),
  fill_weight = NULL,
  hachure_angle = -41,
  hachure_gap = NULL,
  curve_tightness = 0,
  disable_multi_stroke = FALSE,
  preserve_vertices = FALSE,
  seed = 1L
)

Arguments

Details

Sketch is a deliberate exception to vellum's crisp, fidelity-first defaults — see vignette / ⁠_docs/DESIGN-ROUGHR.md⁠. Text is never sketched.

Value

A vellum_sketch object for a grob's sketch argument.

Examples

rect_grob(gp = vl_gpar(fill = "steelblue", col = "black"), sketch = sketch())

Description

Grow each non-empty pixel of a raster over a small neighbourhood so thin marks stay visible. This is datashader's spread: useful after datashade(), datashade_lines(), or datashade_segments() when the output is sparse (single-pixel lines, isolated points). dynspread() chooses the radius automatically from the image's density; spread() uses a fixed one.

Usage

spread(grob, px = 1L, shape = c("circle", "square"), how = c("over", "add"))

Arguments

Value

A raster grob with the spread applied.

See Also

dynspread(), datashade(), datashade_lines().

Examples

set.seed(1)
g <- datashade_segments(rnorm(2000), rnorm(2000), rnorm(2000), rnorm(2000))
g2 <- spread(g, px = 2)

Description

Converts the stroke of a line-like grob into a path_grob describing the region the stroke covers — the shape you would get by tracing round the drawn line. What was a one-pixel-wide path with a colour becomes an area with an interior, which is what you need in order to fill it with a gradient or a pattern, to send it to a cutting plotter or CNC tool, or to do geometry with it.

Usage

stroke_to_path(
  grob,
  width = 6,
  height = 4,
  dpi = 96,
  gp = NULL,
  lwd_profile = NULL,
  along = c("arclength", "vertex")
)

Arguments

Details

At constant width the expansion uses the same stroker the rasterizer uses, so the outline is exactly the region that would have been inked, not a reimplementation that could drift from it. A varying width has no such reference — no rasterizer can stroke a line at a changing width — so lwd_profile is served by vellum's own offsetter instead. See ⁠Variable width⁠ below.

The result is baked at one size. A stroke width is a device quantity, so its outline only exists once a page size and resolution are chosen. Those are arguments here, and the returned coordinates are absolute (mm) — the outline will not rescale with the page the way the original stroke would. That is inherent: an outline is a shape, not a stroke.

Value

A path_grob() in mm units, with rule = "winding", whose fill is the stroked region. Its gp starts from the source grob's stroke colour as a fill, so drawing it looks like the original line.

Variable width

The region swept by a round nib of varying radius is the union of the convex hulls of successive pairs of end discs, so lwd_profile builds that union rather than offsetting each vertex along its normal. The distinction matters at a taper: an offset boundary would cut into the end disc and the tip would come out waisted rather than pointed.

Three consequences worth knowing:

• Width varies linearly between vertices, so a profile is only as smooth as the polyline under it. bezier_grob() and spline_grob() flatten to a polyline before this function sees them, so a profile rides the flattened points — prefer along = "arclength" there, and raise their n if a taper looks faceted.

• On a closed polygon_grob() or path_grob() the profile is cyclic: a ring has no first vertex a reader can see, so the values wrap. c(1, 0) on a ring is therefore two tapers, not one.

• lwd_profile = NULL is byte-identical to previous versions. A constant profile such as lwd_profile = 1 is not — it goes through the offsetter, so it agrees with tiny-skia's stroker as a picture but not to the last bit. lineend and linejoin are honoured, but only on the outer silhouette; the inner side of a join is the natural overlap either way.

See Also

path_grob(), grob, segments_grob() for per-element widths

Examples

zig <- lines_grob(c(0.1, 0.35, 0.6, 0.9), c(0.2, 0.8, 0.2, 0.8),
                  gp = vl_gpar(col = "steelblue", lwd = 12))
outline <- stroke_to_path(zig, width = 3, height = 2)
# A width that varies along the line: thick in the middle, tapered at both ends.
leaf <- stroke_to_path(zig, width = 3, height = 2, lwd_profile = c(0.15, 1, 0.15))
# Now fillable: a gradient across the ribbon the line traced.
vl_scene(3, 2) |>
  draw(S7::set_props(outline, gp = vl_gpar(
    fill = linear_gradient(c("tomato", "gold")), col = "grey20", lwd = 0.5
  )))

Description

A style bundles vl_gpar() graphical parameters under an optional name so the same look can be reused across many viewports or grobs. A style is a gpar — it carries every graphical-parameter field and obeys the same inheritance rules — with an added name for identification. It can therefore be passed anywhere a gp is accepted.

Usage

style(
  col = NULL,
  fill = NULL,
  lwd = NULL,
  alpha = NULL,
  lty = NULL,
  lineend = NULL,
  linejoin = NULL,
  linemitre = NULL,
  fontfamily = NULL,
  fontface = NULL,
  fontsize = NULL,
  cex = NULL,
  lineheight = NULL,
  halo_col = NULL,
  halo_width = NULL,
  features = NULL,
  antialias = NULL,
  crisp = NULL,
  dash_phase = NULL,
  name = NULL
)

Arguments

Details

Attaching a style to a viewport cascades its defaults to the whole subtree via the ordinary gpar inheritance (more-specific overrides less-specific), so a child grob's own gp still wins. This is the reusable "style class" layer that sits below a grammar's themes: a theme can compile into named styles rather than setting gpar fields ad hoc on every element.

Value

A style object (a subclass of gpar).

Examples

accent <- style(col = "firebrick", lwd = 2, name = "accent")
# Reuse it on a viewport; children inherit unless they override.
vl_viewport(gp = accent)

Description

text_path_grob() places a label along a polyline baseline instead of at a point: each glyph keeps the pen position shaping gave it and is drawn at that distance along the path, rotated to the local tangent. Use it for labels that follow an arc, a contour, a river or a curved axis.

Usage

text_path_grob(
  label,
  x,
  y,
  just = "centre",
  offset = 0,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  id = NULL,
  role = NULL
)

Arguments

Details

The path is a sequence of points, exactly like lines_grob() — pass the output of bezier_grob()-style control points already flattened, or any polyline. Arc length is measured on the rendered path, so the result adapts to the viewport the grob is drawn in.

just does double duty: the horizontal component slides the run along the baseline ("left" starts at the first point, "centre" centres it, "right" ends at the last), and the vertical component positions the glyphs against the baseline as it would for ordinary text. For finer control of the standoff — a label riding just above a curve rather than sitting on it — use offset.

Glyphs follow the tangent, as in SVG textPath: a label on the underside of a closed curve reads upside-down. That is the honest result of the geometry, and the fix is to reverse the path rather than the glyphs — set the lower arc as a second text_path_grob() whose points run the other way.

Glyphs are placed one per character. For Latin text that is exact; scripts where shaping produces a different number of glyphs than characters (Arabic, Devanagari, and ligature-heavy fonts) will still draw, but the per-glyph text recovered by PDF copy-paste and by SVG native text degrades to the whole label on the first glyph.

Value

A grob.

Examples

th <- seq(pi, 0, length.out = 60)
vl_scene(4, 2.2, dpi = 96, bg = "white") |>
  draw(text_path_grob(
    "text that follows a curve",
    x = 0.5 + 0.42 * cos(th), y = 0.15 + 0.7 * sin(th),
    offset = 3, gp = vl_gpar(fontsize = 13)
  ))

Description

Describe arrowheads to draw on the ends of a lines_grob() or segments_grob() (pass as their ⁠arrow =⁠ argument).

Usage

vl_arrow(
  angle = 30,
  length = vl_unit(0.25, "in"),
  ends = c("last", "first", "both"),
  type = c("open", "closed")
)

Arguments

Value

A vellum_arrow object.

Examples

lines_grob(c(0.1, 0.9), c(0.1, 0.9), arrow = vl_arrow(type = "closed"))

Description

Grows a ring by width in every direction — the exclusion zone around a region, the halo around a cluster outline, the standoff a leader line should keep.

Usage

vl_buffer(x, y, width, arc = 6)

Arguments

Details

Corners are rounded, which is what a standoff usually wants and what keeps the result well-defined at sharp angles (a mitred corner runs away to infinity as the angle closes).

On concave rings: the offset boundary of a concave polygon can cross itself where the buffer is wider than a local feature. This function offsets the ring and does not repair that, because repairing it is a boolean union — a Phase 12 operation. Buffering a convex ring, or buffering by less than the narrowest feature, is always well-behaved. Passing the result through vl_hull() is a crude but effective fix when it is not.

Value

A data frame of the buffered ring's x/y.

Examples

tri <- data.frame(x = c(0.3, 0.7, 0.5), y = c(0.3, 0.35, 0.7))
buf <- vl_buffer(tri$x, tri$y, 0.08)
vl_scene(3, 3, dpi = 96, bg = "white") |>
  draw(polygon_grob(buf$x, buf$y, gp = vl_gpar(fill = "#F3E0DA", col = NA))) |>
  draw(polygon_grob(tri$x, tri$y, gp = vl_gpar(fill = "tomato", col = NA)))

Description

vellum memoises compiled scenes keyed on an object-identity token so repeat renders of an unchanged scene (multi-format export, a display() resize back to a prior size, or animation replaying a fixed set of frames) are cheap. The cache is transparent — a cached render is byte-identical to an uncached one — and bounded (options(vellum.cache_size=), default 8), so you rarely need this; it is provided to reclaim memory or to force a cold render in benchmarks. Disable caching entirely with options(vellum.cache = FALSE).

Usage

vl_clear_render_cache()

Value

NULL, invisibly.

Examples

vl_clear_render_cache()

Description

Marching squares over a matrix, chained into polylines. Use it for density isolines over a datashade() surface, level curves of a fitted model, or any other gridded field.

Usage

vl_contour(z, levels = NULL, xlim = c(0, 1), ylim = c(0, 1))

contour_grob(
  contours,
  close = TRUE,
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  role = NULL
)

Arguments

Details

Segments are chained into continuous lines rather than returned loose. That matters beyond tidiness: an unchained contour restarts its dash pattern in every grid cell, cannot be simplified or measured, and cannot be filled. Closed rings come back closed.

Cells with a non-finite corner are skipped, so a contour breaks around missing data rather than being drawn through it.

Value

A data frame with one row per point: level, id (a distinct contour line), x, y, and closed. Draw it with lines_grob(x, y, id = id).

Examples

# A ring contour around a Gaussian bump.
# rows index x, columns index y -- exactly what `outer(xs, ys, f)` gives.
g <- outer(seq(-3, 3, length.out = 60), seq(-3, 3, length.out = 60),
           function(x, y) exp(-(x^2 + y^2) / 2))
head(vl_contour(g, levels = c(0.2, 0.5, 0.8)))
# Draw them: one grob per contour, because each is its own polyline.
# rows index x, columns index y -- exactly what `outer(xs, ys, f)` gives.
g <- outer(seq(-3, 3, length.out = 60), seq(-3, 3, length.out = 60),
           function(x, y) exp(-(x^2 + y^2) / 2))
vl_scene(3, 3, dpi = 96, bg = "white") |>
  push(vl_viewport(xscale = c(-3, 3), yscale = c(-3, 3))) |>
  draw(contour_grob(vl_contour(g, levels = c(0.2, 0.5, 0.8)),
                    gp = vl_gpar(col = "steelblue"))) |>
  pop() |>
  (\(s) s)()

Description

The counterpart to grid's convertWidth()/convertHeight()/convertX()/ convertY(): resolve a vl_unit() vector to a plain number in some other unit. why_size() explains a named node's resolved size and scene_model() reports resolved boxes for keyed elements; this answers the remaining question — "how big is this particular unit, here?" — which a layer built on vellum needs whenever it has to size something itself.

Usage

vl_convert(
  u,
  to = "mm",
  scene = NULL,
  name = NULL,
  axis = c("x", "y"),
  what = c("length", "position")
)

Arguments

Details

Absolute units (mm, cm, ⁠in⁠, pt) convert with no context, so scene may be omitted. Relative units (npc, native) need to know the region they are relative to, and therefore need a scene — and, for anything other than the whole page, the name of a viewport in it.

Where grid uses four functions, this uses two arguments: axis picks the x or y extent, and what distinguishes a length from a position. They differ only for native, and only when the scale does not start at zero: on xscale = c(10, 20), unit(12, "native") is two tenths of the width as a position, but twelve tenths as a length.

Value

A numeric vector the same length as u, in to units.

See Also

why_size(), scene_model(), vl_unit()

Examples

s <- vl_scene(4, 3, dpi = 100)
vl_convert(vl_unit(1, "in"), "mm") # absolute: no scene needed
vl_convert(vl_unit(0.5, "npc"), "mm", s) # half the page width
vl_convert(vl_unit(0.5, "npc"), "mm", s, axis = "y")

# A named viewport, and the length/position distinction on a shifted scale.
s2 <- s |> push(vl_viewport(width = 0.5, xscale = c(10, 20), name = "panel"))
vl_convert(vl_unit(12, "native"), "mm", s2, name = "panel")
vl_convert(vl_unit(12, "native"), "mm", s2, name = "panel", what = "position")

Description

Answers "where is there room?" — for a legend, an annotation, a watermark, or anything else that has to go somewhere the marks are not.

Usage

vl_empty_region(
  scene,
  avoid = NULL,
  within = NULL,
  grid = 200,
  unit = c("npc", "mm")
)

Arguments

Details

Occupancy is rasterised onto a grid and the answer is exact on that grid. The approximation is deliberate: the exact maximal empty rectangle over n boxes is superquadratic, and nothing is placed to sub-pixel tolerance. Raise grid to trade time for precision. Boxes are rounded outward, so the result is conservative — it will never claim space that is in fact occupied.

Value

A named numeric c(x0, y0, x1, y1), in unit, using the usual y-grows-up convention. All zeros if there is no free space.

Examples

set.seed(1)
s <- vl_scene(4, 3, dpi = 96, bg = "white") |>
  draw(points_grob(runif(40) * 0.5, runif(40),
                   gp = vl_gpar(fill = "steelblue", col = NA)))
vl_empty_region(s)

Description

Builds a set of graphical parameters attached to a grob or viewport. Any field left NULL is inherited from the enclosing viewport; alpha multiplies down the viewport tree. A colour value sets it; NA means "no paint".

Usage

vl_gpar(
  col = NULL,
  fill = NULL,
  lwd = NULL,
  alpha = NULL,
  lty = NULL,
  lineend = NULL,
  linejoin = NULL,
  linemitre = NULL,
  fontfamily = NULL,
  fontface = NULL,
  fontsize = NULL,
  cex = NULL,
  lineheight = NULL,
  halo_col = NULL,
  halo_width = NULL,
  features = NULL,
  antialias = NULL,
  crisp = NULL,
  dash_phase = NULL
)

Arguments

Value

A gpar object.

Examples

vl_gpar(col = "steelblue", lwd = 2, lty = "dashed", lineend = "round")

Description

Fills a shape with ruled parallel lines. Unlike vl_pattern(), which rasterises a tile, a hatch is geometry: it stays crisp at any zoom, prints correctly, and survives being converted to greyscale.

Usage

vl_hatch(angle = 45, spacing = 3, width = 0.75, col = "black", bg = NA)

Arguments

Details

That last point is the reason to reach for it. A colour encoding that fails for a red/green-blind reader — which render()'s cvd argument will show you and vl_lint() will flag — is fixed by encoding with texture as well as hue. Hatching is the standard way to do that.

Value

A vellum_hatch object, usable anywhere a fill is.

See Also

vl_pattern() for a tiled grob, linear_gradient(), vl_lint()

Examples

vl_scene(3, 2) |>
  draw(rect_grob(width = 0.8, height = 0.8, gp = vl_gpar(
    fill = vl_hatch(angle = 45, spacing = 4), col = "grey30"
  )))

Description

vl_hull() returns the convex hull, or a concave one that follows the point set more closely — useful for outlining a cluster, or for building an exclusion zone that annotations should avoid.

Usage

vl_hull(x, y, concavity = Inf)

Arguments

Details

The concave hull digs into the convex hull, replacing an edge with two edges through the nearest unused point whenever the edge is long relative to the detour. concavity is that threshold, and larger means more convex:

• Inf (the default) is exactly the convex hull.

• 8 follows the points loosely.

• 4 is a good tight outline for a scattered cluster.

• Below about 3 the boundary starts to self-intersect.

Self-intersection is inherent to the method, not a defect to be fixed here — a boundary that threads between interior points has to cross itself eventually. Inspect the result if you push it hard.

Value

A data frame of the hull ring's x/y, in order, ready for polygon_grob(). The ring is not closed (the last point does not repeat the first).

Examples

set.seed(1)
pts <- data.frame(x = runif(40), y = runif(40))
h <- vl_hull(pts$x, pts$y)
vl_scene(3, 3, dpi = 96, bg = "white") |>
  draw(polygon_grob(h$x, h$y, gp = vl_gpar(fill = "#DCE7F5", col = "steelblue"))) |>
  draw(points_grob(pts$x, pts$y, gp = vl_gpar(fill = "grey25", col = NA)))

Description

Static analysis for graphics. vl_lint() resolves the scene and inspects the geometry the renderer would draw with, reporting the things people normally find by squinting at the output: a mark that landed off-canvas, a label too small to read, text that will not contrast with what is behind it, an element that is invisible because nothing was ever going to paint it.

Usage

vl_lint(
  scene,
  rules = NULL,
  exclude = NULL,
  severity = NULL,
  min_text_px = 7,
  min_text_pt = 6,
  min_contrast = 3,
  max_overplot = 8,
  cvd = "deuteranopia",
  min_cvd_delta = 0.06
)

Arguments

Details

This is possible because vellum resolves layout and text metrics before drawing. A layer above grid cannot ask "how many pixels tall is this label", because the answer does not exist until a device is open.

The rule set is extensible — see vl_lint_rule().

Value

A data frame of findings, empty if the scene is clean: rule, severity, node, message, and the finding's device-px box (x0, y0, x1, y1, NA where a rule reported something with no geometry). Printing shows a grouped summary.

A rule that fails does not abort the lint: it is reported as a rule_error finding naming the rule, and the other rules still run.

See Also

vl_lint_rule(), scene_stats(), why_size()

Examples

# A label pushed off the page, and one too small to read.
s <- vl_scene(3, 2) |>
  draw(text_grob("off the edge", x = 1.6, y = 0.5)) |>
  draw(text_grob("tiny", x = 0.5, y = 0.2, gp = vl_gpar(fontsize = 2)))
vl_lint(s)

Description

vl_lint() for a test suite or a CI job: run the rules and stop if anything turns up. A figure that lints clean today stays that way, in the same spirit as font_pin() and scene_hash() — with the difference that this one catches defects rather than changes.

Usage

vl_lint_assert(
  scene,
  ...,
  severity = c("warning", "note"),
  on = c("error", "warn")
)

Arguments

Value

Invisibly, the findings that triggered the failure — a zero-row frame when the scene is clean.

See Also

vl_lint(), vl_lint_overlay() to see what was reported.

Examples

clean <- vl_scene(3, 2) |> draw(text_grob("fine", gp = vl_gpar(fontsize = 12)))
vl_lint_assert(clean)

# In a test:
# test_that("the figure has no lint findings", vl_lint_assert(my_plot()))

Description

The return shape vl_lint_rule() functions must produce. Vectorised over nodes, so a rule matches rows and describes them in one call.

Usage

vl_lint_finding(rule, severity = c("warning", "note"), nodes, message)

Arguments

Value

A data frame of findings, one row per node, with the node's device-px box carried through in x0/y0/x1/y1 so a caller can point at the finding on the image. The box is NA when nodes has no geometry.

Description

Puts a box around every finding that has geometry, and labels it with the rules that fired. For a graphics linter this is usually the fastest way to understand a report: a message says a mark is clipped, an outline shows you which one.

Usage

vl_lint_overlay(scene, findings = NULL, labels = TRUE)

Arguments

Details

Findings with no geometry (a rule_error, or a rule reporting something scene-wide) have nothing to point at and are skipped.

Value

A new scene: scene with the overlay drawn on top, at page level.

See Also

vl_lint(), vl_lint_assert()

Examples

s <- vl_scene(3, 2) |>
  draw(text_grob("off the edge", x = 1.6, y = 0.5)) |>
  draw(text_grob("tiny", x = 0.5, y = 0.2, gp = vl_gpar(fontsize = 2)))
# display(vl_lint_overlay(s))
nrow(vl_lint(s)) > 0

Description

Adds a rule to the registry vl_lint() runs. A package layered on vellum can register rules of its own — vellum supplies the geometric ones (a mark drawn off-canvas, text too small to read), a grammar layer can add semantic ones (a scale with a single level, a legend with forty entries) — and both come back from one vl_lint() call.

Usage

vl_lint_rule(
  name,
  fn,
  description = "",
  kinds = NULL,
  needs_pixels = FALSE,
  tags = character()
)

vl_lint_rules()

Arguments

Value

Invisibly, name.

vl_lint_rules(): a data frame of registered rules, with the kinds a rule looks at, whether it renders the scene, and its tags.

See Also

vl_lint(), vl_lint_rules()

Examples

vl_lint_rule("no_hexagons", function(scene, nodes, ctx) {
  hits <- nodes[nodes$kind == "hexagon", , drop = FALSE]
  if (!nrow(hits)) return(NULL)
  vl_lint_finding("no_hexagons", "note", hits, "hexagons are banned here")
}, "example rule", kinds = "hexagon")

Description

Ranks a scene's keyed elements by their distance to a point — measuring to the actual geometry, not to a bounding box.

Usage

vl_nearest(scene, x, y, units = c("npc", "px"), n = 1L, max_dist = Inf)

Arguments

Value

A data frame of key, kind and dist (device px), nearest first. Zero rows if nothing is in range. Only keyed elements are considered — an unkeyed mark is not addressable, so reporting it would be no use.

Why not the bounding box

For a round or upright mark the two agree. For anything diagonal or thin they do not, and the difference is not subtle: a line from the bottom-left of a panel to the top-right has a bounding box covering the entire panel, so a box-based "what is nearest" reports it from anywhere in the plot. That is why a host holding only boxes has to exclude such marks from hover rather than rank them wrongly.

Distances are: to the disc for round marks (zero inside), to the rectangle for rects (zero inside), perpendicular to the segment for segments, to the nearest edge for open polylines, and zero anywhere inside a closed polygon or path — so clicking the middle of a choropleth region hits that region.

Marks vellum cannot describe more precisely than a box — labels, rounded rects — fall back to their box, which for a label is a fair description of the target anyway.

For a client-side host

A browser cannot call back into R on every mouse move. Use element_geometry() instead: it returns the same true geometry once, and the client computes distances locally. vl_nearest() is for hosts that can ask — a Shiny app, a test, a script.

See Also

element_geometry() for the geometry itself, scene_model() for bounding boxes, hit_test() for "which grob is under this pixel".

Examples

s <- vl_scene(4, 3, dpi = 96, bg = "white") |>
  draw(segments_grob(0.1, 0.1, 0.9, 0.9, key = "diagonal")) |>
  draw(points_grob(0.8, 0.2, key = "corner"))

# Near the corner the diagonal's *bounding box* also contains this point,
# but its geometry is far away.
vl_nearest(s, 0.8, 0.2)

Description

Combine two shapes as geometry: union, intersection, difference or exclusive-or over their closed rings.

Usage

vl_path_op(
  a,
  b,
  op = c("union", "intersect", "difference", "xor"),
  rule = c("nonzero", "evenodd"),
  gp = vl_gpar(),
  name = NULL,
  vp = NULL,
  role = NULL
)

Arguments

Value

A path_grob() with rule = "winding". An empty result (a disjoint intersection, say) gives a grob with no points, which draws nothing.

Why geometry and not a mask

vellum can already clip one shape by another at render time, and for simply showing an intersection that is often enough. A boolean result is different in kind: it is an ordinary path, so it can be measured, hit-tested, simplified, filled with a gradient, stroked, exported as ⁠<path>⁠ data, and fed into another boolean. A mask can do none of those, rasterises, and degrades on some PDF paths.

Rings, holes and the fill rule

rule says how to interpret the inputs — whether a ring inside another ring is a hole ("evenodd") or a separate island ("nonzero"). It must match the rule the operands were drawn with, or the answer will be correct for a shape you did not mean.

The result always uses the non-zero rule: holes come back wound opposite to their outer ring, which is how the returned path_grob() is set up.

Operands must be in a single coordinate space — one unit, no offsets — since a boolean has to be computed somewhere, and mixed units have no common space.

Examples

sq <- function(x0, y0, s = 0.4) {
  list(x = c(x0, x0 + s, x0 + s, x0), y = c(y0, y0, y0 + s, y0 + s))
}
a <- sq(0.2, 0.3)
b <- sq(0.45, 0.4)
vl_scene(3, 2, dpi = 96, bg = "white") |>
  draw(vl_path_op(a, b, "union", gp = vl_gpar(fill = "#DCE7F5", col = "steelblue")))

Description

Create a pattern that fills a shape by tiling a grob. The grob is drawn once into a tile occupying the unit square (⁠0..1⁠ npc), then repeated across a cell of size width x height (in units) anchored at ⁠(x, y)⁠. Like gradients, the cell geometry is resolved against the viewport at draw time.

Usage

vl_pattern(
  grob,
  width = 0.1,
  height = 0.1,
  x = 0.5,
  y = 0.5,
  units = "npc",
  extend = "repeat"
)

Arguments

Details

The tile is rendered to a raster image (sized from width/height at the scene's resolution) and embedded on every backend: PNG raster, SVG ⁠<image>⁠ in a ⁠<pattern>⁠, and a PDF tiling pattern with the tile as an embedded image XObject. Only a degenerate tile or cell size fails, leaving the shape unfilled with a degrade warning.

Value

A vellum_pattern object, suitable for vl_gpar(fill = ...).

Examples

dots <- circle_grob(r = 0.25, gp = vl_gpar(fill = "white", col = NA))
vl_pattern(dots, width = 0.08, height = 0.08)