pamstereogram - create a single-image stereogram from a PAM depth map
pamstereogram [-help] [-verbose] [-blackandwhite | -grayscale | -color] [-maxval=value] [-patfile=pamfile] [-texfile=pamfile] [-bgcolor=color] [-smoothing=pixels] [-xbegin=pixels] [-xshift=pixels] [-yshift=pixels] [-magnifypat=scale] [-guidetop] [-guidebottom] [-guidesize=pixels] [-dpi=resolution] [-crosseyed] [-makemask] [-eyesep=inches] [-depth=fraction] [-planes=near_pixels,far_pixels] [-randomseed=integer] [-tileable] [infile]
This program is part of Netpbm(1).
pamstereogram 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 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 pamstereogram program provides a wealth of control over how the stereogram is generated, including the following:
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 pamtopnm 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.
To make a red/cyan type of stereogram (that you view with 3-D glasses) instead, see ppm3d.
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.
In addition to the options common to all programs based on libnetpbm
(most notably -quiet, see
Common Options
), pamstereogram recognizes the following
command line options:
The default is to begin in the center.
This option was new in Netpbm 10.71 (June 2015).
This option was new in Netpbm 10.53 (December 2010).
This option was new in Netpbm 10.53 (December 2010).
When used with -texfile, horizontally blur non-background colors into background pixels up to a distance of pixels pixels. This helps smooth over distracting glitches introduced by the stereogram's color constraints when producing a mapped-texture stereogram. In this case, the -smoothing 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.
This option was new in Netpbm 10.53 (December 2010). Before Netpbm 10.61 (December 2012), it has no effect without -texfile.
This option is valid only along with -patfile.
This option was new in Netpbm 10.94 (March 2021).
This option was new in Netpbm 10.61 (December 2012). Before that, the presence of -guidesize, with a positive value, has the same effect.
This option was new in Netpbm 10.61 (December 2012). Before that, the presence of -guidesize, with a negative value, has the same effect.
This is valid only with -guidetop or -guidebottom.
Default is 20.
Before Netpbm 10.61 (December 2012), if you don't specify this option, pamstereogram draws no guides. If you specify it with a positive value, pamstereogram behaves as if you specified -guidebottom too, and if you specify it with a negative value, it behaves as if you specified -guidetop and specified guidesize with the absolute value of that negative value.
Before Netpbm 10.53 (December 2010), the default was 96 DPI.
Before Netpbm 10.53 (December 2010), pamstereogram used higher (lighter) numbers for things closer to the eye without -crosseyed and vice versa.
The number of distinct 3-D depths is far - near + 1. One might say that -eyesep and -depth are a more human-friendly way to specify stereoscopic parameters (distance between eyes and tradeoff between perceptibility and depth) while -planes is a more computer-centric way (pixel distances in the resulting stereogram).
This option was new in Netpbm 10.59 (June 2012).
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 pamstereogram.
This is irrelevant if you use a pattern file (-patfile option), because there is no random element to pamstereogram's behavior.
This option was new in Netpbm 10.32 (February 2006).
This option was new in Netpbm 10.91 (June 2020).
The only parameter, infile, is the name of an input file that is a depth map image. If you don't specify infile, the input is from standard input.
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. Lower (darker) numbers mean further from the eye.
pamstereogram pays no attention to the image's tuple type and ignores all planes other than plane 0.
Like any Netpbm program, pamstereogram will accept PNM input as if it were the PAM equivalent.
In a mapped-texture stereogram (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.
You create an MTS with pamstereogram by passing the filename of a PAM "texture image" with a -texfile 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.
pamstereogram 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 exact matches with the background color.
You should specify a larger-than-normal value for -eyesep (and/or -dpi) 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.
An MTS can employ a background pattern (-patfile). In this case, pamstereogram replaces background pixels with pattern pixels in the final step of generating the image.
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 white square on a black background).
With the default values for -dpi and -eyesep, pattern images that are 128 pixels wide can tile seamlessly.
Generate a SIRDS out of small, brightly colored squares and prepare it for display on an 87 DPI monitor:
pamstereogram depthmap.pam \
-dpi 87 -verbose -color -maxval 1 -magnifypat 3 \
>3d.pam
Generate a SIS by tiling a PPM file (a prior run with -verbose indicates how wide the pattern file should be for seamless tiling, although any width is acceptable for producing SISes):
pamstereogram depthmap.pam -patfile mypattern.ppm >3d.pam
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:
pamstereogram depthmap.pam \
-texfile colormap.pam -smoothing 2 -eyesep 3.5 \
>3d.pam
pam(1)
ppm3d(1)
pamstereogram was new in Netpbm 10.22 (April 2004), but probably broken beyond usability until Netpbm 10.32 (February 2006) and Netpbm 10.26.23 (January 2006).
A backward incompatible change to the way you request guide boxes (-guidetop, -guidebottom, -guidesize happened in Netpbm 10.61 (December 2012).
Copyright © 2006-2020 Scott Pakin, scott+pbm@pakin.org.
SYNOPSIS
DESCRIPTION
OPTIONS
PARAMETERS
NOTES
Input Images
Mapped-texture Stereograms
Miscellaneous
EXAMPLES
SEE ALSO
HISTORY
AUTHOR