Convert PBM Images to Group 3 Fax Files with pbmtog3

You will convert a PBM bitmap into a Group 3 MH fax file, keep the source unchanged, and check the result with Netpbm's decoder. Allow about ten minutes if you already have a PBM image and the output dimensions are understood. The examples use Netpbm 11.5.2, installed here as package version 2:11.05.02-1.1build1.

You need the netpbm package, a readable PBM file, and a writable destination directory. Conversion normally needs no elevated privileges. Do not use sudo just to read an image or create a file in your own working directory.

1. Check the installed tools

Confirm that the converter is the command you expect, and check that the optional decoder is available for verification:

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

Your package manager may report a different version. The manual page documents the behaviour used here. The installed command does not provide a useful option summary: pbmtog3 --help tells you to use the manual page instead.

2. Convert a PBM file without replacing an existing result

Supply the input path and redirect standard output to a new filename:

$ pbmtog3 /path/to/input.pbm > /path/to/output.g3

The command writes the fax data to standard output and normally prints no progress message. Shell redirection with > truncates an existing destination before conversion starts. Choose a new name, or use a temporary output and rename it only after verification:

$ pbmtog3 /path/to/input.pbm > /path/to/output.g3.new
$ test -s /path/to/output.g3.new
$ mv /path/to/output.g3.new /path/to/output.g3

The last command replaces the old file only after the converter has exited successfully and produced a non-empty file. If conversion fails, leave the original in place and inspect the error. Remove the incomplete .new file manually after checking it; do not delete the source PBM as part of this workflow.

3. Understand the 1728-column default

Most fax machines expect 1728 columns, so pbmtog3 cuts the output to that width by default. This is the easiest behaviour to miss when converting a small test image or a bitmap whose width is deliberately significant. The manual says that -nofixedwidth preserves the original width.

Use that option when the receiver or your later processing step needs the PBM's width:

$ pbmtog3 -nofixedwidth /path/to/input.pbm > /path/to/input-width.g3
$ g3topbm /path/to/input-width.g3 > /path/to/roundtrip.pbm
$ file /path/to/roundtrip.pbm
/path/to/roundtrip.pbm: Netpbm image data, size = 8 x 4, rawbits, bitmap

The displayed dimensions are an example for an 8 by 4 source. With the default settings, the same source decodes as 1728 columns by 4 rows on the installed tools. A successful conversion therefore does not prove that the width was what you intended.

4. Verify the encoding and dimensions

Use g3topbm when it is installed. It reads the Group 3 file and emits a PBM image, so redirect its output rather than allowing binary data into your terminal:

$ g3topbm /path/to/output.g3 > /tmp/decoded.pbm
$ file /tmp/decoded.pbm
/tmp/decoded.pbm: Netpbm image data, size = 1728 x 4, rawbits, bitmap
$ head -c 2 /tmp/decoded.pbm
P4

Check the decoded dimensions against the intended fax page. The round trip checks that a decoder can read the file; it does not prove that a fax device accepts every transport or page-layout convention. Keep the original PBM until the decoded image has been inspected or passed to the next tested stage.

5. Choose row alignment only when required

By default, rows have no padding and may start or end anywhere within a byte. -align8 adds padding so output rows align to 8-bit boundaries; -align16 does the same for 16-bit boundaries.

$ pbmtog3 -align8 /path/to/input.pbm > /path/to/aligned8.g3
$ pbmtog3 -align16 /path/to/input.pbm > /path/to/aligned16.g3

These options are alternatives. Do not pass both. They were added in Netpbm 10.79, released in June 2017, so older installations may reject them. Use alignment only when the receiving software requires it; it is not needed for ordinary Group 3 output.

6. Handle bit order and common failures

If a reader reports many bad code words, try -reversebits for that reader's expected bit order:

$ pbmtog3 -reversebits /path/to/input.pbm > /path/to/reversed.g3

The manual warns that the result with this option is not G3 in the usual sense. Treat it as a compatibility workaround for hardware or software that expects reversed bits, not as a general improvement.

An input-open error usually means the path, permissions, or file type is wrong. Check without changing anything:

$ ls -l /path/to/input.pbm
$ file /path/to/input.pbm
$ test -r /path/to/input.pbm && echo readable

If the decoder reports bad code words, first confirm that you selected the correct output and did not redirect diagnostic text into it. Then test -reversebits only if the receiving reader documents that expectation. If the decoded width is wrong, choose between the default fixed width and -nofixedwidth; changing alignment does not change the image width.