Skip to contents

Getting started with rpic

Source: vignettes/rpic.Rmd
rpic.Rmd

rpic renders diagrams written in Brian Kernighan’s pic picture-drawing language: you describe a drawing by walking around a plane dropping primitives — boxes, circles, lines, arrows — with relative positioning doing the layout for you. The engine is pure Rust (no troff, no LaTeX, no system dependencies) and outputs SVG, PNG and PDF.

All diagrams in this vignette were pre-rendered with rpic_svg() — the code chunks show exactly the source that produced each figure. The full language reference, extension pages and a live playground are at rpic.dev.

A first picture

Primitives placed in sequence flow in the current direction (right, by default); arrow connects them; arc bends between named positions:

library(rpic)

svg <- rpic_svg('
boxht = 0.35; boxwid = 0.8
A: box "input"
arrow
box "process" fill 0.9
arrow
E: ellipse "output"
arc cw -> from A.n to E.n
')
input, process and output connected by arrows, with an arc looping over the top
input, process and output connected by arrows, with an arc looping over the top

Positioning

Objects can be labelled (A:), addressed by compass corners (.n, .e, .c, …) or by ordinals (last circle, 2nd box), and placed with expressions — including fractions of the way between two points:

rpic_svg('
A: box "A" wid 0.6 ht 0.4
B: box "B" wid 0.6 ht 0.4 at A + (1.6, 0)
line dashed from A.e to B.w
circle rad 0.06 fill 0 at 1/2 between A.e and B.w
"midpoint" at last circle.s below
arrow from A.n up 0.3 then right 1.6 then down 0.3 to B.n
"the long way" at 1/2 between A.n and B.n + (0, 0.42)
')
two boxes joined by a dashed line with a marked midpoint, and an arrow taking the long way over the top
two boxes joined by a dashed line with a marked midpoint, and an arrow taking the long way over the top

Programmability

pic is a little language: for/if, variables, define macros with $1…$9, and sprintf are all built in:

rpic_svg('
for i = 0 to 5 do {
  circle rad 0.12 fill i/6 at (i * 0.4, 0)
}
')
six circles in a row, shading from black to light gray
six circles in a row, shading from black to light gray

TeX math labels

With texlabels = TRUE (or texlabels = 1 in the source), a label written entirely as $…$ is typeset as TeX math, natively — KaTeX-grade quality with exact metrics, so boxes fit around formulas correctly. Write TeX commands with a single backslash in the pic source (escaped as \\ inside an R string):

rpic_svg('
box "$\\frac{1}{2\\pi}\\int_{-\\infty}^{\\infty} f(t)\\,e^{-i\\omega t}\\,dt$" fit
', texlabels = TRUE)
a box fitted around the Fourier-transform integral, typeset as math
a box fitted around the Fourier-transform integral, typeset as math

rpic extensions

Beyond classic pic, opt-in extensions cover linear gradient fills, hatch patterns, curly brace annotations, margin, fit, opacity, layers (behind) and more — each documented with live examples at rpic.dev. They are inert for classic input:

rpic_svg('
B: box wid 0.9 ht 0.55 gradient "steelblue" "white"
"gradient" at B.c
C: circle rad 0.3 hatch hatchangle 45 at B.e + (1.0, 0)
"hatch" at C.s below
brace from B.nw + (0, 0.15) to C.ne + (0, 0.15) up "extensions"
')
a gradient-filled box and a hatched circle spanned by a curly brace labelled extensions
a gradient-filled box and a hatched circle spanned by a curly brace labelled extensions

Errors you can point at

Compile failures raise a classed rpic_error condition whose info field carries the structured diagnostic — position (always relative to your source), kind, and a did-you-mean hint:

tryCatch(
  rpic_svg("bxo", circuits = TRUE),
  rpic_error = function(e) list(line = e$info$line, hint = e$info$hint)
)
#> $line
#> [1] 1
#> $hint
#> [1] "did you mean `box`?"

Where next