Trace a PNM image into SVG with pamtosvg

You will turn a Netpbm PNM image into an SVG made from paths, then check that the result is valid and has the expected dimensions. The installed command here is Netpbm 11.5.2, while its local manual page is dated 23 April 2006. Allow about ten minutes for a small image. You need the netpbm package and a readable PBM, PGM or PPM file.

pamtosvg is a tracer, not a simple raster-to-vector wrapper. It follows shapes in the input and writes unitless SVG coordinates, with one SVG unit corresponding to one input pixel. Simple, high-contrast artwork usually traces more predictably than a detailed photograph.

1. Check the installed command

Start by confirming which executable 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
...

The version output includes build details, so the final lines can differ between package builds. No elevated privileges are needed for a normal conversion. Do not use sudo unless ordinary file permissions genuinely prevent 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 is quiet apart from any diagnostic output. Verify the exit status immediately, inspect the SVG header, and ask an XML parser to check the file:

$ 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

The exact paths depend on the image. The useful checks are status 0, an svg element with width and height, and successful XML parsing. A browser is also a convenient visual check.

3. Protect an existing output

Shell redirection with > truncates its destination before pamtosvg starts. That matters if a failed trace would leave you with a partial file. Write to a temporary name in the same directory, inspect it, then replace the old output deliberately:

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

If the command or validation fails, leave the old logo.svg alone and remove the incomplete logo.svg.new after checking that it is the file you intended to discard. The mv changes state and can replace an existing destination, so do not run it until the new file has passed your checks.

4. Trace from standard input

The input filename is optional. This makes pipelines possible and avoids creating an intermediate file:

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

For a Netpbm producer, connect the commands directly:

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

Use this only when the first command really emits a PNM image. A pipeline can hide an upstream failure if you only inspect the final command's status. In Bash, enable pipeline failure reporting for a script:

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

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

5. Choose the tracing mode

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

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

-preserve-width only has meaning with -centerline; it preserves the line width before thinning. It is not a general SVG sizing option. Run the two modes into separate files and compare them in a viewer. Neither option changes the input file.

If a known background should not become a path, specify it explicitly:

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

Without this background option, no colour is treated as background. The colour name follows Netpbm's colour-name rules. If the background is not uniform, this option is unlikely to give the result you want.

6. Adjust detail only when the trace needs it

Start with 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. The installed defaults include a corner threshold of 100 degrees, an always-corner threshold of 60 degrees, four filter iterations, an error threshold of 2.0 pixels, and a line threshold of 1 pixel.

Change one setting at a time so you can 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 reduce smoothing. These are trace-fitting choices, not a promise of higher visual quality, so compare the output and keep the original raster.

7. Diagnose the common failures

If the command reports an end-of-file or read error, check that the input is a complete PNM image and that the path is readable:

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

A successful command can still produce a poor trace. Inspect the SVG rather than relying only on its exit status. Wrong-looking proportions often indicate that the source image itself is not what you expected. If the output is noisy, simplify speckles with pbmclean for PBM input or reduce colours with pnmquant before tracing, keeping those preprocessing outputs separate from the original.

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