diff --git a/crates/engine/src/cmd/buildcmds.rs b/crates/engine/src/cmd/buildcmds.rs index 98aa9ae490..907f4ef513 100644 --- a/crates/engine/src/cmd/buildcmds.rs +++ b/crates/engine/src/cmd/buildcmds.rs @@ -144,7 +144,7 @@ pub fn specs() -> Vec { "Make", ["Object", "Image Trace"], None, - "{id?: image or Image Trace group (default: selection), preset?: name (imageTrace.presets), savedPreset?: {settings} (a saved preset's settings, which the journal records so a replay traces with them after the preset is changed, renamed or deleted; used in place of the saved preset `preset` names), enhanced?: false (the preset's enhanced version: with Auto Grouping, and with Shapes in all but High Fidelity Photo; Flat Logo has none and is traced as it is), params?: {mode: \"blackAndWhite\"|\"grayscale\"|\"color\"|\"logo\", threshold: 0-255, palette: \"limited\"|\"fullTone\"|\"automatic\"|\"documentLibrary\" (color mode; limited: the `colors` best colours, fullTone: as many as the tones need, more with colorDetail, automatic: flat art with its own colours, else fullTone, documentLibrary: at most `colors` of the library's colours, as they are), colors: 2-256, colorDetail: 0-100 (fullTone, automatic), library: \"document\" (the document's swatches) or a swatch library id or name (swatch.library.list; documentLibrary), colorGroup?: name (color mode, documentLibrary with library \"document\": the colors of that document color group instead of every swatch; \"\" is every swatch), paths: 0-100, corners: 0-100, noise: px (an area smaller than this joins the color it shares the longest border with; when that color is far from its own and the area is 2 px or more, or a single pixel whose longest border is not tied between colors, it joins the neighboring color nearest its pixels among those sharing at least a tenth of that border), method: \"abutting\"|\"overlapping\" (abutting with fills, not mode logo: a \"Seam Fills\" clip group under the paths holds strokes along the edges two filled paths share, 1.5 image pixels wide (VectorCraft's own width), in the color of the lower path (on an image stretched more one way than another, each stroke's outline in image pixels as a filled path), clipped to the image's box within the traced paths' box; paths that became live shapes get none; the paths are not changed), ignoreWhite (leave out white areas), ignoreColor?: \"#rrggbb\" (with ignoreWhite: the colour left out instead of white), ignoreBackground: false (with ignoreWhite: only the areas of the ignored color that reach the image's edge are left out), keepColors?: [\"#rrggbb\"…] (not mode logo: only the palette colors within about 30 levels of a listed color are traced; empty: every color), snapCurvesToLines, shapes: false (filled outlines that are a circle, an ellipse, a rectangle or a regular polygon come out as that live shape), autoGrouping: false (each path that has others inside it is grouped with them), gradients: false (grayscale and color: an area whose colour changes evenly along one direction is one path with a linear gradient fill), fills: true, strokes: false (Create: lines up to strokeWidth wide become stroked centre lines; without fills, wider areas become stroked outlines), strokeWidth: px (10), logoColors?: [\"#rrggbb\"…] (mode logo: flat-colour logos only; colours found automatically or named here, at most ten; white is its own color, and a named color with every channel 245 or more is taken as that white, except with logoColors named, logoWhite false and no ignoreWhite; noise = areas under noise/10 px ignored; edges to a fraction of a pixel, sharp corners restored, lines and circles snapped; enclosed transparent areas are painted white while white is its own color, and stay holes with ignoreWhite or without a white of its own; fills/strokes are ignored; gradients and photos are refused, judged by the image's own colors also when logoColors are named), logoWhite: true (mode logo with logoColors named; false traces the named colors only: white areas take the nearest of them, a named white is kept and enclosed transparent areas stay holes; with ignoreWhite, white areas are left out either way)}, view?: as imageTrace.setView (default: the traced object's own, else tracingResult), ids?: [id…] (instead of id)} → {id, paths, anchors, colors, warnings: [text…] (the image is over 1500 px on a side, so it traces more slowly; or it was traced scaled down; Flat Logo names only the size it traced a larger image at; or a keepColors color matches none the trace found, or nothing was traced)}", + "{id?: image or Image Trace group (default: selection), preset?: name (imageTrace.presets), savedPreset?: {settings} (a saved preset's settings, which the journal records so a replay traces with them after the preset is changed, renamed or deleted; used in place of the saved preset `preset` names), enhanced?: false (the preset's enhanced version: with Auto Grouping, and with Shapes in all but High Fidelity Photo; Flat Logo has none and is traced as it is), params?: {mode: \"blackAndWhite\"|\"grayscale\"|\"color\"|\"logo\", threshold: 0-255, palette: \"limited\"|\"fullTone\"|\"automatic\"|\"documentLibrary\" (color mode; limited: the `colors` best colours, fullTone: as many as the tones need, more with colorDetail, split into at least colorDetail colors where the image has that many before colors that look alike merge (less than 5 apart in Oklab × 100 and thoroughly mixed, or less than 1.5 and mixed in patches), automatic: flat art with its own colours, else as many as the tones need without fullTone's least count, merging close RGB colors, documentLibrary: at most `colors` of the library's colours, as they are), colors: 2-256, colorDetail: 0-100 (fullTone, automatic), library: \"document\" (the document's swatches) or a swatch library id or name (swatch.library.list; documentLibrary), colorGroup?: name (color mode, documentLibrary with library \"document\": the colors of that document color group instead of every swatch; \"\" is every swatch), paths: 0-100, corners: 0-100, noise: px (an area smaller than this joins the color it shares the longest border with; when that color is far from its own and the area is 2 px or more, or a single pixel whose longest border is not tied between colors, it joins the neighboring color nearest its pixels among those sharing at least a tenth of that border), method: \"abutting\"|\"overlapping\" (abutting with fills, not mode logo: a \"Seam Fills\" clip group under the paths holds strokes along the edges two filled paths share, 1.5 image pixels wide (VectorCraft's own width), in the color of the lower path (on an image stretched more one way than another, each stroke's outline in image pixels as a filled path), clipped to the image's box within the traced paths' box; paths that became live shapes get none; the paths are not changed), ignoreWhite (leave out white areas), ignoreColor?: \"#rrggbb\" (with ignoreWhite: the colour left out instead of white), ignoreBackground: false (with ignoreWhite: only the areas of the ignored color that reach the image's edge are left out), keepColors?: [\"#rrggbb\"…] (not mode logo: only the palette colors within about 30 levels of a listed color are traced; empty: every color), snapCurvesToLines, shapes: false (filled outlines that are a circle, an ellipse, a rectangle or a regular polygon come out as that live shape), autoGrouping: false (each path that has others inside it is grouped with them), gradients: false (grayscale and color: an area whose colour changes evenly along one direction is one path with a linear gradient fill), fills: true, strokes: false (Create: lines up to strokeWidth wide become stroked centre lines; without fills, wider areas become stroked outlines), strokeWidth: px (10), logoColors?: [\"#rrggbb\"…] (mode logo: flat-colour logos only; colours found automatically or named here, at most ten; white is its own color, and a named color with every channel 245 or more is taken as that white, except with logoColors named, logoWhite false and no ignoreWhite; noise = areas under noise/10 px ignored; edges to a fraction of a pixel, sharp corners restored, lines and circles snapped; enclosed transparent areas are painted white while white is its own color, and stay holes with ignoreWhite or without a white of its own; fills/strokes are ignored; gradients and photos are refused, judged by the image's own colors also when logoColors are named), logoWhite: true (mode logo with logoColors named; false traces the named colors only: white areas take the nearest of them, a named white is kept and enclosed transparent areas stay holes; with ignoreWhite, white areas are left out either way)}, view?: as imageTrace.setView (default: the traced object's own, else tracingResult), ids?: [id…] (instead of id)} → {id, paths, anchors, colors, warnings: [text…] (the image is over 1500 px on a side, so it traces more slowly; or it was traced scaled down; Flat Logo names only the size it traced a larger image at; or a keepColors color matches none the trace found, or nothing was traced)}", has_selection_or_ids, |s, p| trace_make(s, p, false) ), diff --git a/crates/trace/src/params.rs b/crates/trace/src/params.rs index 7b850fc344..1fa8aaa2c3 100644 --- a/crates/trace/src/params.rs +++ b/crates/trace/src/params.rs @@ -38,11 +38,12 @@ pub enum Palette { #[serde(alias = "Limited")] Limited, /// As many colours as the image's tones need, up to [`FULL_TONE_MAX`] (photos, gradients): - /// `color_detail` sets how close two colours may be and stay apart. + /// `color_detail` sets how close two colours may be and stay apart. Before merging colors that + /// look alike, it splits to at least one color per step of `color_detail` where the image has that many. #[serde(alias = "Full Tone")] FullTone, /// Flat art (a few colours cover nearly all of it) traces with exactly those colours, anything - /// else as Full Tone. + /// else with as many as its tones need, without Full Tone's least count and merging close RGB colors. #[serde(alias = "Automatic")] Automatic, /// The most used colours of a swatch library ([`TraceParams::swatches`]), at most `colors` of @@ -243,7 +244,10 @@ pub fn preset(name: &str) -> Option { // many as its tones need where it is not. // (Color detail 85: a colour on a hundredth of the picture is still one of its colours.) "auto color" => TraceParams { palette: Palette::Automatic, color_detail: 85.0, ..color(6, 65.0, 60.0, 16, Method::Abutting) }, - "high fidelity photo" => color(64, 50.0, 50.0, 5, Method::Overlapping), + // A photo's tones: as many colors as they need (Full Tone), split until no color spans more + // than about 21 levels of a channel and into at least 85 (Color detail 85) before colors that + // look alike merge, as abutting shapes. VectorCraft's own values. + "high fidelity photo" => TraceParams { palette: Palette::FullTone, color_detail: 85.0, ..color(64, 50.0, 50.0, 5, Method::Abutting) }, "low fidelity photo" => color(20, 50.0, 50.0, 10, Method::Overlapping), "3 colors" => color(3, 50.0, 50.0, 15, Method::Abutting), "6 colors" => color(6, 50.0, 50.0, 8, Method::Abutting), diff --git a/crates/trace/src/quantize.rs b/crates/trace/src/quantize.rs index ea8fa00ac8..2a0deeb013 100644 --- a/crates/trace/src/quantize.rs +++ b/crates/trace/src/quantize.rs @@ -93,7 +93,7 @@ pub(crate) fn quantize_keeping(img: &Raster, params: &TraceParams) -> (Quantized let g = l.round().clamp(0.0, 255.0) as u8; [g, g, g] }); - let q = merge_mixed(compact(labels, palette.collect()), img.width as usize, img.height as usize, &[]); + let q = merge_mixed(compact(labels, palette.collect()), img.width as usize, img.height as usize, &[], Alike::Rgb); (if settles_wide(params) { settled_wide(q, img, &own, true) } else { settled(q, img, &own) }, vec![]) } // Logo mode traces without quantising; asked directly, it quantises like Color. @@ -175,12 +175,14 @@ pub(crate) fn quantize_keeping(img: &Raster, params: &TraceParams) -> (Quantized img.rgba.as_chunks::<4>().0.iter().map(|p| if p[3] < 128 { TRANSPARENT } else { lut[hk.key(p[0], p[1], p[2])] }).collect(); let palette = centers.iter().map(|c| [c[0].round() as u8, c[1].round() as u8, c[2].round() as u8]).collect(); let q = compact(labels, palette); - // A swatch library's colours are used as they are. + // A swatch library's colours are used as they are. Full Tone's colors merge only when + // they look alike (see `Alike`). if library { return (q, false); } + let alike = if params.palette == Palette::FullTone { Alike::Seen } else { Alike::Rgb }; let before = q.palette.len(); - let q = merge_mixed(q, img.width as usize, img.height as usize, &rare); + let q = merge_mixed(q, img.width as usize, img.height as usize, &rare, alike); let merged = q.palette.len() < before; (q, merged) }; @@ -309,6 +311,27 @@ pub(crate) fn tests_oklab(c: [u8; 3]) -> [f64; 3] { oklab(c.map(f64::from)) } +/// Which colors [`merge_mixed`] takes for one color that noise split. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +enum Alike { + /// Close in RGB: under 30 levels apart and thoroughly mixed, or under 12 and mixed in patches. + /// A limited palette's colors are few and far apart, so two this close are one color. + Rgb, + /// Close to the eye: under [`FULL_TONE_ALIKE`] apart in Oklab and thoroughly mixed, or under + /// [`FULL_TONE_PATCHES`] and mixed in patches (compression blocks). Full Tone's neighboring tones + /// of a smooth photo are about as close in RGB as noise makes one color, and mixed along their + /// soft border, so the RGB test would take most of them for one color. + Seen, +} + +/// How far apart (Oklab × 100) two thoroughly mixed Full Tone colors may lie and still be merged +/// as one color that noise split: a little more than the least difference one sees (see [`oklab`]). +const FULL_TONE_ALIKE: f64 = 5.0; + +/// How far apart (Oklab × 100) two Full Tone colors mixed in patches may lie and still be merged: +/// the blocks of one flat color that compression shifted by a few levels each. +const FULL_TONE_PATCHES: f64 = 1.5; + /// `q` with the colours that noise made of one colour merged, largest mix first. /// /// Asked for more colours than a picture has, k-means splits a flat colour along its noise, and @@ -317,8 +340,9 @@ pub(crate) fn tests_oklab(c: [u8; 3]) -> [f64; 3] { /// taken in RGB) and thoroughly mixed: the pixels of the lesser one have, on average, more than /// half a neighbour of the other each; or they are closer still (under 12 levels) and mixed in /// patches (compression blocks). The bands of a gradient are close too, but each keeps to itself -/// and they stay apart. The colours in `keep` merge with none. -fn merge_mixed(q: Quantized, w: usize, h: usize, keep: &[[u8; 3]]) -> Quantized { +/// and they stay apart. The colours in `keep` merge with none. With [`Alike::Seen`], the distances are +/// taken in Oklab (see [`FULL_TONE_ALIKE`] and [`FULL_TONE_PATCHES`]). +fn merge_mixed(q: Quantized, w: usize, h: usize, keep: &[[u8; 3]], alike: Alike) -> Quantized { let k = q.palette.len(); // A rare colour kept on purpose (see `rare_colours`) is distinct by choice: it merges with none. let kept: Vec = q.palette.iter().map(|c| keep.contains(c)).collect(); @@ -350,8 +374,18 @@ fn merge_mixed(q: Quantized, w: usize, h: usize, keep: &[[u8; 3]]) -> Quantized continue; } let mixed = touch[a * k + b] / count[a].min(count[b]); - let apart = (0..3).map(|c| (color[a][c] - color[b][c]).powi(2)).sum::().sqrt(); - if (mixed > 0.5 && apart < 30.0 || mixed > 0.15 && apart < 12.0) && best.is_none_or(|x| mixed > x.0) { + let merges = match alike { + Alike::Rgb => { + let apart = (0..3).map(|c| (color[a][c] - color[b][c]).powi(2)).sum::().sqrt(); + mixed > 0.5 && apart < 30.0 || mixed > 0.15 && apart < 12.0 + } + Alike::Seen => { + let (la, lb) = (oklab(color[a]), oklab(color[b])); + let apart = (0..3).map(|c| (la[c] - lb[c]).powi(2)).sum::().sqrt(); + mixed > 0.5 && apart < FULL_TONE_ALIKE || mixed > 0.15 && apart < FULL_TONE_PATCHES + } + }; + if merges && best.is_none_or(|x| mixed > x.0) { best = Some((mixed, a, b)); } } @@ -410,6 +444,33 @@ mod tests { assert!(own.iter().all(|o| *o == own[0])); } + #[test] + fn full_tone_merges_only_mixed_colors_that_look_alike() { + // Two colors in a checkerboard: every pixel has four neighbors of the other color. + let mixed = + |a: [u8; 3], b: [u8; 3]| Quantized { labels: (0..16 * 16).map(|i| ((i % 16 + i / 16) % 2) as u16).collect(), palette: vec![a, b] }; + let colors = |q: Quantized, alike: Alike| merge_mixed(q, 16, 16, &[], alike).palette.len(); + // Gray and a greener gray, 22 levels apart (about 6.4 in Oklab): one color in RGB, two that look different. + let (gray, green) = ([128, 128, 128], [128, 150, 128]); + assert_eq!(colors(mixed(gray, green), Alike::Rgb), 1); + assert_eq!(colors(mixed(gray, green), Alike::Seen), 2); + // Two grays 3 levels apart (about 1 in Oklab): one color either way. + assert_eq!(colors(mixed(gray, [131; 3]), Alike::Rgb), 1); + assert_eq!(colors(mixed(gray, [131; 3]), Alike::Seen), 1); + // Side by side, not mixed: two colors either way. + let halves = Quantized { labels: (0..16 * 16).map(|i| u16::from(i % 16 >= 8)).collect(), palette: vec![[128; 3], [131; 3]] }; + assert_eq!(colors(halves.clone(), Alike::Rgb), 2); + assert_eq!(colors(halves, Alike::Seen), 2); + // In 8 × 8 blocks, mixed in patches: grays 3 levels apart merge either way; grays 6 levels + // apart (about 10 in RGB, more than 1.5 in Oklab) merge only in RGB. + let blocks = + |b: [u8; 3]| Quantized { labels: (0..16 * 16).map(|i| ((i % 16 / 8 + i / 16 / 8) % 2) as u16).collect(), palette: vec![gray, b] }; + assert_eq!(colors(blocks([131; 3]), Alike::Rgb), 1); + assert_eq!(colors(blocks([131; 3]), Alike::Seen), 1); + assert_eq!(colors(blocks([134; 3]), Alike::Rgb), 1); + assert_eq!(colors(blocks([134; 3]), Alike::Seen), 2); + } + #[test] fn a_picture_with_no_pixels_is_not_shared_out() { // No band for each of the rows of a picture with no columns, however many rows it has. diff --git a/crates/trace/src/quantize/palette.rs b/crates/trace/src/quantize/palette.rs index 43a1954cd7..828217ca55 100644 --- a/crates/trace/src/quantize/palette.rs +++ b/crates/trace/src/quantize/palette.rs @@ -138,6 +138,12 @@ pub(super) fn labs(colors: &[[f64; 3]]) -> Vec<[f64; 3]> { /// The most colours Full Tone (and Automatic on continuous-tone images) makes. pub const FULL_TONE_MAX: usize = 256; +/// The fewest colors Palette › Full Tone splits into, before merging, at Color detail `detail` +/// (0–1): one per step of Color detail, 85 at 85. Automatic does not use it. +pub(super) fn full_tone_least(detail: f64) -> usize { + (detail.clamp(0.0, 1.0) * 100.0).round() as usize +} + /// A histogram bin in use: its index, mean colour and pixel count. pub(super) type Used = (usize, [f64; 3], f64); @@ -152,11 +158,14 @@ pub(super) fn color_palette(used: &[Used], params: &TraceParams) -> Vec<[f64; 3] // Full Tone: split until no colour box is wider than 96 (few colours) … 8 (many) levels per // channel, which is one histogram bin. let full_tone = || refine(used, centers(&median_cut(used, FULL_TONE_MAX, 96.0 - 88.0 * detail))); + // Palette › Full Tone also splits into at least one color per step of Color detail, where the + // picture has that many (see [`full_tone_least`]). + let full_tone_palette = || refine(used, centers(&median_cut_least(used, FULL_TONE_MAX, 96.0 - 88.0 * detail, full_tone_least(detail)))); // A Limited palette of 9 to 16 colors keeps a nearly flat dark ground in one color (see [`kmeans_rgb`]). let limited = || kmeans_rgb(used, k, if FEW_COLORS.contains(&k) { LEAST_APART } else { 0.0 }); match params.palette { Palette::Limited => limited(), - Palette::FullTone => full_tone(), + Palette::FullTone => full_tone_palette(), Palette::Automatic => match flat_colors(used, detail) { Some(n) => flat_palette(used, n), None => full_tone(), @@ -285,7 +294,7 @@ const GRAY: f64 = 3.0; /// (see [`median_cut_apart`]). A large, nearly flat dark ground then keeps one color, and the /// color it would have taken goes to another cut. fn kmeans_rgb(used: &[Used], k: usize, apart: f64) -> Vec<[f64; 3]> { - refine(used, centers(&median_cut_apart(used, k, 0.0, apart))) + refine(used, centers(&median_cut_apart(used, k, 0.0, apart, 0))) } /// Divisive clustering in the manner of median cut, but each box is cut where that leaves its two @@ -295,21 +304,32 @@ fn kmeans_rgb(used: &[Used], k: usize, apart: f64) -> Vec<[f64; 3]> { /// and leaves two smaller colours in one box. Boxes are cut while there are fewer than `k` and /// some box spans more than `spread` levels of a channel. pub(super) fn median_cut(used: &[Used], k: usize, spread: f64) -> Vec { - median_cut_apart(used, k, spread, 0.0) + median_cut_apart(used, k, spread, 0.0, 0) } -/// [`median_cut`], except when both sides of a cut have a dark gray mean color (see [`DARK`] and -/// [`GRAY`]) and the two means lie `d` (Oklab × 100) apart with `d` < `apart`: then the cut's gain -/// is scaled by (`d` / `apart`)². With `apart` 0 it is [`median_cut`]. -fn median_cut_apart(used: &[Used], k: usize, spread: f64, apart: f64) -> Vec { +/// [`median_cut`], then, while there are fewer than `least` boxes, cutting the boxes no wider than +/// `spread` too, the one whose cut gains most first. +fn median_cut_least(used: &[Used], k: usize, spread: f64, least: usize) -> Vec { + median_cut_apart(used, k, spread, 0.0, least) +} + +/// [`median_cut`] with at least `least` boxes where the bins allow (see [`median_cut_least`]), +/// except when both sides of a cut have a dark gray mean color (see [`DARK`] and [`GRAY`]) and the +/// two means lie `d` (Oklab × 100) apart with `d` < `apart`: then the cut's gain is scaled by +/// (`d` / `apart`)². With `apart` 0 and `least` 0 it is [`median_cut`]. +fn median_cut_apart(used: &[Used], k: usize, spread: f64, apart: f64, least: usize) -> Vec { if used.is_empty() { return vec![ColorBox { mean: [255.0; 3], weight: 0.0, peak: 0.0 }]; } - /// A box's bins and its best cut: (gain, bins sorted along the cut's channel, bins on the first side). + /// A box's bins, its widest span over the channels, and its best cut: (gain, bins sorted along + /// the cut's channel, bins on the first side). struct Cut { bins: Vec, + widest: f64, best: Option<(f64, Vec, usize)>, } + // Boxes no wider than this are never cut. + let narrowest = if least > 0 { 0.0 } else { spread.max(0.0) }; // How much of a cut's gain counts when its sides' mean colors are `a` and `b`: all of it when // they look different or either is not a dark gray, less as two dark grays look more alike. let dark_gray = |c: [f64; 3]| c[0] < DARK && c[1].hypot(c[2]) < GRAY; @@ -328,7 +348,7 @@ fn median_cut_apart(used: &[Used], k: usize, spread: f64, apart: f64) -> Vec= 2 && widest > spread.max(0.0) { + if bins.len() >= 2 && widest > narrowest { for ch in 0..3 { let mut sorted = bins.clone(); sorted.sort_by(|x, y| used[*x].1[ch].total_cmp(&used[*y].1[ch])); @@ -366,12 +386,19 @@ fn median_cut_apart(used: &[Used], k: usize, spread: f64, apart: f64) -> Vec spread.max(0.0))) + .max_by(|&a, &b| gain(&boxes[a]).total_cmp(&gain(&boxes[b]))) + }; + let Some(bi) = most(true).or_else(|| if boxes.len() < least { most(false) } else { None }) else { break; }; let Some((_, mut sorted, at)) = boxes.swap_remove(bi).best else { break }; @@ -467,7 +494,9 @@ mod tests { assert_eq!(palette(Palette::DocumentLibrary, colors), plain(colors as usize), "{colors} colors"); } let detail = (TraceParams::default().color_detail / 100.0).clamp(0.0, 1.0); - assert_eq!(palette(Palette::FullTone, 16), refine(&used, centers(&median_cut(&used, FULL_TONE_MAX, 96.0 - 88.0 * detail)))); + // Full Tone's median cut makes at least one color per step of Color detail. + let full_tone = refine(&used, centers(&median_cut_least(&used, FULL_TONE_MAX, 96.0 - 88.0 * detail, full_tone_least(detail)))); + assert_eq!(palette(Palette::FullTone, 16), full_tone); let automatic = match flat_colors(&used, detail) { Some(n) => plain(n), None => refine(&used, centers(&median_cut(&used, FULL_TONE_MAX, 96.0 - 88.0 * detail))), @@ -475,6 +504,32 @@ mod tests { assert_eq!(palette(Palette::Automatic, 16), automatic); } + #[test] + fn full_tone_makes_one_color_per_step_of_color_detail() { + // 256 grays, 1,200 pixels each: the width limit alone gives fewer colors than Color detail. + let ramp = bins((0..256).map(|g| ([f64::from(g); 3], 1200.0))); + let colors = |used: &[Used], color_detail: f64| { + color_palette(used, &TraceParams { palette: Palette::FullTone, color_detail, ..TraceParams::default() }).len() + }; + assert!(median_cut(&ramp, FULL_TONE_MAX, 96.0 - 88.0 * 0.85).len() < 85); + assert_eq!(colors(&ramp, 85.0), 85); + assert_eq!(colors(&ramp, 40.0), 40); + // A picture of three colors keeps three. + let three = bins([([0.0; 3], 100.0), ([128.0; 3], 100.0), ([255.0; 3], 100.0)]); + assert_eq!(colors(&three, 85.0), 3); + // A large, finely shaded area does not take the count from a small pair of reds 40 levels + // apart, wider than one color may be at Color detail 85: the pair keeps two colors. + let shaded = bins((0..128).map(|g| ([f64::from(g); 3], 10_000.0)).chain([([200.0, 0.0, 0.0], 1.0), ([240.0, 0.0, 0.0], 1.0)])); + let reds = color_palette(&shaded, &TraceParams { palette: Palette::FullTone, color_detail: 85.0, ..TraceParams::default() }); + assert!(reds.len() >= 85, "{} colors", reds.len()); + for red in [200.0, 240.0] { + assert!(reds.iter().any(|c| (c[0] - red).abs() < 1.0 && c[1] < 1.0), "no color for red {red}: {reds:?}"); + } + // Automatic's continuous-tone colors are not raised to the count. + let automatic = color_palette(&ramp, &TraceParams { palette: Palette::Automatic, color_detail: 85.0, ..TraceParams::default() }); + assert!(automatic.len() < 85, "{} colors with Automatic", automatic.len()); + } + /// `colors`, each with `n` pixels, as histogram bins. fn bins(colors: impl IntoIterator) -> Vec { colors.into_iter().enumerate().map(|(i, (c, n))| (i, c, n)).collect() diff --git a/crates/trace/src/tests.rs b/crates/trace/src/tests.rs index 7e037c8b70..1cc61e2bdf 100644 --- a/crates/trace/src/tests.rs +++ b/crates/trace/src/tests.rs @@ -944,6 +944,16 @@ fn presets_have_their_paths_corners_and_noise() { assert_eq!(colors, [64, 20, 3, 6, 16, 8]); } +#[test] +fn high_fidelity_photo_traces_in_full_tone() { + // As many colors as the tones need, split until no color spans more than about 21 levels, as + // abutting shapes. + let p = preset("High Fidelity Photo").unwrap(); + assert_eq!((p.palette, p.color_detail, p.method), (Palette::FullTone, 85.0, Method::Abutting)); + // Low Fidelity Photo keeps its 20 colors. + assert_eq!(preset("Low Fidelity Photo").unwrap().palette, Palette::Limited); +} + #[test] fn params_json_roundtrip_and_partial() { let p = preset("6 Colors").unwrap(); @@ -1213,12 +1223,14 @@ fn full_tone_follows_the_tones_the_image_has() { } #[test] -fn automatic_traces_flat_art_with_its_colours_and_photos_in_full_tone() { +fn automatic_traces_flat_art_with_its_colours_and_photos_in_continuous_tone() { let flat = palette(&flat_quads(), Palette::Automatic, 2, 50.0); assert_eq!(flat.len(), 4, "the four flat colours, whatever `colors` says: {flat:?}"); assert!(flat.iter().any(|c| c[0] > 200 && c[1] < 60 && c[2] < 60), "red is one of them: {flat:?}"); let tone = palette(&gradient(), Palette::Automatic, 2, 50.0); - assert_eq!(tone.len(), palette(&gradient(), Palette::FullTone, 2, 50.0).len(), "continuous tone: as Full Tone"); + // Continuous tone: as many colors as the tones need, without Full Tone's least count. + let full = palette(&gradient(), Palette::FullTone, 2, 50.0); + assert!(tone.len() > 4 && tone.len() <= full.len(), "{} colors, {} in Full Tone", tone.len(), full.len()); } #[test] @@ -1713,6 +1725,39 @@ fn jitter(x: u32, y: u32, salt: u32) -> f64 { f64::from(v & 0xFFFF) / 32768.0 - 1.0 } +#[test] +fn full_tone_keeps_a_noisy_ramps_neighboring_tones() { + // Gray to green with grain: Full Tone's neighboring tones are close in RGB and mixed along + // their borders, and still look different. + let img = Raster::from_fn(256, 96, |x, y| { + let v = |k: u32, base: f64, slope: f64| (base + slope * f64::from(x) + 8.0 * jitter(x, y, k)).round().clamp(0.0, 255.0) as u8; + [v(0, 100.0, 0.0), v(1, 40.0, 0.7), v(2, 100.0, 0.0), 255] + }); + let params = TraceParams { mode: Mode::Color, palette: Palette::FullTone, color_detail: 85.0, ..TraceParams::default() }; + // Median cut gives at least 85 (one per step of Color detail); merged where they look alike, 6 + // are left, and merged as close RGB colors, 5 would be. + let n = quantize(&img, ¶ms).palette.len(); + assert!(n >= 6, "{n} tones"); + // Automatic traces continuous tone without Full Tone's least count and keeps merging close RGB colors. + let automatic = quantize(&img, &TraceParams { palette: Palette::Automatic, ..params }).palette.len(); + assert!(automatic < n, "{automatic} tones with Automatic, {n} with Full Tone"); +} + +#[test] +fn full_tone_merges_a_flat_colors_compression_blocks() { + // Three flat colors stored in 8 × 8 blocks, each block off by up to 8 levels a channel, with a + // little grain: the blocks of one color look alike and are mixed in patches, so each flat + // color traces as one shape in Full Tone too, not as squares of near colors. + let bases = [[200.0, 150.0, 120.0], [70.0, 120.0, 190.0], [40.0, 90.0, 40.0]]; + let img = Raster::from_fn(192, 128, |x, y| { + let base: [f64; 3] = bases[(x / 64) as usize]; + let c = |k: u32| (base[k as usize] + 8.0 * jitter(x / 8, y / 8, k) + 1.5 * jitter(x, y, k + 7)).round().clamp(0.0, 255.0) as u8; + [c(0), c(1), c(2), 255] + }); + let res = trace(&img, &preset("High Fidelity Photo").unwrap()); + assert_eq!((res.palette.len(), res.paths.len()), (3, 3), "{:?}", res.palette); +} + /// Three flat colours (a navy field, a yellow disc, a green bar) drawn anti-aliased, with `noise` /// levels of noise per channel. fn three_colour_art(noise: f64) -> Raster { @@ -2013,7 +2058,7 @@ fn a_nearly_flat_dark_ground_keeps_one_color() { #[test] fn a_noisy_gradient_keeps_its_tones_without_specks() { - // Tones 0–255 across with noise larger than High Fidelity Photo's 64 steps are apart. + // Tones 0–255 across with up to 5 levels of noise a channel. let img = Raster::from_fn(256, 96, |x, y| { let c = |k: u32| (f64::from(x) + 5.0 * jitter(x, y, k)).round().clamp(0.0, 255.0) as u8; [c(0), c(1), c(2), 255] diff --git a/docs/image-trace-adjustments.md b/docs/image-trace-adjustments.md index 2bd58e4df4..92cd467cab 100644 --- a/docs/image-trace-adjustments.md +++ b/docs/image-trace-adjustments.md @@ -23,7 +23,9 @@ versions. Among those presets, Corners is 100 in Technical Drawing, 75 in Defaul Logo, Line Art and Outline, and 50 in the other eight. Noise is 1 px in Technical Drawing, 5 in High Fidelity Photo and Black and White Logo, 8 in 6 Colors and 16 Colors, 10 in Low Fidelity Photo, 15 in 3 Colors and Shades of Gray, 20 in Sketched Art, Line Art and Outline, 25 in Default, and 90 in Silhouettes (see -[image-trace-quality.md](image-trace-quality.md#preset-paths-corners-and-noise)). +[image-trace-quality.md](image-trace-quality.md#preset-paths-corners-and-noise)). High Fidelity Photo +traces with Palette › Full Tone at Color detail 85 and Method › Abutting (VectorCraft's own values); Low +Fidelity Photo traces with a Limited palette of 20 colors, Overlapping. Sliders apply on release, and their numeric fields can be edited directly. Each committed adjustment re-traces the selected object as one undo step and changes the preset to Custom. @@ -83,8 +85,8 @@ leaves out every white area whatever `ignoreBackground` is. color nearest to it in lightness and hue, with a difference in hue or chroma counted three times as much as one in lightness, so a gray or a muted brown takes a black, white or other neutral library color rather than a saturated color of the same lightness. -**Abutting and Overlapping.** Abutting is the default Method, and the Default, Auto Color, 3 Colors, -6 Colors and 16 Colors presets use it. With Abutting, two neighboring colors share one exact edge. The +**Abutting and Overlapping.** Abutting is the default Method, and the Default, Auto Color, High Fidelity +Photo, 3 Colors, 6 Colors and 16 Colors presets use it. With Abutting, two neighboring colors share one exact edge. The canvas smooths the edges of each path on its own, so each of the two paths covers only part of the pixels along that edge, and a thin line of the background can show between the colors. Web browsers and PDF viewers usually draw an exported SVG or PDF file the same way and show the same line. Raster diff --git a/docs/image-trace-quality.md b/docs/image-trace-quality.md index b111a25fb7..7977d5b919 100644 --- a/docs/image-trace-quality.md +++ b/docs/image-trace-quality.md @@ -83,7 +83,7 @@ gradient, texture, sensor noise): Photo trace was 86,000 anchors under the old limit; a noisier scan of the same size would have been refused. At 8,000,000 anchors a trace keeps about 0.7 GB, with a peak of about 0.9 GB while tracing. The preset rows were measured with the earlier preset values: High Fidelity Photo at Paths 90, Corners 25 -and Noise 4, Low Fidelity Photo at Paths 60, Noise 12 and 16 Colors at Paths 70, Corners 55 and Noise 10 +and Noise 4 with a Limited palette of 64 colors and Overlapping, Low Fidelity Photo at Paths 60, Noise 12 and 16 Colors at Paths 70, Corners 55 and Noise 10 (see [Preset Paths, Corners and Noise](#preset-paths-corners-and-noise)). ## Collapsed loops keep few segments A small closed loop (or a piece that returns to its own junction) whose fit collapsed to a single @@ -252,6 +252,35 @@ versions of these presets use the same Paths, Corners and Noise. 6 Colors and 16 and Black and White Logo at 25 until [Noise joins the nearest color](#noise-joins-the-nearest-color); the measurements below were made at those values. +High Fidelity Photo later moved to Palette › Full Tone at Color detail 85 and Method › Abutting (it was a +Limited palette of 64 colors, Overlapping); Paths, Corners and Noise stay 50, 50 and 5. These are +VectorCraft's own values. Palette › Full Tone splits its colors until none spans more than its width +limit, then, while it has fewer colors than Color detail's value (85 at 85), splits the narrower ones +too, where the image has that many colors; the colors that look alike then merge, so a trace can end +with fewer. Automatic's continuous-tone colors do not take that count. Full Tone's colors merge as one +color when they are thoroughly mixed and less than 5 apart in Oklab × 100, or mixed in patches +(compression blocks) and less than 1.5 apart; the other palettes, Automatic included, keep the RGB test +(under 30 levels and thoroughly mixed, or under 12 and mixed in patches). These rules apply to every +trace with Palette › Full Tone, so an existing Full Tone trace or saved preset traces differently when +it is traced again. + +On 19 photos, cartoons and synthetic shapes of 400 to 4,000 px, the mean pixel difference summed over the +inputs fell from 80.5 to 65.6 levels. It fell by more than 1% on 14 inputs (2.88 to 2.19 and 2.59 to 2.48 +on two photos, the second a JPEG at quality 40; 1.88 to 1.45 on a 4000 × 3000 photo; 12.40 to 7.44 on an +upscaled cartoon) and changed by less than 1% on the other 5. Anchors rose 1.66 times (1.98 million to +3.29 million), the SVG size 1.31 times, and the trace time 1.9 times (14.1 to 27.1 s for all 19, 3 at a +time). Flat synthetic art costs the most: 12 to 400 anchors on a 4000 × 3000 image of two flat colors, and +about 3 times the anchors on two images of synthetic shapes (400 × 300 and 1600 × 1200), with the same +pixel difference. Peak memory fell on every input in the same pass: +942 to 626 MiB on a 1536 × 2048 cartoon. Low Fidelity Photo, 16 Colors, 6 Colors, Black and White Logo +and Auto Color give byte-identical SVGs. On three flat colors stored in 8 × 8 blocks, each block off by +up to 8 levels a channel, High Fidelity Photo traces 3 colors as 3 paths; without the patch rule it traced +7 colors as 74 paths. Tests: `high_fidelity_photo_traces_in_full_tone`, +`full_tone_keeps_a_noisy_ramps_neighboring_tones` and `full_tone_merges_a_flat_colors_compression_blocks` +in `crates/trace/src/tests.rs`, `full_tone_merges_only_mixed_colors_that_look_alike` in +`crates/trace/src/quantize.rs`, and `full_tone_makes_one_color_per_step_of_color_detail` in +`crates/trace/src/quantize/palette.rs`. + Measured with the harness below (section 1, each preset on the inputs it is meant for), before and after: anchors fall in 10 of the 12 changed presets, for example 5,494 to 3,136 (High Fidelity Photo), 33 to 27 (16 Colors), 27 to 14 (Black and White Logo) and 43 to 28 (Line Art); Silhouettes rises from 13 to 15 and diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md index 0782bacab9..2e88552340 100644 --- a/docs/target-app-parity.md +++ b/docs/target-app-parity.md @@ -1584,6 +1584,7 @@ Moved from the ROADMAP's "Shipped so far" on 2026-10-10. Update it when a featur - **Image Trace, cut-out edges choose no color:** in Color and Grayscale, the edge pixels that take the color beside them, and the semi-transparent pixels within two pixels of them whose color is also the opaque art's color blended with the background, do not count when the palette or the grays are chosen, so the edge of a cut-out image no longer adds a second shade of a color to Auto Color's palette, takes away an outline's color or takes a gray of its own; beside those pixels, the anti-aliasing between a color and an outline drawn along the edge is no color of Auto Color's own when it lies at least 0.45 of the way from the color to the outline and at least one in 32 of its pixels has both around it (edge pixels that choose no color count when they lie within 2.5 Oklab × 100 of the nearest of those colors): its pixels trace as the outline, so a thin outline stays a ring of few pieces, except beside an outline along the edge with a region of 8 pixels of its own, where each takes the nearer of the two, so a wider outline is not drawn wider; an outline over the edge in the color of other art traces in that color, while an opaque rim drawn along the edge keeps its color, also where other art reaches it; a thin semi-transparent outline of another color still counts, and opaque images trace as before; code-drawn cut-out outline, rim, opaque line and grayscale edge tests in `crates/trace`. - **Image Trace, blurred edges:** in Color with a Limited palette of at most 16 colors (3 Colors, 6 Colors, 16 Colors) and in Grayscale with at most 16 grays (Shades of Gray), by VectorCraft's own rule (RGB distances, 0 to 255 a channel), a blend pixel with no unblended pixel of its own color within 4 pixels takes the nearer side of the pair of colors within 8 pixels that it is best a blend of, of the 8 colors within 8 pixels nearest to its color, when that pair explains it twice as well as its own color, or when it lies between the two and off the line between them by less than 0.15 of their distance apart; it keeps its color when it is one of the pair. Grayscale compares lightness. The in-between tones of an edge blurred over several pixels no longer trace as rings around it. High Fidelity Photo, Low Fidelity Photo and Black and White trace as before, and so do Automatic, Full Tone and Document Library palettes. Noisy and textured images settle more of their pixels. By `crates/trace/tests/quality` (256 px variants), 16 Colors on blurred flat art went from 9.0 paths to 3.0, 158 anchors to 34 and 0.239 px off to 0.069, and 6 Colors from 6.0 paths to 3.0 and 0.226 px off to 0.071; askew shapes take up to 11 px more area in colors the art does not have, and with 16 Colors the largest distance from a thin line's outline to the trace goes from 23.5 px to 45.3 (see [quality notes](image-trace-quality.md#blurred-edges)). Code-drawn blurred-disc and grayscale ramp tests in `crates/trace`. - **Image Trace, preset Paths, Corners and Noise:** every built-in preset but Auto Color and Flat Logo traces at Paths 50, and so do their enhanced versions; among those presets, Corners is 100 in Technical Drawing, 75 in Default, Black and White Logo, Line Art and Outline and 50 in the other eight, and Noise is 1 to 90 px by preset. Palettes and color counts are unchanged. Figures for these presets in the other Image Trace entries were measured at the earlier values. By `crates/trace/tests/quality`, High Fidelity Photo goes from 5,494 anchors to 3,136 and Black and White Logo from 27 to 14, while 16 Colors on flat art goes from 0.100 px off to 0.123 (see [quality notes](image-trace-quality.md#preset-paths-corners-and-noise)). Test `presets_have_their_paths_corners_and_noise` in `crates/trace`. +- **Image Trace, High Fidelity Photo in Full Tone:** High Fidelity Photo traces with Palette › Full Tone at Color detail 85 and Method › Abutting (VectorCraft's own values; it was a Limited palette of 64 colors, Overlapping). Palette › Full Tone splits into at least one color per step of Color detail where the image has that many, and its colors merge only when they look alike (less than 5 apart in Oklab × 100 and thoroughly mixed, or less than 1.5 and mixed in patches); this applies to every Full Tone trace. On 19 test images the summed mean pixel difference fell from 80.5 to 65.6 levels, with 1.66 times the anchors and 1.9 times the trace time (see [quality notes](image-trace-quality.md#preset-paths-corners-and-noise)). Tests in `crates/trace`. - **Image Trace, Noise joins the nearest color:** in Color and Grayscale, a region below Noise whose longest-border color is 10 or more apart from its own (Oklab × 100) joins the neighboring color nearest the average of its pixels (leaving out cut-edge pixels that are the color beside them blended with the transparent background), among those sharing at least a tenth of that border, so thin dark lines no longer break into dashes; a single pixel tied between colors joins by border (VectorCraft's own rule and values). 6 Colors and 16 Colors use Noise 8 and Black and White Logo Noise 5. On three illustrations with fine dark lines the mean difference falls 29% to 42% (16 Colors) with 72% to 99% more anchors (see [quality notes](image-trace-quality.md#noise-joins-the-nearest-color)). Tests in `crates/trace/src/quantize/denoise.rs`. Scores and hours unchanged. - **Image Trace, simpler contour walk:** `contour::trace_mask` works out each turn from the pixels during the walk, with no precomputed direction table and no assertion; identical loops to the previous walk on every 4 × 4 mask (see [quality notes](image-trace-quality.md#a-simpler-contour-walk)). - **Image Trace, measured:** `crates/trace/tests/quality` traces drawings made from known vector art with every preset and [`image-trace-quality.md`](image-trace-quality.md) records the numbers against the baseline. Black and White, Grayscale and Color place each edge by the blend of the pixels across it (to a fraction of a pixel on anti-aliased and blurred images; hard-edged images are read as staircases) and fit outlines as Flat Logo does. *Measured* on each preset's own inputs, all sizes and variants: Default's outlines went from 0.31 px off on average to 0.09 (largest 1.51 to 1.02), Black and White Logo's from 0.27 to 0.06 with 0.3 kinks per trace where it had 15, and the gaps between abutting paths from 64 px to 22. On clean curved shapes Black and White Logo is 0.02 px off (the open tracer measured beside it: 0.20). The palette is made of the picture's own colours (blends along edges take none of it, colours that noise made of one colour merge, a blend pixel goes to one of the two colours it lies between; #1504): 16 Colors on flat art, all variants, went from 70 paths to 4.2 and from 5.1 px off to 0.13, with no path left in a colour the art doesn't have (5.9 before). Photos are smoothed within their tones before they are quantised and stacked layers go by lightness (#1516): High Fidelity Photo went from 3,653 paths to 121 with its colour error down from 2.30 to 1.75, and a 16 megapixel photo-like image is traced in 3.5 s where 4 megapixels were refused. Since then, by the same harness: outlines are cut at their junctions and each shared piece is fitted once (#1535: gaps and overlaps between abutting paths 22 to 50 px of area down to under 2); layers are traced within the box of their pixels and a few at a time (#1546: a 16 megapixel photo 3.9 GB to 0.9 GB); black and white are read against the image's own black and the paper near each edge (#1563, for thin lines in blurred and scanned art); Ignore Color and the Auto Color and Outline presets (#1574); Snap Curves To Lines levels lines within 2.5 degrees of level or upright (#1593, the angle our choice); Create: Strokes puts centre lines in the middle of their ink and makes them as wide as it (#1595: Outline 0.295 to 0.052 px from the true centre line, 18.4 to 2.7 anchors a stroke); sharp corners whose pixel is mostly outside the shape stay corners (#1609: Default 69% to 76% kept). Three options, each off unless asked for as the legacy presets have them: Shapes (#1609: 57 to 62% of plain circles, ellipses, rectangles and regular polygons come out as live shapes, rounded rectangles rarely), Auto Grouping (#1618: paths grouped with what lies inside them, the same picture) and Gradients (#1627: linear gradients traced as one gradient-filled path; on gradient inputs 6 Colors' colour error 2.12 to 0.62 with 6.4 to 3.4 paths, none found in flat art). Snap Curves To Lines moves no end of a line by more than 1.6 px, so long lines a degree or two off stay as the image has them (#1647: Technical Drawing's largest distance 4.21 px to 1.46). Flat Logo takes the tones a scan's uneven paper makes of one colour for one colour (#1657: on scans 470 paths and 21 px off to 8.5 paths and 0.09 px). Shapes finds rounded rectangles and shapes in aliased, blurred and scanned art (#1845: 57 to 62% of the plain shapes up to 98 to 100%, no false shape but one line 2 px wide). Stroked lines get square caps where their ink is cut square, and a wide end that turned towards a corner goes back on its line (#1846: Outline's largest distance 2.94 px to 0.88, 14 anchors to 10). Each of the 14 documented presets has an enhanced version with Auto Grouping and, in all but High Fidelity Photo, Shapes (#1847), measured beside its preset: equal or better within 0.005 px and 1% of edge ΔE on every preset's own inputs (Default 0.091 to 0.083 px); Auto Grouping keeps traced order in its groups, which removed a light seam along the counters of letters. Gradients grows a gradient over the pixels noise and soft rims took off it (#1848: blurred and noisy linear gradients 3 to 11 paths beside the gradient down to 0.5 with 6 Colors, 24 to 56 down to 0.5 to 1.5 with High Fidelity Photo). Silhouettes is 0.52 px off because its threshold is 200 (0.11 px at 128). Still weak, by the same numbers: rounded rectangles and other line-and-arc outlines take 12 to 16 anchors (the fitter does not split lines from arcs), blurred and scanned polygons lose corners, hairlines under half a pixel are lost to the threshold, aliased art is about 0.25 px off, a scan's uneven paper splits into tones when more colours are asked for than the art has, stroke junctions stay at their skeleton pixels, a three-stop gradient in a small or scanned disc is not found, radial gradients stay bands (a draft, #1849, traces them; the documented option is for linear ones, so it waits for a decision), near-regular polygons a few dozen pixels across are made regular with Shapes (up to 0.5 px off), and aliased stroked lines are 0.8 px off at worst. @@ -1597,7 +1598,7 @@ Moved from the ROADMAP's "Shipped so far" on 2026-10-10. Update it when a featur - **Image Trace, Flat Logo flat-art check with named colors:** with `logoColors` named, whether the image is flat art is judged by its own colors, as many as are named, with white, or as the Colors setting gives, whichever is more. Named colors 20 levels off a flat badge's colors still trace it, a hatch on a light ground gives the same result with close and far named colors, a gradient's refusal score does not depend on how far the named colors are from it, and areas of colors that were not named are traced in the named colors instead of being refused; code-drawn tests in `crates/trace`. - **Image Trace, Flat Logo with a color between two others:** an anti-aliased edge pixel between black and white is read as a blend of black and white, not of black and a gray that lies between them, when the flat areas around it and the pixels beside it show that edge, so a black disc beside a gray square on white, with sharp edges or edges blurred by up to about half a pixel, traces with one gray path, the square, instead of the square plus 8 to 24 gray slivers around the disc with the colors found or named exactly (an edge blurred by a pixel or more, or pixel noise of a level or more, can still leave gray slivers); gray strokes two and three pixels wide beside black stay gray (a soft-edged gray stroke about two pixels wide that touches black traces as black and white, and a short one about three pixels wide can lose most or all of its gray), and a one-pixel gray line of at least 13 touching pixels between black and white stays gray (a shorter one, or one that falls between pixels or is blurred, traces as black and white); code-drawn tests in `crates/trace`. - **Image Trace, Keep Colors:** `"keepColors": ["#rrggbb", …]` traces only the palette colors near a listed color (Abutting: each with the paths the trace of every color gives it; Overlapping: not reaching under the colors left out), in Black and White, Grayscale and Color; code-drawn tests in `crates/trace` and `crates/engine`. -- **Advanced art:** live Blends (steps/distance/smooth colour, editable spine, anchor-targeted Blend tool, faithful interpolation, knockout), Envelope Distort (warp/mesh/top object, Reset, full Envelope Options, mesh handles, Edit Contents; type, images, symbols, gradients, patterns and appearance distorted everywhere), Liquify tools with options and pen pressure, Puppet Warp with rotating pins, Perspective Grid with presets, movable planes and projected type (choosing a perspective tool shows the grid; Hide Grid hides it with the tool still chosen), Gradient Mesh, Shape Builder (stroke-only open paths and lines cut the regions they cross and enclose regions of their own, and regions they bound merge without seams where the lines cross at rounded coordinates (#893); filled open paths count as closed; erase mode while Alt/Option is held: a minus pointer, red highlights of what will go, a click or drag deletes the regions touched, the pieces of open lines and the edges (outline pieces between the points where paths meet, opening their paths there) it passes over, one undo step, `shapeBuilder.merge {erase}` and `shapeBuilder.regions` edges over MCP), Live Paint (every path an edge, open lines included), Image Trace (12 presets, colour layers traced in parallel; a trace past two million anchor points is refused with advice rather than running out of memory, an image over 64 megapixels is traced scaled down to that size (aspect kept, paths at the image's own size) and one over 192 megapixels is refused, and a selection too large to outline shows its bounds (#525); Object › Image Trace › Make and Make and Expand trace at once with the Default preset, #543; with an image selected the Control bar and the Properties panel show Image Trace, whose arrow traces with any preset, Mask (`object.maskImage`: a clipping path on the image's outline, selected so its handles crop), Crop Image (a crop box on the image, starting on its part over the artboard, dragged by its handles or inside it, the outside dimmed, with X/Y/W/H, Apply and Cancel in the Control bar, Enter and Escape, #734; an image that isn't turned or skewed, isn't CMYK and can be read at its recorded size is cut from its own pixels when the crop edges fall on its pixel grid, copied as they are without resampling; any other image is drawn, #5534; `object.cropImage {rect}` for agents, `{trim: true}` cuts an image to its pixels that aren't fully transparent, pixel for pixel) and Embed or Unembed in place of Fill and Stroke; with an Image Trace object selected, its Preset (choosing another traces again), View, the Image Trace panel and Expand, plus Release in Properties; the five View modes (Tracing Result, with Outlines, Outlines, Outlines with Source Image, Source Image) redraw a trace on screen without tracing again, are saved with it and `imageTrace.setView` sets them, while exports and Expand keep the result; the panel's Advanced section is a header that stays open or closed as it was left (part of #641); Color mode's Palette: Limited, Full Tone (as many colours as the tones need, Less … More), Automatic (flat art with its own colours, else Full Tone; a heuristic) and Document Library (the most used colours of the document's swatches or a swatch library, filled with the swatch colours as they are), part of #641; Advanced › Create: Fills and/or Strokes, where lines up to the Stroke width trace as stroked centre lines (distance transform, thinning, a skeleton graph with spurs pruned, curve fitting; one width per line; without Fills, wider areas become stroked outlines), part of #641), pattern swatches with pattern editing mode, live Repeat (radial/grid/mirror). A single selected mirror repeat shows a prominent axis with a center move handle and two rotation handles. Drag the line or center to change spacing, or an end to change angle; Shift snaps rotation to 45°. The original artwork stays in place, the reflected copy previews live, Escape cancels and each drag takes one undo step through `object.repeat.options`. Controls follow zoom/view rotation and hide with edges or the bounding box. Engine and headless canvas regressions passed for gestures, history and visibility; native move, rotation and Escape screenshots were reviewed. [Public mirror-repeat reference](https://helpx.adobe.com/illustrator/desktop/paint-and-fill/create-and-edit-patterns/set-mirror-repeat-options.html). A single selected grid repeat shows a handle below the grid for rows, one right of it for columns and one past its bottom-right corner for both, and sliders between its first two columns and rows for the horizontal and vertical spacing; the source keeps its size, each drag is one undo step and Escape cancels it ([public grid-repeat reference](https://helpx.adobe.com/illustrator/desktop/paint-and-fill/create-and-edit-patterns/set-grid-repeat-options.html), #2691). Object › Expand turns radial, grid and mirror repeats into groups of their instances (#1765, #1756). +- **Advanced art:** live Blends (steps/distance/smooth colour, editable spine, anchor-targeted Blend tool, faithful interpolation, knockout), Envelope Distort (warp/mesh/top object, Reset, full Envelope Options, mesh handles, Edit Contents; type, images, symbols, gradients, patterns and appearance distorted everywhere), Liquify tools with options and pen pressure, Puppet Warp with rotating pins, Perspective Grid with presets, movable planes and projected type (choosing a perspective tool shows the grid; Hide Grid hides it with the tool still chosen), Gradient Mesh, Shape Builder (stroke-only open paths and lines cut the regions they cross and enclose regions of their own, and regions they bound merge without seams where the lines cross at rounded coordinates (#893); filled open paths count as closed; erase mode while Alt/Option is held: a minus pointer, red highlights of what will go, a click or drag deletes the regions touched, the pieces of open lines and the edges (outline pieces between the points where paths meet, opening their paths there) it passes over, one undo step, `shapeBuilder.merge {erase}` and `shapeBuilder.regions` edges over MCP), Live Paint (every path an edge, open lines included), Image Trace (12 presets, colour layers traced in parallel; a trace past two million anchor points is refused with advice rather than running out of memory, an image over 64 megapixels is traced scaled down to that size (aspect kept, paths at the image's own size) and one over 192 megapixels is refused, and a selection too large to outline shows its bounds (#525); Object › Image Trace › Make and Make and Expand trace at once with the Default preset, #543; with an image selected the Control bar and the Properties panel show Image Trace, whose arrow traces with any preset, Mask (`object.maskImage`: a clipping path on the image's outline, selected so its handles crop), Crop Image (a crop box on the image, starting on its part over the artboard, dragged by its handles or inside it, the outside dimmed, with X/Y/W/H, Apply and Cancel in the Control bar, Enter and Escape, #734; an image that isn't turned or skewed, isn't CMYK and can be read at its recorded size is cut from its own pixels when the crop edges fall on its pixel grid, copied as they are without resampling; any other image is drawn, #5534; `object.cropImage {rect}` for agents, `{trim: true}` cuts an image to its pixels that aren't fully transparent, pixel for pixel) and Embed or Unembed in place of Fill and Stroke; with an Image Trace object selected, its Preset (choosing another traces again), View, the Image Trace panel and Expand, plus Release in Properties; the five View modes (Tracing Result, with Outlines, Outlines, Outlines with Source Image, Source Image) redraw a trace on screen without tracing again, are saved with it and `imageTrace.setView` sets them, while exports and Expand keep the result; the panel's Advanced section is a header that stays open or closed as it was left (part of #641); Color mode's Palette: Limited, Full Tone (as many colours as the tones need, Less … More, split into at least one color per step of Color detail before colors that look alike merge), Automatic (flat art with its own colours, else as many as the tones need; a heuristic) and Document Library (the most used colours of the document's swatches or a swatch library, filled with the swatch colours as they are), part of #641; Advanced › Create: Fills and/or Strokes, where lines up to the Stroke width trace as stroked centre lines (distance transform, thinning, a skeleton graph with spurs pruned, curve fitting; one width per line; without Fills, wider areas become stroked outlines), part of #641), pattern swatches with pattern editing mode, live Repeat (radial/grid/mirror). A single selected mirror repeat shows a prominent axis with a center move handle and two rotation handles. Drag the line or center to change spacing, or an end to change angle; Shift snaps rotation to 45°. The original artwork stays in place, the reflected copy previews live, Escape cancels and each drag takes one undo step through `object.repeat.options`. Controls follow zoom/view rotation and hide with edges or the bounding box. Engine and headless canvas regressions passed for gestures, history and visibility; native move, rotation and Escape screenshots were reviewed. [Public mirror-repeat reference](https://helpx.adobe.com/illustrator/desktop/paint-and-fill/create-and-edit-patterns/set-mirror-repeat-options.html). A single selected grid repeat shows a handle below the grid for rows, one right of it for columns and one past its bottom-right corner for both, and sliders between its first two columns and rows for the horizontal and vertical spacing; the source keeps its size, each drag is one undo step and Escape cancels it ([public grid-repeat reference](https://helpx.adobe.com/illustrator/desktop/paint-and-fill/create-and-edit-patterns/set-grid-repeat-options.html), #2691). Object › Expand turns radial, grid and mirror repeats into groups of their instances (#1765, #1756). While Crop Image shows its box, the Control bar also sets the cropped image's resolution (PPI: a list of 72, 96, 150, 200 and 300 ppi with the ones above the image's own disabled, or a typed value; at most the image's own, or 300 ppi for a linked image ([Crop Image](https://web.archive.org/web/20210601162814/https://helpx.adobe.com/pdf/illustrator_reference.pdf#page=352))), a reference point that X and Y name and that W and H resize about, and a link that keeps W and H in proportion; `object.cropImage {ppi}` resamples the cut pixels and refuses a resolution above the limit, and `tool.setOption` sets `ppi`, `reference` and `linked` ([Crop images](https://helpx.adobe.com/illustrator/desktop/manage-objects/edit-objects/crop-images-in-illustrator.html)). The list's resolutions and the default (the image's own resolution, the center, unlinked) are VectorCraft's own. Choosing the Blend tool again while it is active (its toolbar button, W or `tool.select`) finishes the blend: the object clicked first is dropped and the next click no longer adds to the blend just made, so the click after it starts a new blend ([Blending objects](https://web.archive.org/web/20241217212108/https://helpx.adobe.com/illustrator/using/blending-objects.html)). Window › Blend exposes easing Type, Ramp and independent color Shift through `object.blend.options`.