Turn a PBM Image into an EPSI Preview with pbmtoepsi

pbmtoepsi builds an EPSI preview from a PBM image, with a bounding box in PostScript points, for embedding in an encapsulated PostScript file. The examples use the installed Netpbm 11.5.2 command on Debian or Ubuntu.

Allow about fifteen minutes. You need a shell, the netpbm package, and a PBM file that represents a complete output page. This is an ordinary user-space conversion: no command here needs sudo. Keep the original PBM until the generated preview has been checked.

1. Check the installed command

Confirm which executable will run and record the package version:

$ command -v pbmtoepsi
/usr/bin/pbmtoepsi
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1
$ pbmtoepsi --version
pbmtoepsi: Using libnetpbm from Netpbm Version: Netpbm 11.5.2

The version diagnostic also prints build details. Exact package revisions vary, so treat your own machine's version as authoritative. The command reads a PBM image from a named file, or from standard input when none is given, and writes the EPSI-style result to standard output.

2. Make or select a PBM page

pbmtoepsi assumes the PBM describes the whole output page. It treats each pixel as one output-device dot, finds the white borders, and describes the non-white principal image with a PostScript bounding box. A small portable PBM is enough for a smoke test:

$ cat > sample.pbm <<'PBM'
P1
# A page with a white border and a dark rectangular mark
8 6
0 0 0 0 0 0 0 0
0 1 1 1 1 1 1 0
0 1 0 0 0 0 1 0
0 1 0 0 0 0 1 0
0 1 1 1 1 1 1 0
0 0 0 0 0 0 0 0
PBM
$ file sample.pbm
sample.pbm: Netpbm image data, size = 8 x 6, format = ASCII bitmap

In PBM, 0 is white and 1 is black. The heredoc creates a new file, and if sample.pbm already exists, it just gets overwritten: choose a fresh working directory or a different name when the input matters, because there's no recovery from that overwrite without a backup.

3. Convert the PBM and choose the resolution

Use output redirection to save the EPSI data. The -dpi option isn't an image resampling control: it tells the program the ultimate output device resolution so it can turn pixel counts into absolute distances for the bounding box:

$ pbmtoepsi -dpi=100x200 sample.pbm > sample.epsi
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ sed -n '1,8p' sample.epsi
%!PS-Adobe-2.0 EPSF-1.2
%%BoundingBox: 1 1 4 2
%%BeginPreview: 6 4 1 4
% fc
% 84
% 84
% fc
%%EndImage

• First number is horizontal, second is vertical. A single value like -dpi=300 applies to both.
• Omit the option and the documented default is 72 dots per inch both ways, which can give a physically wrong bounding box if the PBM was prepared for another device.
• Both spellings work. -dpi=100x200 or --dpi 100x200, and option names can be abbreviated to a unique prefix. Use the full form in scripts, and don't put spaces around the x.

4. Inspect what was generated

Check the file type and the two metadata lines that matter:

$ file sample.epsi
sample.epsi: PostScript document text conforming DSC level 2.0, type EPS
$ grep -E '^%%(BoundingBox|BeginPreview):' sample.epsi
%%BoundingBox: 1 1 4 2
%%BeginPreview: 6 4 1 4

For this 8 by 6 test image, the non-white area is six pixels wide and four high. At 100 horizontal and 200 vertical dots per inch, those dimensions become roughly 4.32 by 1.44 PostScript points, rounded to the integer bounding-box coordinates above. Exact placement depends on the border scan and the program's own coordinate calculations.

A zero exit status only says the conversion completed, not that the PBM had the intended artwork or page geometry. Open the EPSI in the application that will actually consume it, and keep the PBM as your source of truth.

5. Generate only the bounding box when that is the job

Use -bbonly when you need the bounding-box header without the preview bitmap:

$ pbmtoepsi -dpi=100 -bbonly sample.pbm > sample-bbox.epsi
$ cat sample-bbox.epsi
%!PS-Adobe-2.0 EPSF-1.2
%%BoundingBox: 1 1 4 4

That's metadata only. Without -bbonly, the output includes the EPSI preview bitmap too. Changing the vertical resolution changes the physical box, so only compare files whose resolution settings match.

There's no inverse epsitopbm tool in this workflow. If the preview needs regenerating, keep the PBM and rerun the conversion with the corrected resolution or source image.

6. Avoid the common boundary errors

• Do not treat the result as a complete drawing. The manpage describes it as a preview bitmap meant for an encapsulated PostScript file, not a stand-alone PostScript document.
• Do not assume pixels equal points. Pixels are converted using the selected dots-per-inch values, so record those values beside generated assets.
• Do not use a cropped PBM by accident. The program expects the input to represent the whole page and uses white borders to locate the principal image.
• Do not overwrite the source or a reviewed output. Shell redirection truncates an existing destination before the command runs, so use a new name or back up first.
• Do not run it as root. Reading an image and writing an output file need no elevated privileges. Root just makes an accidental overwrite more damaging.