miscellaneous update

git-svn-id: http://svn.code.sf.net/p/netpbm/code/userguide@1975 9d0c8265-081b-0410-96cb-a4ca84ce46f8

2 files changed, 33 insertions, 10 deletions

diff --git a/pngtopam.html b/pngtopam.html
index 09406ef4..11f330c6 100644
--- a/pngtopam.html
+++ b/pngtopam.html
@@ -131,12 +131,33 @@ caused a usability problem).
 
 <DT><B>-gamma=</b><i>value</i>
 
-<DD>Converts the image to a new display-gamma value.  If a gAMA chunk
-is present in the <I>png-file</I>, <b>pngtopam</b> uses the specified
-image-gamma value.  If not, <b>pngtopam</b> considers the image-gamma
-to be 1.0.  Based on the image-gamma and the display-gamma given with
-this option, <b>pngtopam</b> adjusts the colors written to the
-<I>pnm-file</I>.
+<dd>This option causes <b>pngtopam</b> to respect the image gamma information
+in the PNG file (from the gAMA chunk).  Probably by historical accident,
+<b>pngtopam</b> 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).
+
+<p>But when you <em>do</em> specify <b>-gamma</b>, you get a rather strange
+additional function, probably a historical mistake:
+<b>pngtopam</b> 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 <b>pngtopam</b>, applied to the normal output of
+<b>pngtopam</b>.
+
+<p>If you specify <b>-gamma</b>, but the PNG image does not specify what gamma
+transformation it uses (there is no gAMA chunk), <b>pngtopam</b> 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.
 
 <p>Because the gammas of uncompensated monitors are around 2.6, which results 
 in an image-gamma of 0.45, some typical situations are: 
@@ -152,13 +173,10 @@ transparent.  But <b>pngtopam</b> 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 and specifies that one of them is transparent.  After gamma
+of white (gray) and specifies that one of them is transparent.  After gamma
 correction, those three shades are indistinguishable, so
 <b>pngtopam</b> considers pixels of all three shades to be transparent.
 
-<p>If this is not what you want, don't use <b>gamma</b>.  Instead,
-use <b>pnmgamma</b> on the output.
-
 
 <DT><B>-text=</b><i>file</i>
 
diff --git a/pnmtops.html b/pnmtops.html
index 90b8f5cc..e5910e2f 100644
--- a/pnmtops.html
+++ b/pnmtops.html
@@ -81,6 +81,11 @@ to Postscript).  It is designed so that an EPSF stream can be embedded
 in another Postscript stream.  A typical reason to do that is where an
 EPSF stream describes a picture you want in a larger document.
 
+<p>But EPSF is not an image format -- converting from Netpbm format to EPSF
+really means generating a program to print that Netpbm image on paper.  Note
+that there are myriad ways to print an image on paper; <b>pnmtops</b>
+command line options let you control some of them.
+
 <p>An Encapsulated Postscript document conforms to the DSC (Document
 Structuring Convention).  The DSC defines some Postscript comments
 (they're comments from a Postscript point of view, but have semantic