Turn a PBM Image into an EPSI Preview with pbmtoepsi

You will finish with an EPSI-style preview file generated from a PBM image, a bounding box measured in PostScript points, and a quick way to confirm what the output is. 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 the version on your machine as authoritative. The command reads a PBM image from a named file, or from standard input when no file argument is supplied, and writes the EPSI-style result to standard output.

2. Make or select a PBM page

pbmtoepsi assumes that the PBM describes the whole output page. It treats each PBM pixel as one output-device dot, finds white borders, and describes the non-white principal image with a PostScript bounding box. A small portable PBM is useful 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. If sample.pbm already exists, the redirection replaces it, so choose a fresh working directory or a different name when the input matters. There is no recovery for that overwrite unless you have a backup.

3. Convert the PBM and choose the resolution

Use output redirection to save the EPSI data. The -dpi option is not 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

The first number is horizontal resolution and the second is vertical resolution. A single value, such as -dpi=300, applies to both directions. If you omit the option, the documented default is 72 dots per inch in both directions. That default can produce a physically wrong bounding box when the PBM was prepared for another device.

The command accepts the option as -dpi=100x200 or --dpi 100x200; option names may be abbreviated to a unique prefix. Using the full form makes scripts easier to read. Do not put spaces around the x.

4. Inspect what was generated

Check the file type and the two important metadata lines:

$ 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 pixels high. At 100 horizontal dots per inch and 200 vertical dots per inch, those dimensions become roughly 4.32 by 1.44 PostScript points, which are represented by the integer bounding-box coordinates shown above. The exact placement depends on the border scan and the program's coordinate calculations.

A zero exit status says that the conversion completed. It does not prove that the PBM has the intended artwork or page geometry. Open the EPSI in the application that will consume it, or inspect it through that application's import or preview path. Keep the PBM as the 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

This is metadata only. With no -bbonly, the output includes the EPSI preview bitmap as well. Notice that changing the vertical resolution changes the physical box, so compare files only when their resolution settings match.

There is no inverse epsitopbm tool in this workflow. If the preview has to be regenerated, retain 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 that can be included in an encapsulated PostScript file, not as a stand-alone PostScript document.
• Do not assume pixels equal points. Pixels are converted using the selected dots-per-inch values. 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. Use a new name, or make a backup before regenerating.
• Do not run it as root. Reading an image and writing an output file do not require elevated privileges. Root would only make an accidental destination overwrite more damaging.