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.

Originally published at https://vectorize.dudko.dev/blog/tracer-colour-count-is-not-your-separation-count.