ranger-compiler 3.5.1 → 3.5.2

package/dist/lib/evg/EvgTraceTypes.rgr

@@ -0,0 +1,559 @@
+; SPDX-License-Identifier: MIT
+
+; ==============================================================================
+; EvgTraceTypes.rgr — shared types for bitmap tracing
+; ==============================================================================
+
+class EvgTracePoint {
+    def x:double 0.0
+    def y:double 0.0
+
+    Constructor () {
+    }
+
+    sfn of:EvgTracePoint (x:double y:double) {
+        def p (new EvgTracePoint())
+        p.x = x
+        p.y = y
+        return p
+    }
+
+    sfn ofInt:EvgTracePoint (x:int y:int) {
+        def p (new EvgTracePoint())
+        p.x = (to_double x)
+        p.y = (to_double y)
+        return p
+    }
+}
+
+; One closed edge walk before curve fitting.
+class EvgTraceRing {
+    def pts:[EvgTracePoint]
+    def area:int 0
+    ; "+" = black exterior walk, "-" = white (hole) walk — mirrors Potrace.
+    def sign:string "+"
+    def minX:int 0
+    def minY:int 0
+    def maxX:int 0
+    def maxY:int 0
+
+    Constructor () {
+        def p:[EvgTracePoint]
+        pts = p
+    }
+
+    fn len:int () {
+        return (array_length pts)
+    }
+}
+
+; One colored path layer after posterize / multi-color trace.
+class EvgTraceLayer {
+    def fillHex:string "#000000"
+    def pathData:string ""
+    def ringCount:int 0
+    def commandCount:int 0
+    ; How the layer is filled: "flat" uses fillHex alone; "linear" and "radial"
+    ; add a gradient, chosen per region by which one describes it best. Only
+    ; toSVG renders these — an EVGElement carries a single color, so
+    ; toEVGElements falls back to fillHex.
+    def fillKind:string "flat"
+    ; Linear: (x0,y0) → (x1,y1). Only linear gradients are emitted; a radial
+    ; one infers shapes the picture does not have unless the region is round.
+    def gx0:double 0.0
+    def gy0:double 0.0
+    def gx1:double 0.0
+    def gy1:double 0.0
+    ; Color at the start of the gradient and at its end.
+    def stopA:string "#000000"
+    def stopB:string "#000000"
+
+    Constructor () {
+    }
+}
+
+class EvgTraceOptions {
+    ; Speckle filter: drop rings whose |area| is at most this (Potrace default 2).
+    def turdsize:int 2
+    ; Corner threshold. Higher → smoother (fewer corners). Potrace default 1.0.
+    def alphamax:double 1.0
+    ; "minority" | "majority" | "black" | "white" | "left" | "right"
+    def turnpolicy:string "minority"
+    ; When true, fit cubics; when false, emit a polygon.
+    def optcurve:boolean true
+    ; Curve optimization tolerance (Potrace -O; used by optiCurve).
+    def opttolerance:double 0.2
+    ; Luminance threshold 0..255. Negative → Otsu on the source image.
+    def threshold:int 128
+    ; Trace dark pixels as foreground (Potrace blackOnWhite).
+    def blackOnWhite:boolean true
+    ; Mono fill for binary traces (SVG / EVG). Default black.
+    def fillHex:string "#000000"
+    ; 1 = mono (threshold). >1 = quantize ImageBuffer into this many colors
+    ; and trace each palette entry as its own evenodd path layer.
+    def colorCount:int 1
+    ; When posterizing, skip near-white / background swatches (luma >= this).
+    ; 250 keeps paper-white out of typical scans; set 256 to keep white.
+    def skipLuma:int 250
+    ; Posterize: a pixel counts as a region interior when every 4-neighbour is
+    ; within this per-channel distance. Anti-aliased boundary pixels fail the
+    ; test and are kept out of the palette vote.
+    def flatTolerance:int 12
+    ; Let a boundary pixel join a region that actually touches it instead of a
+    ; swatch it only resembles — see assignLabels.
+    def edgeSnap:boolean true
+    ; How much worse a touching region may fit before the snap is refused.
+    ; 1.0 = only when it fits at least as well; larger = snap more eagerly.
+    def snapRatio:double 1.5
+    ; Extra weight on the luma term of the palette distance (1 = plain RGB).
+    ; Only consulted by colorSpace "rgb".
+    def lumaWeight:int 3
+    ; Which space the posterizer measures color difference in:
+    ;   "rgb"   — weighted RGB with an extra luma term (lumaWeight)
+    ;   "oklab" — Euclidean distance in OKLab, where that distance actually
+    ;             tracks perceived difference. Scaled onto the same numeric
+    ;             range as "rgb" (black against white is 390150 in both), so
+    ;             minColorDelta, snapRatio and the rest keep their meaning.
+    ; Costs two cube roots per comparison; buys a palette that is spent on
+    ; colors a viewer can tell apart rather than on whatever RGB happened to
+    ; stretch.
+    def colorSpace:string "rgb"
+    ; How the palette is decided:
+    ;   "auto"   — quantize the image; paletteHex is ignored
+    ;   "fixed"  — use paletteHex exactly, in the given order; colorCount is
+    ;              ignored, and every pixel goes to whichever of them is nearest
+    ;   "seeded" — paletteHex are pinned and the quantizer fills the rest up to
+    ;              colorCount around them
+    ; An unparseable or empty paletteHex falls back to "auto".
+    def paletteMode:string "auto"
+    ; Colors for "fixed" / "seeded" — anything EVGColor.parse accepts:
+    ; "#1a1a1a", "#f80", "rgb(20 30 40)", "crimson".
+    def paletteHex:[string]
+    ; What a swatch is spent on when the quantizer picks one:
+    ;   "area"     — the biggest regions win (the default, and what a photo's
+    ;                large flat background will always take)
+    ;   "balanced" — sqrt of area, so a small vivid object can still claim one
+    ;   "distinct" — every color present counts once, however much of it there
+    ;                is; the palette covers the picture's gamut rather than its
+    ;                mass, above a noise floor
+    ; This governs the seeding AND the Lloyd passes that follow it. Steering
+    ; only the seeds is the same as not steering at all — the passes are the
+    ; step that decides where a swatch settles, and run on population they walk
+    ; every seed back onto the mass it was chosen to get away from.
+    def paletteBias:string "area"
+    ; How much being colorful counts on top of paletteBias, in percent: at 100
+    ; a fully colored swatch is worth twice its area, at 300 four times.
+    ;
+    ; A picture's subject is very often a small saturated thing on a large
+    ; unsaturated ground — the ochre hulls of two boats against grey sea and
+    ; beige paper. Weighted by area those pixels never earn a swatch, and the
+    ; result is not that the color comes out approximate: it comes out *gone*,
+    ; because nothing else in the palette is anywhere near it. Measured on the
+    ; Hokusai wave at eight colors, the nearest palette entry to the hulls sits
+    ; 48 units away and is a grey; the color a viewer would name in the picture
+    ; is not in the output at all.
+    ;
+    ; 0 = area and colorfulness are unrelated, which is the old behaviour.
+    def paletteChroma:int 0
+    ; --- The palette objective ---------------------------------------------
+    ;
+    ; Applied to the finished palette after the picture's regions have been
+    ; decided, so these move what it is painted with and not where its edges
+    ; are. All four are identity at their defaults. Measured in OKLab.
+    ;
+    ; Chroma scale, percent. Below 100 breaks every color toward grey, which is
+    ; what a painter means by a broken tone; above 100 enriches. 100 = the
+    ; colors the picture actually holds.
+    def paletteMute:int 100
+    ; Chroma floor, in thousandths of an OKLab unit. No swatch comes out below
+    ; it, so the palette can be broken toward grey without any of it arriving
+    ; as dead grey — a neutral is tinted in the palette's own average hue
+    ; instead. 20 is a tint you notice without being able to name; 60 is an
+    ; openly colored neutral. 0 = no floor.
+    def paletteTint:int 0
+    ; Warmth, in thousandths of an OKLab unit along the yellow–blue axis.
+    ; Positive is warmer. A shift rather than a hue rotation, because that is
+    ; what a temperature change is: it moves a neutral toward yellow instead of
+    ; spinning it to some unrelated hue.
+    def paletteWarm:int 0
+    ; Lightness spread about the palette's own mean, percent. Below 100 closes
+    ; the palette up toward a mid tone, above 100 opens it out. Does not touch
+    ; the picture's own contrast, only how far apart the swatches sit.
+    def paletteContrast:int 100
+    ; Swatches closer than this (largest per-channel difference) are merged
+    ; after quantization. Asking for more colors than the image actually holds
+    ; otherwise splits one region between two near-identical swatches, and each
+    ; half then falls under turdsize — which is how outlines turn into dashes.
+    def minColorDelta:int 10
+    ; Banding suppression. A quantizer cuts a hard edge wherever a smooth ramp
+    ; crosses the midpoint between two swatches, which is a contour the picture
+    ; does not have; meanwhile a real edge between two *similar* colors can go
+    ; unmarked. Read small differences as continuous and large ones as a break:
+    ;   "off"    — every pixel takes its own nearest swatch (the default)
+    ;   "smooth" — grow regions across neighbours that differ by at most
+    ;              contourEdge, then give the whole region the one swatch
+    ;              nearest its mean. A ramp becomes one region and loses its
+    ;              false contour; a step larger than contourEdge still splits.
+    ;   "overlay" — the same growth, but the shapes are stacked instead of
+    ;              partitioned. A surface is finished to its end; every edge it
+    ;              ran into becomes a seed for a shape started on the far side
+    ;              and drawn ON TOP of it. An overlay may cover ground the
+    ;              surface below already claimed, so a boundary that fades for
+    ;              a few pixels — which lets the flood leak and swallow the
+    ;              shape behind it — is no longer a lost shape: it is repainted
+    ;              from above. It stops at an edge, and it also stops where it
+    ;              has become indistinguishable from what is under it, so an
+    ;              overlay only exists where it shows.
+    ; Off by default because it is a real segmentation, and segmentation has
+    ; failure modes: where two areas are joined by a gradual path it will merge
+    ; them, and that mistake is a large one.
+    def contourMode:string "off"
+    ; "overlay": how close to the color already painted underneath is close
+    ; enough to stop. An overlay that matches its background adds nothing.
+    def overlaySimilar:int 8
+    ; "overlay": keep every shape inside one region of the picture the
+    ; quantizer already produced. An overlay shape is meant to be a refinement
+    ; of that picture — one region resolved into several shapes stacked in z —
+    ; not a second opinion about where the regions are. Allowed to disagree, it
+    ; grows a surface from a face out into the background behind it and paints
+    ; the pair one color, which is how a portrait came back as mush. This also
+    ; bounds what any single shape can claim, since no shape outgrows its
+    ; region.
+    def overlayFollowBase:boolean true
+    ; Where the picture needs fine work, let overlay do fine work.
+    ;
+    ; An eye is a few pixels holding four plainly different colors — white,
+    ; iris, lash, skin — and a pass coarse enough to be sensible on a cheek
+    ; throws all of it away. A window counts as detail when it holds at least
+    ; detailSwatches distinct swatches *and* spans at least detailSpread levels
+    ; of luma: both halves are needed, or a gradient (few swatches, wide spread)
+    ; and noise inside one flat color (one swatch) both read as detail.
+    ; Inside such a window overlay divides its smallest-area and its similarity
+    ; limits by detailBoost, so small strong shapes are drawn there and nowhere
+    ; else. detailSwatches below 2, or detailBoost below 2, turns it off.
+    ; Swept against landmarks on a portrait: at 4 swatches / 120 luma / radius
+    ; 2 the mask covers 2.8% of the frame and fires on both eyes while missing
+    ; the cheek, the suit, the curtain and the flag. Three swatches lets the
+    ; flag in; five loses one of the eyes.
+    def detailSwatches:int 4
+    def detailSpread:int 120
+    def detailRadius:int 2
+    def detailBoost:int 4
+    ; In a detail neighbourhood, let an overlay keep its own measured color
+    ; instead of snapping it to the palette. This is the only way the mode can
+    ; add resolution rather than redraw what is already there: everywhere else
+    ; an overlay is snapped to the same swatches the base picture used, and a
+    ; shape sitting inside one region has a mean dominated by that region — so
+    ; it snaps back to that region's own swatch and repaints it. Unsnapped, the
+    ; white of an eye can be white and the pupil black even when neither is in
+    ; the palette. It costs the guarantee that the color count is a hard ceiling,
+    ; which is why it is a separate switch; the detail mask covers a few percent
+    ; of a frame, so the cost is bounded.
+    def detailTrueColor:boolean false
+    ; How many colors a detail neighbourhood gets to quantize itself into.
+    ; Zoom into an eye on its own and the tracer renders it beautifully, because
+    ; the whole color budget is spent on an eye. Give it the whole face and the
+    ; eye gets two swatches out of ten and comes back as a smudge that keeps the
+    ; outline and loses the lid, the lash line and the opening. A detail
+    ; neighbourhood therefore builds its own small palette out of its own pixels
+    ; — which is what "zoom in on it" means, done in place — and its shapes are
+    ; drawn on top of the picture the global palette produced. 0 turns it off.
+    def detailColors:int 4
+    ; Smallest ring a detail shape may keep, as a share of its neighbourhood, in
+    ; percent. The local palette buys structure inside a feature and speckle
+    ; along with it, and this is what separates them: each band traces to one
+    ; large ring plus a spray of small ones, and the spray is the speckle.
+    ; Swept on a portrait's eyes — 0%: every bit of structure and every bit of
+    ; grain, 687 KB. 8%: the lid, the lash line and the opening all still read,
+    ; the grain is gone, 599 KB. 15% and up: it starts eating the structure too
+    ; and converges on what the plain algorithm already gives.
+    def detailMinShare:int 8
+    ; Detail neighbourhoods share one palette, and this is how close two of
+    ; their colors may be before they become one entry in it. Each
+    ; neighbourhood still derives its own bands from its own pixels — that is
+    ; the point of the feature — but derived in ignorance of each other, forty
+    ; neighbourhoods invent forty nearly identical browns. Measured on a
+    ; portrait: 456 distinct fills unmerged, 234 at a tolerance of 8, 91 at 16,
+    ; 49 at 24. 0 disables the merge and lets every neighbourhood keep its own.
+    def detailColorMerge:int 16
+    ; The most colors the detail neighbourhoods may add between them. Merging
+    ; near-duplicates bounds nothing on its own: colors that are genuinely
+    ; different keep accumulating, one per neighbourhood per band, and a busy
+    ; picture has hundreds of neighbourhoods — a portrait asked for six swatches
+    ; came back with 103. Once this many have been taken, a new band uses the
+    ; nearest one already in hand instead of adding another, so the color count
+    ; is at most colorCount + this, whatever the picture does. 0 removes the
+    ; ceiling.
+    def detailColorMax:int 12
+    ; A step only counts as a boundary when it is *unique* in its
+    ; neighbourhood — the strongest one across its own direction, so a noisy
+    ; pixel does not out-vote the ridge beside it — and *continuous*, part of a
+    ; run at least this many pixels long. Without both, every speck in a
+    ; photograph is a boundary, and the tracer spends its shapes on them.
+    ; 0 turns the filter off and takes every step at face value.
+    def edgeMinRun:int 3
+    ; Largest per-channel step still counted as continuous. Small on purpose:
+    ; at 10 a soft-edged object merges into the field behind it.
+    def contourEdge:int 3
+    ; How far a region may drift from its own running mean before it stops
+    ; growing. This is the leash on the failure above: without it one ramp can
+    ; walk across the whole picture.
+    def contourSpread:int 48
+    ; Fill each region with the gradient that describes it rather than one flat
+    ; color: fit a flat, a linear and a radial model per region and keep
+    ; whichever leaves the least error. Needs the continuity segmentation, so
+    ; turning this on runs it whether or not contourMode asked for it.
+    ; Rendered by toSVG only.
+    def gradientFill:boolean false
+    ; A gradient only replaces the flat fill when it explains this much more of
+    ; the region's variation, in percent. Keeps a nearly flat region flat.
+    def gradientGain:int 15
+    ; How the color layers are stacked:
+    ;   "stacked" — layer i covers every pixel at or above it in the palette
+    ;               order, so the layers are painted over one another and a
+    ;               curve-fitting gap exposes the neighbouring color, not the
+    ;               page. Two independent fits of the same pixel boundary never
+    ;               agree exactly, which is where the white hairlines came from.
+    ;   "flat"    — one disjoint region per swatch; smaller, and correct only if
+    ;               nothing is ever going to look at the seams.
+    def layerMode:string "stacked"
+    ; How the `d` attribute is written. The geometry is the same either way:
+    ;   "plain"   — absolute M/L/C at four decimals, what VectorShapes writes
+    ;               for the rest of the vector stack
+    ;   "compact" — per segment the shorter of the absolute and relative form,
+    ;               H/V for axis-aligned lines, S for mirrored cubic handles,
+    ;               numbers trimmed to pathPrecision, and separators only where
+    ;               the SVG grammar needs one. Same picture, roughly half the
+    ;               bytes. See EvgTracePath.
+    def pathFormat:string "compact"
+    ; Decimal places kept in "compact". Two is a hundredth of a pixel, well
+    ; below what a trace resolves; the coordinates are rounded before the
+    ; degenerate-segment cleanup, so the rounding does not leave debris behind.
+    def pathPrecision:int 2
+    ; Posterize: passes of a 3×3 median over the color planes before anything
+    ; else looks at them. A photograph's per-pixel noise otherwise survives
+    ; quantization as speckle, and every extra color splits it further, so the
+    ; trace gains fragments instead of shapes. 0 = off, which is what line art
+    ; and flat-color art want: a median would eat their thin strokes.
+    def smooth:int 0
+    ; Posterize: a connected run of pixels smaller than this joins the region
+    ; around it instead of being traced. Without it turdsize simply deletes
+    ; those rings and leaves holes, so coverage falls as colorCount rises.
+    def minRegion:int 6
+    ; The other half of the minRegion test, in per-channel color units: a run
+    ; below minRegion is still kept when the swatch it would be absorbed into
+    ; is at least this far away. Size on its own cannot tell noise from
+    ; subject — the spray off a wave, a boat on the sea and the white of an eye
+    ; are each a few pixels that no larger shape puts back, while a few pixels
+    ; of a neighbouring blue inside blue are exactly what minRegion is for.
+    ; Measured on the Hokusai wave at colorCount 16: absorbing everything costs
+    ; 15 RMSE points and both boats; keeping what stands out recovers nearly
+    ; all of it at a third of the extra bytes. 0 restores the unconditional
+    ; absorb.
+    def absorbContrast:int 40
+    ; Background handling for posterize:
+    ;   "auto" — flood the page color in from the border and drop only that,
+    ;            so a white belly or highlight inside the subject survives.
+    ;            Falls back to "luma" when the border is not one flat color.
+    ;   "color" — the same flood, but from a color you name in bgColor rather
+    ;             than the one the border happens to hold, and with no
+    ;             uniformity test to pass. What to reach for when "auto"
+    ;             declines because the border is not flat enough.
+    ;   "luma" — the old rule: drop every pixel with luma >= skipLuma.
+    ;   "none" — paint everything opaque.
+    def bgMode:string "auto"
+    ; The background color for bgMode "color". Anything EVGColor.parse accepts.
+    def bgColor:string "#ffffff"
+    ; Per-channel tolerance for the "auto" background flood.
+    def bgTolerance:int 24
+
+    Constructor () {
+        def ph:[string]
+        paletteHex = ph
+    }
+
+    sfn defaults:EvgTraceOptions () {
+        return (new EvgTraceOptions())
+    }
+
+    ; A starting point for a kind of picture. Forty-one knobs is the right
+    ; number for a tracer that has to handle a scanned blueprint and a
+    ; photograph with the same code, and the wrong number to hand somebody who
+    ; has one image and a deadline. Each preset below is a setting that was
+    ; measured rather than guessed; from there the individual knobs still work.
+    ;
+    ;   "lineart"  — one-color ink on paper. No median (it eats thin strokes),
+    ;                no speckle absorb, Otsu picks the threshold.
+    ;   "poster"   — flat-color art: few colors, hard edges, keep every one.
+    ;   "photo"    — a photograph: median away the sensor grain, absorb the
+    ;                speckle it leaves, and spend the palette on area.
+    ;   "broken"   — the palette chosen for its colors rather than for its
+    ;                fidelity: swatches spent on covering the gamut, then
+    ;                enriched and tinted. What to reach for when the measured
+    ;                palette comes back grey.
+    ;   "print"    — a detailed picture with hard edges and fine marks, the
+    ;                Hokusai wave being the case it was tuned on: absorb small
+    ;                runs, but not the ones that stand out from what surrounds
+    ;                them, which is where the spray and the boats live.
+    ;
+    ; An unknown name returns the plain defaults.
+    sfn preset:EvgTraceOptions (name:string) {
+        def o (new EvgTraceOptions())
+        if (name == "lineart") {
+            o.colorCount = 1
+            o.threshold = (0 - 1)
+            o.smooth = 0
+            o.minRegion = 0
+            return o
+        }
+        if (name == "poster") {
+            o.colorCount = 8
+            o.smooth = 0
+            o.minRegion = 4
+            o.absorbContrast = 24
+            o.minColorDelta = 12
+            return o
+        }
+        if (name == "photo") {
+            o.colorCount = 16
+            o.smooth = 1
+            o.minRegion = 8
+            o.absorbContrast = 56
+            o.paletteBias = "area"
+            return o
+        }
+        ; The palette dialled rather than measured. Measured means come out
+        ; grey because the mean of a large region is grey; a picture painted in
+        ; eight of them has no color a painter would have chosen. This spends
+        ; the swatches on covering the picture's gamut instead of its mass, and
+        ; then enriches and tints what comes back. On the Hokusai wave it is
+        ; what puts the ochre of the boat hulls into the output at all: the
+        ; nearest palette entry to the hulls goes from 48 units away and grey
+        ; to 27 away and ochre, and the error measured over the hulls alone
+        ; falls from 30.4 to 22.4 — below what vtracer manages there.
+        if (name == "broken") {
+            o.colorCount = 8
+            o.smooth = 0
+            o.minRegion = 4
+            o.absorbContrast = 24
+            o.paletteBias = "distinct"
+            o.paletteChroma = 300
+            o.paletteMute = 130
+            o.paletteTint = 30
+            return o
+        }
+        if (name == "print") {
+            o.colorCount = 16
+            o.smooth = 0
+            o.minRegion = 6
+            o.absorbContrast = 32
+            return o
+        }
+        return o
+    }
+}
+
+; Packed 0/1 bitmap. Index = y * w + x.
+class EvgBinaryBitmap {
+    def w:int 0
+    def h:int 0
+    def data:[int]
+
+    Constructor () {
+        def d:[int]
+        data = d
+    }
+
+    sfn create:EvgBinaryBitmap (w:int h:int) {
+        def bm (new EvgBinaryBitmap())
+        bm.w = w
+        bm.h = h
+        def d:[int]
+        def n:int (w * h)
+        def i:int 0
+        while (i < n) {
+            push d 0
+            i = (i + 1)
+        }
+        bm.data = d
+        return bm
+    }
+
+    fn size:int () {
+        return (array_length data)
+    }
+
+    fn at:boolean (x:int y:int) {
+        if (x < 0) {
+            return false
+        }
+        if (y < 0) {
+            return false
+        }
+        if (x >= w) {
+            return false
+        }
+        if (y >= h) {
+            return false
+        }
+        def v:int (itemAt data ((y * w) + x))
+        return (v == 1)
+    }
+
+    fn setBit:void (x:int y:int on:boolean) {
+        if (x < 0) {
+            return
+        }
+        if (y < 0) {
+            return
+        }
+        if (x >= w) {
+            return
+        }
+        if (y >= h) {
+            return
+        }
+        if on {
+            set data ((y * w) + x) 1
+        } {
+            set data ((y * w) + x) 0
+        }
+    }
+
+    fn flip:void (x:int y:int) {
+        if (this.at(x y)) {
+            this.setBit(x y false)
+        } {
+            this.setBit(x y true)
+        }
+    }
+
+    fn copy:EvgBinaryBitmap () {
+        def bm (new EvgBinaryBitmap())
+        bm.w = w
+        bm.h = h
+        def d:[int]
+        def n:int (array_length data)
+        def i:int 0
+        while (i < n) {
+            push d (itemAt data i)
+            i = (i + 1)
+        }
+        bm.data = d
+        return bm
+    }
+
+    ; Find the next set pixel at or after linear index `start`.
+    fn findNext:int (start:int) {
+        def n:int (array_length data)
+        def i:int start
+        while (i < n) {
+            if ((itemAt data i) == 1) {
+                return i
+            }
+            i = (i + 1)
+        }
+        return (0 - 1)
+    }
+}
+