1Pamstereogram User Manual(0)                      Pamstereogram User Manual(0)
2
3
4

NAME

6       pamstereogram - create a single-image stereogram from a PAM depth map
7
8

SYNOPSIS

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
18
19
20
21

DESCRIPTION

23       This program is part of Netpbm(1).
24
25       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
35
36
37       ·      black and white, grayscale, or color output
38
39
40       ·      single-image random-dot stereograms (SIRDS), single-image stere‐
41              ograms (SIS) using a tiled image, or mapped-texture  stereograms
42              (MTS)
43
44
45       ·      images targeting a given device resolution and eye separation
46
47
48       ·      optional guide boxes to assist in focusing
49
50
51       ·      the ability to trade off depth levels for easier viewing
52
53
54       ·      choice of wall-eyed or cross-eyed stereograms
55
56
57
58       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
64       To make a red/green type of stereogram (that you view with 3-D glasses)
65       instead, see ppm3d.
66
67
68

OPTIONS

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
74
75
76
77       -verbose
78              Display messages about image sizes and formats and properties of
79              the stereogram being generated.
80
81
82       -blackandwhite
83              Produce  a  single-image  random-dot black-and-white stereogram.
84              This is the default.
85
86
87       -grayscale
88              Produce a single-image random-dot grayscale stereogram.
89
90
91       -color Produce a single-image random-dot color stereogram.
92
93
94       -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
101
102       -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
111
112       -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
123              The default is to begin in the center.
124
125              This option was new in Netpbm 10.71 (June 2015).
126
127
128       -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
137              This option was new in Netpbm 10.53 (December 2010).
138
139
140
141       -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
148              This option was new in Netpbm 10.53 (December 2010).
149
150
151
152       -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
157              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
166              This  option  was  new  in Netpbm 10.53 (December 2010).  Before
167              Netpbm 10.61 (December 2012), it has no effect without -texfile.
168
169
170
171       -xshift=pixels
172              Shift the pattern image (designated by -patfile) to the right by
173              pixels pixels (default: 0).
174
175              This option is valid only along with -patfile.
176
177
178       -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
183
184       -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
190
191       -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
200              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
204
205
206       -guidetop
207              Same as -guidebottom, except the guides go at  the  top  of  the
208              image.
209
210              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
214
215       -guidesize=pixels
216              The size (width and height) of each guide box.
217
218              This is valid only with -guidetop or -guidebottom.
219
220              Default is 20.
221
222              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
229
230       -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
235              Before Netpbm 10.53 (December 2010), the default was 96 DPI.
236
237
238
239       -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
249              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
253
254
255       -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
265
266       -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
271
272       -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
280
281       -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
286
287
288       ·      eyesep = 2 * far
289
290       ·      depth = 2 * (far - near) /
291                    (2 * far - near)
292
293
294              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
301              This option was new in Netpbm 10.59 (June 2012).
302
303
304
305       -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
310              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
314              This is irrelevant if you use a pattern file (-patfile  option),
315              because there is no random element to pamstereogram's behavior.
316
317              This option was new in Netpbm 10.32 (February 2006).
318
319
320
321
322
323

PARAMETERS

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
329       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
333

NOTES

335   Input Images
336       pamstereogram  pays  no attention to the image's tuple type and ignores
337       all planes other than plane 0.
338
339       Like any Netpbm program, pamstereogram will accept PNM input as  if  it
340       were the PAM equivalent.
341
342
343   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
350       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
355       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
365       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
370       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
374
375
376   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
381       With  the  default values for -dpi and -eyesep, pattern images that are
382       128 pixels wide can tile seamlessly.
383
384
385

EXAMPLES

387       Generate a SIRDS out of small, brightly colored squares and prepare  it
388       for display on an 87 DPI monitor:
389
390           pamstereogram depthmap.pam \
391               -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \
392               >3d.pam
393
394       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
398           pamstereogram depthmap.pam -patfile mypattern.ppm >3d.pam
399
400       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
404           pamstereogram depthmap.pam \
405               -texfile colormap.pam -smoothing 2 -eyesep 3.5 \
406               >3d.pam
407
408
409

SEE ALSO

411       ·
412
413              pam(1)
414
415
416       ·
417
418              pamsistoaglyph(1)
419
420
421       ·
422
423              ppm3d(1)
424
425
426       ·      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
431
432       ·      W.   A.   Steer.    Stereograms:   Technical   Details.     URL:
433              http://www.techmind.org/stereo/stech.html(1).
434
435
436
437

HISTORY

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
443       A  backward  incompatible  change  to  the  way you request guide boxes
444       (-guidetop, -guidebottom, -guidesize happened in Netpbm 10.61 (December
445       2012).
446
447
448

AUTHOR

450       Copyright © 2006-2015 Scott Pakin, scott+pbm@pakin.org.
451
452

Table Of Contents

454       ·
455
456              SYNOPSIS ⟨#synopsis⟩
457
458       ·
459
460              DESCRIPTION ⟨#description⟩
461
462       ·
463
464              OPTIONS ⟨#options⟩
465
466       ·
467
468              PARAMETERS ⟨#parameters⟩
469
470       ·
471
472              NOTES ⟨#notes⟩
473
474
475       ·
476
477              Input Images ⟨#inputimages⟩
478
479       ·
480
481              Mapped-texture Stereograms ⟨#mappedtexture⟩
482
483       ·
484
485              Miscellaneous ⟨#notes_misc⟩
486
487
488
489       ·
490
491              EXAMPLES ⟨#examples⟩
492
493       ·
494
495              SEE ALSO ⟨#seealso⟩
496
497       ·
498
499              HISTORY ⟨#history⟩
500
501       ·
502
503              AUTHOR ⟨#author⟩
504

DOCUMENT SOURCE

506       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
507       source.  The master documentation is at
508
509              http://netpbm.sourceforge.net/doc/pamstereogram.html
510
511netpbm documentation             19 June 2015     Pamstereogram User Manual(0)
Impressum