Convert a Page-Sized PBM Image to HP PPA Output

You will finish with an HP Printer Performance Architecture (PPA) data stream made from a PBM page image, ready to pass to the print path for a supported HP PPA printer. The examples use Netpbm pbmtoppa 2:11.05.02-1.1build1, installed on this machine as part of the netpbm package.

Allow about fifteen minutes. You need a shell, a readable PBM file, and a printer or spooler that understands the resulting PPA stream. This converter is not a general image resizer: each PBM image must already have the exact page dimensions expected by the selected paper and resolution. The examples do not need elevated privileges until you deliberately send output to a device or administer a queue.

1. Confirm the installed command

Check which executable will run and record the package version. These are ordinary read-only commands:

$ command -v pbmtoppa
/usr/bin/pbmtoppa
$ dpkg-query -W -f='\${Package} \${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

pbmtoppa does not document a version-printing option in its manpage, so use the package manager on Debian-family systems. On another distribution, use its package query tool and keep the local manpage close at hand, because defaults and diagnostics may differ.

Checkpoint: if command -v finds nothing, stop here and install Netpbm through your normal system package process. Do not copy a random binary into /usr/bin.

2. Check the PBM page dimensions

The input may contain several PBM images. Each image is one page, and every page must match the selected page geometry at 600 pixels per inch unless you deliberately choose another supported resolution with -d. Inspect the file without changing it:

$ file /path/to/page.pbm
/path/to/page.pbm: Netpbm image data, size = 4960 x 7016, rawbits, bitmap

The dimensions in that output are illustrative. Replace the path with your file and use the dimensions reported for your actual paper and converter settings. A PBM with the wrong width or height can produce an unusable stream even when the command exits successfully.

For a calibration pattern, Netpbm provides pbmpage. It generates a 600 dpi PBM test pattern, but its paper-sized output still has to fit the margins and page dimensions accepted by your PPA setup. Generate it in a temporary or working file, then inspect it before conversion:

$ pbmpage 1 > calibration.pbm
$ file calibration.pbm
calibration.pbm: Netpbm image data, size = 5100 x 6600, rawbits, bitmap

Do not treat those sample dimensions as universal. The installed pbmpage documents US paper as 8.5 by 11 inches and A4 as a separate -a4 mode, while pbmtoppa checks the page dimensions against its own printer and paper settings. If it reports that the image is not the size of a page, fix the page generation or margins before sending anything to a printer.

3. Convert one PBM file to a PPA file

Write the converter's standard output to a new file. Keeping the original PBM and choosing a new destination makes a failed conversion easy to recover from:

$ pbmtoppa /path/to/page.pbm /path/to/page.ppa
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ file /path/to/page.ppa
/path/to/page.ppa: data
$ wc -c /path/to/page.ppa
283405 /path/to/page.ppa

The byte count and file description vary with the image, printer version and margins. The useful checks are a zero exit status and a non-empty destination. PPA is a printer data stream, not a format that file will normally identify by name. If the command fails, keep the PBM and remove only the newly created incomplete output after checking the error.

Shell redirection also works when you want standard input or output explicitly:

$ pbmtoppa < /path/to/page.pbm > /path/to/page.ppa
$ test -s /path/to/page.ppa && echo 'PPA output is non-empty'
PPA output is non-empty

Do not redirect to a useful existing PPA file unless you intend to replace it. The shell truncates the destination before pbmtoppa starts.

4. Select the printer and paper settings

Use -v for the printer version documented by the command: 720, 820 or 1000. Use -s us or -s a4 for paper size. For example:

$ pbmtoppa -v 720 -s a4 /path/to/a4-page.pbm /path/to/a4-page.ppa
$ test -s /path/to/a4-page.ppa && echo 'converted'
converted

Choose values that match the actual printer and the PBM page. These options do not resize the input. The default paper setting is us; do not assume A4 merely because the host uses metric locale settings.

The converter also accepts -d for dots per inch and -t, -l, -r and -b for top, left, right and bottom margins. Margin defaults are 150 units, or one quarter of an inch at 600 dpi. The -x and -y options apply horizontal and vertical offset adjustments in 1/600 inch units. Repeating either option accumulates the adjustments, so -x 60 -x 120 means an offset of 180 units, not the last value only.

5. Calibrate offsets before trusting a print

A successful conversion does not prove that the page will land correctly on paper. PPA leaves much of the page and swath processing to the host computer, so printer alignment matters. Send a calibration pattern only when you are ready to consume paper:

$ pbmpage 1 | pbmtoppa -v 720 -s us > calibration.ppa
$ test -s calibration.ppa && echo 'calibration stream created'
calibration stream created

Review calibration.ppa before submitting it to a queue. If you use a direct device such as /dev/lp1, opening it may require elevated privileges and will immediately send printer data:

$ sudo sh -c 'pbmpage 1 | pbmtoppa -v 720 -s us > /dev/lp1'

This is a service-affecting action: the printer may move paper and the output cannot be recalled. Prefer a spooler or a test printer until the settings are verified. If the printer rejects the page and blinks its lights, the manpage points first to material outside the printable area. Increase margins while calibrating, or adjust the -x and -y offsets after measuring the test pattern. At 600 dpi, 600 units equal one inch.

For a spooler, use the queue command and options required by that spooler. The documented example is:

$ pbmtoppa -v 720 -s us /path/to/page.pbm | lpr -l

The -l option is a request to the print filter for direct output, not a universal lpr guarantee. Confirm that your filter supports it. A queued job can be cancelled with your spooler's normal cancellation command if it has not reached the printer; once the printer has accepted the stream, stop using the queue rather than repeatedly resending the same job.

6. Use a configuration file for repeat jobs

For stable printer settings, put the parameters in a file owned by the account that runs the conversion:

# /path/to/pbmtoppa-720.conf
version 720
papersize us
topmargin 150
leftmargin 150
rightmargin 150
bottommargin 150
xoffset 0
yoffset 0

Pass it with -f:

$ pbmtoppa -f /path/to/pbmtoppa-720.conf /path/to/page.pbm /path/to/page.ppa
$ test -s /path/to/page.ppa && echo 'converted with configuration'
converted with configuration

On startup, the program reads /etc/pbmtoppa.conf if it exists, then applies each file named by -f in order, and then processes the remaining command-line options. A later setting therefore overrides an earlier one. Configuration keys may be shortened to an unambiguous prefix, but full names are easier to audit. Protect a shared configuration file from untrusted edits because it controls where print jobs are directed and how they are formatted.

7. Diagnose the common failures

• Input cannot be opened: check the path and read permission with ls -l and test -r. Do not add sudo automatically; changing ownership or permissions may expose the source image.
• Image is not the size of a page: compare the PBM dimensions with the selected printer, paper and resolution. Correct the upstream Ghostscript or Netpbm generation step, or use the documented margin and crop tools during calibration. pbmtoppa is not a resize operation.
• Printer refuses the stream: check the printer version, paper size, offsets and printable margins. A stream that is merely non-empty is not proof that the hardware accepts it.
• Output was overwritten: recover the original PBM or PPA from your backup or source job, then use a new temporary destination and rename it only after validation. There is no undo operation inside pbmtoppa.

Keep the PBM source until the printed result has been inspected. When the conversion is part of a script, check the exit status immediately and test that the output file is non-empty before passing it to a printer or queue.