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 ), 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

netpbm documentation                              02 July 2023                            G3topbm User Manual(1)