What the painters were given

The easel

notes/easel_guide.md · 475 lines · Guide

Given to 11 painters:

The easel

The easel is a live oil painting in a background process. You send it Lua chunks from the shell, one at a time, and look at the canvas as a small PNG between them. Under it is a physical paint simulator: simulated bristles carry wet paint over a primed linen canvas, the paint levels and dries on a clock, and layers combine by Kubelka–Munk optics.

Three things hold for every session:

Starting

The easel is the program bin/easel in this folder. The studio holds one painting, and every command works on it. Run the commands from this folder:

bin/easel open                                # start the session (2400 px wide), or reattach to it
bin/easel do 'canvas{size=400, aspect=1.25, linen=15, ground={{pile={{"lead white", 1}}, um=100, apply="knife"}}}'
bin/easel look                                # prints the path of a PNG of the canvas: read it
bin/easel note 'what I did and why'           # an entry in notes/journal.md
bin/easel save                                # the finished canvas: out/easel/painting/painting.png
bin/easel close                               # the log stays in paintings/lua/painting.lua
command what it does
bin/easel open starts the 2400-pixel-wide session, or reattaches to it if it is running. If paintings/lua/painting.lua exists, the session verifies and replays it first and goes on from there
bin/easel do '<lua>', do -f file.lua, do - runs a chunk. The reply is what the chunk printed, then ok · chunk N. Add --look to look afterwards
bin/easel look [...] writes a PNG of the canvas and prints its path (see Looking)
bin/easel log prints the painting so far (the log file)
bin/easel status chunks, width and the canvas's setup
bin/easel save writes the canvas as it is now to out/easel/painting/painting.png and prints the path
bin/easel frames on|off saves a look after every chunk in out/easel/painting/frames/
bin/easel check replays the log in a fresh session and confirms it matches the live canvas
bin/easel close ends the session
bin/easel note '<text>', note - adds an entry to your journal (see The journal)

The first chunk is canvas{}. When the painting is done, bin/easel save writes the picture to out/easel/painting/painting.png; the program that paints it is paintings/lua/painting.lua.

In the examples below, <tube> stands for a name from the tube box and <parts> for a number of parts you choose.

The canvas

canvas{size=400, aspect=1.25, linen={16, 14}, seed=1,
       ground={{pile={{"<tube>", <parts>}, {"<tube>", <parts>}}, um=100, apply="knife", texture=0.3},
               {pile={{"<tube>", <parts>}}, um=50, apply="brush"}}}

It sets W (1000) and H (1000 / aspect). The canvas is always 1000 units wide, whatever its pixel width. The origin (0, 0) is the upper left corner; x increases to the right and y downward. Angles are radians, 0 left to right, π/2 downward.

Tubes and piles

Paint reaches the canvas only from piles you knife together on the palette from the tubes in the box:

p = pile{{"<tube>", <parts>}, {"<tube>", <parts>}}
q = pile{{"<tube>", <parts>}, medium=0.3}
print(p)                         -- pile(<tube> <parts>, <tube> <parts>; medium 0)
print(table.concat(tubes(), ", "))   -- the names in the box

A pile is parts by volume of named tubes, plus medium: the share of oil medium mixed in (0, as from the tube, to 0.95). Medium makes the paint more transparent and more fluid, and slower to dry. What a pile looks like is what its pigments make together, thick or thin, over what is already on the canvas; you find out by painting with it and looking. A pile mixed by hand is a little uneven: each brushload takes slightly different proportions (about 6%). The palette has room for 16 piles; the oldest is scraped off to make room.

The tube box (all made by the 1820s):

tube pigment hiding stiffness tinting strength drying
lead white basic lead carbonate 0.82 0.8 1.0 2.0
smalt cobalt potash glass, coarse 0.3 0.55 0.45 1.6
pale smalt a paler grade of smalt 0.35 0.55 0.35 1.6
yellow ochre hydrated iron oxide earth 0.8 0.7 0.8 0.8
red earth iron oxide earth 0.85 0.7 0.9 1.0
vermilion mercuric sulfide 0.9 0.75 1.0 0.4
raw umber iron and manganese oxide earth 0.8 0.65 0.9 2.4
bone black charred bone (carbon, calcium phosphate) 0.9 0.7 1.1 0.4
cobalt blue cobalt aluminate 0.55 0.6 0.8 1.4
chrome yellow lead chromate 0.9 0.7 1.0 1.8
Prussian blue iron ferrocyanide 0.35 0.45 3.0 1.8
green earth celadonite and glauconite clay 0.2 0.35 0.3 0.8
Rinmann's green cobalt-zinc oxide 0.35 0.5 0.4 1.4
copper green verdigris ground in oil 0.25 0.4 1.0 1.6

Hiding is how much one coat of the tube paint hides what is under it (0 transparent, 1 opaque). Stiffness is the paint's body as it comes from the tube (0 fluid, 1 stiff). Tinting strength is relative to an average pigment. Drying is the rate relative to average paint (higher dries faster); a pile dries at its tubes' rates mixed by volume. These numbers are estimates from the pigment literature, not measurements.

Brushes and strokes

b = brush("filbert", 8)                  -- kinds: round, flat, filbert, fan, rigger, badger, stippler
b = brush{kind="round", width=3, point=1, stiffness=0.5}   -- also length, hair, run, lay, pickup,
                                                           -- push, splay, ragged, bristles
b:load(p, 0.8)                           -- dip into a pile: 0..1 of a full load
b:reload(q, 0.8)                         -- wipe most of the old paint off, then load
b:wipe(0.85)                             -- remove 85% of the paint onto 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(400, 300, {pressure=0.6, drag={1, 0}, twist=0.2, angle=0.3, clip=m})
b:mark_width(0.4)                        -- the width of a mark at this pressure (units)
b:pressure_for(0.5)                      -- the pressure for a 0.5-unit line

Widths are in canvas units. A brush keeps its paint across strokes and chunks, so strokes from one load run dry, and a brush that has been through wet paint carries some of it. Pressure ranges from 0 (lifted) to 1 (fully pressed); a stroke's pressure is {start, end}. ramps gives the press-down and lift-off fractions, swell pressure factors along the stroke, orient "across", "along" or a fixed angle.

Brushes are blunt unless given a point (0 blunt, 1 a full point). A pointed round or rigger lays a hairline at light pressure and spreads to its belly when pressed, so its width follows the pressure and a stroke whose pressure falls to 0 ends in a point.

Covering an area

work(m, {hand="body", pile=p, angle=0.3, coverage=3})
blend(m, {angle=0})                      -- a clean blender over wet paint (= work with hand="blend")
stipple(m, {pile=p, width=3, coverage=1.2})
work(m, {hand="glaze", pile=q})          -- a thin layer brushed on with a soft brush
lose(m, {pile=p, where=0.5})

work covers a mask with strokes of a real brush, planned the way a hand lays them. hand picks a starting handling, which the options below change:

hand tool strokes
broad filbert 22 80–220 units, bowing in long arcs, direction wandering over 350-unit patches
body (default) filbert 9 20–60 units
detail round 2.2 4–14 units, clipped to the mask
hatch round 2.6 5–12 units, nearly straight, side by side, clumped
glaze soft filbert 26 120–300 units, light pressure
scumble filbert 9 10–20 units, worked back and forth
blend badger 40 a clean blender, crossing passes top to bottom, inside the mask
option meaning
pile the pile every stroke dips into (every hand but blend)
tool "filbert 8", {kind=, width=, ...} or a brush
length {min, max} stroke length in units
coverage layers of strokes over each point on average
angle stroke direction: a number or function(x, y)
pressure, ramps {min, max} pressure; attack and release fractions
dips {strokes per trip to the palette, load, wipe before dipping}
load, load_at load per dip; a number or function(x, y) that varies it
edge how the passage meets the mask's edge (below)
clip true: every bristle stops on the mask's edge; or a mask to clip to
hug true (default): strokes reach the mask's edges; false lets coverage thin there
fill false by default: gaps between strokes stay. Set true to follow the strokes with dabs into the gaps they left
order "passages" (default), "scatter", "down", "across" or a sweep angle
angle_jitter, curve ({bow, wave}), cross, drift ({amount, scale}), tail, broken, swell, clump, ruler how far the strokes depart from even ruler lines (ruler=true sets them straight and even)
orient, shake, threshold, cut_in (a tool), scrub, blender, mix_jitter, seed the brush's orientation, the hand's unsteadiness, the mask level strokes start at, cutting in the edge with a second tool, back-and-forth strokes, a clean brush, how uneven each dip of the pile is, the randomness

Where an option takes function(x, y), it is sampled every 2 units over the area and interpolated. A mistyped option is an error that lists the valid ones.

Edges. edge= carries the passage up to the mask's edge the way a brush does: each stroke stops by its own amount, and past the line its film thins out over the weave. It takes a number from 0 (found: crisp) to 1 (lost: the passage runs well past the line and dissolves), a name ("found", "firm", "soft", "loose", "lost"), a function of (x, y), a mask, or a table: {found=, soft=, lost=, period=40, seed=} lays those shares out along the contour in runs about period units long; waver= and reach= scale how far the line wanders and how far strokes run over. It can't be combined with cut_in.

stipple(m, {...}) lays many small touches of a tip, each through the bristles: pile, width (a stippler's width, 2 by default) or tool, coverage (touches per point; a number or function(x, y)), pressure {min, max}, dips {touches per dip, load, wipe}, drag (how far the tip moves while down: a number or {length, angle}), twist, cluster (0 even .. 1 in clumps, or {amount, size}), feather (0 by default; above 0, touches get lighter where coverage is below 1), clip, mix_jitter, seed.

lose(m, {pile=, where=, ...}) drags a lightly loaded brush across the mask's edge from the outside in, where where (as edge=; 1 by default) is high: short strokes start outside, cross the edge at a slant (or at angle) and lift off inside. Also tool ("filbert 4"), reach ({out, in} units), load (0.2), pressure ({0.35, 0.02}), every (a stroke every 1.2 brush widths), seed. It returns the number of strokes.

work, blend and stipple also take visible=, behind=, at= and view= (see Depth).

Masks and geometry

Masks are coverage maps (0..1) of the whole canvas. Operations return new masks.

everywhere()   rect(x, y, w, h)   ellipse(cx, cy, rx, ry)
poly({{x, y}, ...})   poly(pts, true)                  -- true: smoothed
below(function(x) return 400 + 30 * math.sin(x / 90) end)   -- under a curve (or a point list)
above(curve)
ribbon(points, widths)   ribbon(points, 3)             -- a band along a line
mask(function(x, y) return x < 500 and 1 or 0 end)    -- any function, at every pixel
m + n   m * n   m - n   -m                             -- union, intersection, difference, inverse
m:roughen(units, period, seed, edge)   m:soften(units)   m:blur(units)
m:grow(units)   m:shrink(units)   m:offset(units)   m:rim(width, soft)
m:distance()   m:band(lo, hi, soft)   m:times(fn or mask)   m:map(function(v) return v * v end)
m:at(x, y)   m:area()

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

Numbers and randomness: rand(a, b), randn(mean, sd), math.random, lerp(a, b, t), clamp(x, lo, hi), smoothstep(a, b, x); noise{seed=, octaves=4, period=200, persistence=0.5, kind="fbm"|"ridged"|"billow", warp={period, amount, twice}, stretch={angle, k}} (call it as n(x, y) for about -1..1, n:at01(x, y) for 0..1; it can be passed to coverage= or load_at=); worley{seed=, period=, jitter=} (c:at(x, y) gives the distances to the nearest two cell points, how near a cell wall, and a stable 0..1 per cell); uneven(n, lo, hi, irregular, clump, seed) (n positions from lo to hi with uneven, clumped gaps).

Drawn lines. outline{pts... or pts=, char=, seed=, closed=, open=, corners=, corner_angle=60, size=, amount=, lobe=, edge=} turns a few points into a line drawn by hand (a smooth curve through them, broken at corners marked "c", with a hand's irregularity) and its mask:

o = outline{{300, 600, "c"}, {320, 450}, {420, 380, "c"}, {560, 400}, {650, 480, "c"}, {500, 620}, char="firm", seed=3}
work(o:mask(), {hand="body", pile=p})
o:paint(b, {pressure=0.8, dip={p, 0.6}, every=3})   -- stroke the line itself
char the line
firm (default for outline) long strokes, slight overshoots, a crisp mask
searching short strokes restated a little off each other, running past corners
broken straight facets and chips in broken stretches between quiet ones
soft (default for body_of) lobes of two sizes, light broken strokes, a mask edge lost in places

amount scales the irregularity (0 is a clean curve), lobe sets the lobe width in units, edge the mask's soft edge in units. An open line's outside is on its left. body_of{spine=, widths=, limbs={{pts..., widths=}, ...}, blend=0.8, char=} is the silhouette of a skeleton of points and widths. Methods: o:mask(), o:below(bottom), o:above(), o:band(width, taper), o:inset(d), o:offset(d), o:paint(brush, {...}), o:path(i), o:paths(), o:strokes(), o:at(t), o:length(), o:corners().

Drawing: pencil, chalk and eraser

h = pencil("2H")                  -- or pencil{grade="2H"}: 9H..H, F, HB, B..9B
c = chalk()                       -- black chalk
h:sketch(pts, {pressure=0.3})     -- a few light passes (passes=3, wander= units, smooth=true)
h:line(pts, {pressure={0.5, 0.7, 0.4}})    -- one line through the points (smooth=false keeps corners)
h:rule({0, 400}, {1000, 400}, {pressure=0.3})   -- straight, against a ruler
h:hatch(m, {angle=-1.1, pressure=0.35})         -- short parallel strokes (spacing=, length=)
h:width()   h.worn   h:sharpen()  -- the point blunts as you draw
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_guide()                      -- the drawn lines themselves, as a continuous mask

The point rides on the tops of the weave; pressure lets it reach into the hollows. Soft leads lay darker, glossier lines, hard ones pale silver lines. The eraser lifts most of a line, more from the tops than the hollows, and leaves a ghost. Once paint has gone over the drawing it is sealed: thin paint lets it show through, body paint hides it.

Solids, light and space

These are scaffolds for shapes you give them: they answer where light and shadow fall and what lies in front of what. They paint nothing.

Form. Solids in canvas units, z toward you, lit by one light:

s = body.ellipsoid({400, 500, 0}, {120, 90, 80}):turn({400, 500, 0}, 0.3, 0.1, 0)
      :cut({400, 430, 0}, {-0.3, -1, 0.4}, 1, 3):rough(6, 120, 1)
k = body.block({650, 520, 0}, {160, 60, 90}, 3)       -- center, size, rounding
t = terrain{area={0, 400, 1000, 800}, height=function(x, y) return 10 * math.sin(x / 60) end}
f = form{ {s, dist=0.3}, {k}, light={from={-1, -0.7}, front=0.5, ambient=0.2} }
f:value(x, y)   f:lit_at(x, y, soft)   f:part(x, y)   f:sample(x, y)   f:fall(x, y)   f:across(x, y)
f:lit{parts={1}, soft=0.12}   f:shadow{parts={1}}   f:silhouette{parts={1}}   f:edges{turn=0.8}   f:parts_mask{1}
work(f:lit{parts={1}}, {pile=p, angle=f:field("fall")})   -- field("fall"|"across"|"edge") for angle=

Solids combine with s:union(o) and s:subtract(o); body.half_space(at, normal) cuts. The light also takes bounce, bounce_from, penumbra, reach, thickness and across_parts.

World. A space in meters seen in perspective: a camera over a supporting surface, one directional light, and the bodies you place there. A flat plane with one block:

w = world{eye=1.6, fov=45}               -- camera height (m) and field of view (degrees)
s = w:spot(500, 600)                     -- the plane seen at a canvas point (or w:spot_at(X, Z))
w, n = w:place(s, body.block(s:p(0, 0.5, 0), s:size(1, 1, 1), s:m(0.05)))   -- meters to units
v = w:view()                             -- trace once and keep it
v:bodies_mask{n}   v:shadows()   v:contact(0.25)   v:at(x, y)   v.form
w:to_ground(x, y)   w:project(X, Y, Z)   w:scale_at(Z)   w:height(x, y, meters)
w:shadow_angle(x, y)   w:sun_canvas()   w:ribbon(pts, width)   w:recede({X, Z}, {dX, dZ}, n)

world{} takes, all optional: view (the canvas rectangle it covers), horizon (the canvas y of eye level), eye, fov, ground (a function (X, Z) giving the surface's height in meters; flat by default), water ({level=, ripple=}: a level reflecting surface), sun ({azimuth=, elevation=} in degrees: the light's direction; azimuth 0 is straight ahead, -90 to the left, 180 behind you), visibility and backdrop. With water, v:water() and v:mirror(x, y) say where it is seen and what it reflects; v:land() and v:sky() are where the surface and the space above it are seen. w:proxy(s, body) places a body that casts a shadow but isn't seen. w:aerial(Z) and aerial(dist, visibility) give how much air lies between the eye and a distance (0..1).

Depth. A view knows what lies behind what. w = w:layer(name, mask, depth) registers a shape you paint by hand at a depth (meters, a spot, a canvas point {x, y} where it stands on the ground, or "ground"); make the view after it. Then v:visible(x), v:front(x), v:behind(x), v:at_depth(m), v:between(a, b) and v:seen(x, y) are masks and answers, and v:cast_shadow{soft=, from=} and v:contact_shadow{reach=, from=} are shadows that fall off with distance from what casts them. Things are named by body number, layer name, "ground", "water", "surface", "sky", "bodies", "layers", a mask or a list. Passes take visible= (only where that is seen), behind= (only where nothing in front of it is) and at= (a depth in meters): strokes still overrun the mask's own edges, never what is in front.

Time

Painting takes time, and paint dries on the painting's clock. Only painting operations (strokes, touches, passes, trips to the palette) and wait(minutes) advance it. Real time between commands does not: paint doesn't dry while you think. wait(minutes) passes painting time at once; it doesn't make you wait that many real minutes.

Each film dries at its own pace, set by its pigments, its thickness and its oil. Thin lean paint of fast-drying pigments is touch-dry in a day; thick, oily paint of slow pigments can stay open for weeks. Wet paint under a new stroke comes up into it; paint laid over dry paint sits on top of it.

Finishing (optional)

Each of these is optional.

varnish{coats=0.4, vary=0.12}     -- a mastic varnish film over the whole canvas, as it looks aged
cracks{}                          -- craquelure through paint and ground
relief(0.3, 0.02)                 -- light the surface's relief from the upper left

Each needs all the paint on the canvas to be touch-dry. cracks{} grows cracks one at a time from the film's stress, fitted to this canvas's ground; its options are island_mm, ground_um, width_um, depth_um, cupping_um, dirt, corners, vary, veil, hierarchy, patchy, grain, grime and seed.

Looking

bin/easel look prints the path of a PNG of the canvas as it is now, with wet paint as laid. The live canvas is 2400 pixels wide. A whole view is scaled down to at most 1600 pixels on its long side and kept below 3 MB, like stepping back. A crop shows the original pixels at 1:1 and may be at most 1200 pixels on either side. --crop x0,y0,x1,y1 gives two opposite corners in canvas units, not a position and width/height.

bin/easel look --crop 300,200,500,350          # a window in canvas units, shown at 1:1 pixels
bin/easel look --mode value                    # in grays
bin/easel look --mode squint                   # blurred, as through half-closed eyes
bin/easel look --mode mirror                   # flipped left to right
bin/easel look --mode value,squint --size 600  # modes combine; --size sets the long side
bin/easel look --grid                          # a squared grid in canvas units, labeled along the edges
bin/easel look --crop 300,200,500,350 --grid 10

The grid is drawn on the PNG only, never on the canvas, like the squares ruled over a drawing to transfer it.

How chunks behave

The journal

notes/journal.md is your working journal. bin/easel note '<text>' (or bin/easel note - to read the text from stdin) appends an entry stamped with the session's painting time, such as day 2, 09:40; the session must be open. Entries already there stay as they were written; writing a note doesn't advance painting time.

The log

bin/easel check replays the log in a fresh session and compares it with the live canvas. The log, paintings/lua/painting.lua, is plain Lua with a line --@ chunk N before each chunk. The easel keeps a record of it in out/easel/painting/committed.lua. If the log is changed, shortened or missing, the easel refuses to continue.

Source