Debian Codegraph @

userguide/giftopnm.html

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