G3topbm User Manual(1) General Commands Manual G3topbm User Manual(1)
NAME
g3topbm - convert a Group 3 fax file into a PBM image
SYNOPSIS
g3topbm [-reversebits] [-stretch] [-width=pixels | pa-
per_size={A3|A4|A5|A6|B4}] [-stop_error] [-correctlong] [-kludge]
[g3file]
Minimum unique abbreviation of option is acceptable. You may use double
hyphens instead of single hyphen to denote options. You may use white
space in place of the equals sign to separate an option name from its
value.
DESCRIPTION
This program is part of Netpbm(1).
g3topbm reads a Group 3 fax file with MH (Modified Huffman) compression
as input and produces a PBM image as output.
g3topbm tolerates various deviations from the standard, so as to recover
some of the image if there was a transmission error. One thing it tol-
erates is lines of varying length. The standard requires all the lines
to be the same length; g3topbm makes the output image as wide as the
longest line in the input and pads the others on the right. It warns
you when it does this.
You can use the stop_error option to make g3topbm insist on valid input.
There is no Netpbm program that understands the other G3 fax compression
methods: MR (Modified Read) and MMR (Modified Modified Read).
Note that the Group 3 fax file format does not include any kind of a
signature so that g3topbm might verify it's actually looking at a G3
file or that the compression method is MH. The program will interpret
any sequence of bytes you give it as if it is G3 and, while typically
issuing a lot of error messages about the file not conforming to the G3
MH format, will produce output (unless you use -stoperror). In particu-
lar, if you feed g3topbm an MR or MMR file, it will not tell you of your
mistake.
There are subformats of TIFF that use the Group 3 fax encodings inside.
See tifftopnm.
OPTIONS
In addition to the options common to all programs based on libnetpbm
(most notably -quiet, see ]8;;index.html#commonoptions\ Common Options]8;;\ ), g3topbm recognizes the fol-
lowing command line options:
-reversebits
Tells g3topbm to interpret bits least-significant first, instead
of the default most-significant first. Apparently some fax
modems do it one way and others do it the other way. If you get
a whole bunch of "bad code word" messages, try using this option.
-stretch
This option tells g3topbm to stretch the image vertically by du-
plicating each row. This is for the low-quality transmission
mode.
-width=pixels
This option tells g3topbm that the image is supposed to be pixels
pixels wide. If any line in it is not that size, g3topbm issues
a warning or fails, depending on whether you specify -stop_error.
You cannot specify both -width and -paper_size.
This option was new in Netpbm 10.33 (March 2006).
-paper_size={A3,A4,A5,A6,B4}
This option tells g3topbm for what size paper this image is sup-
posed to be formatted. g3topbm uses the width of the paper the
same way as with the -width option. g3topbm does not use the
height of the paper for anything.
You cannot specify both -width and -paper_size.
This option was new in Netpbm 10.33 (March 2006).
-stop_error
This option tells g3topbm to fail when it finds a problem in the
input. "Fail" means it terminates with a nonzero status code
with the contents of the output file undefined.
If you don't specify this option, g3topbm does its best to work
around input errors and salvage as much of the image as possible
in the output image. It first tries to resynchronize to a later
line by searching for the next End Of Line marker, skipping any
lines or partial lines in between. It saves the beginning of the
line in which it encountered the problem. If the input file ends
prematurely, g3topbm produces output containing the lines up to
where it encountered the problem.
g3topbm issues warning messages when it continues in spite of in-
put errors.
This option was new in Netpbm 10.24 (August 2004). Before that,
g3topbm always failed when it encountered premature EOF and never
failed when it encountered other problems. -correctlong
This option helps with certain corrupted input files. Faxes of-
ten are corrupted because of communication line errors. A par-
ticularly annoying corruption causes a line to be much longer
than it is supposed to be. One way that can happen is where an
End of Line marker is missing, so two consecutive lines turn into
one.
Without this option, g3topbm faithfully renders the document as
coded, so the output PBM image simply contains that long line.
This is an especially problematic corruption because it makes the
entire output image about twice as wide as it is supposed to be.
But with -correctlong, g3topbm truncates that line so the overall
effect of the input corruption is that a line is missing rather
than that the image is twice as wide as it is supposed to be.
Specifically, with -correctlong, the program looks at the lengths
of all the lines (which would all be the same length in an uncor-
rupted G3 image) and considers the line length that occurs the
most to be the intended image width. It truncates every line
that is longer than that.
The program warns you when corruption has caused the input image
to have lines of more than one length, whether you specify -cor-
rectlong or not.
Note that there is no point to specifying -correctlong if you
also specify -stop_error.
This option was new in Netpbm 11.04 (September 2023).
-kludge
Tells g3topbm to ignore the first few lines of the file; some-
times fax files have some junk at the beginning.
SEE ALSO
pbmtog3(1), tifftopnm(1), pbm(1), fax formats(1)
DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source. The master documentation is at
http://netpbm.sourceforge.net/doc/g3topbm.html
netpbm documentation 02 July 2023 G3topbm User Manual(1)
Generated by dwww version 1.16 on Tue Dec 16 04:54:03 CET 2025.