\ .\" 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 "Pamtopng User Manual" 0 "12 March 2017" "netpbm documentation" .SH NAME pamtopng - convert a Netpbm image to PNG .UN synopsis .SH SYNOPSIS \fBpamtopng\fP [\fB-verbose\fP] [\fB-transparent=\fP\fIcolor\fP] [\fB-background=\fP\fIcolor\fP] [\fB-gamma=\fP\fIvalue\fP] [\fB-chroma='\fP\fIwx\fP \fIwy\fP \fIrx\fP \fIry\fP \fIgx\fP \fIgy\fP \fIbx\fP \fIby\fP\fB'\fP] [\fB-srgbintent=\fP\fIintent\fP] [\fB-time=\fP[\fIyy\fP]\fIyy\fP\fB-\fP\fImm\fP\fB-\fP\fIdd\fP \fIhh\fP\fB:\fP\fImm\fP\fB:\fP\fIss\fP] [\fB-text=\fP\fIfile\fP] [\fB-ztxt=\fP\fIfile\fP] [\fB-itxt=\fP\fIfile\fP] [\fIpnmfile\fP] .SH OPTION USAGE .PP Minimum unique abbreviation of option is acceptable. You may use double hyphens instead of a single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. .UN description .SH DESCRIPTION .PP This program is part of .BR "Netpbm" (1)\c \&. .PP \fBpamtopng\fP reads a Netpbm image as input and produces a PNG image as output. .PP Color component values in PNG files are either 8 or 16 bits wide, so where necessary \fBpamtopng\fP scales colors to have a maxval of 255 or 65535. In that case, it will add an sBIT chunk to indicated the original bit-depth. .PP \fBpamtopng\fP works only on images with maxval 1, 3, 15, 255, or 65535. You can use \fBpamdepth\fP to convert an image with some other maxval to one of these. .PP \fBpamtopng\fP produces a color PNG from a color PAM, even if the only colors in the image are shades of gray. To create a graycale PNG, from such an image (which might be slightly smaller), you can use other Netpbm programs to convert the input to grayscale. .UN pnmtopng .SS Alternative: \fBpnmtopng\fP .PP Netpbm contains another program for generating PNG images: \fBpnmtopng\fP. \fBpnmtopng\fP is a much older program - it is in fact the first program in the world that could generate a PNG. \fBpnmtopng\fP is a complex, feature-laden program. It lets you control various arcane aspects of the conversion and create PNGs with various arcane features. It does various transformations on the image to create the greatest compression possible, to a degree that probably doesn't make any difference in the modern world. .PP The main advantage \fBpamtopng\fP has over \fBpnmtopng\fP is that the former can use the transparency channel of a PAM image to generate the transparency information in the PNG. In contrast, handling of the alpha channel is very cumbersome with \fBpnmotpng\fP. .PP One difference that \fIdoes not\fP exist, that some people might incorrectly infer from the names is the possible input formats. Both programs can take PBM, PGM, PPM, and PAM input. .PP Because \fBpnmtopng\fP has been around virtually forever, programs and procedures that use it are more portable than those that use \fBpamtopng\fP. Its age and popularity also probably make it have fewer bugs. .PP \fBpamtopng\fP does not have any way to do what the following do in \fBpnmtopng\fP: .IP \(bu \fB-palette\fP .IP \(bu \fB-history\fP .IP \(bu \fB-filter\fP .IP \(bu \fB-size\fP .IP \(bu \fB-paeth\fP .IP \(bu \fB-hist\fP .IP \(bu \fB-nofilter\fP .IP \(bu \fB-sub\fP .IP \(bu \fB-up\fP .IP \(bu \fB-avg\fP .IP \(bu \fB-force\fP .IP \(bu \fB-libversion\fP .IP \(bu \fB-compression\fP .IP \(bu \fB-comp_\fP\fIxxx\fP .PP These are some of the other functions of \fBpnmtopng\fP that \fBpamtopng\fP lacks: .IP \(bu When you specify a transparent or background color that is not in the image, \fBpnmtopng\fP can optionally choose the closest one that is in the image. \fBpamtopng\fP always uses the exact color you specify. .PP Features that exist in both programs are controlled by largely the same command syntax. But there are these differences: .IP \(bu \fBpnmtopng\fP's \fB-rgb\fP option is \fB-chroma\fP in \fBpamtopng\fP. \fB-chroma\fP is a better name, and in fact was the name that \fBpnmtopng\fP used originally, but we had to change it when we had to change the syntax of the option value to conform to the rest of Netpbm. .IP \(bu \fBpnmtopng\fP's \fB-modtime\fP option is \fB-time\fP in \fBpamtopng\fP. The origin of \fB-modtime\fP is analogous to that of \fB-rgb\fP. .UN options .SH OPTIONS .TP \fB-transparent=\fP\fIcolor\fP \fBpamtopng\fP marks the specified color as transparent in the PNG image. .sp Specify the color (\fIcolor\fP) as described for the .UR libppm.html#colorname argument of the \fBppm_parsecolor()\fP library routine .UE \&. E.g. \fBred\fP or \fBrgb:ff/00/0d\fP. .TP \fB-background=\fP\fIcolor\fP This causes \fBpamtopng\fP to create a background color chunk in the PNG output which can be used for subsequent transparency channel or transparent color conversions. Specify \fIcolor\fP the same as for \fB-transparent\fP. .TP \fB-gamma=\fP\fIvalue\fP This causes \fBpnmtopng\fP to create a gAMA chunk. This information helps describe how the color values in the PNG must be interpreted. Without the gAMA chunk, whatever interprets the PNG must get this information separately (or just assume something standard). If your input is a true PPM or PGM image, you should specify \fB-gamma=.45\fP. But sometimes people generate images which are ostensibly PPM except the image uses a different gamma transfer function than the one specified for PPM. A common case of this is when the image is created by simple hardware that doesn't have digital computational ability. Also, some simple programs that generate images from scratch do it with a gamma transfer in which the gamma value is 1.0. .TP \fB-chroma=\fP\fIchroma_list\fP This option specifies how red, green, and blue component values of a pixel specify a particular color, by telling the chromaticities of those 3 primary illuminants and of white (i.e. full strength of all three). .sp The \fIchroma_list\fP value is a blank-separated list of 8 floating point decimal numbers. The CIE-1931 X and Y chromaticities (in that order) of each of white, red, green, and blue, in that order. .sp This information goes into the PNG's cHRM chunk. .sp In a shell command, make sure you use quotation marks so that the blanks in \fIchroma_list\fP don't make the shell see multiple command arguments. .TP \fB-srgbintent=\fP\fIintent\fP This asserts that the input is a pseudo-Netpbm image that uses an sRGB color space (unlike true Netpbm) and indicates how you intend for the colors to be rendered. It causes \fBpamtopng\fP to include an sRGB chunk in the PNG image that specifies that intent, so see the PNG documentation for more information on what this really means. .sp \fIintent\fP is one of: .IP \(bu \fBperceptual\fP .IP \(bu \fBrelativecolorimetric\fP .IP \(bu \fBsaturation\fP .IP \(bu \fBabsolutecolorimetric\fP .TP \fB-text=\fP\fIfilename\fP This option lets you include arbitrary text strings in the PNG output, as tEXt chunks. \fIfilename\fP is the name of a file that contains your text strings. .sp The output contains a distinct tEXt chunk for each entry in the file. .sp Here is an example of a text string file: .nf Title PNG file Author John Doe Description how to include a text chunk PNG file "Creation Date" 2015-may-11 Software pamtopng .fi .sp The file is divided into entries, each entry comprising consecutive lines of text. The first line of an entry starts in the first column (i.e. the first column is not white space) and every other line has white space in the first column. The first entry starts in the first line, so it is not valid for the first line of the file to have white space in its first column. .sp The first word in an entry is the key of the text string (e.g. 'Title'). It begins in column one of the line and continues up to, but not including, the first delimiter character or the end of the line, whichever is first. You can enclose the key in double quotes in which case the key can consists of multiple words. The quotes are not part of the key. The text string per se begins after the key and any delimiter characters after it, plus the text in subsequent continuation lines. .sp There is no limit on the length of a file line or entry or key or text string. There is no limit on the number of entries. .TP \fB-ztxt=\fP\fIfilename\fP The same as \fB-text\fP, except the text string is compressed in the PNG output. \fBpnmtopng\fP uses zTXt chunks instead of a tEXt chunks. .TP \fB-itxt=\fP\fIfilename\fP Similar to \fB-text\fP, but the text strings can be in a language other than English. The PNG image indicates what language that is and includes the text string key both in English and that language. \fBpnmtopng\fP uses iTXt chunks instead of tEXt chunks. .sp For each record, you must specify the language and give the key both in English and in the text string language. .sp Example: .nf Language nl-NL Taal nl-NL Title nl-NL Titel PNG file Author nl-NL Auteur Pietje Puk Description nl-NL Omschrijving Tekst in het Nederlands. .fi .sp The language specification is based on the ISO 639-1 standard, see http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for the valid codes. The format is either a two character "nl" or an extended code like "en-US". .TP \fB-time='\fP[\fIyy\fP]\fIyy-mm-dd hh:mm:ss\fP\fB'\fP This option allows you to specify the modification time value to be placed in the PNG output. You can specify the year parameter either as a two or four digit value. .TP \fB-verbose\fP This causes the program to display various facts about the conversion. .UN seealso .SH SEE ALSO .BR "pngtopam" (1)\c \&, .BR "pnmtopng" (1)\c \&, .BR "pam" (5)\c \&, .BR "pnm" (5)\c \& .PP For information on the PNG format, see .UR http://www.w3.org/TR/PNG/ http://www.w3.org/TR/PNG/ .UE \&, .UR http://libpng.org/pub/png/ http://libpng.org/pub/png/ .UE \&, .UR http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes .UE \& and .UR http://schaik.com/png/ http://schaik.com/png/ .UE \&. .UN history .SH HISTORY .PP \fBpamtopng\fP was new in Netpbm 10.70 (June 2015). .PP Before \fBpamtopng\fP, the two ways to create PNG images with Netpbm were \fBpnmtopng\fP and \fBpamrgbatopng\fP. The history of the former is discussed above. The latter was added to Netpbm in 2005 as a cheap way to fill a significant need that \fBpnmtopng\fP did not: the ability to turn the alpha channel in a PAM image into the alpha channel in a PNG image. .PP Handling of the alpha channel with \fBpnmtopng\fP is very cumbersome (as was dealing with alpha channels in general before the introduction of the PAM format). \fBpamrgbatopng\fP could do what people wanted with the alpha channel, but nothing else. It was a very small program with literally no command line options. .PP The goal in those days was eventually to expand \fBpnmtopng\fP to do the PAM alpha channel thing, rename it to \fBpamtopng\fP, and retire \fBpamrgbatopng\fP. But \fBpnmtopng\fP is such a complex program, because of its dizzying array of features and its need for backward compatibility, that adding that one capability to it was a daunting task and for ten years nobody attempted it. .PP In 2015, one of the authors of the original \fBpnmtopng\fP (from before it was even part of Netpbm -- a program that shared essentially no lines of code with \fBpnmtopng\fP of 2015) decided to go in a different direction. While many features of \fBpnmtopng\fP were pretty important and easy to implement, many others were probably of no use in the modern world or at least not important enough to justify the complexity they lent to the code. (The features thought to be outdated were ones that were intended to make the PNG output slightly smaller - something considerably less important with the declining cost of computer resources). .PP And there was an opportunity to drop those features: We could use the new name 'pamtopng' for a new program, keep the existing program under the name 'pnmtopng', and avoid most backward compatibility trouble. .PP Therefore, Willem van Schaik wrote an intermediate level program that had all the most important features of \fBpnmtopng\fP, plus the alpha channel handling of \fBpamrgbatopng\fP, with nice, simple code. That was \fBpamtopng\fP. .PP Because \fBpamrgbatopng\fP had no options, \fBpamtopng\fP was backward compatible with it without even trying. Therefore, as soon as we added \fBpamtopng\fP to Netpbm, we removed \fBpamrgbatopng\fP and recommended that \fBpamrgbatopng\fP be installed as an alias for \fBpamtopng\fP. .UN author .SH AUTHOR Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik. Copyright (C) 2015 by Willem van Schaik. .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/pamtopng.html .PP