Convert Group 3 Fax Data with Netpbm

There is no command called faxformat, it is a Netpbm documentation page, and that trips people up before they even start converting a fax file. This guide uses the real commands it describes to turn Group 3 MH fax data into PBM, back again, and through fax-compressed TIFF. The examples use the Netpbm tools installed with package version 2:11.05.02-1.1build1; allow about fifteen minutes and no elevated privileges.

What faxformat(1) actually covers

faxformat(1) is a Netpbm documentation page, not an executable called faxformat. It explains the fax encodings that the other Netpbm programs understand. On this machine, there is no command with that name; the useful commands are g3topbm, pbmtog3, tifftopnm and pamtotiff.

Group 3 is associated with ITU Recommendation T.4. Its three relevant coding methods are MH, MR and MMR. MH compresses each raster line separately and is the format supported by g3topbm and pbmtog3. MR and MMR use more information between lines. The fax-format documentation says that Netpbm does not provide a direct converter for those raw formats.

This distinction is the main trap. A file named .g3 does not prove that it contains MH data, and raw Group 3 data has no signature that lets g3topbm identify its compression method. If you give it MR or MMR, it may print errors and still produce misleading output.

Checkpoint: confirm the tools and versions

1. Check that the four programs are installed.

command -v g3topbm pbmtog3 tifftopnm pamtotiff
dpkg-query -W -f='\${Package} \${Version}\n' netpbm

Expected output includes four paths under /usr/bin and the installed Netpbm package version. The version matters here because the local manuals describe Netpbm 11.x behaviour, including options added after the 2008 faxformat(1) page was written.

Convert an MH fax file to PBM

Use g3topbm when the input is a raw Group 3 MH stream. Redirect standard output to a new file so the source remains untouched.

g3topbm --stop_error /path/to/input.g3 > /path/to/output.pbm

--stop_error makes damaged input a hard failure instead of allowing the program to salvage partial lines. That is the safer choice when the PBM will be archived, printed or passed to another system. Without it, g3topbm can recover lines after an error and warn on standard error, which is useful for rescue work but easy to miss in a script.

Verify the result before using it:

file /path/to/output.pbm
head -n 3 /path/to/output.pbm

A normal binary PBM starts with the magic number P4, followed by width and height information. Do not assume that a zero exit status means the original document was perfect if you deliberately omitted --stop_error; read the warnings as well.

If every line is the wrong width, check the expected paper or pixel width. For example, an A4 fax commonly uses 1728 columns, but the input itself and the sender's settings are authoritative.

g3topbm --paper_size=A4 --stop_error /path/to/input.g3 > /path/to/a4.pbm
g3topbm --width=1728 --stop_error /path/to/input.g3 > /path/to/1728.pbm

Use only one of --paper_size and --width. The program checks the line length against the selected width. If the modem stored bits in the opposite order, retry with --reversebits. A run that produces many bad-code-word messages is a sign to investigate bit order or the input format, not a reason to trust the output.

Convert PBM back to an MH fax stream

To create raw Group 3 MH data, provide a PBM file to pbmtog3 and redirect the binary output. The default crops rows to 1728 columns because that is what many fax machines expect.

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

Keep the original PBM as a recovery copy. If the receiver needs the complete source width, use --nofixedwidth; this changes the generated file and can make it unsuitable for equipment expecting the traditional width.

pbmtog3 --nofixedwidth /path/to/input.pbm > /path/to/full-width.g3

Some receivers require each encoded row to start on a byte or 16-bit boundary. Try --align8 or --align16 only when the receiving software documents that requirement. These options add padding bits, and they cannot be combined.

For a modem or decoder that expects least-significant-bit-first bytes, use --reversebits. The manual warns that this output is not standard G3, so record that choice alongside the file rather than silently replacing the normal output.

Use TIFF as the interchange format

TIFF can contain MH, MR or MMR compression. This is the practical route when a fax arrives as TIFF or when another application needs a TIFF file. Decode it with tifftopnm:

tifftopnm /path/to/input.tiff > /path/to/output.pnm

The output type depends on the TIFF image. A black-and-white input becomes PBM, greyscale becomes PGM, and colour becomes PPM. A multi-image TIFF produces a multi-image PNM stream, so check whether the consumer supports more than one image. For a large or awkward TIFF, --byrow uses less memory, while --respectfillorder makes the decoder follow the TIFF fill-order tag instead of its default handling.

To create a fax-compressed TIFF from a Netpbm image, choose the compression explicitly:

pamtotiff --g3 /path/to/input.pbm > /path/to/output-g3.tiff
pamtotiff --g4 /path/to/input.pbm > /path/to/output-g4.tiff

--g3 asks the TIFF writer for Group 3 compression and --g4 asks for Group 4 compression. For Group 3, the local pamtotiff(1) manual documents --2d as the switch for two-dimensional encoding. That is a TIFF setting, not a promise that raw pbmtog3 output can represent MR.

Creating a file with shell redirection overwrites an existing destination without asking. Use a new path, or stop and inspect the target first:

test ! -e /path/to/output-g3.tiff || {
    printf '%s\n' 'Refusing to overwrite an existing TIFF' >&2
    exit 1
}
pamtotiff --g3 /path/to/input.pbm > /path/to/output-g3.tiff

If the conversion is wrong, delete only the newly created output after checking its exact path, then rerun from the preserved PBM or TIFF source. The commands above do not modify the input files.

Common failure modes

• Bad code words from the first line: check whether the file has a non-fax header, then consider --kludge, which ignores the first few lines. Use it only when the source has been identified as a fax file with junk before the encoded stream.
• Output is twice as wide: a missing end-of-line marker may have joined two rows. g3topbm --correctlong estimates the intended width from the most common line length and truncates longer lines. Do not combine it with --stop_error; the manuals describe those choices as contradictory.
• A raw G3 conversion is unreadable: verify that the data is MH, not MR or MMR. Use TIFF as the boundary when the source or destination supports it.
• Only part of a TIFF appears: inspect whether it has multiple directories. tifftopnm emits all images as one PNM stream on current Netpbm.