Workflow: crop renders, checkpoints, speed (stream 3, branch workflow)
Goal: a fast feedback loop, so a painter can afford tiny details. Before this branch, the only way to see a detail at full resolution was a whole 3200px render (friedrich_moonrise_valley: 107–145 s here, under a load average of 20–130 from the other streams), and every run repainted every stage.
What landed:
- Crop renders:
--crop x0,y0,x1,y1(units) paints only that window, at the run's full resolution. They are fast, and close to a whole render (not exact; the reasons are below). - Stages and checkpoints:
--ckptsaves the complete canvas state after every stage and--resume <stage>starts from one. Resuming is bit-exact, and stale checkpoints are refused. - Speed, with the output unchanged: an exact per-column memo for 1-D profiles (cuts mask cost in crops) and a dependency-ordered tile scheduler in place of phase barriers.
- Not done:
--frames(the "watch Claude paint" time-lapse).
All timings below were taken on the shared 10-core machine with the other four streams running (load average 17–130). They are wall-clock times and noisy; compare within a row, not across rows.
The fast loop
cargo paint friedrich_moonrise_valley -- --full --crop 280,440,460,580 --ckpt # once, 14 s
cargo paint friedrich_moonrise_valley -- --full --crop 280,440,460,580 --resume mist
# 1.6 s per iteration
| moonrise, the two figures on the ledge | time |
|---|---|
| whole canvas, 3200px | 86–145 s (load 14–110) |
| crop 180×140 units (576×448 px) at 3200px, margin 40 | 13–14 s |
| the same crop, resumed from "mist" | 1.6 s |
| whole canvas, 1000px preview | 16–21 s |
| 1000px preview, resumed from "mist" | 1.1–2.7 s |
Painter API
paintings/src/run.rs (module docs have the full list):
let o = Run::new("my_painting");
let mut rng = Rng::new(o.seed);
let mut c = o.canvas(|| st.prepare(o.width, 1.4, o.seed)); // loaded instead on --resume
let f = c.frame(); // whole-canvas frame for masks
let ridge = f.per_column(|x| h * 0.6 + 12.0 * n.get(x, 0.0)); // optional: exact memo
let sky = Mask::from_fn(f, |x, y| ...); // outside stages: always runs
if o.stage("sky", &mut c, &mut rng) {
c.work(&sky, ...); // skipped when resuming later
}
if o.stage("land", &mut c, &mut rng) { ... }
o.finish(&mut c, &Finish::aged(st.relief));
stage(name, c, state)begins a stage and ends the previous one. Ending a stage prints its time, writes its checkpoint with--ckptand stops the run with--stop name. It returns false when a resumed run should skip the stage.- Rules: paint only inside stage blocks. Code between blocks runs on every
run, resumed or not, so keep it to masks, fields and constants. Anything a
stage hands to later stages must travel in the canvas or in the
Keepstate (usually the painting'sRng;()and pairs also implementKeep). - Migration for other streams' paintings: the old
if o.stage(&mut c, "x") { return; }came after a stage's code. Now putif o.stage("x", &mut c, &mut rng) {before that code and}where the old marker was, and hoist any value a later stage uses (moonrise hoists the moon's position).friedrich_moonrise_valleyandfriedrich_monk2are converted. Their output is unchanged by the conversion, but see the palette fix below. --cropneeds no painting changes.Run::newcallspaint::set_crop, andCanvas::newpicks it up. An explicit form isCanvas::new_window(px, aspect, ground, Some(Crop { units, margin })).
Crop renders: how they work
Frame gained a window: w × h are the pixels a buffer holds, at origin
(x0, y0) in the whole full_w × full_h canvas. width() and height()
stay whole-canvas units, and all px↔unit conversions go through
Frame::{index, ux, uy, whole, clip, whole_index}. For a whole canvas every
formula reduces to the old arithmetic, so the golden fingerprint did not move.
- Masks stay whole-canvas:
c.frame()returns the whole frame andc.window()the buffer's. So stroke planning runs over the whole canvas with the same RNG sequence, the same tiles and the same stroke ids. Tiles whose footprint misses the window are skipped. The cost is that mask building and planning scale with the canvas, not the crop. See speed below. - Brush geometry stays in whole-canvas pixels (
bristle::exchange), and only buffer indices are translated. A crop therefore does the same float arithmetic as a whole render for every pixel it holds. - Where a bristle's contact lies outside the window, there is no canvas to
feel. The bristle is assumed to lay paint as usual (
GHOST_TOUCH0.8) and to lift none, so it enters the window about as spent as in a whole render. A contact cut by the window edge lays only the window's share there. - Linen, grounds (
prime), glazes,apply, relief and the save dither are pixel-local, so they are exact. Cracks grow over the whole canvas (the network is in mm) and only the window is rasterized, so they are exact too. - The margin (default 40 units,
--margin) is painted but not saved. It gives paint leveling (settleblurs), the brushes' contact surface and strokes that enter the window their context.
Why a crop is close but not exact
A mark's look depends on the brush's history along its whole path: paint it picked up and ridges it ploughed ahead of itself before entering the window, and earlier strokes of the same tile's brush. That history depends on the canvas outside the window, which a crop doesn't have. Long strokes (grounds of 250–600 units, mist of 80–200, badger fusing) carry the most history. Short strokes, dabs, the rigger, figures, trees and cracks match well. Resolution of the numbers below: max/mean over RGB, in 8-bit levels.
| moonrise figures crop vs the same region of a whole render | mean | pixels > 8 levels | max |
|---|---|---|---|
| 1000px, margin 12 | 1.47 | 4.5% | 39 |
| 1000px, margin 40 | 1.11 | 2.5% | 40 |
| 1000px, margin 80 | 0.86 | 1.8% | 42 |
| 1000px, margin 160 | 0.56 | 0.9% | 41 |
| 3200px, margin 40 | 1.34 | 4.5% | 56 |
| 3200px, margin 80 | 1.01 | 3.0% | 48 |
Engine test crop_matches_whole checks this: linen and ground are exact,
brushwork is close, and the difference falls as the margin grows. For
scale: the palette history bug (below) alone moved the whole painting by a
mean of 1.6 levels. The 1000px preview and the 3200px render differ in kind:
work accepts a stroke center by reading the mask at that point, masks at
another resolution accept slightly different centers, and from there the
RNG sequence and every later mark differ.
Evidence (all in [local path redacted], viewed through
scripts/peek):
evidence_crop3200.png: whole-render region | 3200px crop (margin 40) | difference ×8. The figures, grass, cracks and spruces are the same marks. The difference is low-amplitude and in the mist (long strokes), plus one faint mist band at the top.cmp_m80.png: the same at 1000px, margin 80.cargo paint study_workflowwritesout/study_workflow.png, the same sheet for a small scene, and prints the times and the difference (here: whole 6.4 s, crop 1.8 s, mean 1.37 and max 35 levels; the error is in the badger-fused sky).
In a crop, c.sample(), c.pixels() and c.surface_um() see only the
window (sample clamps to it).
Checkpoints
- File:
out/<stem>.<stage>.ckpt. The stem is<name>[_full][_crop], regardless of--out, and spaces in stage names become_. Contents: magic, a key=value header (name, stage, width, seed, crop and margin, theKeepstate, a timestamp and three source hashes), then the canvas. The canvas part is the frame, crop window, color, relief, film, linen, size, the wet layer (volume, Mixbox latents, hiding and stiffness, dirty box) and the stroke counter. Per-pixel stroke ids and film floors are not saved, because every later stroke has a new id and never reads them. The brushes' contact surface is rebuilt from the relief. Sizes: 43 MB at 1000px, about 440 MB at 3200px whole, 35 MB for the 3200px figures crop. Writing takes 0.02–0.05 s at 1000px. - Exact: resuming from any stage, including one that ends with wet paint ("sky lay"), gives a byte-identical PNG. Checked for mist and "sky lay" at 1000px and for mist in the 3200px crop.
- Validation: a checkpoint must match name, width, seed and crop.
--resumealso refuses it if any of these changed since it was saved: the painting's source up to the end of that stage (the lines before the nextstage/finishcall, found with#[track_caller]),paintings/src/*.rsorcrates/paint/src/*.rs. The error names what changed.--stale-okuses the checkpoint anyway. Edits after the stage are what resuming is for, and they are allowed. - Not covered: helper functions below
mainin the painting file, and code between stage blocks that paints (a rule, not checked).
A bug found by exactness: Palette::mix depended on history
The first resume from "sky lay" differed from the straight run: 0.02% of
pixels, by 1 level. The cause was that Palette::mix cached mixtures under
a quantized OKLab key but searched for whichever color reached the bucket
first. So a pile's mixture depended on which colors had been mixed before,
and a resumed run with an empty cache mixed differently. It now searches
the bucket's center, which makes the result a pure function of the key.
This changes output: per-stroke piles move within one 1/400 OKLab bucket,
moonrise moves by a mean of 1.6 levels, and it looks the same (compared
side by side). The golden was re-recorded (commit 3ca1c69). palette.rs is
stream 1's file. The change is one line in mix, and stream 1 should keep
the property "mix is a pure function of its input".
Speed
Profile (macOS sample; moonrise at 1000px, and the 3200px ground stage):
bristle::drag_on/exchange is about 85% of busy CPU. The rest is dry and
settle, the Mixbox conversion and crack rastering. Rayon workers are idle
most of the time. Phases hold only 1–6 tiles (long strokes make big tiles),
the badger passes over the sky run 1–3 tiles at a time (the sky stage takes
as long on 1 thread as on 10), and the single drags (clouds, wisps, 100+
spruces) are sequential. In a crop at 3200px, the whole-canvas masks
dominated instead: Perlin noise in the painting's mask closures.
Wins taken, all with bit-identical output (golden unchanged; moonrise at 1000px byte-identical to the post-palette-fix render):
Frame::per_column(g)tabulates a function of x at every pixel-column center. A mask callingridge(x)per pixel then evaluates it once per column, and any other x falls through tog. Moonrise uses it for its 4 profile lines. The 3200px crop's ground stage dropped from 13.2 s to 4.5 s and the whole crop from 24 s to 13 s.sched::run_ordered:Canvas::workused to wait at each of the four phase barriers. Now a tile starts as soon as every earlier tile whose footprint overlaps it has finished. Tiles with disjoint footprints commute exactly, so the result is the one-by-one order's. The mist stage (resumed, 3 runs alternating with the old binary): 3.63 s against 3.9 s. The gain is limited by how few tiles there are and by this machine's load. I expect, but didn't measure, a larger effect on an idle machine and for passes of short strokes (more tiles).
Before/after, moonrise:
| before (main) | after | |
|---|---|---|
| 1000px whole | 18.4 s (load ~20) | 15.9–16.7 s (load ~46) |
| 3200px whole | 107 s (load ~40); 145 s after the palette fix (load ~110) | 86 s (load ~14), byte-identical to the post-fix render |
| 3200px crop, figures | — (not possible) | 13.3 s |
| 3200px crop, resumed from mist | — | 1.6 s |
What I'd do next for speed, in order: (1) exact micro-optimizations in
exchange, which needs line-level profiling; I didn't have line tables.
(2) Masks that evaluate lazily outside a crop window, so crops stop paying
for whole-canvas masks. (3) Anything faster for long badger passes changes
the physics order, so it is a design decision, not a safe win.
Merge notes for the integrator
canvas.rs:Framehas new fields (x0, y0, full_w, full_h). UseFrame::new(w, h, scale)instead of struct literals.Canvas.fis now the buffer (window) frame. Code that builds masks inside the crate must usec.frame(), notc.f;check_maskpanics loudly otherwise. I changedstyle.rs(one line) andtree.rs(one line,from_shape). Buffer code that indexespx/height/film/wetbyself.f.wkeeps working in both modes. New buffer code that converts px↔units should usef.ux/uy/index.handling.rs(stream 2's file):workandcut_in_edgesplan inmask.f(2 lines). The execution loop at the end ofrun_plansis now a closure passed tosched::run_ordered(the tile body is unchanged). If stream 2 changed that loop, apply their change insidepaint_tile.palette.rs(stream 1's file): the one-line cache fix above.rng.rs:Rng::state/Rng::from_state.lib.rs:pub mod checkpoint; mod sched;and exportsCropandset_crop.bristle.rs:Surfcarries the window;exchangeclips to it and estimates contacts outside it. For whole canvases the arithmetic is unchanged.crack.rs:raster_window;Canvas::crackgrows the network over the whole canvas.- If you add state to
CanvasorWet, add it tocheckpoint.rsand bumpMAGIC. Otherwise resumes silently lose it. .gitignore:out/*.ckpt.
Known issues
- A crop is close, not exact (see above), and its mask and planning cost scale with the whole canvas.
- Checkpoints of whole 3200px canvases are about 440 MB each.
--ckptwrites one per stage, so use it with crops or at preview size. - The
Runstage API changed. Paintings on other branches that still useo.stage(&mut c, "x")won't compile until migrated (mechanical, above). study_cracksbuilds several canvases in one process;--cropapplies to all of them, so don't crop it.--frames(time-lapse) is not implemented. The natural hook isRun::stageplus aCanvascallback after eachworkphase or every N strokes, saving a copy with the wet layer composited (adry()on a clone).