# Material v5: physical paper, water, pigment and brush

New sheets (`watercolor-standard-v2`) use `paper-brush-v5`. It simulates the material, not the look: a water film that flows and dries, fibres that absorb it, pigment particles that ride the flow, settle, stain and granulate, a brush made of hair that holds a finite charge, and Kubelka-Munk optics. Edges, blooms, granulation and dry-brush breaks are not settings. They happen when you create the physical conditions for them, as with real paint. This page lists those conditions.

One control is deliberately unreal: the drying clock. Layer `environment:{drying:"hold"}` stops drying (flow continues); `"fast"` is a hair dryer (evaporation six times faster). Everything else runs at its own rate.

Drying times, wet-in-wet spread, and how much each paint stains are matched to painters' published measurements (handprint.com: a wash is shiny for about 2 minutes, loses its sheen at about 4, is dry at about 20; the swab test ratings of each pigment). Other constants are estimates. The numbers below were measured on this simulation (`scripts/v5-techniques.mjs`, `artifacts/material-v5/techniques.json`), standard paper, 384-cell test grid. Treat them as starting points for your own trial, not recipes.

## Brush fields on v5

- `water` 0-1: how charged the brush is (default 0.6). A charged round comes to a point; a dry brush opens into clumps and skips the paper's valleys.
- `opacity` 0-1: how much paint is in the mix. 0 is clear water, about 0.5 is one full-strength wash, 1 is almost tube paste. Dry brush needs a high value, because little water carries the paint.
- `duration`: time the stroke takes. A fast stroke leaves less water and breaks up; a slow one floods.
- `pressure`: lays more hair down. A round needs pressure to widen; a flat is full width at any pressure.
- `tilt`, `angle`: lean and ferrule direction. Scalar marks lean along the travel and hold a flat across it unless `angle` is given.
- `tip`: `round` (sable), `flat`, `fan`, `liner` (rigger), `hake` (wide goat hair), `mop` (squirrel, holds the most water), `hog` (stiff bristle, scrubs). Customise with `{preset, bristles, length, point, stiffness, capacity, spread, thickness, shape}`; see schema.json for ranges.
- `pigment`: a named paint or a mix of up to four `{name, part}` (`part` 0.01-1, relative amounts). Without it, `color` is a transparent paint; `granulation` sets its coarse share (default 0.15) and `staining` the share of its fine particles that bond to the fibres (default 0.45).
- `supply:{model:"brush-v5", id, action}`: keep one brush between marks. `continue` paints with what is left, including colour it has drunk from the paper; `reload` rinses and recharges.
- Not accepted on v5: `dry`, `load`, `lift`, `texture`, `softness`, `dynamics`. Their effects come from water, pressure, speed and the brush.

## Other tools and the board

- `{type:"spatter", points, spread, drops, size, opacity, color|pigment}`: flicks drops from a loaded brush around each point. `spread` is the scatter radius as a fraction of sheet width (0.001-0.3), `drops` per point (1-400), `size` the median drop diameter in mm (0.2-4). Drops on wet paper soften; on dry paper they dry with rims.
- `{type:"salt", points, spread, grains, size}`: salt crystals (`size` 0.2-3 mm). Each dissolving crystal draws water, and the paint still loose in it, from a zone about 2.5 crystal widths across, leaving a pale star. Pigment near the crystals, relative to the wash away from them: 0.69 when salted on a shining wash (30 s), 0.55 at 150 s, 0.49 once the sheen has gone (240 s), 0.48 at 420 s while the paper is still damp. On dry paper salt does nothing.
- `{type:"mask", points, width, pressure?, duration?}`: masking fluid along a path. It sets over 600 drying-clock seconds (100 s under `fast`). Once set it keeps water and paint off the paper; a wet brush drawn over it before then smears it away. Let it set before painting over it.
- `{type:"unmask"}`: peels all masking fluid; the paper under it is as clean as when the fluid went on. Remove it only after the paint around it is dry.
- Layer `environment:{tilt:0..60}`: raises the top of the board by that many degrees. Wet paint runs down the sheet from about 6°; at 15° or more backruns cannot form, because water collects at the bottom edge of the wash instead. Flat again with `tilt:0` (or no tilt) on the next layer.

## Paints

| name | opacity | granulation | staining | left after 5 wet scrubs |
|---|---|---|---|---|
| french-ultramarine | transparent | strong | low | 0.16 |
| phthalo-blue | transparent | none | very high | 0.89 |
| cerulean | opaque | moderate | moderate | 0.38 |
| viridian | transparent | moderate | low-moderate | – |
| sap-green | transparent | none | high | – |
| hansa-yellow | semi-transparent | none | high | – |
| yellow-ochre | opaque | mild | low | 0.24 |
| cadmium-red | opaque | none | high | – |
| quinacridone-rose | transparent | none | high | 0.81 |
| burnt-sienna | transparent | mild | high | 0.65 |
| raw-umber | semi-opaque | mild | moderate | 0.49 |
| lamp-black | opaque | none | very high | – |
| chinese-white | opaque white | none | moderate | – |

Granulation and staining follow the handprint.com ratings of each pigment. The last column is the handprint swab test run on this simulation: a dried swatch rewetted and scrubbed with a stiff brush five times. Real paints rated low keep 5-15 % of their colour, moderate 30-50 %, very high over 75 %.

Opaque paints cover darker paint beneath them; transparent ones darken it. White is paint, not an eraser: over dark paint it reads milky. Mix on the brush (`pigment:[…]`) to get mixtures that separate as they dry, such as ultramarine with burnt sienna.

## Timing on standard paper

| stroke | shine gone | paper dry |
|---|---|---|
| flat, water 0.6 | 1.8 min (108 s) | 13 min (759 s) |
| mop wash, water 0.9 | 3.4 min (205 s) | 18 min (1103 s) |

"Shine gone" means no surface film remains; the fibres are still damp. Blooms, lifting and wet-in-wet all depend on which of these states the paper is in: shining, losing its sheen, damp, or dry. A scene may spend 7200 material seconds. Waiting for a wash to dry naturally is often right, because it is what lets granulating paint granulate and smooth paint stay smooth; `fast` drying reaches "dry" six times sooner but gives every paint the same fine mottle.

## Behaviours and how to cause them

**Hard edge with a dark rim.** Paint a charged stroke on dry paper and leave it alone. The film is pinned where the brush left it; water evaporates fastest at the edge and pulls pigment outward. Measured rim/centre 1.35-1.65 for a flat stroke (the two edges differ with the paper under them), 1.4-1.65 for ultramarine, 1.4-1.55 with a charged mop. Touching the stroke again while it dries disturbs the rim.

**Soft edge / wet-in-wet.** Wet the area first (`opacity:0`, `water:1`), then drop paint into it. Colour spreads only as far as the water. Spread diameter for a 4.8 mm brush dropped into a clear-water wash:

| wait after wetting | spread |
|---|---|
| 0 s | 27 mm |
| 60 s | 26 mm |
| 120 s | 23 mm |
| 180 s | 16 mm |
| 240 s | 14 mm |

Colour flares widely into shining paper and stays closer to the brush as the sheen goes.

**Bloom (backrun).** Drop clear water or wetter paint into a drying wash. What you get depends on the stage (mop wash on standard paper, shine gone at about 3.5 min):

| wait before the drop | centre pigment vs untouched |
|---|---|
| 30 s | 0.72 |
| 120 s | 0.82 |
| 180 s | 0.82 |
| 240 s, sheen just gone | 0.84 |
| 300 s | 0.87 |
| 420 s | 0.96 |

While the wash shines the drop makes a soft pale spot. As the sheen goes, the spot lightens less but its front dries into a ragged dark ring: the cauliflower bloom. The centre number does not capture that ring; look at the image.

Paint that is only damp is still loose; the new water pushes it into a ragged front that dries hard. To avoid blooms, do not add water to a wash that is losing its shine. To make one, drop the water just as the shine goes.

**Granulation.** Choose a granulating paint (`french-ultramarine`, `cerulean`, `viridian`) and let it dry undisturbed and naturally. Coarse particles slide into the paper's valleys as the film thins. Variation inside a test stroke left to dry naturally: ultramarine 0.30, cerulean 0.24, phthalo blue 0.10, quinacridone rose 0.12. Dried with `fast`, all four came out alike (0.30-0.43): the hair dryer hides the difference between granulating and smooth paints.

**Dry brush.** Use little water, strong paint (`opacity` 0.7-0.9), a fast stroke and light pressure. A stiff `hog` or a `fan` breaks up most. Paper covered by a quick hog stroke:

| water | covered |
|---|---|
| 0.10 | 21 % |
| 0.20 | 63 % |
| 0.35 | 68 % |
| 0.60 | 100 % |

**Lifting.** Use a clean, squeezed-out brush (`opacity:0`, `water` about 0.1), best a stiff `hog`, drawn slowly (`duration` about 3 s for 10 cm). Paint left after one pass:

| when | left |
|---|---|
| wash still shining (5 s) | 0.83: nearby wet paint flows back in |
| losing its sheen (150 s) | 0.74: the cleanest lift |
| damp, no sheen (300 s) | 0.92 |
| dry, lifted directly | 0.98 |
| dry, rewetted with a mop, 15 s wait, then lifted | 0.71 |

The rewet-and-lift pass left 0.51 of ultramarine but 0.94 of phthalo blue: staining paints stay. Repeat the pass, rinsing between, to lift more (see the swab column above). A stiff `hog` also scrubs dried paint: one slow clear-water pass removed 20 % of a dried layer; a soft `mop` pass removed 2 %.

**Glazing.** Let the layer below dry completely ("paper dry", or a `fast` drying layer), then pass over it once with a soft brush. A quick soft pass leaves the layer beneath intact. Lingering, repeated passes or a stiff brush lift and muddy it.

**Brush running dry.** A stroke drains the brush. Long strokes get paler and then break into streaks near the end. Reload (new mark, or `supply` with `reload`) before that point, or plan the break.

**Dirty brush.** A named brush that crosses wet paint drinks some of it. With `continue`, that colour goes into the next mark.

## Working speed

The simulation is heavy: a painting with a few minutes of material time takes minutes to compute from blank paper. In browsers with WebGPU the studio runs the simulation on the GPU, several times faster than the CPU version; results differ from the CPU version only in the last details. The studio also keeps a checkpoint at every layer boundary for this page session, so a preview that keeps the earlier layers identical resumes after them: appending a layer to a nine-layer painting took under a second instead of two minutes. Editing an early layer repaints everything after it. Work forward in layers; reload clears the checkpoints.

## Known limits

- Calibrated against published painters' observations (drying timeline, staining and granulation ratings, wet-in-wet spread), not against measured paper samples. Paper texture, flow and brush constants are estimates.
- Three optical bands, not a spectrum. Mixtures that depend on narrow absorption bands are approximate.
- Three particle populations per paint (fine staining, fine loose, coarse), not measured size distributions.
- A single thirsty pass on damp paper that has lost its sheen lifts little; real painters sometimes get more there.
- No cockling, alcohol, tissue blotting or scraping.
- The relief is a synthetic cold-press texture, not a scan.
- Rendering is at the 640-cell material grid, scaled to the 720 px output.