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
-
Open.
easel open <name> [--width 1000] [--undo 8]starts a background session, or reattaches if it's already running. Ifpaintings/lua/<name>.luaexists, 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>, orEASEL_SESSION). The checkout is the nearest directory at or above where you runeaselthat holdscrates/easel(orEASEL_ROOT): logs go to itspaintings/lua, renders to itsout/, so git worktrees stay apart. With several painters on one machine, still name your session (-s <name>). -
Paint a chunk.
easel do '<lua>',easel do -f chunk.luaoreasel do -(stdin). The reply is whatever the chunkprinted, thenok · chunk N · seconds · clock · sitting · how much is open, setting, tacky and dry. Add--lookto also get a look in the same command. -
Look.
easel lookprints the path of a ≤1000px JPEG (100–250 KB):--crop x0,y0,x1,y1a 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;--reliefalso lights the brushwork from the upper left;--size Nfor the longest side;--grid,--probe x,y,--showand--scale 3.2help 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.
-
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). -
Step back.
easel logprints the program so far.easel statusgives a one-line summary (with the clock, the sitting and the drying stages).easel save [path]writes a PNG.easel checkreplays the log in a fresh session and confirms it matches the live canvas exactly. -
Fix an early chunk in place.
easel show Nprints 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. -
Time-lapse.
easel frames onsaves a JPEG after every chunk inout/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
--grid [step]draws major and minor lines with the major values along the top and left edges, and the steps in the lower left corner (GRID 20 / 4 UNITS). It works on crops, mirrored looks (the labels still give true x) and--scalelooks.--probe x,y[;x,y...]reports the color there (hex and OKLab), the drying stage, the wet film in µm and, if a global holds a view (v = w:view()) or a world, what the eye sees there: sky, ground, water or body N, its distance and the point in meters. It also marks the points on the image.probe(x, y [, view])is the same in Lua. It returns{x, y, color, hex, L, a, b, value, drying, wet_um, world, what, body, at, dist, lit}(the world fields only with a view or world: the one passed, else the first global holding a view, by name, else one holding a world). It also marks its point (P1, P2...) in the next look.show(...)draws an overlay on the next looks. It never paints. It returns its first argument, sowork(show(m), {...})paints the mask and shows its outline.show(mask, {color=, label=}): the region, tinted by coverage and outlined at its 0.5 level.show(points, {closed=, label=, color=, dots=, numbers=}): a polyline (a polygon withclosed=true) with numbered vertices (up to 40), so you can say "move point 4 left 6".show(points, {width=8})or{brush=b, pressure=0.6}: the band a stroke of that width lays along the path (widthmay be one per point), with its center line.show(x, y, "label"): one point.show()clears the overlay.
- Which overlay you see. The first
show()orprobe()in a chunk (or atry) replaces the overlay; a chunk that shows nothing leaves it, andlookstill names the run that made it (from chunk 12,from try). An edit replays its chunks the same way, from the overlay the chunks before them left; a failed edit leaves the overlay as it was, and undo leaves it alone.look --show offhides it,--show onshows it again,--showtoggles and--show cleardrops it. Every look that draws one says so. easel try '<lua>'(also-f file,-,--look) runs a chunk exactly asdowould (it gets the same chunk number, so the same seeds), keeps what it printed and showed, then rolls everything back: the canvas, your globals, the brushes and the clock. It is not logged and your undo snapshots stay. Use it to preview shapes and probes and to print positions (w:spot,v:attables) without a chunk to undo later.- show() in the log. A
show()orprobe()inside a chunk youdois logged with the chunk. In a replay (easel run,easel check, a reopened session)show()draws nothing andprobe()only returns its table, so the painting replays exactly as if they weren't there. --crop x0,y0,x1,y1 --scale 3.2renders that window as it looks on a 3200 px canvas (--scale 3200works too): the real grain of a figure 45 units tall. The easel keeps a session painting a slightly larger window (30 units more on each side) at that width in the background and follows your log chunk by chunk, undos included. The first look at a new window replays the whole log once, which takes about as long as a replay at 1000 px. The look waits up to--wait 90seconds, then shows the latest state it has (it says how many chunks behind) or tells you to look again. After that, a look only waits for the chunks you ran since the last one, and any crop inside a kept window is immediate. Two windows are kept. The grid, probes and overlays work on these looks. A chunk that reads the canvas outside the window (sample,probe) sees less there than the live session does, as witheasel run --crop.
How chunks behave
- Globals persist, locals don't. Each chunk is its own Lua chunk. Write
sky = ...to useskylater;local sky = ...lives only in that chunk. - Units. The canvas is 1000 units wide and
1000 / aspecttall (WandHaftercanvas{}), y pointing down, whatever the pixel width. Angles are radians, 0 = left to right, π/2 = downward. - Randomness is deterministic.
math.random,rand(a, b)andrandn(mean, sd)are reseeded at the start of every chunk from the canvas seed and the chunk number.work,stipple,brushandtreepick their own seeds the same way (passseed=to fix one). A replay therefore paints the same thing, and a failed chunk doesn't shift the randomness of the next. - No OS access.
io,os,debug,require,dofile,loadfileandcollectgarbageare not available.printgoes to the reply. - Lua 5.5. Numbers are integers or floats (
7 // 2is 3,7 / 2is 3.5;math.typetells them apart), and whole numbers from the easel (W,H) are integers. Bitwise operators are built in (a & b,1 << 4); there is nobitlibrary and no globalunpack(usetable.unpack). Loop variables are read-only:for i = 1, 3 do i = i + 1 endis an error. Don't writeglobaldeclarations: oneglobal xswitches its chunk to strict mode, and then evenprintmust be declared. Plain assignment (x = 1) makes a global, as in older Lua. pairsandnextwalk a table in the same order in every session and every replay. A table keyed only by strings, numbers and booleans walks in Lua's own order. A table with any other key (a table, function, mask or other easel value) walks in a fixed order instead: booleans, numbers, strings (each ascending), then the other keys in the order your program created them. That costs a sort per walk, so for a big collection of objects a list andipairsis still the better choice.string.gmatchiterators survive rollback. An iterator kept in a global resumes where it was before a failed or undone chunk.- Colors are
"#rrggbb"strings,rgb(r, g, b)(0–255 sRGB) or color values frommix,gradient,sampleandpal:mix. A color value has.r .g .b(linear),.value(luminance),.L(OKLab lightness),:mix(other, t, mode)and:hex(). - Fields. Wherever an option takes a function of
(x, y)(a color, an angle, a coverage), it's sampled every 2 units over the area being painted and interpolated. That's fine for gradients and noise but not for single-pixel detail; use masks for hard edges. Mask functions (mask(fn)) run at every pixel. Both cost about 0.1 s at 1000px. - Engine errors are rolled back too. A mistyped option name is an error that lists the valid options.
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
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:
- Values.
t.limbs(trunk first:{pts, w, z, order, parent, twig}),t.clumps(back to front:{x, y, z, depth, r, squash, tilt, fill, lit, shade, turn, dead, limb}, depth from -1 at the back to 1 at the front),t.foot,t.fork,t.height,t.step,t.grain(mean clump radius),t.touch_w(a good pointed-brush width),t.bounds,t.crown,t.species,t.seasonandt.detail. - Masks.
t:leaves()ort:leaves{depth={lo, hi}, lit={lo, hi}, turn=, dead=}(clumps by depth or light),t:light()(0..1 on the leaves),t:lit(from)andt:shade(from)(default 0.55),t:gaps(reach)(sky through the crown),t:wood()ort:wood(lo, hi)(the wood where it is that wide, sot:wood(7)is the trunk and stout limb bases),t:trunk(),t:mask()andt:crown_mask(). - Touches.
t:touches{lit=, depth=, turn=, dead=}gives{pts, w, lit, z, depth, turn, dead, clump}.t:paint(brush, {color=, lit=, depth=, turn=, dead=, share=1, every=10, load=0.8, pressure={0.75, 0.05}, ramps=, shake=, clip=, fit=true})lays them back to front, with the brush pressed to each touch's width.colormay befunction(touch)(autumn: mix bytouch.turn).sharelays a deterministic part of them. Thelitranges are half open. - Wood strokes.
t:paint_wood(brush, {color=, min=, max=, detail=, twigs=true, every=5, pressure=, ramps=, shake=, clip=})strokes the wood whose local width is in[min, max), each stroke starting on the wood it leaves from and pressed to the width along it (see "A bare tree holds together" above).pressureis the pressure at a tip (where the brush lifts off);rampsdefaults to no attack and a short lift at tips only.twigs=falseleaves out the fine twigs past the model. - Wood strokes as data.
t:wood_strokes{min=, max=, detail=}gives the strokespaint_woodlays ({pts, w, tip, fine, limb}), to stroke by hand. - Twig mass (not recommended, see above).
t:twig_mass(detail): the fine wood not drawn atdetail(defaultt.detail) as a soft tone, 0..1.
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 mass: the outline inflated into a pillow, round for granite and boxy for sandstone and chalk. It turns away at your line;
- planes: cut into the mass, rim planes along the outline's spans (arrises run in from its corners) and face planes over the inside (upper ones turned to the sky, lower ones to the ground);
- your lines: each one splits a fracture into two planes facing different ways, and each crack also cuts a groove;
- joints: grown from the outline's concave corners;
- by kind: bedding for sandstone, flutes for chalk.
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=}:
outline: a closedoutline{}or points. Its corners (marked"c"or found on the line) split the rim into planes.corners=adds more.cracksandplanes: lists of lines (anoutline{open=true}or points). A crack is a joint with a groove. A plane line is an arris where two planes meet (no groove).kind:"granite"(or"erratic"),"sandstone"or"chalk".sun: a direction{x, y, z}toward the sun, a light table as forform{}(from=, front=, ambient=, bounce=, bounce_from=, penumbra=) or aworld{}, whose sun it uses.- Override the kind's numbers:
round: arris rounding (fraction of R, the inradius). 0.035 for granite, 0.02 for fresh sandstone.facets: face planes.profile: the mass. 2 is round, 4 is boxy.sink={lo, hi}: how deep planes cut; deeper cuts make bigger planes.tilt={lo, hi}: how far planes turn.bulge.bed: bed thickness in units (0: none), withbed_tiltandbed_recess.crack_depth,crack_width.joints: the share of concave corners that grow a joint.lumps,grain,flutes.ground: the ground's foreshortening, z per unit down. Smaller means you look down on it more, and the cast shadow comes out taller.
What you get:
- Masks:
r:mask(), exactly your line.r:lit(soft)andr:shadow(soft), the light and shadow families.r:halftone(),r:core()(the core shadow just past the terminator) andr:reflected()(reflected light in the shadow family).r:value(), the light as one value, 0..1. It is darkened by occlusion. Usev:at(x, y)in color functions.r:occlusion()andr:cracks().r:up(lo, hi), the faces turned up to the sky (the "upper face" mask).r:snow{amount=, depth=, seed=}, up faces broken by noise, plus a cap over the top edge.r:plane(i)andr:arrises()(convex breaks).r:contact{inside=, outside=}, the seam at the foot and the contact shadow under it.r:cast(), the rock's shadow on the ground around it.
- Fields for
work{angle=}:r:field("plane")(down each plane: one direction per plane),"fall","across","crack"(along the nearest seam or bed joint) and"bed". - Numbers:
r:levels(lo, hi), the rock's values at those quantiles.r:sample(x, y):{n, z, plane, turn, direct, cast, bounce, sky, value, lit, core, reflected, ao, crack, up}.r:bend(x, y, span),r.r,r.bounds,r.baseandr.foot(the outline's stretch on the ground).r.planes:{kind, n, fall, turn, value, up, area}per plane.r.seams:{pts, crack, grown}for every drawn, grown and bed line.
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
canvas{}, thenw = world{...}andsk = w:sky{...}(and clouds).- The sky, thin, in long strokes, then
blend;wait(24*60). - The distance: ranges far to near, each hazed by
l:haze; mist stippled over their feet. - The ground as tone, colored by distance (
w:to_ground,w:aerial). - The motifs: bodies and proxies placed in the world,
v = w:view(), then shadows and contact, trees (limbs, then foliage dark to light), rocks fromv.form, meadows fromsward. - The small particulars last, with small rounds and riggers (
point=1for a tip that draws down to a hairline): twigs, blades, flowers, figures. 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}
- The time comes from what the brushes actually did: each stroke from its
length and the brush's width (Fitts's and the steering law: fine lines
are slow per mm, broad sweeps fast), each stipple touch (about 3 a
second), each trip to the palette (2.5 s to reload from a pile already
mixed, 20 s more to mix a new one) and each wipe. A 10 cm sweep with a
12 mm flat takes 0.6 s, a 3 mm hatch 0.4 s and a 10 cm hairline 4.6 s.
The fir wood in
notes/loops/l5_near.luawould be 53 hours. work,blend,stipple,glazeand pencil lines put their time on the clock when they finish. A long pass is painted in slices of 15 minutes and ages between them, top to bottom. Brush strokes, touches and the motif verbs made of them put theirs on once a minute has piled up, and every chunk ends with the clock up to date.- A sitting ends at its length. Once its time reaches its hours, the
easel refuses marks (strokes, touches, motif verbs,
work,blend,stipple,glaze, pencil lines,varnish):the sitting is over after 3.0 h: rest(hours) first. Queries (timesheet,clock,drying,look) still answer. A verb already started finishes its pass (not cut short, so a long pass started late runs over), and the reply reports the overrun (sitting 2: 3.8 h at the easel, 3.0 h planned; ...). A refused chunk is rolled back whole: plan chunks by the time left (t.hours*60 - t.sitting).sitting{}can't end a sitting under way (only a rest can) andhand_time(false)is refused once it is on. - This holds for every session the easel starts (its log says so in a
header line,
-- sittings enforced: ...). Logs from before have no such line and replay as painted, overruns only reported (notes/time.md). - In one sitting the paint under a later passage is still open and comes
up into it. Lay each passage only where it shows, a little past where
its neighbor will meet it (
notes/time/example_three_ways.jpg). - Old paintings don't use hand time and replay exactly as before.
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)
canvas{}(the primed linen) ≈ 3 s; a broad sky pass with a blend ≈ 6 s; a body passage ≈ 1–1.5 s; a stipple pass ≈ 0.2 s; hundreds of brush strokes along tree limbs ≈ 0.05 slook≈ 0.04 s,look --dried≈ 0.3 s;--grid,--probeand overlays add under 0.1 slook --scale 3.2on a new window: about a replay of the log at 1000 px (masks stay whole-canvas at 3200); after that, only the chunks run since the last look, at crop cost- replaying the example: 18–29 s at 1000px (see notes/easel.md for 3200px)
- creating Lua tables and closures costs about 15% more than in plain Lua
(the easel numbers them for
pairs); arithmetic is unaffected - rollback bookkeeping ≈ 1 µs per live Lua table per chunk (a tree's 4,000
tables: under 5 ms; a meadow of 9,000 tufts kept in a global: 0.1 s). Keep
big lists
localwhen later chunks don't need them. w:view()≈ 0.3 s,w:sky{}≈ 0.2 s,w:clouds{}1–4 s (cell 2–3)- the first depth mask or depth option on a view ≈ 0.1–0.5 s (traced once),
each further one ≈ 0.05 s;
cast_shadowandcontact_shadow0.1–1 s easel edit 5in a 30-chunk log: 30 s against 47 s to reopen and 62 s foreasel run(notes/depth.md)
Limits
- Rollback restores everything reachable from your globals: tables, their
metatables, the variables your functions close over and
gmatchiterators. A coroutine suspended across chunks is not restored. After a rollback that restored a string-keyed table the failed chunk had changed,pairsover that table may visit keys in a different order than a replay would;easel checkdetects this, andipairs, numeric loops and tables with object keys are unaffected. - A table that once held object keys and then lost them all may keep an
order that depends on the process until it grows again. Build a fresh
table if you rely on its
pairsorder. - Sessions paint the whole canvas.
look --crop ... --scale 3.2keeps a window painted at 3200 px that follows the session;easel run --croprenders a window of a finished program.