Turn an ESC/P2 Printer Stream into a Usable PBM

Someone salvaged a raw print job captured on its way to an old Epson, and escp2topbm turns that stream into a PBM you can view. Along the way you get a quick way to check whether the result is plausible rather than just hoping. The examples use the installed Netpbm 11.5.2 command and write output to temporary files, so they do not send anything to a printer.

Allow about fifteen minutes. You need a shell, the netpbm package, and an ESC/P2 stream saved as a file or available on standard input. You do not need elevated privileges for any step below. The input must contain raster data in the ESC/P2 form that this program understands; an arbitrary printer file is not automatically a valid image.

1. Check the installed command

Confirm which executable will run, then ask Netpbm for its library and build information. Both commands are read-only:

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

The remaining version lines contain build details and can differ between machines. The installed command accepts common Netpbm options such as -version, -quiet and -plain. Its own manual defines no other command-specific options.

Checkpoint: If command -v finds a different path, or the reported version is not 11.5.2, keep that fact beside your output when comparing results.

2. Convert a saved stream

Give the input file as the single optional argument and redirect standard output to a new PBM file:

$ escp2topbm ./printer-stream.escp2 > ./image.pbm
$ printf 'exit status: %s\n' "$?"
exit status: 0

The program reads printer-stream.escp2 and writes the image to standard output. It emits a standard raw PBM, also called binary PBM, by default. A successful exit means that an image was produced, not that the source contained the image you intended.

Inspect the PBM header without opening or altering the file:

$ od -An -c -N32 ./image.pbm
   P   4  \n   8       2   4  \n

P4 identifies raw PBM. The next line contains the width and height; the numbers above are only an example. Do not assume that a stream's paper size or printer resolution is preserved as PBM metadata. PBM carries the bitmap dimensions, not a print instruction.

3. Use standard input in a pipeline

Omit the file argument when another command supplies the ESC/P2 stream. This keeps the conversion composable:

$ cat ./printer-stream.escp2 | escp2topbm > ./image.pbm
$ file ./image.pbm
image.pbm: Netpbm image data, rawbits, 8 x 24

For a real pipeline, replace cat with the command that produces the stream. The pipe is ordinary user-level processing. Keep the redirection target separate from the input so that a shell mistake cannot truncate the source file.

To request an ASCII PBM instead, use the common -plain option:

$ escp2topbm -plain ./printer-stream.escp2 > ./image-plain.pbm
$ od -An -c -N12 ./image-plain.pbm
   P   1  \n   8       2   4  \n

This installed version supports the option. The manual records a compatibility boundary: before Netpbm 10.72, -plain had no effect on escp2topbm. If a script needs ASCII output, check escp2topbm -version rather than silently trusting the header.

4. Verify with a local round trip

If you do not have a printer capture yet, generate a small test stream with Netpbm's companion command. This creates only files under /tmp:

$ printf 'P1\n2 2\n0 1\n1 0\n' > /tmp/escp2-input.pbm
$ pbmtoescp2 /tmp/escp2-input.pbm > /tmp/escp2-stream.bin
$ escp2topbm /tmp/escp2-stream.bin > /tmp/escp2-output.pbm
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ od -An -c -N12 /tmp/escp2-output.pbm
   P   4  \n   8       2   4  \n

The output is wider and taller than the two-by-two source because ESC/P2 raster data is arranged in printer stripes and the generated stream is padded to those boundaries. That padding is not a conversion failure. For a captured stream, compare the header dimensions with the raster area you expect rather than comparing byte-for-byte with a source PBM.

Remove these temporary test files when you no longer need them:

$ rm -f /tmp/escp2-input.pbm /tmp/escp2-stream.bin /tmp/escp2-output.pbm

This cleanup is irreversible for those temporary files, but it does not touch your source stream or the converted image in the working directory. Skip it until you have copied any test output you want to keep.

5. Know what the parser ignores

escp2topbm is a narrow tool by design: it filters raster graphic content from an Epson ESC/P2 control stream and quietly skips everything else. It understands compression modes 0, uncompressed, and 1, RLE compressed. It looks at ESC. sequences and ignores data outside them.

That narrow parser has three practical limits:

Test a suspicious capture without overwriting its source:

$ escp2topbm ./suspect-stream.escp2 > /tmp/suspect.pbm
escp2topbm: No image
$ printf 'exit status: %s\n' "$?"
exit status: 1

The diagnostic is written to standard error and the exit status is non-zero when no image is found. Do not treat a newly created, zero-byte output file as proof that the input was valid. Redirect to a temporary path first, inspect the status, then move or copy it into place only after you have checked the result.

6. Keep output handling safe

Shell redirection truncates an existing destination before the program starts. If image.pbm already matters, choose a new name or use a temporary file in the same directory and rename it only after a successful conversion and header check. A rename changes the destination immediately, so make sure it is the file you intend to replace.

Do not run this command with sudo just because the source came from a printer. Read access to a capture should normally be solved with file permissions or group membership. Elevated privileges would make an accidental output path more dangerous and do not repair malformed ESC/P2 data.

Done means