.\" I converted this manually from the html I found on the web
.\" dated 1997.08.08 -Bryan
.TH ppmshadow 1 "12 March 2000"
.IX ppmshadow
.SH NAME
ppmshadow - add simulated shadows to a portable pixmap image
.SH SYNOPSIS
.B ppmshadow
.RB [ \-b
.IR blur_size ]
.RB [ \-k ]
.RB [ \-t ]
.RB [ \-x
.IR xoffset ]
.RB [ \-y
.IR yoffset ]
.RB [ \-u ]
.RI [ pnmfile ]
.IX shadow
.SH DESCRIPTION
.B 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.
.SH OPTIONS
.TP
.BI \-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.
.I blur_size
defaults to 11 pixels.
.TP
.B \-k
Keep the intermediate temporary image files. When debugging, these
intermediate files provide many clues as to the source of an error.
See
.B FILES
below for a list of the contents of each file.
.TP
.B \-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.
.TP
.B \-u
Print command syntax and a summary of options.
.TP
.BI \-x " xoffset"
Specifies the displacement of the light source to the left of the
image. Larger settings of
.B 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
.I blur_size
(above), to the left.
.TP
.BI \-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
.BR \-y ,
the vertical offset defaults to the same as the horizontal offset (above),
upward.
.SH FILES
Input is an anymap named by the
.I pnmfile
command line argument; if you don't specify
.IR pnmfile ,
the input is the Standard Input file.
.PP
Output is a always a PPM file, written to Standard Output.
.PP
.B pnmfile
creates a number of temporary files as it executes. It creates them
in the /tmp directory, with names of the form:
.PP
.BI _PPMshadow pid - N .ppm
.PP
where
.I pid
is the process number of the
.B ppmshadow
process and
.I N
is a number identifying the file as described below. In normal
operation,
.B 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
.B \-k
command line option.
.PP
.I N
in the filename means:
.TP
.B 1
Positive binary mask
.TP
.B 2
Convolution kernel for blurring shadow
.TP
.B 3
Blurred shadow image
.TP
.B 4
Clipped shadow image, offset as requested
.TP
.B 5
Blank image with background of source image
.TP
.B 6
Offset shadow
.TP
.B 7
Inverse mask file
.TP
.B 8
Original image times inverse mask
.TP
.B 9
Generated shadow times positive mask
.TP
.B 10
Shadow times background colour
.SH 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
.B pnmmargin
before processing it with
.BR ppmshadow .
.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
.B ppmshadow
calls will, in general, provide little or no clue as to where
.B ppmshadow
went astray.
In this case,
Specify the
.B \-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
.B 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
.B \-k
option, modify them appropriately with an
image editor, then recombine them with the steps used by the code in
.BR ppmshadow .
See the
.B ppmshadow.doc
document for additional details and examples of the intermediate
files.
.PP
Shadows are by default black, as cast by opaque material in the image
occluding white light. Use the
.B \-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
.B \-t
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
.B pnmconvol
could use was 11 by 11,
.B 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
.B 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.
.PP
If you wish to generate an image at high resolution, then
scale it to publication size with
.B 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.
.SH EXIT STATUS
.B 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.
.SH SEE ALSO
.BR pnm (5),
.BR pnmmargin (1),
.BR pnmconvol (1),
.BR pnmscale (1),
.BR pnmsmooth (1),
.BR ppm (5)
.SH AUTHOR
John Walker August 8, 1997
.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.