Files
vectorcraft/docs/image-trace-adjustments.md
T
dotCooCoo 99ccdb790a Image Trace: Flat Logo docs count a gray stroke's loss at black in pixel centers
The parity line said a soft-edged gray stroke running out of black loses
"3 or 4 pixels" where it meets black. It now says 3 or 4 of the 16 pixel
centers along its middle nearest black, as docs/image-trace-adjustments.md
and the test count them.

In docs/image-trace-adjustments.md, gray near black on blurred edges now
traces gray at fewer of its pixel centers instead of "losing pixels", a
wider band loses some or most of its gray instead of part of it (bands 3
and 4 pixels wide at a blur of 1 pixel keep about 60 of 336), and the
paragraph is wrapped to the file's line width.
2026-11-16 13:04:10 -08:00

216 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Adjusting an Image Trace
Select a placed raster image, then choose **Image Trace** or a preset from its arrow
in Properties or the Control bar. The original image stays inside the tracing object so
that subsequent adjustments always use the original pixels.
To adjust the result, select the tracing object and click **Image Trace** in Properties or the
image icon in the Control bar: the Image Trace panel opens with **Advanced** expanded. An existing floating or docked panel is activated in
its current location. Opening the controls does not add a document undo step.
| Control | Range | Effect |
|---|---|---|
| Threshold (Black and White) | 0–255 | Higher values include lighter pixels as black ink. |
| Paths | 0–100% | Higher values fit outlines more closely to the image. |
| Corners | 0–100% | Higher values preserve more sharp turns. |
| Noise | 1–100 px | Suppresses small connected regions; higher values remove more small details. |
| Method | Abutting / Overlapping | Chooses shared boundaries or stacked overlapping paths. |
| Create | Fills / Strokes | Creates filled areas, stroked lines, or both. |
| Ignore Color | Color picker | Leaves out the selected color (white by default). |
The built-in presets other than Auto Color and Flat Logo all use 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. 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)).
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.
While dragging, the preset and Enhanced row stay in place until release so the
slider retains its active interaction. Committed settings are synchronized immediately,
so Undo also restores the panel values before its next frame. View can show the source image, the result, outlines, or combinations without re-tracing.
Use **Expand** when finished to turn the result into ordinary editable vector objects;
after expanding, the tracing settings are no longer available. **Release** restores the source.
**Auto Color** (the Automatic palette) counts flat art's colours by area, and also keeps colours too
rare for that count when they are distinct and drawn as regions of their own (a stem, a highlight, a
white beside a cream), at most six; scattered specks of a colour add none. Adobe does not document how
its own palettes are chosen; this is VectorCraft's own method (see
[image-trace-quality.md](image-trace-quality.md#auto-color-keeps-rare-colours)).
**Keep Colors.** `"keepColors": ["#rrggbb", …]` in the params of `imageTrace.make` or
`imageTrace.makeAndExpand` traces only the palette colors within about 30 levels of a listed color,
the distance Ignore Color matches by, and leaves the other colors out. With Method Abutting, the paths
of the kept colors are the same as in a trace of every color. With Method Overlapping, a kept color's
paths reach under the kept colors above it in the stack and not under the colors left out, as with
Ignore Color. An empty list traces every color, and a value that is not a six-digit hex color is
refused. With Ignore Color as well, a kept color that Ignore Color matches is still left out. Flat
Logo does not use `keepColors`: it traces the colors named in `logoColors`, or the colors it finds.
The reply's `warnings` name each listed color that matches none of the colors the trace found. When
nothing is traced because no listed color matches, because Ignore Color leaves out every area of the
ones that match, or because the ones that match produce no paths, the first warning says so, and the
status bar shows it. In Flat Logo mode the
warning says that `keepColors` is not used.
**Document Library color groups.** With Palette › Document Library and Library › Document Swatches,
the panel's **Colors** menu traces with every document swatch (**All**) or with the colors of one
color group from the Swatches panel, as the public
[Image Trace panel options](https://helpx.adobe.com/illustrator/desktop/manage-objects/traces-mockups-symbols/image-trace-panel-options.html)
page ([archived](https://web.archive.org/web/20251230195658/https://helpx.adobe.com/illustrator/desktop/manage-objects/traces-mockups-symbols/image-trace-panel-options.html))
describes Document Library. In the params of `imageTrace.make` or `imageTrace.makeAndExpand`,
`"colorGroup": "<name>"` names the group. It needs `"mode": "color"`, `"palette": "documentLibrary"` and
`"library": "document"`; a `colorGroup` with a nonempty name and any other mode, palette or library is refused. An
empty name names no group and is accepted with any mode, palette or library; with Document Library and
`"library": "document"` it traces with every document swatch. A group whose name matches exactly is used first, then one whose name differs only in case. At
most `colors` of its colors are used. A missing group and a group with no solid colors are refused. Choosing another
mode, palette or library in the panel clears the group. A group the active document does not have shows as All
and traces as All.
**Document Library colors.** With Library › Document Swatches, with or without a color group,
traced fills and strokes take the library color without a link to its swatch. This includes global,
spot and tint swatches. Tints trace at the color shown by the tint swatch. Editing a swatch later
does not recolor the trace. Colors from other swatch libraries are also unlinked.
**Ignore Color, background only.** Ignore Color leaves out every area of the chosen color. With
`"ignoreBackground": true` beside `"ignoreWhite": true` in the params of `imageTrace.make` or
`imageTrace.makeAndExpand`, it leaves out only the areas of that color that reach the image's edge,
joined through pixels above, below or to either side, and traces the areas of it that other colors
enclose: black line work inside a panel stays when the black around the panel is left out. Flat Logo
leaves out every white area whatever `ignoreBackground` is.
**Document Library** traces with the library's colors as they are. Each pixel takes the library
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
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
exports (PNG, JPEG, TIFF and the other bitmap formats) with None anti-aliasing do not show it at any
size. Raster exports with Art Optimized anti-aliasing, the default, do not show it up to 10 million
pixels and 16,384 pixels on a side. A raster export shows the line as the canvas does when it uses
Type Optimized anti-aliasing, or when it uses Art Optimized and is larger than either limit.
Overlapping stacks the colors instead: a lower color continues under the edge of the color above it,
and no background shows along that edge. With Fills and without Create Strokes, Overlapping also
follows a fill rule of VectorCraft's own: each shape is filled whole, and the area of other colors
that a shape encloses is traced again as shapes of its own and stacked above it. Each enclosed
outline is then fitted once. The [Image Trace presets](https://helpx.adobe.com/illustrator/desktop/manage-objects/traces-mockups-symbols/image-trace-presets.html)
page describes Overlapping as stacking shapes where it can and overlapping their edges elsewhere. A
shape keeps a hole where the enclosed area holds a transparent pixel or a color that Ignore Color or
Keep Colors leaves out. A hole smaller than Noise is filled with the shape's own color, as before.
The pixels of an area inside other areas are scanned once more for each area around it, within a
work budget of VectorCraft's own: four times the image's pixels (counted as at least 65,536) times
its colors, with each area costing its bounding box times the colors in it. An area that costs more
than what is left of the budget keeps its holes and is not charged, so a smaller area after it can
still be filled.
With Create Strokes, or without Fills, shapes keep their holes.
**Flat Logo with named colors.** With `logoColors` named, Flat Logo decides whether the image is flat
art by the image's own colors. It finds them the same way as when no colors are named, and looks for as
many colors as are named, with white, or as the Colors setting gives, whichever is more. How far the named colors
are from the image's colors does not change whether the image is refused. While no more colors are
named than the Colors setting, an image is refused exactly when it is refused without named colors.
The trace then uses only the named colors, and white while white is a color of its own. An area of a
color that was not named is traced too: each of its pixels goes to the named color, white or
transparent that has the largest share in the blend of them that comes closest to the pixel.
**Flat Logo with a color between two others.** When a traced color lies between two others, as a gray
lies between black and white, an anti-aliased edge pixel between the outer two is also a blend of the
middle color and one of them. Flat Logo then reads the pixel as a blend of the outer two when the pixel
lies on an edge between them and that blend lies nearer the pixel than the blend with the middle color.
The pixel lies on such an edge when, along the line between the outer two colors, it reaches a pixel
darker than the middle color in at most 5 steps, each to the neighbor that lies farthest toward the
darker color while the pixels keep getting darker, and reaches a pixel lighter than the middle color the
same way. When the first step toward one outer color comes to a pixel that is less than half as far from
that color as from any other traced color, the path toward the other outer color stops at the first
pixel within 4 levels (out of 255) of the middle color that it comes to before it gets past the middle
color. A blend lies as near the pixel as the farther of its colors' nearest flat areas within 6 pixels.
The blend of the outer two also lies as near as the larger of the two step counts, when that number is
smaller. Each path counts its steps to the first pixel past the middle color that is less than half as
far from that path's outer color as from any other traced color.
A black disc beside a gray square on white traces with one gray shape, the square, and no gray slivers
around the disc, when its edges are sharp or blurred by up to 2 pixels, with the colors found or named.
A light gray (230) blurred by 1.5 pixels leaves up to 4 slivers of up to 3 pixels. With the colors named
and edges blurred by 3 pixels, a gray of 128 is still one shape, a gray of 200 leaves 4 slivers with no
area, and a light gray leaves 8 slivers of up to 21 pixels. An image with noise of a level or more in its
pixels can still leave gray slivers along the disc.
With sharp edges, a gray stroke two or three pixels wide beside black has no darker pixel next to it and
stays gray, and so does a gray band along black. The counts below are of pixel centers that trace gray.
With edges blurred by 0.6 pixels, as by ordinary anti-aliasing, a gray band 3 to 8 pixels wide along
black traces gray at no fewer than 4 of every 5 of its pixel centers. On edges blurred by a pixel or
more, gray near black traces gray at fewer of its pixel centers. A soft-edged gray band along black
traces as black and white, with gray at no more than 1 of every 16 of its pixel centers, when it is up
to 4 pixels wide at blurs of 1.5 and 2 pixels, up to 3 pixels wide at a blur of 3 pixels, or 2 pixels
wide at a blur of 1 pixel. A wider band loses some or most of its gray next to black. Bands 3 and 4
pixels wide blurred by 1 pixel trace gray at about 60 of their 336 pixel centers (over grays of 230, 200
and 128), bands 4 pixels wide blurred by 3 pixels at about 39 of 192, and a band 8 pixels wide at no
fewer than half of its pixel centers at blurs of 1 to 3 pixels. A light gray stroke 2 pixels wide,
blurred by 1.5 pixels, traces gray at about 10 of the 34 pixel centers along its middle when it lies 2
pixels from black and at about 25 when it lies 4 pixels away. At 6 or 8 pixels from black it traces gray
at all 34: its pixels do not reach black in 5 steps and are not read as an edge of black and white. A
soft-edged gray stroke 2 or 3 pixels wide running straight out of black, blurred by 1 or 1.5 pixels,
loses 3 or 4 of the 16 pixel centers along its middle nearest black. Blurred by 2 pixels, one 3 pixels
wide loses 2 or 3 of them, and one 2 pixels wide traces as black and white along its whole length. A
soft-edged gray stroke about two pixels wide lying along black traces as black and white, and one about
three pixels wide lying along black can lose most or all of its gray when it is short (12 pixels long or
less). A line of gray one
pixel wide between black and white stays gray when at least 13 of its pixels touch: such a line and a
straight black-to-white edge whose pixels are as light as the gray give the same pixels, and both
trace as gray. A one-pixel gray line between black and white that is shorter than 13 pixels, falls
between pixels or is blurred traces as black and white. A flat area whose color lies between two named colors, as when the colors are named
some levels off, counts as holding the named colors it is a blend of, and so do the pixels of exactly
its color that touch it.
The same holds when the left-out color lies beyond both colors of the edge, as a pale gray ground lies
beyond a gray panel and a charcoal disc: an edge pixel between the panel and the disc is also a blend of
the ground and the disc. Flat Logo reads it as a blend of the panel and the disc when, along the line
through the three colors, the pixel has a neighbor on each side of it, no neighbor lies past the panel
toward the ground, and a chain of neighbors, each nearer the panel's color than the one before, leads
from the pixel, in at most 6 steps, to the panel's color or to a flat area of the panel. The same rule
applies to a left-out color darker than both colors of the edge, and to colors that are not grays. A
charcoal disc on a gray panel on a paler ground then traces with no slivers of the ground around it when
its edges are sharp or blurred by 0.7 pixel. An edge blurred by a pixel or more can still leave slivers
of the ground. The pixels of a pale line on the disc, whether one pixel wide, blurred over three pixels
or falling between two pixels, and the edge of a gap of the ground's color between the disc and the
panel keep the ground in their blends.
**Large images.** An image of more than 1500 pixels on a side is traced as any other, only more
slowly, and the trace says so: `imageTrace.make` returns the note in `warnings` and the status bar
shows it (the [results optimization](https://helpx.adobe.com/illustrator/using/image-trace-results-optimization.html)
page describes the same warning for images over 1500 px). An image of more than 64 megapixels (up to
192) is traced from a copy scaled down to 64 megapixels, and the trace says that too. Flat Logo traces at
most 1024 pixels on a side: a larger decoded raster is averaged down in whole-number blocks first (a 1025-pixel
image is traced at 513, and a 16,000 × 12,000 image, decoded at 9,459 × 7,094, is traced at 946 × 710), and the trace names both sizes in `warnings`. Flat Logo gives that note in place
of the slower-trace note for an image over 1500 pixels and in place of the 64-megapixel note. An image at most
1024 pixels on a side is traced at its own size, also when the named `logoColors` differ slightly from the
image's colors. Only an image with more than 150,000 different pixel values to unmix (values that are
not exactly one traced color, and values that are, at pixels outside a flat area) is averaged down
further: the factor doubles until at most 150,000 remain or the working copy has at
most 16,384 pixels (at most six times). A trace that would
make more than 8,000,000 anchor points (2,000,000 on the web) is refused to protect memory, with advice:
raise Noise, lower Paths or Colors, or pick a lower-fidelity preset. A trace keeps
about 90 bytes an anchor; a 4000 × 3000 photo at Limited 64 colors, Paths 90, Corners 25 and Noise 4
makes about 1.9 million.
**Tracing in the background.** On the desktop a trace runs on a thread of its own, so the window
keeps answering while a photo or a large image is traced (#3098). Make, Make and Expand, the task
bar's Image Trace and the panel's Trace and presets start it. The status bar says "Tracing the
image…", and after 0.4 s a progress window shows how many of its colours are traced, with Cancel
(also Esc, `imageTrace.cancelRuns`) and Continue in Background (`imageTrace.hideRuns`). The result is
one undo step, as before. A new trace of the same object replaces one still running. A trace whose
image or settings changed meanwhile changes nothing, and the status bar says to trace it again.
`imageTrace.make` and `imageTrace.makeAndExpand` from MCP, scripts and the control channel trace at
once and return their result, as every trace on the web does.
These controls use VectorCraft's existing tracing algorithm. Parameter effects follow its
implementation; they do not claim pixel-identical results with another application.
The terminology and general control behavior are described in the
[public Image Trace panel documentation](https://helpx.adobe.com/illustrator/desktop/manage-objects/traces-mockups-symbols/image-trace-panel-options.html).
Regression coverage: `crates/ui-egui/src/panels/image_trace.rs` tests opening the panel,
a quick trace leaving it as it was, repeated opening, floating ownership, slider commits, visible threshold
changes, undo, and the Properties entry point. Tracing in the background:
`crates/ui-egui/src/tests/trace_runs.rs`. Tracer tests live in `crates/trace/src/tests.rs`.