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 [-magnifypat=scale] [-guidetop] [-guidebottom] [-guidesize=pixels]
14 [-dpi=resolution] [-crosseyed] [-makemask] [-eyesep=inches]
15 [-depth=fraction] [-planes=near_pixels,far_pixels] [-randomseed=inte‐
16 ger] [-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
59 exact format of the PAM. If you want a PNM (PBM, PGM, or PPM) image,
60 use pamtopnm on the output. There is no need to convert if you will
61 use the image as input to a current Netpbm program, but many other pro‐
62 grams 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.TP
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
160 introduced 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)
170 appear 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"
197 (6–7 pixels 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
204 integral scaling factor scale. Note that pamstereogram applies
205 the 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
226 image.
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
262 enables 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
278 option can be used to help create more sophisticated pattern
279 files (to use with -patfile) Note that -makemask ignores -magni‐
280 fypat; it always produces masks that assume a pattern magnifica‐
281 tion of 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
325 Specify a seed to be used for the random number generator. The
326 default is to use a seed based on the time of day, to one second
327 granularity.
328 It is useful to specify the seed if you want to create repro‐
330 ducible results. With the same random seed, you should get
331 identical results every time you run pamstereogram.
332 This is irrelevant if you use a pattern file (-patfile option),
334 because there is no random element to pamstereogram's behavior.
335 This option was new in Netpbm 10.32 (February 2006).
337 -tileable
340 Make the generated image horizontally tileable. This works by
341 blending a left-to-right rendering (the equivalent of -xbegin=0)
342 with a right-to-left rendering (the equivalent of -xbe‐
343 gin=width-1).
344 This option was new in Netpbm 10.91 (June 2020).
346
352 The only parameter, infile, is the name of an input file that is a
353 depth map image. If you don't specify infile, the input is from stan‐
354 dard input.
355 The input is a PAM image of depth 1. Each sample represents the dis‐
357 tance from the eye that the 3-D image at that location should be.
358 Lower (darker) numbers mean further from the eye.
359
362 Input Images
363 pamstereogram pays no attention to the image's tuple type and ignores
364 all planes other than plane 0.
365 Like any Netpbm program, pamstereogram will accept PNM input as if it
367 were the PAM equivalent.
368 Mapped-texture Stereograms
371 In a mapped-texture stereogram (MTS), the 3-D image can be drawn with
372 true colors. Unlike a SIRDS or tiled-image SIS, however, the image
373 portrayed by an MTS is apparent in normal 2-D viewing. It appears
374 repeated multiple times and overlapped with itself, but it is not hid‐
375 den.
376 You create an MTS with pamstereogram by passing the filename of a PAM
378 "texture image" with a -texfile option. A texture image portrays the
379 same 3-D object as the depth-map image but indicates the colors that
380 the program should apply to the object.
381 pamstereogram ignores the texture image's background color when it
383 overlaps copies of the 3-D object. This prevents, for example, a
384 bright-red object on a black background from being drawn as a dark-red
385 object (a blend of 50% bright red and 50% black); instead, the program
386 ignores the black and the object remains bright red. A consequence of
387 this feature is that an MTS looks best when the objects in the texture
388 image have a crisp outline. Smooth transitions to the background color
389 result in unwanted color artifacts around edges because the program
390 ignores only exact matches with the background color.
391 You should specify a larger-than-normal value for -eyesep (and/or -dpi)
393 when producing an MTS. Otherwise, the 3-D object will repeat so many
394 times that most colored pixels will overlap other colored pixels,
395 reducing the number of true-colored pixels that remain.
396 An MTS can employ a background pattern (-patfile). In this case, pam‐
398 stereogram replaces background pixels with pattern pixels in the final
399 step of generating the image.
400 Miscellaneous
404 A good initial test is to input an image consisting of a solid shape of
405 distance 0 within a large field of maximum distance (e.g., a white
406 square on a black background).
407 With the default values for -dpi and -eyesep, pattern images that are
409 128 pixels wide can tile seamlessly.
410
414 Generate a SIRDS out of small, brightly colored squares and prepare it
415 for display on an 87 DPI monitor:
416 pamstereogram depthmap.pam \
418 -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \
419 >3d.pam
420 Generate a SIS by tiling a PPM file (a prior run with -verbose indi‐
422 cates how wide the pattern file should be for seamless tiling, although
423 any width is acceptable for producing SISes):
424 pamstereogram depthmap.pam -patfile mypattern.ppm >3d.pam
426 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
438 ·
439 pam(1)
441 ·
444 pamsistoaglyph(1)
446 ·
449 ppm3d(1)
451 · Harold W. Thimbleby, Stuart Inglis, and Ian H. Witten. Display‐
454 ing 3D Images: Algorithms for Single Image Random Dot Stere‐
455 ograms. In IEEE Computer, 27(10):38-48, October 1994. DOI:
456 10.1109/2.318576 ⟨http://dx.doi.org/10.1109/2.318576⟩ .
457 · W. A. Steer. Stereograms: Technical Details. URL:
460 http://www.techmind.org/stereo/stech.html(1).
461
466 pamstereogram was new in Netpbm 10.22 (April 2004), but probably broken
467 beyond usability until Netpbm 10.32 (February 2006) and Netpbm 10.26.23
468 (January 2006).
469 A backward incompatible change to the way you request guide boxes
471 (-guidetop, -guidebottom, -guidesize happened in Netpbm 10.61 (December
472 2012).
473
477 Copyright © 2006-2020 Scott Pakin, scott+pbm@pakin.org.
478
481 ·
482 SYNOPSIS ⟨#synopsis⟩
484 ·
486 DESCRIPTION ⟨#description⟩
488 ·
490 OPTIONS ⟨#options⟩
492 ·
494 PARAMETERS ⟨#parameters⟩
496 ·
498 NOTES ⟨#notes⟩
500 ·
503 Input Images ⟨#inputimages⟩
505 ·
507 Mapped-texture Stereograms ⟨#mappedtexture⟩
509 ·
511 Miscellaneous ⟨#notes_misc⟩
513 ·
516 EXAMPLES ⟨#examples⟩
518 ·
520 SEE ALSO ⟨#seealso⟩
522 ·
524 HISTORY ⟨#history⟩
526 ·
528 AUTHOR ⟨#author⟩
530
532 This manual page was generated by the Netpbm tool 'makeman' from HTML
533 source. The master documentation is at
534 http://netpbm.sourceforge.net/doc/pamstereogram.html
536netpbm documentation 2 January 2021 Pamstereogram User Manual(0)