diff options
Diffstat (limited to 'upstream/opensuse-leap-15-6/man1/pngtopam.1')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man1/pngtopam.1 | 320 |
1 files changed, 320 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man1/pngtopam.1 b/upstream/opensuse-leap-15-6/man1/pngtopam.1 new file mode 100644 index 00000000..697355bd --- /dev/null +++ b/upstream/opensuse-leap-15-6/man1/pngtopam.1 @@ -0,0 +1,320 @@ +\ +.\" 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 "Pngtopam User Manual" 0 "22 July 2008" "netpbm documentation" + +.SH NAME + +pngtopam - convert a PNG image into a Netpbm image + +.UN synopsis +.SH SYNOPSIS + +\fBpngtopam\fP +[\fB-verbose\fP] +[\fB-alphapam\fP | \fB-alpha\fP | \fB-mix\fP] +[\fB-background\fP=\fIcolor\fP] +[\fB-gamma\fP=\fIvalue\fP] +[\fB-text\fP=\fIfilename\fP] +[\fB-time\fP] +[\fB-byrow\fP] +[\fIpngfile\fP] +.PP +Minimum unique abbreviation of option is acceptable. You may use double +hyphens instead of 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 +\fBpngtopam\fP reads a PNG image (Portable Network Graphics) as +input and produces a Netpbm image as output. The type of the output file +depends on the input file - if it's black & white, \fBpngtopam\fP +creates a PBM file. If it's grayscale, \fBpngtopam\fP creates a PGM +file. Otherwise, it creates a PPM file. Except that with the +\fB-alphapam\fP option, it always creates a PAM file. That file has +tuple type GRAYSCALE_ALPHA or RGB_ALPHA depending on whether the input +has color or not. +.PP +To convert in the other direction, use \fBpamtopng\fP or +\fBpnmtopng\fP. The former is the more modern of the two and can recognize +transparency information in a PAM file, as you might generate with \fBpngtopam +-alphapam\fP. It has existed only since June 2015. The latter has more +features, but probably not ones that matter in the modern world. + + +.UN options +.SH OPTIONS + + +.TP +\fB-verbose\fP +Display various information about the input PNG image and the +conversion process. +.sp +If you want even more information about the PNG image, use +\fBpngcheck\fP (not part of Netpbm). + +.TP +\fB-alphapam\fP +Produce a single output image containing the main image (foreground) +and the transparency channel or transparency mask. This image is in the PAM +format with tuple type of either GRAYSCALE_ALPHA (which has a depth of +2 channels) or RGB_ALPHA (which has a depth of 4 channels). +.sp +You can specify only one of \fB-alphapam\fP, \fB-alpha\fP, and +\fB-mix\fP. With none of them, \fBpngtopam\fP produces an image of +the foreground of the input image and discards transparency information. +.sp +This option was new in Netpbm 10.44 (September 2008). + +.TP +\fB-alpha\fP +Output the transparency channel or transparency mask of the image. The +result is either a PBM file or a PGM file, depending on whether +different levels of transparency appear. +.sp +\fBpngtopam\fP discards the main image (the foreground). +.sp +You can specify only one of \fB-alphapam\fP, \fB-alpha\fP, and +\fB-mix\fP. With none of them, \fBpngtopam\fP produces an image of +the foreground of the input image and discards transparency information. + +.TP +\fB-mix\fP +Compose the image with the transparency or transparency mask against a +background. The background color is determined by the bKGD chunk in +the PNG, except that you can override it with \fB-background\fP. +If the PNG has no bKGD chunk and you don't specify \fB-background\fP, +the background color is white. +.sp +You can specify only one of \fB-alphapam\fP, \fB-alpha\fP, and +\fB-mix\fP. With none of them, \fBpngtopam\fP produces an image of +the foreground of the input image and discards transparency information. + +.TP +\fB-background=\fP\fIcolor\fP +This option specifies the background color with which to mix the image +when you specify \fB-mix\fP. +.sp +\fIcolor\fP is as described for the +.UR libppm.html#colorname +argument of the \fBppm_parsecolor()\fP library routine +.UE +\&. +.sp +Examples: + + +.IP \(bu +\f(CW-background=rgb:01/ff/80\fP +.IP \(bu +\f(CW-background=rgbi:1/255/128\fP + +.sp +If you don't specify \fB-background\fP, the background color is what +is specified in the PNG image, and if the PNG doesn't specify anything, +white. +.sp +You cannot specify \fB-background\fP unless you also specify +\fB-mix\fP. Before Netpbm 10.27 (March 2005), you could specify +\fB-background\fP without \fB-mix\fP and it was just ignored. (This +caused a usability problem). + + +.TP +\fB-gamma=\fP\fIvalue\fP +This option causes \fBpngtopam\fP to respect the image gamma information +in the PNG file (from the gAMA chunk). Probably by historical accident, +\fBpngtopam\fP ignores that information by default, assuming the image uses +the same gamma transformation as a Netpbm image, so the output image has +different colors than the PNG file actually represents if the PNG doesn't +actually do that. (However, it is rare for a PNG file to use a gamma +transformation different from what the Netpbm formats specify, or if it does, +to specify with a gAMA chuck what that is). +.sp +But when you \fIdo\fP specify \fB-gamma\fP, you get a rather strange +additional function, probably a historical mistake: +\fBpngtopam\fP incorporates the specified screen gamma value into the output +pixels, so that the samples in the Netpbm output deviate from the Netpbm +format specifications and are appropriate raw intensity values to send to the +display. This function essentially just exercises the ability of the PNG +library to make gamma corrections to the pixels as it reads them from the PNG +file to produce values appropriate for sending to a certain display in certain +viewing conditions. It's a strange function because it has nothing to do with +PNG and because in Netpbm, the normal way to make gamma corrections +appropriate for sending to a ceratin display in certain viewing conditions is +with the program \fBpngtopam\fP, applied to the normal output of +\fBpngtopam\fP. +.sp +If you specify \fB-gamma\fP, but the PNG image does not specify what gamma +transformation it uses (there is no gAMA chunk), \fBpngtopam\fP assumes a +simple power transformation with an image gamma of 1.0. That is probably not +not the actual image gamma; it is much more likely to be .45. +.sp +Because the gammas of uncompensated monitors are around 2.6, which results +in an image-gamma of 0.45, some typical situations are: +when the image-gamma is 0.45 (use -verbose to check) and the picture is too +light, your system is gamma-corrected, so convert with "-gamma 1.0". +When no gAMA chunk is present or the image-gamma is 1.0, use 2.2 to make the +picture lighter and 0.45 to make the picture darker. +.sp +One oddity to be aware of when using \fB-gamma\fP on an image with +transparency: The PNG image specifies that a certain color is +transparent, i.e. every pixel in the image of that color is +transparent. But \fBpngtopam\fP interprets this as applying to the +gamma-corrected space, and there may be less precision in that space +than in the original, which means multiple uncorrected colors map to +the same corrected color. So imagine that the image contains 3 shades +of white (gray) and specifies that one of them is transparent. After gamma +correction, those three shades are indistinguishable, so +\fBpngtopam\fP considers pixels of all three shades to be transparent. + + +.TP +\fB-text=\fP\fIfile\fP +Writes the tEXt and zTXt chunks to a file, in a format as +described in the \fBpnmtopng\fP user manual. These chunks contain +text comments or annotations. + +.TP +\fB-time\fP +Prints the tIME chunk to stderr. + +.TP +\fB-byrow\fP +This option can make \fBpngtopam\fP run faster or in environments +where it would otherwise fail. +.sp +\fBpngtopam\fP has two ways to do the conversion from PNG to PAM, using +respectively two facilities of the PNG library: + + + +.TP +Whole Image +Decode the entire image into memory at once, using +\fBpng_read_image()\fP, then convert to PAM and output row by row. + +.TP +Row By Row +Read, convert, and output one row at a time using \fBpng_read_row()\fP. + + +.sp +Whole Image is generally preferable because the PNG library does more of +the work, which means it understands more of the PNG format possibilities now +and in the future. Also, if the PNG is interlaced, \fBpngtopam\fP does +not know how to assemble the rows in the right order. +.sp +Row By Row uses far less memory, which means with large images, it +can run in environments where Whole Image cannot and may also run +faster. And because Netpbm code does more of the work, it's possible +that it can be more flexible or at least give better diagnostic +information if there's something wrong with the PNG. +.sp +The Netpbm native code may do something correctly that the PNG library does +incorrectly, or vice versa. +.sp +In Netpbm, we stress function over performance, so by default +\fBpngtopam\fP uses Whole Image. You can select Row By Row with +\fB-byrow\fP if you want the speed or resource requirement improvement. +.sp +\fB-byrow\fP was new in Netpbm 10.54 (March 2011). + + +.TP +\fB-orientraw\fP +A TIFF stream contains raster data which can be arranged in the +stream various ways. Most commonly, it is arranged by rows, with the +top row first, and the pixels left to right within each row, but many +other orientations are possible. +.sp +The common orientation is the same on the Netpbm formats use, so +\fBtifftopnm\fP can do its jobs quite efficiently when the TIFF raster +is oriented that way. +.sp +But if the TIFF raster is oriented any other way, it can take a +considerable amount of processing for \fBtifftopnm\fP to convert it to +Netpbm format. + + + +.UN seealso +.SH SEE ALSO +.BR "pamtopng" (1)\c +\&, +.BR "pnmtopng" (1)\c +\&, +.BR "pngtopnm" (1)\c +\&, +\fBptot\fP, +.BR "pnmgamma" (1)\c +\&, +.BR "pnm" (5)\c +\& +.PP +For information on the PNG format, see +.UR http://schaik.com/png +http://schaik.com/png +.UE +\&. + +.UN note +.SH NOTE +.PP +A PNG image contains a lot of information that can't be represented in +Netpbm formats. Therefore, you lose information when you convert to +another format with "pngtopam | pnmtoxxx". If there is a specialized +converter that converts directly to the other format, e.g. \fBptot\fP +to convert from PNG to TIFF, you'll get better results using that. + +.UN limitations +.SH LIMITATIONS +.PP +There could be an option to include PNG comment chunks in the output +image as PNM comments instead of putting them in a separate file. +.PP +The program could be much faster, with a bit of code optimizing. +As with any Netpbm program, speed always takes a back seat to quick +present and future development. + +.UN history +.SH HISTORY +.PP +\fBpngtopam\fP was new in Netpbm 10.44, as a replacement for +\fBpngtopnm\fP. The main improvement over \fBpngtopnm\fP was that +it could generate a PAM image with a transparency channel, whereas +with \fBpngtopnm\fP, you would have to extract the transparency +channel as a separate file, in a separate run. +.PP +\fBpngtopnm\fP was new in Netpbm 8.1 (March 2000), the first big +change to the package in Netpbm's renaissance. It and \fBpnmtopng\fP +were simply copied from the +.BR " +\fBpnmtopng\fP package" (1)\c +\& by Greg Roelofs. Those were based on +simpler reference applications by Alexander Lehmann +<alex@hal.rhein-main.de> and Willem van Schaik +<willem@schaik.com> and distributed with their PNG library. +.PP +Nearly all of the code has changed since it was copied from the +\fBpnmtopng\fP package, most of it just to improve maintainability. + + +.UN authors +.SH AUTHORS + +Copyright (C) 1995-1997 by Alexander Lehmann and 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/pngtopam.html +.PP
\ No newline at end of file |