NAME¶
ppmshadow - add simulated shadows to a portable pixmap image
SYNOPSIS¶
ppmshadow [
-b blur_size] [
-k] [
-t] [
-x
xoffset] [
-y yoffset] [
-u] [
pnmfile]
DESCRIPTION¶
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 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 settings
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 displace 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 argument; if you
don't specify
pnmfile, the input is the Standard Input file.
Output is a always a PPM file, written to Standard Output.
pnmfile creates a number of temporary files as it executes. 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 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 processing 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 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 manually 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 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 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 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×11 kernel, then calls
pnmsmooth (which is actually a script
that calls pnmconvol with a 3×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
pnmscale 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.
EXIT STATUS¶
ppmshadow 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 ALSO¶
pnm(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 documentation for any purpose and without fee
is hereby granted, without any conditions or restrictions.