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] [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/green 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 -verbose
78 Display messages about image sizes and formats and properties of
79 the stereogram being generated.
80 -blackandwhite
83 Produce a single-image random-dot black-and-white stereogram.
84 This is the default.
85 -grayscale
88 Produce a single-image random-dot grayscale stereogram.
89 -color Produce a single-image random-dot color stereogram.
92 -maxval=value
95 Designate the maximum value of each gray/color component, i.e.
96 the color resolution. Smaller values make the output image have
97 smaller numbers of unique grays/colors. If you don't specify
98 -maxval, pamstereogram uses the maxval of the input image. This
99 option has no effect with -blackandwhite.
100 -patfile=pamfile
103 Specify an image to use as a repeated background pattern for the
104 stereogram instead of a random-dot pattern. Intricate images
105 generally produce a crisper 3-D effect that simpler images. The
106 output file will have the same maxval and format (black and
107 white, grayscale or color) as the pattern file. You cannot spec‐
108 ify the -patfile option along with -blackandwhite, -grayscale,
109 -color, or -maxval.
110 -xbegin=pixels
113 Specify the horizontal coordinate at which to begin stereogram
114 generation. The background pattern will be minimally distorted
115 at this point and more distorted at greater distances. Consider
116 using this in conjunction with -xshift to align the horizontal
117 start of the pattern with the horizontal start of stereogram
118 generation. -xbegin is meaningful only in conjunction with -pat‐
119 file, -makemask, or -texfile, and pamstereogram actually ignores
120 it with respect to -texfile (but may not in a future version of
121 pamstereogram).
122 The default is to begin in the center.
124 This option was new in Netpbm 10.71 (June 2015).
126 -texfile=pamfile
129 Specify an image to use as the texture for a mapped-texture
130 stereogram. The idea is that the depth-map image provides the
131 depth values of the 3-D object/scene while the texture image
132 provides the true-color values. Consequently, the texture image
133 should align with the depth-map image. (Note that it's required
134 to have the same dimensions.) The texture image's background
135 color is ignored when blending colors.
136 This option was new in Netpbm 10.53 (December 2010).
138 -bgcolor=color
142 Use color as the texture image's background color instead of
143 letting pamstereogram determine it automatically. Specify the
144 color as described for the argument of the ppm_parsecolor()
145 library routine ⟨libppm.html#colorname⟩ . The -bgcolor option
146 is meaningful only in conjunction with -texfile.
147 This option was new in Netpbm 10.53 (December 2010).
149 -smoothing=pixels
153 When used without -texfile, attempt to eliminate artifacts
154 introduced by edges in the depth map if pixels is greater than
155 zero.
156 When used with -texfile, horizontally blur non-background colors
158 into background pixels up to a distance of pixels pixels. This
159 helps smooth over distracting glitches introduced by the stere‐
160 ogram's color constraints when producing a mapped-texture stere‐
161 ogram. In this case, the -smoothing option is helpful when the
162 texture image includes smooth color transitions (as in a photo‐
163 graph) but makes crisp texture images (as in a line drawing)
164 appear blurry.
165 This option was new in Netpbm 10.53 (December 2010). Before
167 Netpbm 10.61 (December 2012), it has no effect without -texfile.
168 -xshift=pixels
172 Shift the pattern image (designated by -patfile) to the right by
173 pixels pixels (default: 0).
174 This option is valid only along with -patfile.
176 -yshift pixels
179 Shift the pattern image (designated by -patfile) downwards by
180 pixels pixels (default: 0). This option is valid only along with
181 -patfile.
182 -magnifypat=scale
185 Magnify each pixel in the pattern file or each random dot by
186 integral scaling factor scale. Note that pamstereogram applies
187 the pattern magnification after pattern shifting (-xshift and
188 -yshift).
189 -guidebottom
192 Draw a pair of black squares on a white background underneath
193 the stereogram proper. These squares help you guide your eyes
194 into proper focus to view the 3-D image. The trick is to focus
195 your eyes some distance behind the image, causing you to see
196 four black squares, then continue altering your focus distance
197 until the middle two black squares fuse into a single black
198 square. At that point, a crisp, 3-D image will appear.
199 This option was new in Netpbm 10.61 (December 2012). Before
201 that, the presence of -guidesize, with a positive value, has the
202 same effect.
203 -guidetop
207 Same as -guidebottom, except the guides go at the top of the
208 image.
209 This option was new in Netpbm 10.61 (December 2012). Before
211 that, the presence of -guidesize, with a negative value, has the
212 same effect.
213 -guidesize=pixels
216 The size (width and height) of each guide box.
217 This is valid only with -guidetop or -guidebottom.
219 Default is 20.
221 Before Netpbm 10.61 (December 2012), if you don't specify this
223 option, pamstereogram draws no guides. If you specify it with a
224 positive value, pamstereogram behaves as if you specified
225 -guidebottom too, and if you specify it with a negative value,
226 it behaves as if you specified -guidetop and specified guidesize
227 with the absolute value of that negative value.
228 -dpi=resolution
231 Specify the resolution of the output device in dots per inch.
232 The default is 100 DPI, which represents a fairly crisp screen
233 resolution.
234 Before Netpbm 10.53 (December 2010), the default was 96 DPI.
236 -crosseyed
240 Invert the gray levels in the depth map (input image) so that
241 the 3-D image pops out of the page where it would otherwise sink
242 into the page and vice versa. Some people are unable to diverge
243 their eyes and can only cross them. The -crosseyed option
244 enables such people to see the 3-D image as intended. You can
245 also specify the -crosseyed option if you prefer using depth
246 maps in which darker colors are closer to the eye and lighter
247 colors are farther from the eye.
248 Before Netpbm 10.53 (December 2010), pamstereogram used higher
250 (lighter) numbers for things closer to the eye without
251 -crosseyed and vice versa.
252 -makemask
256 Instead of a stereogram, output a PAM mask image showing color‐
257 ing constraints. New pixels will be taken from the pattern file
258 where the mask is black. Copies of existing pixels will be taken
259 from the pattern file where the mask is white. The -makemask
260 option can be used to help create more sophisticated pattern
261 files (to use with -patfile) Note that -makemask ignores -magni‐
262 fypat; it always produces masks that assume a pattern magnifica‐
263 tion of 1.
264 -eyesep=inches
267 Specify the separation in inches between your eyes. The default,
268 2.5 inches (6.4 cm), should be sufficient for most people and
269 probably doesn't need to be changed.
270 -depth=fraction
273 Specify the output image's depth of field. That is, fraction
274 represents the fractional distance of the near plane from the
275 far plane. Smaller numbers make the 3-D image easier to perceive
276 but flatter. Larger numbers make the 3-D image more difficult to
277 perceive but deeper. The default, 0.3333, generally works fairly
278 well.
279 -planes=near_pixels,far_pixels
282 Explicitly specify the distance between repeated pixels in the
283 near plane and in the far plane. This is an alternative to
284 -eyesep and -depth. The following equalities hold:
285 · eyesep = 2 * far
289 · depth = 2 * (far - near) /
291 (2 * far - near)
292 The number of distinct 3-D depths is far - near + 1. One might
295 say that -eyesep and -depth are a more human-friendly way to
296 specify stereoscopic parameters (distance between eyes and
297 tradeoff between perceptibility and depth) while -planes is a
298 more computer-centric way (pixel distances in the resulting
299 stereogram).
300 This option was new in Netpbm 10.59 (June 2012).
302 -randomseed=integer
306 Specify a seed to be used for the random number generator. The
307 default is to use a seed based on the time of day, to one second
308 granularity.
309 It is useful to specify the seed if you want to create repro‐
311 ducible results. With the same random seed, you should get
312 identical results every time you run pamstereogram.
313 This is irrelevant if you use a pattern file (-patfile option),
315 because there is no random element to pamstereogram's behavior.
316 This option was new in Netpbm 10.32 (February 2006).
318
325 The only parameter, infile, is the name of an input file that is a
326 depth map image. If you don't specify infile, the input is from stan‐
327 dard input.
328 The input is a PAM image of depth 1. Each sample represents the dis‐
330 tance from the eye that the 3-D image at that location should be.
331 Lower (darker) numbers mean further from the eye.
332
335 Input Images
336 pamstereogram pays no attention to the image's tuple type and ignores
337 all planes other than plane 0.
338 Like any Netpbm program, pamstereogram will accept PNM input as if it
340 were the PAM equivalent.
341 Mapped-texture Stereograms
344 In a mapped-texture stereogram (MTS), the 3-D image can be drawn with
345 true colors. Unlike a SIRDS or tiled-image SIS, however, the image
346 portrayed by an MTS is apparent in normal 2-D viewing. It appears
347 repeated multiple times and overlapped with itself, but it is not hid‐
348 den.
349 You create an MTS with pamstereogram by passing the filename of a PAM
351 "texture image" with a -texfile option. A texture image portrays the
352 same 3-D object as the depth-map image but indicates the colors that
353 the program should apply to the object.
354 pamstereogram ignores the texture image's background color when it
356 overlaps copies of the 3-D object. This prevents, for example, a
357 bright-red object on a black background from being drawn as a dark-red
358 object (a blend of 50% bright red and 50% black); instead, the program
359 ignores the black and the object remains bright red. A consequence of
360 this feature is that an MTS looks best when the objects in the texture
361 image have a crisp outline. Smooth transitions to the background color
362 result in unwanted color artifacts around edges because the program
363 ignores only exact matches with the background color.
364 You should specify a larger-than-normal value for -eyesep (and/or -dpi)
366 when producing an MTS. Otherwise, the 3-D object will repeat so many
367 times that most colored pixels will overlap other colored pixels,
368 reducing the number of true-colored pixels that remain.
369 An MTS can employ a background pattern (-patfile). In this case, pam‐
371 stereogram replaces background pixels with pattern pixels in the final
372 step of generating the image.
373 Miscellaneous
377 A good initial test is to input an image consisting of a solid shape of
378 distance 0 within a large field of maximum distance (e.g., a white
379 square on a black background).
380 With the default values for -dpi and -eyesep, pattern images that are
382 128 pixels wide can tile seamlessly.
383
387 Generate a SIRDS out of small, brightly colored squares and prepare it
388 for display on an 87 DPI monitor:
389 pamstereogram depthmap.pam \
391 -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \
392 >3d.pam
393 Generate a SIS by tiling a PPM file (a prior run with -verbose indi‐
395 cates how wide the pattern file should be for seamless tiling, although
396 any width is acceptable for producing SISes):
397 pamstereogram depthmap.pam -patfile mypattern.ppm >3d.pam
399 Generate an MTS by associating colors with a depth-mapped object (using
401 a large eye separation to reduce the number of repetitions of the tex‐
402 ture image) and twice smoothing over background-colored speckles:
403 pamstereogram depthmap.pam \
405 -texfile colormap.pam -smoothing 2 -eyesep 3.5 \
406 >3d.pam
407
411 ·
412 pam(1)
414 ·
417 pamsistoaglyph(1)
419 ·
422 ppm3d(1)
424 · Harold W. Thimbleby, Stuart Inglis, and Ian H. Witten. Display‐
427 ing 3D Images: Algorithms for Single Image Random Dot Stere‐
428 ograms. In IEEE Computer, 27(10):38-48, October 1994. DOI:
429 10.1109/2.318576 ⟨http://dx.doi.org/10.1109/2.318576⟩ .
430 · W. A. Steer. Stereograms: Technical Details. URL:
433 http://www.techmind.org/stereo/stech.html(1).
434
439 pamstereogram was new in Netpbm 10.22 (April 2004), but probably broken
440 beyond usability until Netpbm 10.32 (February 2006) and Netpbm 10.26.23
441 (January 2006).
442 A backward incompatible change to the way you request guide boxes
444 (-guidetop, -guidebottom, -guidesize happened in Netpbm 10.61 (December
445 2012).
446
450 Copyright © 2006-2015 Scott Pakin, scott+pbm@pakin.org.
451
454 ·
455 SYNOPSIS ⟨#synopsis⟩
457 ·
459 DESCRIPTION ⟨#description⟩
461 ·
463 OPTIONS ⟨#options⟩
465 ·
467 PARAMETERS ⟨#parameters⟩
469 ·
471 NOTES ⟨#notes⟩
473 ·
476 Input Images ⟨#inputimages⟩
478 ·
480 Mapped-texture Stereograms ⟨#mappedtexture⟩
482 ·
484 Miscellaneous ⟨#notes_misc⟩
486 ·
490 EXAMPLES ⟨#examples⟩
492 ·
494 SEE ALSO ⟨#seealso⟩
496 ·
498 HISTORY ⟨#history⟩
500 ·
502 AUTHOR ⟨#author⟩
504
506 This manual page was generated by the Netpbm tool 'makeman' from HTML
507 source. The master documentation is at
508 http://netpbm.sourceforge.net/doc/pamstereogram.html
510netpbm documentation 19 June 2015 Pamstereogram User Manual(0)