Convert PBM Pages to G3-Compressed PostScript with pbmtopsg3

You will finish with a PostScript file containing one or more PBM pages, encoded with G3 fax compression. The examples use the installed Netpbm package, version 2:11.05.02-1.1build1, and keep the original PBM files untouched.

Allow about fifteen minutes. You need pbmtopsg3, a readable PBM file, and a directory where you can create a new output file. The normal conversion is an unprivileged operation. You do not need sudo unless ordinary filesystem permissions prevent access to the input or output directory.

1. Check the installed command

Confirm which executable your shell will run and record the package version. These are read-only checks:

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

Your path and package revision may differ. The local manual describes pbmtopsg3 as a converter from PBM to PostScript with G3 fax compression. It accepts one optional input path; with no path, it reads standard input. Its defaults are no PostScript title and 72 dpi.

Checkpoint: if command -v finds nothing, stop here and install Netpbm through your normal package-management process. Do not work around a missing command by guessing another converter's option syntax.

2. Inspect the PBM before converting

Check the file without changing it. The file command is useful for a quick identification, while head shows the beginning of a portable plain PBM file:

$ file /path/to/page.pbm
/path/to/page.pbm: Netpbm image data, size 1728 x 2200, bitmap, ASCII text
$ head -n 3 /path/to/page.pbm
P1
# source: scanned page
1728 2200

Real output varies. The useful checks are that the file is readable, its format is PBM, and its dimensions are plausible. PBM may be plain text or raw binary, so do not assume that every byte is printable. A comment line is optional and may not be present.

Do not delete or edit the source to make the converter accept it. If the file is another Netpbm format, use a separately verified conversion step first. pbmtopsg3 is for PBM input, even though Netpbm's broader tools support more formats.

3. Convert one page without risking an existing output

Choose a new destination name and redirect standard output to it. Shell redirection with > truncates an existing file before the converter starts, so do not point it at a PostScript file you may need:

$ pbmtopsg3 /path/to/page.pbm > /path/to/page.ps
pbmtopsg3: [1]

The bracketed page notice is emitted by this installed build while it processes page 1. It is not the PostScript output; the output itself is written to page.ps. A successful command returns to the prompt with exit status zero. Check both the status and the result:

$ printf 'exit status: %s\n' "$?"
exit status: 0
$ file /path/to/page.ps
/path/to/page.ps: PostScript document text conforming DSC level 3.0
$ grep -E '^(%%Page:|%%Pages:|%%EOF)' /path/to/page.ps
%%Pages: (atend)
%%Page: 1 1
%%Pages: 1
%%EOF

The exact file wording can vary. Look for a non-empty PostScript document and one page marker. To inspect the rendered page, open the result with a trusted PostScript viewer or convert it with a separate tool that you have already verified. A text check cannot prove that the page looks correct.

4. Set a title and resolution when the defaults are wrong

Use --title= to set the PostScript title value and --dpi= to set the output resolution. The default resolution is 72 dpi; it is not inferred from the PBM dimensions. Keep the title as one quoted shell argument:

$ pbmtopsg3 --title='Archive page 001' --dpi=144 \
    /path/to/page.pbm > /path/to/page-144dpi.ps
pbmtopsg3: [1]
$ grep -E '^(%%Title:|%%Page:|%%Pages:)' /path/to/page-144dpi.ps
%%Title: Archive page 001
%%Pages: (atend)
%%Page: 1 1
%%Pages: 1

These options control PostScript metadata and placement resolution. They do not resize the PBM pixels or improve the source scan. If you need a different image size, resize the PBM in a separate, deliberate step and check that result before invoking pbmtopsg3.

Checkpoint: compare the chosen title and dpi with the command you actually ran. If a script silently relies on 72 dpi, make that choice explicit so a later reader does not mistake the default for source metadata.

5. Build a multi-page document from PBM input

A multi-image PBM can be made by concatenating single-image PBM files. This is useful for a small batch, and it does not alter either source file:

$ cat /path/to/page-001.pbm /path/to/page-002.pbm \
    | pbmtopsg3 --title='Two-page fax' > /path/to/two-pages.ps
pbmtopsg3: [1]
pbmtopsg3: [2]
$ grep -E '^%%Page:' /path/to/two-pages.ps
%%Page: 1 1
%%Page: 2 2
$ grep '^%%Pages:' /path/to/two-pages.ps
%%Pages: (atend)
%%Pages: 2

The command reads standard input because no input path was supplied. The order of the files in cat becomes the page order. Keep the input list explicit when order matters; a broad filename glob can include an unintended file or sort differently than you expect.

For a larger batch, first produce an input list that you have reviewed, then pipe the selected files in order. Do not use an unreviewed glob against a directory containing unrelated PBM files. This changes no source data, but it can create a wrong document that looks superficially successful.

6. Handle failures and recover safely

A bad input should produce a non-zero status. For example, text that is not a PBM header is rejected:

$ pbmtopsg3 /path/to/not-a-pbm > /path/to/failed.ps
pbmtopsg3: bad magic number 0x6e6f - not a PPM, PGM, PBM, or PAM file
$ printf 'exit status: %s\n' "$?"
exit status: 1

If the destination did not exist, shell redirection may leave an empty or partial file after a failure. Treat it as disposable: remove that failed output only after checking its exact path, then correct the input and rerun. If the destination already contains a useful document, use a new temporary name and replace the old file only after verification:

$ pbmtopsg3 /path/to/page.pbm > /path/to/page.ps.new
$ test -s /path/to/page.ps.new && grep -q '^%%EOF$' /path/to/page.ps.new
$ mv /path/to/page.ps.new /path/to/page.ps

The final mv is a deliberate replacement. Do not run it if the check fails. If you need to abandon the new result, remove only page.ps.new; the original page.ps remains in place. Neither conversion example changes a service, system configuration or input image.