Debian Codegraph @

upstream/debian-unstable/man1/giftopnm.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 "Giftopnm User Manual" 1 "13 September 2012" "netpbm documentation"
7
8 .SH NAME
9 giftopnm - convert a GIF file into a PNM image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBgiftopnm\fP
15 [\fB--alphaout=\fP{\fIalpha-filename\fP,\fB-\fP}]
16 [\fB-verbose\fP]
17 [\fB-comments\fP]
18 [\fB-image=\fP{\fIN\fP,\fBall\fP}]
19 [\fB-repair\fP]
20 [\fB-quitearly\fP]
21 [\fIGIFfile\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 This is a graphics format converter from the GIF format to the PNM
35 (i.e. PBM, PGM, or PPM) format.
36 .PP
37 If the image contains only black and maximally bright white, the
38 output is PBM. If the image contains more than those two colors, but
39 only grays, the output is PGM. If the image contains other colors,
40 the output is PPM.
41 .PP
42 A GIF image contains rectangular pixels. They all have the same
43 aspect ratio, but may not be square (it's actually quite unusual for
44 them not to be square, but it could happen). The pixels of a Netpbm
45 image are always square. Because of the engineering complexity to do
46 otherwise, \fBgiftopnm\fP converts a GIF image to a Netpbm image
47 pixel-for-pixel. This means if the GIF pixels are not square, the
48 Netpbm output image has the wrong aspect ratio. In this case,
49 \fBgiftopnm\fP issues an informational message telling you to run
50 \fBpamscale\fP to correct the output.
51
52 .UN options
53 .SH OPTIONS
54 .PP
55 In addition to the options common to all programs based on libnetpbm
56 (most notably \fB-quiet\fP, see
57 .UR index.html#commonoptions
58 Common Options
59 .UE
60 \&), \fBgiftopnm\fP recognizes the following
61 command line options:
62
63
64 .TP
65 \fB--alphaout=\fP\fIalpha-filename\fP
66 \fBgiftopnm \fP creates a PBM file containing the transparency
67 information from the input image. This transparency image is the same
68 dimensions as the input image, and each pixel of the transparency image tells
69 whether the corresponding pixel of the input image is transparent. Black
70 means transparent; white means opaque. If you don't
71 specify \fB--alphaout\fP, \fBgiftopnm\fP does not generate a transparency
72 file, and if the input image has a transparency channel, \fBgiftopnm\fP simply
73 discards it.
74 .sp
75 If you specify \fB-\fP as the filename, \fBgiftopnm\fP writes the
76 transparency output to Standard Output and discards the image.
77 .sp
78 See
79 .BR "pamcomp" (1)\c
80 \& for one way to use
81 the transparency output file.
82
83 .TP
84 \fB-verbose\fP
85 Produce verbose output about the GIF file input.
86
87 .TP
88 \fB-comments\fP
89 With this option, \fBgiftopnm\fP issues messages showing the GIF comments
90 (A GIF89 stream can contain comments in comment extensions).
91 .sp
92 By default, \fBgiftopnm\fP ignores comment extensions.
93
94
95 .TP
96 \fB-image=\fP{\fIN\fP,\fBall\fP}
97 This option identifies which image from the GIF stream you want.
98 You can select either one image or all the images. Select all the
99 images with \fBall\fP. Select one image by specifying its sequence
100 number in the stream: \fB1\fP, \fB2\fP, \fB3\fP, etc.
101 .sp
102 The default is just Image 1.
103 .sp
104 A GIF stream normally contains only one image, so you don't need
105 this option. But some streams, including animated GIFs, have multiple
106 images.
107 .sp
108 When you select multiple GIF images, the output is a PNM stream with
109 multiple images.
110 .sp
111 If you specify a single image, \fBgiftopnm\fP must read and
112 partially validate the images before that in the stream. It may or may
113 not do the same for the images after it; see \fB-quitearly\fP.
114 .sp
115 The \fBall\fP value was added in Netpbm 10.16 (June 2003). Earlier
116 \fBgiftopnm\fP can extract only one image.
117
118 .TP
119 \fB-repair\fP
120 This option makes \fBgiftopnm\fP try to salvage what it can from an
121 invalid GIF input.
122 .sp
123 In particular, when \fBgiftopnm\fP detects that the GIF input is
124 invalid so that it is impossible to determine what the pixels are
125 intended to be, it produces a single arbitrary color for all further
126 pixels in the image. \fBgiftopnm\fP processes the image from top to
127 bottom, left to right, so this means the bottommost pixels will be
128 this padding.
129 .sp
130 \fBgiftopnm\fP issues warning messages when it salvages an image
131 in this way.
132 .sp
133 Without this option, \fBgiftopnm\fP fails when it detects invalid
134 GIF input. Any output it produces is arbitrary, and typically is not
135 a valid PNM image.
136 .sp
137 It is fairly common for an image to be corrupted such that is
138 started off as a valid GIF, but had the end of the file cut off. An
139 interrupted network transfer tends to do this. In this case,
140 \fBgiftopnm\fP's salvage operation will produce a valid PNM image of
141 the proper dimensions, but with a single arbitrary color for the pixels
142 that were left out of the file.
143 .sp
144 This option was new in Netpbm 10.38 (March 2007). From 10.32 through
145 10.37, \fBgiftopnm\fP always fails if it detects invalid GIF input.
146 Before 10.32, it succeeds in the case of a truncated image, and replaces
147 the missing pixels with arbitrary colors, not necessarily all the same
148 (The pre-10.32 behavior wasn't actually intended by the design).
149
150
151 .TP
152 \fB-quitearly\fP
153 This option makes \fBgiftopnm\fP stop reading its input file as soon
154 as it has converted and output the images from the input that you requested.
155 By default, \fBgiftopnm\fP reads until the end of the GIF stream, ignoring
156 any data after the images you requested.
157 .sp
158 Two reasons \fInot\fP to use this option:
159
160 .IP \(bu
161 The input file is a pipe and the process that is filling that pipe
162 expects the pipe to take the entire stream and will fail or get stuck
163 if it doesn't.
164
165 .IP \(bu
166 You want to validate the entire GIF stream.
167
168
169 .sp
170 Two reasons to use this option:
171
172
173 .IP \(bu
174 It saves the time and other resources to read the end of the stream.
175 .IP \(bu
176 There are errors in the end of the stream that make \fBgiftopnm\fP fail.
177
178 .sp
179 This option has no effect if you also specify \fB-image=all\fP
180 .sp
181 This option was new in Netpbm 10.35 (August 2006). Before that,
182 \fBgiftopnm\fP always reads the entire stream.
183
184
185
186 .UN restrictions
187 .SH RESTRICTIONS
188 .PP
189 This does not correctly handle the Plain Text Extension of the
190 GIF89 standard, since I did not have any example input files
191 containing them.
192
193 .UN seealso
194 .SH SEE ALSO
195 .BR "pamtogif" (1)\c
196 \&,
197 .BR "ppmcolormask" (1)\c
198 \&,
199 .BR "pamcomp" (1)\c
200 \&,
201 .UR http://www.lcdf.org/gifsicle
202 http://www.lcdf.org/gifsicle
203 .UE
204 \&,
205 .BR "ppm" (1)\c
206 \&.
207
208 .UN author
209 .SH AUTHOR
210 .PP
211 Copyright (c) 1993 by David Koblas (\[email protected]\fP)
212
213 .UN license
214 .SH LICENSE
215 .PP
216 As a historical note, for a long time if you used \fBgiftopnm\fP,
217 you were using a patent on the LZW compression method which was owned
218 by Unisys, and in all probability you did not have a license from
219 Unisys to do so. Unisys typically asked $5000 for a license for
220 trivial use of the patent. Unisys never enforced the patent against
221 trivial users, and made statements that it is much less concerned
222 about people using the patent for decompression (which is what
223 \fBgiftopnm\fP does than for compression. The patent expired in
224 2003.
225 .PP
226 Rumor has it that IBM also owns a patent covering \fBgiftopnm\fP.
227 .PP
228 A replacement for the GIF format that has never required any patent
229 license to use is the PNG format.
230 .SH DOCUMENT SOURCE
231 This manual page was generated by the Netpbm tool 'makeman' from HTML
232 source. The master documentation is at
233 .IP
234 .B http://netpbm.sourceforge.net/doc/giftopnm.html
235 .PP