Preface: what this handbook is for

✅ verified (everything described here is in the current code and has been run on ch. 19’s worked example; anything that has not been run is marked 📐)

What it sets out to do

An illustration a diffusion model generated is not something an artist can take over: no layers, blurry when enlarged, no brush marks. What this handbook does is turn it into a layered painting – a Krita .kra whose layers have names, where each layer is a whole thing that can be hidden or edited on its own, where the lines are individual strokes, and where every pixel has a provenance: it came either from an analytic curve or from a real brush stroke, and not one pixel is the source image scaled up.

This is not a replica (matching the source pixel for pixel), it is a study: the source is the reference and the output is a fresh painting made from it. So the criteria are not PSNR but “are the edges curves”, “is there an upscaling fingerprint”, “do the value bands look like a person’s”, and “does it still look right when stacked back together” (ch. 7).

It paints at 4x by default (a 1024-wide source is painted 4096 wide). 8x is an option only; it more than doubles the Krita half of the time (ch. 18).

How the handbook is arranged

Painting a picture has a fixed set of stages: cut it into parts, decide the lines on the source, complete the occluded part of every layer, give each layer its own lines, lay out a draft for a human to look at, paint part by part, and check it. Part one follows those steps, one chapter each (the one-shot route’s single step belongs to another route but lives in part one too), and every chapter has the same skeleton: what it does -> inputs and outputs -> the method and its knobs -> which parts.py fields govern it -> how it is judged and what to change when it is wrong -> where it breaks. The lineart chapter is split further: the two sources, each way of extracting raster lineart, skeletonizing, arbitration.

Steps strung together make a route (part two). There are two. One-shot: paint straight after segmentation, two commands to a finished picture – it looks right, but the layers are value bands cut by luminance and have no names. Layered: segment, decide the lines, complete, give each layer its lines, produce a draft for a human first, and paint only once that passes – the layers are made for a person. They answer two different questions; “Concepts” says how to choose.

The four unnumbered pieces before the chapters are getting started: installing, a few concepts, a ten-minute run-through. Part three is a reference for what headless Krita can do: which APIs really work and which fail silently, all measured. Part four is measuring and budgeting: how to measure without fooling yourself, and where the time and memory go. Part five is the worked example: one real picture (origin) taken end to end down both routes, with all its numbers – the main text never quotes them, and each step’s chapter ends with a single line “on origin” pointing here. The appendices: commands, code index, probes, glossary, version history, file formats, parts-table fields.

Honesty

• Every number has to come from a step directory produced by this code and be traceable to a file; anything not measured is marked 📐.
• Description numbers over source numbers, at most 5%: how many numbers it takes to say what this painting is. Writing pixels is allowed, but every single write has to justify itself, and not one unjustified write is permitted.
• Whatever a generative model invented is labelled as invented; when two sources disagree, the source image decides, not the source of the line.
• A gate’s images are to be looked at; having produced them is not enough.

How to read this

Just want to run it: “Installing and self-checking” and “Ten minutes”. Want to change one step: that step’s chapter in part one. Want to change how one part is painted: ch. 6 and appendix G. Want a different lineart extractor: the subsections of ch. 2. Want to take over the code: appendices B and F. Want to do something else in Krita: part three. Read ch. 17 first: it teaches you how not to be fooled by your own measurements – this project has been caught out more than thirty times, and not once did anything raise an error.

The first line of every chapter carries a status: 👤 checked by a human (a person looked and was very satisfied) · ✅ verified (there is data, and the author considers it passed) · 🧪 in progress (it runs but has not settled) · 📐 designed (only the questions and the interface exist) · ⬜ placeholder (the skeleton is up but nothing has been studied: only “how an artist paints it” and “what has to be decided”, with no code).