What the painters were given

The paint engine, as a painter uses it

notes/guide.md · 933 lines · Guide

Given to 3 painters:

The paint engine, as a painter uses it

This guide covers the paint crate (crates/paint/src) and the stage runner (paintings/src/run.rs) in the order a painting needs them. The module docs at the top of each source file are the reference. This guide says what each part does physically and how to call it. The study programs in paintings/src/bin/study_*.rs call these APIs in working code.

Contents:

  1. Units, colors and a program
  2. Canvas, ground and style
  3. Brushes and gestures
  4. Handlings: covering a passage
  5. Palette, color and aiming
  6. Stipple
  7. Glazes and veils
  8. Drying and time
  9. Masks, forms and scene helpers
  10. Pencil
  11. Finish (optional): varnish, cracks, relief
  12. The stage runner, crops and checkpoints
  13. Viewing renders
  14. What is slow

1. Units, colors and a program

A painting is a binary in paintings/src/bin/<name>.rs. Cargo finds it by its file name, and cargo paint <name> -- --full runs it at 2400 px wide (the paint alias is in .cargo/config.toml). A minimal program, one gray swatch on a primed canvas:

use paint::{Mask, Rng, Shape, Style, hex};
use paintings::run::Run;

fn main() {
    let o = Run::new("my_painting");
    let st = Style::friedrich();
    let mut rng = Rng::new(o.seed);
    let mut c = o.canvas(|| st.prepare(o.width, 1.0, o.seed));
    let f = c.frame();
    let swatch = Mask::from_shape(f, Shape::new().rect(400.0, 400.0, 200.0, 200.0));
    if o.stage("swatch", &mut c, &mut rng) {
        c.work(&swatch, &st.body().color(|_, _| hex("#808080")), 1);
    }
    o.end(&mut c, &mut rng);
    o.save(&mut c);
}

Section 12 explains Run, stages and what may go between them. Section 11 shows the optional finish (varnish, cracks, raking light), which replaces end and save with o.finish(..).

2. Canvas, ground and style

The physical surface

A Canvas holds a dry picture (color per pixel), a surface height field in µm (woven linen, ground layers and paint films), a wet paint layer on top and a clock. One coat of paint is COAT_UM = 25 µm of wet film.

Style

A Style is data: support, grounds, tools, a palette and handling presets. Style::friedrich() and Style::friedrich_early() are built from notes/research/friedrich_materials.md:

friedrich() friedrich_early()
width 440 mm 1714 mm
linen 15 × 13 threads/cm 12 × 11 threads/cm
grounds (bottom first) 110 µm knife, 70 µm knife, 60 µm brushed 110 µm knife, 70 µm knife, 30 µm rolled
palette Palette::friedrich_1820() Palette::friedrich_early()

Both share the tools: broad a filbert 22 units wide, body a filbert 9, detail a round sable 2.2, line a rigger 0.6 and a badger blender 40. relief is (0.06, 0.006), the strength and gloss for the finishing light. The fields are public, so a variant is a struct update:

let st = Style { width_mm: 600.0, ..Style::friedrich() };

st.prepare(width_px, aspect, seed) makes the linen at the style's size and primes each ground: Apply::Knife { texture } and Apply::Roller go through prime; Apply::Brush spreads the paste with a 40-unit hog in crossing strokes whose direction drifts, lays it off with the clean brush and dries it, so fine broken bristle striations stay in the top ground. aspect is width ÷ height.

Without a style: Canvas::new(width_px, aspect, raw_color) .with_size_mm(mm).with_linen(linen), then prime as many times as there are grounds. The default size is 700 mm.

3. Brushes and gestures

Tools

A Tool is a physical brush. Held is that brush in the hand: every bristle has its own reservoir (volume, pigment mix, scattering). As the handle moves:

Presets (width in units):

constructor kind character
Tool::round_sable(w) Round soft, little plowing
Tool::hog_flat(w) Flat stiff, square marks, strong ridges, broken edges
Tool::filbert(w) Filbert oval, soft-ended marks
Tool::fan(w) Fan sparse, spread bristles
Tool::rigger(w) Rigger a few long soft hairs, long load (run 250)
Tool::badger(w) Blender big, soft, lays nothing (lay 0)
Tool::stippler(w) Round short full tuft for touches

Fields: width, bristles, length (tip trail), stiffness (0 soft .. 1 hog), hair, run, lay (film laid at the start of a full stroke), pickup, push (plow), splay, ragged, point. Change one with a struct update: Tool { push: 0.02, ..Tool::filbert(9.0) }. Painting calls panic on a tool that Tool::validate rejects (non-finite fields, width ≤ 0, stiffness, pickup or push outside 0..1 and so on).

Pointed tips. Every preset has point: 0.0: the mark is as wide as the brush and pressure make it. point near 1 makes a cone of graded hairs: at light pressure only the point touches (a hairline), pressing spreads the belly, lifting draws the mark to a point, a loaded tip wets the weave's hollows (a continuous line) and a tip run dry splits.

let tool = Tool { point: 1.0, ..Tool::round_sable(1.6) };
let w = tool.mark_width(0.4);     // units at pressure 0.4
let p = tool.pressure_for(0.5);   // pressure for a 0.5-unit mark

Gestures and touches

use paint::{Gesture, Held, Orient, Paint, Tool, Touch, hex};

let mut b = Held::new(Tool::filbert(6.0), 3);          // seed: the brush's hairs
b.load(Paint::body(hex("#7a6a58")), 0.8);             // 0..1 of a full load
let g = Gesture::new(vec![(100.0, 200.0), (140.0, 190.0), (180.0, 205.0)])
    .pressure(0.7, 0.4)                                // start, end
    .ramps(0.1, 0.3)                                   // press-down, lift-off fractions
    .swell(vec![1.0, 1.2, 0.9])                        // pressure along the stroke
    .orient(Orient::Across)                            // or Along, Fixed(angle)
    .shake(1.0);                                       // 0 = mechanically exact
c.drag(&mut b, &g, None);                              // Some(&mask) clips
c.touch(&mut b, &Touch::at(300.0, 220.0).pressure(0.6).drag(0.3, 0.0).twist(0.2), None);
b.wipe(0.8);                                           // rag: remove 80 %
b.reload(Paint::body(hex("#c8c0b0")), 0.6);            // wipe clean and load

Hand frames. Hand::new(at, size, seed) sets a local frame (origin in units, units per local unit, v up) for writing a small group of gestures in its own coordinates: take(tool_fn, width, paint, load) returns a Held, line(c, &mut held, pts, p0, p1), dab(c, &mut held, u, v, len, dir, p) and mark(c, &mut held, Mark { .. }, clip) draw in local coordinates.

Drawn outlines. paint::outline::Outline::draw(pts, corners, closed, Character::firm(), seed, None) turns a few points into a hand-drawn line (wobble, facets or lobes, lifts, gaps, overshoots, restated stretches) and gives its mask(f), band(f, width, taper), below(f, bottom), above(f), gestures(pressure, shake) and paint(c, &mut held, pressure, clip). Characters: firm, searching, broken, soft (Character::named), scaled by .amount(k). Outline::body(&[Bone], ..) grows a silhouette from a skeleton of limbs with widths.

4. Handlings: covering a passage

c.work(&mask, &handling, seed) plans strokes over a region and paints them one by one through the bristle simulation. A Handling says which tool, how the strokes run and how the brush is loaded.

Planning

The knobs

builder meaning Handling::new default
length(a, b) stroke length range, units 30–90
coverage(c) stroke area ÷ region area; 0 disables the pass 2.0
angle(|x, y| ..), angle_jitter(sd) direction field 0, 0.08
curve(bow, wave) sagitta ÷ length (sd); share of S-curves 0.05, 0.25
cross(a) two families at ± a 0
drift(amount, scale) direction wander, radians over units 0.12, 300
tail(share), broken(share), swell(sd), clump(k) see above 0.12, 0.06, 0.15, 0.3
pressure(a, b) per-stroke range 0.6–0.9
ramps(attack, release) press-down and lift-off fractions 0.08, 0.15
orient(Orient) wide axis across, along or fixed Across
dips(every, load, wipe) strokes per palette trip, load, share wiped first 1, 0.64, 0.6
blender() clean brush, never loads off
scrub(n) short back-and-forth strokes 0
shake(k) hand unsteadiness 1
clip(on) stencil each bristle to the mask off
limit(Arc<Mask>) hard mask no bristle paints outside none
fence(Arc<Fence>) per-stroke overrun at the edge (section 9) none
cut_in(tool) body strokes stop short; the tool runs along the outline just inside none
load_at(|x, y| ..) multiplies the load at each stroke's center none
fill(on), hug(on), threshold(t) see above auto, on, 0.3

Color and paint: color(|x, y| rgb), color_over(|x, y, under| rgb), mixed(&palette, medium), palette(&p), medium(m), mix_jitter(sd), by_masstone(), aim(coats), aim_laid(), paint(hiding, stiff) and jitter(l, hue) (section 5).

Style presets

Each preset is a Handling with the style's tool, palette and medium. The presets choose stroke lengths, paths, pressure variation, placement and order; their fields are listed below and in section 4's table, and any of them can be set on the preset (angle, cross, order and the rest).

preset tool strokes coverage medium
st.broad() broad filbert 80–220, long arcs, drift 0.22 over 350 2.5 thin_medium 0.45
st.body() body filbert 20–60, more bowed and broken 2.5 body_medium 0.2
st.detail() round sable 4–14, clipped, threshold 0.1 3.0 0.1
st.hatch() round, 1.2 × detail width 5–12, nearly straight, clumped 2.5 0.15
st.glaze(medium) soft filbert 120–300, by masstone 2.5 as given
st.blend() badger (Option) 120–300, ± 0.2 crossing, clipped, swept top to bottom 3.0 none
st.scumble() body filbert scrub 3, 10–20 default 0.5

st.line_tool(width) is the style's rigger at another width.

use std::f32::consts::FRAC_PI_2;
c.work(&region, &st.broad().color(field).angle(|_, _| 0.1).coverage(3.0), 11);
c.work(&region, &st.blend().unwrap().clip(false), 12);          // fuse across the mask's edge
c.work(&region, &st.body().color(field).cross(0.3).fill(false), 13);
c.work(&region, &st.broad().color(field).sweep(FRAC_PI_2), 14);

work_with(&mut piles, ..) does the same as work but dips into a shared tally::Piles (section 8).

5. Palette, color and aiming

What a color means

Paint constructors: Paint::new(masstone, hiding, stiff), Paint::body(c) (0.92, stiff 1), Paint::scumble(c) (0.5, 0.6), Paint::km(c, scatter, stiff), Paint::tint(tint, hiding, stiff) and Paint::glaze(tint) (named by the look of one coat over white), Paint::aimed(want, under, coats, hiding, stiff). Modifiers: with_hiding, with_stiff, with_drying. p.over(under, coats) is how coats of it look over under.

The palette

A Palette is a set of Tubes (name, masstone color, hiding, stiff, tinting strength). Every pile is mixed from at most three tubes.

Calls:

let m = pal.mix(want);                            // masstone nearest `want` (OKLab)
let m = pal.aim(want, under, medium, coats);      // look nearest `want` laid over `under`
let p: Paint = m.paint(medium);                   // thinned, ready to load
let p = pal.paint(want, medium);                  // mix + thin
let p = pal.paint_for(want, under, medium, coats);
let p = c.aim(&pal, want, (x, y), r, medium, coats); // judged on the canvas at (x, y)
println!("{}", pal.recipe(&m));                   // "lead white 0.72 + ..."

Mixture::error is the OKLab miss. A target out of reach comes out as the nearest pile the tubes make: a transparent glaze can't lighten a dark; a scattering paint (lead white, ochre) thinned with medium can.

Aiming: masstone versus the look on the canvas

A handling with mixed(&pal, medium) treats its color field as the look wanted on the canvas (Aim::Laid). For each stroke it samples what is under the stroke before the pass (nine discs along the path, weighted toward the loaded start, combined by a median per OKLab channel) and picks the pile whose mark will look like the color there when laid as thick as this handling lays paint. That thickness is Handling::laid_coats(): 1.3 coats per unit of load for filberts, flats, fans and blenders, 4.0 for rounds and riggers, times the mean overlap c / (1 − e^−c) at coverage c, clamped to 0.2–8. The pile is scored by the mean look over a spread of thicknesses (a pointed brush lays a thick core and thin edges), with costs that keep its thin edge on the way from the underlayer to the target, keep its masstone in the target's hue family and add a small cost per tube.

Aim results are cached by quantized target, underlayer, thickness and medium, and computed from the key, so they don't depend on call order. Palette::remix gives a jittered copy of a mixture.

6. Stipple

c.stipple(&mask, &Stipple, seed) covers a region with touches of a tip (each a Touch through the bristles). Tone comes from how densely touches fall and their color; the marks have no direction.

use paint::{Stipple, Tool, hex};
let s = Stipple::new(Tool::stippler(2.0))
    .mixed(&pal, 0.5)
    .color(|_, _| hex("#b8b4a8"))
    .coverage(|_, y| 1.5 * (y / 400.0).min(1.0))   // touches per point
    .pressure(0.4, 0.75)
    .dips(24, 0.5, 0.5);
c.stipple(&region, &s, 21);

7. Glazes and veils

Two ways to lay a thin transparent layer.

Canvas::glaze(&pigment, mask, |x, y| coats) lays a film of pigment, coats deep (times the mask), over the whole dry picture in one step. It first dries every wet film on the canvas (it calls dry()). The film is mostly medium: 0.3 coat of film per coat of color depth. It levels and pools in the hollows of the surface, so it is deeper there, and it dries at once. A request thinner than 0.05 µm of film fades out smoothly, so a long falloff ends without an edge.

Pigments for glazes are named by the look of one unit layer over white: Pigment::transparent(c) (hiding 0.06), Pigment::semi(c) (0.45), Pigment::opaque(c) (0.92), Pigment::varnish(c) (0.004, absorbs only), Pigment::with_hiding(c, h), Pigment::from_appearance(on_white, on_black). Pigment::masstone(r, s) and masstone_hiding(r, h) name one by masstone. pig.over(under, coats) previews it.

c.glaze(&Pigment::transparent(hex("#6a5030")), Some(&region), |x, _| 0.2 + 0.6 * (x / 1000.0));

A brushed glaze or scumble is wet paint: st.glaze(medium) is a soft filbert laying paint that is mostly medium (≈ 0.85–0.95 for a transparent glaze, ≈ 0.6 for a veiling scumble) in long strokes, mixed by masstone. Vary its depth with load_at and fuse it with st.blend(); it dries with the clock like any paint.

let g = st.glaze(0.9).color(|_, _| hex("#5a4632")).load_at(|x, _| 0.5 + 0.5 * (x / 1000.0));
c.work(&region, &g, 31);

8. Drying and time

The canvas has a clock in minutes. Oil paint dries by oxidation, and each pixel's open film carries its own cure (0 fresh, 0.15 the gel point, 1 touch-dry). What a brush feels depends on the stage (paint::Stage):

stage cure what brushes do
Open < 0.075 blends, lifts, plows, levels
Setting 0.075–0.15 lift and plow fall with fluidity; marks stop leveling
Tacky set film doesn't flow, mix or lift; grabs the brush: deposit up to 3× faster, in stick-slip patches
Dry ≥ 1 new paint sits on top without mixing

Calls:

c.wait(0.0);          // nothing passes: keep working wet into wet
c.wait(30.0);         // half an hour
c.wait(180.0);
c.wait(24.0 * 60.0);  // a day
c.dry();              // until every film is touch-dry
let t = c.clock();    // minutes (f64)
let s = c.drying_at(x, y);      // Stage at a point
let shares = c.stage_shares();  // [open, setting, tacky, dry] over the kept pixels
let um = c.wet_um(x, y);        // wet film at a point, µm

A negative wait counts as 0 and an infinite one is dry(). The clock doesn't start at 0: Style::prepare dries its grounds, so read c.clock() and count from there. A program that never waits works wet into wet until something dries it: dry, glaze, prime, relief and save all dry the canvas first.

Hand time

Every planned stroke, touch, palette trip and wipe is priced in seconds of hand time and counted in a ledger (c.tally(): strokes, touches, path length in mm, reloads, piles mixed, wipes, pencil lines, seconds). The prices come from Fitts's law for moving to the next mark, the steering law for drawing it (paint::tally::pace), 2.5 s per reload, 20 s per new pile and 2 s per wipe. The ledger never changes what is painted.

With c.set_hand_time(Some(slice_min)) the paint ages while the hand works: work and stipple paint in slices of about slice_min minutes of hand time with a wait between them, and the default order becomes a sweep down. The last slice of each pass stays owed; c.clock_hand_min() puts what is owed on the clock (c.hand_owed_secs() reports it). None (the default) keeps marks off the clock.

tally::Piles is the palette's piles: a dip within 0.035 OKLab of a pile is a reload, anything else a new pile, 16 at most. work_with and stipple_with share one Piles across passes; work and stipple start a clean one.

9. Masks, forms and scene helpers

Masks

A Mask is float coverage the size of the whole canvas, built on c.frame() (a mask of another size panics when painted with).

let f = c.frame();
let m = Mask::from_fn(f, |x, y| if y > 0.4 * x + 200.0 { 1.0 } else { 0.0 });
let s = Mask::from_shape(f, Shape::new().ellipse(500.0, 300.0, 120.0, 80.0));
let soft = s.clone().blur(3.0);                        // radius, units
let rough = s.clone().roughen(7, 25.0, 3.0, 1.5);     // seed, period, amount, edge (units)
let both = m.clone().union(&s);                        // max
let cut = m.clone().subtract(&s);                      // m × (1 − s)
let ring = s.rim(6.0, 2.0);                            // inside, within 6 units of the edge
let grown = s.offset(4.0);                             // dilate(d), erode(d)
let dist = s.distance();                               // signed distance, units (+ inside)
let band = dist.band(2.0, 10.0, 1.0);                  // 1 between two levels of a field
let edge = s.soften(|x, _| if x < 500.0 { 0.0 } else { 6.0 }); // edge ramp width by place

Also map, mul, mul_fn, invert, sample(x, y) and Mask::full / Mask::empty. Shape builds paths in units (move_to, line_to, quad_to, cubic_to, rect, ellipse, circle, poly, smooth_poly, below(curve, bottom), ribbon(pts, widths), add).

f.per_column(|x| ..) tabulates a function of x once per pixel column and returns a Copy reference, so a mask closure that calls it per pixel evaluates it once per column. Fbm is Copy too; both go into any number of move closures.

paint::edge::contours(&mask, step) traces the mask's 0.5 line into polylines with inward normals.

Edges: clip, fence, limit

use paint::fence::{Fence, stretches};
use std::sync::Arc;
let q = stretches(&region, (0.3, 0.5, 0.2), 60.0, 20.0, 5);
let fence = Arc::new(Fence::new(&region, &q, 9.0, 1.0, 1.0, 5));
c.work(&region, &st.body().color(field).fence(fence), 41);

Noise

paint::noise: Fbm::new(seed, octaves, period) (get ≈ −1..1, get01), Octaves::{new, ridged, billow} in 2-D and 3-D with level of detail, Warp::new(seed, period, amount) (domain warping), Aniso::new(angle, stretch), Worley::new(seed, period) (cells: f1, f2, edge(), id), uneven(n, lo, hi, irregular, clump, seed) (positions with unequal gaps), vary(v, amount, i, seed) and rand01(i, j, seed).

Form: a lit depth buffer

Form holds, for every pixel of the whole canvas, the nearest solid, its depth z (units toward the eye), normal, part id, facet id and a distance for aerial perspective. It paints nothing; it gives fields and masks.

use paint::{Form, Light, Sdf};
let mut form = Form::new(c.frame());
let body = Sdf::block([500.0, 400.0, 0.0], [200.0, 120.0, 150.0], 10.0)  // center, whole size, rounding
    .turn([500.0, 400.0, 0.0], 0.4, 0.2, 0.0)                              // yaw, pitch, roll
    .cut([560.0, 360.0, 60.0], [1.0, -0.5, 0.6], 7, 2.0)                   // plane, facet id, rounding
    .rough(3.0, 50.0, 9, false);
let part = form.add(&body, 10.0);                                          // distance for aerial perspective
form.light(Light::new((-1.0, -0.6), 0.4).ambient(0.15).penumbra(0.06));
let lit = form.mask(|s| if s.part == part { s.shade.lit(0.2) } else { 0.0 });
let edges = form.edges(0.5, 4.0, 3.0);                                     // plane breaks and overlaps
let dir = |x: f32, y: f32| form.fall(x, y);                                // down the planes

Scene: one camera, one sun

paint::scene places solids on a ground under one sun, so they share light, scale and shadows. World coordinates are meters: X right, Y up, Z away; the eye is at (0, eye, 0) looking level, so the horizon is the eye level line.

use paint::{Sdf, Sun, Water, World};
let h = c.height();
let mut w = World::new([0.0, 0.0, 1000.0, h], 0.55 * h, 1.6)   // view [x, y, w, h], horizon y, eye m
    .sun(Sun::deg(-40.0, 25.0))                                  // azimuth from straight ahead, elevation
    .water(Water::new(-0.3).ripple(0.02, 3.0, 1.5, 4));
let spot = w.spot(420.0, 0.8 * h).unwrap();                     // the ground seen at a canvas point
let id = w.place(spot, Sdf::ellipsoid(spot.p(0.0, 0.6, 0.0), spot.size(1.2, 0.6, 1.0)));
let view = w.view(c.frame());
let (ground, shadows, contact) = (view.land(), view.shadows(), view.contact(0.1));
let reflected = view.reflections(&[id]);

10. Pencil

paint::graphite draws on the ground before paint. A point is dragged over the tooth: it rides on the local tops of the surface and pressure lets it bite into the hollows, so a light line breaks up in the weave and a heavy one fills in. The deposit covers a share of each pixel with flakes of a given reflectance and goes into the dry picture, so later paint composites over it by KM: a thin layer lets it show, body color hides it. Wet paint doesn't take graphite.

use paint::{Lead, graphite};
let lead = Lead::pencil("2H").unwrap();
let mark = graphite::hand_line(&[(120.0, 400.0), (420.0, 380.0), (760.0, 410.0)], &[0.3, 0.5, 0.35], true, false, 0.2, 7);
let mut worn = 0.0;
worn += c.draw(&lead, &mark, worn, 7);
let lines = c.drawing_guide().band(0.7, 1.0, 0.1);

11. Finish (optional): varnish, cracks, relief

o.finish(&mut c, &mut keep, &finish) ends the last stage, dries the canvas, then applies a Finish:

Finish::aged(st.relief) is varnish #e6d3a4 at 0.4 ± 0.12 coats, Cracks::aged and the style's relief. Every field is public:

let fin = Finish { cracks: None, varnish_coats: 0.2, ..Finish::aged(st.relief) };
o.finish(&mut c, &mut rng, &fin);

Without a finish, a program ends as in section 1: o.end(&mut c, &mut rng);, optionally c.relief(..), then o.save(&mut c);.

12. The stage runner, crops and checkpoints

Run

Run::new(name) reads the command line: --full (2400 px wide; output and checkpoints named <name>_full), --width N (overrides the width), --seed N (default 1), --out path, --crop, --margin, --stop, --ckpt, --resume, --stale-ok, --no-cracks. Call it from the painting's own file: it reads that file's stage names. o.width, o.seed and o.crop are public.

Rules:

Commands

All runs of one painting use the same --full, --width, --seed and crop, since outputs and checkpoints are tied to them.

cargo paint <name> -- --full                                # 2400 px → out/<name>_full.png
cargo paint <name> -- --full --width 2400                   # the same
cargo paint <name> -- --full --stop <stage>                 # save right after a stage
cargo paint <name> -- --full --ckpt                         # checkpoint after every stage
cargo paint <name> -- --full --resume <stage>               # start after that stage
cargo paint <name> -- --full --resume <s> --stop <s>        # the checkpoint as an image
cargo paint <name> -- --full --resume <s> --stale-ok --ckpt
cargo paint <name> -- --full --crop x0,y0,x1,y1             # → out/<name>_full_crop.png
cargo paint <name> -- --full --crop x0,y0,x1,y1 --margin 80 --ckpt
cargo paint <name> -- --full --no-cracks

--stop saves the canvas as it is after that stage; saving dries the wet paint first, and no finish is applied.

Crops

--crop x0,y0,x1,y1 (units of the whole canvas) paints only that window, at the run's resolution, plus a margin (default 40 units, --margin) that is painted but not saved: it gives leveling, the brushes' feel of the surface and strokes entering the window their context. The program doesn't change: c.frame() is still the whole canvas; masks and forms are still whole-canvas; strokes are planned over the whole canvas with the same random draws; tiles that miss the window are skipped. c.window() is the pixels held; in a crop, sample, pixels, under and the aim see only those.

The linen and grounds laid with prime match a whole render exactly. Brushwork, a brushed ground included, matches closely: outside the window there is no canvas for a brush to feel, so the paint it lays and picks up there is estimated, and it enters the window about as loaded as in a whole render. The difference falls as the margin grows and is largest for long strokes. The look-and-fill dabs see only the pixels the crop holds.

A crop's checkpoints are its own (out/<name>_full_crop.<stage>.ckpt), and a crop resumes only from a checkpoint made with the same crop and margin.

Checkpoints

--ckpt writes out/<stem>.<stage>.ckpt after each stage (stem <name>_full or <name>_full_crop with --full; spaces and slashes in the stage name become _). A checkpoint holds the whole canvas state after its stage: dry picture, surface, film, linen, size, the wet layer, stroke ids, clock and drying state, the drawing, the hand-time ledger, plus the keep state, width, seed, crop and fingerprints of the code. A resume from it is exact: it paints bit for bit what an uninterrupted run paints.

--resume <stage> refuses a checkpoint whose width, seed, crop or name differs, and refuses a stale one. A checkpoint is stale when any of this changed since it was saved:

Code after the block, between it and the next stage, is setup for later stages and doesn't count. Setup that has to sit higher (a constant at the top) can be tagged: a line ending in // ckpt: from <stage>, or the lines between // ckpt: from <stage> and // ckpt: end, count only for that stage and later ones. A tag naming no stage is an error. A tag is taken on trust: a tagged value that an earlier stage does read leaves that stage's checkpoint looking fresh.

--stale-ok uses a stale checkpoint anyway; with --ckpt it also rewrites the checkpoint's fingerprints for the current code, so the next resume needs no flag.

13. Viewing renders

Canvas texture makes PNGs large (a 2400 px render is several MB). View them through scripts/peek, which writes a JPEG at most 1000 px on a side (quality 95, full-resolution color), optionally cropping first.

scripts/peek out/<name>_full.png $TMPDIR/view.jpg                     # whole image
scripts/peek out/<name>_full.png $TMPDIR/detail.jpg 600 900 300 1200  # height width y-offset x-offset, px

Crop offsets are pixels of the PNG: at 2400 px wide, units × 2.4. A --crop render (out/<name>_full_crop.png) holds only the window, at full resolution, so it can be peeked whole.

14. What is slow

Measured at 2400 px on a 12-core machine under other load (Style::friedrich(), aspect 1.4 unless noted):

step time
st.prepare (linen, two knifed grounds, brushed top ground) 39 s
broad() over 30 % of the canvas 7 s
blend() over the same region 16 s
body() over 70 % of the canvas 3 s
detail() or hatch() over 200 × 200 units 0.5–0.9 s
stipple over 30 % at coverage 1.5 1.1 s
wait, dry, glaze 0.05–0.2 s each
one Form body, lit 0.1 s
varnish, cracks and relief 0.5 s
checkpoint, whole canvas 2400 × 1500 274 MB, 0.1 s to write

The fast loop for a detail: render its window with --crop and --ckpt once, then iterate on the late stages with --resume <stage> and the same crop.

Source