What the painters were given

The easel

crates/easel/README.md · 1,438 lines · Guide

Given to 5 painters:

The easel

A live painting session for agents. The canvas stays alive in a background process; you send it Lua 5.5 chunks one shell command at a time, look at the result as a small JPEG and carry on. Every chunk that succeeds is appended to paintings/lua/<name>.lua. That file is the painting: easel run repaints it from scratch, byte for byte the same at the same width, or at 3200px for the full render.

The engine underneath is the claude-paint oil-paint simulator (see the repository README): every mark is made by simulated bristles carrying paint, and layers combine by Kubelka–Munk optics. The easel paints nothing on its own. You choose the motifs, colors, brushes and order.

Quick start

cargo build --release -p easel          # once; the binary is target/release/easel
E=target/release/easel

$E open dusk                            # start a session (1000px wide by default)
$E do 'canvas{style="friedrich", aspect=1.4, seed=7}'
$E do --look '
HZ = 470
sky = function(x, y) return gradient({{0,"#5d7396"},{0.6,"#9fabb8"},{1,"#e9d6a6"}}, y/HZ) end
work(above(function(x) return HZ + 15 end), {hand="broad", color=sky, angle=0, coverage=4.5})'
# prints: ok · chunk 2 · 5.98s · ... and the path of a JPEG: read it
$E look --mode value,squint             # judge the values
$E undo                                 # didn't like it
$E close                                # the session stays in paintings/lua/dusk.lua
$E run paintings/lua/dusk.lua --width 3200    # the full render → out/lua/dusk_3200.png

paintings/lua/example.lua is a whole small study made this way: an evening sky, a distant ridge, mist and a spruce on a knoll, in ten chunks. paintings/lua/rocks.lua models a boulder and a mountain range as solids and paints them from their light and shadow. paintings/lua/meadow.lua is a daylight landscape built on a world: a sky and clouds for its sun, hazed ranges, a beech in leaf casting its shadow and a meadow of grass tufts. Read all three before you start.

The loop

  1. Open. easel open <name> [--width 1000] [--undo 8] starts a background session, or reattaches if it's already running. If paintings/lua/<name>.lua exists, the session replays it first, so you can close, come back and go on painting. Other commands use the session you opened last in this checkout (or -s <name>, or EASEL_SESSION). The checkout is the nearest directory at or above where you run easel that holds crates/easel (or EASEL_ROOT): logs go to its paintings/lua, renders to its out/, so git worktrees stay apart. With several painters on one machine, still name your session (-s <name>).

  2. Paint a chunk. easel do '<lua>', easel do -f chunk.lua or easel do - (stdin). The reply is whatever the chunk printed, then ok · chunk N · seconds · clock · sitting · how much is open, setting, tacky and dry. Add --look to also get a look in the same command.

  3. Look. easel look prints the path of a ≤1000px JPEG (100–250 KB):

    • --crop x0,y0,x1,y1 a window in canvas units, enlarged by whole pixels so you see the real grain;
    • --mode value (grayscale), squint (blurred: big shapes and values only), mirror (flipped: fresh eyes on the drawing), wet (where the paint is in drying: open blue, setting green, tacky orange, dry gray, over the picture dimmed); comma-separate to combine, e.g. --mode value,squint;
    • --dried (alias --wet): wet paint as it will look once it has leveled and dried; --relief also lights the brushwork from the upper left; --size N for the longest side;
    • --grid, --probe x,y, --show and --scale 3.2 help you place marks by eye (next section).

    The plain look shows what is on the canvas now: the dry picture with wet paint on it as laid.

  4. Keep or undo. A chunk that fails changes nothing: the canvas, your variables (including anything it changed inside tables and closures from earlier chunks), the paint in your brushes and the clock go back to how they were before it, and it isn't logged. This holds at any --undo, including --undo 0. easel undo [n] takes back the last n successful chunks: instantly within --undo (8 by default; each snapshot costs about 50 MB at 1000px), further back by replaying from a checkpoint. The code of undone chunks is kept (easel undone).

  5. Step back. easel log prints the program so far. easel status gives a one-line summary (with the clock, the sitting and the drying stages). easel save [path] writes a PNG. easel check replays the log in a fresh session and confirms it matches the live canvas exactly.

  6. Fix an early chunk in place. easel show N prints chunk N's code. easel edit N -f chunk.lua (or '<lua>', or - for stdin) replaces chunk N and replays every chunk after it, without closing the session. See Editing a chunk.

  7. Time-lapse. easel frames on saves a JPEG after every chunk in out/easel/<name>/frames/.

Looking by eye

You place every mark by coordinates, so read them off the picture instead of estimating them from a JPEG, and see where a shape will land before you paint it.

$E look --grid                      # labeled grid in canvas units (step picked from the zoom)
$E look --crop 560,480,720,600 --grid 10     # zoomed in: a 10-unit grid, labels at the edges
$E look --probe "412,380;300,520"   # what is there: numbered crosses on the image, and per point
# probe 2 (300, 520): #5a593c · OKLab L 0.458 a -0.013 b +0.043 · open, wet 88 µm · v: ground, 20.6 m away at X -3.9 Y -0.0 Z 20.7 m
$E try '                            # run a chunk, see its overlay, roll it back (not logged)
sheep = {{612,560},{640,548},{668,552},{680,566},{660,578},{626,578}}
show(sheep, {closed=true, label="sheep"})'
$E look                             # the polygon, its numbered vertices and the label over the canvas
$E look --crop 560,500,720,610 --scale 3.2   # that window as it looks at 3200 px

How chunks behave

API reference

Canvas and palette

canvas{style="friedrich", aspect=1.4, seed=7}   -- the first chunk; returns H
-- styles: "friedrich" (after 1820), "friedrich_early". Sets W, H and pal.
canvas{style="friedrich", palette="friedrich_1820_greens", aspect=1.5, seed=11}
canvas{style="friedrich_early", size=440, aspect=1.4, seed=11}   -- size: the width in mm
-- (the style's by default: 440 after 1820, 1714 for the early grounds). Pencil
-- lines are fractions of a mm, so they read at 1000px on a small canvas.
-- palettes: friedrich_1820, friedrich_early, and the same with _greens (adds
-- Prussian blue, green earth and, after 1820, Rinmann's green) for summer
palette("friedrich_early_greens")            -- any palette by name
pal:with{"copper green"}                     -- a rare tube for one passage
print(pal)                                   -- the tubes
pal:tubes()                                  -- list of tube names
local blues = pal:only{"lead white", "pale smalt", "cobalt blue"}
local c, recipe, err = pal:mix("#6f84a8")    -- nearest masstone the tubes reach
local c2 = pal:aim("#9fb0c0", sample(500, 200), 0.3, 1.0)  -- want, over, medium, coats
local p = pal:paint("#445566", 0.2)          -- a Paint (color, medium)
paint("#445566", {raw=true, hiding=0.5, stiff=0.3})        -- a paint not mixed from tubes

Colors and helpers

mix("#334455", "#887766", t, "light")        -- modes: "light" (OKLab, default), "pigment", "linear"
gradient({{0, "#5d7396"}, {0.6, "#9fabb8"}, {1, "#e9d6a6"}}, t)
rgb(120, 130, 140)   color("#aabbcc")
smoothstep(a, b, x)  lerp(a, b, t)  clamp(x, lo, hi)
n = noise{seed=3, octaves=5, period=260, persistence=0.5}
n(x, y)              -- about -1..1        n:at01(x, y)  -- 0..1
sample(x, y, r)      -- what's on the canvas there (wet paint included)
shift(c, dL, da, db) -- the same color moved in OKLab: shift(c, -0.06, 0, -0.02) is darker, bluer

Noise and irregularity

noise{kind="ridged", seed=3, period=120}        -- kinds: fbm (default), ridged (crests), billow (heaps)
noise{period=200, warp={80, 25}}                -- domain warp: {period, amount, twice?}: folds, wisps
noise{period=150, stretch={0.2, 4}}             -- stretched 4x along angle 0.2: wind, bedding
cells = worley{seed=2, period=30}               -- cells: stones, cracked mud, clumps
local f1, f2, edge, r = cells:at(x, y)          -- edge is 0 on a cell wall; r is 0..1 per cell
uneven(9, 120, 860, 0.6, 0.4, 5)                -- 9 positions from 120 to 860, spaced by hand:
                                                -- irregular gaps, clumped (posts, trees, boats)

A noise can be passed straight to coverage= or load_at= (as 0..1).

Masks

Masks are coverage maps of the whole canvas. Operations return new masks.

everywhere()
mask(function(x, y) return y < 300 and 1 or 0 end)    -- any function, 0..1
ellipse(cx, cy, rx, ry)   rect(x, y, w, h)
poly({{x, y}, ...})       poly(pts, true)              -- true: smoothed
below(function(x) return 420 + 20*math.sin(x/90) end)  -- under a curve (or a point list)
above(curve)                                           -- over it
ribbon(points, widths)    ribbon(points, 3)            -- a band along a line
m + n   m * n   m - n   -m                             -- union, intersect, subtract, invert
m:roughen(units, period, seed, edge)  -- push the edge in and out by about `units`
                                      -- (noise of `period` units), new edge `edge` units soft
m:soften(units)   m:blur(units)
m:grow(units)     m:shrink(units)   m:offset(units)
m:rim(width, soft)                -- the inside strip along the edge
m:distance()                      -- signed distance in units (+ inside): a field
m:band(lo, hi, soft)              -- turn a field back into a mask
m:times(fn or mask)  m:map(function(v) return v^2 end)
m:at(x, y)   m:area()

Points are {{x, y}, {x, y}, ...} or a flat {x1, y1, x2, y2, ...}.

The hand: brushes and strokes

b = brush("round", 3)        -- kinds: round, flat, filbert, fan, rigger, badger, stippler
b = brush{kind="filbert", width=8, stiffness=0.5}      -- also: length, hair, run, lay,
                                                       -- pickup, push, splay, ragged, bristles
b:load("#2a3040", 0.9)       -- mix it from pal (masstone) and dip: amount 0..1 of a full load
b:load("#9fb0c0", 0.6, {at={500, 300}, coats=0.8})     -- aim at the look over what's there
b:load(color, 0.8, {medium=0.4, pal=blues})
b:reload(color, amount)      -- wipe most of the old paint, then load
b:wipe(0.85)                 -- on the rag
b:fullness()                 -- paint left, 0..1
b:stroke({{100, 500}, {300, 520}, {500, 510}},
  {pressure={0.9, 0.3}, ramps={0.05, 0.4}, orient="across", shake=1, swell={1, 1.3, 0.8}, clip=m})
b:touch(x, y, {pressure=0.6, drag={1, 0}, twist=0.2, angle=0.3, clip=m})
b:mark_width(0.4)            -- width of a mark at this pressure
b:pressure_for(0.5)          -- the pressure for a 0.5-unit line
brush{kind="round", width=3, point=1}                  -- a pointed tip (0 = blunt, default; 0.5 a soft point)

Every brush is blunt unless you give it a point: a round or a rigger lays about the width you asked for at any pressure. A pointed tip (point=1) is a cone of hairs: at light pressure only the point touches (a hairline), pressed it spreads to the belly, so its width follows the pressure and a stroke draws down to a point on the lift. With a pointed brush, a flick that ends in a hairline is a stroke whose pressure falls to 0: b:stroke({root, mid, tip}, {pressure={0.75, 0}, ramps={0.1, 0.75}}).

A brush keeps its paint across strokes and chunks: several strokes from one load run dry naturally. orient is "across", "along" or a fixed angle.

Drawing: pencil, chalk and eraser

Draw the composition on the ground before you paint, the way Friedrich did: graphite pencils of different hardness and black chalk, often a faint first pass and then a bolder one, the straights against a ruler. The drawing lies in the picture under the paint: thin paint lets it show through (as in his early works), and body color hides it.

h = pencil("2H")                  -- or pencil{grade="2H"}: 9H..H, F, HB, B..9B
b = pencil{grade="2B"}
c = chalk()                       -- black chalk: deep, matte, broad, crumbly
h:sketch(pts, {pressure=0.3})     -- a searching line: a few light passes, each its own guess
                                  -- (passes=3, wander= units, smooth=true)
b:line(pts, {pressure={0.5, 0.7, 0.4}})   -- one firm line through the points (smooth=false keeps corners)
h:rule({0, 432}, {1000, 432}, {pressure=0.3})   -- straight, against a ruler
b:hatch(mask, {angle=-1.1, pressure=0.35})     -- short parallel strokes (spacing=, length= in units)
b:width()   b.worn   b:sharpen()  -- the point blunts as you draw (soft leads fast); lines widen
erase(pts, {strength=0.9, width=9}) -- a kneaded eraser along a path, or erase(mask, {strength=})
fix()                             -- fixative (or fix(mask)): the eraser no longer lifts it
drawing_mask()                    -- where the graphite is (grainy, as laid), 1 on a firm line, also under paint
drawing_guide()                   -- the drawn lines themselves (continuous, whole canvas even in crops):
                                  -- paint INTO your drawing with this, e.g. drawing_guide():band(0.7, 1, 0.1)

How it behaves: the point rides on the tops of the canvas weave, and pressure lets it reach into the hollows, so a light line is a broken line of grain and a heavy one fills in. Soft leads lay darker, glossier gray; hard ones lay a pale silver gray. Graphite doesn't take on wet paint. The eraser lifts most of a line, and better from the tops than the hollows. A ghost stays behind, as on a real canvas. Once paint has gone over the drawing, it is sealed. Look at the drawing with look --crop (it is fine work).

A worked example (from paintings/lua/pencil.lua):

h2 = pencil("2H")                                  -- first pass: light and searching
h2:rule({0, 432}, {1000, 432}, {pressure=0.3})
h2:sketch(ROCK, {pressure=0.3})
b = pencil("2B")                                   -- second pass: firm (the top came out too high)
b:line(WRONG, {pressure={0.55, 0.7, 0.6, 0.5}})
-- next chunk, after a look: lift the wrong top and redraw it
erase(top_of_wrong, {strength=0.9, width=9})
b:line(ROCK, {pressure={0.55, 0.7, 0.6, 0.5}, smooth=false})
b:hatch(poly(shadow_side), {angle=-1.1, pressure=0.35})
fix()
-- thin, translucent paint, blended: the drawing shimmers through
work(rock * LEFT, {hand="body", color="#8d8a80", medium=0.6, load=0.3, coverage=2.2, paint={0.3, 0.3}, clip=LEFT})
blend(LEFT, {angle=0.04, clip=LEFT})
-- body color hides it; paint the next thing into the hidden drawing
work(rock * RIGHT, {hand="body", color="#8d8a80", medium=0.15, load=0.9, coverage=4, clip=RIGHT})
dry()
local firm = drawing_guide():band(0.7, 1, 0.1):grow(1.2) * rect(660, 290, 240, 190)
work(firm, {hand="detail", tool="round 2", color="#3b342c", coverage=3, length={4, 10}})

Drawing: outlines and bodies

Place a few rough points and let a hand draw the line: a smooth curve through them, broken at corners, with a hand's irregularity (a slow wobble, lifts and overlaps, overshoots at corners, pressure that swells and thins). The same line is the mask's edge and the path a brush follows.

-- seven points; "c" marks a corner (or corners={3,5}, or leave it to the angle)
rock = outline{{300,600,"c"}, {312,524}, {354,458,"c"}, {424,446}, {490,424,"c"}, {560,504,"c"}, {572,600,"c"},
               char="broken", seed=3}
m = rock:mask()                        -- its inside, edged by the drawn line
work(m, {hand="body", color=..., clip=m})
rim = m - rock:inset(7):mask()         -- a strip just inside the edge (light, a cut-in)
b = brush{kind="round", width=4}; b:load("#2e2b26", 0.9)
rock:paint(b, {pressure=1, dip={"#2e2b26", 0.8}, every=4})   -- draw the contour

-- a sheep from five spine points (rump, back, shoulder, poll, nose) and four legs
sheep = body_of{spine={{100,500}, {109,499}, {119,499}, {125,503}, {127,507}}, widths={8,10,8.5,3.6,2.4},
                limbs={{{103,502}, {102,508}, widths={1.3,0.9}}, ...}, char="soft"}
char the hand
firm (default for outline) a sure contour: long strokes, slight overshoots, crisp mask
searching a sketch: short strokes restated a little off each other, running past corners
broken rock, bark: straight facets and chips, in broken stretches between quiet ones
soft (default for body_of) foliage, wool, a far wood: lobes of two sizes, light broken strokes, a mask edge lost in places

outline{pts... or pts=, char=, seed=, closed=, open=true, corners=, corner_angle=60, size=, amount=, lobe=, edge=}: closed is the default with three or more points; amount scales the irregularity, lobes set with lobe= included (0 = a clean curve, whatever else is set); lobe sets the lobe width in units (a tree line: lobe=24); edge the mask's soft edge in units (0 = crisp); size the scale the hand works at (default: from the points' extent). An open line's outside is on its left (up, for a line drawn left to right): lobes and chips go that way.

body_of{spine=, widths=, limbs={{pts..., widths=} or {pts..., width=}}, blend=0.8, char=, ...}: the silhouette of a skeleton (widths are full widths). Limbs join the spine smoothly over blend times their width; a limb that starts outside the spine reaches into it. Lobes and chips shrink where the body is thin.

Methods: o:mask() (closed; an outline with no line left, such as an inset deeper than the shape, gives an empty mask, so m - o:inset(d):mask() keeps the whole shape), o:below(bottom), o:above() (open lines), o:band(width, taper) (a band along the line; taper 1 follows the pressure), o:inset(d), o:offset(d) (a parallel outline, redrawn by the same hand), o:paint(brush, {pressure=1, shake=0.3, ramps=, clip=, dip={color, amount}, every=3}) (returns the stroke count), o:path(i) and o:paths() (the drawn line as {{x, y}, ...}), o:strokes() ({{pts=, pressure=}, ...}: how the hand drew it, for any tool), o:at(t) (x, y, tangent, outward normal at a fraction of the length), o:length(), o:corners(), o.scale. A pinna of three points, a rachis of three, a sheep of five: paintings/lua/outline.lua draws them all.

Covering areas

work(mask, {hand="body", color=..., angle=0, ...})

hand picks a preset from the style, which you then adjust: broad (long soft passes: skies, fog, water), body (form in body color, the default), detail (small, cut in), hatch (short strokes side by side: conifers, grass), glaze (thin veils; medium 0.6–0.95), scumble, blend (a clean blender fusing wet paint). Options:

option meaning
color a color, function(x, y) returning one, or a sky or clouds (color=s): the look you want on the canvas
color_over instead of color: relative to what's under each stroke. {shift={dL, da, db}} (e.g. a shadow: {shift={-0.06, 0, -0.012}}), or function(x, y, under) sampled every 2 units with under = the canvas there before the pass
hug true (default): strokes reach a mask's edges; false lets edges thin out
clip true: every bristle stops exactly on the region's edge (a stencil: one crisp, even line). It is true or false: a mask given here counts as true and is not used (the reply says so)
edge instead of clip: carry the passage to the region's edge as a brush does, found, soft or lost (see Edges)
angle stroke direction, a number or function(x, y)
tool "filbert 8", {kind=, width=} or a brush
length {min, max} stroke length in units
coverage layers of strokes over each point (2–5)
medium oil medium in the paint, 0..1 (thin 0.25, body 0.15)
pal a palette (e.g. pal:only{...}), or false for unmixed paint
aim "laid" (default: aim at the look over what's there), "masstone", or a number of coats
pressure, ramps {start, end} pressure; attack and release fractions
dips {every, load, wipe}: strokes per trip to the palette
load, load_at load per dip; a field that varies it
angle_jitter, curve ({bow, wave}), cross, drift ({amount, scale}), tail, broken, swell, clump the hand's irregularity
order "passages", "scatter", "down", "across" or a sweep angle
orient, shake, threshold, cut_in (a tool), scrub, blender, ruler, jitter, mix_jitter, paint ({hiding, stiff}), seed as in the engine's Handling
blend(mask, {angle=0})                    -- = work(mask, {hand="blend", ...})
stipple(mask, {width=2.4, color="#cfccc2", coverage=function(x, y) ... end,
  pressure={0.5, 0.9}, dips={16, 0.35, 0.7}, aim=false, medium=0.6,
  drag={1, 0}, twist=0.3, cluster={0.2, 5}, feather=0.6, clip=false,
  fade=1})                                -- fade: contrast falls where coverage thins; 0 for specks
                                          -- (stars, snowflakes); color_over works here too
glaze(mask_or_nil, {color="#8a6a3a", coats=0.4, pigment="transparent"})   -- or semi, opaque, varnish
                                          -- a veil of 0.05 coats is laid as asked; only
                                          -- float dust under ~0.007 coats fades out

Edges: found, soft and lost

A stencil clip makes an edge no brush makes: one crisp, even line along the whole contour, the same for every stroke (Evening at a Mountain Lake's ridge read as "a filled selection"). A painter decides each edge and varies it along one contour: found (crisp, where a form turns against the light), soft (the stroke runs over and its film thins out) and lost (the passage carries well into its neighbor and dissolves there).

work(rangeM, {hand="body", tool="filbert 6", color=rangecol, edge="soft"})       -- one quality all along
work(rangeM, {..., edge=function(x, y) return 1 - glow(x, y) end})               -- 0 found .. 1 lost: by the light
work(reflM,  {..., edge={found=0.2, soft=0.5, lost=0.3, period=50, seed=3}})      -- stretches along the contour
work(figM,   {..., edge={quality=0.2, waver=0.5, reach=0.8}})                     -- any form, with its knobs
dry()
lose(reflM, {where=function(x, y) return y > HZ + 6 and 0.7 or 0 end, angle=0})  -- drag the water back across

edge= takes a number (0 found .. 1 lost), a name ("found", "firm", "soft", "loose", "lost"), a function of (x, y) or a noise, a mask (its values), or a table: found=, soft=, lost= shares of the contour laid out in runs about period units long (default 40), seed=, or quality= (any of the above); plus waver= (1: how far the painter's line wanders off the mask's, about 0.3 units plus a tenth of the brush where found and three times that where lost) and reach= (1: scales every stroke's overrun). It clips like clip=true (strokes seeded outside still brush in), but each stroke stops by its own amount: up to about a tenth of the brush width past the line where found, a quarter where soft, four tenths where lost, and past that it lifts off over about 0.06, 0.8 and 2.2 brush widths: its hairs ride the tops of the weave and its film thins (the deposit falls with the square of the fence), so a soft edge is a thinning, broken fringe, not a blur. Into wet paint the overrun also picks up the neighbor. It can't be combined with cut_in. Old logs replay unchanged: nothing changes unless you write edge=.

lose(region, {where=, tool="filbert 4", reach={out, in}, load=0.2, pressure={0.35, 0.02}, angle=, every=1.2, mix=0.35, medium=0.45, pal=, seed=}) loses an edge after the passage is laid: along the region's edge, where where (as edge=; default 1 everywhere) is high, short strokes start out in the neighbor, cross the edge at a shallow slant (or at angle, pointed inward) and lift off inside. Each is loaded lightly with what lies out in the neighbor, dirtied with mix of the region's own color, aimed at the look where it crosses. It returns the number of strokes. Use it over dry paint: into wet paint a lean brush lifts the film and shows what is under it. Press harder (pressure={0.75, 0.25}) and thin it (medium=0.6) for a scumble rather than dry-brush specks.

scripts/edges.py RENDER.png --box x0,y0,x1,y1 measures a render's edges (width, contrast, found/soft/lost shares and waver along a contour); the study is paintings/lua/edges_old.lua against edges_new.lua (notes/edges.md).

Trees and foliage

t = tree{habit="beech", x=700, y=336, height=236, seed=5}
-- habits: oak, dead_oak, birch, spruce, beech, alder, willow; years= to grow older or younger
for _, l in ipairs(t.limbs) do
  -- l.pts {{x,y},...}, l.w (width per point), l.z, l.order (0 trunk, 1 limbs, ...),
  -- l.parent (index), l.at, l.dead, l.dead_from, l.broken, l.root
end
t.tips   t.bounds   t:mask()
leaves = t:foliage{sun={-0.6, -0.7, 0.35}, seed=5}   -- sun: toward it (x right, y down, z to you)
-- winter=true: bare; also years, clump, spacing, squash, droop, fill, ragged, bare, tip, spray
leaves:mask()   leaves:lit()   leaves:gaps(6)   leaves:envelope(6)   -- masks
leaves.clumps   -- back to front: {x, y, z, r, squash, tilt, fill, lit, shade, limb, mass}

The skeleton says how the tree grew, and the foliage where its leaves are and how the sun reaches them. Painting them is up to you. A worked example (from meadow.lua):

local trunk, limb, twig = brush("round", 3.5), brush("round", 1.4), brush("rigger", 0.6)
for i, l in ipairs(t.limbs) do
  local b = (l.order == 0) and trunk or ((l.w[1] > 0.9) and limb or twig)
  if i % 5 == 1 or b:fullness() < 0.3 then b:reload("#3e372f", 0.9) end
  b:stroke(l.pts, {pressure={0.85, 0.2}, ramps={0.03, 0.5}})
end
local turn = noise{seed=7, period=12}      -- leaf strokes turn every which way, not in rows
local way = function(x, y) return 2.2 * turn(x, y) end
work(leaves:mask(), {hand="hatch", tool="round 1.6", length={3, 7}, coverage=2.6, angle=way, color="#2c3a22"})
work(leaves:lit() * leaves:mask(), {hand="hatch", tool="round 1.3", length={2, 5}, coverage=2.2, angle=way, color="#6a843b"})

Firs and fir woods

tree{habit="spruce"} grows a forest tree from buds, and you can't say what shape it takes. fir{} works the other way round: you draw the silhouette and a spruce grows into it. It gets a leader, whorls of 3–6 boughs a year seen in projection (so tiers come out uneven), short interwhorl boughs, boughs that sag and lift at the tip with their tips on your line, gaps in runs, broken and dead lower boughs, stubs on a bare trunk and sometimes a crooked or dead top. Needles hang from each bough as a pad, thin above it and deep below. The fir also gives you the short hatched strokes a pointed brush lays on each pad (Friedrich's firs are "short, hatched strokes"), each with how much it faces the light.

SPIRE = {{520,112},{528,170},{540,240},{552,330},{566,420},{580,492,"c"},{548,505},{520,500},
         {492,506},{462,494,"c"},{478,420},{494,330},{505,240},{512,170}}
f = fir{envelope=outline{pts=SPIRE, char="soft", seed=3}, foot={521, 540}, habit="spire", seed=5}
print(f)   -- fir(spire, 428 tall, 168 boughs (6 dead, 11 broken), 986 strokes, tier 13.8, hatch 2.35)
local nd = f:needles()
-- 1. a dark hatched body under everything, clipped to the needle mask (its edge is the strokes' fringe)
work(nd, {hand="hatch", tool="round 1.8", length={3, 7}, coverage=2.6, clip=nd,
  angle=function(x, y) return 1.57 + 0.5 * clamp((f.foot[1] - x) / 12, -1, 1) end, color="#1f2924"})
-- (a continuous angle: one that flips at the stem leaves a seam of thin cover there)
-- 2. the stem and boughs with a rigger (dead ones gray)
local rb = brush("rigger", 1.2)
for i, b in ipairs(f.boughs) do
  if i % 6 == 1 or b.dead then rb:reload(b.dead and "#6a655d" or "#1d211e", 0.8) end
  rb:stroke(b.pts, {pressure={0.7, 0.05}, ramps={0.05, 0.6}})
end
f:paint(brush("rigger", 0.6), {color="#77716a", kind="twig"})
-- 3. the hatched shoots: shaded ones, half-lit ones, then the few that catch the light
local hb = brush("round", f.hatch)
f:paint(hb, {color="#18211d", lit={0, 0.5}})
f:paint(hb, {color="#34402f", lit={0.5, 0.7}})
f:paint(brush("round", f.hatch * 0.8), {color="#667052", lit={0.7, 1}, every=6})

fir{envelope=, foot=, habit=, seed=, sun=}: envelope is a closed outline{} or a point list (apex at the top; the lowest point is the crown's base). foot={x, y} is where the trunk meets the ground (default: just under the crown). Without an envelope, give x=, y= (the foot), height= and width= for a made-up one. sun points toward the sun, as for foliage. Habits:

habit the tree
spire (default) tall and dense, fairly regular, lower boughs hanging
old (or ragged) gaps, broken and dead boughs, needles in tufts, crooked or dead top
young dense to the ground, boughs rising, few years
storm windward boughs short, all swept leeward (wind=-0.8 blows left)

Override any of the habit's numbers: tiers (whorls, about), whorl={min, max} (boughs per whorl), inter, fill={min, max} (reach toward the envelope), gap, broken, dead_below (share of the crown), crook, kink, rise={top, base} (radians), droop, upturn, pad (needle depth per tier), clumpy, bare_inner, wind, trunk, dead_top.

What you get: f.boughs (back to front: {pts, w, pad={{above, below}...}, z, side, t, dead, broken, minor}), f.leader ({pts, w, dead_from}, foot to apex), f.apex, f.foot, f.crown_base, f.tier (whorl spacing), f.hatch (a good brush width), f.bounds, f.envelope. Masks: f:needles(), f:wood() (stem and boughs), f:trunk() (the bare trunk under the crown), f:mask() (all), f:lit(from) (needles facing the light, default 0.55), f:shade(from), f:gaps(reach) (sky through the crown). Strokes: f:strokes{kind=, lit={lo, hi}, z={lo, hi}} returns {pts, w, lit, z, kind, bough}. kind is "under" (shoots hanging from a bough), "top" (along its upper face) or "twig" (on dead boughs). f:paint(brush, {color=, lit=, kind=, z=, every=10, load=0.8, pressure={0.75, 0.05}, ramps=, shake=, clip=, fit=true}) lays them, back to front. color may be function(stroke). fit presses the brush to each stroke's width. It returns the count. lit ranges are half open, so {0, 0.5} and {0.5, 1} split the strokes.

A wood. Draw the wood's skyline, give the line its feet stand on, and fir_wood places firs in rows. The front row's tops reach your line (a few fall short, one pokes above). The rows behind are smaller, stand higher toward the horizon, are more numerous and carry more air. The lower trunks stand bare, so the foot of the wood shows trunks and floor, not one black block.

WOODTOP = {{-10,150},{50,132},{110,158},{170,146},{230,176},{290,214},{340,262},{385,320},{420,392},{445,455}}
wood = fir_wood{skyline=outline{pts=WOODTOP, open=true, char="soft", lobe=14, seed=31}, foot=516,
                depth=4, count=13, seed=32}
print(wood)  -- fir_wood(4 rows: 13 trees scale 1.00 haze 0.00 | 20 trees scale 0.67 haze 0.33 | ...)
local air = "#a4a7a1"
local function row(r)                -- far rows first; each paler by its haze
  local h, s, nd = wood:haze(r), wood:scale(r), wood:needles(r)
  work(nd, {hand="hatch", tool=string.format("round %.1f", math.max(0.9, 1.8 * s)), length={2, 7 * s + 1}, coverage=2.4,
    clip=nd, angle=1.57, angle_jitter=0.5, color=mix("#1f2924", air, 0.62 * h)})
  local rb = brush("rigger", math.max(0.5, 1.4 * s))
  for n, f in ipairs(wood:trees(r)) do
    if n % 5 == 1 then rb:reload(mix("#221f1b", air, 0.6 * h), 0.85) end
    rb:stroke(f.leader.pts, {pressure={0.9, 0.2}, ramps={0.02, 0.3}})
  end
  if r <= 2 then                      -- hatched shoots on the near rows
    local hb = brush("round", 2.2 * s + 0.3)
    wood:paint(hb, r, {color=mix("#161e1a", air, 0.6 * h), lit={0, 0.55}})
    wood:paint(hb, r, {color=mix("#3a4533", air, 0.6 * h), lit={0.55, 1}, every=6})
  end
end
row(4); row(3)
local fl = wood:floor():roughen(7, 22, 34, 3)   -- the dim floor between the trunks
work(fl, {hand="body", coverage=3, clip=fl, angle=1.5, hug=false,
  color=function(x, y) return mix("#2a302d", "#555c5a", smoothstep(485, 518, y)) end})
row(2); row(1)

fir_wood{skyline=, foot=, depth=4, count=12, horizon=, recede=0.5, air=0.4, width={0.2, 0.32}, mix={spire=0.7, old=0.18, young=0.12}, bare={0.06, 0.18}, sun=, seed=}: skyline is an open outline{} or points, left to right. foot is a y or a line. depth is the number of rows and count the trees in the front row. Each row back is 1 + r*recede times farther. Its haze is 1 - exp(-r*air). horizon is the eye level, where the rows' feet converge (default: a little above the foot). width is the crown width as a share of height and bare the bare trunk under it. Rows count from 1 (the front). Masks per row: wood:needles(r), wood:wood(r), wood:all(r), wood:visible(r) (less the rows in front), wood:lit(r, from), plus wood:floor() and wood:mask() (everything). Numbers: wood:haze(r), wood:scale(r), wood.depth, wood.horizon. Trees: wood:trees(r) (fir values, as above). wood:paint(brush, r, {...}) works like f:paint. wood.rows builds a table of every tree, so read it once, not inside a color function.

Broadleaved trees grown into a drawn crown

tree{habit="oak"} grows a tree from buds, and you can't choose its shape. tree_in{} works the other way round: you draw the crown's silhouette and the trunk, and an oak, beech, lime, birch or pollard willow grows into it by space colonization (Runions et al. 2007). Attraction points fill the crown in depth, thinned by a low noise so the crown has its own gaps where limb masses part. The trunk runs on into the crown as a leader, and only a few nodes on it sprout, so the scaffold limbs come from the trunk. Each step bends by the species' habit: an oak grows crooked and level, with sympodial kinks that persist down a limb; a beech rises smooth. Widths follow the pipe model down to the trunk, which flares at the foot. Fine twigs come at the tips and along the thin wood. They hang from a birch and fan off an oak like a fishbone. Leaves come as clumps on the leafy twigs, sized by species and season, and each clump carries the hooked touches a pointed brush lays on it. Each clump is lit by where it faces on the crown and shaded by the clumps between it and the sun. The same crown and seed grow the same wood in every season and anywhere on the canvas.

WORLD = world{horizon=452, sun={azimuth=-125, elevation=38}}
OAK = {{70,236},{96,192},{140,170},{178,150},{226,160},{262,150},{300,178},{330,214},{346,262,"c"},{334,318},
       {310,352},{322,392,"c"},{270,410},{220,402},{178,416},{130,404},{84,396,"c"},{50,366},{38,318},{52,272}}
oak = tree_in{crown=outline{pts=OAK, char="soft", seed=5}, trunk={{196,592},{192,520},{187,452}},
              species="oak", season="summer", sun=WORLD, seed=7}
print(oak)  -- tree_in(oak, summer, crown 286 tall, 3055 limbs (2460 twigs), 4941 clumps, 29462 touches, ...)
-- 1. the wood: stout wood as filled body paint, a lit flank on the trunk, the rest pressed to width
local thick = oak:wood(3.5)                      -- where the wood is at least 3.5 wide
work(thick, {hand="body", tool="round 2", length={4, 12}, coverage=3.5, angle=1.5, clip=thick, color="#3b342c"})
local stout = oak:wood(7)
work(stout * mask(function(x, y) return 1 - stout:at(x + 1.8, y + 1) end),
     {hand="body", tool="round 1.4", coverage=2.5, angle=1.5, clip=thick, color="#7d7566"})
oak:paint_wood(brush("round", 2.4), {color="#3b342c", min=1.2, max=3.5})
oak:paint_wood(brush("rigger", 0.9), {color="#3b342c", max=1.2})
-- 2. the leaves' body from the light on them (deep shade inside, lit masses toward the sun)
local lv, L = oak:leaves(), oak:light()
local turn = noise{seed=9, period=9}
work(lv, {hand="hatch", tool="round 1.6", length={3, 6}, coverage=2.4, clip=lv, hug=false,
  angle=function(x, y) return 2.4 * turn(x, y) end, angle_jitter=0.8,
  color=function(x, y) local v = L:at(x, y)
    return mix(mix("#222b1d", "#35412a", smoothstep(0.1, 0.45, v)), "#5c6a3a", smoothstep(0.5, 0.85, v)) end})
-- 3. sky into the crown's gaps first, so the touches break their edges
local gp = oak:gaps()
work(gp, {hand="detail", tool="round 1.4", color=sky, clip=gp, coverage=2})
-- 4. the hooked touches, shade to light; front shade masses catch the sky
local b = brush("round", oak.touch_w)
oak:paint(b, {color="#263020", lit={0, 0.4}})
oak:paint(b, {color="#4a5446", lit={0.15, 0.4}, depth={0.25, 1}, share=0.5})
oak:paint(b, {color="#46522e", lit={0.4, 0.6}})
oak:paint(brush("round", oak.touch_w * 0.9), {color="#6f7c45", lit={0.6, 0.78}})
oak:paint(brush("round", oak.touch_w * 0.8), {color="#98a060", lit={0.78, 1}, every=6})

-- the same oak bare: same crown, trunk and seed (moved 322 right), season="winter"
local function moved(pts) local o = {} for i, p in ipairs(pts) do o[i] = {p[1] + 322, p[2]} end return o end
bare = tree_in{crown=moved(oak.crown), trunk={{518,592},{514,520},{509,452}}, species="oak", season="winter", sun=WORLD, seed=7}
-- the wood as above (thick body, lit flank, round 2.4 for 1.2..3.5), then the fine wood a shade
-- lighter, each band with a rigger that can lay its widths: the crown's lace against the sky
bare:paint_wood(brush("rigger", 0.9), {color="#554e45", min=0.5, max=1.2, every=2})
bare:paint_wood(brush("rigger", 0.55), {color="#554e45", max=0.5, pressure=0.04, every=2})
bare:paint(brush("round", bare.touch_w * 0.7), {color="#6e5234", share=0.4})   -- the few dead leaves an oak keeps

A bare tree holds together. paint_wood paints the wood by its local width: {min=1.2, max=3.5} is every run of wood between 1.2 and 3.5 wide, including the thin outer end of a stout limb and of the leader (the runs t:wood(3.5) leaves out). Every stroke starts on wood painted before it: a run starts one point back in the thicker wood, and a limb starts half a segment back along its parent, pulled out of it as a painter pulls a twig from a branch. The pressure follows the wood's width along the stroke, and the brush lifts off only at a real tip, never where the wood goes on or where twigs leave it. A limb's leading twig is drawn on in the same stroke, so the limb runs out into it in one movement. So paint the bands thick to thin (t:wood(3.5), then min=1.2, max=3.5, then max=1.2) and nothing floats. Give each band a brush that can lay its widths: a brush's mark runs from b:mark_width(0) (about a third of its size, or two hairs with a pointed tip) to a little over its size (b:mark_width(1)), and paint_wood presses up to that, no further. A rigger 0.55 lays 0.21 to 0.71, so over the whole fine band (0.12 to 1.2) it paints every twig and small limb about the same width: split it (rigger 0.9 for 0.5 to 1.2, rigger 0.55 below 0.5), and the wood visibly thins at each fork and runs out to a point.

An oak is angular. An oak's wood runs fairly straight between its nodes and changes direction at them: elbows, the sympodial zigzag, twigs short and stiff. The species number angular (oak 1, lime 0.5, beech, birch and willow 0) makes it so. The runs between forks are straightened (wiggles under about half a model step are taken out, the larger turns kept at a few nodes), a shoot zigzags about its heading but never turns more than about 70 degrees off it (no hooks or loops), a side twig stands well off its limb, and paint_wood strokes the wood straight from node to node (a brush's own spline through the nodes would round every elbow into a rope-like S-curve). A beech (angular=0) keeps its smooth rising curves. angular= overrides it; it changes the wood in every season.

Fewer, more deliberate twigs: detail. A painter doesn't paint every twig. detail (0..1) is the share of the fine wood (the twigs and limbs under about two twig widths) drawn as lines: pieces picked for character (long ones, a limb's leading twig, those toward the crown's edge where they show against the sky; one side twig per spot, not a starburst), always with the wood they leave from. The stout wood is always drawn, and the rest is left out: draw the selected twigs and leave the sky between them. tree_in{detail=} sets it for the tree (read it back as t.detail); paint_wood{detail=} overrides it.

Not recommended: a tone for the undrawn twigs. t:twig_mass(detail) is a soft mask (0..1) of the fine twig mass that isn't drawn. Laid as a pale dry-brush tone under the drawn twigs it can pass for a winter crown's haze, but it doesn't hold up: a blind panel of four critics (two Gemini, two gpt-6-astra) judging a lab study of it all preferred the version with drawn twigs, strongly, calling the tone "steel wool", "fur" and "gray scribble cushions", and on this branch's study the toned trees look heavier and smeared (notes/oak.md). It stays available for experiments. The default is 0.35 + 0.65 * leaf (the season's share of leaves): 0.35 for a bare tree, 1 (every twig) in summer, where the leaves carry the fine structure. detail=1 draws every twig, as before; 0 only the stout wood. The study is paintings/lua/bare_trees.lua (notes/oak.md).

tree_in{crown=, trunk=, species=, season=, sun=, seed=, detail=, ...}: crown is a closed outline{} or points. With fewer than 12 points the corners are rounded. trunk runs from the foot up, as points or an open outline. If it stops short, a crooked leader carries it on into the crown. A single point is the foot. Without a trunk, one is made under the crown. sun is {x, y, z} toward the sun (x right, y down, z to you) or a world{}, whose sun is used. The default is the upper left, a little in front.

species habit
oak (default) broad crown of crooked, level limbs, sympodial zigzags, 2–4 scaffold limbs, lobed leaf masses with sky between
beech smooth rising limbs, level sprays (flat touches), dense
lime (or linden) a dense dome, leaves to the shell, many fine limbs
birch a leading stem, thin limbs, long hanging twigs, small airy clumps
willow (or pollard) a short thick trunk ending in a head, straight rods rising from it
season leaves
spring 80% of the leaves, small clumps
summer (default) all
autumn about 60%, fallen in patches (whole twigs bare), turned (turn per clump and touch)
late_autumn about 30%, all turned
winter bare, but for a few dead leaves low in an oak or beech (dead=true)

leaf= (0..1) and turn= override the season. Any species number can be overridden: growth step, density, influence, kill, up, out, crook, kink, inertia, shell, voids, void_size and depth. Wood: scaffold={min, max}, girth (trunk width per crown height), twig_w, smooth, pipe, leader (how far the trunk runs on into the crown) and angular (0 smooth; above 0 an oak's straight runs and elbows, the number setting how much is straightened). Twigs: twigs, twig_len, twig_spread, twig_droop, twig_zig and twig_along. Leaves: clump, squash, hang, fill, ragged, leafiness and leafy_w. Touches: touch, touch_w, hook, droop, flat, touches and marcescent.

What you get:

Field trees in depth. Draw a few crowns and tree_group grows them where you drew them. It adds count more trees behind, made from your crowns: flipped, stretched, reshaped, some tall and narrow. The added trees are smaller, stand higher toward the horizon and carry more air.

field = tree_group{crowns={F1, F2, F3}, trunks={{{592,481},{590,460}}, {{651,483},{651,464}}, {{416,488},{418,468}}},
                   species={"oak", "lime", "oak"}, count=6, horizon=452, spread=0.8, sun=WORLD, seed=19}
glaze(field:shadow():blur(1.5), {color="#4d5539", coats=0.25})   -- one faint shadow per tree
for i, t in ipairs(field:trees()) do                                -- far to near
  local lv, L, h = t:leaves(), t:light(), t.haze
  t:paint_wood(brush("round", 1.2), {color=mix("#2f2a24", air, 0.55 * h), min=0.8})
  work(lv, {hand="hatch", tool="round 1.2", length={1.5, 3.5}, coverage=2.4, clip=lv, hug=false, angle_jitter=1.2,
    color=function(x, y) return mix(mix("#27301f", "#56623a", smoothstep(0.3, 0.8, L:at(x, y))), air, 0.7 * h) end})
  t:paint(brush("round", math.max(0.8, t.touch_w)), {color=mix("#6d7746", air, 0.6 * h), lit={0.6, 1}, share=0.7})
end

tree_group{crowns=, trunks=, species= (a name or a list, one per crown), season=, detail=, foot=, count=3, horizon=, recede=1.5, air=0.5, spread=0.5, narrow=0.3, sun=, seed=}: foot is the y the drawn trees stand on if no trunks are given. The added trees stand 1 + u*recede times farther off, with haze = 1 - exp(-(d - 1)*air). They spread spread times the drawn span to each side, and a share narrow are drawn tall and narrow. Trees run from far to near: g:trees(), g:tree(i) (a tree value with haze and scale), g:haze(i), g:scale(i), g:shadow(), g:mask(), g.count and g.horizon. The study is paintings/lua/trees_in.lua.

Rocks from a drawn outline

Don't build a rock from ellipsoids and cuts. Draw its silhouette as an outline{} (char="broken" for a weathered stone, "firm" for a sure contour), and draw any cracks or plane lines you see inside it. rock{} infers a solid behind the drawing:

The rock is lit with your sun, and every point gets its light and shadow family, core shadow and reflected light. The tool traces shadows over the rock itself (cracks and overhangs are occluded) and onto the ground it stands on. Since the planes are many, the terminator steps along their arrises; it doesn't run down one seam.

-- an erratic in snow under a low sun
E = outline{pts={{584,328,"c"},{592,288},{612,244,"c"},{652,212},{704,194,"c"},{752,202},{790,220,"c"},
                 {834,232},{872,262,"c"},{898,298},{904,326,"c"},{830,336},{710,340}}, char="broken", seed=4}
r = rock{outline=E, cracks={{{706,198},{722,232},{736,256},{744,298}}}, kind="granite", seed=7,
  sun={from={-1, -0.14}, front=0.3, ambient=0.25, bounce=0.55, bounce_from={0.3, 1, 0.45}}}  -- snow bounces a lot
print(r)   -- rock(granite, 320x147, R 71, 30 planes (8 sizable), 2 lines (1 grown), lit 43%)
local m, v, core, refl = r:mask(), r:value(), r:core(), r:reflected()
local lo, hi = r:levels(0.03, 0.97)          -- anchor the value scale on this rock's own range
local P = {core="#2c2c34", shadow="#4c4e5a", half="#7c7a80", light="#b09a88", top="#d6b89a", bounce="#8a90a4"}
local function col(x, y)
  local c = gradient({{0, P.core}, {0.3, P.shadow}, {0.55, P.half}, {0.85, P.light}, {1, P.top}}, smoothstep(lo, hi, v:at(x, y)))
  return mix(mix(c, P.bounce, 0.55 * refl:at(x, y)), P.core, 0.45 * core:at(x, y))
end
-- 1. the whole mass thin, down each plane (one direction per plane: the breaks show in the strokes)
work(m, {hand="body", tool="filbert 4", color=col, angle=r:field("plane"), length={6, 16}, coverage=3.2, medium=0.25, clip=m})
-- 2. the lit planes again in stiffer paint; 3. fuse the shadow side a little
work(r:lit(0.2), {hand="body", tool="filbert 3", color=col, angle=r:field("plane"), length={5, 14}, coverage=2.4, medium=0.12, clip=m, hug=false})
blend(r:shadow(0.3), {angle=r:field("plane"), coverage=1.2})
-- 4. every crack and joint as one stroke along its line
local rb = brush("round", 1.3)
for i, s in ipairs(r.seams) do
  if i % 3 == 1 then rb:reload("#26252c", 0.8) end
  rb:stroke(s.pts, {pressure={s.grown and 0.55 or 0.8, 0.2}, ramps={0.15, 0.45}, shake=0.5, clip=m})
end
-- 5. seat it: the shadow it casts on the snow and the dark seam at its foot
glaze(r:cast():blur(1.2), {color="#6a7090", coats=0.27})
glaze(r:contact(), {color="#2c2a2a", coats=0.3})
-- 6. snow on the faces that turn up, with a cap standing over the top edge
local sn = r:snow{amount=0.7, depth=3, seed=3}:blur(2):map(function(x) return smoothstep(0.3, 0.6, x) end)
local bv = v:blur(3)
work(sn, {hand="body", tool="filbert 3", length={4, 12}, coverage=5, medium=0.1, aim="masstone", angle=r:field("across"),
  color=function(x, y) return mix("#8e96ae", "#efe3cf", smoothstep(lo, hi, bv:at(x, y) + 0.1)) end})

A sandstone outcrop: draw a flat top and a stepped flank, and draw the main joints. The tool adds the beds (each weathers back toward its base, so it overhangs and shades the bed below), the bed joints and more vertical joints. r.seams holds all of them for stroking.

LEDGE = {{36,650,"c"},{44,580},{58,520,"c"},{92,500,"c"},{120,462,"c"},{240,452},{330,456,"c"},{352,482,"c"},
         {410,488,"c"},{436,540,"c"},{452,560,"c"},{462,610},{470,656,"c"},{300,664},{150,662}}
s = rock{outline=outline{pts=LEDGE, char="firm", seed=12}, kind="sandstone", sun={-1, -0.5, 0.3}, seed=21,
  cracks={{{210,455},{206,520},{214,600},{208,655}}, {{360,465},{372,540},{366,600}}}}
print(s)   -- rock(sandstone, 434x213, R 106, 34 planes (11 sizable), 12 lines (10 grown), lit 42%)
-- then paint it as above, with warm colors; stroke r.seams for the joints and bed joints

rock{outline=, cracks=, planes=, kind=, sun=, seed=}:

What you get:

It costs about 0.1–0.5 s per rock at 1000 px. Each mask costs 4 bytes per pixel, like any mask.

Meadows

tufts = sward{region=below(function(x) return HZ + 40 end), horizon=HZ, near=H, height=30,
  flowers=0.05, seed=4, wind={lean=0.15, gust=0.2, period=160, seed=2}}
-- also spacing, thin, smallest, blades={lo, hi}, fan, curl, kinds, patch, patch_size
-- tufts far first: {x, y, scale, height, lean, lush, blades={{foot, ctrl, tip}, ...}, flower={x, y, r, kind}}
local g = brush("rigger", 0.7)
for i, t in ipairs(tufts) do
  if i % 4 == 1 then g:reload(i % 8 == 1 and "#7a8f3c" or "#5e7a30", 0.7) end
  for _, bl in ipairs(t.blades) do
    g:stroke(bl, {pressure={clamp(0.25 + 0.5 * t.scale, 0.2, 0.9), 0}, ramps={0.05, 0.7}})
  end
end

Tufts shrink and thin toward the horizon and stop where they'd be smaller than smallest: paint the far meadow as tone underneath first.

Form: solids, light and shade

Model what you paint as solids, light them, then let their planes decide your colors, stroke directions and edges. Form paints nothing itself. Coordinates are canvas units, with z pointing toward you.

-- bodies: a mass, turned, weathered, broken by fracture planes; + and - combine
rock = body.ellipsoid({330, 560, 60}, {150, 105, 110})      -- center, radii
  :turn({330, 560, 60}, 0.3, 0.1, -0.12)                    -- yaw (right side toward you), pitch (top toward you), roll
  :rough(15, 150, 1)                                        -- amp, period, seed, ridged?
  :cut({330, 480, 60}, {-0.35, -1, 0.45}, 10, 4)            -- at, outward normal, facet id, round
  :rough(0.9, 25, 2, true)                                  -- pitted grain
slab = body.block({600, 600, 0}, {200, 40, 80}, 3)          -- center, size, round
-- a mountain face below a crest line (a function of x, or points)
range = ridge{crest=function(x) return 330 - 60*math.sin(x/170) end, depth=320, seed=7,
  lean={0.9, 0.7}, gullies={45, 0.5}, fan=1, base=560, z0=-600}   -- also strata={spacing, step, tilt}
-- any height field: z (toward you) or nil where there's no surface
dune = terrain{area={0, 500, 1000, 714}, height=function(x, y) return 20*math.sin(x/60) end}

-- the lit depth buffer: parts are numbered in order (1, 2, ...)
f = form{ {range, dist={2.0, 0}}, {rock, dist=0.3},          -- dist: number or {at, per_z} (aerial perspective)
  light={from={-1, -0.7}, front=0.5, ambient=0.2, penumbra=0.05} }  -- front < 0: contre-jour
  -- light also takes bounce, bounce_from={x,y,z}, reach, thickness, across_parts

f:sample(x, y)      -- nil off the form, else {part, facet, z, n, dist, fall, across, lit, shade={turn, direct, cast, bounce, sky, value}}
f:shade(x, y)  f:value(x, y)  f:lit_at(x, y, soft)  f:part(x, y)  f:dist(x, y, far)
f:fall(x, y)  f:across(x, y)  f:bend(x, y, span)  f:edge_angle(x, y, span)
aerial(dist, visibility)     -- how much of a color the air replaces, 0..1

-- masks
f:parts_mask{2}                                   -- where a part is in front
f:lit{parts={2}, soft=0.12}   f:shadow{parts={2}} -- the light and shadow families
f:silhouette{parts={1}, soft=0.6, haze={3, 4}}    -- edge soft + 3·aerial(dist, 4)² units wide
f:edges{turn=0.8, step=3, span=2.5, concave=true} -- plane breaks and overlaps (concave: only hollows)
f:mask(function(s) return s.shade.sky end)        -- any rule (serial, ~0.5 s at 1000px; s is reused)

-- stroke directions straight from the form (no grid): down the planes, around them, along breaks
work(f:silhouette{parts={2}} * f:shadow{parts={2}}, {hand="body", color=function(x, y)
  return mix("#3e3a36", "#8a8070", f:value(x, y)) end, angle=f:field("fall")})
f:field("across")   f:field("edge", 2.5)

Place solids in depth with z: a ridge's face leans toward you at its foot, so set its z0 back (e.g. z0=-600) or it will hide the rocks in front of it. A form costs 28 bytes per pixel (20 MB at 1000px, 190 MB at 3200px).

The world: camera, ground, sun, shadows, water

A world is one picture's space in meters: a camera (eye height, horizon, field of view), the ground, water, one sun and the bodies standing there. Build it once. w:place returns a new world (keep the result).

HZ = H * 0.46
w = world{horizon=HZ, eye=1.7, fov=50,                 -- horizon: canvas y at eye level
  sun={azimuth=-125, elevation=38},                    -- degrees: 0 ahead (contre-jour), -90 left,
                                                       -- 180 behind you; below 0: twilight
  ground=function(X, Z) return 1.2*math.sin(X/40) * math.min(1, Z/60) end,   -- meters, gentle
  water={level=-0.2, ripple={0.03, 1.4, 0.3, 7}}}      -- fills hollows below the level
-- also view={x, y, w, h} (a panel), visibility (m), backdrop (m)
local s = w:spot(700, 336)             -- the ground seen at a canvas point (or w:spot_at(X, Z))
print(s)                               -- spot(x, y, units per meter, at X, Y, Z m)
local tall = w:height(s.x, s.y, 18)    -- how tall 18 m looks standing there (units)
local rock = body.block(s:p(0, 0.4, 0), s:size(1.3, 1.0, 1.1), s:m(0.3))   -- meters -> units
w, stone = w:place(s, rock)            -- a body in the world (lit, shadowed, reflected)
w = w:proxy(s, body.ellipsoid(s:p(0, 11, 0), s:size(7, 6, 6)))   -- casts a shadow but isn't painted
                                       -- as a form: stand-in for a tree crown or a figure
v = w:view()                           -- trace once and keep it
v:sky()  v:land()  v:water()  v:shadows()  v:contact(0.25)  v:reflections()  v:bodies_mask{stone}
v:at(x, y)      -- {what="sky"|"ground"|"water"|"body", body, at={X, Y, Z}, n, dist, shade, lit}
v:mirror(x, y)  -- what calm water shows there: {body, src={x, y}, shade, fresnel, travel} or nil
v.form          -- the bodies as a form: v.form:lit{parts={v:part(stone)}}, v.form:field("fall"), ...
                -- (v.form.parts counts visible bodies only; v:part(proxy) is 0)
w:to_ground(x, y)  w:project(X, Y, Z)  w:scale_at(Z)  w:aerial(Z)  w:shadow_angle(x, y)  w:sun_canvas()
w:ribbon({{-2.6, 4.5}, {-1.6, 8.6}, {-0.4, 9.7}}, 1.1)   -- a path on the ground (width m) as a mask
w:recede({2, 6}, {0.3, 4}, 8)                             -- spots stepping away: posts, footprints

A shadow is the ground a little darker and bluer, stroked the way it falls:

work(v:shadows() * v:land(), {hand="body", tool="filbert 3", length={6, 16}, coverage=3,
  angle=w:shadow_angle(s.x, s.y + 2), color_over={shift={-0.06, -0.004, -0.012}}})

Depth: what is in front of what

A view knows what lies behind what at every pixel: the sky, the ground, the water, every body and every layer (a motif you paint by hand, registered at a depth). So you never have to subtract earlier motifs from a mask by hand. Proxies cast shadows but are never seen, so they don't hide anything. Register what you paint for them as a layer.

-- a man written with gestures: a proxy for his shadow, his outline as a layer
fs = w:spot_at(-0.35, 11)
w = w:proxy(fs, body.ellipsoid(fs:p(0, 0.85, 0), fs:size(0.26, 0.88, 0.18)))
w = w:layer("figure", coat + head, fs)   -- depth: a spot, meters, a canvas point
                                          -- {x, y} (the ground seen there: his feet)
                                          -- or "ground" (lies on it: a path, glints)
v = w:view()                              -- the last view made is the one passes use

Passes take visible=, behind= and at= (work, blend, stipple, glaze). They are a hard limit: strokes still overshoot the region's own edges, but they never enter what is in front.

stipple(seaband, {..., behind={"figure", "bodies"}})   -- a veil laid behind the man and the stones
work(zone, {hand="detail", ..., visible="water"})     -- glints only where the water is seen
work(v:visible("bodies"), {...})                       -- the stones, less the man in front of one
glaze(nil, {color="#8a8f98", coats=0.3, at=400})       -- mist 400 m off: all nearer hides it

Things are named by body number (from w:place), layer name, "ground", "water", "surface" (both), "sky", "bodies", "layers" or a list. visible= and behind= also take a mask, alone or in the list (visible={boat, "water"}): a mask is a thing in front of everything, so visible=m is m and a list is m plus what of the rest is seen around it. Pass view=v to use another view.

The same as masks, with soft edges composited front to back:

v:visible(x)        -- where x is seen: its coverage less what is in front (x may hold masks)
v:visible("ground") -- the ground not covered by any body or layer
v:front(x)          -- what hides x, where x is
v:behind(x)         -- where a pass lying just behind x shows
v:at_depth(m)       -- where a pass m meters off shows (a spot or {x, y} too)
v:between(a, b)     -- whatever is seen between a and b meters
v:seen(x, y)        -- {{what="layer", layer="figure", depth=11, share=1}, ...} nearest first

Shadows that fall off the way light does (no rings to soften by hand):

glaze(v:cast_shadow{soft=1.6}, {color="#4a4c60", coats=0.55})       -- crisp at the foot, soft far out
glaze(v:contact_shadow{reach=0.35}, {color="#2a2420", coats=0.9})   -- the sky hidden near the bodies

cast_shadow{soft=, from=} traces the world's sun. The penumbra grows with distance from the caster, and soft widens it (1 is the sun's own width plus haze). contact_shadow{reach=, from=} is the share of the sky the bodies hide from the ground within reach meters. It is about 0.5 in the crease and fades to nothing, and it also darkens the foot of each body. Both stop where a layer or body stands in front. They cost 0.1–1 s at 1000px. paintings/lua/depth.lua uses all of this, and paintings/lua/depth_hand.lua is the same picture with hand masks.

Sky, clouds, haze and distant ranges

sk = w:sky{haze=2.2, uneven={0.5, 30000, 5}}   -- the sky for this world's sun, as paint colors
-- also layer={alt, thick, density, uneven, seed}, overcast=0..1, exposure, balance (adapt to the sun's color)
cl = w:clouds{sky=sk, cell=3,                  -- meters; x right, z away, base/top altitude
  {kind="cumulus", x=-3000, z=9000, base=1300, width=3000, height=1500, seed=4},
  {kind="bank", x0=-2000, x1=30000, z=38000, depth=9000, base=700, top=2600, seed=4},
  {kind="stratus", base=3500, thick=500, cover=0.35, seed=2, wind={-0.2, 2}, breaks={14000, 0.2}}}
work(above(function(x) return HZ + 12 end), {hand="broad", color=cl, angle=0, coverage=4.5})
cl:mask{alpha={0.3, 0.8}, lit={0.4, 0.9}}      -- lit cloud edges; shade={..} for the bellies
sk:at(x, y)  sk:airlight(x)  cl:alpha(x, y)  cl:lit(x, y)

air = haze{visibility=18000, height=800, mist={140, 6, 90, 7}}   -- mist: {top m, density, uneven m, seed}
rs = w:ranges{near=6000, far=22000, count=2, seed=8, heights={180, 700}, kinds={"dome", "saddle"}}
for i = #rs, 1, -1 do                          -- far to near; kinds: peak, dome, plateau, saddle, cliff
  local l = rs[i]
  work(l:mask() * above(function(x) return HZ + 3 end), {hand="body", length={20, 60}, angle=0.05,
    color=function(x, y) return mix("#3f4c44", sk:airlight(x), 0.75 * l:haze(air, x, y)) end})
end
-- l:crest(x), l:z_at(x), l:ridge{depth=200, gully=260} (a solid for form{} to light)

A sky or clouds passed as color= is read on the engine's threads, so it costs nothing extra. Twilight is the same code with the sun below the horizon (elevation=-4): the sky turns to its afterglow, the Earth's shadow and the Belt of Venus, and the clouds catch the light from below.

A whole painting, in order

  1. canvas{}, then w = world{...} and sk = w:sky{...} (and clouds).
  2. The sky, thin, in long strokes, then blend; wait(24*60).
  3. The distance: ranges far to near, each hazed by l:haze; mist stippled over their feet.
  4. The ground as tone, colored by distance (w:to_ground, w:aerial).
  5. The motifs: bodies and proxies placed in the world, v = w:view(), then shadows and contact, trees (limbs, then foliage dark to light), rocks from v.form, meadows from sward.
  6. The small particulars last, with small rounds and riggers (point=1 for a tip that draws down to a hairline): twigs, blades, flowers, figures.
  7. wait(24*60); varnish(); cracks{}; relief(). The craquelure is part of the finished look: a Friedrich is two centuries old and cracked, and Alice wants that (Round 6). Leave it out only for a study meant to show fresh paint.

For winter, grow trees bare (t:foliage{winter=true} or no foliage), and paint snow as the ground's color with color_over for its blue shadows.

Time and finishing

wait(minutes)         -- time passes: the paint ages where it lies; returns the clock
dry()                 -- wait until every film is touch-dry; returns the clock
clock()               -- painting minutes since canvas{}
drying(x, y)          -- "open", "setting", "tacky" or "dry" there
varnish{color="#e6d3a4", coats=0.4, vary=0.12}
cracks{dirt=0.4, vary=1, veil=0.5}          -- craquelure, fitted to this canvas's ground;
                                             -- also island_mm, ground_um, width_um (default:
                                             -- from the ground), depth_um, cupping_um, corners
cracks{hierarchy=1, patchy=1, grain=0.15, grime=1}   -- (the defaults) how uneven it is
relief(strength, gloss)                      -- light the surface relief (style default)

The craquelure is uneven on purpose (Round 7, notes/cracks.md). A few long first cracks open widest (about 70 µm) and cup most. The later generations, splitting smaller islands, are finer and pinch shut for stretches (hierarchy). Some passages kept only their first cracks while others split finely (patchy), and the first cracks lean across the canvas's length (grain, a tendency). Each crack holds a different amount of grime, and a few hold old amber varnish. Its walls show the pale ground, so in darks a crack is a faint light line instead of stopping at the edge of the dark (grime). Thin paint shows hairlines and thick paint wider cracks. Set a knob to 0 for the old even web, or use all four at 0 to get the Round 6 look. The cupped island edges barely show in the style's frontal light, as on a real picture. relief(0.3) rakes the light across them.

wait runs the engine's drying model: each pixel's paint goes from open (workable, blends and lifts) through setting (stiff, barely blends) to tacky (set, grabs the brush) and touch-dry, at a pace set by its pigments, film thickness and oil. So a chunk can work wet into wet (no wait), come back to tacky paint (wait(180)) or paint over a dry layer (wait(24*60)). The clock is written into the log at every chunk, so time is part of the program.

A day isn't always enough: thick, oily or slow-drying paint (bone black, lakes, heavy body color) can stay open for weeks of painting time. Check with drying(x, y) or look --mode wet before painting over a passage, or call dry().

Hand time and sittings

By default marks take no time: only wait, dry and the finishing verbs move the clock. Turn hand time on and every mark costs the time a hand takes to make it, and the paint ages while you work (notes/time.md).

canvas{style="friedrich", aspect=1.4, seed=7, hand=true}   -- or hand_time(true) later
sitting{hours=3}      -- this sitting's length (default 3 h, at most 8), set before painting in it
rest(16)              -- step away: the paint sets; the next mark starts a new sitting
                      -- (rest() = overnight, 16 h; any wait of 2 h or more is a rest too)
t = timesheet()       -- {clock, sitting (min), sittings, hours, hand, open, setting, tacky,
                      --  dry (shares of the canvas), strokes, touches, reloads, piles, hand_min}

glaze goes over dry paint, so it first waits until everything under it is touch-dry; that time passes on the clock and the easel says so (glaze: waited 9.8 days for the paint under it to dry). The other finishing verbs that dry the paint first (varnish, cracks, relief) report their wait the same way, so the clock you see is always the canvas's.

Editing a chunk

easel show 5                     # chunk 5's code
easel edit 5 -f chunk5.lua       # replace it; replays 6.. from the nearest checkpoint
easel edit 5 --insert -f fix.lua # a new chunk before chunk 5
easel edit 5 --drop              # take chunk 5 out (a probe you forgot to undo)
easel undone                     # chunks undone or replaced, newest last
easel undone 3                   # the code of one of them
easel redo 3                     # run it again as a new chunk
easel edit 5 --undone 3          # or put it back in place of chunk 5

The log is still the program. An edit rewrites it and the canvas becomes exactly what a replay of the new log paints (easel check confirms it). If any chunk fails on the way, nothing changes. The replay starts from the nearest checkpoint: a full snapshot of the session (canvas, Lua variables, brushes, clock) kept in memory, not on disk, since the Lua heap can't be written out. The session keeps the --undo snapshots (the last 8 chunks) plus --checkpoints older ones (default 6) on a grid that widens as the log grows (after chunks 0, 4, 8, … in a 30-chunk log). Each costs about 50 MB at 1000px. easel status lists them. Everything after the edited chunk still has to be painted again, so an edit near the start saves the chunks before it (often the slow ones: the canvas and the sky) and an edit near the end is almost instant. undo past the undo snapshots now works too: it replays from a checkpoint.

Code taken out of the log by undo or edit is kept in out/easel/<name>/undone.lua, so undo never throws work away. Each entry's header ends with the code's length (--@ undone 3 · was chunk 5 · undone · 214 bytes) and the code is read by that length, so a chunk that holds header-like lines (in a long string or a comment) comes back whole. Files from before the lengths still read as they did. If you edit the file by hand, keep the lengths right (an entry whose length doesn't fit is read up to the next header line). Inserting or dropping a chunk renumbers the ones after it, and their random choices (rand, automatic seeds) change with the number.

Replay

easel run paintings/lua/<name>.lua [--width 3200] [--out path.png]
          [--crop x0,y0,x1,y1] [--margin 40] [--look]

This runs the chunks in order in a fresh session and writes out/lua/<name>_<width>.png; --look also writes a JPEG next to it. --dump-surface path.f32 also writes the dried surface height under the saved pixels (µm, little-endian f32, row by row). To hunt small digital artifacts in a 3200 crop (specks, pinholes, slivers of ground, outlines, mottle), run uv run scripts/glitch.py <png> --out overlay.png (notes/glitch.md). At the width you painted at, the PNG is byte-identical to easel save from the live session. At 3200px it is the full render: the same program at a finer grain. The file is plain Lua with chunk markers (--@ chunk N · clock M), so you can edit it by hand and replay. If you do, keep the markers, and edit it with the session closed: a live session writes the log after every chunk. To change one chunk with the session open, use easel edit instead. If it finds the file was edited while it was open, it keeps your version as <name>.edited-N.lua next to it (and says so) instead of overwriting it; close, copy it back and open again to paint on from your edit.

Costs (1000px, busy 10-core machine)

Limits

Source