SYNOPSIS
ppmshadow [-b blur_size] [-k] [-t] [-x xoffset] [-y yoffset] [ppmfile]



DESCRIPTION
This program is part of Netpbm.

ppmshadow 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.

ppmshadow sees your image as a foreground on a background. The back-
ground color is whatever color the top left pixel of your image is.
The background is all the pixels that are that color and the fore-
ground is everything else. The shadow that ppmshadow generates is a
shadow of the foreground, cast on the background.

The shadow is the same size as the foreground, plus some fringes as
determined by the -b option. It is truncated to fit in your image.
The output image is the same dimensions as the input image.

You can use pamcomp to place a foreground image over a background
before running ppmshadow on it. You can use ppmmake to make the back-
ground image (just an image of a solid color).


OPTIONS
-b blur_size




-k Keep the intermediate temporary image files. When debugging,


-t Consider the non-background material in the image translucent


-x xoffset


-y yoffset





FILES
Input is a PPM file named by the ppmfile command line argument; if you
don't specify ppmfile, the input is Standard Input.

The output is a PPM file, written to Standard Output.

ppmshadow creates a number of temporary files as it executes. It cre-
ates a new directory for them, /tmp/ppmshadowpid, where pid is the
process ID of the ppmshadow process. If the TMPDIR environment vari-
able is set, ppmshadow creates the directory there instead of /tmp.

In normal operation, ppmshadow 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 -k command line
option.

The temporary files are:



infile.ppm


bgmask.ppm


convkernel.ppm


blurred.ppm


blurred2.ppm


shadow.ppm


background.ppm


shadow.ppm


fgmask.ppm


justfg.ppm


shadback.ppm


allbutfg.ppm




LIMITATIONS
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 pnmmargin before pro-
cessing it with ppmshadow.

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.

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.

If something goes wrong along the way, the error messages from the
various Netpbm programs ppmshadow calls will, in general, provide lit-
tle or no clue as to where ppmshadow went astray. In this case, Spec-
ify the -k option and examine the intermediate results in the tempo-
rary files (which this option causes to be preserved). If you manu-
ally run the commands that ppmshadow runs on these files, you can fig-
ure out where the problem is. In problem cases where you want to man-
ually tweak the image generation process along the way, you can keep
the intermediate files with the -k option, modify them appropriately
with an image editor, then recombine them with the steps used by the
code in ppmshadow.

See the ppmshadow.doc file in the Netpbm source tree for additional
details and examples of the intermediate files and debugging
ppmshadow.

Shadows are by default black, as cast by opaque material in the image
occluding white light. Use the -t 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 -t option may yield unattractive results which resemble simple
blurring of the original image.

Because Netpbm used to have a maximum maxval of 255, which meant that
the largest convolution kernel pnmconvol could use was 11 by 11,
ppmshadow 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 pnmsmooth (which is itself a program
that calls pnmconvol 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.

If you wish to generate an image at high resolution, then scale it to
publication size with pamscale in order to eliminate jagged edges by
resampling, it's best to generate the shadow in the original high res-
olution 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 interme-
diate between the image and background obscuring the shadow.


EXIT STATUS
ppmshadow returns status 0 if processing was completed without errors,
and a nonzero Unix error code if an error prevented generation of out-
put. Some errors may result in the script aborting, usually display-
ing 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 pro-
gram succeeded.


SEE ALSO
pnm, pnmmargin, pnmconvol, pamscale, pnmsmooth, ppm



AUTHOR
John Walker http://www.fourmilab.ch August 8, 1997


COPYRIGHT
This software is in the public domain. Permission to use, copy, mod-
ify, and distribute this software and its documentation for any pur-
pose and without fee is hereby granted, without any conditions or
restrictions.



netpbm documentation 17 April 2005 Ppmshadow User Manual(0)