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       [-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
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 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
64       To  make a red/cyan 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       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
79
80
81
82       -verbose
83              Display messages about image sizes and formats and properties of
84              the stereogram being generated.
85
86
87       -blackandwhite
88              Produce  a  single-image  random-dot black-and-white stereogram.
89              This is the default.
90
91
92       -grayscale
93              Produce a single-image random-dot grayscale stereogram.
94
95
96       -color Produce a single-image random-dot color stereogram.
97
98
99       -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
106
107       -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
117
118       -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
129              The default is to begin in the center.
130
131              This option was new in Netpbm 10.71 (June 2015).
132
133
134       -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
143              This option was new in Netpbm 10.53 (December 2010).
144
145
146
147       -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
154              This option was new in Netpbm 10.53 (December 2010).
155
156
157
158       -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
163              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
172              This option was new in Netpbm  10.53  (December  2010).   Before
173              Netpbm 10.61 (December 2012), it has no effect without -texfile.
174
175
176
177       -xshift=pixels
178              Shift the pattern image (designated by -patfile) to the right by
179              pixels pixels (default: 0).
180
181              This option is valid only along with -patfile.
182
183
184       -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
189
190       -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
199              This option was new in Netpbm 10.94 (March 2021).
200
201
202       -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
208
209       -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
218              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
222
223
224       -guidetop
225              Same as -guidebottom, except the guides go at the top of the im‐
226              age.
227
228              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
232
233       -guidesize=pixels
234              The size (width and height) of each guide box.
235
236              This is valid only with -guidetop or -guidebottom.
237
238              Default is 20.
239
240              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
247
248       -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
253              Before Netpbm 10.53 (December 2010), the default was 96 DPI.
254
255
256
257       -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
267              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
271
272
273       -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
283
284       -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
289
290       -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
298
299       -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
304
305
306eyesep = 2 * far
307
308depth = 2 * (far - near) /
309                    (2 * far - near)
310
311
312              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
319              This option was new in Netpbm 10.59 (June 2012).
320
321
322
323       -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
328              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
332              This  is irrelevant if you use a pattern file (-patfile option),
333              because there is no random element to pamstereogram's behavior.
334
335              This option was new in Netpbm 10.32 (February 2006).
336
337
338       -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
344              This option was new in Netpbm 10.91 (June 2020).
345
346
347
348
349

PARAMETERS

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
355       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
359

NOTES

361   Input Images
362       pamstereogram  pays  no attention to the image's tuple type and ignores
363       all planes other than plane 0.
364
365       Like any Netpbm program, pamstereogram will accept PNM input as  if  it
366       were the PAM equivalent.
367
368
369   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
375       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
380       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
390       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
395       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
399
400
401   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
406       With the default values for -dpi and -eyesep, pattern images  that  are
407       128 pixels wide can tile seamlessly.
408
409
410

EXAMPLES

412       Generate  a SIRDS out of small, brightly colored squares and prepare it
413       for display on an 87 DPI monitor:
414
415           pamstereogram depthmap.pam \
416               -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \
417               >3d.pam
418
419
420       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
424           pamstereogram depthmap.pam -patfile mypattern.ppm >3d.pam
425
426
427       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
431           pamstereogram depthmap.pam \
432               -texfile colormap.pam -smoothing 2 -eyesep 3.5 \
433               >3d.pam
434
435
436
437

SEE ALSO

439
440
441              pam(1)
442
443
444
445
446              pamsistoaglyph(1)
447
448
449
450
451              ppm3d(1)
452
453
454       •      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
459
460       •      W.    A.   Steer.    Stereograms:   Technical   Details.    URL:
461              http://www.techmind.org/stereo/stech.html(1).
462
463
464
465

HISTORY

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
471       A backward incompatible change to  the  way  you  request  guide  boxes
472       (-guidetop, -guidebottom, -guidesize happened in Netpbm 10.61 (December
473       2012).
474
475
476

AUTHOR

478       Copyright © 2006-2020 Scott Pakin, scott+pbm@pakin.org.
479
480

Table Of Contents

482
483
484              SYNOPSIS ⟨#synopsis⟩
485
486
487
488              DESCRIPTION ⟨#description⟩
489
490
491
492              OPTIONS ⟨#options⟩
493
494
495
496              PARAMETERS ⟨#parameters⟩
497
498
499
500              NOTES ⟨#notes⟩
501
502
503
504
505              Input Images ⟨#inputimages⟩
506
507
508
509              Mapped-texture Stereograms ⟨#mappedtexture⟩
510
511
512
513              Miscellaneous ⟨#notes_misc⟩
514
515
516
517
518              EXAMPLES ⟨#examples⟩
519
520
521
522              SEE ALSO ⟨#seealso⟩
523
524
525
526              HISTORY ⟨#history⟩
527
528
529
530              AUTHOR ⟨#author⟩
531

DOCUMENT SOURCE

533       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
534       source.  The master documentation is at
535
536              http://netpbm.sourceforge.net/doc/pamstereogram.html
537
538netpbm documentation            2 January 2021    Pamstereogram User Manual(0)
Impressum