diff options
| author | giraffedata <giraffedata@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2006-12-25 03:06:05 +0000 |
|---|---|---|
| committer | giraffedata <giraffedata@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2006-12-25 03:06:05 +0000 |
| commit | 1017cbebe5d5edd859e0fddad0a8600f509f4821 (patch) | |
| tree | 78bdf336648566f7a7d55f42837357dea3dd674c /pamstereogram.html | |
| parent | 16f2ac126651015a376eba864a3a35f738b0b25a (diff) | |
| download | netpbm-mirror-1017cbebe5d5edd859e0fddad0a8600f509f4821.tar.gz netpbm-mirror-1017cbebe5d5edd859e0fddad0a8600f509f4821.tar.xz netpbm-mirror-1017cbebe5d5edd859e0fddad0a8600f509f4821.zip | |
Place user guide into Subversion repository
git-svn-id: http://svn.code.sf.net/p/netpbm/code/userguide@181 9d0c8265-081b-0410-96cb-a4ca84ce46f8
Diffstat (limited to 'pamstereogram.html')
| -rw-r--r-- | pamstereogram.html | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/pamstereogram.html b/pamstereogram.html new file mode 100644 index 00000000..d367f7ca --- /dev/null +++ b/pamstereogram.html @@ -0,0 +1,286 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" + "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> +<title>Pamstereogram User Manual</title> +<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" /> +</head> + +<body> + +<h1>pamstereogram</h1> + +<p>Updated: 6 January 2006</p> + +<p><a href="#contents">Table Of Contents</a></p> + + +<h2 id="name">NAME</h2> + +<p>pamstereogram - create a single-image stereogram from a PAM +height map</p> + +<h2 id="synopsis">SYNOPSIS</h2> + +<p> +<b>pamstereogram</b> +[<b>-help</b>] +[<b>-verbose</b>] +[<b>-blackandwhite</b> | <b>-grayscale</b> | <b>-color</b>] +[<b>-maxval=</b><i>value</i>] +[<b>-patfile=</b><i>pamfile</i>] +[<b>-xshift=</b><i>pixels</i>] +[<b>-yshift=</b><i>pixels</i>] +[<b>-magnifypat=</b><i>scale</i>] +[<b>-guidesize=</b><i>pixels</i>] +[<b>-dpi=</b><i>resolution</i>] +[<b>-crosseyed</b>] +[<b>-makemask</b>] +[<b>-eyesep=</b><i>inches</i>] +[<b>-depth=</b><i>fraction</i>] +[<b>-randomseed=</b><i>integer</i> +[<i>infile</i>] +</p> + +<p>You may use either single or double hyphens to denote options. You +may use either whitespace or an equals sign to separate an option name +from its value.</p> + + +<h2 id="description">DESCRIPTION</h2> + +<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 +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 +eyes. What's exciting about single-image stereograms is that they +don't require special glasses to view, although it does require a bit +of practice to train your eyes to unfocus properly. The +<b>pamstereogram</b> program provides a wealth of control over how the +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>images targeting a given device resolution and eye +separation</li> + +<li>optional guide boxes to assist in focusing</li> + +<li>the ability to trade off depth levels for easier viewing</li> + +<li>choice of wall-eyed or cross-eyed stereograms</li> + +</ul> +<p>The output is a PAM image on standard output. Options control +the exact format of the PAM. If you want a PNM (PBM, PGM, or PPM) +image, use <b>pamtopnm</b> on the output. There is no need to convert +if you will use the image as input to a current Netpbm program, but +many other programs don't know what a PAM is. + +<p>To make a red/green type of stereogram (that you view with 3-D +glasses) instead, see <b>ppm3d</b>.</p> + + +<h2 id="options">OPTIONS</h2> + +<dl> + +<dt><b>-verbose</b></dt> +<dd>Display messages about image sizes and formats and properties +of the stereogram being generated.</dd> + +<dt><b>-blackandwhite</b></dt> +<dd>Produce a single-image random-dot black-and-white stereogram. +This is the default.</dd> + +<dt><b>-grayscale</b></dt> +<dd>Produce a single-image random-dot grayscale stereogram.</dd> + +<dt><b>-color</b></dt> +<dd>Produce a single-image random-dot color stereogram.</dd> + +<dt><b>-maxval=</b><i>value</i></dt> +<dd>Designate the maximum value of each gray/color component, i.e. +the color resolution. Smaller values make the output image have +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> +<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 +output file will have the same maxval and format (black and white, +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>-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). +<!-- <b>-xshift</b> is helpful when creating "true-color" stereograms. --> +This option is valid only along with <b>-patfile</b>.</dd> + +<dt><b>-yshift</b> <i>pixels</i></dt> +<dd>Shift the pattern image (designated by <b>-patfile</b>) +downwards by <i>pixels</i> pixels (default: 0). This option is +valid only along with <b>-patfile</b>.</dd> + +<dt><b>-magnifypat=</b><i>scale</i></dt> +<dd>Magnify each pixel in the pattern file or each random dot by +integral scaling factor <i>scale</i>. Note that +<b>pamstereogram</b> applies the pattern magnification +<em>after</em> pattern shifting (<b>-xshift</b> and +<b>-yshift</b>).</dd> + +<dt><b>-guidesize=</b><i>pixels</i></dt> +<dd>Draw a pair of <i>pixels</i> by <i>pixels</i> black squares on +a white background underneath the stereogram proper. These squares +help you guide your eyes into proper focus to view the 3-D image. +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 +no guide squares.</p> +</dd> + +<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> + +<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> + +<dt><b>-makemask</b></dt> +<dd>Instead of a stereogram, output a PAM mask image showing +coloring constraints. New pixels will be taken from the pattern +file where the mask is black. Copies of existing pixels will be +taken from the pattern file where the mask is white. The +<b>-makemask</b> option can be used to help create more +sophisticated pattern files (to use with <b>-patfile</b>) Note that +<b>-makemask</b> ignores <b>-magnifypat</b>; it always produces +masks that assume a pattern magnification of 1.</dd> + +<dt><b>-eyesep=</b><i>inches</i></dt> +<dd>Specify the separation in inches between your eyes. The +default, 2.5 inches (6.4 cm), should be sufficient for most people +and probably doesn't need to be changed.</dd> + +<dt><b>-depth=</b><i>fraction</i></dt> +<dd>Specify the output image's depth of field. That is, +<i>fraction</i> represents the fractional distance of the near +plane from the far plane. Smaller numbers make the 3-D image easier +to perceive but flatter. Larger numbers make the 3-D image more +difficult to perceive but deeper. The default, 0.3333, generally +works fairly well.</dd> + +<dt><b>-randomseed=</b><i>integer</i> +<dd>Specify a seed to be used for the random number generator. +The default is to use a seed based on the time of day, to one second +granularity. + +<p>It is useful to specify the seed if you want to create reproducible +results. With the same random seed, you should get identical results +every time you run <b>pamstereogram</b>. + +<p>This is irrelevant if you use a pattern file (<b>-patfile</b> +option), because there is no random element to <b>pamstereogram</b>'s +behavior. + +<p>This option was new in Netpbm 10.32 (Februrary 2006). + +</dl> + + +<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 +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> + +<p><b>pamstereogram</b> pays no attention the the image's tuple +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> + +<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> + + + +<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 \ + >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 >mysis.pam +</pre> + + +<h2 id="seealso">SEE ALSO</h2> +<ul> +<li><a href="pam.html">pam</a></li> + +<li><a href="ppm3d.html">ppm3d</a></li> + +<li>Harold W. Thimbleby, Stuart Inglis, and Ian H. Witten. +<em>Displaying 3D Images: Algorithms for Single Image Random Dot +Stereograms</em>. In IEEE Computer, <strong>27</strong>(10):38-48, +October 1994. DOI <a +href="http://dx.doi.org/10.1109/2.318576">10.1109/2.318576</a>.</li> + +</ul> + + +<h2><a id="history">HISTORY</a></h2> +<p><b>pamstereogram</b> was new in Netpbm 10.22 (April 2004), +but probably broken beyond usability until +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> +<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="#examples">EXAMPLES</a></li> +<li><a href="#seealso">SEE ALSO</a></li> +<li><a href="#history">HISTORY</a></li> +<li><a href="#author">AUTHOR</a></li> +</ul> +</body> +</html> |