ppmshadow(1)ppmshadow(1)NAMEppmshadow - add simulated shadows to a portable pixmap
image
SYNOPSISppmshadow [-b blur_size] [-k] [-t] [-x xoffset] [-y yoff_
set] [-u] [pnmfile]
DESCRIPTIONppmshadow 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 colour of the
object which casts it. You can specify the extent of the
shadow and its displacement from the image with command
line options.
OPTIONS-b blur_size
Sets the distance of the light source from the
image. Larger values move the light source closer,
casting a more diffuse shadow, while smaller set
tings move the light further away, yielding a
sharper shadow. blur_size defaults to 11 pixels.
-k Keep the intermediate temporary image files. When
debugging, these intermediate files provide many
clues as to the source of an error. See FILES
below for a list of the contents of each file.
-t Consider the non-background material in the image
translucent -- it casts shadows of its own colour
rather than a black shadow, which is default. This
often results in fuzzy, difficult-to-read images
but in some circumstances may look better.
-u Print command syntax and a summary of options.
-x xoffset
Specifies the displacement of the light source to
the left of the image. Larger settings of xoffset
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 blur_size (above),
to the left.
-y yoffset
Specifies the displacement of the light source
above the top of the image. Larger settings dis
place the shadow downward, corresponding to moving
the light further above the top of the image. If
you don't specify -y, the vertical offset defaults
to the same as the horizontal offset (above),
upward.
FILES
Input is an anymap named by the pnmfile command line argu
ment; if you don't specify pnmfile, the input is the Stan
dard Input file.
Output is a always a PPM file, written to Standard Output.
pnmfile creates a number of temporary files as it exe
cutes. It creates them in the /tmp directory, with names
of the form:
_PPMshadowpid-N.ppm
where pid is the process number of the ppmshadow process
and N is a number identifying the file as described below.
In normal operation, ppmshadow deletes temporary files as
soon as it is done with them and leaves no debris around
after it completes. To preserve the intermediate files
for debugging, use the -k command line option.
N in the filename means:
1 Positive binary mask
2 Convolution kernel for blurring shadow
3 Blurred shadow image
4 Clipped shadow image, offset as requested
5 Blank image with background of source image
6 Offset shadow
7 Inverse mask file
8 Original image times inverse mask
9 Generated shadow times positive mask
10 Shadow times background colour
LIMITATIONS
The source image must contain sufficient space on the
edges in the direction in which the shadow is cast to con
tain 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 processing
it with ppmshadow.
Black pixels and pixels with the same color as the image
background don't cast a shadow. If this causes uninten
tional "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 pre
served 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 bor
der 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 little or no clue as to where ppmshadow
went astray. In this case, Specify the -k option and
examine the intermediate results in the temporary files
(which this option causes to be preserved). If you manu
ally run the commands that ppmshadow runs on these files,
you can figure out where the problem is. In problem cases
where you want to manually tweak the image generation pro
cess 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 document for
additional details and examples of the intermediate files.
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 colour 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 sim
ple 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 1111
kernel, then calls pnmsmooth (which is actually a script
that calls pnmconvol with a 33 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 pnmscale in order to
eliminate jagged edges by resampling, it's best to gener
ate 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 resam
pled pixels intermediate between the image and background
obscuring the shadow.
EXIT STATUSppmshadow 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.
SEE ALSOpnm(5), pnmmargin(1), pnmconvol(1), pnmscale(1),
pnmsmooth(1), ppm(5)AUTHOR
John Walker <http://www.fourmilab.ch> August 8, 1997
COPYRIGHT
This software is in the public domain. Permission to use,
copy, modify, and distribute this software and its docu
mentation for any purpose and without fee is hereby
granted, without any conditions or restrictions.
12 March 2000 ppmshadow(1)
