Debian Codegraph @

upstream/debian-unstable/man1/pamstereogram.1

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