[#76] Line-quality Phase 0: axis-snap + smooth-gate fix + gated dark-outline snap

Three fidelity-safe line-quality wins, loop-validated on a 23-image harness.

- smooth.py: _axis_snap post-pass — straight runs already classified by the fitter,
  if within ~10deg of an exact 0/45/90/135 axis, snap to exact (length-preserving,
  endpoint propagated as the pen so contours stay seamless, per-snap drift guard).
- pipeline.py: wobble-relief escape on the all-or-nothing smooth gate — keep the
  smoothed output when it cuts contour wobble >=25% within a 0.10 SSIM hard floor,
  even when the plain 0.06 tolerance would veto the visibly-sharper result (SSIM
  rewards the antialiased staircase). The 0.06 safety net is unchanged.
- preprocess.py/postprocess.py/pipeline.py: gated dark-outline palette-snap — on the
  coverage path, collapse scattered near-black outline tints to one clean #000000
  layer (luma/DeltaE snap + palette exclusion + output-side fill snap), NO morph
  erosion. Class-gated (near-black-mass pre-gate) and SSIM-guarded.

Harness medians baseline->after: axis_purity 0.199->0.233, jitter 0.427->0.387,
dark_colors 33->22, SSIM 0.908->0.907 (flat). c_17 dark 47->1 SSIM +0.034; c_15
dark 125->26 paths 311->192 (cleaner outlines, visually confirmed); c_41 axis +0.10.
Only c_15 crosses -0.02 SSIM (the known SSIM metric inversion on the staircase).
No class leak; corpus goldens + full suite green; ruff clean. Tests added for
_axis_snap and snap_dark_fills. Version 0.5.0 -> 0.5.1.

Fixes #76

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: realproject7

src/svgsmith/__init__.py

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

src/svgsmith/pipeline.py

@@ -15,7 +15,7 @@
 
 from svgsmith.classify import Classification, classify
 from svgsmith.engines.base import ImageInput, load_image
-from svgsmith.postprocess import drop_background_paths, snap_background_layer
+from svgsmith.postprocess import drop_background_paths, snap_background_layer, snap_dark_fills
 from svgsmith.preprocess import PreprocessOptions, _edge_flood_fill_mask, preprocess
 from svgsmith.report import Report, svg_stats
 from svgsmith.smooth import smooth_svg
@@ -121,6 +121,51 @@ def _supersample_candidate(image: ImageInput) -> bool:
 # False to fall back to pure Tier 1 (narrow full-frame-gradient gate, no region cleanup).
 _TIER2_REGION_COVERAGE = True
 
+# Dark-outline black snap (#lever-C). On the coverage path the dark linework of an outlined
+# cartoon scatters across many near-black tints (the pigeon JPEG: 186 dark colours), bloating
+# paths and giving a ragged variable-width outline. We pull every pixel within this ΔE76 ball of
+# pure black out of the palette build and paint it ONE clean #000000 region (NO morphology — that
+# was verified to regress outline IoU). ``_COVERAGE_BLACK_SNAP_DE`` is the ball radius;
+# ``_COVERAGE_BLACK_SNAP_MIN_AREA`` is the near-black share that must be present before it fires,
+# so line-free / no-black art (e.g. c_07) is left byte-identical. SSIM-guarded in ``convert``: the
+# snapped trace is kept only when it does not cost more than ``_COVERAGE_BLACK_SNAP_SSIM_DROP``
+# SSIM against the no-snap trace. SAFE-REVERT: set the ΔE to 0.0 to disable.
+_COVERAGE_BLACK_SNAP_DE = 12.0
+_COVERAGE_BLACK_SNAP_MIN_AREA = 0.004
+_COVERAGE_BLACK_SNAP_SSIM_DROP = 0.01
+
+
+def _distinct_dark_fills(svg: str) -> int:
+    """Count distinct dark (luma < 60) fill colours in an SVG — the dark-layer cleanliness
+    proxy. Used to guard the black snap: a sharper black core can make the colour tracer
+    carve MORE near-black edge tints on some inputs, so we keep the snap only when it does
+    not inflate this count.
+    """
+    import re
+
+    dark = set()
+    for hexc in re.findall(r'fill="(#[0-9a-fA-F]{6})"', svg):
+        r, g, b = (int(hexc[i : i + 2], 16) for i in (1, 3, 5))
+        if 0.299 * r + 0.587 * g + 0.114 * b < 60:
+            dark.add(hexc.lower())
+    return len(dark)
+
+
+def _has_black_outline(image: ImageInput) -> bool:
+    """Cheap pre-check: does ``image`` carry enough near-pure-black mass to snap an outline?
+
+    Mirrors the per-pixel test inside ``quantize_coverage`` (ΔE76 to the LAB origin) so the
+    pipeline can decide up front whether the black-snap will fire — and therefore whether the
+    SSIM-guard's extra no-snap render is even needed. No-black art short-circuits to a single
+    render with byte-identical output.
+    """
+    from skimage.color import rgb2lab
+
+    rgb = np.asarray(load_image(image, "RGB"), dtype=np.float64)
+    lab = rgb2lab(rgb / 255.0)
+    near_black = (np.linalg.norm(lab, axis=2) <= _COVERAGE_BLACK_SNAP_DE).mean()
+    return float(near_black) >= _COVERAGE_BLACK_SNAP_MIN_AREA
+
 
 def _coverage_candidate(image: ImageInput) -> bool:
     """Whether ``image`` should take the perceptual-coverage colour path.
@@ -144,10 +189,96 @@ def _coverage_candidate(image: ImageInput) -> bool:
 # Max SSIM the curve-smoothing pass may cost before we fall back to un-smoothed
 # output (smoothing reduces SSIM slightly by design; a big drop = lost feature).
 _SMOOTH_SSIM_TOLERANCE = 0.06
+# Wobble-relief escape clause for the smooth gate. Raw-SSIM rewards the antialiased
+# pixel staircase, so on the wobbliest inputs the visibly-SHARPER smoothed output can
+# score LOWER and get vetoed by the plain SSIM gate above — exactly where smoothing is
+# most needed (e.g. a jittery vtracer polyline that smoothing straightens). To recover
+# those cases we measure path wobble directly off the SVG geometry (angle sign-flips per
+# unit length over the polyline approximation — the same structure SSIM is blind to). If
+# smoothing cuts wobble by at least _SMOOTH_WOBBLE_RELIEF (relative) AND SSIM stays within
+# the wider _SMOOTH_SSIM_HARD_FLOOR, we keep the smoothed output even when the plain SSIM
+# tolerance would veto it. The hard floor still guards against a genuine feature loss
+# (which would crater SSIM far past the staircase penalty). Inputs that already clear the
+# plain tolerance are unaffected, so default behaviour is unchanged for them.
+_SMOOTH_WOBBLE_RELIEF = 0.25
+_SMOOTH_SSIM_HARD_FLOOR = 0.10
 _MODE_PRESET = {"binary": "logo", "color": "illustration", "pixel": "pixel"}
 MODES = ("auto", *_MODE_PRESET)
 
 
+def _path_wobble(svg: str) -> float:
+    """Wobble of an SVG's contours: angle sign-flips per unit length over its polylines.
+
+    Rasterization-free structural measure of polyline jitter — high when a contour
+    zig-zags (raw quantized-pixel edges), low when it is a clean curve (after smoothing).
+    Mirrors the line-quality jitter metric so the smooth gate can reward genuine wobble
+    removal that raw SSIM (which rewards the antialiased staircase) penalises.
+    """
+    import math
+    import re
+    import xml.etree.ElementTree as ET
+
+    num = r"[-+]?(?:\d*\.\d+|\d+\.?)(?:[eE][-+]?\d+)?"
+    try:
+        root = ET.fromstring(svg)
+    except ET.ParseError:
+        return 0.0
+    flips = 0.0
+    length = 0.0
+    for el in root.iter():
+        if el.tag.rsplit("}", 1)[-1] != "path":
+            continue
+        toks = re.findall(r"[MmLlCcQqZzHhVv]|" + num, el.attrib.get("d", ""))
+        pts: list[list[float]] = []
+        subs: list[np.ndarray] = []
+        cur = [0.0, 0.0]
+        i = 0
+        while i < len(toks):
+            t = toks[i]
+            if t in "Mm":
+                if pts:
+                    subs.append(np.array(pts))
+                    pts = []
+                x, y = float(toks[i + 1]), float(toks[i + 2])
+                cur = [x, y] if t == "M" else [cur[0] + x, cur[1] + y]
+                pts = [cur[:]]
+                i += 3
+            elif t in "Ll":
+                x, y = float(toks[i + 1]), float(toks[i + 2])
+                cur = [x, y] if t == "L" else [cur[0] + x, cur[1] + y]
+                pts.append(cur[:])
+                i += 3
+            elif t in "Cc":
+                c = [float(v) for v in toks[i + 1 : i + 7]]
+                cur = [c[4], c[5]] if t == "C" else [cur[0] + c[4], cur[1] + c[5]]
+                pts.append(cur[:])
+                i += 7
+            elif t in "Qq":
+                c = [float(v) for v in toks[i + 1 : i + 5]]
+                cur = [c[2], c[3]] if t == "Q" else [cur[0] + c[2], cur[1] + c[3]]
+                pts.append(cur[:])
+                i += 5
+            else:
+                i += 1
+        if pts:
+            subs.append(np.array(pts))
+        for poly in subs:
+            if len(poly) < 4:
+                continue
+            seg = np.diff(poly, axis=0)
+            seg_len = np.hypot(seg[:, 0], seg[:, 1])
+            ang = np.arctan2(seg[:, 1], seg[:, 0])
+            if len(ang) <= 2:
+                continue
+            da = np.diff(ang)
+            da = (da + np.pi) % (2 * np.pi) - np.pi
+            small = np.abs(da) < math.radians(40)
+            flip = np.sign(da[:-1]) != np.sign(da[1:])
+            flips += float(np.sum(small[:-1] & flip))
+            length += float(seg_len.sum())
+    return 100.0 * flips / max(length, 1.0)
+
+
 @dataclass(frozen=True)
 class ConvertOptions:
     """Options for :func:`convert` (mirrors the ``svgsmith convert`` flags)."""
@@ -326,7 +457,18 @@ def render(
             reference = load_image(image, "RGB")
             smoothed = smooth_svg(svg)
             smoothed_score = score(reference, rasterize(smoothed, reference.size))
-            if smoothed_score >= result.best_score - _SMOOTH_SSIM_TOLERANCE:
+            keep = smoothed_score >= result.best_score - _SMOOTH_SSIM_TOLERANCE
+            # Wobble-relief escape clause: raw SSIM rewards the antialiased staircase, so a
+            # visibly-sharper smooth can dip past the plain tolerance on the wobbliest inputs.
+            # Recover those by measuring path wobble directly (SSIM is blind to it): if
+            # smoothing genuinely straightens the contours and SSIM stays within the wider
+            # hard floor, keep it. The floor still vetoes a true feature loss (huge SSIM drop).
+            if not keep and smoothed_score >= result.best_score - _SMOOTH_SSIM_HARD_FLOOR:
+                raw_wobble = _path_wobble(svg)
+                if raw_wobble > 0.0:
+                    relief = (raw_wobble - _path_wobble(smoothed)) / raw_wobble
+                    keep = relief >= _SMOOTH_WOBBLE_RELIEF
+            if keep:
                 svg, similarity = smoothed, smoothed_score
         return svg, similarity, result.iterations
 
@@ -370,9 +512,42 @@ def render(
                 coverage_dark_thin=opts.illustration_dark_thin,
             )
         cov_class = classification._replace(preset="continuous")
-        svg, similarity, iterations = render(
+        # Dark-outline black snap (#lever-C): collapse scattered near-black tints into one clean
+        # #000000 outline layer. Only engage when there is genuine near-black mass (so no-black art
+        # is untouched and pays no extra render); then SSIM-guard against the no-snap trace so a
+        # dark-but-not-black-detail image can never regress.
+        snap_black = _COVERAGE_BLACK_SNAP_DE > 0.0 and _has_black_outline(image)
+        base_svg, base_sim, base_iters = render(
             cov_pre, cov_class, palette_threshold=0.0, max_iters=1
         )
+        if snap_black:
+            # Palette-build snap gives the tracer a clean pure-black core; the output-side
+            # fill snap then collapses the tints the colour tracer re-derives along the
+            # anti-aliased outline edges into one #000000 layer. SSIM-guarded: keep the
+            # snapped result only when it does not cost more than the tolerance vs the
+            # un-snapped trace, so a dark-but-not-black-detail image can never regress.
+            snap_pre = replace(
+                cov_pre,
+                coverage_black_snap=_COVERAGE_BLACK_SNAP_DE,
+                coverage_black_snap_min_area=_COVERAGE_BLACK_SNAP_MIN_AREA,
+            )
+            snap_svg, snap_sim, snap_iters = render(
+                snap_pre, cov_class, palette_threshold=0.0, max_iters=1
+            )
+            snap_svg = snap_dark_fills(snap_svg, _COVERAGE_BLACK_SNAP_DE)
+            snap_sim = score(
+                load_image(image, "RGB"), rasterize(snap_svg, load_image(image, "RGB").size)
+            )
+            # Keep the snap only when it both holds SSIM AND actually cleans the dark layer
+            # (never inflates the distinct-dark-fill count) — a sharper black core can make the
+            # colour tracer carve MORE edge tints on some inputs, the opposite of the goal.
+            cleaner = _distinct_dark_fills(snap_svg) <= _distinct_dark_fills(base_svg)
+            if base_sim - snap_sim <= _COVERAGE_BLACK_SNAP_SSIM_DROP and cleaner:
+                svg, similarity, iterations = snap_svg, snap_sim, snap_iters
+            else:
+                svg, similarity, iterations = base_svg, base_sim, base_iters
+        else:
+            svg, similarity, iterations = base_svg, base_sim, base_iters
         # Path cap = misgated-photo blowup guard. At --detail high the user opted into
         # max fidelity, so a high count is INTENDED for legitimately grainy/painterly art
         # (the reference traces such inputs into thousands of micro-tiles) — raise the cap

src/svgsmith/postprocess.py

@@ -744,6 +744,34 @@ def drop_background_paths(svg_str: str, bg_mask: np.ndarray) -> str:
     return _build_svg(root, kept, True)
 
 
+_BLACK = "#000000"
+
+
+def snap_dark_fills(svg_str: str, de: float) -> str:
+    """Collapse every near-pure-black fill in the SVG to a single clean ``#000000``.
+
+    The dark-outline black snap (#lever-C) pulls near-black pixels out of the coverage
+    palette build, but the colour tracer re-derives fills from the image and re-introduces
+    a spray of near-black tints along the anti-aliased outline edges. This is the matching
+    output-side step: every fill within ``de`` (CIE76 ΔE) of pure black is rewritten to one
+    ``#000000``, so the linework becomes a single black layer instead of hundreds of tints.
+
+    Surgical string rewrite of the ``fill`` attribute only — geometry, ordering and every
+    non-dark fill are left byte-identical, so the result is a no-op on art with no near-black
+    fills. ``de <= 0`` disables it.
+    """
+    if de <= 0.0:
+        return svg_str
+
+    def _swap(match: re.Match[str]) -> str:
+        hex_color = _normalize_hex(match.group(1))
+        if hex_color and hex_color != _BLACK and _color_distance(hex_color, _BLACK) <= de:
+            return f'fill="{_BLACK}"'
+        return match.group(0)
+
+    return re.sub(r'fill="(#[0-9a-fA-F]{3,6})"', _swap, svg_str)
+
+
 def svg_bbox(svg_str: str, samples: int = 18) -> tuple[float, float, float, float] | None:
     """Overall geometry bounding box ``(minx, miny, maxx, maxy)``, or None."""
     root = ET.fromstring(svg_str)

src/svgsmith/preprocess.py

@@ -95,6 +95,17 @@ class PreprocessOptions:
     # tone — a target for the daily quality loop to refine.
     coverage_dark_thin: int = 0
     coverage_dark_protect: float = 0.0006
+    # Dark-outline black snap (#lever-C; 0 = OFF = unchanged): outlined-cartoon JPEGs scatter the
+    # dark linework across many near-black tints (the pigeon: 186 dark colours), bloating paths and
+    # giving a ragged variable-width outline. When >0, every pixel within ``coverage_black_snap``
+    # (ΔE76) of pure black is pulled OUT of the coverage palette build and painted as ONE clean
+    # #000000 region, so the outline becomes a single black layer. Bounded by construction (a
+    # snapped pixel moves at most ``coverage_black_snap`` ΔE). Self-gating: it only fires when the
+    # near-black mass is at least ``coverage_black_snap_min_area`` of the image, so no-black art
+    # (e.g. a pure-pastel illustration) is left byte-identical. NO morphology — just a luma/chroma
+    # threshold snap + palette exclusion (erosion was verified to regress outline IoU).
+    coverage_black_snap: float = 0.0
+    coverage_black_snap_min_area: float = 0.004  # min near-black share before the snap activates
 
     solid_background: bool = False  # replace the background with one clean solid color
     background_tolerance: int = 32  # per-channel tolerance for the edge-flood-fill bg region
@@ -482,6 +493,8 @@ def quantize_coverage(
     region_noise_de: float = 0.0,
     dark_thin: int = 0,
     dark_protect: float = 0.0006,
+    black_snap: float = 0.0,
+    black_snap_min_area: float = 0.004,
     denoise_lossy: bool = False,
     denoise_sigma_color: float = 0.02,
     denoise_sigma_spatial: float = 1.5,
@@ -510,6 +523,18 @@ def quantize_coverage(
     rgb = rgba[:, :, :3].reshape(-1, 3).astype(np.float64)
     lab = rgb2lab(rgba[:, :, :3] / 255.0).reshape(-1, 3)
 
+    # Dark-outline black snap (#lever-C): pull every pixel within ``black_snap`` (ΔE76) of pure
+    # black OUT of the palette build and paint it one clean #000000 region, so scattered near-black
+    # tints collapse to a single outline layer. ΔE to pure black is just the LAB norm (pure black
+    # is the LAB origin). Self-gating: only fire when the near-black share clears
+    # ``black_snap_min_area`` so no-black art is untouched (a snapped pixel moves at most
+    # ``black_snap`` ΔE).
+    black_mask = None
+    if black_snap > 0.0:
+        cand = np.linalg.norm(lab, axis=1) <= black_snap
+        if cand.mean() >= black_snap_min_area:
+            black_mask = cand
+
     # Weighted histogram over 1-unit LAB bins (cheap, resolution-independent work set).
     # Encode each (L, a, b) bin into one integer key (L highest-order) so the dedup is a
     # 1-D ``np.unique`` instead of ``unique(..., axis=0)``'s lexsort — the dominant cost
@@ -533,16 +558,29 @@ def quantize_coverage(
     bin_rgb_sum = np.zeros((len(bins), 3))
     np.add.at(bin_rgb_sum, inverse, rgb)
 
+    # Exclude the near-black bins from the palette build so the greedy never spends budget
+    # carving the outline into many tints. A bin counts as black when its center is within
+    # ``black_snap`` of the LAB origin (matches the per-pixel test). Their pixels are repainted
+    # pure black at the end via ``black_mask``; here we zero their weight and keep them out of
+    # the leftover/speckle bookkeeping by pre-assigning a sentinel.
+    black_bin = (
+        np.linalg.norm(binf, axis=1) <= black_snap
+        if black_mask is not None
+        else np.zeros(len(bins), dtype=bool)
+    )
+
     assigned = np.full(len(bins), -1, dtype=np.int64)
     centers_lab: list[np.ndarray] = []
     remaining = counts.astype(np.float64).copy()
+    remaining[black_bin] = 0.0  # never selected as / absorbed into a coverage anchor
+    cover_total = float(remaining.sum()) or total  # coverage budget over the non-black mass
     covered = 0.0
-    while covered < coverage * total and len(centers_lab) < max_colors:
+    while covered < coverage * cover_total and len(centers_lab) < max_colors:
         idx = int(np.argmax(remaining))
         if remaining[idx] <= 0:
             break
         center = binf[idx]
-        within = (np.linalg.norm(binf - center, axis=1) <= step) & (assigned < 0)
+        within = (np.linalg.norm(binf - center, axis=1) <= step) & (assigned == -1) & ~black_bin
         ci = len(centers_lab)
         assigned[within] = ci
         centers_lab.append(center)
@@ -553,10 +591,19 @@ def quantize_coverage(
         return img
     centers = np.array(centers_lab)
     # Tail colours beyond the coverage budget snap to their nearest palette entry.
-    leftover = np.where(assigned < 0)[0]
+    leftover = np.where((assigned == -1) & ~black_bin)[0]
     for bi in leftover:
         assigned[bi] = int(np.argmin(np.linalg.norm(centers - binf[bi], axis=1)))
 
+    # The near-black bins become ONE dedicated palette entry, kept out of the coverage build
+    # above so the outline is a single clean layer instead of many scattered tints. Its
+    # representative is forced to pure black at the end (rep-mean would drift to dark grey).
+    black_entry = -1
+    if black_bin.any():
+        black_entry = len(centers)
+        centers = np.vstack([centers, np.zeros((1, 3))])
+        assigned[black_bin] = black_entry
+
     # Representative RGB per palette entry = mean RGB of its pixels.
     n = len(centers)
     rep_sum = np.zeros((n, 3))
@@ -580,6 +627,11 @@ def quantize_coverage(
         np.add.at(rep_cnt, assigned, counts)
         rep_rgb = np.divide(rep_sum, np.maximum(rep_cnt[:, None], 1.0))
 
+    # Force the dedicated outline entry to pure #000000 (the rep-mean of near-black pixels
+    # would otherwise land on a dark grey, defeating the single-clean-black-layer goal).
+    if black_entry >= 0:
+        rep_rgb[black_entry] = 0.0
+
     pixel_palette = assigned[inverse]  # palette index per pixel (flat)
 
     # Tier 2 (#67): merge by connected-component *area*, not global colour mass. This
@@ -782,6 +834,8 @@ def preprocess(image: ImageInput, opts: PreprocessOptions | None = None) -> Imag
                 region_noise_de=opts.coverage_region_noise_de,
                 dark_thin=opts.coverage_dark_thin,
                 dark_protect=opts.coverage_dark_protect,
+                black_snap=opts.coverage_black_snap,
+                black_snap_min_area=opts.coverage_black_snap_min_area,
                 denoise_lossy=lossy_coverage,
                 denoise_sigma_color=opts.coverage_denoise_sigma_color,
                 denoise_sigma_spatial=opts.coverage_denoise_sigma_spatial,