diff options
Diffstat (limited to 'upstream/opensuse-leap-15-6/man1/ppmshadow.1')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man1/ppmshadow.1 | 287 |
1 files changed, 287 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man1/ppmshadow.1 b/upstream/opensuse-leap-15-6/man1/ppmshadow.1 new file mode 100644 index 00000000..e7aa4ae9 --- /dev/null +++ b/upstream/opensuse-leap-15-6/man1/ppmshadow.1 @@ -0,0 +1,287 @@ +\ +.\" 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 "Ppmshadow User Manual" 0 "24 June 2017" "netpbm documentation" + +.UN name +.SH NAME +ppmshadow - add simulated shadows to a PPM image + +.UN synopsis +.SH SYNOPSIS + +\fBppmshadow\fP +[\fB-b\fP \fIblur_size\fP] +[\fB-k\fP] +[\fB-t\fP] +[\fB-x\fP \fIxoffset\fP] +[\fB-y\fP \fIyoffset\fP] +[\fIppmfile\fP] + + +.UN description +.SH DESCRIPTION +.PP +This program is part of +.BR "Netpbm" (1)\c +\&. +.PP +\fBppmshadow\fP adds a simulated shadow to an image, giving the +appearance that the contents of the image float above the page, +casting a diffuse shadow on the background. Shadows can either be +black, as cast by opaque objects, or translucent, where the shadow +takes on the color of the object which casts it. You can specify the +crispness of the shadow and its displacement from the image with command +line options. +.PP +\fBppmshadow\fP sees your image as a foreground on a background. +The background color is whatever color the top left pixel of your image is. +The background is all the pixels that are that color and the foreground +is everything else. The shadow that \fBppmshadow\fP generates is a +shadow of the foreground, cast on the background. +.PP +The shadow is the same size as the foreground, plus some fringes +as determined by the \fB-b\fP option. It is truncated to fit in your +image. The output image is the same dimensions as the input image. +.PP +You can use \fBpamcomp\fP to place a foreground image over a background +before running \fBppmshadow\fP on it. You can use \fBppmmake\fP to make +the background image (just an image of a solid color). +.PP +The output has the same dimensions and maxval as the input. +.PP +The blurring to make the fringes of the shadow will not have a desirable +effect if the color depth (maxval) of the image is too low -- you need a high +maxval to get all the shades needed to create a smooth gradient. So if your +input has low maxval (including most notably if the input is PBM, which means +its maxval is 1), run it through \fBpamdepth\fP to raise its maxval. 255 is +usually a good choice. +.PP +Input is a PPM file named by the \fIppmfile\fP command line argument; if +you don't specify \fIppmfile\fP, the input is Standard Input. +.PP +The output is a PPM file, written to Standard Output. + + +.UN options +.SH OPTIONS + + +.TP +\fB-b\fP \fIblur_size\fP +Sets the distance of the light source from the image. Larger values +move the light source closer, casting a more diffuse shadow, while +smaller settings move the light further away, yielding a sharper +shadow. \fIblur_size\fP is the number of pixels of fringe there is +on the shadow, beyond where the shadow would be if there were no +blurring. +.sp +The default is 11 pixels. +.sp +Note that this option controls only the fringing effect of moving +the light source closer to the object. It does not make the shadow +grow or shrink as would happpen in the real world if you moved a point +light source closer to and further from an object. + +.TP +\fB-k\fP +Keep the intermediate temporary image files. When debugging, these +intermediate files provide many clues as to the source of an error. +See +.UR #files +below +.UE +\& for a list of the contents of each file. + +.TP +\fB-t\fP +Consider the non-background material in the image translucent -- it +casts shadows of its own color rather than a black shadow, which is +default. This often results in fuzzy, difficult-to-read images but in +some circumstances may look better. + +.TP +\fB-x\fP\fI xoffset\fP +Specifies the displacement of the light source to the left of the +image. Larger settings of \fBxoffset\fP displace the shadow to the +right, as would be cast by a light further to the left. If not +specified, the horizontal offset is half of \fIblur_size \fP (above), +to the left. + +.TP +\fB-y\fP\fI yoffset\fP + Specifies the displacement of the light source above the top of +the image. Larger settings displace the shadow downward, +corresponding to moving the light further above the top of the image. +If you don't specify \fB-y\fP, the vertical offset defaults to the +same as the horizontal offset (above), upward. + + + + +.UN limitations +.SH LIMITATIONS +.PP +The source image must contain sufficient space on the edges in the +direction in which the shadow is cast to contain the shadow -- if it +doesn't some of the internal steps may fail. You can usually expand +the border of a too-tightly-cropped image with \fBpnmmargin\fP before +processing it with \fBppmshadow\fP. +.PP +Black pixels and pixels with the same color as the image +background don't cast a shadow. If this causes unintentional +"holes" in the shadow, fill the offending areas with a color +which differs from black or the background by RGB values of 1, which +will be imperceptible to the viewer. Since the comparison is exact, +the modified areas will now cast shadows. +.PP +The background color of the source image (which is preserved in +the output) is deemed to be the color of the pixel at the top left of +the input image. If that pixel isn't part of the background, simply +add a one-pixel border at the top of the image, generate the shadow +image, then delete the border from it. +.PP +If something goes wrong along the way, the error messages from the +various Netpbm programs \fBppmshadow\fP calls will, in general, +provide little or no clue as to where \fBppmshadow\fP went astray. +In this case, Specify the \fB-k\fP option and examine the +intermediate results in the temporary files (which this option causes +to be preserved). If you manually run the commands that +\fBppmshadow\fP runs on these files, you can figure out where the +problem is. In problem cases where you want to manually tweak the +image generation process along the way, you can keep the intermediate +files with the \fB-k \fP option, modify them appropriately with an +image editor, then recombine them with the steps used by the code in +\fBppmshadow\fP. +.PP +Shadows are by default black, as cast by opaque material in the +image occluding white light. Use the \fB-t\fP option to simulate +translucent material, where the shadow takes on the color of the +object that casts it. If the contrast between the image and +background is insufficient, the \fB-t\fP option may yield +unattractive results which resemble simple blurring of the original +image. +.PP +Because Netpbm used to have a maximum maxval of 255, which meant +that the largest convolution kernel \fBpnmconvol\fP could use was 11 +by 11, \fBppmshadow\fP includes a horrid, CPU-time-burning kludge +which, if a blur of greater than 11 is requested, performs an initial +convolution with an 11 x 11 kernel, then calls \fBpnmsmooth\fP +(which is itself a program that calls \fBpnmconvol\fP with a 3 x 3 +kernel) as many times as the requested blur exceeds 11. It's ugly, +but it gets the job done on those rare occasions where you need a blur +greater than 11. +.PP +If you wish to generate an image at high resolution, then scale it +to publication size with \fBpamscale\fP in order to eliminate jagged +edges by resampling, it's best to generate the shadow in the original +high resolution image, prior to scaling it down in size. If you scale +first and then add the shadow, you'll get an unsightly jagged stripe +between the edge of material and its shadow, due to resampled pixels +intermediate between the image and background obscuring the shadow. + +.UN exitstatus +.SH EXIT STATUS + +\fBppmshadow\fP returns status 0 if processing was completed without +errors, and a nonzero Unix error code if an error prevented generation +of output. Some errors may result in the script aborting, usually +displaying error messages from various Netpbm components it uses, +without returning a nonzero error code. When this happens, the output +file will be empty, so be sure to test this if you need to know if the +program succeeded. + +.UN seealso +.SH SEE ALSO +.BR "pnm" (5)\c +\&, +.BR "pnmmargin" (1)\c +\&, +.BR "pnmconvol" (1)\c +\&, +.BR "pamscale" (1)\c +\&, +.BR "pnmsmooth" (1)\c +\&, +.BR "ppm" (5)\c +\& + + +.UN tempfiles +.SH TEMPORARY FILES +.PP +\fBppmshadow\fP creates a number of temporary files as it executes. It +creates a new directory for them in the directory named by the +\fBTMPDIR\fP environment variable, defaulting to \fB/tmp\fP if it is not +set. +.PP +In normal operation, \fBppmshadow\fP finds a unique name for the +temporary directory and deletes each temporary file as +soon as it is done with it and leaves no debris around after it +completes. To preserve the intermediate files for debugging, use the +\fB-k\fP command line option. In that case, the directory name is +\fBppmshadow\fP\fIpid\fP, where \fIpid\fP is the process ID of +the \fBppmshadow\fP process, and the program fails if \fBppmshadow\fP cannot +create that directory because the name is already in use. +.PP +The temporary files are: + + +.TP +\fBinfile.ppm\fP +A copy of the input. + +.TP +\fBbackground.ppm\fP +Blank image with background of source image + +.TP +\fBbgmask.ppm\fP +Positive binary mask + +.TP +\fBconvkernel.ppm\fP +Convolution kernel for blurring shadow + +.TP +\fBblurredlackshad.ppm\fP +Blurred shadow image before coloring + +.TP +\fBblurred.ppm\fP +Blurred, colored shadow image + +.TP +\fBshadow.ppm\fP +Clipped shadow image, offset as requested + +.TP +\fBshadback.ppm\fP +Generated shadow times positive mask + + + +.UN author +.SH AUTHOR + +John Walker +.UR http://www.fourmilab.ch +http://www.fourmilab.ch +.UE +\& August +8, 1997 + +.UN copyright +.SH COPYRIGHT +This software is in the public domain. Permission to use, copy, +modify, and distribute this software and its documentation for any +purpose and without fee is hereby granted, without any conditions or +restrictions. +.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/ppmshadow.html +.PP
\ No newline at end of file |