diff options
Diffstat (limited to 'upstream/opensuse-leap-15-6/man1/pamstereogram.1')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man1/pamstereogram.1 | 598 |
1 files changed, 598 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man1/pamstereogram.1 b/upstream/opensuse-leap-15-6/man1/pamstereogram.1 new file mode 100644 index 00000000..42831484 --- /dev/null +++ b/upstream/opensuse-leap-15-6/man1/pamstereogram.1 @@ -0,0 +1,598 @@ +\ +.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. +.\" Do not hand-hack it! If you have bug fixes or improvements, please find +.\" the corresponding HTML page on the Netpbm website, generate a patch +.\" against that, and send it to the Netpbm maintainer. +.TH "Pamstereogram User Manual" 0 "19 June 2015" "netpbm documentation" +.PP + +.PP +.UR #contents +Table Of Contents +.UE +\& + + +.UN name +.SH NAME +.PP +pamstereogram - create a single-image stereogram from a PAM +depth map + +.UN synopsis +.SH SYNOPSIS +.PP +\fBpamstereogram\fP +[\fB-help\fP] +[\fB-verbose\fP] +[\fB-blackandwhite\fP | \fB-grayscale\fP | \fB-color\fP] +[\fB-maxval=\fP\fIvalue\fP] +[\fB-patfile=\fP\fIpamfile\fP] +[\fB-texfile=\fP\fIpamfile\fP] +[\fB-bgcolor=\fP\fIcolor\fP] +[\fB-smoothing=\fP\fIpixels\fP] +[\fB-xbegin=\fP\fIpixels\fP] +[\fB-xshift=\fP\fIpixels\fP] +[\fB-yshift=\fP\fIpixels\fP] +[\fB-magnifypat=\fP\fIscale\fP] +[\fB-guidetop\fP] +[\fB-guidebottom\fP] +[\fB-guidesize=\fP\fIpixels\fP] +[\fB-dpi=\fP\fIresolution\fP] +[\fB-crosseyed\fP] +[\fB-makemask\fP] +[\fB-eyesep=\fP\fIinches\fP] +[\fB-depth=\fP\fIfraction\fP] +[\fB-planes=\fP\fInear_pixels\fP,\fIfar_pixels\fP] +[\fB-randomseed=\fP\fIinteger\fP] +[\fIinfile\fP] + + + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBpamstereogram\fP 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 +\fBpamstereogram\fP program provides a wealth of control over how the +stereogram is generated, including the following: + + +.IP \(bu +black and white, grayscale, or color output + +.IP \(bu +single-image random-dot stereograms (SIRDS), single-image +stereograms (SIS) using a tiled image, or mapped-texture stereograms +(MTS) + +.IP \(bu +images targeting a given device resolution and eye separation + +.IP \(bu +optional guide boxes to assist in focusing + +.IP \(bu +the ability to trade off depth levels for easier viewing + +.IP \(bu +choice of wall-eyed or cross-eyed stereograms + + +.PP +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 \fBpamtopnm\fP 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. +.PP +To make a red/green type of stereogram (that you view with 3-D +glasses) instead, see \fBppm3d\fP. + + +.UN options +.SH OPTIONS +.PP +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. + + + +.TP +\fB-verbose\fP +Display messages about image sizes and formats and properties +of the stereogram being generated. + +.TP +\fB-blackandwhite\fP +Produce a single-image random-dot black-and-white stereogram. +This is the default. + +.TP +\fB-grayscale\fP +Produce a single-image random-dot grayscale stereogram. + +.TP +\fB-color\fP +Produce a single-image random-dot color stereogram. + +.TP +\fB-maxval=\fP\fIvalue\fP +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 +\fB-maxval\fP, \fBpamstereogram\fP uses the maxval of the input +image. This option has no effect with \fB-blackandwhite\fP. + +.TP +\fB-patfile=\fP\fIpamfile\fP +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 +\fB-patfile\fP option along with \fB-blackandwhite\fP, +\fB-grayscale\fP, \fB-color\fP, or \fB-maxval\fP. + +.TP +\fB-xbegin=\fP\fIpixels\fP +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 \fB-xshift\fP to align the horizontal start of the pattern with the +horizontal start of stereogram generation. \fB-xbegin\fP is meaningful only +in conjunction with \fB-patfile\fP, \fB-makemask\fP, or \fB-texfile\fP, +and \fBpamstereogram\fP actually ignores it with respect to \fB-texfile\fP +(but may not in a future version of \fBpamstereogram\fP). +.sp +The default is to begin in the center. +.sp +This option was new in Netpbm 10.71 (June 2015). + +.TP +\fB-texfile=\fP\fIpamfile\fP +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. +.sp +This option was new in Netpbm 10.53 (December 2010). + + +.TP +\fB-bgcolor=\fP\fIcolor\fP +Use \fIcolor\fP as the texture image's background color instead +of letting \fBpamstereogram\fP determine it automatically. Specify +the color as described for the +.UR libppm.html#colorname +argument of the ppm_parsecolor() library routine +.UE +\&. The \fB-bgcolor\fP option is meaningful only in conjunction +with \fB-texfile\fP. +.sp +This option was new in Netpbm 10.53 (December 2010). + + +.TP +\fB-smoothing=\fP\fIpixels\fP +When used without \fB-texfile\fP, attempt to eliminate artifacts +introduced by edges in the depth map if \fIpixels\fP is greater than zero. +.sp +When used with \fB-texfile\fP, horizontally blur non-background +colors into background pixels up to a distance of \fIpixels\fP pixels. +This helps smooth over distracting glitches introduced +by the stereogram's color constraints when producing a mapped-texture +stereogram. In this case, the \fB-smoothing\fP 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. +.sp +This option was new in Netpbm 10.53 (December 2010). Before +Netpbm 10.61 (December 2012), it has no effect without \fB-texfile\fP. + + +.TP +\fB-xshift=\fP\fIpixels\fP +Shift the pattern image (designated by \fB-patfile\fP) to the +right by \fIpixels\fP pixels (default: 0). + +This option is valid only along with \fB-patfile\fP. + +.TP +\fB-yshift\fP \fIpixels\fP +Shift the pattern image (designated by \fB-patfile\fP) +downwards by \fIpixels\fP pixels (default: 0). This option is +valid only along with \fB-patfile\fP. + +.TP +\fB-magnifypat=\fP\fIscale\fP +Magnify each pixel in the pattern file or each random dot by +integral scaling factor \fIscale\fP. Note that +\fBpamstereogram\fP applies the pattern magnification +\fIafter\fP pattern shifting (\fB-xshift\fP and +\fB-yshift\fP). + +.TP +\fB-guidebottom\fP +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. +.sp +This option was new in Netpbm 10.61 (December 2012). Before that, +the presence of \fB-guidesize\fP, with a positive value, has the same +effect. + + +.TP +\fB-guidetop\fP +Same as \fB-guidebottom\fP, except the guides go at the top of the image. +.sp +This option was new in Netpbm 10.61 (December 2012). Before that, +the presence of \fB-guidesize\fP, with a negative value, has the same +effect. + +.TP +\fB-guidesize=\fP\fIpixels\fP +The size (width and height) of each guide box. +.sp +This is valid only with \fB-guidetop\fP or \fB-guidebottom\fP. +.sp +Default is 20. +.sp +Before Netpbm 10.61 (December 2012), if you don't specify this option, +\fBpamstereogram\fP draws no guides. If you specify it with a positive +value, \fBpamstereogram\fP behaves as if you specified \fB-guidebottom\fP +too, and if you specify it with a negative value, it behaves as if you +specified \fB-guidetop\fP and specified \fBguidesize\fP with the absolute +value of that negative value. + +.TP +\fB-dpi=\fP\fIresolution\fP +Specify the resolution of the output device in dots per inch. +The default is 100 DPI, which represents a fairly crisp screen +resolution. +.sp +Before Netpbm 10.53 (December 2010), the default was 96 DPI. + + +.TP +\fB-crosseyed\fP +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 \fB-crosseyed\fP option enables such people to see the 3-D image as +intended. You can also specify the \fB-crosseyed\fP option if you prefer +using depth maps in which darker colors are closer to the eye and lighter +colors are farther from the eye. +.sp +Before Netpbm 10.53 (December 2010), \fBpamstereogram\fP used higher +(lighter) numbers for things closer to the eye \fIwithout\fP +\fB-crosseyed\fP and vice versa. + + +.TP +\fB-makemask\fP +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 +\fB-makemask\fP option can be used to help create more +sophisticated pattern files (to use with \fB-patfile\fP) Note that +\fB-makemask\fP ignores \fB-magnifypat\fP; it always produces +masks that assume a pattern magnification of 1. + +.TP +\fB-eyesep=\fP\fIinches\fP +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. + +.TP +\fB-depth=\fP\fIfraction\fP +Specify the output image's depth of field. That is, +\fIfraction\fP 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. + +.TP +\fB-planes=\fP\fInear_pixels\fP,\fIfar_pixels\fP +Explicitly specify the distance between repeated pixels in the near plane +and in the far plane. This is an alternative to +\fB-eyesep\fP and \fB-depth\fP. The following equalities hold: + + +.IP \(bu +\fIeyesep\fP = 2 * \fIfar\fP +.IP \(bu +\fIdepth\fP = 2 * (\fIfar\fP - \fInear\fP) / + (2 * \fIfar\fP - \fInear\fP) + +.sp +The number of distinct 3-D depths is \fIfar\fP +- \fInear\fP + 1. One might say that \fB-eyesep\fP +and \fB-depth\fP are a more human-friendly way to specify stereoscopic +parameters (distance between eyes and tradeoff between perceptibility +and depth) while \fB-planes\fP is a more computer-centric way (pixel +distances in the resulting stereogram). +.sp +This option was new in Netpbm 10.59 (June 2012). + + +.TP +\fB-randomseed=\fP\fIinteger\fP +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. +.sp +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 \fBpamstereogram\fP. +.sp +This is irrelevant if you use a pattern file (\fB-patfile\fP +option), because there is no random element to \fBpamstereogram\fP's +behavior. +.sp +This option was new in Netpbm 10.32 (February 2006). + + + + + +.UN parameters +.SH PARAMETERS +.PP +The only parameter, \fIinfile\fP, is the name of an input file +that is a depth map image. If you don't specify \fIinfile\fP, the +input is from standard input. +.PP +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. + +.UN notes +.SH NOTES + +.UN inputimages +.SS Input Images +.PP +\fBpamstereogram\fP pays no attention to the image's tuple type and +ignores all planes other than plane 0. +.PP +Like any Netpbm program, \fBpamstereogram\fP will accept PNM +input as if it were the PAM equivalent. + +.UN mappedtexture +.SS Mapped-texture Stereograms +.PP +In a \fImapped-texture stereogram\fP (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. +.PP +You create an MTS with \fBpamstereogram\fP by passing the filename +of a PAM "texture image" with a \fB-texfile\fP 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. +.PP +\fBpamstereogram\fP 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 \fIexact\fP matches with the +background color. +.PP +You should specify a larger-than-normal value for \fB-eyesep\fP +(and/or \fB-dpi\fP) 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. +.PP +An MTS can employ a background pattern (\fB-patfile\fP). In this +case, \fBpamstereogram\fP replaces background pixels with pattern pixels in +the final step of generating the image. + + +.UN notes_misc +.SS Miscellaneous +.PP +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). +.PP +With the default values for \fB-dpi\fP and \fB-eyesep\fP, pattern +images that are 128 pixels wide can tile seamlessly. + + +.UN examples +.SH EXAMPLES +.PP +Generate a SIRDS out of small, brightly colored squares and +prepare it for display on an 87 DPI monitor: + +.nf + pamstereogram depthmap.pam \e + -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \e + >3d.pam +.fi +.PP +Generate a SIS by tiling a PPM file (a prior run with +\fB-verbose\fP indicates how wide the pattern file should be for +seamless tiling, although any width is acceptable for producing +SISes): + +.nf + pamstereogram depthmap.pam -patfile mypattern.ppm >3d.pam +.fi +.PP +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: + +.nf + pamstereogram depthmap.pam \e + -texfile colormap.pam -smoothing 2 -eyesep 3.5 \e + >3d.pam +.fi + + +.UN seealso +.SH SEE ALSO + +.IP \(bu + +.BR "pam" (5)\c +\& + +.IP \(bu + +.BR "pamsistoaglyph" (1)\c +\& + +.IP \(bu + +.BR "ppm3d" (1)\c +\& + +.IP \(bu +Harold W. Thimbleby, Stuart Inglis, and Ian H. Witten. +\fIDisplaying 3D Images: Algorithms for Single Image Random Dot +Stereograms\fP. In IEEE Computer, \fB27\fP(10):38-48, +October 1994. DOI: +.UR http://dx.doi.org/10.1109/2.318576 +10.1109/2.318576 +.UE +\&. + +.IP \(bu +W. A. Steer. +\fIStereograms: Technical Details\fP. +URL: +.BR "http://www.techmind.org/stereo/stech.html" (1)\c +\&. + + + +.UN history +.SH HISTORY +.PP +\fBpamstereogram\fP 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). +.PP +A backward incompatible change to the way you request guide boxes +(\fB-guidetop\fP, \fB-guidebottom\fP, \fB-guidesize\fP happened in +Netpbm 10.61 (December 2012). + + +.UN author +.SH AUTHOR +.PP +Copyright \(co 2006-2015 Scott Pakin, \fIscott+pbm@pakin.org\fP. + +.UN contents +.SH Table Of Contents + +.IP \(bu + +.UR #synopsis +SYNOPSIS +.UE +\& +.IP \(bu + +.UR #description +DESCRIPTION +.UE +\& +.IP \(bu + +.UR #options +OPTIONS +.UE +\& +.IP \(bu + +.UR #parameters +PARAMETERS +.UE +\& +.IP \(bu + +.UR #notes +NOTES +.UE +\& + +.IP \(bu + +.UR #inputimages +Input Images +.UE +\& +.IP \(bu + +.UR #mappedtexture +Mapped-texture Stereograms +.UE +\& +.IP \(bu + +.UR #notes_misc +Miscellaneous +.UE +\& + + +.IP \(bu + +.UR #examples +EXAMPLES +.UE +\& +.IP \(bu + +.UR #seealso +SEE ALSO +.UE +\& +.IP \(bu + +.UR #history +HISTORY +.UE +\& +.IP \(bu + +.UR #author +AUTHOR +.UE +\& +.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/pamstereogram.html +.PP
\ No newline at end of file |