1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.3//EN">
<html><head><title>Pamstereogram User Manual</title></head>
<body>
<h1>pamstereogram</h1>
<p>Updated: 2 January 2021
<p><a href="#index">Table Of Contents</a>
<h2>NAME</h2>
pamstereogram - create a single-image stereogram from a PAM depth map
<h2 id="synopsis">SYNOPSIS</h2>
<p>
<b>pamstereogram</b>
[<b>-help</b>]
[<b>-verbose</b>]
[<b>-blackandwhite</b> | <b>-grayscale</b> | <b>-color</b>]
[<b>-maxval=</b><i>value</i>]
[<b>-patfile=</b><i>pamfile</i>]
[<b>-texfile=</b><i>pamfile</i>]
[<b>-bgcolor=</b><i>color</i>]
[<b>-smoothing=</b><i>pixels</i>]
[<b>-xbegin=</b><i>pixels</i>]
[<b>-xshift=</b><i>pixels</i>]
[<b>-yshift=</b><i>pixels</i>]
[<b>-yfillshift</b> <i>pixels</i>]
[<b>-magnifypat=</b><i>scale</i>]
[<b>-guidetop</b>]
[<b>-guidebottom</b>]
[<b>-guidesize=</b><i>pixels</i>]
[<b>-dpi=</b><i>resolution</i>]
[<b>-crosseyed</b>]
[<b>-makemask</b>]
[<b>-eyesep=</b><i>inches</i>]
[<b>-depth=</b><i>fraction</i>]
[<b>-planes=</b><i>near_pixels</i>,<i>far_pixels</i>]
[<b>-randomseed=</b><i>integer</i>]
[<b>-tileable</b>]
[<i>infile</i>]
<h2 id="description">DESCRIPTION</h2>
<p>This program is part of <a href="index.html">Netpbm</a>.
<p><b>pamstereogram</b> inputs a depth map (a map of the distances
from your eye of the points in a scene) and outputs a single-image
stereogram (SIS). A SIS is a 2-D image specially designed to appear
three dimensional when viewed with relaxed, slightly unfocused
eyes. What's exciting about single-image stereograms is that they
don't require special glasses to view, although it does require a bit
of practice to train your eyes to unfocus properly. The
<b>pamstereogram</b> program provides a wealth of control over how the
stereogram is generated, including the following:
<ul>
<li>black and white, grayscale, or color output
<li>single-image random-dot stereograms (SIRDS), single-image
stereograms (SIS) using a tiled image, or mapped-texture stereograms
(MTS)
<li>images targeting a given device resolution and eye separation
<li>optional guide boxes to assist in focusing
<li>the ability to trade off depth levels for easier viewing
<li>choice of wall-eyed or cross-eyed stereograms
</ul>
<p>The output is a PAM image on standard output. Options control
the exact format of the PAM. If you want a PNM (PBM, PGM, or PPM)
image, use <b>pamtopnm</b> on the output. There is no need to convert
if you will use the image as input to a current Netpbm program, but
many other programs don't know what a PAM is.
<p>To make a red/cyan type of stereogram (that you view with 3-D
glasses) instead, see <b>ppm3d</b>.
<h2 id="options">OPTIONS</h2>
<p>You may use either single or double hyphens to denote options. You
may use either whitespace or an equals sign to separate an option name
from its value.
<p>In addition to the options common to all programs based on libnetpbm
(most notably <b>-quiet</b>, see <a href="index.html#commonoptions">
Common Options</a>), <b>pamstereogram</b> recognizes the following
command line options:
<dl>
<dt><b>-verbose</b>
<dd>Display messages about image sizes and formats and properties
of the stereogram being generated.
<dt><b>-blackandwhite</b>
<dd>Produce a single-image random-dot black-and-white stereogram.
This is the default.
<dt><b>-grayscale</b>
<dd>Produce a single-image random-dot grayscale stereogram.
<dt><b>-color</b>
<dd>Produce a single-image random-dot color stereogram.
<dt><b>-maxval=</b><i>value</i>
<dd>Designate the maximum value of each gray/color component, i.e.
the color resolution. Smaller values make the output image have
smaller numbers of unique grays/colors. If you don't specify
<b>-maxval</b>, <b>pamstereogram</b> uses the maxval of the input
image. This option has no effect with <b>-blackandwhite</b>.
<dt><b>-patfile=</b><i>pamfile</i>
<dd>Specify an image to use as a repeated background pattern for
the stereogram instead of a random-dot pattern. Intricate images
generally produce a crisper 3-D effect that simpler images. The
output file will have the same maxval and format (black and white,
grayscale or color) as the pattern file. You cannot specify the
<b>-patfile</b> option along with <b>-blackandwhite</b>,
<b>-grayscale</b>, <b>-color</b>, or <b>-maxval</b>. The
<b>-verbose</b> option will give you information on the ideal
dimensions of the pattern file.
<dt><b>-xbegin=</b><i>pixels</i>
<dd>Specify the horizontal coordinate at which to begin stereogram generation.
The background pattern will be minimally distorted at this point and more
distorted at greater distances. Consider using this in conjunction
with <b>-xshift</b> to align the horizontal start of the pattern with the
horizontal start of stereogram generation. <b>-xbegin</b> is meaningful only
in conjunction with <b>-patfile</b>, <b>-makemask</b>, or <b>-texfile</b>,
and <b>pamstereogram</b> actually ignores it with respect to <b>-texfile</b>
(but may not in a future version of <b>pamstereogram</b>).
<p>The default is to begin in the center.
<p>This option was new in Netpbm 10.71 (June 2015).
<dt><b>-texfile=</b><i>pamfile</i>
<dd>Specify an image to use as the texture for a mapped-texture
stereogram. The idea is that the depth-map image provides the depth
values of the 3-D object/scene while the texture image provides the
true-color values. Consequently, the texture image should align with
the depth-map image. (Note that it's required to have the same
dimensions.) The texture image's background color is ignored when
blending colors.
<p>This option was new in Netpbm 10.53 (December 2010).
<dt><b>-bgcolor=</b><i>color</i>
<dd>Use <i>color</i> as the texture image's background color instead
of letting <b>pamstereogram</b> determine it automatically. Specify
the color as described for the
<a href="libnetpbm_image.html#colorname">argument of the pnm_parsecolor() library
routine</a>. The <b>-bgcolor</b> option is meaningful only in conjunction
with <b>-texfile</b>.
<p>This option was new in Netpbm 10.53 (December 2010).
<dt><b>-smoothing=</b><i>pixels</i>
<dd>When used without <b>-texfile</b>, attempt to eliminate artifacts
introduced by edges in the depth map if <i>pixels</i> is greater than zero.
<p>When used with <b>-texfile</b>, horizontally blur non-background
colors into background pixels up to a distance of <i>pixels</i> pixels.
This helps smooth over distracting glitches introduced
by the stereogram's color constraints when producing a mapped-texture
stereogram. In this case, the <b>-smoothing</b> option is helpful
when the texture image includes smooth color transitions (as in a
photograph) but makes crisp texture images (as in a line drawing)
appear blurry.
<p>This option was new in Netpbm 10.53 (December 2010). Before
Netpbm 10.61 (December 2012), it has no effect without <b>-texfile</b>.
<dt><b>-xshift=</b><i>pixels</i>
<dd>Shift the pattern image (designated by <b>-patfile</b>) to the
right by <i>pixels</i> pixels (default: 0).
<p>
This option is valid only along with <b>-patfile</b>.
<dt><b>-yshift</b> <i>pixels</i>
<dd>Shift the pattern image (designated by <b>-patfile</b>)
downwards by <i>pixels</i> pixels (default: 0). This option is
valid only along with <b>-patfile</b>.
<dt><b>-yfillshift</b> <i>pixels</i></dt>
<dd>Shift the pattern image (designated by <b>-patfile</b>) downwards
by <i>pixels</i> pixels (default: 0) but only after the initial
population of the pattern. (If used with <b>-yshift</b> the resulting
shifts are summed.) A small <b>-yfillshift</b> helps reduce visual
artifacts in the 3-D image. Steer's website, referenced under
<a href="#seealso">SEE ALSO</a>, recommends a shift of approximately
1/16" (6-7 pixels at <b>pamstereogram</b>'s default of 100 DPI).
<p>This option was new in Netpbm 10.94 (March 2021).
<dt><b>-magnifypat=</b><i>scale</i>
<dd>Magnify each pixel in the pattern file or each random dot by
integral scaling factor <i>scale</i>. Note that
<b>pamstereogram</b> applies the pattern magnification
<em>after</em> pattern shifting (<b>-xshift</b> and
<b>-yshift</b>).
<dt><b>-guidebottom</b>
<dd>
Draw a pair of black squares on a white background underneath the stereogram
proper. These squares help you guide your eyes into proper focus to view the
3-D image. The trick is to focus your eyes some distance behind the image,
causing you to see four black squares, then continue altering your focus
distance until the middle two black squares fuse into a single black
square. At that point, a crisp, 3-D image will appear.
<p>This option was new in Netpbm 10.61 (December 2012). Before that,
the presence of <b>-guidesize</b>, with a positive value, has the same
effect.
<dt><b>-guidetop</b>
<dd>
Same as <b>-guidebottom</b>, except the guides go at the top of the image.
<p>This option was new in Netpbm 10.61 (December 2012). Before that,
the presence of <b>-guidesize</b>, with a negative value, has the same
effect.
<dt><b>-guidesize=</b><i>pixels</i>
<dd>The size (width and height) of each guide box.
<p>This is valid only with <b>-guidetop</b> or <b>-guidebottom</b>.
<p>Default is 20.
<p>Before Netpbm 10.61 (December 2012), if you don't specify this option,
<b>pamstereogram</b> draws no guides. If you specify it with a positive
value, <b>pamstereogram</b> behaves as if you specified <b>-guidebottom</b>
too, and if you specify it with a negative value, it behaves as if you
specified <b>-guidetop</b> and specified <b>guidesize</b> with the absolute
value of that negative value.
<dt><b>-dpi=</b><i>resolution</i>
<dd>Specify the resolution of the output device in dots per inch.
The default is 100 DPI, which represents a fairly crisp screen
resolution.
<p>Before Netpbm 10.53 (December 2010), the default was 96 DPI.
<dt><b>-crosseyed</b>
<dd>Invert the gray levels in the depth map (input image) so that the 3-D
image pops out of the page where it would otherwise sink into the page and
vice versa. Some people are unable to diverge their eyes and can only cross
them. The <b>-crosseyed</b> option enables such people to see the 3-D image as
intended. You can also specify the <b>-crosseyed</b> option if you prefer
using depth maps in which darker colors are closer to the eye and lighter
colors are farther from the eye.
<p>Before Netpbm 10.53 (December 2010), <b>pamstereogram</b> used higher
(lighter) numbers for things closer to the eye <em>without</em>
<b>-crosseyed</b> and vice versa.
<dt><b>-makemask</b>
<dd>Instead of a stereogram, output a PAM mask image showing
coloring constraints. New pixels will be taken from the pattern
file where the mask is black. Copies of existing pixels will be
taken from the pattern file where the mask is white. The
<b>-makemask</b> option can be used to help create more
sophisticated pattern files (to use with <b>-patfile</b>) Note that
<b>-makemask</b> ignores <b>-magnifypat</b>; it always produces
masks that assume a pattern magnification of 1.
<dt><b>-eyesep=</b><i>inches</i>
<dd>Specify the separation in inches between your eyes. The
default, 2.5 inches (6.4 cm), should be sufficient for most people
and probably doesn't need to be changed.
<dt><b>-depth=</b><i>fraction</i>
<dd>Specify the output image's depth of field. That is,
<i>fraction</i> represents the fractional distance of the near
plane from the far plane. Smaller numbers make the 3-D image easier
to perceive but flatter. Larger numbers make the 3-D image more
difficult to perceive but deeper. The default, 0.3333, generally
works fairly well.
<dt><b>-planes=</b><i>near_pixels</i>,<i>far_pixels</i>
<dd>Explicitly specify the distance between repeated pixels in the near plane
and in the far plane. This is an alternative to
<b>-eyesep</b> and <b>-depth</b>. The following equalities hold:
<ul>
<li><i>eyesep</i> = 2 * <i>far</i>
<li><i>depth</i> = 2 * (<i>far</i> − <i>near</i>) /
(2 * <i>far</i> − <i>near</i>)
</ul>
<p>The number of distinct 3-D depths is <i>far</i>
− <i>near</i> + 1. One might say that <b>-eyesep</b>
and <b>-depth</b> are a more human-friendly way to specify stereoscopic
parameters (distance between eyes and tradeoff between perceptibility
and depth) while <b>-planes</b> is a more computer-centric way (pixel
distances in the resulting stereogram).
<p>This option was new in Netpbm 10.59 (June 2012).
<dt><b>-randomseed=</b><i>integer</i>
<dd>Specify a seed to be used for the random number generator.
The default is to use a seed based on the time of day, to one second
granularity.
<p>It is useful to specify the seed if you want to create reproducible
results. With the same random seed, you should get identical results
every time you run <b>pamstereogram</b>.
<p>This is irrelevant if you use a pattern file (<b>-patfile</b>
option), because there is no random element to <b>pamstereogram</b>'s
behavior.
<p>This option was new in Netpbm 10.32 (February 2006).
<dt><b>-tileable</b>
<dd>Make the generated image horizontally tileable. This works by
blending a left-to-right rendering (the equivalent
of <b>-xbegin</b>=0) with a right-to-left rendering (the equivalent
of <b>-xbegin</b>=<i>width−1</i>).
<p>This option was new in Netpbm 10.91 (June 2020).
</dl>
<h2 id="parameters">PARAMETERS</h2>
<p>The only parameter, <i>infile</i>, is the name of an input file
that is a depth map image. If you don't specify <i>infile</i>, the
input is from standard input.
<p>The input is a PAM image of depth 1. Each sample represents the
distance from the eye that the 3-D image at that location should
be. Lower (darker) numbers mean further from the eye.
<h2 id="notes">NOTES</h2>
<h3 id="inputimages">Input Images</h3>
<p><b>pamstereogram</b> pays no attention to the image's tuple type and
ignores all planes other than plane 0.
<p>Like any Netpbm program, <b>pamstereogram</b> will accept PNM
input as if it were the PAM equivalent.
<h3 id="mappedtexture">Mapped-texture Stereograms</h3>
<p>In a <i>mapped-texture stereogram</i> (MTS), the 3-D image can be
drawn with true colors. Unlike a SIRDS or tiled-image SIS, however,
the image portrayed by an MTS is apparent in normal 2-D viewing. It
appears repeated multiple times and overlapped with itself, but it is
not hidden.
<p>You create an MTS with <b>pamstereogram</b> by passing the filename
of a PAM "texture image" with a <b>-texfile</b> option. A
texture image portrays the same 3-D object as the depth-map image but
indicates the colors that the program should apply to the object.
<p><b>pamstereogram</b> ignores the texture image's background color when it
overlaps copies of the 3-D object. This prevents, for example, a bright-red
object on a black background from being drawn as a dark-red object (a blend of
50% bright red and 50% black); instead, the program ignores the black and the
object remains bright red. A consequence of this feature is that an MTS looks
best when the objects in the texture image have a crisp outline. Smooth
transitions to the background color result in unwanted color artifacts around
edges because the program ignores only <em>exact</em> matches with the
background color.
<p>You should specify a larger-than-normal value for <b>-eyesep</b>
(and/or <b>-dpi</b>) when producing an MTS. Otherwise, the 3-D object will
repeat so many times that most colored pixels will overlap other colored
pixels, reducing the number of true-colored pixels that remain.
<p>An MTS can employ a background pattern (<b>-patfile</b>). In this
case, <b>pamstereogram</b> replaces background pixels with pattern pixels in
the final step of generating the image.
<h3 id="notes_misc">Miscellaneous</h3>
<p>A good initial test is to input an image consisting of a solid
shape of distance 0 within a large field of maximum distance (e.g., a
white square on a black background).
<p>With the default values for <b>-dpi</b> and <b>-eyesep</b>, pattern
images that are 128 pixels wide can tile seamlessly.
<h2 id="examples">EXAMPLES</h2>
<p>Generate a SIRDS out of small, brightly colored squares and
prepare it for display on an 87 DPI monitor:
<pre>
pamstereogram depthmap.pam \
-dpi 87 -verbose -color -maxval 1 -magnifypat 3 \
>3d.pam
</pre>
<p>Generate a SIS by tiling a PPM file (a prior run with
<b>-verbose</b> indicates how wide the pattern file should be for
seamless tiling, although any width is acceptable for producing
SISes):
<pre>
pamstereogram depthmap.pam -patfile mypattern.ppm >3d.pam
</pre>
<p>Generate an MTS by associating colors with a depth-mapped object
(using a large eye separation to reduce the number of repetitions of
the texture image) and twice smoothing over background-colored
speckles:
<pre>
pamstereogram depthmap.pam \
-texfile colormap.pam -smoothing 2 -eyesep 3.5 \
>3d.pam
</pre>
<h2 id="seealso">SEE ALSO</h2>
<ul>
<li><a href="pam.html">pam</a>
<li><a href="pamsistoaglyph.html">pamsistoaglyph</a>
<li><a href="ppm3d.html">ppm3d</a>
<li>Harold W. Thimbleby, Stuart Inglis, and Ian H. Witten.
<em>Displaying 3D Images: Algorithms for Single Image Random Dot
Stereograms</em>. In IEEE Computer, <strong>27</strong>(10):38-48,
October 1994. DOI: <a
href="http://dx.doi.org/10.1109/2.318576">10.1109/2.318576</a>.
<li>W. A. Steer.
<em>Stereograms: Technical Details</em>.
URL: <a href="http://www.techmind.org/stereo/stech.html">http://www.techmind.org/stereo/stech.html</a>.
</ul>
<h2 id="history">HISTORY</h2>
<p><b>pamstereogram</b> was new in Netpbm 10.22 (April 2004), but probably
broken beyond usability until Netpbm 10.32 (February 2006) and Netpbm 10.26.23
(January 2006).
<p>A backward incompatible change to the way you request guide boxes
(<b>-guidetop</b>, <b>-guidebottom</b>, <b>-guidesize</b> happened in
Netpbm 10.61 (December 2012).
<h2 id="author">AUTHOR</h2>
<p>Copyright © 2006-2020 Scott Pakin, <a href="mailto:scott+pbm@pakin.org">scott+pbm@pakin.org</a>.
<h2 id="index">Table Of Contents</h2>
<ul>
<li><a href="#synopsis">SYNOPSIS</a>
<li><a href="#description">DESCRIPTION</a>
<li><a href="#options">OPTIONS</a>
<li><a href="#parameters">PARAMETERS</a>
<li><a href="#notes">NOTES</a>
<ul>
<li><a href="#inputimages">Input Images</a>
<li><a href="#mappedtexture">Mapped-texture Stereograms</a>
<li><a href="#notes_misc">Miscellaneous</a>
</ul>
<li><a href="#examples">EXAMPLES</a>
<li><a href="#seealso">SEE ALSO</a>
<li><a href="#history">HISTORY</a>
<li><a href="#author">AUTHOR</a>
</ul>
</body>
</html>
|
