summaryrefslogtreecommitdiffstats
path: root/upstream/opensuse-leap-15-6/man1/pamtogif.1
diff options
context:
space:
mode:
Diffstat (limited to 'upstream/opensuse-leap-15-6/man1/pamtogif.1')
-rw-r--r--upstream/opensuse-leap-15-6/man1/pamtogif.1376
1 files changed, 376 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man1/pamtogif.1 b/upstream/opensuse-leap-15-6/man1/pamtogif.1
new file mode 100644
index 00000000..eed947e6
--- /dev/null
+++ b/upstream/opensuse-leap-15-6/man1/pamtogif.1
@@ -0,0 +1,376 @@
+\
+.\" 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" 0 "22 March 2007" "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-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 you request features
+that were new with GIF89, to wit the \fB-transparent\fP or
+\fB-comment\fP options. Otherwise, it creates GIF87. Really old GIF
+readers conceivably could not recognize GIF89.
+.PP
+The GIF format is not capable of representing an image with more than
+256 colors in it (it contains a 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, \fBppmtogif\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 was new in Netpbm 10.37 (December 2006). In older Netpbm,
+use \fBppmtogif\fP.
+
+.UN options
+.SH 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 libppm.html#colorname
+argument of the \fBppm_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-alpha=\fP\fIpgmfile\fP
+There is no \fB-alpha\fP option. \fBpamtogif\fP's predecessor had
+such an option because it was not capable of taking PAM input that contains
+a transparency (alpha) plane, so one used this option to supply a
+transparency plane as a separate PGM file.
+
+ This option names a PGM file that contains a transparency mask for the
+image. \fBpamtogif\fP creates fully transparent pixels wherever the
+transparency mask indicates transparency greater than 50%. The color of
+those pixels is that specified by the \fB-alphacolor\fP
+option, or black by default.
+.sp
+To do this, \fBpamtogif\fP creates an entry in the GIF colormap in
+addition to the entries for colors that are actually in the image. It
+marks that colormap entry as transparent and uses that colormap index
+in the output image to create a transparent pixel.
+.sp
+ The transparency image must be the same dimensions as the input
+image, but may have any maxval. White means opaque and black means
+transparent.
+.sp
+ You cannot specify both \fB-transparent\fP and \fB-alpha\fP.
+
+.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 libppm.html#colorname
+argument of the \fBppm_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-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" (5)\c
+\&,
+.BR "pam" (5)\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