.TL
G3topbm User Manual
.SH 1
g3topbm
.LP
Updated: 28 February 2006
.br
Table Of Contents
.SH 2
NAME
.LP
g3topbm - convert a Group 3 fax file into a PBM image
.SH 2
SYNOPSIS
.LP
\fBg3topbm\fR
[\fB-kludge\fR]
[\fB-reversebits\fR]
[\fB-stretch\fR]
[{\fB-width=\fR\fIpixels\fR | paper_size={A3,A4,A5,A6,B4}]
[\fB-stop_error\fR]
[\fIg3file\fR]
.LP
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.
.SH 2
DESCRIPTION
.LP
.LP
This program is part of Netpbm.
.LP
\fBg3topbm\fR reads a Group 3 fax file as input and produces a PBM
image as output.
.LP
\fBg3topbm\fR tolerates various deviations from the standard,
so as to recover some of the image if there was a transmission error.
One thing it tolerates is lines of varying length.  The standard requires
all the lines to be the same length; \fBg3topbm\fR 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.
.LP
You can use the \fBstop_error\fR option to make \fBg3topbm\fR
insist on valid input.
.SH 2
OPTIONS
.LP
.RS
.IP "\fB-kludge\fR"
Tells \fBg3topbm\fR to ignore the first few lines of the file;
sometimes fax files have some junk at the beginning.
.IP "\fB-reversebits\fR"
Tells \fBg3topbm\fR 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.
.IP "\fB-stretch\fR"
This option tells \fBg3topbm\fR to stretch the image vertically by
duplicating each row.  This is for the low-quality transmission mode.
.IP "\fB-width=\fR\fIpixels\fR"
This option tells \fBg3topbm\fR that the image is supposed to be
\fIpixels\fR pixels wide.  If any line in it is not that size, \fBg3topbm\fR
issues a warning or fails, depending on whether you specify
\fB-stop_error\fR.
.LP
You cannot specify both \fB-width\fR and \fB-paper_size\fR.
.LP
This option was new in Netpbm 10.33 (March 2006).
.IP "\fB-paper_size=\fR{\fBA3\fR,\fBA4\fR,\fBA5\fR,\fBA6\fR,\fBB4\fR}"
This option tells \fBg3topbm\fR for what size paper this image is
supposed to be formatted.  \fBg3topbm\fR uses the width of the paper
the same way as with the \fB-width\fR option.  \fBg3topbm\fR
does not use the height of the paper for anything.
.LP
You cannot specify both \fB-width\fR and \fB-paper_size\fR.
.LP
This option was new in Netpbm 10.33 (March 2006).
.IP "\fB-stop_error\fR"
This option tells \fBg3topbm\fR 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.
.LP
If you don't specify this option, \fBg3topbm\fR 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,
\fBg3topbm\fR produces output containing the lines up to where it
encountered the problem.
.LP
\fBg3topbm\fR issues warning messages when it continues in spite of
input errors.
.LP
This option was new in Netpbm 10.24 (August 2004).  Before that,
\fBg3topbm\fR always failed when it encountered premature EOF and
never failed when it encountered other problems.
.RE
.SH 2
ABOUT G3
.LP
.LP
G3 is the near universal format used by fax machines.  There is also
a newer, more capable G4.
.LP
The standard for Group 3 fax is defined in CCITT Recommendation T.4.
In the U.S., that is implemented by EIA standards EIA-465 and EIA-466.
These standards cover the layers below the image format (which are
irrelevant to \fBg3topbm\fR as well.
.LP
G3 faxes are 204 dots per inch (dpi) horizontally and 98 dpi (196
dpi optionally, in fine-detail mode) vertically.  Since G3 neither
assumes error free transmission nor retransmits when errors occur, the
encoding scheme used is differential only over small segments never
exceeding 2 lines at standard resolution or 4 lines for fine-detail.
(The incremental G3 encoding scheme is called two-dimensional and the
number of lines so encoded is specified by a parameter called k.)
.SH 2
SEE ALSO
.LP
pbmtog3,
pbm
.br
\l'5i'
.SH 2
Table Of Contents
.LP
.IP \(bu
SYNOPSIS
.IP \(bu
DESCRIPTION
.IP \(bu
OPTIONS
.IP \(bu
ABOUT G3
.IP \(bu
SEE ALSO
.LP