Debian Codegraph @

upstream/debian-unstable/man1/g3topbm.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "G3topbm User Manual" 1 "02 July 2023" "netpbm documentation"
7
8 .SH NAME
9 g3topbm - convert a Group 3 fax file into a PBM image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBg3topbm\fP
15 [\fB-reversebits\fP]
16 [\fB-stretch\fP]
17 [\fB-width=\fP\fIpixels\fP | paper_size={A3|A4|A5|A6|B4}]
18 [\fB-stop_error\fP]
19 [\fB-correctlong\fP]
20 [\fB-kludge\fP]
21 [\fIg3file\fP]
22 .PP
23 Minimum unique abbreviation of option is acceptable. You may use double
24 hyphens instead of single hyphen to denote options. You may use white
25 space in place of the equals sign to separate an option name from its value.
26
27 .UN description
28 .SH DESCRIPTION
29 .PP
30 This program is part of
31 .BR "Netpbm" (1)\c
32 \&.
33 .PP
34 \fBg3topbm\fP reads a Group 3 fax file with MH (Modified Huffman)
35 compression as input and produces a PBM image as output.
36 .PP
37 \fBg3topbm\fP tolerates various deviations from the standard,
38 so as to recover some of the image if there was a transmission error.
39 One thing it tolerates is lines of varying length. The standard requires
40 all the lines to be the same length; \fBg3topbm\fP makes the output
41 image as wide as the longest line in the input and pads the others on
42 the right. It warns you when it does this.
43 .PP
44 You can use the \fBstop_error\fP option to make \fBg3topbm\fP
45 insist on valid input.
46 .PP
47 There is no Netpbm program that understands the other G3 fax
48 compression methods: MR (Modified Read) and MMR (Modified Modified Read).
49 .PP
50 Note that the Group 3 fax file format does not include any kind of a
51 signature so that \fBg3topbm\fP might verify it's actually looking at a G3
52 file or that the compression method is MH. The program will interpret any
53 sequence of bytes you give it as if it is G3 and, while typically issuing a
54 lot of error messages about the file not conforming to the G3 MH format, will
55 produce output (unless you use
56 \fB-stoperror\fP). In particular, if you feed \fBg3topbm\fP an MR or MMR
57 file, it will not tell you of your mistake.
58 .PP
59 There are subformats of TIFF that use the Group 3 fax encodings
60 inside. See \fBtifftopnm\fP.
61
62
63 .UN options
64 .SH OPTIONS
65 .PP
66 In addition to the options common to all programs based on libnetpbm
67 (most notably \fB-quiet\fP, see
68 .UR index.html#commonoptions
69 Common Options
70 .UE
71 \&), \fBg3topbm\fP recognizes the following
72 command line options:
73
74
75 .TP
76 \fB-reversebits\fP
77 Tells \fBg3topbm\fP to interpret bits least-significant first,
78 instead of the default most-significant first. Apparently some fax
79 modems do it one way and others do it the other way. If you get a
80 whole bunch of "bad code word" messages, try using this
81 option.
82
83 .TP
84 \fB-stretch\fP
85 This option tells \fBg3topbm\fP to stretch the image vertically by
86 duplicating each row. This is for the low-quality transmission mode.
87
88 .TP
89 \fB-width=\fP\fIpixels\fP
90 This option tells \fBg3topbm\fP that the image is supposed to be
91 \fIpixels\fP pixels wide. If any line in it is not that size, \fBg3topbm\fP
92 issues a warning or fails, depending on whether you specify
93 \fB-stop_error\fP.
94 .sp
95 You cannot specify both \fB-width\fP and \fB-paper_size\fP.
96 .sp
97 This option was new in Netpbm 10.33 (March 2006).
98
99 .TP
100 \fB-paper_size=\fP{\fBA3\fP,\fBA4\fP,\fBA5\fP,\fBA6\fP,\fBB4\fP}
101 This option tells \fBg3topbm\fP for what size paper this image is
102 supposed to be formatted. \fBg3topbm\fP uses the width of the paper
103 the same way as with the \fB-width\fP option. \fBg3topbm\fP
104 does not use the height of the paper for anything.
105 .sp
106 You cannot specify both \fB-width\fP and \fB-paper_size\fP.
107 .sp
108 This option was new in Netpbm 10.33 (March 2006).
109
110 .TP
111 \fB-stop_error\fP
112 This option tells \fBg3topbm\fP to fail when it finds a problem
113 in the input. "Fail" means it terminates with a nonzero
114 status code with the contents of the output file undefined.
115 .sp
116 If you don't specify this option, \fBg3topbm\fP does its best to
117 work around input errors and salvage as much of the image as possible
118 in the output image. It first tries to resynchronize to a later line
119 by searching for the next End Of Line marker, skipping any lines or
120 partial lines in between. It saves the beginning of the line in which
121 it encountered the problem. If the input file ends prematurely,
122 \fBg3topbm\fP produces output containing the lines up to where it
123 encountered the problem.
124 .sp
125 \fBg3topbm\fP issues warning messages when it continues in spite of
126 input errors.
127 .sp
128 This option was new in Netpbm 10.24 (August 2004). Before that,
129 \fBg3topbm\fP always failed when it encountered premature EOF and
130 never failed when it encountered other problems.
131 \fB-correctlong\fP
132 .sp
133 This option helps with certain corrupted input files. Faxes often are
134 corrupted because of communication line errors. A particularly annoying
135 corruption causes a line to be much longer than it is supposed to be. One way
136 that can happen is where an End of Line marker is missing, so two consecutive
137 lines turn into one.
138 .sp
139 Without this option, \fBg3topbm\fP faithfully renders the document as
140 coded, so the output PBM image simply contains that long line. This is an
141 especially problematic corruption because it makes the entire output image
142 about twice as wide as it is supposed to be. But with \fB-correctlong\fP,
143 \fBg3topbm\fP truncates that line so the overall effect of the input
144 corruption is that a line is missing rather than that the image is twice as
145 wide as it is supposed to be.
146 .sp
147 Specifically, with \fB-correctlong\fP, the program looks at the lengths of
148 all the lines (which would all be the same length in an uncorrupted G3 image)
149 and considers the line length that occurs the most to be the intended image
150 width. It truncates every line that is longer than that.
151 .sp
152 The program warns you when corruption has caused the input image to have
153 lines of more than one length, whether you specify \fB-correctlong\fP or not.
154 .sp
155 Note that there is no point to specifying \fB-correctlong\fP if you also
156 specify \fB-stop_error\fP.
157 .sp
158 This option was new in Netpbm 11.04 (September 2023).
159
160 .TP
161 \fB-kludge\fP
162 Tells \fBg3topbm\fP to ignore the first few lines of the file; sometimes
163 fax files have some junk at the beginning.
164
165
166
167
168 .UN seealso
169 .SH SEE ALSO
170 .BR "pbmtog3" (1)\c
171 \&,
172 .BR "tifftopnm" (1)\c
173 \&,
174 .BR "pbm" (1)\c
175 \&,
176 .BR "fax formats" (1)\c
177 \&
178 .SH DOCUMENT SOURCE
179 This manual page was generated by the Netpbm tool 'makeman' from HTML
180 source. The master documentation is at
181 .IP
182 .B http://netpbm.sourceforge.net/doc/g3topbm.html
183 .PP