svgsmith 0.1.0__py3-none-any.whl

svgsmith/__init__.py

@@ -0,0 +1,3 @@
+"""svgsmith — convert raster images into clean, editable SVG."""
+
+__version__ = "0.1.0"

svgsmith/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m svgsmith`` to invoke the CLI."""
+
+from svgsmith.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

svgsmith/classify.py

@@ -0,0 +1,90 @@
+"""Input classification for ``--mode auto``.
+
+Deterministic, heuristic-only (no ML) selection of an engine *mode* and a
+canonical *preset* for an input image. Downstream the pipeline maps:
+
+- ``binary`` → Potrace (``logo`` / ``icon`` preset)
+- ``color``  → VTracer (``illustration`` preset)
+- ``pixel``  → VTracer (``pixel`` preset)
+
+Photographic inputs classify as ``color`` and carry a raw warning string; this
+module emits the string only — #8 assembles the canonical report, so the report
+schema is intentionally not imported here.
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+from PIL import Image, ImageFilter, ImageOps
+
+from svgsmith.engines.base import ImageInput, load_image
+
+# Heuristic thresholds. The fixture feature values sit well clear of every
+# boundary, so classification stays stable across Pillow versions.
+PIXEL_MAX_DIM = 64  # pixel art lives on a tiny canvas
+PIXEL_MAX_PALETTE = 32  # ...with a small palette
+PHOTO_MIN_PALETTE = 64  # rich palette / gradients read as photographic
+BINARY_MAX_PALETTE = 3  # monochrome-ish ink-on-paper
+BINARY_MIN_EDGE_DENSITY = 0.02  # ...with sharp edges
+EDGE_MAGNITUDE_CUTOFF = 40  # grayscale edge strength counted as a "strong" edge
+
+PHOTO_WARNING = "photographic gradients; vectorization may bloat"
+
+
+class Classification(NamedTuple):
+    """Result of :func:`classify`.
+
+    Unpacks as ``(mode, preset, warnings)``; callers that only need the engine
+    selection can read ``.mode`` / ``.preset``.
+    """
+
+    mode: str  # "binary" | "color" | "pixel"
+    preset: str  # canonical preset name from engines.PRESETS
+    warnings: tuple[str, ...]
+
+
+def _palette_size(img: Image.Image) -> int:
+    """Distinct colors after a coarse posterize that suppresses codec noise."""
+    posterized = ImageOps.posterize(img, 4)
+    colors = posterized.getcolors(maxcolors=1 << 16)
+    return len(colors) if colors is not None else (1 << 16)
+
+
+def _edge_density(img: Image.Image) -> float:
+    """Fraction of pixels whose grayscale edge magnitude exceeds the cutoff."""
+    edges = img.convert("L").filter(ImageFilter.FIND_EDGES)
+    histogram = edges.histogram()
+    strong = sum(histogram[EDGE_MAGNITUDE_CUTOFF:])
+    total = img.width * img.height
+    return strong / total if total else 0.0
+
+
+def classify(image: ImageInput) -> Classification:
+    """Classify ``image`` into an engine mode + canonical preset.
+
+    Returns a :class:`Classification`. Photographic inputs classify as ``color``
+    with :data:`PHOTO_WARNING` attached.
+    """
+    img = load_image(image, "RGB")
+    max_dim = max(img.size)
+    palette = _palette_size(img)
+
+    # Monochrome-ish + sharp edges → line art. Checked before the pixel-art
+    # branch so a tiny 2-3 color icon reaches `binary`/`icon` instead of being
+    # captured as pixel art (pixel art carries more than a couple of hues).
+    if palette <= BINARY_MAX_PALETTE and _edge_density(img) >= BINARY_MIN_EDGE_DENSITY:
+        preset = "icon" if max_dim <= PIXEL_MAX_DIM else "logo"
+        return Classification("binary", preset, ())
+
+    # Tiny canvas + small (but non-monochrome) palette → pixel art.
+    if max_dim <= PIXEL_MAX_DIM and palette <= PIXEL_MAX_PALETTE:
+        return Classification("pixel", "pixel", ())
+
+    # Rich palette / gradients → photographic. Still vectorizable as color, but
+    # flag the likely bloat for the report to surface.
+    if palette >= PHOTO_MIN_PALETTE:
+        return Classification("color", "illustration", (PHOTO_WARNING,))
+
+    # Everything else: flat multi-color illustration.
+    return Classification("color", "illustration", ())

svgsmith/cli.py

@@ -0,0 +1,266 @@
+"""Command-line interface for svgsmith.
+
+This module wires up the ``svgsmith`` console entrypoint and its ``convert``
+subcommand. ``convert`` runs the full pipeline (classify → preprocess → trace →
+postprocess → verify) and, with ``--report json``, prints the canonical JSON
+report to stdout — and nothing else: all logs and errors go to stderr.
+
+Exit codes:
+    0  success (similarity met the --quality threshold)
+    2  an SVG was produced but its similarity is below --quality
+    1  hard error (could not produce output)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from svgsmith import __version__
+from svgsmith.pipeline import MODES, ConvertOptions, convert
+
+# Process exit codes (documented in the module docstring and --help epilog).
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_BELOW_THRESHOLD = 2
+
+
+def _log(message: str) -> None:
+    """Write a human-facing line to stderr (stdout is reserved for the report)."""
+    print(message, file=sys.stderr)
+
+
+def _convert(args: argparse.Namespace) -> int:
+    """Handle ``svgsmith convert`` once arguments have been parsed."""
+    if not args.input:
+        _log("error: an input image path is required")
+        return EXIT_ERROR
+
+    # Validate bounds before any conversion work so invalid input fails fast
+    # with a clear message instead of an opaque downstream error.
+    if not 0.0 <= args.quality <= 1.0:
+        _log(f"error: --quality must be between 0 and 1 (got {args.quality})")
+        return EXIT_ERROR
+    if args.max_iters < 1:
+        _log(f"error: --max-iters must be at least 1 (got {args.max_iters})")
+        return EXIT_ERROR
+
+    opts = ConvertOptions(
+        mode=args.mode,
+        quality=args.quality,
+        max_iters=args.max_iters,
+        editable=args.editable,
+        smooth=args.smooth,
+        uniform_outline=args.uniform_outline,
+        solid_background=args.solid_background,
+        detail=args.detail,
+        out=args.out,
+    )
+
+    try:
+        svg, report = convert(args.input, opts)
+    except FileNotFoundError:
+        _log(f"error: input not found: {args.input}")
+        return EXIT_ERROR
+    except Exception as exc:  # noqa: BLE001 - surface any failure as a hard error
+        _log(f"error: conversion failed: {exc}")
+        return EXIT_ERROR
+
+    try:
+        with open(report.output, "w", encoding="utf-8") as handle:
+            handle.write(svg)
+    except OSError as exc:
+        _log(f"error: could not write output {report.output!r}: {exc}")
+        return EXIT_ERROR
+
+    if args.report == "json":
+        # stdout carries the report and nothing else.
+        print(report.to_json())
+    else:
+        _log(
+            f"wrote {report.output} "
+            f"(mode={report.mode_used}, similarity={report.similarity:.3f}, "
+            f"passed={report.passed_threshold})"
+        )
+
+    for warning in report.warnings:
+        _log(f"warning: {warning}")
+
+    return EXIT_OK if report.passed_threshold else EXIT_BELOW_THRESHOLD
+
+
+def _rasterize(args: argparse.Namespace) -> int:
+    """Handle ``svgsmith rasterize`` — render an SVG to PNG."""
+    if not args.input:
+        _log("error: an input SVG path is required")
+        return EXIT_ERROR
+    from pathlib import Path
+
+    from svgsmith.render import rasterize as render_png
+
+    out = args.out or str(Path(args.input).with_suffix(".png"))
+    try:
+        render_png(
+            args.input,
+            out,
+            width=args.width,
+            height=args.height,
+            scale=args.scale,
+            background=args.background,
+        )
+    except FileNotFoundError:
+        _log(f"error: input not found: {args.input}")
+        return EXIT_ERROR
+    except Exception as exc:  # noqa: BLE001 - surface any failure as a hard error
+        _log(f"error: rasterize failed: {exc}")
+        return EXIT_ERROR
+    _log(f"wrote {out}")
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level argument parser and its subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="svgsmith",
+        description="Convert raster images into clean, editable SVG.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+
+    convert = subparsers.add_parser(
+        "convert",
+        help="Convert a raster image into SVG.",
+        description="Convert a raster image into clean, editable SVG.",
+        epilog=(
+            "exit codes: 0 success (similarity >= --quality); "
+            "2 SVG produced but below --quality; 1 hard error."
+        ),
+    )
+    convert.add_argument(
+        "input",
+        nargs="?",
+        help="Path to the input raster image (PNG, JPEG, …).",
+    )
+    convert.add_argument(
+        "--mode",
+        choices=list(MODES),
+        default="auto",
+        help="Conversion mode: auto|binary|color|pixel (default: auto).",
+    )
+    convert.add_argument(
+        "--quality",
+        type=float,
+        default=0.9,
+        help="Target fidelity in [0, 1] (default: 0.9).",
+    )
+    convert.add_argument(
+        "--max-iters",
+        type=int,
+        default=4,
+        help="Maximum verify/refine iterations (default: 4).",
+    )
+    convert.add_argument(
+        "--editable",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help=(
+            "Emit editable, grouped/simplified SVG (default: on). "
+            "Use --no-editable to skip postprocessing and emit the raw traced SVG."
+        ),
+    )
+    convert.add_argument(
+        "--smooth",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help=(
+            "Curve-refit color output into smooth, sparse Bezier contours "
+            "(default: on). Use --no-smooth to keep the raw traced geometry."
+        ),
+    )
+    convert.add_argument(
+        "--uniform-outline",
+        action="store_true",
+        default=False,
+        help=(
+            "Force an even-width outline band (color mode). Opt-in: only for "
+            "illustrations that already have a dark outline; would add a wrong "
+            "border on line art."
+        ),
+    )
+    convert.add_argument(
+        "--detail",
+        choices=["high", "normal", "clean", "poster"],
+        default="normal",
+        help=(
+            "Color detail dial (default: normal). high = maximum detail; "
+            "clean = edge-preserving cleanup, less noise; poster = bold flat graphic, "
+            "few colors."
+        ),
+    )
+    convert.add_argument(
+        "--solid-background",
+        action="store_true",
+        default=False,
+        help=(
+            "Isolate the subject and repaint the background as one clean solid "
+            "color, removing texture/grain/specks while keeping subject detail."
+        ),
+    )
+    convert.add_argument(
+        "--out",
+        default=None,
+        help="Output SVG path (default: input path with a .svg extension).",
+    )
+    convert.add_argument(
+        "--report",
+        choices=["off", "json"],
+        default="off",
+        help="Emit a JSON report alongside the SVG (default: off).",
+    )
+    convert.set_defaults(func=_convert)
+
+    rasterize = subparsers.add_parser(
+        "rasterize",
+        help="Render an SVG back to a PNG bitmap.",
+        description="Rasterize an SVG to PNG (preview, thumbnail, round-trip).",
+    )
+    rasterize.add_argument("input", nargs="?", help="Path to the input SVG file.")
+    rasterize.add_argument(
+        "--out", default=None, help="Output PNG path (default: input with a .png extension)."
+    )
+    rasterize.add_argument("--width", type=int, default=None, help="Output width in px.")
+    rasterize.add_argument("--height", type=int, default=None, help="Output height in px.")
+    rasterize.add_argument(
+        "--scale", type=float, default=None, help="Scale factor over the intrinsic size."
+    )
+    rasterize.add_argument(
+        "--background",
+        default=None,
+        help="Background color (e.g. white, #ffffff). Default: transparent.",
+    )
+    rasterize.set_defaults(func=_rasterize)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point for the ``svgsmith`` console script."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    handler = getattr(args, "func", None)
+    if handler is None:
+        parser.print_help()
+        return EXIT_OK
+
+    return handler(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

svgsmith/engines/__init__.py

@@ -0,0 +1,28 @@
+"""Uniform tracing interface over the bundled engines.
+
+Import the adapters and preset helpers from here; downstream code (T3 routing,
+T5 postprocess, T6 verify) depends only on ``trace(image, preset) -> str``.
+"""
+
+from .base import (
+    PRESETS,
+    ImageInput,
+    Preset,
+    Tracer,
+    get_preset,
+    load_image,
+)
+from .binary import BinaryTracer, PotraceNotFoundError
+from .color import ColorTracer
+
+__all__ = [
+    "PRESETS",
+    "BinaryTracer",
+    "ColorTracer",
+    "ImageInput",
+    "PotraceNotFoundError",
+    "Preset",
+    "Tracer",
+    "get_preset",
+    "load_image",
+]

svgsmith/engines/base.py

@@ -0,0 +1,118 @@
+"""Shared types for the tracing engines.
+
+Defines the :class:`Preset` parameter bundle, the canonical named presets, and
+the :class:`Tracer` protocol that every engine adapter implements. The rest of
+the pipeline depends only on ``trace(image, preset) -> str`` and never calls an
+engine library directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from PIL import Image
+
+ImageInput = str | Path | Image.Image
+
+
+@dataclass(frozen=True)
+class Preset:
+    """Engine parameters for one tracing profile.
+
+    A single bundle carries both color (VTracer) and binary (Potrace) knobs so
+    a caller can hand the same preset to either adapter; each adapter reads only
+    the fields it understands.
+    """
+
+    name: str
+
+    # Color (VTracer) parameters.
+    color_mode: str = "color"  # "color" | "binary"
+    color_precision: int = 6
+    layer_difference: int = 16
+    filter_speckle: int = 4
+    corner_threshold: int = 60
+    length_threshold: float = 4.0
+    splice_threshold: int = 45
+    path_precision: int = 8
+    curve_mode: str = "spline"  # "spline" | "polygon" | "none"
+    hierarchical: str = "stacked"  # "stacked" | "cutout"
+
+    # Binary (Potrace) parameters.
+    turdsize: int = 2  # speckle suppression: drop specks up to N pixels
+    alphamax: float = 1.0  # corner threshold
+    opttolerance: float = 0.2  # curve-fitting tolerance
+    threshold: float = 0.5  # luminance cut for binarization, in [0, 1]
+
+
+# Canonical preset names. #4 (classifier) and #8 (report `preset`) reference
+# exactly this list — do not add variants without updating those tickets.
+PRESETS: dict[str, Preset] = {
+    "logo": Preset(
+        name="logo",
+        color_precision=6,
+        filter_speckle=4,
+        corner_threshold=60,
+        turdsize=2,
+        alphamax=1.0,
+        opttolerance=0.2,
+    ),
+    "icon": Preset(
+        name="icon",
+        color_precision=8,
+        filter_speckle=2,
+        corner_threshold=40,
+        turdsize=1,
+        alphamax=1.0,
+        opttolerance=0.2,
+    ),
+    "illustration": Preset(
+        name="illustration",
+        # 6 (not the max 8): fewer, flatter color regions up front — perceptual
+        # LAB merge in postprocess then collapses near-duplicate tints. Together
+        # they drive the palette toward a small flat set without crushing rich art.
+        color_precision=6,
+        layer_difference=8,
+        filter_speckle=4,
+        corner_threshold=60,
+        turdsize=2,
+        alphamax=1.0,
+        opttolerance=0.4,
+    ),
+    "pixel": Preset(
+        name="pixel",
+        color_precision=8,
+        filter_speckle=0,
+        curve_mode="none",
+        corner_threshold=180,
+        turdsize=0,
+        alphamax=0.0,
+        opttolerance=0.0,
+    ),
+}
+
+
+def get_preset(name: str) -> Preset:
+    """Return the named canonical preset, or raise ``ValueError``."""
+    try:
+        return PRESETS[name]
+    except KeyError:
+        known = ", ".join(sorted(PRESETS))
+        raise ValueError(f"unknown preset {name!r}; choose one of: {known}") from None
+
+
+def load_image(image: ImageInput, mode: str = "RGBA") -> Image.Image:
+    """Open ``image`` (path or PIL image) and convert it to ``mode``."""
+    img = image if isinstance(image, Image.Image) else Image.open(image)
+    return img.convert(mode)
+
+
+@runtime_checkable
+class Tracer(Protocol):
+    """Uniform tracing interface implemented by every engine adapter."""
+
+    def trace(self, image: ImageInput, preset: Preset) -> str:
+        """Trace ``image`` with ``preset`` and return an SVG document string."""
+        ...

svgsmith/engines/binary.py

@@ -0,0 +1,71 @@
+"""Potrace-backed adapter for line-art / monochrome images.
+
+Shells out to the system ``potrace`` binary (installed via apt in CI) rather
+than binding to pypotrace, and exposes the uniform ``trace(image, preset) -> str``
+interface. The image is binarized to 1-bit, fed to ``potrace`` as a PBM bitmap
+over stdin, and the SVG is read back from stdout. See README for the system
+dependency.
+"""
+
+from __future__ import annotations
+
+import io
+import shutil
+import subprocess
+
+from .base import ImageInput, Preset, load_image
+
+POTRACE_BINARY = "potrace"
+
+
+class PotraceNotFoundError(RuntimeError):
+    """Raised when the system ``potrace`` binary cannot be located."""
+
+
+class BinaryTracer:
+    """Trace monochrome / line-art images into SVG via the potrace binary."""
+
+    def __init__(self, potrace_path: str | None = None) -> None:
+        self._potrace = potrace_path or shutil.which(POTRACE_BINARY)
+
+    def _binarize(self, image: ImageInput, threshold: float):
+        gray = load_image(image, "L")
+        cut = round(max(0.0, min(1.0, threshold)) * 255)
+        # Pixels brighter than the cut become white (255); darker pixels become
+        # black (0), which is what potrace traces.
+        return gray.point(lambda p, c=cut: 255 if p > c else 0, mode="1")
+
+    def trace(self, image: ImageInput, preset: Preset) -> str:
+        if self._potrace is None:
+            raise PotraceNotFoundError(
+                f"the {POTRACE_BINARY!r} binary was not found on PATH; install it "
+                "(e.g. `apt-get install potrace`)"
+            )
+
+        bitmap = self._binarize(image, preset.threshold)
+        buffer = io.BytesIO()
+        bitmap.save(buffer, format="PPM")  # 1-bit mode is written as binary PBM
+
+        command = [
+            self._potrace,
+            "--svg",
+            "--output",
+            "-",
+            "--turdsize",
+            str(preset.turdsize),
+            "--alphamax",
+            str(preset.alphamax),
+            "--opttolerance",
+            str(preset.opttolerance),
+            "-",
+        ]
+        result = subprocess.run(
+            command,
+            input=buffer.getvalue(),
+            capture_output=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            detail = result.stderr.decode(errors="replace").strip()
+            raise RuntimeError(f"potrace failed (exit {result.returncode}): {detail}")
+        return result.stdout.decode("utf-8")

svgsmith/engines/color.py

@@ -0,0 +1,36 @@
+"""VTracer-backed adapter for full-color raster images.
+
+Wraps the ``vtracer`` PyPI package and exposes the uniform
+``trace(image, preset) -> str`` interface. Produces layered, multi-color SVG.
+"""
+
+from __future__ import annotations
+
+import vtracer
+
+from .base import ImageInput, Preset, load_image
+
+
+class ColorTracer:
+    """Trace color images into multi-color SVG via VTracer."""
+
+    def trace(self, image: ImageInput, preset: Preset) -> str:
+        img = load_image(image, "RGBA")
+        # get_flattened_data() is the forward-compatible accessor; fall back to
+        # getdata() on older Pillow releases.
+        accessor = getattr(img, "get_flattened_data", img.getdata)
+        pixels = list(accessor())
+        return vtracer.convert_pixels_to_svg(
+            pixels,
+            img.size,
+            colormode=preset.color_mode,
+            hierarchical=preset.hierarchical,
+            mode=preset.curve_mode,
+            filter_speckle=preset.filter_speckle,
+            color_precision=preset.color_precision,
+            layer_difference=preset.layer_difference,
+            corner_threshold=preset.corner_threshold,
+            length_threshold=preset.length_threshold,
+            splice_threshold=preset.splice_threshold,
+            path_precision=preset.path_precision,
+        )