1Pamstereogram User Manual(0) Pamstereogram User Manual(0)
2
6 pamstereogram - create a single-image stereogram from a PAM depth map
7
10 pamstereogram [-help] [-verbose] [-blackandwhite | -grayscale | -color]
11 [-maxval=value] [-patfile=pamfile] [-texfile=pamfile] [-bgcolor=color]
12 [-smoothing=pixels] [-xshift=pixels] [-yshift=pixels] [-magnify‐
13 pat=scale] [-guidesize=pixels] [-dpi=resolution] [-crosseyed] [-make‐
14 mask] [-eyesep=inches] [-depth=fraction] [-randomseed=integer] [infile]
15
21 This program is part of Netpbm(1).
22 pamstereogram inputs a depth map (a map of the distances from your eye
24 of the points in a scene) and outputs a single-image stereogram (SIS).
25 A SIS is a 2-D image specially designed to appear three dimensional
26 when viewed with relaxed, slightly unfocused eyes. What's exciting
27 about single-image stereograms is that they don't require special
28 glasses to view, although it does require a bit of practice to train
29 your eyes to unfocus properly. The pamstereogram program provides a
30 wealth of control over how the stereogram is generated, including the
31 following:
32 · black and white, grayscale, or color output
36 · single-image random-dot stereograms (SIRDS), single-image stere‐
39 ograms (SIS) using a tiled image, or mapped-texture stereograms
40 (MTS)
41 · images targeting a given device resolution and eye separation
44 · optional guide boxes to assist in focusing
47 · the ability to trade off depth levels for easier viewing
50 · choice of wall-eyed or cross-eyed stereograms
53 The output is a PAM image on standard output. Options control the
57 exact format of the PAM. If you want a PNM (PBM, PGM, or PPM) image,
58 use pamtopnm on the output. There is no need to convert if you will
59 use the image as input to a current Netpbm program, but many other pro‐
60 grams don't know what a PAM is.
61 To make a red/green type of stereogram (that you view with 3-D glasses)
63 instead, see ppm3d.
64
68 You may use either single or double hyphens to denote options. You may
69 use either whitespace or an equals sign to separate an option name from
70 its value.
71 -verbose
76 Display messages about image sizes and formats and properties of
77 the stereogram being generated.
78 -blackandwhite
81 Produce a single-image random-dot black-and-white stereogram.
82 This is the default.
83 -grayscale
86 Produce a single-image random-dot grayscale stereogram.
87 -color Produce a single-image random-dot color stereogram.
90 -maxval=value
93 Designate the maximum value of each gray/color component, i.e.
94 the color resolution. Smaller values make the output image have
95 smaller numbers of unique grays/colors. If you don't specify
96 -maxval, pamstereogram uses the maxval of the input image. This
97 option has no effect with -blackandwhite.
98 -patfile=pamfile
101 Specify an image to use as a repeated background pattern for the
102 stereogram instead of a random-dot pattern. Intricate images
103 generally produce a crisper 3-D effect that simpler images. The
104 output file will have the same maxval and format (black and
105 white, grayscale or color) as the pattern file. You cannot spec‐
106 ify the -patfile option along with -blackandwhite, -grayscale,
107 -color, or -maxval.
108 -texfile=pamfile
111 Specify an image to use as the texture for a mapped-texture
112 stereogram. The idea is that the depth-map image provides the
113 depth values of the 3-D object/scene while the texture image
114 provides the true-color values. Consequently, the texture image
115 should align with the depth-map image. (Note that it's required
116 to have the same dimensions.) The texture image's background
117 color is ignored when blending colors.
118 This option was new in Netpbm 10.53 (December 2010).
120 -bgcolor=color
123 Use color as the texture image's background color instead of
124 letting pamstereogram determine it automatically. Specify the
125 color as described for the argument of the ppm_parsecolor()
126 library routine ⟨libppm.html#colorname⟩ . The -bgcolor option
127 is meaningful only in conjunction with -texfile.
128 This option was new in Netpbm 10.53 (December 2010).
130 -smoothing=pixels
133 Horizontally blur non-background colors into background pixels
134 up to a distance of pixels pixels (default: 0). This helps
135 smooth over distracting glitches introduced by the stereogram's
136 color constraints when producing a mapped-texture stereogram.
137 The -smoothing option is helpful when the texture image includes
138 smooth color transitions (as in a photograph) but makes crisp
139 texture images (as in a line drawing) appear blurry. The
140 -smoothing option is meaningful only in conjunction with -tex‐
141 file.
142 This option was new in Netpbm 10.53 (December 2010).
144 -xshift=pixels
148 Shift the pattern image (designated by -patfile) to the right by
149 pixels pixels (default: 0). This option is valid only along
150 with -patfile.
151 -yshift pixels
154 Shift the pattern image (designated by -patfile) downwards by
155 pixels pixels (default: 0). This option is valid only along with
156 -patfile.
157 -magnifypat=scale
160 Magnify each pixel in the pattern file or each random dot by
161 integral scaling factor scale. Note that pamstereogram applies
162 the pattern magnification after pattern shifting (-xshift and
163 -yshift).
164 -guidesize=pixels
167 Draw a pair of pixels by pixels black squares on a white back‐
168 ground underneath the stereogram proper. These squares help you
169 guide your eyes into proper focus to view the 3-D image. The
170 trick is to focus your eyes some distance behind the image,
171 causing you to see four black squares, then continue altering
172 your focus distance until the middle two black squares fuse into
173 a single black square. At that point, a crisp, 3-D image will
174 appear.
175 If pixels is negative, pamstereogram will draw the guide squares
177 above the stereogram instead of below it. If pixels is zero (the
178 default), pamstereogram will draw no guide squares.
179 -dpi=resolution
183 Specify the resolution of the output device in dots per inch.
184 The default is 100 DPI, which represents a fairly crisp screen
185 resolution.
186 Before Netpbm 10.53 (December 2010), the default was 96 DPI.
188 -crosseyed
193 Invert the gray levels in the depth map (input image) so that
194 the 3-D image pops out of the page where it would otherwise sink
195 into the page and vice versa. Some people are unable to diverge
196 their eyes and can only cross them. The -crosseyed option
197 enables such people to see the 3-D image as intended. You can
198 also specify the -crosseyed option if you prefer using depth
199 maps in which darker colors are closer to the eye and lighter
200 colors are farther from the eye.
201 Before Netpbm 10.53 (December 2010), pamstereogram used higher
203 (lighter) numbers for things closer to the eye without
204 -crosseyed and vice versa.
205 -makemask
212 Instead of a stereogram, output a PAM mask image showing color‐
213 ing constraints. New pixels will be taken from the pattern file
214 where the mask is black. Copies of existing pixels will be taken
215 from the pattern file where the mask is white. The -makemask
216 option can be used to help create more sophisticated pattern
217 files (to use with -patfile) Note that -makemask ignores -magni‐
218 fypat; it always produces masks that assume a pattern magnifica‐
219 tion of 1.
220 -eyesep=inches
223 Specify the separation in inches between your eyes. The default,
224 2.5 inches (6.4 cm), should be sufficient for most people and
225 probably doesn't need to be changed.
226 -depth=fraction
229 Specify the output image's depth of field. That is, fraction
230 represents the fractional distance of the near plane from the
231 far plane. Smaller numbers make the 3-D image easier to perceive
232 but flatter. Larger numbers make the 3-D image more difficult to
233 perceive but deeper. The default, 0.3333, generally works fairly
234 well.
235 -randomseed=integer
238 Specify a seed to be used for the random number generator. The
239 default is to use a seed based on the time of day, to one second
240 granularity.
241 It is useful to specify the seed if you want to create repro‐
243 ducible results. With the same random seed, you should get
244 identical results every time you run pamstereogram.
245 This is irrelevant if you use a pattern file (-patfile option),
247 because there is no random element to pamstereogram's behavior.
248 This option was new in Netpbm 10.32 (February 2006).
250
256 The only parameter, infile, is the name of an input file that is a
257 depth map image. If you don't specify infile, the input is from stan‐
258 dard input.
259 The input is a PAM image of depth 1. Each sample represents the dis‐
261 tance from the eye that the 3-D image at that location should be.
262 Lower (darker) numbers mean further from the eye.
263
266 Input Images
267 pamstereogram pays no attention the the image's tuple type and ignores
268 all planes other than plane 0.
269 Like any Netpbm program, pamstereogram will accept PNM input as if it
271 were the PAM equivalent.
272 Mapped-texture Stereograms
275 In a mapped-texture stereogram (MTS), the 3-D image can be drawn with
276 true colors. Unlike a SIRDS or tiled-image SIS, however, the image
277 portrayed by an MTS is apparent in normal 2-D viewing. It appears
278 repeated multiple times and overlapped with itself, but it is not hid‐
279 den.
280 You create an MTS with pamstereogram by passing the filename of a PAM
282 <q>texture image</q> with a -texfile option. A texture image portrays
283 the same 3-D object as the depth-map image but indicates the colors
284 that the program should apply to the object.
285 pamstereogram ignores the texture image's background color when it
287 overlaps copies of the 3-D object. This prevents, for example, a
288 bright-red object on a black background from being drawn as a dark-red
289 object (a blend of 50% bright red and 50% black); instead, the program
290 ignores the black and the object remains bright red. A consequence of
291 this feature is that an MTS looks best when the objects in the texture
292 image have a crisp outline. Smooth transitions to the background color
293 result in unwanted color artifacts around edges because the program
294 ignores only exact matches with the background color.
295 You should specify a larger-than-normal value for -eyesep (and/or -dpi)
297 when producing an MTS. Otherwise, the 3-D object will repeat so many
298 times that most colored pixels will overlap other colored pixels,
299 reducing the number of true-colored pixels that remain.
300 An MTS can employ a background pattern (-patfile). In this case, pam‐
302 stereogram replaces background pixels with pattern pixels in the final
303 step of generating the image.
304 Miscellaneous
308 A good initial test is to input an image consisting of a solid shape of
309 distance 0 within a large field of maximum distance (e.g., a white
310 square on a black background).
311 With the default values for -dpi and -eyesep, pattern images that are
313 128 pixels wide can tile seamlessly.
314
318 Generate a SIRDS out of small, brightly colored squares and prepare it
319 for display on an 87 DPI monitor:
320 pamstereogram depthmap.pam \
322 -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \
323 >3d.pam
324 Generate a SIS by tiling a PPM file (a prior run with -verbose indi‐
326 cates how wide the pattern file should be for seamless tiling, although
327 any width is acceptable for producing SISes):
328 pamstereogram depthmap.pam -patfile mypattern.ppm >3d.pam
330 Generate an MTS by associating colors with a depth-mapped object (using
332 a large eye separation to reduce the number of repetitions of the tex‐
333 ture image) and twice smoothing over background-colored speckles:
334 pamstereogram depthmap.pam \
336 -texfile colormap.pam -smoothing 2 -eyesep 3.5 \
337 >3d.pam
338
342 ·
343 pam(1)
345 ·
348 pamsistoaglyph(1)
350 ·
353 ppm3d(1)
355 · Harold W. Thimbleby, Stuart Inglis, and Ian H. Witten. Display‐
359 ing 3D Images: Algorithms for Single Image Random Dot Stere‐
360 ograms. In IEEE Computer, 27(10):38-48, October 1994. DOI
361 10.1109/2.318576 ⟨http://dx.doi.org/10.1109/2.318576⟩ .
362
368 pamstereogram was new in Netpbm 10.22 (April 2004), but probably broken
369 beyond usability until Netpbm 10.32 (Februrary 2006) and Netpbm
370 10.26.23 (January 2006).
371
375 Copyright (C) 2006, 2010 Scott Pakin, scott+pbm@pakin.org.
376
378 ·
379 SYNOPSIS ⟨#synopsis⟩
381 ·
383 DESCRIPTION ⟨#description⟩
385 ·
387 OPTIONS ⟨#options⟩
389 ·
391 PARAMETERS ⟨#parameters⟩
393 ·
395 NOTES ⟨#notes⟩
397 ·
400 Input Images ⟨inputimages⟩
402 ·
404 Mapped-texture Stereograms ⟨mappedtexture⟩
406 ·
408 Miscellaneous ⟨notes_misc⟩
410 ·
414 EXAMPLES ⟨#examples⟩
416 ·
418 SEE ALSO ⟨#seealso⟩
420 ·
422 HISTORY ⟨#history⟩
424 ·
426 AUTHOR ⟨#author⟩
428netpbm documentation 28 September 2010 Pamstereogram User Manual(0)