Image Trace: keepColors traces only the listed palette colors

Image Trace had no way to trace some of an image's colors and leave the
rest out. Ignore Color drops one color, so tracing only the line work of
a multi-color image took a full trace and then deleting the other
colors' paths by hand.

With "keepColors": ["#rrggbb", ...] in the params of imageTrace.make and
imageTrace.makeAndExpand, only the palette colors within about 30 levels
of a listed color are traced, the distance Ignore Color matches by. With
Method Abutting, the kept colors' paths are the same as in a trace of
every color. With Method Overlapping, a kept color's paths do not reach
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.
Flat Logo mode does not use the list.

The reply's warnings name each listed color that matches none of the
colors the trace found, and say when nothing was traced; the status bar
shows the first. The warnings are translated in every complete catalog.
The params help of imageTrace.make lists keepColors and the new
warnings, and the help of imageTrace.makeAndExpand lists the warnings
it returns.

docs/image-trace-adjustments.md

@@ -32,6 +32,19 @@ white beside a cream), at most six; scattered specks of a colour add none. Adobe
 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, or because Ignore Color leaves out every area of
+the ones that match, the first warning says so, and the status bar shows it. In Flat Logo mode the
+warning says that `keepColors` is not used.
+
 **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)

docs/mcp.md

@@ -1447,7 +1447,8 @@ already walks Image Trace. Short agent entry points:
   format's first extension (`png8` gives `.png`, `template` gives `.vctemplate`). A step without `format` keeps the
   source file's extension (`.vectorcraft` over data sets).
 - Image Trace: `imageTrace.presets`, `imageTrace.make {id?, preset?, params?, view?}` (or `imageTrace.makeAndExpand`),
-  `imageTrace.setView`, `imageTrace.expand`, `imageTrace.release`.
+  `imageTrace.setView`, `imageTrace.expand`, `imageTrace.release`. With `keepColors` in `params`, the reply's
+  `warnings` name each listed color that no traced color matches, and say when nothing was traced.
 - Live Paint: `livePaint.make`, `livePaint.merge`, `livePaint.fill {group?, point}`, `livePaint.strokeEdge`,
   `livePaint.info {group}`, `livePaint.release`, `livePaint.expand`, and `livePaint.gapOptions {ids?, detect?, size?,
   color?, closeGaps?}` (Object › Live Paint › Gap Options). With `detect: true`, paint stops at the gaps that run