NAME

       g3topbm - convert a Group 3 fax file into a PBM image

SYNOPSIS

       g3topbm    [-reversebits]   [-stretch]   [-width=pixels   |   paper_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 tolerates 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  particular,  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
        Common Options ⟨index.html#commonoptions⟩ ), g3topbm  recognizes  the  following  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 duplicating 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 supposed 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 input 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  often  are  corrupted
              because  of communication line errors.  A particularly 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 uncorrupted 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 -correctlong 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; sometimes 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