Convert a PNM Image to PostScript with pnmtops

You will finish with a PostScript file made from a PGM or PPM image, with its page size and placement chosen deliberately. The examples use pnmtops from Netpbm 11.5.2, installed here as Debian package netpbm 2:11.05.02-1.1build1.

Allow about ten minutes. You need a readable PNM image and a shell. The conversion itself normally needs no elevated privileges. This guide writes new files in your working directory and does not alter the input image.

1. Check the installed command

Confirm which executable will run and record its version. Both commands are read-only:

$ command -v pnmtops
/usr/bin/pnmtops
$ pnmtops --version
pnmtops: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
pnmtops: Built from source dated 2024-03-31 09:09:47

The installed program accepts one input file, or it reads a PNM stream from standard input when no file is named. It writes PostScript to standard output. That makes shell redirection part of the normal workflow, so choose the destination carefully.

2. Convert one image without destroying an existing output

Use a new destination first. The shell operator > truncates its destination before pnmtops starts, so do not point it at a valuable PostScript file until you have checked the source and destination names.

$ pnmtops /path/to/input.pgm > output.ps
$ printf 'converter status: %s\n' "$?"
converter status: 0
$ test -s output.ps && echo 'output exists and is non-empty'
output exists and is non-empty

Use a PPM file for a colour image. A PGM input produces a greyscale PostScript image, while a PPM input produces a colour one. The output is a PostScript program that represents the image, not a new raster image.

If the conversion fails, keep the original PNM file and inspect the error. For a safer replacement workflow, write to a temporary name and move it only after the command succeeds:

$ pnmtops /path/to/input.pgm > output.ps.new
$ test -s output.ps.new && mv -- output.ps.new output.ps

The mv command changes the destination name, but it does not change the source image. If the conversion fails, remove the incomplete output.ps.new after checking that it is the file you intended to discard.

3. Choose the printed image size

With no dimensioning option, pnmtops behaves approximately as if -scale=1.0 were selected: 72 input pixels represent about one inch, subject to rounding for the output device. The default output page is 8.5 by 11 inches.

For a fixed image width, use inches:

$ pnmtops -imagewidth=6 /path/to/input.pgm > image-6in.ps

The aspect ratio is preserved. You can give -imageheight instead, or give both to define a box in which the largest proportional image will fit. These options describe the image, not the paper. If the requested image is larger than the page, it can run off the page.

For a predictable page rather than a predictable image, set the page dimensions and let the default fitting behaviour do the work:

$ pnmtops -width=8.5 -height=11 /path/to/input.pgm > letter-page.ps

Do not combine -scale or -equalpixels with -imagewidth or -imageheight. Those are alternative sizing methods, and the command rejects conflicting combinations.

-equalpixels makes the output contain the same number of pixels as the input. Its physical size therefore depends on the selected output resolution. Set that resolution explicitly when it matters:

$ pnmtops -equalpixels -dpi=300 /path/to/input.pgm > 300dpi.ps

At 300 dpi, a 3,000-pixel-wide input is intended to occupy 10 inches. The -dpi option accepts one value for both directions or a pair such as -dpi=300x600.

4. Control orientation and placement

By default, the command centres the image and turns it by 90 degrees when that fits the page better. Use -noturn to prevent automatic rotation, or -turn to rotate it regardless of its shape:

$ pnmtops -noturn -imagewidth=6 /path/to/input.pgm > portrait.ps
$ pnmtops -turn -imagewidth=6 /path/to/input.pgm > rotated.ps

Use -nocenter when another program expects the image at the lower-left corner of the page. The manual also documents a compatibility option that leaves the default placement unchanged. For arbitrary placement, build a full-page PNM with pamcomp first, then convert that composed image.

These commands only create files. They do not send paper to a printer, select a printer tray, or modify a service. If you use -setpage, however, the output includes a PostScript setpagedevice directive based on the page dimensions. That can affect paper selection when a printer interprets it, and it means the output is not EPS-compliant. Leave the default -nosetpage in place when the result will be embedded as EPS.

5. Select compatibility and compression deliberately

The default PostScript level is 2. Level 1 cannot represent a colour image, so keep the default unless you know the receiving interpreter needs another level and supports the features your input requires.

The default raster encoding is ASCII hexadecimal. -ascii85 makes the text shorter, but needs PostScript Level 2 or newer. -psfilter tells the output to use built-in PostScript filters. It is required with -ascii85 and with -flate:

$ pnmtops -psfilter -ascii85 /path/to/input.pgm > compact.ps
$ pnmtops -psfilter -flate /path/to/input.pgm > compressed.ps

-rle or its synonym -runlength can reduce output for images with long repeated runs, especially when the custom raster path is used. It is not automatically faster, and it often helps less with colour output using -psfilter. The installed build must have the Z library support required by -flate; if it does not, the command fails with an explanatory error.

For an EPS-style result, showpage is included by default and is valid according to the manual's EPS guidance. Use -noshowpage when the program embedding the output needs to control page display itself.

6. Inspect the result and diagnose failures

Check the first line and the document comments without opening the PostScript as an image:

$ sed -n '1,12p' output.ps
%!PS-Adobe-3.0 EPSF-3.0
%%Creator: pnmtops
%%Title: output.ps
...

Exact comments vary with the input name and options. Without -setpage, the first line normally declares EPSF 3.0. With -setpage, the EPSF suffix is omitted because the page-device directive is outside EPSF compliance.

If a file is rejected, rerun with -verbose for informational conversion details:

$ pnmtops -verbose /path/to/input.pgm > checked.ps

Common traps are a non-PNM input, a missing or unreadable path, conflicting size options, and a requested image that does not fit the page. A scale that would overflow the page is ignored with a warning and reduced to fit. A successful exit status confirms that the command completed; it does not confirm that a printer or viewer will render the result as you expect. Test the actual target interpreter when compatibility matters.