path: root/upstream/debian-unstable/man1/pngtopam.1

\
.\" 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" 1 "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
.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
\&), \fBpngtopam\fP recognizes the following
command line 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 libnetpbm_image.html#colorname
argument of the \fBpnm_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" (1)\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