ranger-compiler 3.5.1 → 3.5.2

package/dist/lib/evg/EvgBitmapTracer.rgr

@@ -0,0 +1,4277 @@
+; SPDX-License-Identifier: MIT
+
+; ==============================================================================
+; EvgBitmapTracer.rgr — bitmap → EVG path, potrace-style
+; ==============================================================================
+;
+; Pipeline (Potrace paper):
+;   1. decompose bitmap into closed edge paths
+;   2. turdsize despeckle
+;   3. optimal polygon (EvgTraceFit — calcLon / bestPolygon / adjustVertices)
+;   4. alphamax corner/curve fit (+ optional optiCurve)
+;   5. emit PathBuilder / EVGElement / SVG
+;
+; Color:
+;   options.fillHex     — mono path fill (default #000000)
+;   options.colorCount  — 1 = mono threshold; >1 = posterize ImageBuffer into
+;                         N swatches and emit one evenodd <path> per layer
+;
+; Posterize (see the block comment above colorDist2 for why each step exists):
+;   detectBackground  — flood the page in from the border (options.bgMode)
+;   buildFlatMask     — region interior vs. anti-aliased transition
+;   buildPalette      — count-weighted k-means++ over a 5-bit histogram of the
+;                       interiors only, then merge indistinguishable swatches
+;   assignLabels      — nearest swatch, with a guarded snap for transitions
+;   mergeTinyRegions  — absorb runs below options.minRegion into their surround
+;   maskForLabel      — one binary mask per swatch, traced like the mono path
+;
+;   bash lib/evg/tools/run_trace_bench.sh
+; ==============================================================================
+
+Import "EvgTraceTypes.rgr"
+Import "EvgTraceColor.rgr"
+Import "EvgTracePath.rgr"
+Import "EvgTraceFit.rgr"
+Import "EvgTraceCurve.rgr"
+Import "PathBuilder.rgr"
+Import "EVGElement.rgr"
+Import "EVGColor.rgr"
+Import "pkg:image/ImageBuffer.rgr"
+
+class EvgBitmapTracer {
+    def options:EvgTraceOptions
+    def bitmap:EvgBinaryBitmap
+    def rings:[EvgTraceRing]
+    def commands:[PathCommand]
+    def pathData:string ""
+    def width:int 0
+    def height:int 0
+    ; Multi-color posterize planes (populated by fromImageBuffer when colorCount > 1).
+    def hasColorPlanes:boolean false
+    def planeR:[int]
+    def planeG:[int]
+    def planeB:[int]
+    def planeA:[int]
+    ; 1 = region interior, 0 = anti-aliased transition (buildFlatMask).
+    def flat:[int]
+    ; Palette index per pixel, -1 = not painted (assignLabels).
+    def labels:[int]
+    ; 1 = a step that survived the uniqueness and continuity tests, i.e. a
+    ; boundary rather than noise (buildEdgeMask).
+    def edgeMask:[int]
+    def detailMask:[int]
+    ; Whether the two masks are in play at all. Both were being re-derived on
+    ; every call — an options lookup and an array_length against width*height —
+    ; and both are asked once per neighbour per pixel per shape, which on a
+    ; photograph is millions of times for an answer that cannot change during a
+    ; trace.
+    def detailOn:boolean false
+    def edgeMaskOn:boolean false
+    ; OKLab scratch (options.colorSpace). `okLin` is the 256-entry sRGB →
+    ; linear table, built on first use because a binary trace never asks.
+    def okOn:boolean false
+    def okLin:[double]
+    def okP:EvgOklab
+    def okQ:EvgOklab
+    def okC:EvgOklab
+    ; Continuity region id per pixel, -1 = none (buildContourRegions).
+    def regionOf:[int]
+    def regionCount:int 0
+    ; 1 = page background flooded in from the border (detectBackground).
+    def bgMask:[int]
+    def bgActive:boolean false
+    def layers:[EvgTraceLayer]
+
+    Constructor () {
+        options = (EvgTraceOptions.defaults())
+        bitmap = (EvgBinaryBitmap.create(0 0))
+        def r:[EvgTraceRing]
+        rings = r
+        def c:[PathCommand]
+        commands = c
+        def pr:[int]
+        planeR = pr
+        def pg:[int]
+        planeG = pg
+        def pb:[int]
+        planeB = pb
+        def pa:[int]
+        planeA = pa
+        def fl:[int]
+        flat = fl
+        def lb:[int]
+        labels = lb
+        def bg:[int]
+        bgMask = bg
+        def ro:[int]
+        regionOf = ro
+        def em:[int]
+        edgeMask = em
+        edgeMaskOn = ((options.edgeMinRun) >= 1)
+        def ok:[double]
+        okLin = ok
+        okP = (new EvgOklab())
+        okQ = (new EvgOklab())
+        okC = (new EvgOklab())
+        def ly:[EvgTraceLayer]
+        layers = ly
+    }
+
+    ; Flags derived from options. The constructor runs before a caller has
+    ; assigned `options` (fromBinary / fromImageBuffer set it afterwards), so
+    ; anything cached off an option has to be refreshed once the real options
+    ; are in place — trace() does that here.
+    fn syncOptions:void () {
+        edgeMaskOn = ((options.edgeMinRun) >= 1)
+        okOn = ((options.colorSpace) == "oklab")
+    }
+
+    sfn absD:double (v:double) {
+        if (v < 0.0) {
+            return (0.0 - v)
+        }
+        return v
+    }
+
+    sfn absI:int (v:int) {
+        if (v < 0) {
+            return (0 - v)
+        }
+        return v
+    }
+
+    ; Truncating division toward zero for the half-cell neighbour lookups.
+    sfn idivTowardZero:int (a:int b:int) {
+        if (b == 0) {
+            return 0
+        }
+        if (a < 0) {
+            if (b > 0) {
+                return (0 - (idiv (0 - a) b))
+            }
+            return (idiv (0 - a) (0 - b))
+        }
+        if (b < 0) {
+            return (0 - (idiv a (0 - b)))
+        }
+        return (idiv a b)
+    }
+
+    sfn fromBinary:EvgBitmapTracer (bm:EvgBinaryBitmap opts:EvgTraceOptions) {
+        def t (new EvgBitmapTracer())
+        t.options = opts
+        t.bitmap = bm
+        t.width = bm.w
+        t.height = bm.h
+        return t
+    }
+
+    ; Threshold an RGBA ImageBuffer into a binary bitmap, then wrap a tracer.
+    ; When options.colorCount > 1, keep RGB planes and posterize in trace().
+    sfn fromImageBuffer:EvgBitmapTracer (img:ImageBuffer opts:EvgTraceOptions) {
+        if (opts.colorCount > 1) {
+            def tCol (new EvgBitmapTracer())
+            tCol.options = opts
+            tCol.width = img.width
+            tCol.height = img.height
+            tCol.hasColorPlanes = true
+            tCol.bitmap = (EvgBinaryBitmap.create(img.width img.height))
+            def pr:[int]
+            def pg:[int]
+            def pb:[int]
+            def pa:[int]
+            def y:int 0
+            while (y < img.height) {
+                def x:int 0
+                while (x < img.width) {
+                    def c:Color (img.getPixel(x y))
+                    push pr c.r
+                    push pg c.g
+                    push pb c.b
+                    push pa c.a
+                    x = (x + 1)
+                }
+                y = (y + 1)
+            }
+            tCol.planeR = pr
+            tCol.planeG = pg
+            tCol.planeB = pb
+            tCol.planeA = pa
+            return tCol
+        }
+        def thr:int opts.threshold
+        if (thr < 0) {
+            thr = (EvgBitmapTracer.otsuThreshold(img))
+        }
+        def bm:EvgBinaryBitmap (EvgBinaryBitmap.create(img.width img.height))
+        def y2:int 0
+        while (y2 < img.height) {
+            def x2:int 0
+            while (x2 < img.width) {
+                def c2:Color (img.getPixel(x2 y2))
+                def g:int (c2.grayscale())
+                def on:boolean false
+                if opts.blackOnWhite {
+                    if (g < thr) {
+                        on = true
+                    }
+                } {
+                    if (g >= thr) {
+                        on = true
+                    }
+                }
+                ; Transparent pixels never count as foreground.
+                if (c2.a < 16) {
+                    on = false
+                }
+                bm.setBit(x2 y2 on)
+                x2 = (x2 + 1)
+            }
+            y2 = (y2 + 1)
+        }
+        return (EvgBitmapTracer.fromBinary(bm opts))
+    }
+
+    ; Otsu threshold on luminance — used when options.threshold < 0.
+    sfn otsuThreshold:int (img:ImageBuffer) {
+        def hist:[int]
+        def i:int 0
+        while (i < 256) {
+            push hist 0
+            i = (i + 1)
+        }
+        def total:int (img.width * img.height)
+        if (total <= 0) {
+            return 128
+        }
+        def y:int 0
+        while (y < img.height) {
+            def x:int 0
+            while (x < img.width) {
+                def c:Color (img.getPixel(x y))
+                def g:int (c.grayscale())
+                def prev:int (itemAt hist g)
+                set hist g (prev + 1)
+                x = (x + 1)
+            }
+            y = (y + 1)
+        }
+        def sum:double 0.0
+        i = 0
+        while (i < 256) {
+            def cnt:int (itemAt hist i)
+            sum = (sum + ((to_double i) * (to_double cnt)))
+            i = (i + 1)
+        }
+        def sumB:double 0.0
+        def wB:int 0
+        def best:double (0.0 - 1.0)
+        def thr:int 128
+        i = 0
+        while (i < 256) {
+            def c2:int (itemAt hist i)
+            wB = (wB + c2)
+            if (wB > 0) {
+                def wF:int (total - wB)
+                if (wF > 0) {
+                    sumB = (sumB + ((to_double i) * (to_double c2)))
+                    def mB:double (sumB / (to_double wB))
+                    def mF:double ((sum - sumB) / (to_double wF))
+                    def diff:double (mB - mF)
+                    def between:double ((diff * diff) * (to_double wB) * (to_double wF))
+                    if (between > best) {
+                        best = between
+                        thr = i
+                    }
+                }
+            }
+            i = (i + 1)
+        }
+        return thr
+    }
+
+    ; ----------------------------------------------------------------------
+    ; Public entry
+    ; ----------------------------------------------------------------------
+
+    fn trace:void () {
+        this.syncOptions()
+        def emptyR:[EvgTraceRing]
+        rings = emptyR
+        def emptyC:[PathCommand]
+        commands = emptyC
+        def emptyL:[EvgTraceLayer]
+        layers = emptyL
+        pathData = ""
+        if hasColorPlanes {
+            this.traceColorLayers()
+        } {
+            this.decompose()
+            this.emitCommands()
+            pathData = (this.pathDataOf(commands))
+            ; Mono also exposes a single layer so callers can always use layers.
+            def layer (new EvgTraceLayer())
+            layer.fillHex = options.fillHex
+            layer.pathData = pathData
+            layer.ringCount = (array_length rings)
+            layer.commandCount = (array_length commands)
+            push layers layer
+        }
+    }
+
+    fn getCommands:[PathCommand] () {
+        return commands
+    }
+
+    fn getPathData:string () {
+        return pathData
+    }
+
+    fn ringCount:int () {
+        return (array_length rings)
+    }
+
+    fn commandCount:int () {
+        return (array_length commands)
+    }
+
+    ; True when a page color was actually flooded away — the page can say so,
+    ; because "auto" declining silently is indistinguishable from it failing.
+    fn backgroundRemoved:boolean () {
+        return bgActive
+    }
+
+    fn layerCount:int () {
+        return (array_length layers)
+    }
+
+    fn getLayers:[EvgTraceLayer] () {
+        return layers
+    }
+
+    fn toPathBuilder:PathBuilder () {
+        def b (new PathBuilder())
+        b.addCommands(commands)
+        return b
+    }
+
+    fn toEVGElement:EVGElement () {
+        def el:EVGElement (EVGElement.createPath())
+        el.svgPath = pathData
+        el.fillRule = "evenodd"
+        el.viewBox = ("0 0 " + (to_string width) + " " + (to_string height))
+        el.fillColor = (EVGColor.parse(options.fillHex))
+        if ((array_length layers) > 0) {
+            def layer0:EvgTraceLayer (itemAt layers 0)
+            el.svgPath = layer0.pathData
+            el.fillColor = (EVGColor.parse(layer0.fillHex))
+        }
+        el.width = (EVGUnit.px((to_double width)))
+        el.height = (EVGUnit.px((to_double height)))
+        return el
+    }
+
+    ; One EVG path element per color layer (posterize / mono).
+    fn toEVGElements:[EVGElement] () {
+        def out:[EVGElement]
+        def i:int 0
+        while (i < (array_length layers)) {
+            def layer:EvgTraceLayer (itemAt layers i)
+            def el:EVGElement (EVGElement.createPath())
+            el.svgPath = layer.pathData
+            el.fillRule = "evenodd"
+            el.viewBox = ("0 0 " + (to_string width) + " " + (to_string height))
+            el.fillColor = (EVGColor.parse(layer.fillHex))
+            el.width = (EVGUnit.px((to_double width)))
+            el.height = (EVGUnit.px((to_double height)))
+            push out el
+            i = (i + 1)
+        }
+        return out
+    }
+
+    sfn num:string (v:double) {
+        ; Two decimals is plenty for a gradient axis and keeps the file small.
+        def scaled:int (to_int ((v * 100.0) + 0.5))
+        def whole:int (idiv scaled 100)
+        def frac:int (scaled - (whole * 100))
+        if (frac < 0) {
+            frac = (0 - frac)
+        }
+        def fs:string (to_string frac)
+        if (frac < 10) {
+            fs = ("0" + fs)
+        }
+        return ((to_string whole) + "." + fs)
+    }
+
+    fn toSVG:string () {
+        def svg:string "<svg xmlns=\"http://www.w3.org/2000/svg\" "
+        svg = (svg + "width=\"" + (to_string width) + "\" ")
+        svg = (svg + "height=\"" + (to_string height) + "\" ")
+        svg = (svg + "viewBox=\"0 0 " + (to_string width) + " " + (to_string height) + "\">")
+        if ((array_length layers) > 0) {
+            ; Gradients have to be declared before they are referenced.
+            def defs:string ""
+            def i:int 0
+            while (i < (array_length layers)) {
+                def layer:EvgTraceLayer (itemAt layers i)
+                def id:string ("g" + (to_string i))
+                if ((layer.fillKind) == "linear") {
+                    defs = (defs + "<linearGradient id=\"" + id + "\" gradientUnits=\"userSpaceOnUse\"")
+                    defs = (defs + " x1=\"" + (EvgBitmapTracer.num(layer.gx0)) + "\" y1=\"" + (EvgBitmapTracer.num(layer.gy0)) + "\"")
+                    defs = (defs + " x2=\"" + (EvgBitmapTracer.num(layer.gx1)) + "\" y2=\"" + (EvgBitmapTracer.num(layer.gy1)) + "\">")
+                    defs = (defs + "<stop offset=\"0\" stop-color=\"" + layer.stopA + "\"/>")
+                    defs = (defs + "<stop offset=\"1\" stop-color=\"" + layer.stopB + "\"/></linearGradient>")
+                }
+                i = (i + 1)
+            }
+            if ((strlen defs) > 0) {
+                svg = (svg + "<defs>" + defs + "</defs>")
+            }
+            i = 0
+            while (i < (array_length layers)) {
+                def layer2:EvgTraceLayer (itemAt layers i)
+                def fill:string layer2.fillHex
+                if ((layer2.fillKind) != "flat") {
+                    fill = ("url(#g" + (to_string i) + ")")
+                }
+                svg = (svg + "<path fill=\"" + fill + "\" fill-rule=\"evenodd\" d=\"" + layer2.pathData + "\"/>")
+                i = (i + 1)
+            }
+        } {
+            svg = (svg + "<path fill=\"" + options.fillHex + "\" fill-rule=\"evenodd\" d=\"" + pathData + "\"/>")
+        }
+        svg = (svg + "</svg>")
+        return svg
+    }
+
+    ; ----------------------------------------------------------------------
+    ; Multi-color posterize (quantize → per-swatch binary trace)
+    ;
+    ; The palette is built from *plateau* pixels only. Anti-aliased boundary
+    ; pixels are blends of two real colors: if they are allowed to vote, the
+    ; extra swatches are spent on halo tones instead of new regions, and every
+    ; ink stroke is then eaten from both sides until turdsize deletes what is
+    ; left. Transitional pixels are instead snapped to a neighbouring region.
+    ; ----------------------------------------------------------------------
+
+    ; Weighted Euclidean distance in RGB with an extra luma term, so a dark
+    ; ink line never collapses into a mid-tone of the same hue.
+    sfn colorDist2:double (r0:int g0:int b0:int r1:int g1:int b1:int lw:int) {
+        def dr:double (to_double (r0 - r1))
+        def dg:double (to_double (g0 - g1))
+        def db:double (to_double (b0 - b1))
+        def l0:int (EvgBitmapTracer.lumaOf(r0 g0 b0))
+        def l1:int (EvgBitmapTracer.lumaOf(r1 g1 b1))
+        def dl:double (to_double (l0 - l1))
+        return ((((dr * dr) + (dg * dg)) + (db * db)) + ((dl * dl) * (to_double lw)))
+    }
+
+    sfn lumaOf:int (r:int g:int b:int) {
+        ; Integer approx of 0.299R+0.587G+0.114B
+        return (idiv (((r * 299) + (g * 587)) + (b * 114)) 1000)
+    }
+
+    fn lumaWeight:int () {
+        def lw:int options.lumaWeight
+        if (lw < 1) {
+            return 1
+        }
+        return lw
+    }
+
+    ; Every `d` attribute the tracer emits goes through here, so the encoding
+    ; is one option rather than a choice repeated at each emit site.
+    fn pathDataOf:string (cmds:[PathCommand]) {
+        if ((options.pathFormat) == "plain") {
+            return (VectorShapes.asPathData(cmds))
+        }
+        def p:int options.pathPrecision
+        if (p < 0) {
+            p = 0
+        }
+        return (EvgTracePath.encode(cmds p true))
+    }
+
+    ; The one place the posterizer asks how far apart two colors are. Which
+    ; space answers is options.colorSpace; both answers are on the same scale,
+    ; so a caller comparing against a threshold does not care which ran.
+    fn dist2:double (r0:int g0:int b0:int r1:int g1:int b1:int) {
+        if (okOn == false) {
+            def lw:int (this.lumaWeight())
+            return (EvgBitmapTracer.colorDist2(r0 g0 b0 r1 g1 b1 lw))
+        }
+        if ((array_length okLin) == 0) {
+            okLin = (EvgTraceColor.buildLinearTable())
+        }
+        okP.setFrom(okLin r0 g0 b0)
+        okQ.setFrom(okLin r1 g1 b1)
+        def p:EvgOklab (unwrap okP)
+        def q:EvgOklab (unwrap okQ)
+        return (EvgTraceColor.dist2(p q))
+    }
+
+    ; What `dist2` returns for a gray step of `perChannel` in every channel —
+    ; the bridge between a threshold written in channel units (minColorDelta)
+    ; and the metric actually in use. Exact for "rgb"; for "oklab" the scale
+    ; was chosen to make black-to-white agree, and a gray step agrees with it
+    ; to within the transfer curve's own bend.
+    fn dist2Limit:double (perChannel:int) {
+        def d:double (to_double (perChannel * perChannel))
+        if okOn {
+            return (d * 6.0)
+        }
+        def lw:int (this.lumaWeight())
+        def w:double (to_double (3 + lw))
+        return (d * w)
+    }
+
+    ; True if this opaque pixel may join the palette / masks.
+    fn pixelAllowed:boolean (i:int) {
+        def a:int (itemAt planeA i)
+        if (a < 16) {
+            return false
+        }
+        if bgActive {
+            return ((itemAt bgMask i) == 0)
+        }
+        ; Nothing else drops a pixel. The bright-pixel rule that used to sit here
+        ; had no idea where it was: it deleted the white of an eye and the white
+        ; of a boot along with the white of the page, because all it asked was
+        ; how bright the pixel is. Transparency belongs to what is outside the
+        ; subject, so it is decided by the border floods in detectBackground and
+        ; nowhere else.
+        return true
+    }
+
+    ; ----------------------------------------------------------------------
+    ; Background detection
+    ;
+    ; skipLuma is a blunt instrument: it deletes every bright pixel, so a white
+    ; belly or a highlight inside the subject is thrown away along with the
+    ; page. Instead, flood the border color inwards and drop only what is
+    ; actually connected to the edge of the image. Bail out (and leave the
+    ; skipLuma rule in charge) unless the border really is one flat color —
+    ; a photograph has no page to remove.
+    ; ----------------------------------------------------------------------
+
+    fn detectBackground:void () {
+        bgActive = false
+        def mode:string options.bgMode
+        def named:boolean (mode == "color")
+        if ((mode != "auto") && (named == false)) {
+            return
+        }
+        def n:int (width * height)
+        if (n < 4) {
+            return
+        }
+        ; Modal border color, via the same 5-bit histogram as the palette.
+        def bins:int 32768
+        def cnt:[int]
+        def sr:[int]
+        def sg:[int]
+        def sb:[int]
+        def i:int 0
+        while (i < bins) {
+            push cnt 0
+            push sr 0
+            push sg 0
+            push sb 0
+            i = (i + 1)
+        }
+        def border:[int]
+        def x:int 0
+        while (x < width) {
+            push border x
+            push border (((height - 1) * width) + x)
+            x = (x + 1)
+        }
+        def y:int 1
+        while (y < (height - 1)) {
+            push border (y * width)
+            push border ((y * width) + (width - 1))
+            y = (y + 1)
+        }
+        def bn:int (array_length border)
+        if (bn == 0) {
+            return
+        }
+        def opaqueBorder:int 0
+        i = 0
+        while (i < bn) {
+            def idx:int (itemAt border i)
+            if ((itemAt planeA idx) >= 16) {
+                def r:int (itemAt planeR idx)
+                def g:int (itemAt planeG idx)
+                def b:int (itemAt planeB idx)
+                def key:int (((((idiv r 8) * 32) + (idiv g 8)) * 32) + (idiv b 8))
+                set cnt key ((itemAt cnt key) + 1)
+                set sr key ((itemAt sr key) + r)
+                set sg key ((itemAt sg key) + g)
+                set sb key ((itemAt sb key) + b)
+                opaqueBorder = (opaqueBorder + 1)
+            }
+            i = (i + 1)
+        }
+        ; A fully transparent border is a cut-out: alpha already removed it.
+        if (opaqueBorder == 0) {
+            return
+        }
+        def topI:int (0 - 1)
+        def topC:int 0
+        i = 0
+        while (i < bins) {
+            if ((itemAt cnt i) > topC) {
+                topC = (itemAt cnt i)
+                topI = i
+            }
+            i = (i + 1)
+        }
+        if (topI < 0) {
+            return
+        }
+        def bgR:int (idiv (itemAt sr topI) topC)
+        def bgG:int (idiv (itemAt sg topI) topC)
+        def bgB:int (idiv (itemAt sb topI) topC)
+        def tol:int options.bgTolerance
+        if (tol < 0) {
+            tol = 0
+        }
+        if named {
+            ; The caller named the color, so the border does not get a vote on
+            ; what it is — or on whether the flood happens at all.
+            def c:EVGColor (EVGColor.parse(options.bgColor))
+            if (c.isSet == false) {
+                return
+            }
+            bgR = (to_int c.r)
+            bgG = (to_int c.g)
+            bgB = (to_int c.b)
+        } {
+            ; How much of the border actually is that color?
+            def within:int 0
+            i = 0
+            while (i < bn) {
+                def idx2:int (itemAt border i)
+                if ((itemAt planeA idx2) >= 16) {
+                    if (this.nearBg(idx2 bgR bgG bgB tol)) {
+                        within = (within + 1)
+                    }
+                }
+                i = (i + 1)
+            }
+            if ((idiv (within * 100) opaqueBorder) < 80) {
+                ; The border is not one flat color — a gradient page, or a
+                ; photograph with no page at all. Rather than fall back to
+                ; deleting every bright pixel wherever it sits, try the same
+                ; question the other way round: is there a *bright* area
+                ; connected to the edge? That removes a white or near-white page
+                ; and cannot touch a white belly, because a belly does not reach
+                ; the border.
+                this.floodBrightFromBorder(border bn)
+                return
+            }
+        }
+        ; Flood the page in from every matching border pixel.
+        def mask:[int]
+        i = 0
+        while (i < n) {
+            push mask 0
+            i = (i + 1)
+        }
+        def stack:[int]
+        i = 0
+        while (i < bn) {
+            def s0:int (itemAt border i)
+            if ((itemAt mask s0) == 0) {
+                if (this.nearBg(s0 bgR bgG bgB tol)) {
+                    set mask s0 1
+                    push stack s0
+                }
+            }
+            i = (i + 1)
+        }
+        def head:int 0
+        while (head < (array_length stack)) {
+            def cur:int (itemAt stack head)
+            head = (head + 1)
+            def cy:int (idiv cur width)
+            def cx:int (cur - (cy * width))
+            if (cx > 0) {
+                this.floodStep((cur - 1) mask stack bgR bgG bgB tol)
+            }
+            if (cx < (width - 1)) {
+                this.floodStep((cur + 1) mask stack bgR bgG bgB tol)
+            }
+            if (cy > 0) {
+                this.floodStep((cur - width) mask stack bgR bgG bgB tol)
+            }
+            if (cy < (height - 1)) {
+                this.floodStep((cur + width) mask stack bgR bgG bgB tol)
+            }
+        }
+        bgMask = mask
+        bgActive = true
+    }
+
+    ; A page that is bright but not one flat color: flood inwards from every
+    ; border pixel at least as bright as skipLuma. Interiors are unreachable by
+    ; construction, which is the whole point — brightness alone was never a
+    ; statement about being background.
+    fn floodBrightFromBorder:void (border:[int] bn:int) {
+        def lim:int options.skipLuma
+        if (lim > 255) {
+            return
+        }
+        def n:int (width * height)
+        def mask:[int]
+        def i:int 0
+        while (i < n) {
+            push mask 0
+            i = (i + 1)
+        }
+        def stack:[int]
+        i = 0
+        while (i < bn) {
+            def s0:int (itemAt border i)
+            if ((itemAt mask s0) == 0) {
+                if (this.brightEnough(s0 lim)) {
+                    set mask s0 1
+                    push stack s0
+                }
+            }
+            i = (i + 1)
+        }
+        if ((array_length stack) == 0) {
+            return
+        }
+        def head:int 0
+        while (head < (array_length stack)) {
+            def cur:int (itemAt stack head)
+            head = (head + 1)
+            def cy:int (idiv cur width)
+            def cx:int (cur - (cy * width))
+            if (cx > 0) {
+                this.brightStep((cur - 1) mask stack lim)
+            }
+            if (cx < (width - 1)) {
+                this.brightStep((cur + 1) mask stack lim)
+            }
+            if (cy > 0) {
+                this.brightStep((cur - width) mask stack lim)
+            }
+            if (cy < (height - 1)) {
+                this.brightStep((cur + width) mask stack lim)
+            }
+        }
+        bgMask = mask
+        bgActive = true
+    }
+
+    fn brightEnough:boolean (i:int lim:int) {
+        if ((itemAt planeA i) < 16) {
+            return true
+        }
+        return ((EvgBitmapTracer.lumaOf((itemAt planeR i) (itemAt planeG i) (itemAt planeB i))) >= lim)
+    }
+
+    fn brightStep:void (i:int mask:[int] stack:[int] lim:int) {
+        if ((itemAt mask i) == 1) {
+            return
+        }
+        if ((this.brightEnough(i lim)) == false) {
+            return
+        }
+        set mask i 1
+        push stack i
+    }
+
+    fn nearBg:boolean (i:int bgR:int bgG:int bgB:int tol:int) {
+        if ((itemAt planeA i) < 16) {
+            return true
+        }
+        if ((EvgBitmapTracer.absI((itemAt planeR i) - bgR)) > tol) {
+            return false
+        }
+        if ((EvgBitmapTracer.absI((itemAt planeG i) - bgG)) > tol) {
+            return false
+        }
+        if ((EvgBitmapTracer.absI((itemAt planeB i) - bgB)) > tol) {
+            return false
+        }
+        return true
+    }
+
+    fn floodStep:void (i:int mask:[int] stack:[int] bgR:int bgG:int bgB:int tol:int) {
+        if ((itemAt mask i) != 0) {
+            return
+        }
+        if (this.nearBg(i bgR bgG bgB tol)) {
+            set mask i 1
+            push stack i
+        }
+    }
+
+    ; ----------------------------------------------------------------------
+    ; Plateau / edge classification
+    ; ----------------------------------------------------------------------
+
+    ; Largest per-channel difference between two pixels (alpha included, so the
+    ; feathered rim of a cut-out counts as a transition too).
+    fn pixelDelta:int (i:int j:int) {
+        def d:int (EvgBitmapTracer.absI((itemAt planeR i) - (itemAt planeR j)))
+        def dg:int (EvgBitmapTracer.absI((itemAt planeG i) - (itemAt planeG j)))
+        if (dg > d) {
+            d = dg
+        }
+        def db:int (EvgBitmapTracer.absI((itemAt planeB i) - (itemAt planeB j)))
+        if (db > d) {
+            d = db
+        }
+        def da:int (EvgBitmapTracer.absI((itemAt planeA i) - (itemAt planeA j)))
+        if (da > d) {
+            d = da
+        }
+        return d
+    }
+
+    ; flat[i] = 1 when every 4-neighbour is within flatTolerance, i.e. the pixel
+    ; sits inside a region rather than on an anti-aliased boundary.
+    fn buildFlatMask:void () {
+        def n:int (width * height)
+        def f:[int]
+        def i:int 0
+        while (i < n) {
+            push f 1
+            i = (i + 1)
+        }
+        def tol:int options.flatTolerance
+        if (tol < 0) {
+            tol = 0
+        }
+        def y:int 0
+        while (y < height) {
+            def x:int 0
+            while (x < width) {
+                def idx:int ((y * width) + x)
+                def isFlat:boolean true
+                if (x > 0) {
+                    if ((this.pixelDelta(idx (idx - 1))) > tol) {
+                        isFlat = false
+                    }
+                }
+                if (x < (width - 1)) {
+                    if ((this.pixelDelta(idx (idx + 1))) > tol) {
+                        isFlat = false
+                    }
+                }
+                if (y > 0) {
+                    if ((this.pixelDelta(idx (idx - width))) > tol) {
+                        isFlat = false
+                    }
+                }
+                if (y < (height - 1)) {
+                    if ((this.pixelDelta(idx (idx + width))) > tol) {
+                        isFlat = false
+                    }
+                }
+                if isFlat {
+                    set f idx 1
+                } {
+                    set f idx 0
+                }
+                x = (x + 1)
+            }
+            y = (y + 1)
+        }
+        flat = f
+    }
+
+    ; ----------------------------------------------------------------------
+    ; Color histogram (5 bits per channel) over the pixels that may vote
+    ; ----------------------------------------------------------------------
+
+    fn buildHistogram:void (flatOnly:boolean binR:[int] binG:[int] binB:[int] binW:[int]) {
+        def bins:int 32768
+        def cnt:[int]
+        def sumR:[int]
+        def sumG:[int]
+        def sumB:[int]
+        def i:int 0
+        while (i < bins) {
+            push cnt 0
+            push sumR 0
+            push sumG 0
+            push sumB 0
+            i = (i + 1)
+        }
+        def n:int (array_length planeR)
+        def hasFlat:boolean ((array_length flat) == n)
+        i = 0
+        while (i < n) {
+            def take:boolean (this.pixelAllowed(i))
+            if (take && flatOnly && hasFlat) {
+                if ((itemAt flat i) == 0) {
+                    take = false
+                }
+            }
+            if take {
+                def r:int (itemAt planeR i)
+                def g:int (itemAt planeG i)
+                def b:int (itemAt planeB i)
+                def key:int (((((idiv r 8) * 32) + (idiv g 8)) * 32) + (idiv b 8))
+                set cnt key ((itemAt cnt key) + 1)
+                set sumR key ((itemAt sumR key) + r)
+                set sumG key ((itemAt sumG key) + g)
+                set sumB key ((itemAt sumB key) + b)
+            }
+            i = (i + 1)
+        }
+        i = 0
+        while (i < bins) {
+            def c:int (itemAt cnt i)
+            if (c > 0) {
+                push binR (idiv (itemAt sumR i) c)
+                push binG (idiv (itemAt sumG i) c)
+                push binB (idiv (itemAt sumB i) c)
+                push binW c
+            }
+            i = (i + 1)
+        }
+    }
+
+    ; ----------------------------------------------------------------------
+    ; Palette: weighted k-means++ seeding + Lloyd passes over the histogram.
+    ; Weighting by pixel count is what stops a handful of outlier pixels from
+    ; claiming a swatch that then paints nothing — the old farthest-point seed
+    ; was drawn to exactly those outliers.
+    ; ----------------------------------------------------------------------
+
+    ; Parse options.paletteHex into RGB triples, dropping anything EVGColor
+    ; cannot read. Returns how many survived.
+    fn parsePaletteHex:int (outR:[int] outG:[int] outB:[int]) {
+        def n:int (array_length options.paletteHex)
+        def i:int 0
+        while (i < n) {
+            def c:EVGColor (EVGColor.parse((itemAt options.paletteHex i)))
+            if c.isSet {
+                push outR (to_int c.r)
+                push outG (to_int c.g)
+                push outB (to_int c.b)
+            }
+            i = (i + 1)
+        }
+        return (array_length outR)
+    }
+
+    ; The seeding score for one histogram bin. "area" is population × distance²,
+    ; which is why a photo's big flat background always takes the first swatches;
+    ; the other two trade that away for colors that are merely distinct.
+    ; How colorful a color is, 0 = neutral, 1 = as colorful as this picture is
+    ; likely to get. OKLab chroma, normalized by 0.10 rather than by the 0.32
+    ; a pure sRGB primary reaches: normalized against the primaries every
+    ;色 an actual picture contains lands in the bottom fifth of the range and
+    ; the dial does nothing. At 0.10 the ochre of a boat hull reads 0.79 and
+    ; the grey of the sea 0.16, which is the separation the dial is for.
+    fn chromaOf:double (r:int g:int b:int) {
+        if ((array_length okLin) == 0) {
+            okLin = (EvgTraceColor.buildLinearTable())
+        }
+        okC.setFrom(okLin r g b)
+        def c:EvgOklab (unwrap okC)
+        def ca:double c.a
+        def cb:double c.b
+        def mag:double (sqrt ((ca * ca) + (cb * cb)))
+        def norm:double (mag / 0.10)
+        if (norm > 1.0) {
+            return 1.0
+        }
+        return norm
+    }
+
+    ; ----------------------------------------------------------------------
+    ; The palette objective (options.paletteMute / Tint / Warm / Contrast)
+    ; ----------------------------------------------------------------------
+    ;
+    ; Quantization answers "which colors are in this picture". It does not
+    ; answer "which colors should this picture be painted in", and the second
+    ; question has no exact match to snap to. A palette that lands on the
+    ; measured mean of every region is faithful and often dead: the mean of a
+    ; large region is a neutral, the mean of a small vivid one rarely survives
+    ; to be asked, and a picture built out of eight measured means has no color
+    ; in it that a painter would have chosen.
+    ;
+    ; So the palette gets its own objective, dialled rather than measured, in
+    ; OKLab where the dials mean what their names say. It runs AFTER
+    ; assignLabels: every decision about where an edge goes, which swatch a
+    ; pixel joins and which small region survives has already been made against
+    ; the measured colors, and what moves here is only what the picture is
+    ; painted with. Each dial is identity at its default, so an untouched
+    ; trace comes out exactly as before.
+    fn gradePalette:void (palR:[int] palG:[int] palB:[int]) {
+        def mute:int options.paletteMute
+        def tint:int options.paletteTint
+        def warm:int options.paletteWarm
+        def contrast:int options.paletteContrast
+        def on:boolean false
+        if (mute != 100) {
+            on = true
+        }
+        if (tint > 0) {
+            on = true
+        }
+        if (warm != 0) {
+            on = true
+        }
+        if (contrast != 100) {
+            on = true
+        }
+        if (on == false) {
+            return
+        }
+        def k:int (array_length palR)
+        if (k == 0) {
+            return
+        }
+        if ((array_length okLin) == 0) {
+            okLin = (EvgTraceColor.buildLinearTable())
+        }
+
+        ; Read the palette into OKLab. Two things about the palette as a whole
+        ; are needed: the lightness the contrast dial pivots about, and the hue
+        ; a swatch with no hue of its own is tinted in.
+        def ls:[double]
+        def cas:[double]
+        def cbs:[double]
+        def sumL:double 0.0
+        def sumA:double 0.0
+        def sumB:double 0.0
+        def i:int 0
+        while (i < k) {
+            okC.setFrom(okLin (itemAt palR i) (itemAt palG i) (itemAt palB i))
+            def c:EvgOklab (unwrap okC)
+            def cl:double c.l
+            def ca:double c.a
+            def cb:double c.b
+            push ls cl
+            push cas ca
+            push cbs cb
+            sumL = (sumL + cl)
+            sumA = (sumA + ca)
+            sumB = (sumB + cb)
+            i = (i + 1)
+        }
+        def kd:double (to_double k)
+        def meanL:double (sumL / kd)
+        def meanA:double (sumA / kd)
+        def meanB:double (sumB / kd)
+        def meanMag:double (sqrt ((meanA * meanA) + (meanB * meanB)))
+        ; A palette with no color at all still has to tint somewhere; yellow is
+        ; the direction paper and skin already lean, so it is the least
+        ; surprising default.
+        def dirA:double 0.0
+        def dirB:double 1.0
+        if (meanMag > 0.000001) {
+            dirA = (meanA / meanMag)
+            dirB = (meanB / meanMag)
+        }
+
+        def wd:double ((to_double warm) / 1000.0)
+        def floorC:double ((to_double tint) / 1000.0)
+        def ms:double ((to_double mute) / 100.0)
+        def cs:double ((to_double contrast) / 100.0)
+        i = 0
+        while (i < k) {
+            ; Warmth first, as a shift along the yellow–blue axis. That is what
+            ; a temperature change physically is, and unlike a hue rotation it
+            ; leaves a neutral neutral-ish instead of spinning it somewhere.
+            def la:double (itemAt cas i)
+            def lb:double ((itemAt cbs i) + wd)
+            def mag:double (sqrt ((la * la) + (lb * lb)))
+            def na:double dirA
+            def nb:double dirB
+            if (mag > 0.000001) {
+                na = (la / mag)
+                nb = (lb / mag)
+            }
+            ; Chroma: scaled, then never below the tint floor, so the palette
+            ; can be broken toward grey without any swatch reaching dead grey.
+            def chroma:double (mag * ms)
+            if (chroma < floorC) {
+                chroma = floorC
+            }
+            def lightness:double (meanL + (((itemAt ls i) - meanL) * cs))
+            if (lightness < 0.0) {
+                lightness = 0.0
+            }
+            if (lightness > 1.0) {
+                lightness = 1.0
+            }
+            def outA:double (na * chroma)
+            def outB:double (nb * chroma)
+            def rgb:[int] (EvgTraceColor.srgbOf(lightness outA outB))
+            set palR i (itemAt rgb 0)
+            set palG i (itemAt rgb 1)
+            set palB i (itemAt rgb 2)
+            i = (i + 1)
+        }
+    }
+
+    ; What one histogram bin is worth when the palette is decided.
+    ;
+    ; This is the objective, and it is not the same question as "reproduce the
+    ; picture". k-means over pixel counts minimizes total squared error, and a
+    ; color covering one percent of the frame contributes one percent of that
+    ; error — so dropping it is cheap by that measure and free by any measure
+    ; the quantizer can see. To a viewer it is the boats. options.paletteBias
+    ; chooses what a swatch is spent on and options.paletteChroma says how much
+    ; being colorful counts on top of it.
+    ;
+    ; The weight is used for the seeding, for the Lloyd passes, and for moving
+    ; a stranded swatch — every step that decides *where* a swatch sits. It is
+    ; deliberately not used for the noise floor, which stays on true population
+    ; so a single stray saturated pixel cannot buy a swatch, nor for the merge,
+    ; where the question is only which of two indistinguishable colors is the
+    ; representative and population is the right answer.
+    fn binWeight:double (w:int r:int g:int b:int) {
+        def bias:string options.paletteBias
+        def base:double (to_double w)
+        if (bias == "balanced") {
+            base = (sqrt base)
+        }
+        if (bias == "distinct") {
+            ; Every color present counts once, however much of it there is.
+            base = 1.0
+        }
+        def gain:int options.paletteChroma
+        if (gain <= 0) {
+            return base
+        }
+        def c:double (this.chromaOf(r g b))
+        def g2:double (to_double gain)
+        def mul:double (1.0 + ((g2 / 100.0) * c))
+        return (base * mul)
+    }
+
+    fn seedScore:double (weight:double dist2:double) {
+        return (weight * dist2)
+    }
+
+    ; `outR/outG/outB` may arrive holding `locked` pinned swatches; those are
+    ; seeds the caller chose, so they are never moved by a Lloyd pass and never
+    ; dropped by the merge.
+    fn buildPalette:void (want:int locked:int outR:[int] outG:[int] outB:[int]) {
+        def binR:[int]
+        def binG:[int]
+        def binB:[int]
+        def binW:[int]
+        this.buildHistogram(true binR binG binB binW)
+        ; Line art can be thin enough to have no plateau at all — then let every
+        ; allowed pixel vote rather than emitting nothing.
+        if ((array_length binR) < 2) {
+            def allR:[int]
+            def allG:[int]
+            def allB:[int]
+            def allW:[int]
+            this.buildHistogram(false allR allG allB allW)
+            binR = allR
+            binG = allG
+            binB = allB
+            binW = allW
+        }
+        def m:int (array_length binR)
+        if (m == 0) {
+            return
+        }
+        ; A bin has to clear a noise floor before it can win a swatch. Only the
+        ; "distinct" bias would otherwise hand one to a single stray pixel.
+        def total:int 0
+        def i:int 0
+        while (i < m) {
+            total = (total + (itemAt binW i))
+            i = (i + 1)
+        }
+        def floorW:int (idiv total 2000)
+        if (floorW < 2) {
+            floorW = 2
+        }
+        if (locked == 0) {
+            ; Seed 1: the heaviest bin.
+            def bestI:int 0
+            def bestW:int (itemAt binW 0)
+            i = 1
+            while (i < m) {
+                if ((itemAt binW i) > bestW) {
+                    bestW = (itemAt binW i)
+                    bestI = i
+                }
+                i = (i + 1)
+            }
+            push outR (itemAt binR bestI)
+            push outG (itemAt binG bestI)
+            push outB (itemAt binB bestI)
+        }
+        ; Remaining seeds: maximize seedScore against the closest center so far.
+        def dist:[double]
+        i = 0
+        while (i < m) {
+            push dist (this.dist2((itemAt binR i) (itemAt binG i) (itemAt binB i) (itemAt outR 0) (itemAt outG 0) (itemAt outB 0)))
+            i = (i + 1)
+        }
+        def seeded:int 1
+        while (seeded < (array_length outR)) {
+            i = 0
+            while (i < m) {
+                def d0:double (this.dist2((itemAt binR i) (itemAt binG i) (itemAt binB i) (itemAt outR seeded) (itemAt outG seeded) (itemAt outB seeded)))
+                if (d0 < (itemAt dist i)) {
+                    set dist i d0
+                }
+                i = (i + 1)
+            }
+            seeded = (seeded + 1)
+        }
+        while ((array_length outR) < want) {
+            def pickI:int (0 - 1)
+            def pickScore:double 0.0
+            i = 0
+            while (i < m) {
+                if ((itemAt binW i) >= floorW) {
+                    def bw:double (this.binWeight((itemAt binW i) (itemAt binR i) (itemAt binG i) (itemAt binB i)))
+                    def score:double (this.seedScore(bw (itemAt dist i)))
+                    if (score > pickScore) {
+                        pickScore = score
+                        pickI = i
+                    }
+                }
+                i = (i + 1)
+            }
+            if (pickI < 0) {
+                want = (array_length outR)
+            } {
+                def cr:int (itemAt binR pickI)
+                def cg:int (itemAt binG pickI)
+                def cb:int (itemAt binB pickI)
+                push outR cr
+                push outG cg
+                push outB cb
+                i = 0
+                while (i < m) {
+                    def d:double (this.dist2((itemAt binR i) (itemAt binG i) (itemAt binB i) cr cg cb))
+                    if (d < (itemAt dist i)) {
+                        set dist i d
+                    }
+                    i = (i + 1)
+                }
+            }
+        }
+        ; Lloyd passes, weighted by bin population.
+        def k:int (array_length outR)
+        def pass:int 0
+        while (pass < 12) {
+            def sumR:[double]
+            def sumG:[double]
+            def sumB:[double]
+            def wgt:[double]
+            def ki:int 0
+            while (ki < k) {
+                push sumR 0.0
+                push sumG 0.0
+                push sumB 0.0
+                push wgt 0.0
+                ki = (ki + 1)
+            }
+            i = 0
+            while (i < m) {
+                def br:int (itemAt binR i)
+                def bg:int (itemAt binG i)
+                def bb:int (itemAt binB i)
+                def best:int (this.nearestIndex(br bg bb outR outG outB))
+                def w:double (this.binWeight((itemAt binW i) br bg bb))
+                set sumR best ((itemAt sumR best) + ((to_double br) * w))
+                set sumG best ((itemAt sumG best) + ((to_double bg) * w))
+                set sumB best ((itemAt sumB best) + ((to_double bb) * w))
+                set wgt best ((itemAt wgt best) + w)
+                set dist i 0.0
+                i = (i + 1)
+            }
+            def moved:boolean false
+            ki = locked
+            while (ki < k) {
+                def wk:double (itemAt wgt ki)
+                if (wk > 0.0) {
+                    def nr:int (to_int ((itemAt sumR ki) / wk))
+                    def ng:int (to_int ((itemAt sumG ki) / wk))
+                    def nb:int (to_int ((itemAt sumB ki) / wk))
+                    if ((nr != (itemAt outR ki)) || (ng != (itemAt outG ki)) || (nb != (itemAt outB ki))) {
+                        moved = true
+                    }
+                    set outR ki nr
+                    set outG ki ng
+                    set outB ki nb
+                } {
+                    ; An empty swatch paints nothing — move it onto the bin that
+                    ; is worst served right now instead of leaving it stranded.
+                    def farI:int (0 - 1)
+                    def farScore:double 0.0
+                    i = 0
+                    while (i < m) {
+                        def dd:double (this.dist2((itemAt binR i) (itemAt binG i) (itemAt binB i) (itemAt outR (this.nearestIndex((itemAt binR i) (itemAt binG i) (itemAt binB i) outR outG outB))) (itemAt outG (this.nearestIndex((itemAt binR i) (itemAt binG i) (itemAt binB i) outR outG outB))) (itemAt outB (this.nearestIndex((itemAt binR i) (itemAt binG i) (itemAt binB i) outR outG outB)))))
+                        def bw2:double (this.binWeight((itemAt binW i) (itemAt binR i) (itemAt binG i) (itemAt binB i)))
+                        def sc:double (dd * bw2)
+                        if (sc > farScore) {
+                            farScore = sc
+                            farI = i
+                        }
+                        i = (i + 1)
+                    }
+                    if (farI >= 0) {
+                        set outR ki (itemAt binR farI)
+                        set outG ki (itemAt binG farI)
+                        set outB ki (itemAt binB farI)
+                        moved = true
+                    }
+                }
+                ki = (ki + 1)
+            }
+            if (moved) {
+                pass = (pass + 1)
+            } {
+                pass = 12
+            }
+        }
+        ; Collapse swatches the eye cannot tell apart. Without this, asking for
+        ; more colors than the image holds splits one region between two
+        ; near-identical swatches and turdsize eats both halves.
+        this.mergeCloseSwatches(locked outR outG outB binR binG binB binW)
+        ; Sort palette dark → light (ascending luma). Masks are disjoint so
+        ; paint order is mostly cosmetic; lightest ends up last.
+        def k2:int (array_length outR)
+        def a:int 0
+        while (a < k2) {
+            def bIdx:int (a + 1)
+            while (bIdx < k2) {
+                def la:int (EvgBitmapTracer.lumaOf((itemAt outR a) (itemAt outG a) (itemAt outB a)))
+                def lb:int (EvgBitmapTracer.lumaOf((itemAt outR bIdx) (itemAt outG bIdx) (itemAt outB bIdx)))
+                if (la > lb) {
+                    def tr:int (itemAt outR a)
+                    def tg:int (itemAt outG a)
+                    def tb:int (itemAt outB a)
+                    set outR a (itemAt outR bIdx)
+                    set outG a (itemAt outG bIdx)
+                    set outB a (itemAt outB bIdx)
+                    set outR bIdx tr
+                    set outG bIdx tg
+                    set outB bIdx tb
+                }
+                bIdx = (bIdx + 1)
+            }
+            a = (a + 1)
+        }
+    }
+
+    ; Merge palette entries closer than options.minColorDelta, keeping whichever
+    ; of the pair paints more pixels. The first `locked` entries were chosen by
+    ; the caller: a pair of them is left alone, and against an automatic swatch
+    ; the locked one is what survives.
+    fn mergeCloseSwatches:void (locked:int outR:[int] outG:[int] outB:[int] binR:[int] binG:[int] binB:[int] binW:[int]) {
+        def delta:int options.minColorDelta
+        if (delta <= 0) {
+            return
+        }
+        ; Same metric the assignment uses, scaled so `delta` still reads as a
+        ; per-channel difference whichever space is measuring.
+        def limit:double (this.dist2Limit(delta))
+        def merged:boolean true
+        while merged {
+            merged = false
+            def k:int (array_length outR)
+            if (k < 2) {
+                return
+            }
+            ; Population of each swatch, so the survivor is the one that paints.
+            def wgt:[int]
+            def ki:int 0
+            while (ki < k) {
+                push wgt 0
+                ki = (ki + 1)
+            }
+            def m:int (array_length binR)
+            def i:int 0
+            while (i < m) {
+                def idx:int (this.nearestIndex((itemAt binR i) (itemAt binG i) (itemAt binB i) outR outG outB))
+                set wgt idx ((itemAt wgt idx) + (itemAt binW i))
+                i = (i + 1)
+            }
+            def dropAt:int (0 - 1)
+            def a:int 0
+            while ((a < k) && (dropAt < 0)) {
+                def b:int (a + 1)
+                while ((b < k) && (dropAt < 0)) {
+                    def d:double (this.dist2((itemAt outR a) (itemAt outG a) (itemAt outB a) (itemAt outR b) (itemAt outG b) (itemAt outB b)))
+                    if (d <= limit) {
+                        if (b < locked) {
+                            ; both pinned — the caller asked for both.
+                        } {
+                            if (a < locked) {
+                                dropAt = b
+                            } {
+                                if ((itemAt wgt a) >= (itemAt wgt b)) {
+                                    dropAt = b
+                                } {
+                                    dropAt = a
+                                }
+                            }
+                        }
+                    }
+                    b = (b + 1)
+                }
+                a = (a + 1)
+            }
+            if (dropAt >= 0) {
+                remove outR dropAt
+                remove outG dropAt
+                remove outB dropAt
+                merged = true
+            }
+        }
+    }
+
+    fn nearestIndex:int (r:int g:int b:int palR:[int] palG:[int] palB:[int]) {
+        def k:int (array_length palR)
+        if (k == 0) {
+            return 0
+        }
+        def best:int 0
+        def bestD:double (this.dist2(r g b (itemAt palR 0) (itemAt palG 0) (itemAt palB 0)))
+        def j:int 1
+        while (j < k) {
+            def d:double (this.dist2(r g b (itemAt palR j) (itemAt palG j) (itemAt palB j)))
+            if (d < bestD) {
+                bestD = d
+                best = j
+            }
+            j = (j + 1)
+        }
+        return best
+    }
+
+    ; ----------------------------------------------------------------------
+    ; Pixel → swatch assignment
+    ; ----------------------------------------------------------------------
+
+    ; Every allowed pixel takes its nearest swatch. A transitional pixel is
+    ; then re-checked against the regions actually touching it: it only moves
+    ; there when the neighbouring swatch fits about as well as the global best
+    ; (snapRatio). That guard matters — the one-pixel ink core of a thin
+    ; anti-aliased outline is transitional too, and an unguarded snap hands it
+    ; to the big region beside it, which is what turns outlines into dashes.
+    fn assignLabels:void (palR:[int] palG:[int] palB:[int]) {
+        def n:int (width * height)
+        def base:[int]
+        def dists:[double]
+        def i:int 0
+        while (i < n) {
+            push base (0 - 1)
+            push dists 0.0
+            i = (i + 1)
+        }
+        i = 0
+        while (i < n) {
+            if (this.pixelAllowed(i)) {
+                def lab:int (this.nearestIndex((itemAt planeR i) (itemAt planeG i) (itemAt planeB i) palR palG palB))
+                set base i lab
+                set dists i (this.dist2((itemAt planeR i) (itemAt planeG i) (itemAt planeB i) (itemAt palR lab) (itemAt palG lab) (itemAt palB lab)))
+            }
+            i = (i + 1)
+        }
+        def outL:[int]
+        i = 0
+        while (i < n) {
+            push outL (itemAt base i)
+            i = (i + 1)
+        }
+        def hasFlat:boolean ((array_length flat) == n)
+        if (options.edgeSnap && hasFlat) {
+            def ratio:double options.snapRatio
+            def y:int 0
+            while (y < height) {
+                def x:int 0
+                while (x < width) {
+                    def idx:int ((y * width) + x)
+                    def gLab:int (itemAt base idx)
+                    if ((gLab >= 0) && ((itemAt flat idx) == 0)) {
+                        def gD:double (itemAt dists idx)
+                        def pr:int (itemAt planeR idx)
+                        def pg:int (itemAt planeG idx)
+                        def pb:int (itemAt planeB idx)
+                        def nLab:int (0 - 1)
+                        def nD:double 0.0
+                        def dy:int (0 - 1)
+                        while (dy <= 1) {
+                            def yy:int (y + dy)
+                            if ((yy >= 0) && (yy < height)) {
+                                def dx:int (0 - 1)
+                                while (dx <= 1) {
+                                    def xx:int (x + dx)
+                                    if ((xx >= 0) && (xx < width)) {
+                                        def nIdx:int ((yy * width) + xx)
+                                        if ((itemAt flat nIdx) == 1) {
+                                            def lab2:int (itemAt base nIdx)
+                                            if (lab2 >= 0) {
+                                                def d:double (this.dist2(pr pg pb (itemAt palR lab2) (itemAt palG lab2) (itemAt palB lab2)))
+                                                if ((nLab < 0) || (d < nD)) {
+                                                    nLab = lab2
+                                                    nD = d
+                                                }
+                                            }
+                                        }
+                                    }
+                                    dx = (dx + 1)
+                                }
+                            }
+                            dy = (dy + 1)
+                        }
+                        if ((nLab >= 0) && (nLab != gLab)) {
+                            if (nD <= ((gD * ratio) + 1.0)) {
+                                set outL idx nLab
+                            }
+                        }
+                    }
+                    x = (x + 1)
+                }
+                y = (y + 1)
+            }
+        }
+        labels = outL
+        this.despeckleLabels()
+        this.smoothContours(palR palG palB)
+        this.mergeTinyRegions(palR palG palB)
+    }
+
+    ; ----------------------------------------------------------------------
+    ; Banding suppression (options.contourMode)
+    ; ----------------------------------------------------------------------
+
+    ; One step of the continuity walk. A neighbour joins when the step to it is
+    ; small enough to read as continuous AND it has not drifted too far from
+    ; what the region has averaged so far — the second test is what stops a
+    ; gradient from walking off across the whole picture.
+    fn contourStep:void (i:int from:int seen:[int] stack:[int] acc:[int] edgeTol:int spread:int) {
+        if ((itemAt seen i) != 0) {
+            return
+        }
+        if ((itemAt labels i) < 0) {
+            return
+        }
+        ; A step stops the growth only when it is a boundary: strongest across
+        ; its own direction, and part of a run rather than a speck. On a
+        ; photograph nearly every neighbouring pair differs by a few levels, so
+        ; taking each one at face value stops the growth everywhere and the
+        ; picture comes apart into noise.
+        if (this.isBoundary(from i edgeTol)) {
+            return
+        }
+        def cnt:int (itemAt acc 3)
+        if (cnt > 0) {
+            def mr:int (idiv (itemAt acc 0) cnt)
+            def mg:int (idiv (itemAt acc 1) cnt)
+            def mb:int (idiv (itemAt acc 2) cnt)
+            def d:int (EvgBitmapTracer.absI((itemAt planeR i) - mr))
+            def dg:int (EvgBitmapTracer.absI((itemAt planeG i) - mg))
+            if (dg > d) {
+                d = dg
+            }
+            def db:int (EvgBitmapTracer.absI((itemAt planeB i) - mb))
+            if (db > d) {
+                d = db
+            }
+            if (d > spread) {
+                return
+            }
+        }
+        set seen i 1
+        push stack i
+        set acc 0 ((itemAt acc 0) + (itemAt planeR i))
+        set acc 1 ((itemAt acc 1) + (itemAt planeG i))
+        set acc 2 ((itemAt acc 2) + (itemAt planeB i))
+        set acc 3 (cnt + 1)
+    }
+
+    ; ----------------------------------------------------------------------
+    ; Which steps are boundaries and which are noise
+    ; ----------------------------------------------------------------------
+
+    ; Mark the steps that are worth treating as boundaries. Two tests, and a
+    ; step has to pass both:
+    ;   unique     — it is at least as strong as the steps either side of it
+    ;                ACROSS its own direction. A ridge keeps its crest; a lone
+    ;                noisy pixel loses to whatever it sits next to.
+    ;   continuous — it belongs to a run of at least edgeMinRun such pixels.
+    ;                A boundary is a line; noise is scattered.
+    ; Mark the neighbourhoods that need fine work.
+    ;
+    ; Not every busy patch of a picture is the same kind of busy. A gradient is
+    ; busy and wants to be left alone; an eye is busy because three or four
+    ; plainly different colors — the white, the iris, the lash, the skin — meet
+    ; inside a few pixels, and that is detail a coarse pass throws away. The
+    ; test is therefore both halves at once: several distinct swatches inside a
+    ; small window *and* a wide luma spread across it. A smooth ramp fails the
+    ; first (its window is one or two swatches), and a patch of noise in one
+    ; flat color fails the second.
+    ;
+    ; Overlay uses this to work at a finer grain where it finds it, and only
+    ; there, which is what lets the whites and the darks of an eye be resolved
+    ; without spending the same effort on a cheek.
+    fn buildDetailMask:void () {
+        def n:int (width * height)
+        def dm:[int]
+        def i:int 0
+        while (i < n) {
+            push dm 0
+            i = (i + 1)
+        }
+        detailMask = dm
+        detailOn = ((options.detailBoost) >= 2)
+        def minSwatches:int options.detailSwatches
+        if (minSwatches < 2) {
+            return
+        }
+        def minSpread:int options.detailSpread
+        def r:int options.detailRadius
+        if (r < 1) {
+            r = 1
+        }
+        def lum:[int]
+        i = 0
+        while (i < n) {
+            push lum (EvgBitmapTracer.lumaOf((itemAt planeR i) (itemAt planeG i) (itemAt planeB i)))
+            i = (i + 1)
+        }
+        ; One slot per swatch, stamped with the window it was last seen in,
+        ; instead of a fresh list per pixel searched linearly. The old form
+        ; allocated an array for every pixel in the image and scanned it once
+        ; per neighbour — a quarter of a million allocations to answer "how many
+        ; different swatches are in this little square".
+        def mark:[int]
+        def mi:int 0
+        def marks:int 256
+        while (mi < marks) {
+            push mark (0 - 1)
+            mi = (mi + 1)
+        }
+        def visit:int 0
+        def y:int 0
+        while (y < height) {
+            def x:int 0
+            while (x < width) {
+                visit = (visit + 1)
+                def distinct:int 0
+                def lo:int 256
+                def hi:int (0 - 1)
+                def dy:int (0 - r)
+                while (dy <= r) {
+                    def yy:int (y + dy)
+                    if ((yy >= 0) && (yy < height)) {
+                        def dx:int (0 - r)
+                        while (dx <= r) {
+                            def xx:int (x + dx)
+                            if ((xx >= 0) && (xx < width)) {
+                                def q:int ((yy * width) + xx)
+                                def lab:int (itemAt labels q)
+                                if (lab >= 0) {
+                                    if (lab < marks) {
+                                        if ((itemAt mark lab) != visit) {
+                                            set mark lab visit
+                                            distinct = (distinct + 1)
+                                        }
+                                    }
+                                    def lv:int (itemAt lum q)
+                                    if (lv < lo) {
+                                        lo = lv
+                                    }
+                                    if (lv > hi) {
+                                        hi = lv
+                                    }
+                                }
+                            }
+                            dx = (dx + 1)
+                        }
+                    }
+                    dy = (dy + 1)
+                }
+                if (distinct >= minSwatches) {
+                    if ((hi - lo) >= minSpread) {
+                        set dm ((y * width) + x) 1
+                    }
+                }
+                x = (x + 1)
+            }
+            y = (y + 1)
+        }
+        ; What the test marks is where the colors *meet* — a ring around an eye
+        ; rather than the eye. The flat middle of a pupil is as plain as a cheek
+        ; by this measure, and left out it would split the feature in two.
+        ; Growing the mark by the window radius closes the ring into the shape a
+        ; person would have drawn around the feature.
+        def grown:[int]
+        i = 0
+        while (i < n) {
+            push grown (itemAt dm i)
+            i = (i + 1)
+        }
+        def gy:int 0
+        while (gy < height) {
+            def gx:int 0
+            while (gx < width) {
+                if ((itemAt dm ((gy * width) + gx)) == 1) {
+                    def dy2:int (0 - r)
+                    while (dy2 <= r) {
+                        def yy2:int (gy + dy2)
+                        if ((yy2 >= 0) && (yy2 < height)) {
+                            def dx2:int (0 - r)
+                            while (dx2 <= r) {
+                                def xx2:int (gx + dx2)
+                                if ((xx2 >= 0) && (xx2 < width)) {
+                                    set grown ((yy2 * width) + xx2) 1
+                                }
+                                dx2 = (dx2 + 1)
+                            }
+                        }
+                        dy2 = (dy2 + 1)
+                    }
+                }
+                gx = (gx + 1)
+            }
+            gy = (gy + 1)
+        }
+        detailMask = grown
+        detailOn = ((options.detailBoost) >= 2)
+    }
+
+    fn buildEdgeMask:void () {
+        def n:int (width * height)
+        def keep:[int]
+        def mag:[int]
+        def lum:[int]
+        def i:int 0
+        while (i < n) {
+            push keep 0
+            push mag 0
+            push lum (EvgBitmapTracer.lumaOf((itemAt planeR i) (itemAt planeG i) (itemAt planeB i)))
+            i = (i + 1)
+        }
+        if ((options.edgeMinRun) < 1) {
+            edgeMask = keep
+            edgeMaskOn = false
+            return
+        }
+        def edgeTol:int options.contourEdge
+        if (edgeTol < 1) {
+            edgeTol = 1
+        }
+        ; --- magnitude ---
+        def y:int 1
+        while (y < (height - 1)) {
+            def x:int 1
+            while (x < (width - 1)) {
+                def idx:int ((y * width) + x)
+                def gx:int ((itemAt lum (idx + 1)) - (itemAt lum (idx - 1)))
+                def gy:int ((itemAt lum (idx + width)) - (itemAt lum (idx - width)))
+                set mag idx ((EvgBitmapTracer.absI(gx)) + (EvgBitmapTracer.absI(gy)))
+                x = (x + 1)
+            }
+            y = (y + 1)
+        }
+        ; --- unique: strongest across its own direction ---
+        y = 1
+        while (y < (height - 1)) {
+            def x2:int 1
+            while (x2 < (width - 1)) {
+                def idx2:int ((y * width) + x2)
+                def m:int (itemAt mag idx2)
+                if (m > edgeTol) {
+                    def gx2:int ((itemAt lum (idx2 + 1)) - (itemAt lum (idx2 - 1)))
+                    def gy2:int ((itemAt lum (idx2 + width)) - (itemAt lum (idx2 - width)))
+                    def ax:int (EvgBitmapTracer.absI(gx2))
+                    def ay:int (EvgBitmapTracer.absI(gy2))
+                    def a:int 0
+                    def b:int 0
+                    if (ax > (ay * 2)) {
+                        a = (idx2 - 1)
+                        b = (idx2 + 1)
+                    } {
+                        if (ay > (ax * 2)) {
+                            a = (idx2 - width)
+                            b = (idx2 + width)
+                        } {
+                            if ((gx2 * gy2) > 0) {
+                                a = ((idx2 - width) - 1)
+                                b = ((idx2 + width) + 1)
+                            } {
+                                a = ((idx2 - width) + 1)
+                                b = ((idx2 + width) - 1)
+                            }
+                        }
+                    }
+                    if ((m >= (itemAt mag a)) && (m >= (itemAt mag b))) {
+                        set keep idx2 1
+                    }
+                }
+                x2 = (x2 + 1)
+            }
+            y = (y + 1)
+        }
+        ; --- continuous: drop runs shorter than edgeMinRun ---
+        def minRun:int options.edgeMinRun
+        def seen:[int]
+        i = 0
+        while (i < n) {
+            push seen 0
+            i = (i + 1)
+        }
+        def start:int 0
+        while (start < n) {
+            if (((itemAt keep start) == 1) && ((itemAt seen start) == 0)) {
+                def comp:[int]
+                def stack:[int]
+                set seen start 1
+                push stack start
+                def head:int 0
+                while (head < (array_length stack)) {
+                    def cur:int (itemAt stack head)
+                    head = (head + 1)
+                    push comp cur
+                    def cy:int (idiv cur width)
+                    def cx:int (cur - (cy * width))
+                    def dy:int (0 - 1)
+                    while (dy <= 1) {
+                        def yy:int (cy + dy)
+                        if ((yy >= 0) && (yy < height)) {
+                            def dx:int (0 - 1)
+                            while (dx <= 1) {
+                                def xx:int (cx + dx)
+                                if ((xx >= 0) && (xx < width)) {
+                                    def j:int ((yy * width) + xx)
+                                    if (((itemAt keep j) == 1) && ((itemAt seen j) == 0)) {
+                                        set seen j 1
+                                        push stack j
+                                    }
+                                }
+                                dx = (dx + 1)
+                            }
+                        }
+                        dy = (dy + 1)
+                    }
+                }
+                if ((array_length comp) < minRun) {
+                    def c:int 0
+                    while (c < (array_length comp)) {
+                        set keep (itemAt comp c) 0
+                        c = (c + 1)
+                    }
+                }
+            }
+            start = (start + 1)
+        }
+        edgeMask = keep
+    }
+
+    ; True when the step from `a` to `b` should split two regions: big enough,
+    ; and landing on a boundary that passed both tests rather than on noise.
+    fn isBoundary:boolean (a:int b:int edgeTol:int) {
+        return (this.isBoundaryOf(a b edgeTol (this.pixelDelta(a b))))
+    }
+
+    ; The same test for a caller that has already measured the step. The growth
+    ; loop had measured it, compared it to the tolerance, and then called in
+    ; here — which measured it again. pixelDelta was a fifth of the trace.
+    fn isBoundaryOf:boolean (a:int b:int edgeTol:int delta:int) {
+        if (delta <= edgeTol) {
+            return false
+        }
+        if (edgeMaskOn == false) {
+            return true
+        }
+        if ((itemAt edgeMask b) == 1) {
+            return true
+        }
+        return ((itemAt edgeMask a) == 1)
+    }
+
+    ; Grow every allowed pixel into a region of continuous color and record
+    ; which region it landed in. Both the banding fix and the gradient fills
+    ; read this; it is the segmentation, and everything downstream is a choice
+    ; of what to paint each region with.
+    fn buildContourRegions:void () {
+        this.buildEdgeMask()
+        def edgeTol:int options.contourEdge
+        if (edgeTol < 1) {
+            edgeTol = 1
+        }
+        def spread:int options.contourSpread
+        if (spread < 1) {
+            spread = 1
+        }
+        def n:int (width * height)
+        def ro:[int]
+        def seen:[int]
+        def i:int 0
+        while (i < n) {
+            push ro (0 - 1)
+            push seen 0
+            i = (i + 1)
+        }
+        def rid:int 0
+        def start:int 0
+        while (start < n) {
+            if (((itemAt seen start) == 0) && ((itemAt labels start) >= 0)) {
+                def stack:[int]
+                def acc:[int]
+                push acc (itemAt planeR start)
+                push acc (itemAt planeG start)
+                push acc (itemAt planeB start)
+                push acc 1
+                set seen start 1
+                push stack start
+                def head:int 0
+                while (head < (array_length stack)) {
+                    def cur:int (itemAt stack head)
+                    head = (head + 1)
+                    set ro cur rid
+                    def cy:int (idiv cur width)
+                    def cx:int (cur - (cy * width))
+                    if (cx > 0) {
+                        this.contourStep((cur - 1) cur seen stack acc edgeTol spread)
+                    }
+                    if (cx < (width - 1)) {
+                        this.contourStep((cur + 1) cur seen stack acc edgeTol spread)
+                    }
+                    if (cy > 0) {
+                        this.contourStep((cur - width) cur seen stack acc edgeTol spread)
+                    }
+                    if (cy < (height - 1)) {
+                        this.contourStep((cur + width) cur seen stack acc edgeTol spread)
+                    }
+                }
+                rid = (rid + 1)
+            }
+            start = (start + 1)
+        }
+        regionOf = ro
+        regionCount = rid
+    }
+
+    ; Give each continuity region the one swatch nearest its own mean, so a
+    ; ramp stops being cut into bands.
+    fn smoothContours:void (palR:[int] palG:[int] palB:[int]) {
+        if ((options.contourMode) != "smooth") {
+            return
+        }
+        this.buildContourRegions()
+        def k:int regionCount
+        if (k == 0) {
+            return
+        }
+        def sumR:[int]
+        def sumG:[int]
+        def sumB:[int]
+        def cnt:[int]
+        def i:int 0
+        while (i < k) {
+            push sumR 0
+            push sumG 0
+            push sumB 0
+            push cnt 0
+            i = (i + 1)
+        }
+        def n:int (width * height)
+        i = 0
+        while (i < n) {
+            def r:int (itemAt regionOf i)
+            if (r >= 0) {
+                set sumR r ((itemAt sumR r) + (itemAt planeR i))
+                set sumG r ((itemAt sumG r) + (itemAt planeG i))
+                set sumB r ((itemAt sumB r) + (itemAt planeB i))
+                set cnt r ((itemAt cnt r) + 1)
+            }
+            i = (i + 1)
+        }
+        def lab:[int]
+        i = 0
+        while (i < k) {
+            def c:int (itemAt cnt i)
+            if (c > 0) {
+                push lab (this.nearestIndex((idiv (itemAt sumR i) c) (idiv (itemAt sumG i) c) (idiv (itemAt sumB i) c) palR palG palB))
+            } {
+                push lab 0
+            }
+            i = (i + 1)
+        }
+        i = 0
+        while (i < n) {
+            def r2:int (itemAt regionOf i)
+            if (r2 >= 0) {
+                set labels i (itemAt lab r2)
+            }
+            i = (i + 1)
+        }
+    }
+
+    ; ----------------------------------------------------------------------
+    ; Gradient fills (options.gradientFill)
+    ;
+    ; Each continuity region is fitted with three models — one flat color, a
+    ; linear ramp — and keeps whichever leaves the least error. A radial model
+    ; is fitted alongside them but not used: away from a genuinely round region
+    ; its cone infers structure the picture does not contain.
+    ; ----------------------------------------------------------------------
+
+    sfn clamp255:int (v:double) {
+        if (v < 0.0) {
+            return 0
+        }
+        if (v > 255.0) {
+            return 255
+        }
+        return (to_int v)
+    }
+
+    ; Merge any region below minPx into whichever neighbour it shares the most
+    ; boundary with, then renumber what is left from zero.
+    fn absorbTinyRegions:void (minPx:int) {
+        def k:int regionCount
+        if (k == 0) {
+            return
+        }
+        def n:int (width * height)
+        def size:[int]
+        def i:int 0
+        while (i < k) {
+            push size 0
+            i = (i + 1)
+        }
+        i = 0
+        while (i < n) {
+            def r:int (itemAt regionOf i)
+            if (r >= 0) {
+                set size r ((itemAt size r) + 1)
+            }
+            i = (i + 1)
+        }
+        ; One pass: every small region takes the neighbour it touches most.
+        def target:[int]
+        i = 0
+        while (i < k) {
+            push target i
+            i = (i + 1)
+        }
+        def bestN:[int]
+        def bestR:[int]
+        i = 0
+        while (i < k) {
+            push bestN 0
+            push bestR (0 - 1)
+            i = (i + 1)
+        }
+        def y:int 0
+        while (y < height) {
+            def x:int 0
+            while (x < width) {
+                def idx:int ((y * width) + x)
+                def r0:int (itemAt regionOf idx)
+                if ((r0 >= 0) && ((itemAt size r0) < minPx)) {
+                    if (x < (width - 1)) {
+                        this.tallyNeighbour(r0 (itemAt regionOf (idx + 1)) size minPx bestN bestR)
+                    }
+                    if (x > 0) {
+                        this.tallyNeighbour(r0 (itemAt regionOf (idx - 1)) size minPx bestN bestR)
+                    }
+                    if (y < (height - 1)) {
+                        this.tallyNeighbour(r0 (itemAt regionOf (idx + width)) size minPx bestN bestR)
+                    }
+                    if (y > 0) {
+                        this.tallyNeighbour(r0 (itemAt regionOf (idx - width)) size minPx bestN bestR)
+                    }
+                }
+                x = (x + 1)
+            }
+            y = (y + 1)
+        }
+        i = 0
+        while (i < k) {
+            if ((itemAt bestR i) >= 0) {
+                set target i (itemAt bestR i)
+            }
+            i = (i + 1)
+        }
+        ; Renumber: only regions that still hold pixels get an id.
+        def remap:[int]
+        i = 0
+        while (i < k) {
+            push remap (0 - 1)
+            i = (i + 1)
+        }
+        def next:int 0
+        i = 0
+        while (i < n) {
+            def r2:int (itemAt regionOf i)
+            if (r2 >= 0) {
+                def t:int (itemAt target r2)
+                if ((itemAt remap t) < 0) {
+                    set remap t next
+                    next = (next + 1)
+                }
+                set regionOf i (itemAt remap t)
+            }
+            i = (i + 1)
+        }
+        regionCount = next
+    }
+
+    ; The biggest neighbour wins. Requiring it to clear minPx would strand a
+    ; chain of small regions that only ever touch each other — which is most of
+    ; a photograph — so any different neighbour will do, and repeated passes
+    ; then cascade the small ones into the large.
+    fn tallyNeighbour:void (mine:int other:int size:[int] minPx:int bestN:[int] bestR:[int]) {
+        if (other < 0) {
+            return
+        }
+        if (other == mine) {
+            return
+        }
+        def sz:int (itemAt size other)
+        if ((itemAt bestR mine) < 0) {
+            set bestR mine other
+            set bestN mine sz
+            return
+        }
+        if (sz > (itemAt bestN mine)) {
+            set bestR mine other
+            set bestN mine sz
+        }
+    }
+
+    ; Least squares for  v = a + b·x + c·y  over one region, by Cramer's rule
+    ; on the normal equations. out = [ok, a, b, c].
+    sfn solveLinear:void (n:double sx:double sy:double sxx:double sxy:double syy:double v0:double v1:double v2:double out:[double]) {
+        def det:double (((n * ((sxx * syy) - (sxy * sxy))) - (sx * ((sx * syy) - (sxy * sy)))) + (sy * ((sx * sxy) - (sxx * sy))))
+        if ((EvgBitmapTracer.absD(det)) < 0.000001) {
+            set out 0 0.0
+            return
+        }
+        def da:double (((v0 * ((sxx * syy) - (sxy * sxy))) - (sx * ((v1 * syy) - (sxy * v2)))) + (sy * ((v1 * sxy) - (sxx * v2))))
+        def db:double (((n * ((v1 * syy) - (v2 * sxy))) - (v0 * ((sx * syy) - (sxy * sy)))) + (sy * ((sx * v2) - (v1 * sy))))
+        def dc:double (((n * ((sxx * v2) - (sxy * v1))) - (sx * ((sx * v2) - (v1 * sy)))) + (v0 * ((sx * sxy) - (sxx * sy))))
+        set out 0 1.0
+        set out 1 (da / det)
+        set out 2 (db / det)
+        set out 3 (dc / det)
+    }
+
+    fn hexOf:string (r:double g:double b:double) {
+        return (this.hexFromRgb((EvgBitmapTracer.clamp255(r)) (EvgBitmapTracer.clamp255(g)) (EvgBitmapTracer.clamp255(b))))
+    }
+
+    ; One layer per continuity region, filled with whichever of flat / linear /
+    ; a linear ramp explains it best. Regions are painted largest first, each mask
+    ; is grown by a pixel, so the smaller shape laid on top covers the join —
+    ; the same reason the swatch layers are stacked rather than butted together.
+    fn traceGradientRegions:void (palR:[int] palG:[int] palB:[int]) {
+        this.buildContourRegions()
+        def floorPx:int options.minRegion
+        if (floorPx < 8) {
+            floorPx = 8
+        }
+        ; Absorb until it settles, not once. A pass lets a region below the
+        ; floor join the largest big-enough neighbour it touches — and on a
+        ; photograph a small region's neighbours are mostly small too, so one
+        ; pass moves almost nothing and the floor never bites. Measured before
+        ; this: minRegion from 6 to 4000 moved the region count from 1131 to
+        ; 1052, which is a control that does nothing. Each pass grows the
+        ; survivors, so neighbours that were too small last time are eligible
+        ; this time, and repeating until the count stops falling is what makes
+        ; the number the user set the number they get.
+        def prev:int (regionCount + 1)
+        def guard:int 0
+        while ((regionCount < prev) && (guard < 24)) {
+            prev = regionCount
+            this.absorbTinyRegions(floorPx)
+            guard = (guard + 1)
+        }
+        ; A photograph can still segment into tens of thousands of scraps; each
+        ; one would be its own traced path. Raise the floor until that is sane.
+        guard = 0
+        while ((regionCount > 2000) && (guard < 8)) {
+            floorPx = (floorPx * 2)
+            prev = (regionCount + 1)
+            def inner:int 0
+            while ((regionCount < prev) && (inner < 24)) {
+                prev = regionCount
+                this.absorbTinyRegions(floorPx)
+                inner = (inner + 1)
+            }
+            guard = (guard + 1)
+        }
+        def k:int regionCount
+        if (k == 0) {
+            return
+        }
+        def n:int (width * height)
+        ; --- pass 1: geometry and the linear normal equations ---
+        def rn:[double]
+        def rsx:[double]
+        def rsy:[double]
+        def rsxx:[double]
+        def rsyy:[double]
+        def rsxy:[double]
+        def sv:[double]
+        def sxv:[double]
+        def syv:[double]
+        def svv:[double]
+        def i:int 0
+        while (i < k) {
+            push rn 0.0
+            push rsx 0.0
+            push rsy 0.0
+            push rsxx 0.0
+            push rsyy 0.0
+            push rsxy 0.0
+            def c:int 0
+            while (c < 3) {
+                push sv 0.0
+                push sxv 0.0
+                push syv 0.0
+                push svv 0.0
+                c = (c + 1)
+            }
+            i = (i + 1)
+        }
+        def y:int 0
+        while (y < height) {
+            def x:int 0
+            while (x < width) {
+                def idx:int ((y * width) + x)
+                def r:int (itemAt regionOf idx)
+                if (r >= 0) {
+                    def dx:double (to_double x)
+                    def dy:double (to_double y)
+                    set rn r ((itemAt rn r) + 1.0)
+                    set rsx r ((itemAt rsx r) + dx)
+                    set rsy r ((itemAt rsy r) + dy)
+                    set rsxx r ((itemAt rsxx r) + (dx * dx))
+                    set rsyy r ((itemAt rsyy r) + (dy * dy))
+                    set rsxy r ((itemAt rsxy r) + (dx * dy))
+                    def c2:int 0
+                    while (c2 < 3) {
+                        def v:double (to_double (this.planeAt(c2 idx)))
+                        def j:int ((r * 3) + c2)
+                        set sv j ((itemAt sv j) + v)
+                        set sxv j ((itemAt sxv j) + (dx * v))
+                        set syv j ((itemAt syv j) + (dy * v))
+                        set svv j ((itemAt svv j) + (v * v))
+                        c2 = (c2 + 1)
+                    }
+                }
+                x = (x + 1)
+            }
+            y = (y + 1)
+        }
+        ; --- solve the linear model, per region per channel ---
+        def la:[double]
+        def lb:[double]
+        def lc:[double]
+        def lok:[double]
+        i = 0
+        while (i < k) {
+            def sol:[double]
+            push sol 0.0
+            push sol 0.0
+            push sol 0.0
+            push sol 0.0
+            def okAll:double 1.0
+            def c3:int 0
+            while (c3 < 3) {
+                def j2:int ((i * 3) + c3)
+                EvgBitmapTracer.solveLinear((itemAt rn i) (itemAt rsx i) (itemAt rsy i) (itemAt rsxx i) (itemAt rsxy i) (itemAt rsyy i) (itemAt sv j2) (itemAt sxv j2) (itemAt syv j2) sol)
+                if ((itemAt sol 0) < 0.5) {
+                    okAll = 0.0
+                }
+                push la (itemAt sol 1)
+                push lb (itemAt sol 2)
+                push lc (itemAt sol 3)
+                c3 = (c3 + 1)
+            }
+            push lok okAll
+            i = (i + 1)
+        }
+        ; --- pass 2: radial sums and the extents, both centroid-based ---
+        def rsd:[double]
+        def rsdd:[double]
+        def rsdv:[double]
+        def tmin:[double]
+        def tmax:[double]
+        def dmax:[double]
+        def ux:[double]
+        def uy:[double]
+        i = 0
+        while (i < k) {
+            push rsd 0.0
+            push rsdd 0.0
+            push tmin 1000000.0
+            push tmax (0.0 - 1000000.0)
+            push dmax 0.0
+            def c4:int 0
+            while (c4 < 3) {
+                push rsdv 0.0
+                c4 = (c4 + 1)
+            }
+            ; The gradient's direction is the one luma runs along — the three
+            ; channels each have their own slope, but the SVG has one axis.
+            def bl:double (((0.299 * (itemAt lb ((i * 3) + 0))) + (0.587 * (itemAt lb ((i * 3) + 1)))) + (0.114 * (itemAt lb ((i * 3) + 2))))
+            def cl:double (((0.299 * (itemAt lc ((i * 3) + 0))) + (0.587 * (itemAt lc ((i * 3) + 1)))) + (0.114 * (itemAt lc ((i * 3) + 2))))
+            def mag:double (sqrt ((bl * bl) + (cl * cl)))
+            if (mag < 0.000001) {
+                push ux 1.0
+                push uy 0.0
+            } {
+                push ux (bl / mag)
+                push uy (cl / mag)
+            }
+            i = (i + 1)
+        }
+        y = 0
+        while (y < height) {
+            def x2:int 0
+            while (x2 < width) {
+                def idx2:int ((y * width) + x2)
+                def r2:int (itemAt regionOf idx2)
+                if (r2 >= 0) {
+                    def cnt:double (itemAt rn r2)
+                    def mx:double ((itemAt rsx r2) / cnt)
+                    def my:double ((itemAt rsy r2) / cnt)
+                    def ddx:double ((to_double x2) - mx)
+                    def ddy:double ((to_double y) - my)
+                    def dist:double (sqrt ((ddx * ddx) + (ddy * ddy)))
+                    set rsd r2 ((itemAt rsd r2) + dist)
+                    set rsdd r2 ((itemAt rsdd r2) + (dist * dist))
+                    if (dist > (itemAt dmax r2)) {
+                        set dmax r2 dist
+                    }
+                    def tproj:double ((ddx * (itemAt ux r2)) + (ddy * (itemAt uy r2)))
+                    if (tproj < (itemAt tmin r2)) {
+                        set tmin r2 tproj
+                    }
+                    if (tproj > (itemAt tmax r2)) {
+                        set tmax r2 tproj
+                    }
+                    def c5:int 0
+                    while (c5 < 3) {
+                        def j3:int ((r2 * 3) + c5)
+                        set rsdv j3 ((itemAt rsdv j3) + (dist * (to_double (this.planeAt(c5 idx2)))))
+                        c5 = (c5 + 1)
+                    }
+                }
+                x2 = (x2 + 1)
+            }
+            y = (y + 1)
+        }
+        this.emitRegionLayers(palR palG palB k rn rsx rsy sv svv sxv syv la lb lc lok rsd rsdd rsdv tmin tmax dmax ux uy)
+    }
+
+    fn planeAt:int (c:int i:int) {
+        if (c == 0) {
+            return (itemAt planeR i)
+        }
+        if (c == 1) {
+            return (itemAt planeG i)
+        }
+        return (itemAt planeB i)
+    }
+
+    ; Pick the model for each region and trace it. Sum of squared error comes
+    ; straight out of the sums already gathered, so choosing costs no extra
+    ; pass over the pixels.
+    fn emitRegionLayers:void (palR:[int] palG:[int] palB:[int] k:int rn:[double] rsx:[double] rsy:[double] sv:[double] svv:[double] sxv:[double] syv:[double] la:[double] lb:[double] lc:[double] lok:[double] rsd:[double] rsdd:[double] rsdv:[double] tmin:[double] tmax:[double] dmax:[double] ux:[double] uy:[double]) {
+        ; Largest region first: a smaller shape drawn later covers the join.
+        def order:[int]
+        def i:int 0
+        while (i < k) {
+            push order i
+            i = (i + 1)
+        }
+        def a:int 0
+        while (a < k) {
+            def b:int (a + 1)
+            while (b < k) {
+                if ((itemAt rn (itemAt order b)) > (itemAt rn (itemAt order a))) {
+                    def tmp:int (itemAt order a)
+                    set order a (itemAt order b)
+                    set order b tmp
+                }
+                b = (b + 1)
+            }
+            a = (a + 1)
+        }
+        def gain:double ((to_double options.gradientGain) / 100.0)
+        def allCmds:[PathCommand]
+        def oi:int 0
+        while (oi < k) {
+            def r:int (itemAt order oi)
+            def cnt:double (itemAt rn r)
+            if (cnt > 0.0) {
+                def mx:double ((itemAt rsx r) / cnt)
+                def my:double ((itemAt rsy r) / cnt)
+                ; --- error of each model, summed over the three channels ---
+                def eFlat:double 0.0
+                def eLin:double 0.0
+                def eRad:double 0.0
+                def ra:[double]
+                def rb:[double]
+                def c:int 0
+                while (c < 3) {
+                    def j:int ((r * 3) + c)
+                    def n2:double cnt
+                    def s1:double (itemAt sv j)
+                    eFlat = (eFlat + ((itemAt svv j) - ((s1 * s1) / n2)))
+                    if ((itemAt lok r) > 0.5) {
+                        eLin = (eLin + ((itemAt svv j) - ((((itemAt la j) * s1) + ((itemAt lb j) * (itemAt sxv j))) + ((itemAt lc j) * (itemAt syv j)))))
+                    } {
+                        eLin = (eLin + 1000000000.0)
+                    }
+                    def den:double ((n2 * (itemAt rsdd r)) - ((itemAt rsd r) * (itemAt rsd r)))
+                    if ((EvgBitmapTracer.absD(den)) > 0.000001) {
+                        def bb:double (((n2 * (itemAt rsdv j)) - ((itemAt rsd r) * s1)) / den)
+                        def aa:double ((s1 - (bb * (itemAt rsd r))) / n2)
+                        push ra aa
+                        push rb bb
+                        eRad = (eRad + ((itemAt svv j) - ((aa * s1) + (bb * (itemAt rsdv j)))))
+                    } {
+                        push ra 0.0
+                        push rb 0.0
+                        eRad = (eRad + 1000000000.0)
+                    }
+                    c = (c + 1)
+                }
+                if (eFlat < 0.0) {
+                    eFlat = 0.0
+                }
+                ; A thin or tiny region gives an ill-conditioned fit: the normal
+                ; equations are near-singular along the missing direction and
+                ; Cramer's rule answers with wild coefficients whose residual
+                ; looks excellent and whose stop colors are nonsense. Below a
+                ; useful size, and whenever the arithmetic returns something a
+                ; sum of squares cannot be, stay flat.
+                if (cnt < 64.0) {
+                    eLin = 1000000000.0
+                    eRad = 1000000000.0
+                }
+                if (eLin < 0.0) {
+                    eLin = 1000000000.0
+                }
+                if (eRad < 0.0) {
+                    eRad = 1000000000.0
+                }
+                ; --- choose ---
+                def kind:string "flat"
+                def best:double eFlat
+                if (eLin < best) {
+                    best = eLin
+                    kind = "linear"
+                }
+                ; Radial is fitted but never chosen: an isotropic cone
+                ; invents structure that is not in the picture wherever the
+                ; region is not actually round, and the shapes it infers are
+                ; strange rather than merely wrong. Kept out until it can be
+                ; fitted to the region's real geometry.
+                ; A gradient has to earn its place: a nearly flat region stays
+                ; flat. Both tests are needed — the relative one alone lets a
+                ; perfectly even region through, because zero is not 15% worse
+                ; than zero, and it would emit a gradient with two equal stops.
+                if (kind != "flat") {
+                    if ((eFlat - best) < (eFlat * gain)) {
+                        kind = "flat"
+                    }
+                    if (eFlat < (cnt * 3.0)) {
+                        kind = "flat"
+                    }
+                }
+                def mask:EvgBinaryBitmap (this.maskForRegion(r))
+                def layerOpts:EvgTraceOptions (EvgTraceOptions.defaults())
+                layerOpts.turdsize = options.turdsize
+                layerOpts.alphamax = options.alphamax
+                layerOpts.turnpolicy = options.turnpolicy
+                layerOpts.optcurve = options.optcurve
+                layerOpts.opttolerance = options.opttolerance
+                layerOpts.pathFormat = options.pathFormat
+                layerOpts.pathPrecision = options.pathPrecision
+                def sub:EvgBitmapTracer (EvgBitmapTracer.fromBinary(mask layerOpts))
+                sub.trace()
+                if ((sub.ringCount()) > 0) {
+                    def layer:EvgTraceLayer (itemAt sub.layers 0)
+                    def meanR:double ((itemAt sv ((r * 3) + 0)) / cnt)
+                    def meanG:double ((itemAt sv ((r * 3) + 1)) / cnt)
+                    def meanB:double ((itemAt sv ((r * 3) + 2)) / cnt)
+                    ; Snap the region's own mean onto the palette. It was
+                    ; written out raw, which meant one color per region and a
+                    ; thousand regions: a portrait asked for ten swatches came
+                    ; back with 1128, and nine in ten of those were flat fills —
+                    ; a mosaic, not a gradient render. A gradient's stops stay
+                    ; as measured, because describing a ramp is the whole point
+                    ; of the mode; this is the color the region falls back to,
+                    ; and the color the palette strip reads.
+                    def gi:int (this.nearestIndex((EvgBitmapTracer.clamp255(meanR)) (EvgBitmapTracer.clamp255(meanG)) (EvgBitmapTracer.clamp255(meanB)) palR palG palB))
+                    layer.fillHex = (this.hexFromRgb((itemAt palR gi) (itemAt palG gi) (itemAt palB gi)))
+                    layer.fillKind = kind
+                    if (kind == "linear") {
+                        def t0:double (itemAt tmin r)
+                        def t1:double (itemAt tmax r)
+                        ; A region with no extent along its own gradient axis
+                        ; would emit a zero-length linearGradient, which SVG
+                        ; leaves undefined — and an axis a pixel or two long is
+                        ; a flat color written the long way. One says it better.
+                        if ((t1 - t0) < 2.0) {
+                            kind = "flat"
+                            layer.fillKind = "flat"
+                        }
+                        layer.gx0 = (mx + ((itemAt ux r) * t0))
+                        layer.gy0 = (my + ((itemAt uy r) * t0))
+                        layer.gx1 = (mx + ((itemAt ux r) * t1))
+                        layer.gy1 = (my + ((itemAt uy r) * t1))
+                        layer.stopA = (this.hexOf((this.linAt(la lb lc r 0 layer.gx0 layer.gy0)) (this.linAt(la lb lc r 1 layer.gx0 layer.gy0)) (this.linAt(la lb lc r 2 layer.gx0 layer.gy0))))
+                        layer.stopB = (this.hexOf((this.linAt(la lb lc r 0 layer.gx1 layer.gy1)) (this.linAt(la lb lc r 1 layer.gx1 layer.gy1)) (this.linAt(la lb lc r 2 layer.gx1 layer.gy1))))
+                    }
+                    push layers layer
+                    def cmds:[PathCommand] (sub.getCommands())
+                    def ci:int 0
+                    while (ci < (array_length cmds)) {
+                        push allCmds (itemAt cmds ci)
+                        ci = (ci + 1)
+                    }
+                    pathData = layer.pathData
+                    rings = sub.rings
+                }
+            }
+            oi = (oi + 1)
+        }
+        commands = allCmds
+        if ((array_length layers) > 0) {
+            def first:EvgTraceLayer (itemAt layers 0)
+            pathData = first.pathData
+        }
+    }
+
+    fn linAt:double (la:[double] lb:[double] lc:[double] r:int c:int x:double y:double) {
+        def j:int ((r * 3) + c)
+        return (((itemAt la j) + ((itemAt lb j) * x)) + ((itemAt lc j) * y))
+    }
+
+    ; The region's own pixels, grown by one so the neighbour drawn on top of it
+    ; has something to cover rather than the page.
+    fn maskForRegion:EvgBinaryBitmap (rid:int) {
+        def bm:EvgBinaryBitmap (EvgBinaryBitmap.create(width height))
+        def n:int (width * height)
+        def i:int 0
+        while (i < n) {
+            if ((itemAt regionOf i) == rid) {
+                def y:int (idiv i width)
+                def x:int (i - (y * width))
+                bm.setBit(x y true)
+                if (x > 0) {
+                    bm.setBit((x - 1) y true)
+                }
+                if (x < (width - 1)) {
+                    bm.setBit((x + 1) y true)
+                }
+                if (y > 0) {
+                    bm.setBit(x (y - 1) true)
+                }
+                if (y < (height - 1)) {
+                    bm.setBit(x (y + 1) true)
+                }
+            }
+            i = (i + 1)
+        }
+        return bm
+    }
+
+    ; ----------------------------------------------------------------------
+    ; Overlay shapes (contourMode "overlay")
+    ;
+    ; The partition's weakness is that one weak pixel on a boundary lets the
+    ; flood through, and the shape behind it is gone for good. Stacking removes
+    ; the consequence rather than the cause: the surface below keeps whatever it
+    ; took, and the shape it swallowed is drawn again on top of it.
+    ; ----------------------------------------------------------------------
+
+    ; Is this pixel already covered by something it would not be told apart
+    ; from? Then an overlay has no reason to reach it.
+    fn coveredAlready:boolean (i:int paintR:[int] paintG:[int] paintB:[int] painted:[int] tol:int) {
+        if ((itemAt painted i) == 0) {
+            return false
+        }
+        def d:int (EvgBitmapTracer.absI((itemAt planeR i) - (itemAt paintR i)))
+        def dg:int (EvgBitmapTracer.absI((itemAt planeG i) - (itemAt paintG i)))
+        if (dg > d) {
+            d = dg
+        }
+        def db:int (EvgBitmapTracer.absI((itemAt planeB i) - (itemAt paintB i)))
+        if (db > d) {
+            d = db
+        }
+        return (d <= tol)
+    }
+
+    ; Fit one shape's pixel list with flat or linear, describe the
+    ; winner on the layer, and write what the model *predicts* into the paint
+    ; map. That last part is the whole reason the two features belong together:
+    ; the similarity stop asks "does an overlay show against what is under it",
+    ; and against a flat mean the answer is yes everywhere a ramp leaves the
+    ; mean — so every gradient shatters into bands. Against the model, it is
+    ; only yes where the model is actually wrong.
+    fn fitAndPaintShape:void (comp:[int] layer:EvgTraceLayer paintR:[int] paintG:[int] paintB:[int]) {
+        def n:int (array_length comp)
+        if (n == 0) {
+            return
+        }
+        def cnt:double (to_double n)
+        def sx:double 0.0
+        def sy:double 0.0
+        def sxx:double 0.0
+        def syy:double 0.0
+        def sxy:double 0.0
+        def sv:[double]
+        def sxv:[double]
+        def syv:[double]
+        def svv:[double]
+        def c:int 0
+        while (c < 3) {
+            push sv 0.0
+            push sxv 0.0
+            push syv 0.0
+            push svv 0.0
+            c = (c + 1)
+        }
+        def i:int 0
+        while (i < n) {
+            def idx:int (itemAt comp i)
+            def yy:int (idiv idx width)
+            def dx:double (to_double (idx - (yy * width)))
+            def dy:double (to_double yy)
+            sx = (sx + dx)
+            sy = (sy + dy)
+            sxx = (sxx + (dx * dx))
+            syy = (syy + (dy * dy))
+            sxy = (sxy + (dx * dy))
+            c = 0
+            while (c < 3) {
+                def v:double (to_double (this.planeAt(c idx)))
+                set sv c ((itemAt sv c) + v)
+                set sxv c ((itemAt sxv c) + (dx * v))
+                set syv c ((itemAt syv c) + (dy * v))
+                set svv c ((itemAt svv c) + (v * v))
+                c = (c + 1)
+            }
+            i = (i + 1)
+        }
+        def mx:double (sx / cnt)
+        def my:double (sy / cnt)
+        def la:[double]
+        def lb:[double]
+        def lc:[double]
+        def eFlat:double 0.0
+        def eLin:double 0.0
+        def sol:[double]
+        push sol 0.0
+        push sol 0.0
+        push sol 0.0
+        push sol 0.0
+        c = 0
+        while (c < 3) {
+            def s1:double (itemAt sv c)
+            eFlat = (eFlat + ((itemAt svv c) - ((s1 * s1) / cnt)))
+            EvgBitmapTracer.solveLinear(cnt sx sy sxx sxy syy s1 (itemAt sxv c) (itemAt syv c) sol)
+            if ((itemAt sol 0) > 0.5) {
+                push la (itemAt sol 1)
+                push lb (itemAt sol 2)
+                push lc (itemAt sol 3)
+                eLin = (eLin + ((itemAt svv c) - ((((itemAt sol 1) * s1) + ((itemAt sol 2) * (itemAt sxv c))) + ((itemAt sol 3) * (itemAt syv c)))))
+            } {
+                push la (s1 / cnt)
+                push lb 0.0
+                push lc 0.0
+                eLin = (eLin + 1000000000.0)
+            }
+            c = (c + 1)
+        }
+        if (eFlat < 0.0) {
+            eFlat = 0.0
+        }
+        if ((eLin < 0.0) || (cnt < 64.0)) {
+            eLin = 1000000000.0
+        }
+        def gain:double ((to_double options.gradientGain) / 100.0)
+        def best:double eFlat
+        def useLin:boolean false
+        if (eLin < best) {
+            best = eLin
+            useLin = true
+        }
+        if ((eFlat - best) < (eFlat * gain)) {
+            useLin = false
+        }
+        if (eFlat < (cnt * 3.0)) {
+            useLin = false
+        }
+        def mR:int (EvgBitmapTracer.clamp255((itemAt sv 0) / cnt))
+        def mG:int (EvgBitmapTracer.clamp255((itemAt sv 1) / cnt))
+        def mB:int (EvgBitmapTracer.clamp255((itemAt sv 2) / cnt))
+        layer.fillHex = (this.hexFromRgb(mR mG mB))
+        if (useLin == false) {
+            layer.fillKind = "flat"
+            i = 0
+            while (i < n) {
+                def p0:int (itemAt comp i)
+                set paintR p0 mR
+                set paintG p0 mG
+                set paintB p0 mB
+                i = (i + 1)
+            }
+            return
+        }
+        ; The axis is the direction luma runs along; the extent comes from the
+        ; shape's own pixels projected onto it.
+        def bl:double (((0.299 * (itemAt lb 0)) + (0.587 * (itemAt lb 1))) + (0.114 * (itemAt lb 2)))
+        def cl:double (((0.299 * (itemAt lc 0)) + (0.587 * (itemAt lc 1))) + (0.114 * (itemAt lc 2)))
+        def mag:double (sqrt ((bl * bl) + (cl * cl)))
+        def ux:double 1.0
+        def uy:double 0.0
+        if (mag > 0.000001) {
+            ux = (bl / mag)
+            uy = (cl / mag)
+        }
+        def tmin:double 1000000.0
+        def tmax:double (0.0 - 1000000.0)
+        i = 0
+        while (i < n) {
+            def p1:int (itemAt comp i)
+            def y1:int (idiv p1 width)
+            def t:double ((((to_double (p1 - (y1 * width))) - mx) * ux) + (((to_double y1) - my) * uy))
+            if (t < tmin) {
+                tmin = t
+            }
+            if (t > tmax) {
+                tmax = t
+            }
+            ; Paint the prediction, clamped, so the similarity test below sees
+            ; the ramp this shape actually describes.
+            set paintR p1 (EvgBitmapTracer.clamp255((this.linAt(la lb lc 0 0 (to_double (p1 - (y1 * width))) (to_double y1))))) 
+            set paintG p1 (EvgBitmapTracer.clamp255((this.linAt(la lb lc 0 1 (to_double (p1 - (y1 * width))) (to_double y1)))))
+            set paintB p1 (EvgBitmapTracer.clamp255((this.linAt(la lb lc 0 2 (to_double (p1 - (y1 * width))) (to_double y1)))))
+            i = (i + 1)
+        }
+        if ((tmax - tmin) < 2.0) {
+            layer.fillKind = "flat"
+            return
+        }
+        layer.fillKind = "linear"
+        layer.gx0 = (mx + (ux * tmin))
+        layer.gy0 = (my + (uy * tmin))
+        layer.gx1 = (mx + (ux * tmax))
+        layer.gy1 = (my + (uy * tmax))
+        layer.stopA = (this.hexOf((this.linAt(la lb lc 0 0 layer.gx0 layer.gy0)) (this.linAt(la lb lc 0 1 layer.gx0 layer.gy0)) (this.linAt(la lb lc 0 2 layer.gx0 layer.gy0))))
+        layer.stopB = (this.hexOf((this.linAt(la lb lc 0 0 layer.gx1 layer.gy1)) (this.linAt(la lb lc 0 1 layer.gx1 layer.gy1)) (this.linAt(la lb lc 0 2 layer.gx1 layer.gy1))))
+    }
+
+    ; Re-quantize each detail neighbourhood using only its own pixels, and draw
+    ; the result on top of the picture the global palette produced.
+    ;
+    ; This answers the complaint that an eye traced on its own comes out
+    ; beautifully while the same eye inside a whole face comes out a smudge.
+    ; Nothing is wrong with the tracer in either case: zoomed in, the entire
+    ; color budget is spent on an eye; in a portrait the eye gets two swatches
+    ; out of ten, because the quantizer counts the whole frame and a face is
+    ; mostly cheek. What survives that is the eye's outline; what is lost is the
+    ; lid, the lash line and the opening — everything that makes it read as an
+    ; eye rather than a dark almond. Giving the neighbourhood its own palette is
+    ; what "zoom in on it" means, done in place, and the shapes come out the way
+    ; the plain algorithm makes shapes — whole connected regions of one color —
+    ; rather than grown on a leash and fragmented.
+    fn traceDetailShapes:void (allCmds:[PathCommand] minPx:int) {
+        def k:int options.detailColors
+        if (k < 2) {
+            return
+        }
+        def n:int (width * height)
+        if ((array_length detailMask) != n) {
+            return
+        }
+        def seen:[int]
+        def i:int 0
+        while (i < n) {
+            push seen 0
+            i = (i + 1)
+        }
+        def needPx:int minPx
+        if ((options.detailBoost) >= 2) {
+            needPx = (idiv minPx (options.detailBoost))
+        }
+        if (needPx < 4) {
+            needPx = 4
+        }
+        ; One palette shared by every neighbourhood. Each still derives its own
+        ; bands from its own pixels — that is the whole feature — but derived in
+        ; ignorance of one another, forty neighbourhoods invent forty nearly
+        ; identical browns, and a portrait came back with 456 fills for 561
+        ; shapes. A band that lands close to a color already in use takes that
+        ; one instead of adding another.
+        def shR:[int]
+        def shG:[int]
+        def shB:[int]
+        def start:int 0
+        while (start < n) {
+            if (((itemAt detailMask start) == 1) && ((itemAt seen start) == 0)) {
+                def comp:[int]
+                def stack:[int]
+                set seen start 1
+                push stack start
+                def head:int 0
+                while (head < (array_length stack)) {
+                    def cur:int (itemAt stack head)
+                    head = (head + 1)
+                    push comp cur
+                    def cy:int (idiv cur width)
+                    def cx:int (cur - (cy * width))
+                    if (cx > 0) {
+                        this.detailVisit((cur - 1) seen stack)
+                    }
+                    if (cx < (width - 1)) {
+                        this.detailVisit((cur + 1) seen stack)
+                    }
+                    if (cy > 0) {
+                        this.detailVisit((cur - width) seen stack)
+                    }
+                    if (cy < (height - 1)) {
+                        this.detailVisit((cur + width) seen stack)
+                    }
+                }
+                ; A neighbourhood has to be able to hold the pieces it is being
+                ; split into, or the split is noise.
+                if ((array_length comp) >= (needPx * k)) {
+                    this.paintDetailCluster(comp k needPx allCmds shR shG shB)
+                }
+            }
+            start = (start + 1)
+        }
+    }
+
+    fn detailVisit:void (i:int seen:[int] stack:[int]) {
+        if ((itemAt seen i) == 1) {
+            return
+        }
+        if ((itemAt detailMask i) == 0) {
+            return
+        }
+        set seen i 1
+        push stack i
+    }
+
+    ; Find this color in the shared detail palette, or add it. Greedy and in
+    ; order, which is enough: the question is only whether two neighbourhoods
+    ; are describing the same brown.
+    fn shareColor:int (r:int g:int b:int tol:int shR:[int] shG:[int] shB:[int]) {
+        def n:int (array_length shR)
+        ; Nearest entry as well as near-enough entry: the first answers "is this
+        ; the same brown as one we have", the second answers "which of the ones
+        ; we have is this closest to", and the ceiling needs the second.
+        def best:int (0 - 1)
+        def bestD:int 1000
+        def i:int 0
+        while (i < n) {
+            def dr:int (EvgBitmapTracer.absI(r - (itemAt shR i)))
+            def dg:int (EvgBitmapTracer.absI(g - (itemAt shG i)))
+            def db:int (EvgBitmapTracer.absI(b - (itemAt shB i)))
+            def d:int dr
+            if (dg > d) {
+                d = dg
+            }
+            if (db > d) {
+                d = db
+            }
+            if (d < bestD) {
+                bestD = d
+                best = i
+            }
+            i = (i + 1)
+        }
+        if ((best >= 0) && (bestD <= tol)) {
+            return best
+        }
+        ; Merging near-duplicates bounds nothing on its own — colors that really
+        ; are different keep arriving, one per neighbourhood per band, and a busy
+        ; picture has hundreds of neighbourhoods. Past the ceiling a new band
+        ; takes the closest color already in hand, however far that is, so the
+        ; count the user asked for stays the count they roughly get.
+        def cap:int options.detailColorMax
+        if ((cap > 0) && (n >= cap)) {
+            if (best >= 0) {
+                return best
+            }
+        }
+        push shR r
+        push shG g
+        push shB b
+        return n
+    }
+
+    ; One neighbourhood: build a palette out of its own pixels, split it by that
+    ; palette, and emit each piece as a layer.
+    fn paintDetailCluster:void (comp:[int] k:int needPx:int allCmds:[PathCommand] shR:[int] shG:[int] shB:[int]) {
+        ; The local palette comes from equal shares of the neighbourhood's own
+        ; luma range. Bands rather than a k-means because what has to be
+        ; separated here is exactly light from dark — the white of an eye from
+        ; its pupil — and a band split does that by construction, cheaply, and
+        ; with the same answer every run.
+        def binN:[int]
+        def binR:[int]
+        def binG:[int]
+        def binB:[int]
+        def i:int 0
+        while (i < 256) {
+            push binN 0
+            push binR 0
+            push binG 0
+            push binB 0
+            i = (i + 1)
+        }
+        def c:int 0
+        while (c < (array_length comp)) {
+            def px:int (itemAt comp c)
+            def r:int (itemAt planeR px)
+            def g:int (itemAt planeG px)
+            def b:int (itemAt planeB px)
+            def l:int (EvgBitmapTracer.lumaOf(r g b))
+            set binN l ((itemAt binN l) + 1)
+            set binR l ((itemAt binR l) + r)
+            set binG l ((itemAt binG l) + g)
+            set binB l ((itemAt binB l) + b)
+            c = (c + 1)
+        }
+        def total:int (array_length comp)
+        def lpR:[int]
+        def lpG:[int]
+        def lpB:[int]
+        def acc:int 0
+        def sR:int 0
+        def sG:int 0
+        def sB:int 0
+        def sN:int 0
+        def band:int 1
+        i = 0
+        while (i < 256) {
+            def cnt:int (itemAt binN i)
+            if (cnt > 0) {
+                sR = (sR + (itemAt binR i))
+                sG = (sG + (itemAt binG i))
+                sB = (sB + (itemAt binB i))
+                sN = (sN + cnt)
+                acc = (acc + cnt)
+            }
+            def edge:int (idiv (total * band) k)
+            if ((acc >= edge) && (band < k)) {
+                if (sN > 0) {
+                    push lpR (idiv sR sN)
+                    push lpG (idiv sG sN)
+                    push lpB (idiv sB sN)
+                }
+                sR = 0
+                sG = 0
+                sB = 0
+                sN = 0
+                band = (band + 1)
+            }
+            i = (i + 1)
+        }
+        if (sN > 0) {
+            push lpR (idiv sR sN)
+            push lpG (idiv sG sN)
+            push lpB (idiv sB sN)
+        }
+        def lk:int (array_length lpR)
+        if (lk < 2) {
+            return
+        }
+        def merge:int options.detailColorMerge
+        if (merge > 0) {
+            def bi:int 0
+            while (bi < lk) {
+                def want:int (this.shareColor((itemAt lpR bi) (itemAt lpG bi) (itemAt lpB bi) merge shR shG shB))
+                set lpR bi (itemAt shR want)
+                set lpG bi (itemAt shG want)
+                set lpB bi (itemAt shB want)
+                bi = (bi + 1)
+            }
+        }
+        ; Speckle here is not whole bands that are too small — with equal-share
+        ; bands none ever is, each holds about 1/k of the neighbourhood by
+        ; construction, and gating on that was measured to do nothing until it
+        ; was high enough to delete real structure. It is the scatter *inside* a
+        ; band: a band traces to one big ring plus a spray of little ones. So
+        ; the share is spent where it bites, as the smallest ring a detail shape
+        ; may keep.
+        def speck:int (idiv (total * (options.detailMinShare)) 100)
+        def bx0:int width
+        def by0:int height
+        def bx1:int 0
+        def by1:int 0
+        c = 0
+        while (c < (array_length comp)) {
+            def q:int (itemAt comp c)
+            def qy:int (idiv q width)
+            def qx:int (q - (qy * width))
+            if (qx < bx0) {
+                bx0 = qx
+            }
+            if (qx > bx1) {
+                bx1 = qx
+            }
+            if (qy < by0) {
+                by0 = qy
+            }
+            if (qy > by1) {
+                by1 = qy
+            }
+            c = (c + 1)
+        }
+        bx0 = (bx0 - 1)
+        by0 = (by0 - 1)
+        def bw:int ((bx1 - bx0) + 2)
+        def bh:int ((by1 - by0) + 2)
+        def li:int 0
+        while (li < lk) {
+            def mask:EvgBinaryBitmap (EvgBinaryBitmap.create(bw bh))
+            def held:int 0
+            c = 0
+            while (c < (array_length comp)) {
+                def p2:int (itemAt comp c)
+                def py:int (idiv p2 width)
+                def pxx:int (p2 - (py * width))
+                def near:int (this.nearestIndex((itemAt planeR p2) (itemAt planeG p2) (itemAt planeB p2) lpR lpG lpB))
+                if (near == li) {
+                    mask.setBit((pxx - bx0) (py - by0) true)
+                    held = (held + 1)
+                }
+                c = (c + 1)
+            }
+            if (held >= needPx) {
+                def layerOpts:EvgTraceOptions (EvgTraceOptions.defaults())
+                layerOpts.turdsize = options.turdsize
+                if (speck > (options.turdsize)) {
+                    layerOpts.turdsize = speck
+                }
+                layerOpts.alphamax = options.alphamax
+                layerOpts.turnpolicy = options.turnpolicy
+                layerOpts.optcurve = options.optcurve
+                layerOpts.opttolerance = options.opttolerance
+                layerOpts.fillHex = (this.hexFromRgb((itemAt lpR li) (itemAt lpG li) (itemAt lpB li)))
+                layerOpts.pathFormat = options.pathFormat
+                layerOpts.pathPrecision = options.pathPrecision
+                def sub:EvgBitmapTracer (EvgBitmapTracer.fromBinary(mask layerOpts))
+                sub.trace()
+                if ((sub.ringCount()) > 0) {
+                    def cmds:[PathCommand] (sub.getCommands())
+                    def ox:double (to_double bx0)
+                    def oy:double (to_double by0)
+                    def ci:int 0
+                    while (ci < (array_length cmds)) {
+                        def cm:PathCommand (itemAt cmds ci)
+                        cm.x = (cm.x + ox)
+                        cm.y = (cm.y + oy)
+                        cm.x1 = (cm.x1 + ox)
+                        cm.y1 = (cm.y1 + oy)
+                        cm.x2 = (cm.x2 + ox)
+                        cm.y2 = (cm.y2 + oy)
+                        push allCmds cm
+                        ci = (ci + 1)
+                    }
+                    def layer:EvgTraceLayer (itemAt sub.layers 0)
+                    layer.pathData = (this.pathDataOf(cmds))
+                    push layers layer
+                    rings = sub.rings
+                }
+            }
+            li = (li + 1)
+        }
+    }
+
+    fn traceOverlayShapes:void (palR:[int] palG:[int] palB:[int]) {
+        this.buildEdgeMask()
+        this.buildDetailMask()
+        def n:int (width * height)
+        def edgeTol:int options.contourEdge
+        if (edgeTol < 1) {
+            edgeTol = 1
+        }
+        def spread:int options.contourSpread
+        if (spread < 1) {
+            spread = 1
+        }
+        def simTol:int options.overlaySimilar
+        def minPx:int options.minRegion
+        if (minPx < 4) {
+            minPx = 4
+        }
+        def paintR:[int]
+        def paintG:[int]
+        def paintB:[int]
+        def painted:[int]
+        def stamp:[int]
+        ; The paint map starts as the base picture, because that is what is on
+        ; screen before a single overlay is drawn. It was started blank, which
+        ; made both of the stop rules lie: "would this overlay show against what
+        ; is under it" was asked against nothing, so every overlay showed and
+        ; every overlay was drawn. Answered against the real picture, the rule
+        ; means what it says — an overlay exists only where it differs from the
+        ; picture it sits on — and the shapes that merely repeat it fall out.
+        def i:int 0
+        while (i < n) {
+            def lab:int (itemAt labels i)
+            if ((lab >= 0) && (lab < (array_length palR))) {
+                push paintR (itemAt palR lab)
+                push paintG (itemAt palG lab)
+                push paintB (itemAt palB lab)
+                push painted 1
+            } {
+                push paintR 0
+                push paintG 0
+                push paintB 0
+                push painted 0
+            }
+            push stamp (0 - 1)
+            i = (i + 1)
+        }
+        ; Seeds are held in 256 buckets by the strength of the edge that
+        ; produced them, and the steepest is always served first. Order is not
+        ; a detail here: a smooth surface started first spreads across weak
+        ; boundaries and claims what lies behind them, and the shape it took can
+        ; then only come back as whatever part of itself still differs — half a
+        ; rectangle, with the other half sitting inside the surface that ate it.
+        ; Started from the sharpest edge, the shapes with an identity are laid
+        ; down before the smooth ones get to move.
+        def bucket:[int]
+        def seedPixel:[int]
+        def seedNext:[int]
+        def seedBest:[int]
+        i = 0
+        while (i < 256) {
+            push bucket (0 - 1)
+            i = (i + 1)
+        }
+        i = 0
+        while (i < n) {
+            push seedBest (0 - 1)
+            i = (i + 1)
+        }
+        ; Every steep pixel goes in up front, not just the steepest one. A
+        ; figure can be star-shaped, or in several pieces, and growing outward
+        ; from one point does not necessarily reach the sharp corners of the
+        ; others. Queued together and served steepest-first, the question
+        ; "have all the steep points been dealt with" answers itself: the queue
+        ; is empty when they have.
+        def y0:int 0
+        while (y0 < height) {
+            def x0:int 0
+            while (x0 < width) {
+                def idx0:int ((y0 * width) + x0)
+                ; Only a step that passed the uniqueness and continuity tests
+                ; earns a seed. Seeding every raw step means seeding every
+                ; speck, and the shape budget goes to noise.
+                if ((itemAt labels idx0) >= 0) {
+                    def st:int 0
+                    if (x0 > 0) {
+                        if (this.isBoundary(idx0 (idx0 - 1) edgeTol)) {
+                            st = (this.pixelDelta(idx0 (idx0 - 1)))
+                        }
+                    }
+                    if (x0 < (width - 1)) {
+                        if (this.isBoundary(idx0 (idx0 + 1) edgeTol)) {
+                            def s1:int (this.pixelDelta(idx0 (idx0 + 1)))
+                            if (s1 > st) {
+                                st = s1
+                            }
+                        }
+                    }
+                    if (y0 > 0) {
+                        if (this.isBoundary(idx0 (idx0 - width) edgeTol)) {
+                            def s2:int (this.pixelDelta(idx0 (idx0 - width)))
+                            if (s2 > st) {
+                                st = s2
+                            }
+                        }
+                    }
+                    if (y0 < (height - 1)) {
+                        if (this.isBoundary(idx0 (idx0 + width) edgeTol)) {
+                            def s3:int (this.pixelDelta(idx0 (idx0 + width)))
+                            if (s3 > st) {
+                                st = s3
+                            }
+                        }
+                    }
+                    if (st > 0) {
+                        this.pushSeed(idx0 st bucket seedPixel seedNext seedBest)
+                    }
+                }
+                x0 = (x0 + 1)
+            }
+            y0 = (y0 + 1)
+        }
+        def allCmds:[PathCommand]
+        ; The picture the quantizer just produced goes down first, and the
+        ; overlay shapes stack on top of it.
+        ;
+        ; What used to be here was a single flat rectangle in the average color
+        ; of the frame, on the theory that the shapes above would cover it. They
+        ; do not: on a portrait the base was a dark brown sheet, the shapes on
+        ; top reached the face only as slivers, and the face read as that brown
+        ; — with its own skin shapes sitting in the file underneath, drawn and
+        ; invisible. Measured on the cheek pixel: layer 0 painted it #6C2D21 and
+        ; of the 1467 shapes above it exactly one touched it at all.
+        ;
+        ; Standing on the real picture makes the floor of this mode the ordinary
+        ; result rather than a flat sheet. An overlay that adds nothing now
+        ; costs nothing, and one that is wrong can only be as wrong as the
+        ; shape it draws — never the whole frame.
+        this.paintLabelLayers(palR palG palB allCmds)
+        ; Then the neighbourhoods that need a palette of their own, before the
+        ; grown overlays — those refine the picture, these re-read it.
+        this.traceDetailShapes(allCmds minPx)
+        ; How many shapes are worth making scales with the picture: a fixed
+        ; ceiling starves a large photograph of exactly the shapes it needs,
+        ; and the flag in one test came out as bare background because its
+        ; stripes were never reached.
+        def budget:int (idiv n 4)
+        if (budget < 500) {
+            budget = 500
+        }
+        if (budget > 80000) {
+            budget = 80000
+        }
+        def shapeNo:int 0
+        def sweepFrom:int 0
+        while (shapeNo < budget) {
+            ; Take the next seed; when they run out, sweep for anything still
+            ; unpainted so nothing is left as a hole.
+            def seed:int (0 - 1)
+            def empty:boolean false
+            ; Steepest-first alone starves the large smooth areas: a photograph
+            ; has thousands of sharp spots, they take the whole shape budget as
+            ; small overlays, and a face — which is nearly all low-contrast —
+            ; never reaches the front of the queue at all. Every fourth shape
+            ; is therefore taken from the plain sweep instead, so the big quiet
+            ; surfaces are laid down alongside the loud little ones.
+            if (((shapeNo % 4) == 3) && (sweepFrom < n)) {
+                while ((sweepFrom < n) && (seed < 0)) {
+                    if (((itemAt labels sweepFrom) >= 0) && ((itemAt painted sweepFrom) == 0)) {
+                        seed = sweepFrom
+                    }
+                    sweepFrom = (sweepFrom + 1)
+                }
+            }
+            while ((seed < 0) && (empty == false)) {
+                def cand:int (this.popSeed(bucket seedPixel seedNext))
+                if (cand < 0) {
+                    empty = true
+                } {
+                    if ((itemAt labels cand) >= 0) {
+                        def candSim:int simTol
+                        if (this.isDetail(cand)) {
+                            candSim = (idiv simTol (options.detailBoost))
+                        }
+                        if ((this.coveredAlready(cand paintR paintG paintB painted candSim)) == false) {
+                            seed = cand
+                        }
+                    }
+                }
+            }
+            if (seed < 0) {
+                while ((sweepFrom < n) && (seed < 0)) {
+                    if (((itemAt labels sweepFrom) >= 0) && ((itemAt painted sweepFrom) == 0)) {
+                        seed = sweepFrom
+                    }
+                    sweepFrom = (sweepFrom + 1)
+                }
+            }
+            if (seed < 0) {
+                shapeNo = budget
+            } {
+                ; --- grow one surface to its end ---
+                def comp:[int]
+                def stack:[int]
+                def acc:[int]
+                push acc (itemAt planeR seed)
+                push acc (itemAt planeG seed)
+                push acc (itemAt planeB seed)
+                push acc 1
+                set stamp seed shapeNo
+                push stack seed
+                def h2:int 0
+                while (h2 < (array_length stack)) {
+                    def cur:int (itemAt stack h2)
+                    h2 = (h2 + 1)
+                    push comp cur
+                    def cy:int (idiv cur width)
+                    def cx:int (cur - (cy * width))
+                    if (cx > 0) {
+                        this.overlayStep((cur - 1) cur stamp stack acc bucket seedPixel seedNext seedBest shapeNo edgeTol spread simTol paintR paintG paintB painted)
+                    }
+                    if (cx < (width - 1)) {
+                        this.overlayStep((cur + 1) cur stamp stack acc bucket seedPixel seedNext seedBest shapeNo edgeTol spread simTol paintR paintG paintB painted)
+                    }
+                    if (cy > 0) {
+                        this.overlayStep((cur - width) cur stamp stack acc bucket seedPixel seedNext seedBest shapeNo edgeTol spread simTol paintR paintG paintB painted)
+                    }
+                    if (cy < (height - 1)) {
+                        this.overlayStep((cur + width) cur stamp stack acc bucket seedPixel seedNext seedBest shapeNo edgeTol spread simTol paintR paintG paintB painted)
+                    }
+                }
+                def cnt:int (itemAt acc 3)
+                def mr:int (idiv (itemAt acc 0) cnt)
+                def mg:int (idiv (itemAt acc 1) cnt)
+                def mb:int (idiv (itemAt acc 2) cnt)
+                ; Every shape used to be painted its own mean, which meant the
+                ; color count did nothing at all in this mode: a photograph
+                ; decomposes into thousands of surfaces, each one got a color of
+                ; its own, and the palette strip came back with five thousand
+                ; swatches under a slider that said four. The mean is snapped
+                ; onto the palette the quantizer already built, so "four colors"
+                ; means four colors here too — and a shape that lands on the
+                ; same swatch as the surface under it is then exactly, not
+                ; approximately, the same color, which is what lets it be
+                ; dropped rather than drawn.
+                def pi:int (this.nearestIndex(mr mg mb palR palG palB))
+                def keepTrue:boolean false
+                if (options.detailTrueColor) {
+                    if (this.isDetail(seed)) {
+                        keepTrue = true
+                    }
+                }
+                ; Giving the shape its *region's* swatch instead was tried and
+                ; is provably useless: the base picture already paints that
+                ; swatch there, so every overlay would add nothing by
+                ; construction and the mode collapses to the plain result. A
+                ; shape earns its place by differing from what it sits on, so
+                ; the mean is what decides its color.
+                if (keepTrue == false) {
+                    mr = (itemAt palR pi)
+                    mg = (itemAt palG pi)
+                    mb = (itemAt palB pi)
+                }
+                ; Every shape marks its ground, whatever its size — a scrap too
+                ; small to be worth its own path still has to stop later shapes
+                ; from growing over it again.
+                def sameBelow:int 0
+                def c:int 0
+                while (c < (array_length comp)) {
+                    def px:int (itemAt comp c)
+                    if ((itemAt painted px) == 1) {
+                        if (((itemAt paintR px) == mr) && ((itemAt paintG px) == mg)) {
+                            if ((itemAt paintB px) == mb) {
+                                sameBelow = (sameBelow + 1)
+                            }
+                        }
+                    }
+                    set paintR px mr
+                    set paintG px mg
+                    set paintB px mb
+                    set painted px 1
+                    c = (c + 1)
+                }
+                ; Every shape that marks the map has to be drawn, or it is a
+                ; hole: the shapes below it have already stopped at its border
+                ; and nothing else will cover it. Only specks smaller than a
+                ; traceable ring are skipped — turdsize deals with those.
+                ; A shape every pixel of which already carries this exact
+                ; swatch is a path that would change no pixel on screen. It can
+                ; be dropped without leaving a hole, and the argument is by
+                ; induction: a color reaches the paint map only from a shape
+                ; that was drawn, because the first shape to cover a pixel
+                ; always finds it unpainted and so is never dropped here.
+                def addsNothing:boolean (sameBelow == (array_length comp))
+                ; And a shape that sits in detail is allowed to be small. A
+                ; pupil is a handful of pixels; the area that is right for a
+                ; cheek discards it.
+                def needPx:int minPx
+                if (this.isDetail(seed)) {
+                    needPx = (idiv minPx (options.detailBoost))
+                    if (needPx < 4) {
+                        needPx = 4
+                    }
+                }
+                if (((array_length comp) >= needPx) && (addsNothing == false)) {
+                    ; The mask covers the shape's own bounding box, not the
+                    ; frame. A full-size bitmap per shape is allocated, copied
+                    ; and scanned once each, so a photograph — which is
+                    ; thousands of shapes — was paying the whole image area
+                    ; thousands of times over. The path is moved back
+                    ; afterwards.
+                    def bx0:int width
+                    def by0:int height
+                    def bx1:int 0
+                    def by1:int 0
+                    c = 0
+                    while (c < (array_length comp)) {
+                        def q:int (itemAt comp c)
+                        def qy:int (idiv q width)
+                        def qx:int (q - (qy * width))
+                        if (qx < bx0) {
+                            bx0 = qx
+                        }
+                        if (qx > bx1) {
+                            bx1 = qx
+                        }
+                        if (qy < by0) {
+                            by0 = qy
+                        }
+                        if (qy > by1) {
+                            by1 = qy
+                        }
+                        c = (c + 1)
+                    }
+                    ; One cell of margin so a shape touching the box edge still
+                    ; closes a ring around itself.
+                    bx0 = (bx0 - 1)
+                    by0 = (by0 - 1)
+                    def bw:int ((bx1 - bx0) + 2)
+                    def bh:int ((by1 - by0) + 2)
+                    def bm:EvgBinaryBitmap (EvgBinaryBitmap.create(bw bh))
+                    c = 0
+                    while (c < (array_length comp)) {
+                        def p2:int (itemAt comp c)
+                        def yy:int (idiv p2 width)
+                        bm.setBit(((p2 - (yy * width)) - bx0) (yy - by0) true)
+                        c = (c + 1)
+                    }
+                    def layerOpts:EvgTraceOptions (EvgTraceOptions.defaults())
+                    layerOpts.turdsize = options.turdsize
+                    layerOpts.alphamax = options.alphamax
+                    layerOpts.turnpolicy = options.turnpolicy
+                    layerOpts.optcurve = options.optcurve
+                    layerOpts.opttolerance = options.opttolerance
+                    layerOpts.fillHex = (this.hexFromRgb(mr mg mb))
+                    layerOpts.pathFormat = options.pathFormat
+                    layerOpts.pathPrecision = options.pathPrecision
+                    def sub:EvgBitmapTracer (EvgBitmapTracer.fromBinary(bm layerOpts))
+                        sub.trace()
+                    if ((sub.ringCount()) > 0) {
+                        def cmds:[PathCommand] (sub.getCommands())
+                        def ox:double (to_double bx0)
+                        def oy:double (to_double by0)
+                        def ci:int 0
+                        while (ci < (array_length cmds)) {
+                            def cm:PathCommand (itemAt cmds ci)
+                            cm.x = (cm.x + ox)
+                            cm.y = (cm.y + oy)
+                            cm.x1 = (cm.x1 + ox)
+                            cm.y1 = (cm.y1 + oy)
+                            cm.x2 = (cm.x2 + ox)
+                            cm.y2 = (cm.y2 + oy)
+                            push allCmds cm
+                            ci = (ci + 1)
+                        }
+                        def layer:EvgTraceLayer (itemAt sub.layers 0)
+                        layer.pathData = (this.pathDataOf(cmds))
+                        if options.gradientFill {
+                            this.fitAndPaintShape(comp layer paintR paintG paintB)
+                        }
+                        push layers layer
+                        rings = sub.rings
+                    }
+                }
+                shapeNo = (shapeNo + 1)
+            }
+        }
+        commands = allCmds
+        if ((array_length layers) > 0) {
+            def first:EvgTraceLayer (itemAt layers 0)
+            pathData = first.pathData
+        }
+    }
+
+    ; True where the picture asks for fine work — see buildDetailMask.
+    fn isDetail:boolean (i:int) {
+        if (detailOn == false) {
+            return false
+        }
+        return ((itemAt detailMask i) == 1)
+    }
+
+    ; One step of an overlay's growth. Three things stop it: an edge, drifting
+    ; too far from its own mean, and arriving somewhere it would look the same
+    ; as what is already painted. An edge is not just a stop — it is where the
+    ; next shape begins, on the far side and above.
+    ; Push one seed into the bucket for its edge strength.
+    ;
+    ; A pixel is a point, and the queue's question is "has every steep point
+    ; been dealt with" — so queuing the same pixel twice answers nothing and
+    ; costs everything. Growth bumps into the same boundary from every pixel
+    ; along it, and each bump used to queue both sides again: on a photograph
+    ; that is millions of entries in three arrays that only ever grow, which is
+    ; why a 640-pixel-wide photo spent ten seconds here and half of it in the
+    ; collector. seedBest remembers the strength each pixel is already waiting
+    ; at, and only a steeper claim on the same pixel gets through — so a pixel
+    ; can still be promoted to the front, but never merely repeated.
+    fn pushSeed:void (px:int strength:int bucket:[int] seedPixel:[int] seedNext:[int] seedBest:[int]) {
+        def s:int strength
+        if (s < 0) {
+            s = 0
+        }
+        if (s > 255) {
+            s = 255
+        }
+        if (s <= (itemAt seedBest px)) {
+            return
+        }
+        set seedBest px s
+        def idx:int (array_length seedPixel)
+        push seedPixel px
+        push seedNext (itemAt bucket s)
+        set bucket s idx
+    }
+
+    ; Take the steepest seed still waiting, or -1 when there are none.
+    fn popSeed:int (bucket:[int] seedPixel:[int] seedNext:[int]) {
+        def s:int 255
+        while (s >= 0) {
+            def idx:int (itemAt bucket s)
+            if (idx >= 0) {
+                set bucket s (itemAt seedNext idx)
+                return (itemAt seedPixel idx)
+            }
+            s = (s - 1)
+        }
+        return (0 - 1)
+    }
+
+    fn overlayStep:void (i:int from:int stamp:[int] stack:[int] acc:[int] bucket:[int] seedPixel:[int] seedNext:[int] seedBest:[int] shapeNo:int edgeTol:int spread:int simTol:int paintR:[int] paintG:[int] paintB:[int] painted:[int]) {
+        if ((itemAt stamp i) == shapeNo) {
+            return
+        }
+        if ((itemAt labels i) < 0) {
+            return
+        }
+        ; An overlay shape may not cross a boundary of the base picture.
+        ;
+        ; Without this it is free to disagree with the quantizer that ran just
+        ; before it, and on a photograph it does: a surface grown by continuity
+        ; runs from a cheek out into the background behind it, takes one color
+        ; for the pair, and a face comes back as brown mush. Growth stopping at
+        ; the base boundary makes overlay a *refinement* of that picture rather
+        ; than a competitor to it — it may still split one region into several
+        ; shapes stacked in z, which is the whole point of it, but it can no
+        ; longer contradict where the regions are.
+        ;
+        ; Checking the pair rather than the seed is the same test: every step
+        ; preserves the label, so the whole component carries one. It is also
+        ; what bounds a shape's area, since no shape can outgrow its region.
+        ; — except where the picture asks for precision. The leash and the
+        ; point of the mode are in tension: a shape confined to one region has a
+        ; mean dominated by that region, so it snaps back to that region's own
+        ; swatch and repaints what is already there. Measured: with the leash on
+        ; everywhere, 42 overlay shapes changed the per-pixel error by nothing
+        ; at all, to two decimals. Off everywhere, a face turns to mush. So it
+        ; comes off exactly where buildDetailMask says several plainly different
+        ; colors meet in a few pixels — an eye, a set of teeth — and stays on
+        ; across the cheeks and the curtains, which is where letting go hurt.
+        if (options.overlayFollowBase) {
+            if ((this.isDetail(i)) == false) {
+                if ((itemAt labels i) != (itemAt labels from)) {
+                    return
+                }
+            }
+        }
+        def step:int (this.pixelDelta(from i))
+        if (step > edgeTol) {
+            ; Both sides of an edge are shapes of their own. Seeding only the
+            ; far side leaves the near side to whichever surface happens to
+            ; arrive there, and at a boundary that fades that is the surface
+            ; which already leaked through it — which is how half a shape goes
+            ; missing while the other half is drawn.
+            ;
+            ; A step still stops the growth whatever it is — crossing it would
+            ; only hand the region a color it cannot describe — but it earns a
+            ; new shape only when it is a boundary rather than a speck. That is
+            ; the difference between finding edges and finding noise.
+            if (this.isBoundaryOf(from i edgeTol step)) {
+                this.pushSeed(i step bucket seedPixel seedNext seedBest)
+                this.pushSeed(from step bucket seedPixel seedNext seedBest)
+            }
+            return
+        }
+        ; Inside a detail neighbourhood the bar for "this shows against what is
+        ; under it" is lower, so the small strong shapes an eye is made of are
+        ; drawn instead of being written off as near enough to the skin.
+        def useSim:int simTol
+        if (this.isDetail(i)) {
+            useSim = (idiv simTol (options.detailBoost))
+        }
+        if (this.coveredAlready(i paintR paintG paintB painted useSim)) {
+            return
+        }
+        def cnt:int (itemAt acc 3)
+        def mr:int (idiv (itemAt acc 0) cnt)
+        def mg:int (idiv (itemAt acc 1) cnt)
+        def mb:int (idiv (itemAt acc 2) cnt)
+        def d:int (EvgBitmapTracer.absI((itemAt planeR i) - mr))
+        def dg:int (EvgBitmapTracer.absI((itemAt planeG i) - mg))
+        if (dg > d) {
+            d = dg
+        }
+        def db:int (EvgBitmapTracer.absI((itemAt planeB i) - mb))
+        if (db > d) {
+            d = db
+        }
+        if (d > spread) {
+            return
+        }
+        set stamp i shapeNo
+        push stack i
+        set acc 0 ((itemAt acc 0) + (itemAt planeR i))
+        set acc 1 ((itemAt acc 1) + (itemAt planeG i))
+        set acc 2 ((itemAt acc 2) + (itemAt planeB i))
+        set acc 3 (cnt + 1)
+    }
+
+    ; Absorb connected runs below options.minRegion into the region that
+    ; surrounds them. turdsize would otherwise drop those rings outright, which
+    ; is why the painted area used to shrink every time colorCount went up.
+    ;
+    ; Size alone is the wrong question, though. A four-pixel run is noise when
+    ; it looks like what is around it and it is the *subject* when it does not:
+    ; the spray off a wave, a boat against the sea, a highlight in an eye are
+    ; all a handful of pixels that no larger shape is going to put back.
+    ; options.absorbContrast is the second half of the test — a run whose
+    ; swatch is that far from the swatch it would join survives on its own.
+    fn mergeTinyRegions:void (palR:[int] palG:[int] palB:[int]) {
+        def k:int (array_length palR)
+        def minPx:int options.minRegion
+        if (minPx < 2) {
+            return
+        }
+        def keepLimit:double 0.0
+        def keepOn:boolean false
+        if ((options.absorbContrast) > 0) {
+            keepOn = true
+            keepLimit = (this.dist2Limit(options.absorbContrast))
+        }
+        def n:int (width * height)
+        def seen:[int]
+        def i:int 0
+        while (i < n) {
+            push seen 0
+            i = (i + 1)
+        }
+        def touch:[int]
+        def ki:int 0
+        while (ki < k) {
+            push touch 0
+            ki = (ki + 1)
+        }
+        def start:int 0
+        while (start < n) {
+            def lab:int (itemAt labels start)
+            if ((lab >= 0) && ((itemAt seen start) == 0)) {
+                def comp:[int]
+                def stack:[int]
+                def c:int 0
+                ki = 0
+                while (ki < k) {
+                    set touch ki 0
+                    ki = (ki + 1)
+                }
+                set seen start 1
+                push stack start
+                def head:int 0
+                while (head < (array_length stack)) {
+                    def cur:int (itemAt stack head)
+                    head = (head + 1)
+                    push comp cur
+                    def cy:int (idiv cur width)
+                    def cx:int (cur - (cy * width))
+                    if (cx > 0) {
+                        this.compStep((cur - 1) lab seen stack touch)
+                    }
+                    if (cx < (width - 1)) {
+                        this.compStep((cur + 1) lab seen stack touch)
+                    }
+                    if (cy > 0) {
+                        this.compStep((cur - width) lab seen stack touch)
+                    }
+                    if (cy < (height - 1)) {
+                        this.compStep((cur + width) lab seen stack touch)
+                    }
+                }
+                if ((array_length comp) < minPx) {
+                    def bestLab:int (0 - 1)
+                    def bestN:int 0
+                    ki = 0
+                    while (ki < k) {
+                        if ((itemAt touch ki) > bestN) {
+                            bestN = (itemAt touch ki)
+                            bestLab = ki
+                        }
+                        ki = (ki + 1)
+                    }
+                    if (bestLab >= 0) {
+                        def absorb:boolean true
+                        if (keepOn && (lab >= 0)) {
+                            def gap:double (this.dist2((itemAt palR lab) (itemAt palG lab) (itemAt palB lab) (itemAt palR bestLab) (itemAt palG bestLab) (itemAt palB bestLab)))
+                            if (gap >= keepLimit) {
+                                absorb = false
+                            }
+                        }
+                        if absorb {
+                            c = 0
+                            while (c < (array_length comp)) {
+                                set labels (itemAt comp c) bestLab
+                                c = (c + 1)
+                            }
+                        }
+                    }
+                }
+            }
+            start = (start + 1)
+        }
+    }
+
+    ; Flood one step of the component walk; a differently-labelled neighbour is
+    ; recorded as a merge candidate instead.
+    fn compStep:void (i:int lab:int seen:[int] stack:[int] touch:[int]) {
+        def other:int (itemAt labels i)
+        if (other == lab) {
+            if ((itemAt seen i) == 0) {
+                set seen i 1
+                push stack i
+            }
+            return
+        }
+        if (other >= 0) {
+            set touch other ((itemAt touch other) + 1)
+        }
+    }
+
+    ; Drop single-pixel islands whose whole 4-neighbourhood agrees on another
+    ; swatch. Those specks only add rings that turdsize would delete anyway.
+    fn despeckleLabels:void () {
+        def n:int (width * height)
+        def src:[int]
+        def i:int 0
+        while (i < n) {
+            push src (itemAt labels i)
+            i = (i + 1)
+        }
+        def y:int 0
+        while (y < height) {
+            def x:int 0
+            while (x < width) {
+                def idx:int ((y * width) + x)
+                def me:int (itemAt src idx)
+                if (me >= 0) {
+                    def agree:int (0 - 2)
+                    def same:boolean true
+                    def cnt:int 0
+                    if (x > 0) {
+                        def l:int (itemAt src (idx - 1))
+                        if (agree == (0 - 2)) {
+                            agree = l
+                        }
+                        if (l != agree) {
+                            same = false
+                        }
+                        cnt = (cnt + 1)
+                    }
+                    if (x < (width - 1)) {
+                        def r:int (itemAt src (idx + 1))
+                        if (agree == (0 - 2)) {
+                            agree = r
+                        }
+                        if (r != agree) {
+                            same = false
+                        }
+                        cnt = (cnt + 1)
+                    }
+                    if (y > 0) {
+                        def u:int (itemAt src (idx - width))
+                        if (agree == (0 - 2)) {
+                            agree = u
+                        }
+                        if (u != agree) {
+                            same = false
+                        }
+                        cnt = (cnt + 1)
+                    }
+                    if (y < (height - 1)) {
+                        def dn:int (itemAt src (idx + width))
+                        if (agree == (0 - 2)) {
+                            agree = dn
+                        }
+                        if (dn != agree) {
+                            same = false
+                        }
+                        cnt = (cnt + 1)
+                    }
+                    if (same && (cnt >= 3) && (agree != me)) {
+                        set labels idx agree
+                    }
+                }
+                x = (x + 1)
+            }
+            y = (y + 1)
+        }
+    }
+
+    fn hexFromRgb:string (r:int g:int b:int) {
+        def c:EVGColor (EVGColor.rgb(r g b))
+        return (c.toHexString())
+    }
+
+    ; In "stacked" mode a layer claims its own swatch and everything painted
+    ; after it, so each layer is drawn on top of a filled neighbour rather than
+    ; on the page. The palette is sorted dark → light, so what shows through a
+    ; hairline is the next darker color instead of white.
+    fn maskForLabel:EvgBinaryBitmap (colorIndex:int) {
+        def stacked:boolean ((options.layerMode) != "flat")
+        def bm:EvgBinaryBitmap (EvgBinaryBitmap.create(width height))
+        def n:int (array_length labels)
+        def i:int 0
+        while (i < n) {
+            def lab:int (itemAt labels i)
+            def take:boolean (lab == colorIndex)
+            if (stacked && (lab >= colorIndex) && (lab >= 0)) {
+                take = true
+            }
+            if take {
+                def y:int (idiv i width)
+                def x:int (i - (y * width))
+                bm.setBit(x y true)
+            }
+            i = (i + 1)
+        }
+        return bm
+    }
+
+    ; A 3×3 median that moves whole pixels: of the nine neighbours, take the one
+    ; whose luma is the median and copy its RGB. Picking each channel's median
+    ; separately would invent colors that are nowhere in the image; this cannot,
+    ; and it removes speckle without softening an edge the way a blur does.
+    fn smoothPlanes:void () {
+        def passes:int options.smooth
+        if (passes < 1) {
+            return
+        }
+        if (passes > 4) {
+            passes = 4
+        }
+        def n:int (width * height)
+        def pass:int 0
+        while (pass < passes) {
+            def srcR:[int]
+            def srcG:[int]
+            def srcB:[int]
+            def i:int 0
+            while (i < n) {
+                push srcR (itemAt planeR i)
+                push srcG (itemAt planeG i)
+                push srcB (itemAt planeB i)
+                i = (i + 1)
+            }
+            def y:int 0
+            while (y < height) {
+                def x:int 0
+                while (x < width) {
+                    def lum:[int]
+                    def idxs:[int]
+                    def dy:int (0 - 1)
+                    while (dy <= 1) {
+                        def yy:int (y + dy)
+                        if ((yy >= 0) && (yy < height)) {
+                            def dx:int (0 - 1)
+                            while (dx <= 1) {
+                                def xx:int (x + dx)
+                                if ((xx >= 0) && (xx < width)) {
+                                    def j:int ((yy * width) + xx)
+                                    push idxs j
+                                    push lum (EvgBitmapTracer.lumaOf((itemAt srcR j) (itemAt srcG j) (itemAt srcB j)))
+                                }
+                                dx = (dx + 1)
+                            }
+                        }
+                        dy = (dy + 1)
+                    }
+                    ; Insertion sort — at most nine entries.
+                    def k:int (array_length lum)
+                    def a:int 1
+                    while (a < k) {
+                        def lv:int (itemAt lum a)
+                        def iv:int (itemAt idxs a)
+                        def b:int (a - 1)
+                        while ((b >= 0) && ((itemAt lum b) > lv)) {
+                            set lum (b + 1) (itemAt lum b)
+                            set idxs (b + 1) (itemAt idxs b)
+                            b = (b - 1)
+                        }
+                        set lum (b + 1) lv
+                        set idxs (b + 1) iv
+                        a = (a + 1)
+                    }
+                    def pick:int (itemAt idxs (idiv k 2))
+                    def here:int ((y * width) + x)
+                    set planeR here (itemAt srcR pick)
+                    set planeG here (itemAt srcG pick)
+                    set planeB here (itemAt srcB pick)
+                    x = (x + 1)
+                }
+                y = (y + 1)
+            }
+            pass = (pass + 1)
+        }
+    }
+
+    ; Paint the ordinary quantized picture — one evenodd layer per swatch —
+    ; appending to layers and to allCmds. This is what the tracer draws when no
+    ; extra algorithm is asked for, and it is also what the overlay tracer now
+    ; stands on.
+    fn paintLabelLayers:void (palR:[int] palG:[int] palB:[int] allCmds:[PathCommand]) {
+        def k:int (array_length palR)
+        def li:int 0
+        while (li < k) {
+            def mask:EvgBinaryBitmap (this.maskForLabel(li))
+            def layerOpts:EvgTraceOptions (EvgTraceOptions.defaults())
+            layerOpts.turdsize = options.turdsize
+            layerOpts.alphamax = options.alphamax
+            layerOpts.turnpolicy = options.turnpolicy
+            layerOpts.optcurve = options.optcurve
+            layerOpts.opttolerance = options.opttolerance
+            layerOpts.pathFormat = options.pathFormat
+            layerOpts.pathPrecision = options.pathPrecision
+            layerOpts.fillHex = (this.hexFromRgb((itemAt palR li) (itemAt palG li) (itemAt palB li)))
+            def sub:EvgBitmapTracer (EvgBitmapTracer.fromBinary(mask layerOpts))
+            sub.trace()
+            if ((sub.ringCount()) > 0) {
+                def layer:EvgTraceLayer (itemAt sub.layers 0)
+                push layers layer
+                def cmds:[PathCommand] (sub.getCommands())
+                def ci:int 0
+                while (ci < (array_length cmds)) {
+                    push allCmds (itemAt cmds ci)
+                    ci = (ci + 1)
+                }
+                ; Keep mono-compatible aggregates: last non-empty path + total rings.
+                pathData = layer.pathData
+                rings = sub.rings
+            }
+            li = (li + 1)
+        }
+    }
+
+    fn traceColorLayers:void () {
+        def want:int options.colorCount
+        if (want < 2) {
+            want = 2
+        }
+        this.smoothPlanes()
+        this.detectBackground()
+        this.buildFlatMask()
+        def mode:string options.paletteMode
+        def palR:[int]
+        def palG:[int]
+        def palB:[int]
+        def given:int 0
+        if ((mode == "fixed") || (mode == "seeded")) {
+            given = (this.parsePaletteHex(palR palG palB))
+        }
+        ; "fixed" with a usable list skips quantization entirely and keeps the
+        ; caller's order; anything else (including a list that parsed to
+        ; nothing) goes through the quantizer, with the given colors pinned.
+        def useGivenOnly:boolean false
+        if (mode == "fixed") {
+            if (given > 0) {
+                useGivenOnly = true
+            }
+        }
+        if (useGivenOnly == false) {
+            this.buildPalette(want given palR palG palB)
+        }
+        def k:int (array_length palR)
+        if (k == 0) {
+            return
+        }
+        this.assignLabels(palR palG palB)
+        ; Every decision above was made against the measured colors; from here
+        ; the palette is only what the picture gets painted with, so this is
+        ; where a dialled palette replaces a measured one.
+        this.gradePalette(palR palG palB)
+        ; Overlay shapes carry their own fits, so it takes precedence when both
+        ; are asked for — the two compose rather than compete.
+        if ((options.contourMode) == "overlay") {
+            this.traceOverlayShapes(palR palG palB)
+            return
+        }
+        if options.gradientFill {
+            this.traceGradientRegions(palR palG palB)
+            return
+        }
+        def allCmds:[PathCommand]
+        this.paintLabelLayers(palR palG palB allCmds)
+        commands = allCmds
+        if ((array_length layers) > 0) {
+            def first:EvgTraceLayer (itemAt layers 0)
+            pathData = first.pathData
+        }
+    }
+
+    ; ----------------------------------------------------------------------
+    ; 1. Path decomposition (Potrace-style edge walk)
+    ; ----------------------------------------------------------------------
+
+    fn decompose:void () {
+        def work:EvgBinaryBitmap (bitmap.copy())
+        def start:int 0
+        while (start >= 0) {
+            def idx:int (work.findNext(start))
+            if (idx < 0) {
+                start = (0 - 1)
+            } {
+                def y0:int (idiv idx work.w)
+                def x0:int (idx - (y0 * work.w))
+                def ring:EvgTraceRing (this.findPath(work x0 y0))
+                this.xorPath(work ring)
+                def a:int (EvgBitmapTracer.absI(ring.area))
+                if (a > options.turdsize) {
+                    push rings ring
+                }
+                start = idx
+            }
+        }
+    }
+
+    fn majorityAt:boolean (bm:EvgBinaryBitmap x:int y:int) {
+        def i:int 2
+        while (i < 5) {
+            def ct:int 0
+            def a:int (0 - i + 1)
+            while (a <= (i - 1)) {
+                if (bm.at((x + a) (y + i - 1))) {
+                    ct = (ct + 1)
+                } {
+                    ct = (ct - 1)
+                }
+                if (bm.at((x + i - 1) (y + a - 1))) {
+                    ct = (ct + 1)
+                } {
+                    ct = (ct - 1)
+                }
+                if (bm.at((x + a - 1) (y - i))) {
+                    ct = (ct + 1)
+                } {
+                    ct = (ct - 1)
+                }
+                if (bm.at((x - i) (y + a))) {
+                    ct = (ct + 1)
+                } {
+                    ct = (ct - 1)
+                }
+                a = (a + 1)
+            }
+            if (ct > 0) {
+                return true
+            }
+            if (ct < 0) {
+                return false
+            }
+            i = (i + 1)
+        }
+        return false
+    }
+
+    fn shouldTurnRight:boolean (bm:EvgBinaryBitmap path:EvgTraceRing x:int y:int) {
+        def pol:string options.turnpolicy
+        if (pol == "right") {
+            return true
+        }
+        if (pol == "left") {
+            return false
+        }
+        if (pol == "black") {
+            return (path.sign == "+")
+        }
+        if (pol == "white") {
+            return (path.sign == "-")
+        }
+        if (pol == "majority") {
+            return (this.majorityAt(bm x y))
+        }
+        ; minority (default): turn right when majority is false
+        def maj:boolean (this.majorityAt(bm x y))
+        return (maj == false)
+    }
+
+    fn findPath:EvgTraceRing (bm:EvgBinaryBitmap x0:int y0:int) {
+        def path (new EvgTraceRing())
+        path.minX = x0
+        path.maxX = x0
+        path.minY = y0
+        path.maxY = y0
+        if (bitmap.at(x0 y0)) {
+            path.sign = "+"
+        } {
+            path.sign = "-"
+        }
+        def x:int x0
+        def y:int y0
+        def dirx:int 0
+        def diry:int 1
+        def done:boolean false
+        def guard:int 0
+        def limit:int ((bm.w * bm.h) * 8)
+        if (limit < 64) {
+            limit = 64
+        }
+        while (done == false) {
+            if (guard >= limit) {
+                done = true
+            } {
+                push path.pts (EvgTracePoint.ofInt(x y))
+                if (x > path.maxX) {
+                    path.maxX = x
+                }
+                if (x < path.minX) {
+                    path.minX = x
+                }
+                if (y > path.maxY) {
+                    path.maxY = y
+                }
+                if (y < path.minY) {
+                    path.minY = y
+                }
+                x = (x + dirx)
+                y = (y + diry)
+                path.area = (path.area - (x * diry))
+                if ((x == x0) && (y == y0)) {
+                    done = true
+                } {
+                    ; Left / right samples in the half-cell neighbours of the step.
+                    def lx:int (EvgBitmapTracer.idivTowardZero(((dirx + diry) - 1) 2))
+                    def ly:int (EvgBitmapTracer.idivTowardZero(((diry - dirx) - 1) 2))
+                    def rx:int (EvgBitmapTracer.idivTowardZero(((dirx - diry) - 1) 2))
+                    def ry:int (EvgBitmapTracer.idivTowardZero(((diry + dirx) - 1) 2))
+                    def l:boolean (bm.at((x + lx) (y + ly)))
+                    def r:boolean (bm.at((x + rx) (y + ry)))
+                    if r {
+                        if (l == false) {
+                            if (this.shouldTurnRight(bm path x y)) {
+                                def tmp:int dirx
+                                dirx = (0 - diry)
+                                diry = tmp
+                            } {
+                                def tmp2:int dirx
+                                dirx = diry
+                                diry = (0 - tmp2)
+                            }
+                        } {
+                            def tmp3:int dirx
+                            dirx = (0 - diry)
+                            diry = tmp3
+                        }
+                    } {
+                        if (l == false) {
+                            def tmp4:int dirx
+                            dirx = diry
+                            diry = (0 - tmp4)
+                        }
+                    }
+                }
+                guard = (guard + 1)
+            }
+        }
+        return path
+    }
+
+    fn xorPath:void (bm:EvgBinaryBitmap path:EvgTraceRing) {
+        def n:int (path.len())
+        if (n < 2) {
+            return
+        }
+        def p0:EvgTracePoint (itemAt path.pts 0)
+        def y1:int (to_int p0.y)
+        def i:int 1
+        while (i < n) {
+            def p:EvgTracePoint (itemAt path.pts i)
+            def x:int (to_int p.x)
+            def y:int (to_int p.y)
+            if (y != y1) {
+                def minY:int y1
+                if (y < y1) {
+                    minY = y
+                }
+                def j:int x
+                while (j < path.maxX) {
+                    bm.flip(j minY)
+                    j = (j + 1)
+                }
+                y1 = y
+            }
+            i = (i + 1)
+        }
+    }
+
+    ; ----------------------------------------------------------------------
+    ; 2–4. Optimal polygon + alphamax smooth + optiCurve → path commands
+    ; ----------------------------------------------------------------------
+
+    ; When optcurve is false: emit the optimal polygon as straight edges.
+    ; When true: alphamax smooth followed by optiCurve (Potrace default).
+    fn emitCommands:void () {
+        def out:[PathCommand]
+        def ri:int 0
+        while (ri < (array_length rings)) {
+            def ring:EvgTraceRing (itemAt rings ri)
+            def poly:[EvgTracePoint] (EvgTraceFit.fitRing(ring))
+            def n:int (array_length poly)
+            if (n >= 3) {
+                ; Potrace reverses negative (hole) polygons so evenodd winding matches.
+                if (ring.sign == "-") {
+                    def rev:[EvgTracePoint]
+                    def ri2:int (n - 1)
+                    while (ri2 >= 0) {
+                        push rev (itemAt poly ri2)
+                        ri2 = (ri2 - 1)
+                    }
+                    poly = rev
+                }
+                if options.optcurve {
+                    def curve:EvgTraceCurve (EvgTraceCurve.fromPolygon(poly options.alphamax))
+                    def opt:EvgTraceCurve (curve.optimize(options.opttolerance))
+                    opt.emit(out)
+                } {
+                    this.appendPolygon(out poly)
+                }
+            }
+            ri = (ri + 1)
+        }
+        commands = out
+    }
+
+    fn appendPolygon:void (out:[PathCommand] poly:[EvgTracePoint]) {
+        def n:int (array_length poly)
+        def p0:EvgTracePoint (itemAt poly 0)
+        push out (VectorShapes.moveTo(p0.x p0.y))
+        def i:int 1
+        while (i < n) {
+            def p:EvgTracePoint (itemAt poly i)
+            push out (VectorShapes.lineTo(p.x p.y))
+            i = (i + 1)
+        }
+        push out (VectorShapes.closePath())
+    }
+}