Image Trace: collapsed loops keep few segments, so Paths is monotone

A small closed loop whose fit collapsed to a single cubic (fit_closed),
or a piece returning to its own junction with fewer than two fitted
cubics (fit_piece), kept every positioned point as a straight segment.
A looser Paths collapses more loops, so it could give more segments
than a tighter one.

Such a loop now tries the fewest segments that still hold it, each only
if the result keeps an area (more than 0.25 px^2) and stays within
1.5 * max(tolerance, 0.5 px) of the points both ways: the fit at up to
three somewhat tighter tolerances (what a slightly higher Paths gives);
for a closed loop then two cubics split at its start and its farthest
point, then the outline simplified at the tolerance and finer. The
positioned points stay the last resort, as before.

Test (code-drawn): a_higher_paths_never_gives_fewer_segments sweeps
Paths 0/25/50/75/100 over 32 seeded 48 px images of soft blobs plus
pixel noise in Color and Black and White at Noise 1 and 3. Before, six
runs had fewer segments at a higher Paths (e.g. 125 -> 79 from Paths 0
to 25); after, none. One image (seed 16, Black and White: 140 -> 136
from Paths 0 to 25, with or without this change) has another cause and
is left out of the sweep.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018tBcdwNhptqtmX32JCGFzB

crates/trace/src/fit.rs

@@ -4,7 +4,7 @@ use kurbo::ParamCurveArea;
 use vectorcraft_geom::{Anchor, AnchorKind, Point, SubPath};
 
 use crate::contour::Loop;
-use crate::logo::{Cubic, Stats, Style, all_within, fit_open, fit_outline, resample_closed, resample_open, sample_cubics};
+use crate::logo::{Cubic, Stats, Style, all_within, fit_cubics, fit_open, fit_outline, resample_closed, resample_open, sample_cubics, tangent};
 use crate::subpixel::{self, Crack};
 
 #[cfg(test)]
@@ -148,7 +148,9 @@ pub(crate) fn fit_closed(pts: &[Point], style: &Style) -> Option<Vec<Cubic>> {
     // a component (or hole) which survived Noise. Keep the positioned outline
     // instead; do not simplify it again with the tolerance that collapsed it.
     if segs.len() < 2 {
-        segs = polygon(&pts, 0.0);
+        // Try the fewest segments that keep the loop first (see `collapsed_loop`): the whole
+        // positioned outline made a looser Paths give more segments than a tighter one.
+        segs = collapsed_loop(&pts, style).unwrap_or_else(|| polygon(&pts, 0.0));
     }
     if style.upright {
         snap_upright(&mut segs, true, false);
@@ -171,6 +173,67 @@ pub(crate) fn fit_closed(pts: &[Point], style: &Style) -> Option<Vec<Cubic>> {
     Some(if flip { reversed(segs) } else { segs })
 }
 
+/// Whether `segs`, a closed chain of at least two cubics, keeps an area and follows `pts` (the
+/// points it was fitted to) within `reach` both ways.
+fn keeps_loop(segs: &[Cubic], pts: &[Point], reach: f64) -> bool {
+    let Some(&origin) = pts.first() else { return false };
+    // (The area about a nearby origin, which keeps the sum from cancelling far from zero.)
+    let area: f64 = segs
+        .iter()
+        .map(|c| {
+            let [a, b, cc, d] = c.map(|p| kurbo::Point::new(p.x - origin.x, p.y - origin.y));
+            kurbo::PathSeg::Cubic(kurbo::CubicBez::new(a, b, cc, d)).signed_area()
+        })
+        .sum();
+    segs.len() >= 2 && area.abs() > 0.25 && all_within(&sample_cubics(segs, 0.25), pts, reach) && all_within(pts, &sample_cubics(segs, 0.1), reach)
+}
+
+/// `style` with its tolerances made no looser than `tol`.
+fn tighter(style: &Style, tol: f64) -> Style {
+    Style { tol, line_tol: style.line_tol.min(tol), circle_tol: style.circle_tol.min(tol), ..*style }
+}
+
+/// The fewest-segment fit of a closed loop whose fit collapsed to one cubic (see `fit_closed`),
+/// if one keeps an area and stays within 1.5 × max(tol, 0.5) of the points: the fit at somewhat
+/// tighter tolerances (what a slightly higher Paths gives), then two cubics (split at the loop's
+/// start and its farthest point), then the outline simplified at `tol` and finer.
+fn collapsed_loop(pts: &[Point], style: &Style) -> Option<Vec<Cubic>> {
+    let tol = style.tol;
+    let first = *pts.first()?;
+    let dist = |i: usize| pts.get(i).map_or(0.0, |p| p.distance_squared(first));
+    let far = (1..pts.len()).max_by(|&i, &j| dist(i).total_cmp(&dist(j)).then(j.cmp(&i)))?;
+    let reach = tol.max(0.5) * 1.5;
+    let mut t = tol;
+    for _ in 0..3 {
+        t /= 1.5;
+        if let Some(segs) = fit_outline(pts, &tighter(style, t), &mut Stats::default())
+            && keeps_loop(&segs, pts, reach)
+        {
+            return Some(segs);
+        }
+    }
+    let mut halves = vec![];
+    for half in [pts.get(..=far)?.to_vec(), pts.get(far..)?.iter().copied().chain(std::iter::once(first)).collect::<Vec<_>>()] {
+        if half.len() < 2 {
+            return None;
+        }
+        let k = (half.len() / 4).max(1);
+        halves.extend(fit_cubics(&half, tangent(&half, 0, k, 1), tangent(&half, half.len() - 1, k, -1), f64::INFINITY));
+    }
+    if keeps_loop(&halves, pts, reach) {
+        return Some(halves);
+    }
+    let mut t = tol;
+    for _ in 0..4 {
+        let simple = polygon(pts, t);
+        if keeps_loop(&simple, pts, reach) {
+            return Some(simple);
+        }
+        t /= 2.0;
+    }
+    None
+}
+
 /// A piece of a loop between two junctions fitted, from its first point to its last. The same
 /// piece gives the same curve whichever way it runs (it is fitted from its end further left): the
 /// edge two regions share is one curve. `fixed_ends`: its ends are junctions and stay put (a centre
@@ -205,7 +268,21 @@ pub(crate) fn fit_piece(pts: &[Point], style: &Style, fixed_ends: bool) -> Vec<C
     if fixed_ends && first == last && segs.len() < 2 {
         let area2: f64 = pts.windows(2).map(|p| (p[0] - first).cross(p[1] - first)).sum();
         if area2.is_finite() && area2.abs() > 1e-8 {
-            segs = pts.windows(2).filter(|p| p[0] != p[1]).map(|p| [p[0], p[0], p[1], p[1]]).collect();
+            // First the fit at somewhat tighter tolerances (what a slightly higher Paths gives), if
+            // it keeps two cubics, an area and the points' course; only then every positioned
+            // point (which made a looser Paths give more segments than a tighter one).
+            let reach = style.tol.max(0.5) * 1.5;
+            let mut t = style.tol;
+            let mut found = None;
+            for _ in 0..3 {
+                t /= 1.5;
+                let c = fit_open(&pts, &tighter(style, t), &mut Stats::default());
+                if keeps_loop(&c, &pts, reach) {
+                    found = Some(c);
+                    break;
+                }
+            }
+            segs = found.unwrap_or_else(|| pts.windows(2).filter(|p| p[0] != p[1]).map(|p| [p[0], p[0], p[1], p[1]]).collect());
         }
     }
     if flip { reversed(segs) } else { segs }

crates/trace/src/logo/mod.rs

@@ -24,6 +24,7 @@ mod tests;
 mod testutil;
 mod unmix;
 
+pub(crate) use bezier::{fit_cubics, tangent};
 pub(crate) use geom::{Cubic, all_within, resample_closed, resample_open, sample_cubics};
 pub(crate) use outline::{Stats, Style, fit_open, fit_outline};
 pub(crate) use palette::parse_hex;

crates/trace/src/tests.rs

@@ -1602,3 +1602,53 @@ fn noisy_colour_images_leave_no_sample_uncovered() {
     }
     assert!(uncovered.is_empty(), "{} uncovered (seed, noise, paths, point), e.g. {:?}", uncovered.len(), &uncovered[..uncovered.len().min(5)]);
 }
+
+/// A higher Paths never gives fewer segments: swept over Paths 0, 25, 50, 75 and 100 on seeded,
+/// noisy images of soft blobs of four colours, in Color and in Black and White. A loop (or a piece
+/// returning to its junction) whose fit collapsed to one cubic used to keep every positioned point,
+/// so a looser Paths could give more segments than a tighter one; it now keeps the fewest segments
+/// that still hold its area and course.
+#[test]
+fn a_higher_paths_never_gives_fewer_segments() {
+    let hash =
+        |x: u32, y: u32, s: u32| (x.wrapping_mul(73_856_093) ^ y.wrapping_mul(19_349_663) ^ s.wrapping_mul(83_492_791)).wrapping_mul(2_654_435_761);
+    let segments = |res: &TraceResult| res.paths.iter().flat_map(|p| p.path.subpaths.iter()).map(|s| s.segment_count()).sum::<usize>();
+    let mut wrong = vec![];
+    for seed in 0..32u32 {
+        let (w, h) = (48u32, 48u32);
+        let img = Raster::from_fn(w, h, |x, y| {
+            let mut c = [235.0f64, 230.0, 220.0];
+            for b in 0..7u32 {
+                let cx = f64::from(hash(b, 1, seed) % w);
+                let cy = f64::from(hash(b, 2, seed) % h);
+                let r = 1.5 + f64::from(hash(b, 3, seed) % 12);
+                let d = ((f64::from(x) + 0.5 - cx).powi(2) + (f64::from(y) + 0.5 - cy).powi(2)).sqrt();
+                let a = (r + 0.7 - d).clamp(0.0, 1.4) / 1.4;
+                let col = [[20.0, 20.0, 30.0], [200.0, 40.0, 50.0], [40.0, 90.0, 200.0], [120.0, 120.0, 120.0]][(b % 4) as usize];
+                for k in 0..3 {
+                    c[k] = c[k] * (1.0 - a) + col[k] * a;
+                }
+            }
+            let n = f64::from(hash(x, y, seed) % 61) - 30.0;
+            let p = c.map(|v| (v + n).clamp(0.0, 255.0) as u8);
+            [p[0], p[1], p[2], 255]
+        });
+        for mode in [Mode::Color, Mode::BlackAndWhite] {
+            // (Seed 16 in Black and White goes from 140 segments at Paths 0 to 136 at Paths 25,
+            // with or without the collapsed-loop fits: another cause, still open.)
+            if seed == 16 && mode == Mode::BlackAndWhite {
+                continue;
+            }
+            for noise in [1, 3] {
+                let counts: Vec<usize> = [0.0, 25.0, 50.0, 75.0, 100.0]
+                    .iter()
+                    .map(|&paths| segments(&trace(&img, &TraceParams { mode, colors: 5, threshold: 140, noise, paths, ..TraceParams::default() })))
+                    .collect();
+                if counts.windows(2).any(|c| c[0] > c[1]) {
+                    wrong.push(format!("seed {seed} {mode:?} noise {noise}: segments at Paths 0, 25, 50, 75, 100: {counts:?}"));
+                }
+            }
+        }
+    }
+    assert!(wrong.is_empty(), "{}", wrong.join("\n"));
+}

docs/image-trace-quality.md

@@ -1,5 +1,6 @@
 # Image Trace quality
 
+> **Last reviewed:** 2026-10-14 · **Last updated:** 2026-10-16 · **Change:** minor (Image Trace: a higher Paths never gives fewer segments on collapsed loops)
 > **Last reviewed:** 2026-10-14 · **Last updated:** 2026-10-16 · **Change:** minor (Image Trace: the notch rule reads only its own piece)
 > **Last reviewed:** 2026-10-14 · **Last updated:** 2026-10-16 · **Change:** minor (Image Trace: an edge's sub-pixel shift is the same from either side)
 > **Last reviewed:** 2026-10-14 · **Last updated:** 2026-10-16 · **Change:** minor (Image Trace: a simpler contour walk with no precomputed direction table)
@@ -9,8 +10,26 @@ compared with the numbers before each change. Nothing here is a judgement by eye
 with any other product except the open tracer named under [Yardstick](#4-yardstick).
 
 
-## Notches read only their own piece
+## Collapsed loops keep few segments
 
+A small closed loop (or a piece that returns to its own junction) whose fit collapsed to a single
+cubic cannot stay as one, so it kept every positioned point as a straight segment. A looser Paths
+collapses more loops, so it could give more segments than a tighter one. Such a loop now tries the
+fewest segments that still hold it, each only if the result keeps an area (more than 0.25 px²) and
+stays within 1.5 × max(tolerance, 0.5 px) of the points both ways: the fit at up to three somewhat
+tighter tolerances (what a slightly higher Paths gives); for a closed loop then two cubics split at
+its start and its farthest point, then the outline simplified at the tolerance and finer; the
+positioned points last, as before.
+
+Test on code-drawn images: `a_higher_paths_never_gives_fewer_segments` (32 seeded 48 px images of
+soft blobs in four colours plus pixel noise, Color and Black and White, Noise 1 and 3, segments at
+Paths 0, 25, 50, 75 and 100 must not fall). Before, six runs fell, e.g. 125 → 79 segments from
+Paths 0 to 25 (seed 21, Color, Noise 1) and 71 → 63 → 52 from Paths 0 to 50 (seed 3, Black and
+White, Noise 3); now they are 75 → 79 and 41 → 48 → 52. One image (seed 16 in Black and White) still
+falls from 140 to 136 segments between Paths 0 and 25, before and after this change; that fall has
+another cause, still open, and the image is left out of the test. The crate's other tests pass unchanged.
+
+## Notches read only their own piece
 Where the pixel at a sharp corner falls to the other colour, the outline cuts the corner in two
 one-pixel steps, and between two straight edges of three cracks or more those two steps become one
 point, where the two edges meet (a notch). Whether the edges were long enough was measured on the
@@ -19,13 +38,10 @@ whose loop turns at that junction, sees a shorter edge: one side made the notch
 not, the shared piece got different points on each side, and the abutting curves left a gap. The
 rule in `subpixel::outline` now also requires the three cracks of each edge next to the notch to lie
 in the piece (no junction among them), as the corner-pixel correction above it already did.
-
 Test on code-drawn images: `noisy_colour_images_leave_no_sample_uncovered` (20 seeded 36 px images
 of soft overlapping blobs in four colours plus pixel noise; Color, 5 colours, Noise 1 and 2, Paths
 0, 50 and 100; five sample points per pixel must each lie in some path). Without the condition 93
 sample points were uncovered (seeds 9, 11 and 13); with it none are. The crate's other tests pass
-unchanged.
-
 ## Same sub-pixel shift from either side of an edge
 Each crack between two regions is moved by a sub-pixel shift read from the image. The reading
 looked for a thin run (one to three pixels) on the crack's inside before one on its outside, so where
@@ -1058,6 +1074,7 @@ One trace at a time on this machine (all cores); memory is the peak allocated ab
 
 | date | change |
 |:--|:--|
+| 2026-10-16 | Image Trace: a loop or junction-returning piece whose fit collapsed to one cubic keeps the fewest segments that hold its area and course instead of every positioned point, so a higher Paths no longer gives fewer segments on code-drawn noisy images (six falling runs to none; one other cause remains). |
 | 2026-10-16 | Image Trace: a notch corner is cut only when the straight edges beside it lie in the shared piece, so both regions of the piece get the same points (code-drawn noisy colour images: 93 uncovered sample points to 0). |
 | 2026-10-16 | Image Trace: a crack's sub-pixel shift is the mean of the readings from its two sides, exactly antisymmetric, so abutting regions get the same points on thin slivers (a code-drawn noisy ripple went from 482–1,228 uncovered sample points per trace to 0). |
 | 2026-10-16 | Image Trace: the contour walk works out each turn from the pixels as it goes instead of following a precomputed table of per-corner directions; identical loops on all 65,536 4 × 4 masks and 400 seeded masks, and no slower (whole 1 MP traces 1–5% faster). |