"miscellaneous update"

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

1 files changed, 137 insertions, 23 deletions

diff --git a/pamstereogram.html b/pamstereogram.html
index a2feab0a..9780c2b6 100644
--- a/pamstereogram.html
+++ b/pamstereogram.html
@@ -10,7 +10,7 @@
 
 <h1>pamstereogram</h1>
 
-<p>Updated: 6 January 2006</p>
+<p>Updated: 28 September 2010</p>
 
 <p><a href="#contents">Table Of Contents</a></p>
 
@@ -18,7 +18,7 @@
 <h2 id="name">NAME</h2>
 
 <p>pamstereogram - create a single-image stereogram from a PAM
-height map</p>
+depth map</p>
 
 <h2 id="synopsis">SYNOPSIS</h2>
 
@@ -29,6 +29,9 @@ height map</p>
 [<b>-blackandwhite</b> | <b>-grayscale</b> | <b>-color</b>]
 [<b>-maxval=</b><i>value</i>]
 [<b>-patfile=</b><i>pamfile</i>]
+[<b>-texfile=</b><i>pamfile</i>]
+[<b>-bgcolor=</b><i>color</i>]
+[<b>-smoothing=</b><i>pixels</i>]
 [<b>-xshift=</b><i>pixels</i>]
 [<b>-yshift=</b><i>pixels</i>]
 [<b>-magnifypat=</b><i>scale</i>]
@@ -48,7 +51,7 @@ height map</p>
 
 <p>This program is part of <a href="index.html">Netpbm</a>.</p>
 
-<p><b>pamstereogram</b> inputs a height map (a map of the distances
+<p><b>pamstereogram</b> inputs a depth map (a map of the distances
 from your eye of the points in a scene) and outputs a single-image
 stereogram (SIS). A SIS is a 2-D image specially designed to appear
 three dimensional when viewed with relaxed, slightly unfocused
@@ -61,11 +64,11 @@ stereogram is generated, including the following:</p>
 <ul>
 <li>black and white, grayscale, or color output</li>
 
-<li>single-image random-dot stereograms (SIRDS) or single-image
-stereograms (SIS) using a tiled image</li>
+<li>single-image random-dot stereograms (SIRDS), single-image
+stereograms (SIS) using a tiled image, or mapped-texture stereograms
+(MTS)</li>
 
-<li>images targeting a given device resolution and eye
-separation</li>
+<li>images targeting a given device resolution and eye separation</li>
 
 <li>optional guide boxes to assist in focusing</li>
 
@@ -113,7 +116,7 @@ smaller numbers of unique grays/colors. If you don't specify
 <b>-maxval</b>, <b>pamstereogram</b> uses the maxval of the input
 image. This option has no effect with <b>-blackandwhite</b>.</dd>
 
-<dt><b>-patfile=</b><i>pnmfile</i></dt>
+<dt><b>-patfile=</b><i>pamfile</i></dt>
 <dd>Specify an image to use as a repeated background pattern for
 the stereogram instead of a random-dot pattern. Intricate images
 generally produce a crisper 3-D effect that simpler images. The
@@ -122,6 +125,40 @@ grayscale or color) as the pattern file. You cannot specify the
 <b>-patfile</b> option along with <b>-blackandwhite</b>,
 <b>-grayscale</b>, <b>-color</b>, or <b>-maxval</b>.</dd>
 
+<dt><b>-texfile=</b><i>pamfile</i></dt>
+<dd>Specify an image to use as the texture for a mapped-texture
+stereogram.  The idea is that the depth-map image provides the depth
+values of the 3-D object/scene while the texture image provides the
+true-color values.  Consequently, the texture image should align with
+the depth-map image.  (Note that it's required to have the same
+dimensions.)  The texture image's background color is ignored when
+blending colors.</dd>
+
+<p>This option was new in Netpbm 10.53 (December 2010).</p>
+
+<dt><b>-bgcolor=</b><i>color</i></dt>
+<dd>Use <i>color</i> as the texture image's background color instead
+of letting <b>pamstereogram</b> determine it automatically.  Specify
+the color as described for the
+<a href="libppm.html#colorname">argument of the ppm_parsecolor() library
+routine</a>.  The <b>-bgcolor</b> option is meaningful only in conjunction
+with <b>-texfile</b>.</dd>
+
+<p>This option was new in Netpbm 10.53 (December 2010).</p>
+
+<dt><b>-smoothing=</b><i>pixels</i></dt>
+<dd>Horizontally blur non-background colors into background pixels up
+to a distance of <i>pixels</i> pixels (default: 0).  This helps smooth
+over distracting glitches introduced by the stereogram's color
+constraints when producing a mapped-texture stereogram.
+The <b>-smoothing</b> option is helpful when the texture image
+includes smooth color transitions (as in a photograph) but makes crisp
+texture images (as in a line drawing) appear blurry.
+The <b>-smoothing</b> option is meaningful only in conjunction with
+<b>-texfile</b>.</dd>
+
+<p>This option was new in Netpbm 10.53 (December 2010).</p>
+
 <dt><b>-xshift=</b><i>pixels</i></dt>
 <dd>Shift the pattern image (designated by <b>-patfile</b>) to the
 right by <i>pixels</i> pixels (default: 0).
@@ -148,6 +185,7 @@ The trick is to focus your eyes some distance behind the image,
 causing you to see four black squares, then continue altering your
 focus distance until the middle two black squares fuse into a
 single black square. At that point, a crisp, 3-D image will appear.
+
 <p>If <i>pixels</i> is negative, <b>pamstereogram</b> will draw the
 guide squares above the stereogram instead of below it. If
 <i>pixels</i> is zero (the default), <b>pamstereogram</b> will draw
@@ -156,15 +194,29 @@ no guide squares.</p>
 
 <dt><b>-dpi=</b><i>resolution</i></dt>
 <dd>Specify the resolution of the output device in dots per inch.
-The default is 96 DPI, which represents a fairly crisp screen
-resolution.</dd>
+The default is 100 DPI, which represents a fairly crisp screen
+resolution.
+
+<p>Before Netpbm 10.53 (December 2010), the default was 96 DPI.</p>
+
+</dd>
 
 <dt><b>-crosseyed</b></dt>
-<dd>Invert the gray levels in the height map (input image) so that
-the 3-D image pops out of the page where it would otherwise sink
-into the page and vice versa. Some people are unable to diverge
-their eyes and can only cross them. The <b>-crosseyed</b> option
-enables such people to see the 3-D image as intended.</dd>
+<dd>Invert the gray levels in the depth map (input image) so that the 3-D
+image pops out of the page where it would otherwise sink into the page and
+vice versa. Some people are unable to diverge their eyes and can only cross
+them. The <b>-crosseyed</b> option enables such people to see the 3-D image as
+intended.  You can also specify the <b>-crosseyed</b> option if you prefer
+using depth maps in which darker colors are closer to the eye and lighter
+colors are farther from the eye.</dd>
+
+<p>Before Netpbm 10.53 (December 2010), <b>pamstereogram</b> used higher
+(lighter) numbers for things closer to the eye <em>without</em>
+<b>-crosseyed</b> and vice versa.
+
+</p>
+
+</dd>
 
 <dt><b>-makemask</b></dt>
 <dd>Instead of a stereogram, output a PAM mask image showing
@@ -210,12 +262,16 @@ behavior.
 <h2 id="parameters">PARAMETERS</h2>
 
 <p>The only parameter, <i>infile</i>, is the name of an input file
-that is a height map image. If you don't specify <i>infile</i>, the
+that is a depth map image. If you don't specify <i>infile</i>, the
 input is from standard input.</p>
 
 <p>The input is a PAM image of depth 1. Each sample represents the
 distance from the eye that the 3-D image at that location should
-be. Higher numbers mean further from the eye.</p>
+be.  Lower (darker) numbers mean further from the eye.
+
+<h2 id="notes">NOTES</h2>
+
+<h3 id="inputimages">Input Images</h3>
 
 <p><b>pamstereogram</b> pays no attention the the image's tuple
 type and ignores all planes other than plane 0.</p>
@@ -223,27 +279,79 @@ type and ignores all planes other than plane 0.</p>
 <p>Like any Netpbm program, <b>pamstereogram</b> will accept PNM
 input as if it were the PAM equivalent.</p>
 
+<h3 id="mappedtexture">Mapped-texture Stereograms</h3>
+
+<p>In a <i>mapped-texture stereogram</i> (MTS), the 3-D image can be
+drawn with true colors.  Unlike a SIRDS or tiled-image SIS, however,
+the image portrayed by an MTS is apparent in normal 2-D viewing.  It
+appears repeated multiple times and overlapped with itself, but it is
+not hidden.</p>
+
+<p>You create an MTS with <b>pamstereogram</b> by passing the filename
+of a PAM <q>texture image</q> with a <b>-texfile</b> option.  A
+texture image portrays the same 3-D object as the depth-map image but
+indicates the colors that the program should apply to the object.</p>
+
+<p><b>pamstereogram</b> ignores the texture image's background color when it
+overlaps copies of the 3-D object.  This prevents, for example, a bright-red
+object on a black background from being drawn as a dark-red object (a blend of
+50% bright red and 50% black); instead, the program ignores the black and the
+object remains bright red.  A consequence of this feature is that an MTS looks
+best when the objects in the texture image have a crisp outline.  Smooth
+transitions to the background color result in unwanted color artifacts around
+edges because the program ignores only <em>exact</em> matches with the
+background color.</p>
+
+<p>You should specify a larger-than-normal value for <b>-eyesep</b>
+(and/or <b>-dpi</b>) when producing an MTS.  Otherwise, the 3-D object will
+repeat so many times that most colored pixels will overlap other colored
+pixels, reducing the number of true-colored pixels that remain.</p>
+
+<p>An MTS can employ a background pattern (<b>-patfile</b>).  In this
+case, <b>pamstereogram</b> replaces background pixels with pattern pixels in
+the final step of generating the image.</p>
+
+
+<h3 id="notes_misc">Miscellaneous</h3>
+
 <p>A good initial test is to input an image consisting of a solid
 shape of distance 0 within a large field of maximum distance (e.g., a
-black square on a white background).</p>
+white square on a black background).</p>
 
+<p>With the default values for <b>-dpi</b> and <b>-eyesep</b>, pattern
+images that are 128 pixels wide can tile seamlessly.</p>
 
 
 <h2 id="examples">EXAMPLES</h2>
 
 <p>Generate a SIRDS out of small, brightly colored squares and
 prepare it for display on an 87 DPI monitor:</p>
+
 <pre>
-   pamstereogram heightmap.pam \
-                 -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \
-                 &gt;3d.pam
+    pamstereogram depthmap.pam \
+        -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \
+        &gt;3d.pam
 </pre>
+
 <p>Generate a SIS by tiling a PPM file (a prior run with
 <b>-verbose</b> indicates how wide the pattern file should be for
 seamless tiling, although any width is acceptable for producing
 SISes):</p>
+
 <pre>
-   pamstereogram myheights.pam -patfile mypattern.ppm &gt;mysis.pam
+    pamstereogram depthmap.pam -patfile mypattern.ppm &gt;3d.pam
+</pre>
+
+
+<p>Generate an MTS by associating colors with a depth-mapped object
+(using a large eye separation to reduce the number of repetitions of
+the texture image) and twice smoothing over background-colored
+speckles:</p>
+
+<pre>
+    pamstereogram depthmap.pam \
+        -texfile colormap.pam -smoothing 2 -eyesep 3.5 \
+        &gt;3d.pam
 </pre>
 
 
@@ -272,13 +380,19 @@ Netpbm 10.32 (Februrary 2006) and Netpbm 10.26.23 (January 2006).</p>
 
 
 <h2><a id="author">AUTHOR</a></h2>
-<p>Copyright (C) 2006 Scott Pakin, <a href="mailto:scott+pbm@pakin.org">scott+pbm@pakin.org</a>.</p>
+<p>Copyright (C) 2006, 2010 Scott Pakin, <a href="mailto:scott+pbm@pakin.org">scott+pbm@pakin.org</a>.</p>
 <h2><a id="contents">Table Of Contents</a></h2>
 <ul>
 <li><a href="#synopsis">SYNOPSIS</a></li>
 <li><a href="#description">DESCRIPTION</a></li>
 <li><a href="#options">OPTIONS</a></li>
 <li><a href="#parameters">PARAMETERS</a></li>
+<li><a href="#notes">NOTES</a></li>
+<ul>
+  <li><a href="inputimages">Input Images</a></li>
+  <li><a href="mappedtexture">Mapped-texture Stereograms</a></li>
+  <li><a href="notes_misc">Miscellaneous</a></li>
+  </ul>
 <li><a href="#examples">EXAMPLES</a></li>
 <li><a href="#seealso">SEE ALSO</a></li>
 <li><a href="#history">HISTORY</a></li>