Convert Group 3 Fax Files to PBM with g3topbm

g3topbm turns an MH-compressed Group 3 fax file into a Portable BitMap image, ready for checking or further processing. The commands use the Netpbm package already installed on this machine, version 11.05.02. Allow about 10 minutes if the fax file is ready; investigating a damaged transmission will take longer.

Before you start

You need a Group 3 file using MH, or Modified Huffman, compression. Replace INPUT.g3 with the path to your file. The format has no signature, so g3topbm cannot prove that an arbitrary file is really Group 3 MH data: it will try to decode almost any byte stream. MR and MMR are different Group 3 compression methods and are not supported by this command.

Conversion does not need root privileges. Work in a directory where you can write the output and keep the original input unchanged. The examples create a new file, so there is no destructive step to undo.

1. Convert the fax

Run the basic conversion, redirecting standard output to a new PBM file:

g3topbm INPUT.g3 > output.pbm

A successful conversion normally leaves output.pbm as a raw PBM image. The command writes diagnostics to the terminal when it finds suspicious or damaged data. A warning does not necessarily mean no usable image was produced, because the default mode tries to salvage complete lines.

Check the result before handing it to another program:

file output.pbm
pnmfile output.pbm

Expected output identifies a PBM image and reports its width and height. The exact wording depends on the installed file and Netpbm versions. If pnmfile is unavailable, check the PBM header directly:

head -c 20 output.pbm

Raw PBM starts with P4, followed by the width and height. Do not interpret a P4 header as proof the source was valid: in recovery mode, output can still be made from malformed input.

2. Make width an explicit check

If you know the fax line width, supply it. This is useful when a downstream process must receive a particular canvas size:

g3topbm -width=1728 INPUT.g3 > output-1728.pbm
pnmfile output-1728.pbm

Every decoded line is compared with the requested width. Without -stop_error, a mismatch produces a warning and the command may continue. Add strict checking when a wrong width must not reach the next stage:

g3topbm -width=1728 -stop_error INPUT.g3 > output-1728.pbm
test $? -eq 0 && pnmfile output-1728.pbm

Warning: on failure, the exit status is non-zero and the contents of the output file are undefined. Treat that file as unusable: remove it or overwrite it only after fixing the input. This is the one example in this guide where the command's output must not be trusted after an error.

You can use a paper size instead of a pixel width:

g3topbm -paper_size=A4 INPUT.g3 > output-a4.pbm

Supported values are A3, A4, A5, A6 and B4. The option uses the paper width only; it does not calculate or enforce a paper height. Do not combine -width and -paper_size.

3. Handle common fax quirks

Vertically compressed image. If it was sent in a low-quality mode, duplicate each decoded row:

g3topbm -stretch INPUT.g3 > output-stretched.pbm

Terminal full of bad code word messages. Try the other bit order:

g3topbm -reversebits INPUT.g3 > output-reversed.pbm

Some fax modems store bits least-significant first, while the default interpretation is most-significant first. Compare the dimensions and visual appearance of both outputs. Do not apply this option automatically to every file: it changes how every byte is decoded.

Junk before the fax data. Try:

g3topbm -kludge INPUT.g3 > output-without-prefix.pbm

This ignores the first few lines. It is a recovery aid, not a format detector. Keep the original file, and record that you used the option, because a successful-looking image can still be the wrong part of the input.

4. Recover damaged lines with strict automation

By default, g3topbm attempts to resynchronise after an input error by looking for a later End Of Line marker. It can emit the lines it recovered, including partial recovery before an unexpected end of file. That behaviour is useful for inspection, but it is a poor success criterion for an unattended import. Use -stop_error there, and check the exit status before consuming the PBM.

One specific corruption can merge two fax lines into one very long line. -correctlong estimates the intended width from the line length that occurs most often, then truncates longer lines:

g3topbm -correctlong INPUT.g3 > output-recovered.pbm
pnmfile output-recovered.pbm

This may produce a usable page with a missing line instead of a page that is twice as wide. It is available from Netpbm 11.04, so it is present in the installed 11.05.02 build. There is no useful combination of -correctlong and -stop_error: strict mode is intended to reject the corruption that the recovery option is meant to repair.

Done means