Trace a PNM Image into SVG with pamtosvg

pamtosvg traces a Netpbm PNM image into SVG paths, and getting a clean result depends far more on your source image than on any flag you pass it. The installed command here is Netpbm 11.5.2, though its local manual page is dated 23 April 2006. Allow about ten minutes for a small image, and have the netpbm package and a readable PBM, PGM or PPM file ready.

This is a tracer, not a simple raster-to-vector wrapper: it follows shapes in the input and writes unitless SVG coordinates, one SVG unit per input pixel. Simple, high-contrast artwork traces far more predictably than a detailed photograph, so set your expectations accordingly before you start.

1. Check the installed command

Confirm which binary your shell will run and record the Netpbm version:

$ command -v pamtosvg
/usr/bin/pamtosvg
$ pamtosvg --version
pamtosvg: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
...

Build details tail the version number, so the final lines can differ between package builds. No elevated privileges are needed for a normal conversion, do not reach for sudo unless ordinary file permissions are genuinely stopping you reading the input or writing the destination.

2. Trace the input to a new SVG

Pass the PNM filename as the optional argument and redirect standard output to a new destination:

$ pamtosvg /path/to/logo.pnm > logo.svg

A successful run stays quiet apart from any diagnostic output. Check the exit status right away, look at the SVG header, and let an XML parser confirm the file is well formed:

$ printf '%s\n' "$?"
0
$ sed -n '1,5p' logo.svg
<?xml version="1.0" standalone="yes"?>
<svg width="640" height="480">
<path style="fill:#..."
$ xmllint --noout logo.svg

Exact paths depend on the image. What matters is status 0, an svg element with width and height, and clean XML parsing. A browser tab is also a perfectly good visual check.

3. Protect an existing output

> truncates its destination before pamtosvg even starts, which matters if a failed trace would otherwise leave you with a partial file. Write to a temporary name in the same directory, check it, then replace the old output on purpose:

$ pamtosvg /path/to/logo.pnm > logo.svg.new
$ xmllint --noout logo.svg.new
$ mv logo.svg.new logo.svg

If the command or the validation fails, leave the old logo.svg alone and remove only the incomplete logo.svg.new, once you have confirmed that is really the file you meant to discard. mv changes state and can overwrite an existing destination, so do not run it until the new file has actually passed your checks.

4. Trace from standard input

The input filename is optional, which opens up pipelines and skips an intermediate file entirely:

$ cat /path/to/logo.pnm | pamtosvg > logo.svg

Connect a Netpbm producer directly:

$ pnmquant 16 /path/to/photo.ppm | pamtosvg > photo.svg

Only do this when the first command genuinely emits a PNM image. A pipeline can quietly hide an upstream failure if you only look at the final command's exit status, so enable pipeline failure reporting in a script:

set -o pipefail
pnmquant 16 /path/to/photo.ppm | pamtosvg > photo.svg

Quantising colours can make a busy image far easier to trace, but it changes the raster before tracing ever happens. Keep the original and compare the result rather than applying this blindly.

5. Choose the tracing mode

By default the program traces an object's outline. For line art where the path through the middle matters more than the boundary, switch to -centerline:

$ pamtosvg -centerline /path/to/line-art.pbm > line-art.svg

-preserve-width only means anything alongside -centerline, it preserves the line width before thinning and is not a general SVG sizing option. Run both modes into separate files and compare them in a viewer, neither changes the input file.

Got a known, uniform background that should not become a path? Say so explicitly:

$ pamtosvg -background-color white /path/to/icon.ppm > icon.svg

Without this option, no colour is treated as background by default. The colour name follows Netpbm's usual colour-name rules. A non-uniform background makes this option unlikely to give you the result you actually want.

6. Adjust detail only when the trace needs it

Start with the defaults. If corners look too rounded or the output has too many small bends, the manual exposes controls for corner detection, smoothing and curve fitting:

• Corner threshold: 100 degrees by default.
• Always-corner threshold: 60 degrees.
• Filter iterations: four.
• Error threshold: 2.0 pixels.
• Line threshold: 1 pixel.

Change one setting at a time so you can actually tell what helped:

$ pamtosvg -filter-iterations=2 -error-threshold=1 \
    /path/to/logo.pnm > logo-tuned.svg

Lowering the error threshold can preserve more detail and produce more path data. Fewer filter iterations mean less smoothing. These are trace-fitting choices, not a promise of higher visual quality, so compare the output yourself and keep the original raster around.

7. Diagnose the common failures

An end-of-file or read error means the input is not a complete PNM image, or the path is not readable. Check both without changing anything:

$ test -r /path/to/logo.pnm && echo readable
$ file /path/to/logo.pnm

A command that exits cleanly can still produce a poor trace, so inspect the SVG rather than trusting the exit status alone. Proportions that look wrong usually mean the source image itself is not what you thought it was. Noisy output? Clean up speckles with pbmclean for PBM input, or reduce colours with pnmquant before tracing, keeping those preprocessing outputs well separate from the original.

For debugging, -report-progress writes tracing progress to standard error. -log writes a curve-tracing log beside the input, named from the input filename root, or pamtosvg.log when reading standard input. Treat that log as temporary diagnostic data, and check where it will land before using the option in a shared directory.