.TL Pamstereogram User Manual .SH 1 pamstereogram .LP .LP Updated: 6 January 2006 .LP Table Of Contents .SH 2 NAME .LP .LP pamstereogram - create a single-image stereogram from a PAM height map .SH 2 SYNOPSIS .LP .LP \fBpamstereogram\fR [\fB-help\fR] [\fB-verbose\fR] [\fB-blackandwhite\fR | \fB-grayscale\fR | \fB-color\fR] [\fB-maxval=\fR\fIvalue\fR] [\fB-patfile=\fR\fIpamfile\fR] [\fB-xshift=\fR\fIpixels\fR] [\fB-yshift=\fR\fIpixels\fR] [\fB-magnifypat=\fR\fIscale\fR] [\fB-guidesize=\fR\fIpixels\fR] [\fB-dpi=\fR\fIresolution\fR] [\fB-crosseyed\fR] [\fB-makemask\fR] [\fB-eyesep=\fR\fIinches\fR] [\fB-depth=\fR\fIfraction\fR] [\fB-randomseed=\fR\fIinteger\fR [\fIinfile\fR] .LP 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. .SH 2 DESCRIPTION .LP .LP This program is part of Netpbm. .LP \fBpamstereogram\fR 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 \fBpamstereogram\fR program provides a wealth of control over how the stereogram is generated, including the following: .IP \(bu black and white, grayscale, or color output .IP \(bu single-image random-dot stereograms (SIRDS) or single-image stereograms (SIS) using a tiled image .IP \(bu images targeting a given device resolution and eye separation .IP \(bu optional guide boxes to assist in focusing .IP \(bu the ability to trade off depth levels for easier viewing .IP \(bu choice of wall-eyed or cross-eyed stereograms .LP .LP 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 \fBpamtopnm\fR 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. .LP To make a red/green type of stereogram (that you view with 3-D glasses) instead, see \fBppm3d\fR. .SH 2 OPTIONS .LP .RS .IP "\fB-verbose\fR" Display messages about image sizes and formats and properties of the stereogram being generated. .IP "\fB-blackandwhite\fR" Produce a single-image random-dot black-and-white stereogram. This is the default. .IP "\fB-grayscale\fR" Produce a single-image random-dot grayscale stereogram. .IP "\fB-color\fR" Produce a single-image random-dot color stereogram. .IP "\fB-maxval=\fR\fIvalue\fR" 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 \fB-maxval\fR, \fBpamstereogram\fR uses the maxval of the input image. This option has no effect with \fB-blackandwhite\fR. .IP "\fB-patfile=\fR\fIpnmfile\fR" 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 \fB-patfile\fR option along with \fB-blackandwhite\fR, \fB-grayscale\fR, \fB-color\fR, or \fB-maxval\fR. .IP "\fB-xshift=\fR\fIpixels\fR" Shift the pattern image (designated by \fB-patfile\fR) to the right by \fIpixels\fR pixels (default: 0). This option is valid only along with \fB-patfile\fR. .IP "\fB-yshift\fR \fIpixels\fR" Shift the pattern image (designated by \fB-patfile\fR) downwards by \fIpixels\fR pixels (default: 0). This option is valid only along with \fB-patfile\fR. .IP "\fB-magnifypat=\fR\fIscale\fR" Magnify each pixel in the pattern file or each random dot by integral scaling factor \fIscale\fR. Note that \fBpamstereogram\fR applies the pattern magnification after pattern shifting (\fB-xshift\fR and \fB-yshift\fR). .IP "\fB-guidesize=\fR\fIpixels\fR" Draw a pair of \fIpixels\fR by \fIpixels\fR 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. .LP If \fIpixels\fR is negative, \fBpamstereogram\fR will draw the guide squares above the stereogram instead of below it. If \fIpixels\fR is zero (the default), \fBpamstereogram\fR will draw no guide squares. .IP "\fB-dpi=\fR\fIresolution\fR" Specify the resolution of the output device in dots per inch. The default is 96 DPI, which represents a fairly crisp screen resolution. .IP "\fB-crosseyed\fR" 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 \fB-crosseyed\fR option enables such people to see the 3-D image as intended. .IP "\fB-makemask\fR" 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 \fB-makemask\fR option can be used to help create more sophisticated pattern files (to use with \fB-patfile\fR) Note that \fB-makemask\fR ignores \fB-magnifypat\fR; it always produces masks that assume a pattern magnification of 1. .IP "\fB-eyesep=\fR\fIinches\fR" 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. .IP "\fB-depth=\fR\fIfraction\fR" Specify the output image's depth of field. That is, \fIfraction\fR 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. .IP "\fB-randomseed=\fR\fIinteger\fR" 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. .LP 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 \fBpamstereogram\fR. .LP This is irrelevant if you use a pattern file (\fB-patfile\fR option), because there is no random element to \fBpamstereogram\fR's behavior. .LP This option was new in Netpbm 10.32 (Februrary 2006). .RE .SH 2 PARAMETERS .LP .LP The only parameter, \fIinfile\fR, is the name of an input file that is a height map image. If you don't specify \fIinfile\fR, the input is from standard input. .LP 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. .LP \fBpamstereogram\fR pays no attention the the image's tuple type and ignores all planes other than plane 0. .LP Like any Netpbm program, \fBpamstereogram\fR will accept PNM input as if it were the PAM equivalent. .LP 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). .SH 2 EXAMPLES .LP .LP Generate a SIRDS out of small, brightly colored squares and prepare it for display on an 87 DPI monitor: .DS L pamstereogram heightmap.pam \ -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \ >3d.pam .DE .LP Generate a SIS by tiling a PPM file (a prior run with \fB-verbose\fR indicates how wide the pattern file should be for seamless tiling, although any width is acceptable for producing SISes): .DS L pamstereogram myheights.pam -patfile mypattern.ppm >mysis.pam .DE .SH 2 SEE ALSO .LP .IP \(bu pam .IP \(bu ppm3d .IP \(bu Harold W. Thimbleby, Stuart Inglis, and Ian H. Witten. Displaying 3D Images: Algorithms for Single Image Random Dot Stereograms. In IEEE Computer, 27(10):38-48, October 1994. DOI 10.1109/2.318576. .LP .SH 2 HISTORY .LP .LP \fBpamstereogram\fR 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). .SH 2 AUTHOR .LP .LP Copyright (C) 2006 Scott Pakin, scott+pbm@pakin.org. .SH 2 Table Of Contents .LP .IP \(bu SYNOPSIS .IP \(bu DESCRIPTION .IP \(bu OPTIONS .IP \(bu PARAMETERS .IP \(bu EXAMPLES .IP \(bu SEE ALSO .IP \(bu HISTORY .IP \(bu AUTHOR .LP