← Files RasterlessARCHIVED FILE

skills/rasterless/scripts/rasterless.py

20.5 KB · Nov 17, 2026 · 19:20 UTC

↓ Download file

#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.10"
# dependencies = ["pillow", "numpy", "potracer", "resvg-py"]
# ///
"""Convert a flat icon (PNG/JPG/WebP) to a clean SVG.

usage: rasterless.py IN [IN ...] [-o OUT] [--colors N] [--design] [--keep-bg] [--preview]

  -o OUT       output file, or a folder (required form for several inputs); default: next to IN
  --colors N   force exactly N icon colors instead of auto-detecting
  --design     exact colors + width/height (for Figma/Illustrator); default is web-ready
  --keep-bg    keep a solid background instead of dropping it
  --preview    also write a preview PNG (original | SVG render | mismatches in red) to a temp folder
"""
import argparse
import io
import tempfile
from pathlib import Path

import numpy as np
from PIL import Image, ImageDraw, ImageFilter

try:
    import potrace
except ImportError:  # no pip in web sandboxes: use the bundled copy
    import sys
    sys.path.insert(0, str(Path(__file__).resolve().parent / "vendor"))
    import potrace
try:
    import resvg_py
except ImportError:  # optional: only needed for the check
    resvg_py = None

WORK_SIZE = 1024   # upscale target, for sub-pixel edges
MERGE_DIST = 20    # same-color distance, lossy inputs
MERGE_CLEAN = 12   # same, clean inputs above SMALL_SIDE
MIN_SHARE = 0.001  # min share of flat pixels per color
MAX_COLORS = 24    # past this, the smallest colors merge
GROW_DIST = 24     # unexplained-pixel distance
GROW_DIST_JPEG = 0  # off: JPEG bleed fakes colors
GROW_DIST_WEBP = 40  # WebP bleeds less
JPEG_BLUR = 0.4   # pre-snap blur, in source pixels
WEBP_BLUR = 0.0   # same for lossy WebP
GRID = 1024      # coordinate steps across the icon
SPECK = 2.0       # min shape area, in source pixels
MODE_CLEAN = 5    # mode filter size, removes slivers
MODE_LOSSY = 5    # same for JPEG/lossy WebP
SMALL_SIDE = 64   # gentler cleanup at or below this size
MODE_SMALL = 3
SPECK_SMALL = 0.5
MAX_UPSCALE = 4   # more adds nodes, not accuracy
OPT_TOL = 0.2     # potrace curve tolerance


def load(path):
    im = Image.open(path)
    lossy = "jpeg" if im.format == "JPEG" else "webp" if im.format == "WEBP" and _webp_lossy(Path(path).read_bytes()) else None
    return im.convert("RGBA"), lossy


def _webp_lossy(data):
    """Lossy WebP has a 'VP8 ' chunk, lossless 'VP8L'."""
    pos = 12
    while pos + 8 <= len(data):
        tag, size = data[pos:pos + 4], int.from_bytes(data[pos + 4:pos + 8], "little")
        if tag in (b"VP8 ", b"VP8L"):
            return tag == b"VP8 "
        pos += 8 + size + (size & 1)
    return False


def detect_background(rgba):
    """Return (transparent, bg_rgb)."""
    a = rgba[..., 3]
    border = np.concatenate([a[0], a[-1], a[:, 0], a[:, -1]])
    if (border < 250).mean() > 0.5 or (a < 250).mean() > 0.05:
        return True, None
    rgb = rgba[..., :3].astype(np.float32)
    # corners first, then the border
    k = max(1, min(rgb.shape[:2]) // 32)
    corners = [rgb[:k, :k], rgb[:k, -k:], rgb[-k:, :k], rgb[-k:, -k:]]
    corners = [c.reshape(-1, 3).mean(0) for c in corners]
    for c in corners:
        agree = [o for o in corners if np.linalg.norm(o - c) < 30]
        if len(agree) >= 3:
            return False, np.mean(agree, axis=0)
    edge = np.concatenate([rgb[0], rgb[-1], rgb[:, 0], rgb[:, -1]])
    return False, np.median(edge, axis=0)


def estimate_palette(rgba, transparent, bg, n_colors=None, lossy=None):
    """Flat colors from interior pixels."""
    small = Image.fromarray(rgba)
    small.thumbnail((512, 512), Image.LANCZOS)
    px = np.asarray(small).astype(np.float32)
    rgb, a = px[..., :3], px[..., 3]
    # flat: the 3x3 neighborhood barely varies
    pad = np.pad(rgb, ((1, 1), (1, 1), (0, 0)), mode="edge")
    win = np.lib.stride_tricks.sliding_window_view(pad, (3, 3), axis=(0, 1))
    flat = (win.max(axis=(-1, -2)) - win.min(axis=(-1, -2))).max(axis=-1) < 24
    opaque = a >= 250 if transparent else np.ones(a.shape, bool)
    pts = rgb[flat & opaque]
    merge = merge_dist(lossy, max(rgba.shape[:2]))
    # shares count icon pixels only; bg stays in pts to absorb halos
    icon_n = len(pts) if bg is None else int((((pts - bg) ** 2).sum(-1) >= merge ** 2).sum())
    if len(pts) < 16:  # nothing flat: use all solid pixels
        pts = rgb[a >= 128] if transparent else rgb.reshape(-1, 3)

    if n_colors:  # forced count: plain k-means
        centers = _peaks(pts, merge=0)[:n_colors]
    else:
        centers, counts = _peaks(pts, merge=merge, min_count=MIN_SHARE * icon_n, with_counts=True,
                                 step=8 if merge < MERGE_DIST else 16)
        if bg is not None:
            # drop backdrop halos
            centers = _drop_bg_halos(centers, counts, bg, MIN_SHARE * len(pts))
    # k-means on nearby pixels only, so shades don't drift
    for _ in range(4):
        idx = _nearest(pts, centers)
        near = ((pts - centers[idx]) ** 2).sum(-1) < (MERGE_DIST / 2) ** 2
        centers = np.array([pts[(idx == k) & near].mean(0) if ((idx == k) & near).any() else c
                            for k, c in enumerate(centers)])
    if not n_colors:  # merge peaks that converged
        merged = []
        for c in centers:
            if all(np.linalg.norm(c - o) >= merge for o in merged):
                merged.append(c)
        centers = np.array(merged)
        grow = {"jpeg": GROW_DIST_JPEG, "webp": GROW_DIST_WEBP}.get(lossy, GROW_DIST)
        if grow:
            centers = _grow(rgb[opaque], centers, bg, grow)
    # unexplained share: high means gradients
    d = np.min([((pts - c) ** 2).sum(-1) for c in centers], axis=0)
    if len(pts) < 500:  # too few interior pixels to judge
        return centers, 0.0
    return centers, (d > 6 ** 2).mean()  # flat < 16%, gradients > 45%


def merge_dist(lossy, side):
    """Tight merging only for large clean inputs."""
    return MERGE_CLEAN if not lossy and side > SMALL_SIDE else MERGE_DIST


def _drop_bg_halos(centers, counts, bg, min_count):
    keep = []
    for c, count in zip(centers, counts):
        if count < min_count and keep:
            seg_d = []
            for o in keep:
                seg = o - bg
                t = np.clip((c - bg) @ seg / max(seg @ seg, 1e-6), 0, 1)
                seg_d.append(np.linalg.norm(c - bg - t * seg))
            if min(seg_d) < 16:
                continue
        keep.append(c)
    return np.array(keep)


def semi_levels(rgba):
    """Flat semi-transparent fills as (rgb, alpha)."""
    small = Image.fromarray(rgba)
    small.thumbnail((512, 512), Image.LANCZOS)
    px = np.asarray(small).astype(np.float32)
    pad = np.pad(px, ((1, 1), (1, 1), (0, 0)), mode="edge")
    win = np.lib.stride_tricks.sliding_window_view(pad, (3, 3), axis=(0, 1))
    rng = win.max(axis=(-1, -2)) - win.min(axis=(-1, -2))
    a = px[..., 3]
    semi = (rng[..., :3].max(-1) < 24) & (rng[..., 3] < 12) & (a >= 20) & (a < 235)
    pts = px[semi]
    need = max(50, 0.005 * (a >= 20).sum())
    levels = []
    while len(pts) >= need and len(levels) < 3:
        bins = (pts[:, 3] // 24).astype(int)
        top = np.bincount(bins).argmax()
        mid = np.median(pts[bins == top, 3])
        grp = pts[np.abs(pts[:, 3] - mid) <= 16]
        if len(grp) < need:
            break
        levels.append((np.median(grp[:, :3], axis=0), float(np.median(grp[:, 3]))))
        pts = pts[np.abs(pts[:, 3] - mid) > 16]
    return levels


def _blend_dist(pts, centers):
    """Distance to the nearest color or two-color blend, and its label."""
    best = np.full(len(pts), np.inf, np.float32)
    lab = np.zeros(len(pts), np.int32)
    for i, c in enumerate(centers):
        d = np.sqrt(((pts - c) ** 2).sum(-1))
        better = d < best
        best[better], lab[better] = d[better], i
    for i in range(len(centers)):
        for j in range(i + 1, len(centers)):
            seg = centers[j] - centers[i]
            t = np.clip(((pts - centers[i]) @ seg) / max(seg @ seg, 1e-6), 0, 1)
            d = np.sqrt(((pts - centers[i] - t[:, None] * seg) ** 2).sum(-1))
            better = d < best
            best[better] = d[better]
            lab[better] = np.where(t[better] < 0.5, i, j)
    return best, lab


def _grow(pts, centers, bg, dist):
    """Add colors that are neither a palette color nor a blend (thin details)."""
    if len(pts) > 60000:
        pts = pts[np.random.default_rng(0).choice(len(pts), 60000, replace=False)]
    centers = list(centers)
    anchors = centers + ([bg] if bg is not None else [])
    need = max(4, 0.003 * len(pts))
    while len(centers) < MAX_COLORS + 1:
        d, _ = _blend_dist(pts, np.array(anchors))
        resid = pts[d > dist]
        if len(resid) < need:
            break
        c = _peaks(resid, merge=0, min_share=0)[0]
        near = resid[((resid - c) ** 2).sum(-1) < dist ** 2]
        if len(near) < need:
            break
        c = near.mean(0)
        centers.append(c)
        anchors.insert(len(centers) - 1, c)
    return np.array(centers)


def _peaks(pts, merge, min_share=MIN_SHARE, min_count=None, with_counts=False, step=16):
    q = (pts // step).astype(np.int32)  # step 8 separates near-whites
    n = 256 // step
    keys = (q[:, 0] * n + q[:, 1]) * n + q[:, 2]
    uniq, inv, counts = np.unique(keys, return_inverse=True, return_counts=True)
    need = min_share * len(pts) if min_count is None else min_count
    chosen, sizes = [], []
    for b in np.argsort(-counts):
        if counts[b] < need and chosen:
            break
        c = pts[inv == b].mean(0)
        if all(np.linalg.norm(c - o) >= merge for o in chosen):
            chosen.append(c)
            sizes.append(counts[b])
    return (np.array(chosen), sizes) if with_counts else np.array(chosen)


def _nearest(pts, centers):
    best = np.full(len(pts), np.inf, np.float32)
    idx = np.zeros(len(pts), np.int32)
    for k, c in enumerate(centers):
        d = ((pts - c) ** 2).sum(-1)
        better = d < best
        best[better], idx[better] = d[better], k
    return idx


def label_pixels(img, palette, transparent, bg, lossy=None, semi=()):
    """Snap upscaled pixels to palette indices; -1 is background."""
    w, h = img.size
    scale = min(WORK_SIZE / max(w, h), MAX_UPSCALE)
    big = img.resize((round(w * scale), round(h * scale)), Image.LANCZOS)
    blur = {"jpeg": JPEG_BLUR, "webp": WEBP_BLUR}.get(lossy, 0)
    if blur:
        big = big.filter(ImageFilter.GaussianBlur(blur * scale))
    big = np.asarray(big).astype(np.float32)
    rgb, a = big[..., :3].reshape(-1, 3), big[..., 3].reshape(-1)
    centers = palette if bg is None else np.vstack([palette, bg])
    idx = _nearest(rgb, centers)
    # edge blends go to the nearer end, never a third color
    far = np.sqrt(((rgb - centers[idx]) ** 2).sum(-1)) > 12
    if far.any() and len(centers) > 1:
        idx[far] = _blend_dist(rgb[far], centers)[1]
    if bg is not None:
        idx[idx == len(palette)] = -1
    if transparent and semi:
        # nearest opacity level
        levels = np.array([0.0] + [s[1] for s in semi] + [255.0])
        lvl = np.abs(a[:, None] - levels[None]).argmin(1)
        idx[lvl == 0] = -1
        for j, (c, _) in enumerate(semi):
            idx[lvl == j + 1] = len(palette) + (0 if bg is None else 1) + j
    elif transparent:
        idx[a < 128] = -1
    lab = idx.reshape(big.shape[:2])
    # mode filter removes noise and slivers
    size = int(MODE_SMALL if max(w, h) <= SMALL_SIDE else MODE_LOSSY if lossy else MODE_CLEAN)
    if size > 1:
        lab = np.asarray(Image.fromarray((lab + 1).astype(np.uint8)).filter(ImageFilter.ModeFilter(size))).astype(np.int32) - 1
    if bg is not None:  # close the gap left by the bg slot
        lab[lab > len(palette)] -= 1
    return lab, scale


def border_connected(mask):
    """Mask pixels connected to the image border."""
    m = Image.fromarray(np.pad(mask, 1, constant_values=True).astype(np.uint8) * 255).copy()
    ImageDraw.floodfill(m, (0, 0), 128)
    return (np.asarray(m) == 128)[1:-1, 1:-1]


def trace(mask, scale, decimals, speck):
    """Trace a mask into SVG path data."""
    # potracer treats False as ink, hence ~mask
    args = dict(turdsize=max(2, int(scale * scale * speck)), turnpolicy=potrace.POTRACE_TURNPOLICY_MINORITY,
                alphamax=1.0, opttolerance=OPT_TOL * max(1, scale / 2))
    try:
        plist = potrace.Bitmap(~mask).trace(opticurve=True, **args)
    except ValueError:  # potracer bug in curve merging
        plist = potrace.Bitmap(~mask).trace(opticurve=False, **args)
    cmds = []  # (command, numbers), relative
    cur = (0.0, 0.0)

    def pt(p):
        return (round(p.x / scale, decimals), round(p.y / scale, decimals))

    for curve in plist:
        start = pt(curve.start_point)
        cmds.append(("m", [start[0] - cur[0], start[1] - cur[1]]))
        cur = start
        for seg in curve.segments:
            if seg.is_corner:
                for q in (pt(seg.c), pt(seg.end_point)):
                    cmds.append(("l", [q[0] - cur[0], q[1] - cur[1]]))
                    cur = q
            else:  # relative to rounded absolutes: no drift
                c1, c2, e = pt(seg.c1), pt(seg.c2), pt(seg.end_point)
                cmds.append(("c", [v for q in (c1, c2, e) for v in (q[0] - cur[0], q[1] - cur[1])]))
                cur = e
        cmds.append(("z", []))
    return serialize(cmds, decimals), sum(len(c.segments) for c in plist)


def serialize(cmds, decimals):
    """Compact path data."""
    out, prev_cmd, prev = [], None, ""
    for c, vals in cmds:
        if c != prev_cmd or c in "mz":
            out.append(c)
            prev = c
        prev_cmd = c
        for v in vals:
            n = num(v, decimals)
            # separator only where numbers would merge
            if prev and prev[-1] not in "mlcz" and not n.startswith("-") and not (n.startswith(".") and "." in prev):
                out.append(" ")
            out.append(n)
            prev = n
    return "".join(out)


def num(v, decimals):
    s = f"{v:.{decimals}f}"
    if "." in s:  # keep "120" intact
        s = s.rstrip("0").rstrip(".")
    if s in ("-0", ""):
        return "0"
    return s.replace("0.", ".", 1) if s.startswith(("0.", "-0.")) else s


def hexc(c):
    return "#{:02x}{:02x}{:02x}".format(*(int(round(min(255, max(0, v)))) for v in c))


def is_dark_neutral(c):
    return max(c) < 90 and max(c) - min(c) < 30


def convert(src, dst, n_colors=None, design=False, keep_bg=False, preview=False):
    img, lossy = load(src)
    rgba = np.asarray(img)
    transparent, bg = detect_background(rgba)
    bg_color = bg
    if keep_bg:
        bg = None
    palette, unexplained = estimate_palette(rgba, transparent, bg, n_colors, lossy)
    if bg is not None:  # drop the background color
        palette = np.array([c for c in palette if np.linalg.norm(c - bg) >= merge_dist(lossy, max(rgba.shape[:2]))]) if len(palette) > 1 else palette
    warn = ""
    if unexplained > 0.3:
        warn = f"gradient or shading detected ({unexplained:.0%} of pixels between flat colors): approximated with flat bands"
    semi = semi_levels(rgba) if transparent else []
    lab, scale = label_pixels(img, palette, transparent, bg, lossy, semi)
    alpha = [255.0] * len(palette) + [s[1] for s in semi]
    if semi:
        palette = np.vstack([palette] + [s[0][None] for s in semi])
    if bg is not None:
        # border-connected bg is backdrop; enclosed bg is a shape
        enclosed = (lab == -1) & ~border_connected(lab == -1)
        if enclosed.any() and len(np.unique(lab[lab >= 0])) > 1:
            palette = np.vstack([palette, bg])
            alpha.append(255.0)
            lab[enclosed] = len(palette) - 1
    areas = [(lab == k).sum() for k in range(len(palette))]
    order = [k for k in np.argsort(areas)[::-1] if areas[k] > 0]
    cap = max(MAX_COLORS, n_colors or 0)  # --colors can exceed the cap
    if len(order) > cap:  # merge extras into the nearest kept color
        kept, dropped = order[:cap], order[cap:]
        for k in dropped:
            near = kept[int(np.argmin([np.linalg.norm(palette[k] - palette[j]) for j in kept]))]
            lab[lab == k] = near
        order = kept
    if len(order) >= cap and not n_colors:  # hitting the cap means not flat
        warn = f"{cap}+ colors: gradients or shading, approximated with flat bands"
    order = [k for k in order if alpha[k] < 250] + [k for k in order if alpha[k] >= 250]  # see-through layers go underneath
    if keep_bg and bg_color is not None:  # kept background goes at the bottom
        b = int(np.argmin([np.linalg.norm(c - bg_color) for c in palette]))
        order = [b] + [k for k in order if k != b]

    w, h = img.size
    decimals = max(0, int(np.ceil(np.log10(GRID / max(w, h)))))
    # mono: one color, maybe at several opacities
    mono = all(np.linalg.norm(palette[k] - palette[order[0]]) < MERGE_DIST for k in order)
    paths, nodes = [], 0
    for i, k in enumerate(order):
        # extend under later solid layers, so no gaps
        mask = (lab == k) | np.isin(lab, [j for j in order[i + 1:] if alpha[j] >= 250])
        d, n = trace(mask, scale, decimals, SPECK_SMALL if max(w, h) <= SMALL_SIDE else SPECK)
        nodes += n
        fill = "currentColor" if mono and not design and is_dark_neutral(palette[k]) else hexc(palette[k])
        op = f' fill-opacity="{num(alpha[k] / 255, 2)}"' if alpha[k] < 250 else ""
        paths.append(f'<path fill="{fill}"{op} fill-rule="evenodd" d="{d}"/>')

    size = f' width="{w}" height="{h}"' if design else ""
    svg = f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {w} {h}"{size}>{"".join(paths)}</svg>\n'
    Path(dst).write_text(svg)

    # gray backdrop for transparent inputs exposes holes
    backdrop = tuple(int(v) for v in bg_color) if bg_color is not None else (128, 128, 128)
    check = verify_note(img, svg, dst, preview, backdrop)
    kind = "mono" if mono else f"{len(order)} colors"
    cols = " ".join(hexc(palette[k]) + (f"@{alpha[k] / 255:.0%}" if alpha[k] < 250 else "") for k in order)
    print(f"{dst}: {kind} [{cols}], {nodes} segments, "
          f"{len(svg.encode()) / 1024:.1f} KB, {check}" + (f"  WARNING: {warn}" if warn else ""))


def verify_note(img, svg, dst, preview, backdrop):
    """Check, save the preview, return the report text."""
    if resvg_py is None:
        return "not verified (install resvg-py for the check and preview)"
    mismatch, pv = verify(img, svg, preview, backdrop)
    note = f"mismatch {mismatch:.2%}"
    if preview:
        pv_path = Path(tempfile.gettempdir()) / "rasterless-previews" / (Path(dst).stem + ".preview.png")
        pv_path.parent.mkdir(exist_ok=True)
        pv.save(pv_path)
        note += f", preview {pv_path}"
    return note


def verify(img, svg, want_preview, backdrop):
    """Render the SVG back and count visible misses."""
    w, h = img.size
    out = Image.open(io.BytesIO(bytes(resvg_py.svg_to_bytes(svg_string=svg, width=w, height=h)))).convert("RGBA")
    white = Image.new("RGBA", (w, h), backdrop + (255,))
    a = np.asarray(Image.alpha_composite(white, img)).astype(np.int16)[..., :3]
    b = np.asarray(Image.alpha_composite(white, out)).astype(np.int16)[..., :3]
    bad = np.abs(a - b).max(-1) > 64
    # ignore the 1px anti-aliasing fringe
    core = bad & (np.roll(bad, 1, 0) | np.roll(bad, -1, 0)) & (np.roll(bad, 1, 1) | np.roll(bad, -1, 1))
    pv = None
    if want_preview:
        diff = np.asarray(Image.alpha_composite(white, img).convert("L").convert("RGB")).copy()
        diff = (diff * 0.35 + 165).astype(np.uint8)
        diff[core] = (230, 30, 30)
        tiles = [Image.alpha_composite(white, img).convert("RGB"), Image.alpha_composite(white, out).convert("RGB"),
                 Image.fromarray(diff)]
        t = 320
        pv = Image.new("RGB", (t * 3 + 16, t), "#888")
        for i, tile in enumerate(tiles):
            pv.paste(tile.resize((t, round(t * h / w)), Image.NEAREST if w < t else Image.LANCZOS), (i * (t + 8), 0))
    return core.mean(), pv


def main():
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("inputs", nargs="+")
    ap.add_argument("-o", "--out")
    ap.add_argument("--colors", type=int)
    ap.add_argument("--design", action="store_true")
    ap.add_argument("--keep-bg", action="store_true")
    ap.add_argument("--preview", action="store_true")
    args = ap.parse_args()
    out_dir = None
    if args.out and (len(args.inputs) > 1 or Path(args.out).is_dir() or args.out.endswith("/")):
        out_dir = Path(args.out)
        out_dir.mkdir(parents=True, exist_ok=True)
    for f in args.inputs:
        dst = out_dir / (Path(f).stem + ".svg") if out_dir else (args.out or Path(f).with_suffix(".svg"))
        Path(dst).parent.mkdir(parents=True, exist_ok=True)
        convert(f, dst, args.colors, args.design, args.keep_bg, args.preview)


if __name__ == "__main__":
    main()

SHA-256: 6c9c5543735a461b0d93199494671573225bca4522381feb49ab857dfb0ec425