diff options
Diffstat (limited to 'upstream/debian-bookworm/man1/pamtogif.1')
| -rw-r--r-- | upstream/debian-bookworm/man1/pamtogif.1 | 405 |
1 files changed, 405 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man1/pamtogif.1 b/upstream/debian-bookworm/man1/pamtogif.1 new file mode 100644 index 00000000..26958a44 --- /dev/null +++ b/upstream/debian-bookworm/man1/pamtogif.1 @@ -0,0 +1,405 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Pamtogif User Manual" 1 "09 June 2021" "netpbm documentation" + +.SH NAME +pamtogif - convert a Netpbm image to a GIF image + +.UN synopsis +.SH SYNOPSIS + +\fBpamtogif\fP + +[\fB-interlace\fP] + +[\fB-sort\fP] + +[\fB-mapfile=\fP\fImapfile\fP] +[\fB-transparent=\fP[\fB=\fP]\fIcolor\fP] + +[\fB-alphacolor=\fP\fIcolor\fP] + +[\fB-comment=\fP\fItext\fP] + +[\fB-noclear\fP] + +[\fB-nolzw\fP] + +[\fB-aspect=\fP\fIfraction\fP] + +[\fB-verbose\fP] +[\fInetpbmfile\fP] +.PP +All options can be abbreviated to their shortest unique prefix. You +may use two hyphens instead of one to designate an option. You may +use either white space or an equals sign between an option name and its +value. + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBpamtogif\fP reads a Netpbm image as input and produces a GIF file +as output. +.PP +This program creates only individual GIF images. To combine +multiple GIF images into an animated GIF, use +.UR http://www.lcdf.org/gifsicle/ +\fBgifsicle\fP +.UE +\& (not part of +the Netpbm package). +.PP +\fBpamtogif\fP creates either an original GIF87 format GIF file or the + newer GIF89 format. It creates GIF89 when the output needs to have features + that were new with GIF89, to wit transparency or comments. Otherwise, it + creates GIF87. Really old GIF readers conceivably could not recognize + GIF89. The output needs to have transparency when either the input has a + transparency information or you specify the \fB-transparent\fP option. It + needs to have comments when you specify the + \fB-comment\fP option. +.PP +\fBpamtogif\fP generates a GIF image with a single image block, which +means the image cannot have more than 256 colors in it (it contains a single +color map with a maximum size of 256). If the image you want to convert has +more colors than that (\fBppmhist\fP can tell you), you can +use \fBpnmquant\fP to reduce it to 256. Or use the more complex but faster +method described under the \fB-mapfile\fP option. +.PP +If your input image is a PAM with transparency information, \fBpamtogif\fP +uses one entry in the GIF colormap specifically for the transparent pixels, +so you can have at most 255 opaque colors. In contrast, if you use the +\fB-transparent\fP option, one of the colors from the input becomes +transparent, so the limit is still 256. +.PP +\fBpamtogif\fP recognizes transparency information in the input by the + tuple type being \fBRGB_ALPHA\fP, \fBGRAYSCALE_ALPHA\fP, or + \fBBLACKANDWHITE_ALPHA\fP. This is the case for any image that has + transparency information and was created by a Netpbm program that + manipulates visual images. If, on the other hand, you have a PAM generated + some other way, but you know the planes have the same meaning as implied by + these tuple types, you can make \fBpamtogif\fP process the transparency + information by changing the tuple type accordingly before you pass it + to \fBpamtogif\fP. You can use \fBpamstack\fP to change the tuple type. +.PP +\fBpamtogif\fP was new in Netpbm 10.37 (December 2006). In older Netpbm, +use \fBppmtogif\fP. + +.UN options +.SH OPTIONS +.PP +In addition to the options common to all programs based on libnetpbm +(most notably \fB-quiet\fP, see +.UR index.html#commonoptions + Common Options +.UE +\&), \fBpamtogif\fP recognizes the following +command line options: + + + +.TP +\fB-interlace\fP +Produce an interlaced GIF file. + +.TP +\fB-sort\fP +Produce a GIF file with a color map sorted in a predictable order. +.sp +This does \fInot\fP produce the sorted color map which is part +of the GIF format. That kind of sorted color map is one where the +colors are sorted according to how important they are, and the GIF +header tells the viewer that it is sorted that way. Its purpose is to +allow the viewer to use fewer colors than are in the color map if it +is not capable of displaying all the colors. +.sp +What this option produces is a color map sorted by red value, then +green, then blue. That can be useful in analyzing GIF images, particularly +those made with two versions of the program, because it removes some of +the variability. + + +.TP +\fB-mapfile=\fP\fImapfile\fP +.sp +Use the colors found in the file \fImapfile\fP to create the +colormap in the GIF file, instead of the colors from \fInetpbmfile\fP. +\fImapfile\fP can be any PPM file; all that matters is the colors in +it. If the colors in \fInetpbmfile\fP do not match those in +\fImapfile\fP, \fBpamtogif\fP matches them to a "best +match." You can obtain a much better result by using \fBpnmremap\fP +to change the colors in the input to those in the map file. +.sp +The \fImapfile\fP file is not a palette file, just an image whose +colors you want to use. The order of colors in the GIF palette have +nothing to do with where they appear in the \fImapfile\fP image, and +duplication of colors in the image is irrelevant. +.sp +The map file's depth must match the number of color components in +the input (which is not necessarily the same as the input's depth -- +the input might have a transparency plane in addition). If your map file +does not, or it \fImight\fP not, run your input through +\fBpnmremap\fP using the same map file so that it does. +.sp +You can use \fB-mapfile\fP to speed up conversion of an image where you +already have a map file because of earlier processing of your image. For +example, it is common to start with an image that has more than 256 colors +and remap its colors to a set of 256 colors so that \fBpamgtogif\fP can +convert it (a GIF can have only 256 colors; \fBpamtogif\fP without +\fB-mapfile\fP fails on any image that has more than that) with +\fBpnmquant\fP. When you do this, \fBpnmquant\fP generates a palette to do +the color quantization, then \fBpamtogif\fP generates an identical palette +from the quantized image. You can save computation by generating the palette +once: + +.nf +\f(CW + $ pnmcolormap 256 myimage.ppm >/tmp/colormap.ppm + $ pamtogif myimage.ppm -mapfile=/tmp/colormap.ppm >output.gif +\fP + +.fi + + +.TP +\fB-transparent=\fP\fIcolor\fP +\fBpamtogif\fP marks the specified color as transparent in the GIF image. +.sp +If you don't specify \fB-transparent\fP, \fBpamtogif\fP does not +mark any color transparent (except as indicated by the transparency +information in the input file). +.sp +Specify the color (\fIcolor\fP) as described for the +.UR libnetpbm_image.html#colorname +argument of the \fBpnm_parsecolor()\fP library routine +.UE +\&. +.sp +If the color you specify is not present in the image, \fBpamtogif\fP +selects instead the color in the image that is closest to the one you +specify. Closeness is measured as a Cartesian distance between colors +in RGB space. If multiple colors are equidistant, \fBpamtogif\fP +chooses one of them arbitrarily. +.sp +However, if you prefix your color specification with "=", +e.g. \fB-transparent==red\fP, only the exact color you specify will +be transparent. If that color does not appear in the image, there +will be no transparency. \fBpamtogif\fP issues an information +message when this is the case. +.sp +When you specify \fB-transparent\fP, \fBpamtogif\fP ignores +explicit transparency information (the "alpha channel") in +the input image. + +.TP +\fB-alphacolor=\fP\fIcolor\fP +This specifies the foreground color for transparent pixels. A +viewer may use the foreground color for a transparent pixel if it +chooses not to have another color "show through.". The +default is black. +.sp +This applies only to pixels that are transparent in the GIF because +they are transparent in the Netpbm input. If a GIF pixel is +transparent because of the \fB-transparent\fP option, the foreground +color is the color indicated by that option. +.sp +Note that in GIF, all transparent pixels have the same foreground +color. (There is only one entry in the GIF colormap for transparent +pixels). +.sp +Specify the color (\fIcolor\fP) as described for the +.UR libnetpbm_image.html#colorname +argument of the \fBpnm_parsecolor()\fP library routine +.UE +\&. + +.TP +\fB-comment=\fP\fItext\fP +Include a comment in the GIF output with comment text \fItext\fP. +.sp +Without this option, there are no comments in the output. +.sp +Note that in a command shell, you'll have to use quotation marks around +\fItext\fP if it contains characters (e.g. space) that would make the shell +think it is multiple arguments: +.nf +$ pamtogif -comment "this is a comment" <xxx.ppm >xxx.gif + +.fi + +.TP +\fB-noclear\fP +.sp +This option causes the output not to contain any GIF clear codes. +.sp +In GIF, the stream defines codes that represent strings of pixels as it +goes. The stream contains definitions of codes mixed in with the references +to those codes that describe the pixels of the image. GIF specifies a maximum +number of codes that can be defined; when the stream has defined that many, +the stream can either just use those for the rest of the image or include a +clear code, deleting all the string codes so that the stream can start over +defining new ones. +.sp +By far the most common choice is the clear code. This usually results in a +smaller stream because the set of strings of pixels that occur in an image +vary over the parts of the image. Hardly any GIF encoders produce streams +that don't use the clear code. +.sp +But it is conceivable that a stream could be smaller without the use of the +clear code because it saves the stream having to redefine the same string +codes over and over. It could even avoid a thrashing situation where the +stream continually defines a set of strings that never get used again before +the maximum is reached. +.sp +The default is to use the clear codes. +.sp +This option was new in Netpbm 10.82 (March 2018). Before that, the program +aways uses the clear codes. + +.TP +\fB-nolzw\fP +.sp +This option is mainly of historical interest -- it involves use of +a patent that is now expired. +.sp +This option causes the GIF output, and thus \fBpamtogif\fP, not to +use LZW (Lempel-Ziv) compression. As a result, the image file is +larger and, before the patent expired, no royalties would be owed to +the holder of the patent on LZW. See the section LICENSE below. +.sp +LZW is a method for combining the information from multiple pixels into a +single GIF code. With the \fB-nolzw\fP option, \fBpamtogif\fP +creates one GIF code per pixel, so it is not doing any compression and not +using LZW. However, any GIF decoder, whether it uses an LZW decompressor +or not, will correctly decode this uncompressed format. An LZW decompressor +would see this as a particular case of LZW compression. +.sp +Note that if someone uses an LZW decompressor such as the one in +\fBgiftopnm\fP or pretty much any graphics display program to process +the output of \fBpamtogif -nolzw \fP, he is then using the LZW +patent. But the patent holder expressed far less interest in +enforcing the patent on decoding than on encoding. + +.TP +\fB-aspect=\fP\fIfraction\fP +This is the aspect ratio of the pixels of the image. Its only +effect is to record that information in the GIF for use by whatever +interprets the GIF. Note that this feature of GIF is hardly ever used +and most GIF decoders ignore this information and assume pixels are +square. +.sp +Pixels in a Netpbm image do not have aspect ratios; there is always +a one-one correspondence between GIF pixels and Netpbm pixels. +.sp +The aspect ratio is the quotient of width divided by height. GIF +allows aspect ratios from 0.25 (1:4) to 4 (4:1) in increments of 1/64. +\fBpamtogif\fP implements a natural extension of GIF that allows an +aspect ratio up to 4 14/64. If you specify anything outside this range, +\fBpamtogif\fP fails. \fBpamtogif\fP rounds \fIfraction\fP to +the nearest 1/64. +.sp +The default is square (1.0). +.sp +This option was new in Netpbm 10.38 (March 2007). Before that, the +pixels are always square. + + +.TP +\fB-verbose\fP +This option causes \fBpamtogif\fP to display information about the +conversion process and the image it produces. + + + +.UN seealso +.SH SEE ALSO +.BR "giftopnm" (1)\c +\&, +.BR "pnmremap" (1)\c +\&, +.BR "ppmtogif" (1)\c +\&, + +\fBgifsicle\fP +.UR http://www.lcdf.org/gifsicle +http://www.lcdf.org/gifsicle +.UE +\&, +.BR "pnm" (1)\c +\&, +.BR "pam" (1)\c +\&. + +.UN history +.SH HISTORY +.PP +\fBpamtogif\fP was new in Netpbm 10.37 (December 2006). It +replaced \fBppmtogif\fP, which created GIF images for Pbmplus/Netpbm +users since 1989. +.PP +The main outward change in the conversion from \fBppmtogif\fP to +\fBpamtogif\fP was that \fBpamtogif\fP was able to use transparency +information ("alpha channel") in PAM input, whereas with +\fBppmtogif\fP, one had to supply the transparency mask in a separate +pseudo-PGM image (via the \fB-alpha\fP option). +.PP +Jef Poskanzer wrote \fBppmtogif\fP in 1989, and it has always been +a cornerstone of Pbmplus/Netpbm because GIF is such a popular image +format. Jef based the LZW encoding on GIFENCOD by David Rowley <\fImgardi@watdcsu.waterloo.edu\fP>. +Jef included GIFENCOD's GIFCOMPR.C file pretty much whole. Rowley, in +turn, adapted the LZW compression code from classic Unix +\fBcompress\fP, which used techniques described in IEEE Computer, +June 1984. +.PP +Jef's \fBppmtogif\fP notably lacked the ability to use a +transparency mask with it. You could create transparent pixels in a +GIF, but only with the \fB-transparent\fP option, which allowed one +to specify that all pixels of a certain color in the input were to be +transparent. Bryan Henderson added the \fB-alpha\fP option in July +2001 so you could supply a mask image that indicates exactly which +pixels are to be transparent, and those pixels could have the same +color as other opaque ones. +.PP +Bryan Henderson added another significant piece of code and +function in October 2001: the ability to generate a GIF without using +the LZW patent -- an uncompressed GIF. This was very important to +many people at the time because the GIF patent was still in force, and +this allowed them to make an image that any GIF viewer could display, +royalty-free. Bryan adapted code from the Independent JPEG Group's +\fBdjpeg\fP for that. +.PP +There is no code in \fBpamtogif\fP from Jef's original, but Jef +may still hold copyright over it because of the way in which it evolved. +Virtually all of the code in \fBpamtogif\fP was written by Bryan +Henderson and contributed to the public domain. + + +.UN license +.SH LICENSE +.PP +If you use \fBpamtogif\fP without the \fB-nolzw\fP option, you +are using a patent on the LZW compression method which is owned by +Unisys. The patent has expired (in 2003 in the US and in 2004 +elsewhere), so it doesn't matter. While the patent was in force, most +people who used \fBpamtogif\fP and similar programs did so without a +license from Unisys to do so. Unisys typically asked $5000 for a +license for trivial use of the patent. Unisys never enforced the +patent against trivial users. +.PP +Rumor has it that IBM also owns or owned a patent covering +\fBpamtogif\fP. +.PP +A replacement for the GIF format that never required any patents to +use is the PNG format. +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/pamtogif.html +.PP
\ No newline at end of file |