If you quote screens, plates or ink changes off a traced file, there is a number
sitting right in front of you that looks like the one you want. Trace a logo and
the tool tells you how many colours it found. Our CLI prints it in its --json
line as colors. It is the obvious thing to read.
On artwork with two inks on white, that number came back as 3, as 10, as 13 and as 14 in four otherwise identical runs. The thing that moved it was the typeface the word was set in.
That is the small problem. Here is the one that costs money: in the run that reported 14, the DXF it wrote alongside that number contained 67 colour layers. The stats line was not merely a different kind of number. It was low by a factor of nearly five, and the file is the thing your cutter opens.
Everything below was run on 2026-11-16 against @dudko.dev/vectorize-cli 0.6.11
over vectorize-core 0.6.7, which is what npm served that day. (The default-settings
numbers are identical to a run on 0.6.5 almost four weeks earlier.) The fixture is
four lines of ImageMagick, so you can reproduce all of it.
The fixture
The same artwork, four times. A five-letter word in navy #1b3a6b, a red
#c0392b disc beside it, on white. 640 × 200. Two inks and a background, exactly
as a customer would describe it on the phone.
for f in Carlito-Bold Caladea-Bold LiberationSans-Bold DejaVuSans-Bold; do
convert -size 640x200 xc:white \
-font "/usr/share/fonts/truetype/.../$f.ttf" -pointsize 110 \
-fill '#1b3a6b' -annotate +20+140 'RADIO' \
-fill '#c0392b' -draw "circle 560,100 560,55" \
-density 96 "m-$f.png"
convert "m-$f.png" -density 96 -quality 82 "in-$f.jpg"
done
Four PNGs, and a JPEG of each at quality 82 to stand in for the file a customer actually emails you.
What came back
colors is what the tracer reported. layers is how many colour layers the DXF
it wrote actually contains, counted afterwards. contours is the polyline count.
| typeface | source | reported colors |
layers in the DXF | contours |
|---|---|---|---|---|
| Carlito Bold | clean PNG | 3 | 3 | 12 |
| Carlito Bold | JPEG q82 | 3 | 3 | 12 |
| Caladea Bold | clean PNG | 9 | 18 | 68 |
| Caladea Bold | JPEG q82 | 10 | 27 | 63 |
| Liberation Sans Bold | clean PNG | 9 | 18 | 68 |
| Liberation Sans Bold | JPEG q82 | 13 | 24 | 91 |
| DejaVu Sans Bold | clean PNG | 14 | 64 | 142 |
| DejaVu Sans Bold | JPEG q82 | 14 | 67 | 136 |
Two inks and white in all eight rows.
Read the two middle columns against each other. Where the reported count is 3 it is right. Everywhere else it is low, and it gets proportionally worse as the count climbs: 9 against 18, 13 against 24, 14 against 67. If you had only ever traced the Carlito file you would walk away believing the number works perfectly.
The explanation that is wrong, and I had it wrong too
The obvious reading is compression. JPEG smears a letter's edge into intermediate shades, the tracer faithfully finds them, each becomes a "colour". Tidy story, and it is the one I would have told you before running this. The table breaks it already: the clean PNGs report 9, 9 and 14 with no compression anywhere near them.
So I checked what was actually in the source files, which is the step that
settles it. convert <file> -format %k info: counts distinct colours:
| typeface | distinct colours in the PNG | in the JPEG |
|---|---|---|
| Carlito Bold | 513 | 5380 |
| Caladea Bold | 517 | 5708 |
| Liberation Sans Bold | 513 | 5474 |
| DejaVu Sans Bold | 515 | 5523 |
Every one of the four PNGs holds about the same number of distinct colours: 513 to 517. Anti-aliasing put them there: a smooth letter edge is a gradient, and that is equally true of all four typefaces. The JPEGs all sit around 5,500. The colour content of the source is, for any practical purpose, identical across the four.
And the reported count still goes 3, 9, 9, 14.
So it is not a measurement of the image, because the image is the same. It is the result of a clustering decision (how many groups the algorithm chose to split ~515 shades into), and that turns on the geometry of where those shades fall, which is the only thing changing the typeface changed. The number is a true report of a decision. It is not a fact about your artwork, and as the table shows, it is not even a reliable report of the file that decision produced.
The general version, which is worth more than the specific one: when software tells you how many of something it found, you are reading its model, not your file.
Count the file
One command, and it cannot be wrong about itself.
DXF — one layer per colour, so the layer count is the separation count:
grep -o '^COLOR_[0-9A-Fa-f]*$' out.dxf | sort -u # the layers
grep -o '^COLOR_[0-9A-Fa-f]*$' out.dxf | sort -u | wc -l # how many
grep -c LWPOLYLINE out.dxf # total contours
(Our writer names DXF layers COLOR_RRGGBB. If you are checking another tool's
output, read the layer names it uses and adjust the pattern. The group code for
a layer name is 8, with the name on the line after it.)
SVG or EPS — count distinct fills:
grep -o 'fill="#[0-9a-fA-F]*"' out.svg | sort -u
On the Liberation JPEG that prints thirteen fills, eleven of which are
near-shades of the one red disc: #c1392b, then #c74d41, #cc5d52, #d06c62,
#d57c74, #da8c84 and on up to #f6e7e5. A separation program will treat each
as its own colour, because each of them is one.
And note the DXF and the SVG from the same source do not agree with each other: 24 layers against 13 fills. Count the format you are actually going to use.
Getting the file down to the inks
--colors N puts a ceiling on the clustering. On this artwork, two inks with
anti-aliased lettering, --colors 2 is the request that works:
| typeface | JPEG at defaults | --colors 2 |
--colors 3 |
|---|---|---|---|
| Carlito Bold | 3 layers / 12 contours | 3 / 12 | 3 / 12 |
| Caladea Bold | 27 / 63 | 3 / 26 | 5 / 29 |
| Liberation Sans Bold | 24 / 91 | 3 / 26 | 5 / 29 |
| DejaVu Sans Bold | 67 / 136 | 3 / 30 | 10 / 48 |
With 2, every file comes out as three layers: the navy, the red and the white
ground. With 3, the spare slot goes to edge shades. On the Liberation JPEG that
was two pinks around the disc (#DB928A, #DC918A), and on DejaVu it was seven
in-between blues around the letters.
Three things worth knowing, all of the kind you otherwise find out late:
The right number depends on the art, not on a rule. On flat shapes with
hard edges, a navy square and a green circle, the same tool wants --colors 3
for two inks, because there the white background takes a slot of its own. Ask
for 2 on that file and the green merges with white into a blended fill. Lettering
with soft edges behaves the other way. "Inks plus one" is right for one file and
wrong for the other, and nothing in the output tells you which one you have.
The stats line under-reports here too. The DejaVu runs with --colors 2
printed "colors":2, and the files have three layers. Nothing was lost. The
number is just low again, in the same direction.
The ink hex moves. With --colors 2 the navy layer came out #041143 on
the DejaVu JPEG and #101C4B on the Liberation one, darker than the #1b3a6b
the artwork used. That is fine for a separation, since the layer is the screen
and you pick the ink at the press. It is not fine if you read the hex as the
customer's colour.
If you do not know how many inks the original had, trace once at defaults, count the layers, and decide from that.
If you only take one thing
A rule for the art desk: the tracer's colour count is a claim; the file is the evidence. Count layers on a DXF, or distinct fills on an SVG or EPS, before anything reaches a screen or a cutter. One command, and it is the only number in the whole process that is about your artwork rather than about somebody's algorithm.
Measured 2026-11-16 on @dudko.dev/vectorize-cli 0.6.11 over vectorize-core
0.6.7, the npm latest that day. Versions move, and how --colors counts has
changed more than once between releases, which is the other reason the advice
here is "count the file" rather than "use this flag value". Endpoint and format
list: vectorize.dudko.dev/api.