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] [-xbegin=pixels] [-xshift=pixels] [-yshift=pixels]
13 [-yfillshift pixels] [-magnifypat=scale] [-guidetop] [-guidebottom]
14 [-guidesize=pixels] [-dpi=resolution] [-crosseyed] [-makemask] [-eye‐
15 sep=inches] [-depth=fraction] [-planes=near_pixels,far_pixels] [-ran‐
16 domseed=integer] [-tileable] [infile]
17
23 This program is part of Netpbm(1).
24 pamstereogram inputs a depth map (a map of the distances from your eye
26 of the points in a scene) and outputs a single-image stereogram (SIS).
27 A SIS is a 2-D image specially designed to appear three dimensional
28 when viewed with relaxed, slightly unfocused eyes. What's exciting
29 about single-image stereograms is that they don't require special
30 glasses to view, although it does require a bit of practice to train
31 your eyes to unfocus properly. The pamstereogram program provides a
32 wealth of control over how the stereogram is generated, including the
33 following:
34 • black and white, grayscale, or color output
38 • single-image random-dot stereograms (SIRDS), single-image stere‐
41 ograms (SIS) using a tiled image, or mapped-texture stereograms
42 (MTS)
43 • images targeting a given device resolution and eye separation
46 • optional guide boxes to assist in focusing
49 • the ability to trade off depth levels for easier viewing
52 • choice of wall-eyed or cross-eyed stereograms
55 The output is a PAM image on standard output. Options control the ex‐
59 act format of the PAM. If you want a PNM (PBM, PGM, or PPM) image, use
60 pamtopnm on the output. There is no need to convert if you will use
61 the image as input to a current Netpbm program, but many other programs
62 don't know what a PAM is.
63 To make a red/cyan type of stereogram (that you view with 3-D glasses)
65 instead, see ppm3d.
66
70 You may use either single or double hyphens to denote options. You may
71 use either whitespace or an equals sign to separate an option name from
72 its value.
73 In addition to the options common to all programs based on libnetpbm
75 (most notably -quiet, see
76 Common Options ⟨index.html#commonoptions⟩ ), pamstereogram recognizes
77 the following command line options:
78 -verbose
83 Display messages about image sizes and formats and properties of
84 the stereogram being generated.
85 -blackandwhite
88 Produce a single-image random-dot black-and-white stereogram.
89 This is the default.
90 -grayscale
93 Produce a single-image random-dot grayscale stereogram.
94 -color Produce a single-image random-dot color stereogram.
97 -maxval=value
100 Designate the maximum value of each gray/color component, i.e.
101 the color resolution. Smaller values make the output image have
102 smaller numbers of unique grays/colors. If you don't specify
103 -maxval, pamstereogram uses the maxval of the input image. This
104 option has no effect with -blackandwhite.
105 -patfile=pamfile
108 Specify an image to use as a repeated background pattern for the
109 stereogram instead of a random-dot pattern. Intricate images
110 generally produce a crisper 3-D effect that simpler images. The
111 output file will have the same maxval and format (black and
112 white, grayscale or color) as the pattern file. You cannot spec‐
113 ify the -patfile option along with -blackandwhite, -grayscale,
114 -color, or -maxval. The -verbose option will give you informa‐
115 tion on the ideal dimensions of the pattern file.
116 -xbegin=pixels
119 Specify the horizontal coordinate at which to begin stereogram
120 generation. The background pattern will be minimally distorted
121 at this point and more distorted at greater distances. Consider
122 using this in conjunction with -xshift to align the horizontal
123 start of the pattern with the horizontal start of stereogram
124 generation. -xbegin is meaningful only in conjunction with -pat‐
125 file, -makemask, or -texfile, and pamstereogram actually ignores
126 it with respect to -texfile (but may not in a future version of
127 pamstereogram).
128 The default is to begin in the center.
130 This option was new in Netpbm 10.71 (June 2015).
132 -texfile=pamfile
135 Specify an image to use as the texture for a mapped-texture
136 stereogram. The idea is that the depth-map image provides the
137 depth values of the 3-D object/scene while the texture image
138 provides the true-color values. Consequently, the texture image
139 should align with the depth-map image. (Note that it's required
140 to have the same dimensions.) The texture image's background
141 color is ignored when blending colors.
142 This option was new in Netpbm 10.53 (December 2010).
144 -bgcolor=color
148 Use color as the texture image's background color instead of
149 letting pamstereogram determine it automatically. Specify the
150 color as described for the argument of the pnm_parsecolor()
151 library routine ⟨libnetpbm_image.html#colorname⟩ . The -bgcolor
152 option is meaningful only in conjunction with -texfile.
153 This option was new in Netpbm 10.53 (December 2010).
155 -smoothing=pixels
159 When used without -texfile, attempt to eliminate artifacts in‐
160 troduced by edges in the depth map if pixels is greater than
161 zero.
162 When used with -texfile, horizontally blur non-background colors
164 into background pixels up to a distance of pixels pixels. This
165 helps smooth over distracting glitches introduced by the stere‐
166 ogram's color constraints when producing a mapped-texture stere‐
167 ogram. In this case, the -smoothing option is helpful when the
168 texture image includes smooth color transitions (as in a photo‐
169 graph) but makes crisp texture images (as in a line drawing) ap‐
170 pear blurry.
171 This option was new in Netpbm 10.53 (December 2010). Before
173 Netpbm 10.61 (December 2012), it has no effect without -texfile.
174 -xshift=pixels
178 Shift the pattern image (designated by -patfile) to the right by
179 pixels pixels (default: 0).
180 This option is valid only along with -patfile.
182 -yshift pixels
185 Shift the pattern image (designated by -patfile) downwards by
186 pixels pixels (default: 0). This option is valid only along with
187 -patfile.
188 -yfillshift pixels
191 Shift the pattern image (designated by -patfile) downwards by
192 pixels pixels (default: 0) but only after the initial population
193 of the pattern. (If used with -yshift the resulting shifts are
194 summed.) A small -yfillshift helps reduce visual artifacts in
195 the 3-D image. Steer's website, referenced under SEE ALSO
196 ⟨#seealso⟩ , recommends a shift of approximately 1/16" (6-7 pix‐
197 els at pamstereogram's default of 100 DPI).
198 This option was new in Netpbm 10.94 (March 2021).
200 -magnifypat=scale
203 Magnify each pixel in the pattern file or each random dot by in‐
204 tegral scaling factor scale. Note that pamstereogram applies the
205 pattern magnification after pattern shifting (-xshift and
206 -yshift).
207 -guidebottom
210 Draw a pair of black squares on a white background underneath
211 the stereogram proper. These squares help you guide your eyes
212 into proper focus to view the 3-D image. The trick is to focus
213 your eyes some distance behind the image, causing you to see
214 four black squares, then continue altering your focus distance
215 until the middle two black squares fuse into a single black
216 square. At that point, a crisp, 3-D image will appear.
217 This option was new in Netpbm 10.61 (December 2012). Before
219 that, the presence of -guidesize, with a positive value, has the
220 same effect.
221 -guidetop
225 Same as -guidebottom, except the guides go at the top of the im‐
226 age.
227 This option was new in Netpbm 10.61 (December 2012). Before
229 that, the presence of -guidesize, with a negative value, has the
230 same effect.
231 -guidesize=pixels
234 The size (width and height) of each guide box.
235 This is valid only with -guidetop or -guidebottom.
237 Default is 20.
239 Before Netpbm 10.61 (December 2012), if you don't specify this
241 option, pamstereogram draws no guides. If you specify it with a
242 positive value, pamstereogram behaves as if you specified
243 -guidebottom too, and if you specify it with a negative value,
244 it behaves as if you specified -guidetop and specified guidesize
245 with the absolute value of that negative value.
246 -dpi=resolution
249 Specify the resolution of the output device in dots per inch.
250 The default is 100 DPI, which represents a fairly crisp screen
251 resolution.
252 Before Netpbm 10.53 (December 2010), the default was 96 DPI.
254 -crosseyed
258 Invert the gray levels in the depth map (input image) so that
259 the 3-D image pops out of the page where it would otherwise sink
260 into the page and vice versa. Some people are unable to diverge
261 their eyes and can only cross them. The -crosseyed option en‐
262 ables such people to see the 3-D image as intended. You can
263 also specify the -crosseyed option if you prefer using depth
264 maps in which darker colors are closer to the eye and lighter
265 colors are farther from the eye.
266 Before Netpbm 10.53 (December 2010), pamstereogram used higher
268 (lighter) numbers for things closer to the eye without
269 -crosseyed and vice versa.
270 -makemask
274 Instead of a stereogram, output a PAM mask image showing color‐
275 ing constraints. New pixels will be taken from the pattern file
276 where the mask is black. Copies of existing pixels will be taken
277 from the pattern file where the mask is white. The -makemask op‐
278 tion can be used to help create more sophisticated pattern files
279 (to use with -patfile) Note that -makemask ignores -magnifypat;
280 it always produces masks that assume a pattern magnification of
281 1.
282 -eyesep=inches
285 Specify the separation in inches between your eyes. The default,
286 2.5 inches (6.4 cm), should be sufficient for most people and
287 probably doesn't need to be changed.
288 -depth=fraction
291 Specify the output image's depth of field. That is, fraction
292 represents the fractional distance of the near plane from the
293 far plane. Smaller numbers make the 3-D image easier to perceive
294 but flatter. Larger numbers make the 3-D image more difficult to
295 perceive but deeper. The default, 0.3333, generally works fairly
296 well.
297 -planes=near_pixels,far_pixels
300 Explicitly specify the distance between repeated pixels in the
301 near plane and in the far plane. This is an alternative to
302 -eyesep and -depth. The following equalities hold:
303 • eyesep = 2 * far
307 • depth = 2 * (far - near) /
309 (2 * far - near)
310 The number of distinct 3-D depths is far - near + 1. One might
313 say that -eyesep and -depth are a more human-friendly way to
314 specify stereoscopic parameters (distance between eyes and
315 tradeoff between perceptibility and depth) while -planes is a
316 more computer-centric way (pixel distances in the resulting
317 stereogram).
318 This option was new in Netpbm 10.59 (June 2012).
320 -randomseed=integer
324 Specify a seed to be used for the random number generator. The
325 default is to use a seed based on the time of day, to one second
326 granularity.
327 It is useful to specify the seed if you want to create repro‐
329 ducible results. With the same random seed, you should get
330 identical results every time you run pamstereogram.
331 This is irrelevant if you use a pattern file (-patfile option),
333 because there is no random element to pamstereogram's behavior.
334 This option was new in Netpbm 10.32 (February 2006).
336 -tileable
339 Make the generated image horizontally tileable. This works by
340 blending a left-to-right rendering (the equivalent of -xbegin=0)
341 with a right-to-left rendering (the equivalent of -xbe‐
342 gin=width-1).
343 This option was new in Netpbm 10.91 (June 2020).
345
351 The only parameter, infile, is the name of an input file that is a
352 depth map image. If you don't specify infile, the input is from stan‐
353 dard input.
354 The input is a PAM image of depth 1. Each sample represents the dis‐
356 tance from the eye that the 3-D image at that location should be.
357 Lower (darker) numbers mean further from the eye.
358
361 Input Images
362 pamstereogram pays no attention to the image's tuple type and ignores
363 all planes other than plane 0.
364 Like any Netpbm program, pamstereogram will accept PNM input as if it
366 were the PAM equivalent.
367 Mapped-texture Stereograms
370 In a mapped-texture stereogram (MTS), the 3-D image can be drawn with
371 true colors. Unlike a SIRDS or tiled-image SIS, however, the image
372 portrayed by an MTS is apparent in normal 2-D viewing. It appears re‐
373 peated multiple times and overlapped with itself, but it is not hidden.
374 You create an MTS with pamstereogram by passing the filename of a PAM
376 "texture image" with a -texfile option. A texture image portrays the
377 same 3-D object as the depth-map image but indicates the colors that
378 the program should apply to the object.
379 pamstereogram ignores the texture image's background color when it
381 overlaps copies of the 3-D object. This prevents, for example, a
382 bright-red object on a black background from being drawn as a dark-red
383 object (a blend of 50% bright red and 50% black); instead, the program
384 ignores the black and the object remains bright red. A consequence of
385 this feature is that an MTS looks best when the objects in the texture
386 image have a crisp outline. Smooth transitions to the background color
387 result in unwanted color artifacts around edges because the program ig‐
388 nores only exact matches with the background color.
389 You should specify a larger-than-normal value for -eyesep (and/or -dpi)
391 when producing an MTS. Otherwise, the 3-D object will repeat so many
392 times that most colored pixels will overlap other colored pixels, re‐
393 ducing the number of true-colored pixels that remain.
394 An MTS can employ a background pattern (-patfile). In this case, pam‐
396 stereogram replaces background pixels with pattern pixels in the final
397 step of generating the image.
398 Miscellaneous
402 A good initial test is to input an image consisting of a solid shape of
403 distance 0 within a large field of maximum distance (e.g., a white
404 square on a black background).
405 With the default values for -dpi and -eyesep, pattern images that are
407 128 pixels wide can tile seamlessly.
408
412 Generate a SIRDS out of small, brightly colored squares and prepare it
413 for display on an 87 DPI monitor:
414 pamstereogram depthmap.pam \
416 -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \
417 >3d.pam
418 Generate a SIS by tiling a PPM file (a prior run with -verbose indi‐
421 cates how wide the pattern file should be for seamless tiling, although
422 any width is acceptable for producing SISes):
423 pamstereogram depthmap.pam -patfile mypattern.ppm >3d.pam
425 Generate an MTS by associating colors with a depth-mapped object (using
428 a large eye separation to reduce the number of repetitions of the tex‐
429 ture image) and twice smoothing over background-colored speckles:
430 pamstereogram depthmap.pam \
432 -texfile colormap.pam -smoothing 2 -eyesep 3.5 \
433 >3d.pam
434
439 •
440 pam(1)
442 •
445 pamsistoaglyph(1)
447 •
450 ppm3d(1)
452 • Harold W. Thimbleby, Stuart Inglis, and Ian H. Witten. Display‐
455 ing 3D Images: Algorithms for Single Image Random Dot Stere‐
456 ograms. In IEEE Computer, 27(10):38-48, October 1994. DOI:
457 10.1109/2.318576 ⟨http://dx.doi.org/10.1109/2.318576⟩ .
458 • W. A. Steer. Stereograms: Technical Details. URL:
461 http://www.techmind.org/stereo/stech.html(1).
462
467 pamstereogram was new in Netpbm 10.22 (April 2004), but probably broken
468 beyond usability until Netpbm 10.32 (February 2006) and Netpbm 10.26.23
469 (January 2006).
470 A backward incompatible change to the way you request guide boxes
472 (-guidetop, -guidebottom, -guidesize happened in Netpbm 10.61 (December
473 2012).
474
478 Copyright © 2006-2020 Scott Pakin, scott+pbm@pakin.org.
479
482 •
483 SYNOPSIS ⟨#synopsis⟩
485 •
487 DESCRIPTION ⟨#description⟩
489 •
491 OPTIONS ⟨#options⟩
493 •
495 PARAMETERS ⟨#parameters⟩
497 •
499 NOTES ⟨#notes⟩
501 •
504 Input Images ⟨#inputimages⟩
506 •
508 Mapped-texture Stereograms ⟨#mappedtexture⟩
510 •
512 Miscellaneous ⟨#notes_misc⟩
514 •
517 EXAMPLES ⟨#examples⟩
519 •
521 SEE ALSO ⟨#seealso⟩
523 •
525 HISTORY ⟨#history⟩
527 •
529 AUTHOR ⟨#author⟩
531
533 This manual page was generated by the Netpbm tool 'makeman' from HTML
534 source. The master documentation is at
535 http://netpbm.sourceforge.net/doc/pamstereogram.html
537netpbm documentation 2 January 2021 Pamstereogram User Manual(0)